How the harness works, point by point

The DAG executor is the harness’s fault‑boundary primitive. Work compiles into a directed acyclic graph of atomic leaves, and the executor enforces a strict lifecycle: every unit either fully succeeds with all postconditions asserted, or is discarded as if it never ran. Reliability is a function of the graph’s shape and this binary contract, not of the model running inside a leaf.

The failure mode

Without this atomic contract, multi‑step pipelines built on fallible models or services suffer from partial state corruption. A leaf that fails midway can leave half‑written outputs, which downstream leaves consume unknowingly, silently compounding errors. Race conditions arise when multiple leaves share dependencies without a clear done/not‑done signal, so the system cannot answer “is this input stable?”. Retry logic becomes ambiguous: if a leaf partially mutated state, re‑executing it risks double‑applying effects or propagating stale data. The conductor cannot distinguish between a clean failure and a leaf that never properly started, so every failure forces either a costly full‑graph rerun or a manual untangling of side effects. The harness leaks ambiguity into every retry, skip, or reroute decision, and reliability collapses into a tangle of per‑leaf defensive checks.

How it works

The executor enforces a strict status lifecycle for every leaf:

• pending – not yet evaluated for readiness.
• ready – all upstream dependencies are done or skipped; the leaf is eligible for dispatch.
• running – the leaf is executing on its assigned model or tool.
• done – execution completed and the leaf asserted its postconditions successfully.
• failed – execution completed but the postcondition assertion failed (or an exception occurred).
• paused / skipped – external control states (e.g., manual hold or conductor‑directed skip).

A leaf transitions from pending to ready only when every upstream leaf has reached a terminal state (done or skipped). There is no partial readiness, no best‑effort speculation. This topological gate ensures no leaf ever runs against an incomplete or unverified input.

When a leaf finishes its payload, the executor runs the leaf’s postcondition check—a set of invariants that must hold (e.g., output format valid, required fields present). If the assertion passes, the leaf moves to done. If it fails, the leaf is immediately discarded: its status becomes failed, its output is erased from the DAG’s context, and downstream leaves never see it. The failure is contained at the leaf boundary. The conductor can then decide to retry the leaf (re‑instantiate it with possibly different parameters), skip it (mark it skipped so dependents adapt), or reroute the workflow—all without ambiguity, because no partial state escaped the leaf.

The DAG executor never interprets leaf logic. It only enforces the lifecycle, the dependency topology, and the postcondition gate. It guarantees that every leaf that reaches done is fully verified, and every failed leaf leaves zero visible trace inside the graph.

Trade-offs & boundaries

• Postcondition cost. Every leaf must define and execute its own invariants. Cheap postconditions (type checks, schema validation) add low overhead, but heavyweight checks (e.g., re‑evaluating a model’s output) can become a bottleneck. The executor provides no optimization—leaf authors own that cost.
• No partial results or streaming. The binary contract forbids incremental output. Any partial work produced by a failing leaf is lost; the leaf is an all‑or‑nothing unit. Workloads that need progressive delivery must split into smaller leaves or use a different primitive.
• Side effects are not automatically rolled back. “Discarded as if it never ran” makes the leaf invisible to downstream consumers, but any pre‑committed external side effects (API calls, writes) remain. The contract relies on leaf authors to design leaves that are idempotent, delay irreversible effects until postcondition success, or manage compensation externally.
• Acyclic only. The DAG is strictly acyclic. Cyclic workflows must be handled outside the executor, typically by the conductor replanning a new graph each iteration.
• Degradation path. If postconditions are too weak (always pass), the executor degenerates into a simple scheduler and unverified outputs propagate, erasing the reliability guarantee. If postconditions are too strict, healthy outputs are rejected, causing excessive false‑negative failures. Tuning postcondition strictness is a continuous operational concern.
• Granularity is a design choice, not a runtime adjustment. Coarse leaves discard large amounts of work on failure; fine leaves increase graph overhead and scheduling complexity. The executor treats every leaf as atomic regardless.

When it earns its place

The DAG executor pays off in any multi‑step workflow where a single failure must not corrupt the entire pipeline:

• Model chaining with verification: Leaf A generates output; leaf B verifies it with a postcondition. If verification fails, only A is retried, with no contamination of downstream steps.
• Expensive, mixed‑model pipelines: A cheap fast model runs a leaf; a postcondition leaf checks consistency. Failure can trigger a rerun of only that leaf on a more capable model, saving cost.
• Parallel fan‑out with dependencies: The readiness rule guarantees downstream leaves see only stable, verified inputs from all upstream leaves, eliminating race conditions.
• Audit and debugging: Every leaf logs a binary success or failure with its postcondition result, giving a clean, atomically‑traced execution history.
• High‑reliability workflows: Financial calculations, compliance checks, or configuration generation where a half‑executed step would corrupt downstream state.

A leaf is either done or it never happened—the graph guarantees it.

Compare-and-swap (CAS) state is a per‑leaf atomic state machine — pending → claimed → completed — that guarantees exactly one worker can claim and complete a given leaf under any degree of concurrency. It turns on a single idea: only the worker whose compare‑and‑swap instruction succeeds can transition the state; all others see a mismatch and move on. The result is a lock‑free harness that transforms parallel leaf execution from a race condition into a deterministic claim.

The failure mode

Without CAS, every ready leaf in the DAG becomes a potential point of silent corruption. Two or more workers inspect the same leaf, both see pending, and both decide to execute. They duplicate the work — wasting compute — and then both write a completion marker. Downstream dependencies receive two transitions where they expect exactly one, breaking their invariants. If the leaf produces side effects (a file write, an API call, a database insert), those fire twice. The graph’s dependency resolution, built on single‑completion semantics, silently becomes nonsense. The brittleness scales with concurrency: more workers raise the probability of collision, and a single unguarded leaf can corrupt the entire plan. A global mutex could prevent this, but at the cost of serialising all leaf transitions and killing throughput. Without CAS, reliable parallel execution is impossible — the harness becomes a lottery, not a pipeline.

How it works

