Two backends, one app

The harness: original vs the iii refactor

A “harness” is everything around the model that turns a chat into an agent run — the turn loop, tool calls, streaming, sessions, policy, budget, and tracing. This app ships two of them, switchable per run from the chat UI.

Original — in-app harness

The default. Orchestration, the message bus, and tools all run in-process in the Next.js app over the Vercel AI SDK — hand-rolled across lib/.

Zero extra services — works out of the box
The nine patterns live in readable code you can step through
Perfect for a demo, learning, and local dev
No policy, no real budget caps, sessions in localStorage

Refactor — iii engine

The same runners, moved behind iii — an engine exposing a bus of swappable workers (functions, triggers, channels, streams) for the cross-cutting harness jobs.

A real policy layer + budget caps the original lacks
Server-side sessions and OpenTelemetry tracing
Durable runs (queue) and live events over a channel
Cost: a separate engine process to run and operate

Job by job

Harness job	Original	iii refactor
Turn / workflow FSM	Hand-rolled orchestrator + per-pattern runners in lib/ (~1,900 lines)	Same runners, but run inside a worker on the engine bus; optionally queue-backed so a turn outlives the request
Provider streaming	Vercel AI SDK, in-process	Kept — the same AI SDK runners run inside the worker
Events → UI	SSE from the Next route	Live SSE streamed over a channel (the HTTP response itself)
Tool calling	AI SDK tool() + zod	Same tools, gated by a policy check before they run
Policy / permissions	None — every tool runs unchecked	policy::check_permissions + iii-permissions.yaml, fail-closed
Cost / budget	Estimate only (lib/models.ts); nothing stops a run	llm-budget worker — real caps, alerts, forecasts
Sessions / history	Browser localStorage only	iii-state — server-side, keyed by conversation
Human-in-the-loop	In-memory map, single-process, 5-min timeout	Durable via the queue + state (survives restarts)
Observability	Terminal logging (chalk / boxen)	OpenTelemetry spans per worker, automatically
Deploy surface	One Next.js app — zero extra services	Next app + the iii engine (a separate process, e.g. on Fly)

How the toggle works

Every run targets a backend, picked from a selector next to the model and mode dropdowns (with a global default in Settings). The choice is threaded through the request and the API route, which dispatches to the in-app runners or hands the turn to the iii engine. The in-app harness is the default and is fully self-contained; the iii path activates only when an engine is configured. Same UI, same nine patterns, either way.

The refactor in iii's terms

The iii backend uses all four engine primitives: functions (the turn, plus state / stream / policy calls), triggers (an HTTP endpoint and a durable queue), channels (live events stream over the HTTP response; large artifacts hand off worker-to-worker), and streams (an optional named event log for persistence and fan-out).

It's a phased migration — see issue #10 for the plan and the full mapping of hand-rolled pieces to iii workers.

Which should you use?

For a self-contained demo, learning the patterns, or running locally, the original in-app harness wins — nothing to operate, and the coordination logic is right there in the source. Reach for the iii engine when you want the production properties it adds for free: a policy layer, real budget caps, durable server-side sessions, and tracing — accepting a second runtime to run.

Try both in the app