One adapter module per harness, behind one contract

actor

The author of an adapter for a new harness, and the sidecar that drives it.

problem

Harnesses differ in how they start, steer, stop, fail and leave work behind, and the sidecar must stay free of every one of them.

outcome

A harness is added by writing one module that exports a few functions and emits a closed set of neutral events.

value

The mod and the sidecar never change when a harness is added or fixed.

Open questions

• non-blocking · question.capKeyMeaning line 22 · specs/runner/adapter-contract.sdp.md:22 · CONTRACT.md says the cap key names the account a turn spends, while the code keys Codex by one machine-wide bucket named codex and OpenCode by opencode:<provider>, which does not identify distinct accounts.Decider: ownerProvisional: The key is whatever capFor returns; nothing establishes credential identity.
• non-blocking · question.extraArguments line 25 · specs/runner/adapter-contract.sdp.md:25 · The sidecar also passes options to check for a job and options and log to the turn constructor, which CONTRACT.md does not list; OpenCode ignores them.Decider: delegatedProvisional: The contract grows an options argument described by the Relay-compatible job type.
• non-blocking · question.olderDescription line 28 · specs/runner/adapter-contract.sdp.md:28 · Early reports describe a four-method adapter without preparation and reaping; the current contract and code add both.Decider: delegatedProvisional: Only the current contract is described here.

rule line 34 · specs/runner/adapter-contract.sdp.md:34

An adapter module exports capFor, check and one function named create<Harness>Turn, and may export reap and needsModel, and the sidecar finds the constructor by its name.

rule line 35 · specs/runner/adapter-contract.sdp.md:35

The function capFor takes the model and returns a cap key and a default number of concurrent turns, which the user's caps option can replace.

rule line 36 · specs/runner/adapter-contract.sdp.md:36

The function check takes the working directory, model, effort and mode before anything starts, and answers the values the turn will run with, or a refusal that says what would work.

rule line 37 · specs/runner/adapter-contract.sdp.md:37

A mode the harness cannot enforce is refused by check, so no turn runs under a mode that is not enforced.

rule line 38 · specs/runner/adapter-contract.sdp.md:38

The turn constructor returns prepare, run, steer, interrupt and kill, and prepare runs first and names the turn's work as plain JSON before anything executable has been submitted.

rule line 39 · specs/runner/adapter-contract.sdp.md:39

A turn that the harness accepts emits turn once, and before it only status lines about setting up the thread; after it come any of text, tool, status, message and usage. A turn that fails, is refused or is cancelled before the harness accepts it emits no turn. Every turn emits final once, then end once with a status of completed, interrupted or failed, and nothing after end.

rule line 40 · specs/runner/adapter-contract.sdp.md:40

The final event carries the answer exactly as the harness produced it, and usage is the turn's own, not the thread's.

rule line 41 · specs/runner/adapter-contract.sdp.md:41

A steer resolves once the harness accepted the text, rejects when it cannot, and rejects after an interrupt has begun.

rule line 42 · specs/runner/adapter-contract.sdp.md:42

An interrupt resolves once end was emitted, or when the adapter's own confirmation wait runs out with the turn still open, and the end follows only when termination is confirmed. The wait is the adapter's, in phases, and has no single deadline: OpenCode first waits for the turn's startup submission to settle and then confirms for ten seconds, and Codex waits up to three seconds for the stop request, one and a half for the end and eight for its process group, 12.5 seconds in all.

rule line 43 · specs/runner/adapter-contract.sdp.md:43

The end event reports the outcome to the agent and does not free capacity, which comes back only when the turn's work is confirmed ended, by the work's process group or by the adapter's reap.

rule line 44 · specs/runner/adapter-contract.sdp.md:44

An error is null or carries a kind of capacity, rate-limit, quota, auth or other, a message and whether trying later could help, and the sidecar never replays a turn.

11 unkeyed rules.

eventKinds line 48 · specs/runner/adapter-contract.sdp.md:48

turn, text, tool, status, message, usage, final, end.

no citation recorded

errorKinds line 49 · specs/runner/adapter-contract.sdp.md:49

capacity, rate-limit, quota, auth, other.

no citation recorded

workShapes line 50 · specs/runner/adapter-contract.sdp.md:50

{ pgid } for a process group that a guard leads, and any other plain JSON that reap(work) understands.

no citation recorded

turnConstructor line 51 · specs/runner/adapter-contract.sdp.md:51

create<Harness>Turn({ cwd, model, effort, mode, threadId, prompt, emit }) returning { prepare, run, steer, interrupt, kill }.

no citation recorded

Verifier bindings

• test:cc-agents.opencode-suite · the OpenCode adapter against a fake OpenCode service · anchored · test anchor binding present · tests/adapters/opencode.test.mjs:4
• test:cc-agents.sidecar-suite · the sidecar, the Codex adapter, the slots and the guard against a fake Codex app-server · anchored · test anchor binding present · tests/sidecar.test.mjs:4

Requirement drawing

• Declared verifying examples: no declared verifying example.

Decisions

No decision record named.

• impl:cc-agents.codex · the Codex adapter: one guarded app-server per turn, sandbox modes, MCP off · plugin/sidecar/adapters/codex.mjs:15

  Uses

  None.

• impl:cc-agents.opencode · the OpenCode adapter: a session on the user's service, polled by transcript, reaped by lease · plugin/sidecar/adapters/opencode.mjs:26

  Uses

  None.

• impl:cc-agents.sidecar · the per-session sidecar: owns each harness turn, its events and its slot, and drives every adapter through the contract · plugin/sidecar/server.mjs:12

  Uses

  None.

Runtime observation: not tracked.

Runtime observation: not tracked.

Build attestations: not tracked.

Deployments: not tracked.

Bills of materials: not tracked.