Each leaf carries an atomically accessible state word. The harness defines exactly three legal states and two guarded transitions:

• Claiming: A worker reads the leaf’s state (expecting pending) and attempts an atomic compare‑and‑swap to claimed. Only one worker’s CAS succeeds; the loser sees a mismatch — either claimed (another worker won) or completed (already finished). The losing worker does not block. It picks another leaf from the dispatch queue, or retries the same leaf only if the state remains pending (an edge case that quickly resolves).
• Completing: After executing the leaf’s task, the winning worker performs a second CAS from claimed to completed. This prevents duplicate completions: if a bug or a stale recovery attempt tries to complete the same leaf again, the CAS fails because the state is already completed. Only the first successful completion matters.
• Failure handling: If a worker crashes after the claiming CAS but before the completing CAS, the leaf stays claimed. CAS itself cannot time out or roll back that state — it is a pure atomic primitive. Recovery is delegated to the dispatch layer, which monitors leaf states and applies a timeout/retry policy (e.g., resetting the leaf to pending after a configurable deadline). This separation keeps the harness fast and minimal while higher‑level components handle liveness.

The CAS primitive is always on, invisible to the model, and enforced by the harness on every state transition. No global lock exists; workers never wait on each other.

Trade-offs & boundaries

CAS is a single‑state primitive. It does not coordinate multi‑leaf transactions — it cannot atomically claim leaf A and leaf B together, nor roll back a completed leaf. Those responsibilities belong to the conductor (plan‑level orchestration) and dispatch (topological ordering, recovery).

Stuck claimed leaves after a crash demand an external timeout; without it, progress halts. The dispatch layer’s retry policy must be tuned per workload to balance false‑positive resets against prolonged stalls. CAS also does not provide side‑effect idempotency: if a leaf writes to an external database and then the worker crashes before the completing CAS, the harness can retry the leaf after timeout, but it cannot undo the database write. The safety guarantee is state‑transition integrity, not external compensation.

Under extreme contention — many workers racing for the same leaf — CAS failures waste a few CPU cycles on retries. In practice, the dispatch layer distributes work over many ready leaves, keeping contention negligible. The cost of a successful CAS is a single hardware‑atomic instruction (a few cycles), dwarfed by model inference or I/O inside a leaf. If a workload consists solely of microsecond‑long tasks, that overhead might become measurable, but such use is atypical for an agent platform.

CAS does not prevent a leaf from producing a wrong result (model hallucination, buggy tool call). Verification — a separate component on the roadmap — addresses output correctness.

When it earns its place

CAS earns its weight whenever multiple workers execute leaves concurrently. This is the default for any throughput‑sensitive Xihe deployment. It shines when:

• Leaves are costly (seconds of model inference or I/O) and duplicate execution would waste both time and external quota.
• Leaves produce side effects that must not fire twice — e.g., rate‑limited API calls, database inserts, file writes.
• Workers are heterogeneous or unreliable (varying model latency, possible crashes). CAS keeps state transitions honest even as workers come and go.
• The DAG contains tens to thousands of leaves and the dispatch layer feeds many ready leaves simultaneously; a global lock would become a serialisation bottleneck.

In these situations, CAS transforms parallelism from a correctness hazard into a safe, predictable pipeline. If the system runs with a single worker, CAS adds a trivial overhead and never contends; the moment concurrency increases, it silently prevents corruption the developer never has to think about.

CAS turns concurrent leaf execution from a race into a predictable pipeline: one worker, one claim, one completion.

The harness materialises the shared context — system prompt plus task framing — once and locks it as a byte-stable prompt prefix. Every leaf in a DAG inherits that prefix through the provider’s prompt-cache mechanism, eliminating redundant token recomputation. The one idea it turns on is that parallel execution should not multiply the cost of a shared context; by caching that context, concurrency width becomes a function of provider rate limits, not token budgets.

The failure mode

Without a frozen prefix, every leaf in a wide DAG independently transmits and processes the identical system prompt and task framing. That redundancy is not merely wasteful — it compounds destructively. Each leaf pays full token generation price for the prefix, turning a 256‑way fan-out into a 256× token multiplier on the same context. Latency balloons because the provider must compute KV caches for the prefix again and again, saturating its own resources and throttling throughput. Concurrency collapses under the weight of token budgets and rate-limit headroom: what should be a fast, parallel leaf execution becomes a serialised, cost-exploding parade.

The failure is silent — no errors, no crashes. A developer may test with a handful of leaves and never see the problem, only to hit a wall when the DAG widens. The brittleness is that concurrency and prompt size are coupled; eliminating that coupling is the design’s core job.

How it works

The harness materialises the shared context exactly once, before any leaf is dispatched, and locks it as a deterministic, immutable byte sequence. Subsequent leaves do not re‑assemble this prefix; they reference it through the provider’s prompt‑cache mechanism. The provider stores the KV state of the prefix and serves it to every leaf that presents the same byte‑exact prefix, skipping recomputation entirely.

• Each leaf’s request consists of the cached prefix (or a reference to it) plus a leaf‑specific suffix. The provider treats the prefix tokens as a cache hit, billing them at roughly 10% of generation price.
• Recomputation drops to zero; only a lightweight cache‑lookup per leaf remains.
• Structural sharing makes wide concurrency affordable: under this scheme, DeepSeek workloads routinely fan out ~256‑way on a single cached prefix; MiMo scales to ~8‑wide.
• The frozen prefix is a red line. Any edit — even a single token change — invalidates the cache for all downstream leaves, forcing a full recompute of the prefix’s KV states for every leaf. Therefore the harness treats prefix modifications as schema‑breaking operations, permitted only at the conductor’s explicit re‑planning step.

The design divorces concurrency width from prompt‑size cost. Parallelism is now bounded by the provider’s request‑per‑second or token‑per‑minute limits, not by how large the shared context is.

Trade-offs & boundaries

The frozen prefix imposes strict rigidity: the shared context must be identical for all leaves in a DAG. There is no hybrid “partially dynamic” mechanism — any per‑leaf variation in the system prompt or task framing would require a different prefix, defeating the cache’s benefit. Those leaf‑specific needs must reside in the suffix, which does not benefit from caching.

