# Should donto build its own agentic harness? — a faster, leaner alternative to opencode for the abundance firehose

**2026-06-05 · grounded in what we just learned scaling donto to BEAM-10M: the case for `donto-agent`, a minimal high-throughput agent runtime, when to build it, and when to keep opencode/codex.**

---

## 0. TL;DR

Heavy agent CLIs — **opencode, Codex, Claude Code** — are extraordinary for *complex, interactive, self-editing coding agents*. But they carry large **per-call overhead** (a ~10,000-token system prompt, CLI cold-start, sandbox/permission scaffolding, and — in our deployment — a `docker exec` per call). For donto's actual high-volume workloads — **extracting claims from hundreds of thousands of chunks, recall-reasoning, citing, alignment** — that overhead is the wall. We hit it today: **opencode-per-call could not do the 360K-chunk BEAM-10M extraction; a direct-API firehose could.** The recommendation: build **`donto-agent`** — a lean, in-process, provider-rotating ReAct loop assembled mostly from parts we already have (the multi-lane router, the MCP server, the citer, the queue+worker coordinators) — as the **fast path** for abundance-scale agentic work, while keeping opencode/Codex for the complex coding/self-edit agents (the Omega bot). The field agrees the harness is the lever: harness-only changes have moved a coding agent **rank 30 → top 5 with no model swap**, and minimal harnesses like **Pi** run a **sub-1,000-token** system prompt — a **~10× reduction** over opencode/Claude Code.

## 1. What today proved

donto's BEAM-10M push is the empirical case:

- **opencode's path** (the donto-memory worker + genealogy extractor): `OpenCodeAgent` does a `docker exec` into the Omega container, cold-starts the `opencode` CLI, ships files over a shared mount, and runs a ~10K-token agent prompt — **per call**. Fine for a few documents. For **360,899 chunks** it is structurally impossible (per-call overhead × 360K = months of pure scaffolding).
- **The direct-API path we built instead** (the extraction firehose): one HTTPS call to the model (GLM-4.7, thinking disabled) → parse claims → bulk-COPY. **~15 s/chunk — that's the model's generation time, with essentially zero harness overhead.** Concurrent workers off a queue; provider-swappable. This is what made BEAM-10M extraction even attempt-able.
- The **Codex reader/judge** in our benchmarks similarly pays CLI cold-start + per-call MCP-server spawn; we had to disable MCP per call (`mcp_servers={}`) and add retry-on-empty just to make 500–1000 calls reliable.

The lesson is not "harnesses are bad." It's that **the right harness depends on the workload**, and donto's dominant workload is *high-throughput structured LLM calls*, not *one long interactive coding session*.

## 2. What an agent harness actually is

