Ingest: How to build your own agent harness??? (Mike Piccolo / iii)

Type: kb/sources/types/ingest-report.md

Source: how-to-build-your-own-agent-harness-2060069083878408689.md Captured: 2026-05-29 From: https://x.com/mfpiccolo/status/2060069083878408689

Classification

Type: practitioner-report -- Mike Piccolo (Founder/CEO @iiidevs) describes the actual production stack driving an iii agent turn, naming workers, function ids, FSM states, and a shipped refactor. It is a build-and-ship account, not a peer-reviewed study or a neutral taxonomy; it also carries a clear product thesis (iii is the right substrate), so it sits at the practitioner-report/tool-announcement boundary but is dominated by the worked implementation detail. Domains: agent-harness, orchestration, composability, calling-conventions Author: Founder/CEO of the iii project (vendor-interested). Credible on the implementation he is describing because he cites concrete artifacts (iii-hq/workers monorepo, function ids, iii-permissions.yaml, the FSM 11→7 refactor); weak as a neutral comparison because the framework alternatives are characterized only to contrast against iii.

Summary

The post argues that a production agent harness is not one importable framework but ~13-15 separable jobs (provider routing, credential vault, model catalog, durable turn FSM, skill serving, system-prompt assembly, streaming, policy check, approval gate, budget tracking, hook fanout, branching session tree, compaction, event stream, OTel tracing). Frameworks bundle these into a monolith and ship one version of each, so teams eventually fork or rewrite. iii instead ships each job as an independently-versioned worker on a shared engine bus, every worker speaking one WebSocket protocol and connected by a single primitive — iii.trigger() over name-based function ids (models::list, provider::<name>::stream, policy::check_permissions, approval::resolve). Because neighbours talk only through bus-level function ids, any layer is swappable by registering a worker for the same ids, and "build your own harness" collapses into "swap/add a worker." Thin-vs-thick stops being a fork and becomes a slider: a count of installed workers in config.yaml. The post walks one turn end-to-end and offers a self-contained FSM rewrite (11→7 states, with no neighbour change) as evidence the composition holds.

Connections Found

The companion connect report places this source firmly in the KB's harness cluster. As an immutable snapshot it authors nothing; the report's load-bearing output is reverse-edge candidates plus the outbound edges a future note-author could draw. The strongest fits are evidence relationships: agent-runtimes-decompose-into-scheduler-context-engine-and-execution (iii is a fifth convergent practitioner taxonomy whose workers map cleanly onto scheduler / context-engine / execution-substrate — and the only one shipping the decomposition as separately-versioned runtime components), agent-orchestration-occupies-a-multi-dimensional-design-space (iii fixes a distinctive point: external symbolic scheduler, cross-session versioned workers, fail-closed policy guarantee), unified-calling-conventions-enable-bidirectional-refactoring (production evidence that name-based dispatch makes components swappable without touching call sites), methodology-enforcement-is-constraining and enforcement-without-structured-recovery-is-incomplete (the policy worker + allow/deny/needs_approval outcomes + fail-closed-on-timeout + park/resume approval flow is a worked enforcement-plus-recovery layer), and always-loaded-context-mechanisms-in-agent-harnesses (per-turn system-prompt assembly plus progressive skill disclosure via directory::skills::get). The report also flags a theory gap: the KB has rich decomposition theory but no note treating component replaceability / independent versioning behind a uniform calling convention as a first-class harness property — iii is the clearest exemplar.

Extractable Value

  1. Component replaceability behind a uniform calling convention as a first-class harness property. The KB's decomposition theory argues analytic separability (you can describe scheduler/context-engine/substrate); iii adds the operational claim that practitioners now ship the layers as separately-versioned, hot-swappable units behind one bus primitive. This is genuinely new relative to existing connections and is the report's flagged theory gap. High reach: the "swap a worker that registers the same function ids" pattern generalizes beyond iii to any name-routed runtime. [deep-dive]

  2. "The slider, not the fork" reframing of thin-vs-thick. Reframes the Anthropic-thin-loop-vs-LangGraph-thick-DAG debate as a count of installed workers in a config file rather than a one-time architectural commitment. A reusable framing that improves how the KB discusses orchestration tradeoffs; extends agent-orchestration-occupies-a-multi-dimensional-design-space toward "the position on the axis is reconfigurable, not chosen once." [quick-win]

  3. Self-contained internal rewrite as evidence the composition holds. The turn-orchestrator FSM collapsed 11→7 states and deleted a per-call resume mechanism while every neighbour stayed unchanged because contracts are bus-level function ids. Concrete production evidence for unified-calling-conventions-enable-bidirectional-refactoring, which currently grounds the claim only on llm-do. [just-a-reference]

  4. Fail-closed enforcement-plus-recovery as a worked example. policy::check_permissions with a 5s timeout, three outcomes (allow/deny/needs_approval), gate_unavailable denial on timeout/unreachable, publish_failed treated as deny, and a single reactive turn::on_approval trigger that wakes parked calls. This is the recovery column enforcement-without-structured-recovery-is-incomplete describes, realized in production. [just-a-reference]

  5. The 13-15-job harness responsibility list. A concrete enumeration of harness jobs (turn FSM, provider routing, credential vault, model catalog, skill serving, prompt assembly, streaming, policy, approval, budget, hooks, branching session tree, compaction, event stream, OTel tracing). Useful as a checklist data point against the other harness-cluster taxonomies (Anatomy, What-is-an-agent-harness, Raschka). [just-a-reference]

  6. Bus-level function-id routing / engine-bus framing. No existing KB note uses an "engine bus / function-id routing where the engine routes to whichever worker registered the id most recently" mechanism. This is the source's most distinctive mechanism and a vocabulary candidate for discussing how uniform calling conventions are implemented at runtime, not just specified. [experiment]

Limitations (our opinion)

This is editorial opinion. As a practitioner report it shows only what worked: there is no account of failed attempts, latency or operational cost of running 13+ persistent WebSocket processes, or what breaks at scale when many workers contend on shared iii state. The "every worker is a persistent process" choice is the inverse of MCP's stateless-tools-on-stateful-server tradeoff (cf. mcp-bundles-stateless-tools-with-stateful-runtime) and the report does not weigh that tax. It is also vendor-interested: the framework alternatives (LangChain, LangGraph, CrewAI, AutoGen) are characterized only to contrast against iii, so the "frameworks lock you in / you'll rewrite a year in" claim is asserted from iii's vantage rather than measured. The central thesis — uniform calling convention makes layers swappable — is hard to vary and plausible, but the evidence is a sample of one mature project by its own founder; the convergence-across-the-industry reading should lean on the broader harness cluster (Anatomy, cybernetics, Raschka) rather than this source alone. Finally, "swap a worker" understates the contract-design work: the property only holds while the bus-level function-id contracts stay stable, which the FSM-rewrite example demonstrates but does not guarantee in general.

Write a new note in kb/notes/ capturing component replaceability / independent versioning behind a uniform calling convention as a first-class harness property (the connect report's flagged theory gap, Extractable Value #1). It should cite this source as primary evidence, link to unified-calling-conventions-enable-bidirectional-refactoring (mechanism) and agent-runtimes-decompose-into-scheduler-context-engine-and-execution (the decomposition it operationalizes), and carry the "slider not a fork" reframing into agent-orchestration-occupies-a-multi-dimensional-design-space. The connect report flags this as a split candidate, so expect the author to spread the remaining edges (enforcement/recovery, always-loaded-context) across their target notes rather than route everything to one.