The biggest cost is the red‑line penalty. Changing the prefix mid‑flight forces a complete recomputation of every subsequent leaf, spiking token usage and latency. This is acceptable only when re‑plans are rare — the conductor’s re‑planning step is explicitly gated to absorb that cost deliberately, not accidentally triggered by a leaf.

The mechanism depends on the provider supporting prompt caching. If a provider does not offer caching or charges full token price even on cache hits, the token‑savings vanish; only the structural simplification remains. For very small DAGs (a few leaves) or trivial shared contexts, the overhead of managing the frozen prefix may exceed the benefit.

Cache‑hit economics rely on the prefix being reused densely within a short window — exactly the pattern the harness guarantees. However, the harness does not control the provider’s cache eviction policy; it simply ensures the prefix is byte‑stable and transmitted uniformly. The degradation path is a full recompute per leaf, which the harness treats as an expensive cache miss, but does not attempt to retry or compensate.

When it earns its place

The frozen prefix pays off whenever a large, static shared context feeds many concurrent leaves.

• Wide‑fan DAGs such as code generation where a single specification spawns hundreds of independent function implementations. Each leaf inherits the same architectural constraints; the prefix is paid once, parallelism becomes nearly free.
• Multi‑agent evaluation where the same scoring rubric and system prompt are applied to dozens of responses in parallel.
• Batch extraction or classification with a fixed schema description and formatting rules; only the input record varies per leaf.
• Cost‑sensitive deployments where token budgets are tight and the ~10% cache‑hit pricing turns a prohibitive fan‑out into a manageable expense.
• Latency‑sensitive real‑time agents where skipping the KV prefill shaves hundreds of milliseconds per leaf.

The mechanism is overkill for single‑leaf tasks or DAGs whose shared context is trivial (e.g., a one‑line system prompt). It earns its place precisely when the parallelism would otherwise be throttled by token cost — and the shared context is large enough to make the savings decisive.

The frozen prefix turns concurrency from a token cost into a rate‑limit game: pay for the shared context once, and only once.

Best-of-N graft is a harness strategy for high-stakes leaf nodes: the conductor launches N independent attempts in parallel, all sharing the same frozen prefix. A configurable judge panel scores each on cost, quality, and latency; only the top-scoring attempt is grafted into the main tree, while the rest are discarded. The one idea it turns on is that the frozen prefix means you pay for concurrency, not N times the tokens — the cost applies only to the divergent suffixes.

The failure mode

Without Best-of-N, every leaf is a single model call. For a tricky algorithm, a design decision, or an ambiguous spec, that one attempt is effectively a coin-flip. If the model’s first sample is suboptimal — a brittle implementation, a misguided design choice, a misinterpretation — the error propagates silently downstream. Later leaves build on a flawed artifact, compounding the damage. Detection comes late, forcing an expensive re‑plan that rolls back the entire tree or subtree. Even serial retries are wasteful: each pays the full token cost of the prefix again, and there is no mechanism to compare candidates systematically. The plan’s quality collapses to the reliability of its weakest leaf, and developers are left betting the whole tree on a single guess.

How it works

• Frozen prefix. All N attempts share identical context up to the leaf — same conversation history, same intermediate results, same instructions. Divergence begins only at the leaf input, so token expenditure is bounded: you pay roughly for the common prefix once plus N times the suffix tokens. Concurrency replaces token multiplication.
• Parallel execution. The conductor marks the leaf for Best-of-N and launches N independent invocations simultaneously. Every attempt runs in its own model call with no shared mutable state. Latency is the slowest attempt’s wall‑clock time, not the sum.
• Judge panel. Per‑leaf scoring function evaluates each completed attempt on three axes — cost (tokens consumed), quality (correctness, style, adherence to constraints), and latency — each with configurable weights (e.g., quality 0.7, cost 0.2, latency 0.1). The panel may be a rule, a schema validator, or a model call. Only the highest-scoring attempt is grafted into the tree; the discarded N‑1 attempts are ephemeral and never visible downstream.
• Quality gate. If every attempt falls below a minimum quality threshold, the leaf fails as a whole. No “least bad” result propagates. The conductor must then re‑plan or escalate the failure, preventing silent degradation.

Trade-offs & boundaries

What it costs. Concurrency overhead is the primary price: N parallel calls consume rate‑limit headroom, worker slots, and memory. When many leaves in a plan use Best-of-N simultaneously, the system may saturate and starve other branches. Latency is bounded by the max attempt duration plus judge evaluation, not the average. Discarded suffixes waste tokens — if the suffix is long relative to the prefix, the token savings shrink. Finally, the judge panel itself adds latency and, if it is a model call, additional token cost.

Where it does NOT apply. Leaves that produce expensive external side effects — database writes, email dispatch, payment API calls — must never use Best-of-N. Every attempt would fire its side effect, and there is no transactional rollback for losing attempts. State‑dependent judge logic also breaks the pattern: if the judge’s score depends on mutable external state (e.g., a counter that increments per attempt, or the order in which attempts complete), comparisons become invalid. The judge must be a pure function of the attempt’s output and the leaf’s input. Likewise, leaves whose output cannot be independently scored (e.g., purely subjective creative copy without a rubric) are poor candidates; an automated judge provides a false sense of reliability.

Degradation path. If all attempts fail the quality gate, the leaf fails cleanly — better than a silent rotten output. In practice, developers can tune N downward when resources are tight (a small N still diversifies risk) or increase N when the solution space is especially wide. The score gap between top attempts serves as a signal: if attempts score similarly, the extra concurrency buys little; if they diverge sharply, the graft is working.

When it earns its place