The [harness-engineering](https://github.com/ai-boost/awesome-harness-engineering) field decomposes it into ~9 layers: **agent loop control · tool/function calling · MCP · structured output · context delivery · memory/state · permissions · observability · orchestration.** Two design poles have emerged:

| | Heavy (opencode · Codex · Claude Code) | Lightweight (Pi) |
|---|---|---|
| system prompt | ~10,000 tokens | **<1,000 tokens** (~10×) |
| tools | many, always loaded | 4 core (read/write/edit/bash) + **lazy skills** |
| loop | compound multi-model, 5-layer safety, planning docs | **minimal ReAct**: stream → if tool calls, run; else return |
| strength | reliability, safety, complex multi-step coding | speed, token-efficiency, hackability, transparency |
| cost | latency, context bloat, per-call init | no built-in memory/permissions/cross-session |

[Pi](https://lucumr.pocoo.org/2026/1/31/pi/) (Armin Ronacher + Mario Zechner) is the "harness rebellion": a tiny core + user-shaped extensions, betting that frontier models "already know how to reason and use tools" so the prompt should get out of the way. The data backs the lever: **up to 6× performance variation from harness design alone.**

## 3. Why donto should build its own — and why it's already half-built

**donto's workloads are not interactive coding.** They are:
1. **Extraction (the abundance firehose)** — emit free claims from every chunk, at 10⁵–10⁹ scale.
2. **Recall-reasoning** — read recalled memories → answer (the benchmark reader).
3. **Citing** — anchor each fact to its source span (the always-on citer).
4. **Alignment** — fold predicates/entities at query time.

Every one of these is a **bounded, structured, high-throughput LLM call** — exactly what a lean harness is for, and exactly where opencode's overhead hurts. And critically, **the lightweight harnesses' main weakness — no persistent memory — is the one thing donto already is.** `donto-agent` = a minimal loop **+ donto-memory as the memory layer + the MCP server as the tool layer.** That combination is something neither Pi (no memory) nor opencode (heavy, no bitemporal substrate) has.

We already built the pieces this week:

- **Provider abstraction / rotation** — the multi-lane router (`donto-extract/lanes`, codex-spark / GLM / Cerebras, declarative caps + auto-failover), plus today's working **direct backends** (the GLM extraction client, the AMB `codex` LLM backend with structured-JSON output + retry).
- **Tool layer** — the **donto-memory MCP server** (`donto_recall`/`search`/`memorize`), already callable by any agent.
- **Structured output** — JSON-schema'd extraction + the codex `generate(prompt, schema)→dict` backend.
- **Concurrency + durability** — the **embedding coordinator** and **extraction firehose**: queue + `FOR UPDATE SKIP LOCKED` + concurrent workers + bulk ingest + resumability. That *is* an orchestration layer.
- **Observability** — the admin.donto.org panels (live `/api/beam`, processes, fabric).
- **Citer** — evidence-anchoring as a pluggable post-stage.

`donto-agent` is mostly *assembly*, not greenfield.

## 4. Design sketch — `donto-agent`

A small in-process runtime (Rust core or Python, no `docker exec`, no CLI cold-start per call):

- **Minimal ReAct loop** (Pi-style): stream model → if tool calls, execute (independent ones in parallel) → else return. Sub-1K-token base prompt; **lazy skills** loaded on demand.
- **Provider lanes**: one interface over OpenAI-compatible / z.ai / Codex-CLI / Cerebras, with the existing **cap-aware rotation + backoff**. Swap model per task; rotate on cap/429.
- **Structured output** first-class (JSON-schema / Pydantic), since most donto tasks want typed claims, not prose.
- **MCP client** built in → `donto_recall`/`search`/`memorize` and any other MCP tool, with **donto-memory as the always-available memory** (the thing lightweight harnesses lack).
- **Coordinator mode**: queue + SKIP-LOCKED + concurrent workers + bulk ingest (already proven by the embed/extract firehoses) — the high-throughput batch path.
- **Observability**: every call/tool/lane/retry traced → admin.donto.org.
- **Optional sandbox** only when a task needs `bash`/file edits (the rare case); skip it for pure LLM calls.

The headline: **per-call overhead ≈ 0** (no docker exec, no CLI start, no 10K-token prompt, no per-call MCP spawn) → throughput bounded only by the model + provider caps. For the firehose, that's the difference between feasible and not.

## 5. When NOT to build it (honest scope)

Keep **opencode / Codex / Claude Code** for what they're best at: **complex, interactive, self-modifying coding agents** — the Omega bot's self-edit loop, multi-step repo surgery, sandboxed tool use with human-in-the-loop. Those need the heavy safety/planning layers. `donto-agent` is **not** a coding-agent replacement; it's the **abundance fast-path** for extraction/recall/citing/alignment at scale. Two harnesses, two jobs.

## 6. Build plan (assemble, don't greenfield)

1. **Extract the lane interface** from `donto-extract/lanes` into a standalone `donto-agent` core (provider call + rotation + backoff + structured output) — most of it exists.
2. **Add the minimal ReAct tool-loop + MCP client** (the donto-memory MCP is already a server; add a client).
3. **Generalize the coordinator** (the embed/extract firehoses) into the batch/throughput mode — queue + SKIP-LOCKED + concurrent workers + bulk ingest, target-agnostic.
4. **Wire observability** to admin.donto.org (the `/api/beam` pattern generalizes to `/api/agent`).
5. **Port the live workloads**: the donto-memory worker (extraction) and the genealogy extractor move off `OpenCodeAgent` onto `donto-agent` — same claims, no docker-exec tax. Measure the per-call overhead delta (expect ~10× on overhead, and feasibility at firehose scale).

## 7. Verdict

**Yes — build it, scoped.** Not to dethrone opencode, but because donto's defining workload is an *abundance firehose* of structured LLM calls, and the right tool for that is a minimal, in-process, provider-rotating loop with donto-memory as its memory and MCP as its tools — most of which we built this week to make BEAM-10M possible. The field's own evidence (harness = the lever; Pi's 10× leaner prompt; rank-30→top-5 from harness changes) says the upside is large. `donto-agent` turns the ad-hoc fast-paths we wrote under duress into a first-class runtime.

*Grounded in this session: the BEAM-10M extraction firehose (direct-API, ~15s/chunk, 360K chunks) vs opencode-per-call (infeasible); the multi-lane router; the donto-memory MCP server; the embed + extraction coordinators; admin.donto.org observability. Sources: lucumr.pocoo.org/2026/1/31/pi, github.com/ai-boost/awesome-harness-engineering, mariozechner.at Pi write-up, mindstudio agentic-coding-2026.*