# ADR 0130: A headless harness composes the Agent runtime

> Source: https://github.com/max-listov/stitchkit/blob/master/docs/decisions/0130-headless-harness-composes-the-agent-runtime.md

---

# ADR 0130 — A headless harness composes the Agent runtime

## Context

The Agent runtime already owns durable admission, queueing, interruption, checkpoints, recovery,
tool fencing and terminal settlement. A reusable headless session also needs model resolution,
instructions/skills/resources, prompt budgets and a concrete tool profile. Leaving that composition
only in an example makes every host copy it; turning it into a daemon or another loop would split
the canonical state machine and absorb deployment policy into the framework.

Coding sessions additionally repeat file and process tools. A generic command gateway would erase
the direct operation identities and an implicit workspace or environment would grant authority the
framework cannot infer.

## Decision

Publish `stitchkit/agent-runtime/harness` as an evolving server-only facade over exactly one
`createAgentRuntime`. The caller supplies the store, protocol, per-run model resolver, resource
loader, direct tools and prompt-budget policy. Resources are typed and bounded before the provider
step. An observation-only applied-profile event records the actual model descriptor, resource
provenance and direct tool names without content or credentials. SQLite integration is composition
through the existing Bun and Node store leaves, not a harness-owned database.

Publish `stitchkit/agent-runtime/coding-tools` as a separate evolving server-only leaf. It produces
ordinary named runtime tools for bounded UTF-8 file read/write/edit and shell execution. Every
effect requires a host authorization decision. Paths are relative to an absolute root and checked
after realpath resolution; write/edit reject symlink targets. Shell receives an executable alias
from a finite host map and an argument array, inherits no environment implicitly, and has explicit
argument, output and timeout bounds. This root is not claimed to be an OS sandbox.

The framework owns no executable process, restart policy, control transport, workspace discovery,
credential resolution or application model catalog. Provider adapters stay caller-supplied, so a
model/provider switch does not require a new harness. Deferred catalogs compose through the
existing direct-activation surface; selected calls retain their actual tool identities.

Recovery remains the Agent runtime's explicit evidence policy. Completed history is read from the
canonical store and never blindly replayed. Idempotency of effects outside that store remains an
application transaction keyed by stable run/call identity.

## Consequences

- External supervisors can share one supported execution facade without adopting a framework
  daemon or duplicating the durable loop.
- Contract-only consumers load neither entrypoint; coding tools are isolated from the `ai` peer.
- Resource trust, executable authority and OS isolation remain visible host decisions rather than
  permissive defaults.
- The facade remains evolving until independent consumers prove its composition boundary.