• A tricky algorithm or refactor with a wide solution space. Multiple plausible implementations exist; one might handle edge cases poorly. Best-of-N tests the space concurrently and picks the cleanest, cheapest result.
• A design decision with several plausible approaches. Choosing between an event‑driven vs. polling architecture, or a factory vs. strategy pattern. Each attempt argues for a different approach, and the judge picks the best trade‑offs.
• Ambiguous specs where a single pass is a coin‑flip. When the prompt leaves room for interpretation, N attempts sample the interpretation space; the judge selects the most coherent or conservative match.
• Any leaf where being wrong is expensive to discover later. Core business logic, data‑model schemas, security boundaries — a single mistake cascades through dozens of downstream nodes. The concurrency cost of a graft is an insurance premium against much larger rework.

Best-of-N graft buys reliability at the cost of concurrency: the frozen prefix keeps token cost low, and only the winner survives.

Hashline is a harness-level verification step that eliminates line-shift errors from cheap executor models. It works by hashing every line an edit touches—plus surrounding context—before and after the patch, then comparing. If the intended target line’s content is found uniquely elsewhere in the modified file, the offset is auto-corrected; otherwise the patch is rejected outright. No prompt changes, no model involvement, negligible latency. The core idea: use the line’s own content as the positional anchor, not a model’s fragile line-number guess.

The failure mode

A cheap executor model, chosen deliberately for speed and cost, often misplaces an edit by one line. An instruction to change line 42 lands at line 41 or 43. The resulting diff still looks plausible—the code change is syntactically correct, the file compiles, and static checks pass. The error is invisible. Over repeated turns, these off-by-one mistakes compound silently. A guard condition drifts to the wrong branch, a comment migrates one line up, a function call shifts into a different scope. The codebase still builds, tests may still pass, but the logical structure rots. The corruption surfaces only when a downstream bug forces a costly forensic trace across turn history. Debugging that mess far exceeds the compute savings from using a cheap model. The root cause is that weak models treat line numbers as textual coordinates, not semantic anchors—their token-level spatial reasoning is fuzzy, and every edit is a gamble on positional accuracy. Without a mechanical guard, the harness trusts the model’s reported coordinates, and that trust is brittle.

How it works

Hashline inserts a content-based check into the patch-commit pipeline, running entirely outside the model’s invocation:

• Before dispatch, the harness hashes every line the edit is supposed to touch, plus a configurable number of surrounding context lines. This captures the exact content of each line—whitespace and all—and stores the mapping of line-number to hash.
• After the executor returns the patch, the harness applies it to a local copy of the file and re-hashes the same logical lines (by their original positions).
• If every hash matches, the edit was correctly placed and the patch proceeds to commit.
• If a hash mismatch occurs, the harness scans the neighbourhood (typically the whole file) for a line whose content hash matches the pre-edit hash of the intended target line. If exactly one such line exists, the offset is automatically corrected—the edit is applied to that line instead. If zero or multiple lines share that hash, the patch is rejected outright.
• The model is never aware of this step. No prompt modifications, no retraining, no extra inference. The check completes in microseconds, orders of magnitude faster than the model call itself.

This mechanism decouples positional accuracy from model quality. The executor need only produce the correct content for the target line; the harness ensures that content lands on the correct line in the file. Reliability is engineered outside the model.

Trade-offs & boundaries

Hashline is a positional guardrail, not a semantic one. It verifies where an edit lands, not whether the edit itself is logically correct. A patch that is perfectly aligned but introduces a bug will still pass. It complements, rather than replaces, other verification stages.

Hash uniqueness requirement. Auto-correction depends on the intended target line having a unique content hash in the file. If the line is blank, contains only whitespace, or duplicates a neighbour (e.g., consecutive }) lines, the harness cannot disambiguate and falls back to rejection. This is by design: a safe rejection beats a silent misapplication. In practice, non-trivial code lines with distinct identifiers or comments rarely collide, so auto-correction activates most of the time. For files with heavy repetition (auto-generated headers, tabular data), the rejection rate may rise.

Architectural cost. The harness must maintain a pre-edit snapshot of the file to re-hash after the patch is applied—a minor memory overhead that is usually already present in the conductor’s state management. Hashing adds a few microseconds per edit, negligible next to model inference.

Degradation path. As duplicate content increases, rejections become more frequent. Each rejection costs a retry (the conductor redispatching the edit, possibly to a stronger model) but prevents silent corruption. Users can tune the context window size; a wider window can improve uniqueness but also increases the chance that a legitimate edit to a context line triggers a false mismatch, so the trade-off is deliberate.

Scope. Hashline operates on single-file, line-based edits. It does not apply to whole-file rewrites (where “touched lines” lose meaning) or to cross-file moves. Insertions and deletions are handled implicitly: the search compares content, not absolute positions, so an insertion that pushes the target line down does not break the check.

When it earns its place

Hashline earns its weight whenever a cheap executor model is selected for speed or cost rather than positional precision. Concrete scenarios:

• Iterative, multi-turn editing loops—a conductor making dozens of small patches across a session. Without Hashline, the probability of at least one off-by-one error approaches certainty; with it, each patch is pinned to content, not fragile line numbers.
• Cheap executor farms—teams running small, fast models (e.g., Llama 8B, Gemma, Claude Haiku) for bulk leaf edits. These models are cost-efficient but notoriously weak at spatial reasoning. Hashline lets them do surgical, line-precise work that they otherwise couldn’t be trusted with.
• CI/CD fix-bots or automated refactoring—any pipeline where a patch must land correctly without human inspection. A rejection surfaces the failure immediately, rather than hiding it in a corrupted file that only breaks later.
• Mixed-tier systems—a costly conductor model (e.g., Opus, GPT-4o) paired with cheap executors. The planner’s expensive reasoning is wasted if an executor misplaces a line; Hashline decouples the two, preserving the economic advantage of the cheap worker.

It is less useful when the executor model already has near-perfect positional accuracy (top-tier models on short contexts) or when the edit simply regenerates the whole file. But the overhead is so small that it is often left enabled by default—even strong models occasionally miscount lines in very long files.

Never trust a model to count lines—let the content hash be the anchor.

Language-server integration feeds the executor a live, structured view of the codebase through the Language Server Protocol. It turns the problem of “guessing the program” into one of “querying the program,” shifting agent reasoning from probabilistic text completion to an anchored symbol table provided by the same toolchain that powers human editors.

The failure mode

Without LSP integration the executor operates on raw text. Every symbol reference, import path, and method signature must be inferred from surrounding tokens. The model can produce code that looks plausible—correct indentation, familiar naming—yet silently breaks invariants. It may rename a function while missing call sites in other files, generate a call to a method that does not exist, or import a module that was never installed. This is the hallucinated‑path failure mode: the model confidently constructs a reality that has no ground truth in the codebase, and because the text appears coherent the agent has no internal alarm.

The waste compounds. The executor might dump entire files into context hoping the model will spot relevant parts, burning tokens and attention budget on irrelevant function bodies. It may issue clarification rounds (“what is the return type of parseConfig?”) that could have been answered instantly. Worst is silent corruption—edits that pass visual review but break the build or introduce subtle semantic mismatches. Every such edit requires manual debugging that defeats the purpose of automation, and the brittleness scales combinatorially with the number of files the model consults.

How it works

The executor acts as a lightweight LSP client. Instead of asking for a file as free text, it sends targeted, read‑only queries and receives structured replies:

• textDocument/documentSymbol returns the symbol tree of a file—names, kinds (function, class, variable), and location ranges.
• textDocument/references enumerates every usage of a symbol across the entire project.
• textDocument/definition resolves a symbol to its exact declaration site, including file, line, and column.

Each query returns AST‑level metadata, never raw text. The executor constructs its internal symbol table exclusively from these responses. The model can request only what the LSP reports; it cannot fabricate a definition or call site that does not exist. Edits become grounded: renaming a symbol reveals every affected location before the model writes a single token; adding a function call checks the target signature against the actual code graph. The executor reads only the files and line ranges the LSP points to—never entire files hoping context aligns—dramatically reducing token consumption.

The integration is read‑only on the LSP and per‑language. It never sends mutations like textDocument/rename; it activates only when a language server is running for the relevant file type. If no server is available, the executor falls back to text‑based heuristics—less reliable, but functional. When a server is present, structured queries are always preferred.

Trade-offs & boundaries

Language‑server integration has honest edges. It requires a running LSP per language, adding startup latency while the server indexes the project. For short‑lived, single‑file tasks the overhead may outweigh the benefit. The fallback to text heuristics is noisier and less precise, so environments without an LSP (some dynamic languages, custom DSLs) operate at reduced reliability.

The integration is strictly static. It provides structural metadata—symbol names, types, references—but not runtime types, dynamic dispatch, or metaprogramming patterns. A method that compiles but throws at runtime will not be caught. The model must still read bodies and comments for semantic understanding; LSP anchors the structure of reasoning, not its meaning.

LSP servers themselves vary: some lag behind language versions, some omit certain symbol kinds, some crash during large indexing. The harness must handle these gracefully—timeouts, retries, degradation—never blocking the plan indefinitely.

When it earns its place

LSP integration pays off whenever the agent must navigate a codebase with multiple modules or produce edits that demand structural precision. Concrete triggers:

• Cross‑file refactoring: renaming a symbol that appears in dozens of files. The references query provides a definitive list of affected locations, preventing silent misses.
• Type‑aware code generation: adding a function call that must match a signature in another file. The definition query reveals the exact parameter types and return type, eliminating guesswork.
• Import management: documentSymbol lists a module’s exports, so the agent can choose the correct import path without scanning the file manually.
• Validating edits before commit: a follow‑up references query can verify that no dangling references remain after a change.

For single‑file tasks with simple patterns (e.g., generating a unit test for a known signature), the startup cost may not be justified. But any time the agent would need to ask “what is the definition of this name?” or “who uses this variable?”, the LSP provides the answer instantly and groundedly.

The LSP is the single source of truth for static program structure—the harness engineers reliability from outside the model.

The MCP router is a single entry point inside the Xihe harness through which every Model‑Context‑Protocol tool invocation must pass. It turns on one idea: separate the inventory of available tools from their schemas and results. Agents see a lightweight menu and compact pointers; schemas and large payloads are fetched or stored on demand, never preloaded or dumped into context.

The failure mode

Without a centralized router, every agent must preload the complete MCP tool schema into each prompt turn—a fixed tax that grows with the tool catalog. A single schema can weigh hundreds of tokens; a dozen tools waste 4–8K tokens per turn on unused metadata, crowding out task instructions and reasoning space. This is silent context poisoning: no crash, just a gradual degradation of response quality as the prompt fills with irrelevant structure.

The second failure is output dumping. When a tool returns a large payload—file contents, search hits, database rows—it lands directly in the context window. The context bloats monotonically, triggering latency spikes (the model must re‑ingest the entire bloated history), token overflow, and cost blowouts. Because each agent manages its own tool calls, there is no central point to trim, meter, or audit what happened. Adding tools makes prompts heavier; executing tools makes contexts larger. The result is a brittle, scale‑negative integration: more capability means worse performance, often invisibly until the system breaks.

How it works

The router sits in the harness, never on the agent side. It enforces a uniform interface through three meta‑tools, replacing raw schema injection with controlled, on‑demand access.

• Resident menu. At startup the harness builds a lightweight list of tool names and one‑line descriptions. This menu costs only a handful of tokens per tool and lives in the agent’s context as the sole static reference. No schemas, no parameters—enough for an agent to discover what’s available.
• On‑demand schema loading. When an agent decides to invoke a tool, it first calls describe(tool_name). The router fetches the full JSON schema only then, and only for that single tool. The schema never appears in the prompt unless the agent explicitly requests it, cutting per‑turn tool overhead by roughly 70% compared to preloading everything.
• Three meta‑tools. All MCP interactions flow through search (discover tools by capability), describe (retrieve a tool’s schema), and call (execute with parameters). The router never exposes raw tool injection; an agent cannot bypass this interface. The harness intercepts and rejects any direct MCP traffic.
• Output sandboxing. When a tool returns a large result, the router stores the full payload externally and returns a compact pointer—an identifier plus the byte size—instead of the raw output. The agent sees only the pointer, keeping the bulk out of the context window. For oversized results this yields approximately 98% context savings.
• Audit boundary. Every search, describe, and call is logged at the router boundary: agent ID, tool name, input size, output size, latency. The harness maintains a single, structured audit stream for billing, debugging, and governance. The conductor and dispatch remain completely oblivious to output bulk; they schedule leaf tasks that produce pointers, not documents.

The developer experience is simple: register MCP servers with the router via a configuration map. No agent code changes when tools are added or removed. The router’s menu updates automatically at harness initialization.

Trade‑offs & boundaries

On‑demand schema loading adds one extra round‑trip (describe) the first time a tool is used in a turn. For agents that call the same small set of tools repeatedly, this overhead is small compared to LLM inference time but not zero. A very low‑latency pipeline (sub‑200 ms per turn) might feel the cost; in all other cases the token savings outweigh it.

The router is a single point of failure. If the router process goes down, no agent can call any MCP tool. The harness is already a critical component, so this is usually acceptable, but high‑reliability deployments should plan a standby or a graceful degradation path—for example, falling back to a static menu with no sandboxing.

Output sandboxing depends on an external store (in‑memory, file, or object store). If that store is unavailable, the router cannot return a valid pointer. A fallback policy must be explicit: either fail the tool call or allow inline output with a warning. The ~98% savings apply only to large outputs; results already below the sandboxing threshold pass through directly, yielding no savings.

The router does not enforce tool authentication or authorization—that remains the MCP server’s responsibility. It also does not rank tools or decide which to call; the agent’s reasoning loop owns that choice. Finally, the router is not a replacement for overall context window management. Repeatedly calling the same tool and holding old pointers still grows context, so the conductor must still apply summarization or eviction policies.

When it earns its place

The MCP router pays for itself as soon as an agent uses more than three MCP tools, or any tool regularly returns more than a few hundred tokens of output. It is indispensable when:

• Agents share a growing set of tools (codebase search, file I/O, API clients) and preloading all schemas burns 5–15% of the context window.
• Tools produce variable, often large, results—file contents, database dumps, search results—where a single oversized payload would otherwise poison the turn.
• Token budgets are tight, either because of cost constraints or small model context windows.
• Every tool call must be audited for compliance, cost allocation, or replay debugging.
• Multiple agents use the same MCP servers; the router provides a single metered, sandboxed interface and prevents cross‑agent context contamination.

In contrast, a two‑tool prototype with sub‑500‑byte outputs and no audit requirements sees only overhead. The router’s value emerges at scale—precisely when the naïve MCP pattern begins to break.

The MCP router turns MCP from a per‑turn tax into a per‑use toll—metered, sandboxed, and auditable at the harness gate.

Instead of reading files into the context window for computation, the agent writes a small, self-contained script (Python, shell, SQL) that runs in a sandbox. Only the script’s stdout or a failure signal re-enters context — raw file contents never do. This shifts counting, diffing, formatting, and aggregation from an untyped, expensive channel (LLM reasoning) to a typed, cheap channel (execution), turning the model into a thinker rather than a calculator.

The failure mode

Without context-mode, every deterministic sub-task forces the LLM to ingest raw data and perform arithmetic, pattern matching, or logic inside a probabilistic environment. This breaks in three concrete ways. First, token waste and context bloat: raw files consume the budget that should go to planning, making the conductor forget earlier turns as the window fills with noise. Second, silent data hallucination: the model miscounts, invents numbers, or misaligns columns with high confidence, and the error propagates invisibly into downstream reasoning because there is no verifiable trace. Third, non-reproducible output and lost auditability: natural-language reasoning is opaque; a reviewer cannot replay the computation to find the mistake, and a hallucinated summary looks just as plausible as a true one. The harness cedes deterministic work to the component least suited for it, turning every such task into a reliability landmine that poisons the agent’s output without a crash.

How it works

The harness inspects the conductor’s plan and classifies leaf tasks whose result depends only on deterministic computation over known data (counting matches, diffing files, aggregating columns, formatting structured output). When the query is unambiguous enough, it routes the job to a sandboxed executor — this decision can be per-task or a global setting, and it is enforced by the dispatch layer, which is determinate code, not an LLM.

• Script generation. The agent composes a short, self-contained script with explicit input paths, inline comments, type annotations, and assertions. These serve as the reasoning trace; the code is the thought.
• Sandboxed execution. The script runs in an isolated environment (no network, read‑only filesystem, resource limits). Only stdout and an exit code cross the boundary. The sandbox rejects side‑effects and enforces timeouts.
• Result compression. The harness captures stdout (typically a single value, JSON, or table) and forwards it to the conductor as a compressed fact. A non‑zero exit or timeout becomes an explicit, structured failure signal — never a guessed summary.
• Full audit trail. The script source, invocation timestamp, exit code, and output are logged externally. Any developer can replay the exact computation later, turning reasoning from opaque prose into a reproducible artefact.
• Fallback on ambiguity. When the task demands nuance, subjective judgment, or the agent’s script fails irrecoverably, the harness degrades silently to standard context reading. The fallback is transparent to the conductor but noted in logs, preserving correctness at the cost of extra tokens.

Trade-offs & boundaries

Context-mode imposes real costs. Latency from sandbox startup and script writing can be disproportionate for trivial queries (“count words in a single line”). Token overhead appears because generating correct code consumes output tokens; the trade‑off is upfront token spend for later correctness and auditability. Agent competence matters — small or non‑coding models may produce broken scripts, forcing a fallback and wasting time. Security is mandatory: the sandbox must prevent writes, network access, and runaway loops; a mis‑configuration turns code execution into a dangerous vector. Not for nuance: the mode absolutely cannot handle open‑ended tasks like tone analysis or style critique. If forced, a script returns a vacuous mechanical answer (e.g., “0 differences” because it only checked string equality). The red line is that raw file contents must never enter context when active; the harness must intercept and strip any unintended data. The degradation path fails explicitly: if a script errors out, the harness does not retry blindly but escalates to standard reading, adding latency but avoiding silent corruption. Classifying ambiguity correctly remains an engineering art, not a solved algorithm — over‑eager routing produces brittle failures, while under‑eager routing wastes tokens.

When it earns its place

Context-mode earns its place in every concrete, verifiable question from structured or semi‑structured data. Concrete examples: counting occurrences of a pattern across a codebase (PR review), diffing two configuration files or API responses, formatting a CSV into a nested JSON structure, aggregating metrics across multiple log files, or extracting the third column from rows where a value exceeds a threshold. It also shines in multi‑step DAGs where an intermediate count, sum, or constraint check must be exact before the next step proceeds — for instance, a conductor planning a refactor first needs an exact count of deprecated API calls. In audit‑critical environments, the script is a repeatable reproducer, and the output is a single deterministic line. The pattern eliminates the “hallucinated number” bug class that looks plausible in review but erodes trust in the entire system.

Context is a budget to compress, not expand — write a tool, not a document; let code carry the precision, and keep the model for what it does best.

The harness decomposes agent work into three hard-boundary layers—Conductor, Dispatch, Executor—each decoupled from any specific model. The one idea it turns on is that reliability is an engineered property of control flow, not a byproduct of careful prompting. By forcing planning, routing, and execution into separate roles, the harness eliminates the entanglement that makes model‑driven pipelines brittle.

The failure mode

Without this three‑way separation, agent loops collapse into monoliths where the same model decides what to do, when to do it, and how to recover. That coupling breeds a family of failures:

• Race conditions on shared state. Two subtasks that appear independent in a prompt may update the same mutable context (a file handle, a progress counter) without coordination. Without compare‑and‑swap gating, they interleave and corrupt each other’s data, producing outputs that look plausible but are logically inconsistent.
• Silent corruption. A leaf returns a wrong but well‑formatted result. No independent layer validates it; the error propagates downstream, and the developer sees a correct‑looking final answer. The damage is invisible.
• Wasted inference. A single model re‑plans the entire task for a leaf‑level failure, burning tokens and latency to re‑reason over work that was already correct. Alternatively, the system retries the same prompt infinitely because it lacks a distinct re‑planning vocabulary.
• Model‑lock‑in. Every step runs on the same model because there is no routing layer. A cheap, fast model cannot be used for routine leaves while a reasoning‑heavy model handles only the planning—cost and quality are locked together.
• Brittle recovery. When the model itself both plans and executes, a failure is indistinguishable from a change of intent. The system either retries blindly or gives up entirely.

All of these are failures of orchestration, not model quality. The harness solves them by giving each responsibility a separate, deterministic owner.

How it works

The harness enforces three roles with iron boundaries:

• Conductor receives a user intent and returns a directed acyclic graph (DAG) of atomic leaves. Each leaf defines a unit of work—a prompt template, a model binding (Opus, Codex, GLM), and a failure threshold. The conductor is reasoning‑heavy and hot‑swappable; you can swap the planning model without touching the rest of the harness. It never touches execution, never reads a model output, and never consumes raw tokens. Its product is the DAG alone.
• Dispatch is deterministic harness code with no model in the loop. It polls the DAG for leaves whose dependencies are satisfied, layers them topologically, and fans them out under bounded concurrency. Each leaf is routed to its pre‑bound model. State transitions—ready, in‑flight, done, failed—are gated with compare‑and‑swap (CAS) to prevent double‑dispatch or races. Dispatch never plans, never validates an output, and never calls a model. Its job is strictly sequencing and routing.
• Executor runs a single leaf atomically on its assigned model. It receives the leaf definition and pre‑computed inputs from its dependencies, calls the model, and returns either a structured output or a failure signal. It has zero visibility into the DAG, prior leaves, or the overall plan. It is cheap, stateless, and massively parallelizable. Executors do not validate—they only return a binary pass/fail.

The critical loop: when an executor signals failure, dispatch marks the leaf as failed, stops the DAG for that branch, and returns control to the conductor. The conductor then replans—re‑splitting the sub‑DAG, changing the model, or aborting the intent entirely. A failure never passes the dispatch gate silently; it always re‑enters the reasoning layer.

Trade-offs & boundaries

The separation is not free:

• DAG construction overhead. Every task, even a trivial one, requires at least one conductor call to produce the initial plan. For a single‑step operation, this adds latency and cost without benefit.
• Re‑planning latency. A failed leaf must bubble up to the conductor, be re‑reasoned, and produce a new sub‑DAG before execution resumes. For workflows where failures are rare, the indirection may be overkill.
• Granularity burden. The developer must decompose intents into genuinely atomic leaves. Leaves that are too coarse waste re‑planning cycles; leaves that are too fine bloat the DAG and increase dispatch overhead. There is no automatic right‑sizing.
• The verifier closes the plausibility gap. A leaf can return a plausible but wrong result, and the executor’s own pass/fail signal won’t catch it. The verifier — a model‑agnostic cross‑model skeptic, off by default — reviews results after the DAG runs; on a real flaw the conductor silently escalates to a stronger model and re‑plans. Opt‑in: without it configured, a returned result counts as success.
• Determinism limits. Dispatch’s CAS gating guarantees each leaf runs exactly once, but the timing of concurrent dispatches is non‑deterministic. If leaves modify shared external resources, ordering can still cause races—the harness provides no transactional safety for external state.
• Conductor degradation. If the conductor itself fails repeatedly (mis‑specifies the DAG, hits rate limits), the system degrades to a hard error. There is no graceful partial output; either the plan completes or it does not.

Red lines are absolute and breaking them voids the reliability guarantees: dispatch never plans, the executor never validates, and the conductor never consumes raw model outputs. If the conductor ever touches a leaf output, it reintroduces the silent‑corruption path the harness was built to eliminate.

When it earns its place

This architecture pays off when:

• The workflow spans multiple models with different cost/latency profiles—e.g., a reasoning‑heavy planner, a fast executor for bulk operations, and a specialist for code generation. Each leaf is pre‑bound to the right model.
• Independent subtasks can run in parallel (e.g., generating tests, docs, and stubs for the same function). Bounded concurrency prevents resource saturation while exploiting full parallelism.
• High‑stakes correctness is non‑negotiable—financial, legal, or safety‑critical tasks where a silently propagated error is unacceptable. The re‑plan loop ensures that every failure is diagnosed at the reasoning level.
• You need auditable traceability—each leaf’s input, output, and failure history is logged, and the DAG provides a full provenance record for debugging.
• You expect model instability and want a fault‑tolerant system where retries or model switches happen at the plan level, not in an opaque prompt loop.

The planner plans, the router routes, the executor acts—failures return to the reasoning level, never to a model‑in‑the‑loop retry.

The web stack is a harness‑level resource that turns the internet into research‑grade signal by owning the entire retrieval pipeline — querying, failover, content extraction, and size sandboxing — outside the model. Its core premise: every fragile part of web retrieval is engineered into the harness, not prompted into an LLM. The conductor issues a search intent, and the stack autonomously returns clean, bounded text excerpts; the model never parses HTML, handles API keys, or reasons about missing providers.

The failure mode

Without the web stack, any agent that needs online information falls into silent failure patterns. A single‑provider dependency means one expired or exhausted API key stops all retrieval, often without a clear signal — the model receives an empty string or an error page and continues reasoning on noise. Manual URL curation or prompt‑based search forces the conductor to guess links or rely on the model to parse messy HTML, bloating context with navigation and ads. Oversized pages then explode the context window: a single article packed with boilerplate can consume thousands of tokens before any fact appears, triggering silent truncation or drowning the signal in irrelevant content. Because retrieval is treated as an in‑model problem, brittleness compounds — recovery logic, retry prompts, and hallucinated fallbacks all waste reasoning budget and corrupt downstream conclusions. The harness is absent, so reliability rests on fragile tool‑call chains that break silently.

How it works

The web stack operates as a single harness‑level resource invoked by the conductor with a search intent. No hand‑fed URLs, no recovery prompts. It encapsulates three autonomous mechanisms:

• Provider rotation – A pool of search backends (Bing, SerpAPI, self‑hosted endpoints) is cycled automatically. When a provider’s API key is absent or exhausted, that backend is silently skipped. The stack returns a structured “no results” envelope only when every provider in the pool is unreachable. Degradation is graceful: a missing key never breaks retrieval, and the conductor never sees the failover.
• Content extraction – Every fetched page is reduced to its text signal using a Trafilatura‑style extractor that discards navigation, ads, boilerplate, and formatting. The output is a clean block of paragraphs and headings, stripped to the semantic core. If the extracted text exceeds a configurable size threshold, the MCP output axis automatically sandboxes it. Downstream agents receive a pruned excerpt or a condensed reference — never a raw DOM that could overflow context or introduce noise.
• Model‑agnostic reliability – Search dispatch, provider failover, extraction, and sandboxing all happen outside the model loop. The harness owns the mechanics, so the model stays focused on decision‑making. Retrieval is deterministic: the conductor sends an intent, the stack returns structured text snippets with source metadata.

Trade-offs & boundaries

The web stack’s design is deliberate, and its edges are honest.

• Latency overhead – Rotating through providers and fetching full pages adds network time per query. The stack trades absolute speed for guaranteed structural signal; it is not tuned for sub‑second interactive loops.
• Content extraction is lossy – Trafilatura‑style extraction works best on static, well‑structured HTML. It discards images, layout, and interactive elements, and it cannot execute JavaScript. Dynamic content (single‑page apps, lazy‑loaded text) may be minimal or missing. Workflows that need visual evidence or original page layout will get nothing useful.
• Sandboxing is a blunt instrument – Oversized content is truncated, not intelligently summarised. A low threshold may discard nuance; a high threshold may still stress context windows. The configurable size limit demands tuning for the model in use.
• Result quality depends on provider relevance – The stack returns the top results from the search provider as they are. It does not re‑rank, filter spam, or compensate for low‑quality indexes. A degraded provider that returns noisy results will feed those into extraction without signal‑quality checks.
• Network and key dependency – At least one valid provider key must exist in the pool. If all keys are exhausted or misconfigured, the structured “no results” envelope is returned, and the conductor must handle that case explicitly (e.g., fallback to local knowledge or mark the branch unresolved). The stack will not retry indefinitely or alert beyond the empty envelope.
• No interactive or streaming pages – The stack fetches a static URL per result. It cannot follow pagination chains, handle form submissions, or maintain authenticated sessions. It is a one‑shot, text‑first extractor, not a general web browser.

Red line: the stack never exposes raw HTML, never interprets JavaScript, and never bypasses the size sandbox. The conductor cannot override sandboxing or demand a specific provider on a per‑request basis.

When it earns its place

The web stack pays off wherever research breadth is high, context budgets are tight, and the conductor must ground plans in live, uncurated sources without fragile per‑agent integration.

• Research‑intensive plans – A conductor that needs to verify facts from multiple sites or collect documentation across domains can issue search intents as DAG steps; the stack handles parallel retrieval, failover, and pruning, keeping token consumption predictable.
• Long‑running autonomous agents – In loops that run for hours, the cost of a single oversized page grows exponentially. Mandatory sandboxing prevents context‑window explosions from accumulating over time.
• Multi‑step synthesis or reports – Clean extracted text can be fed directly into a summarisation executor or verifier without preprocessing. No manual URL whitelisting or prompt‑engineered recovery logic.
• Environments with multiple search providers – Teams that avoid vendor lock‑in by pooling Bing, SerpAPI, and self‑hosted endpoints gain resilience: one expiring key is a non‑event, and retrieval continues until all providers are exhausted.
• Scenarios that previously demanded hand‑curated URLs – If the workflow required a human to pre‑select pages or a brittle script to scrape them, the web stack replaces that with a single intent call, keeping the conductor in its planning lane.

The harness owns retrieval so the model never has to negotiate a rate‑limit or parse a <div>.