Runtime Adapter Contract
Purpose
Section titled “Purpose”Runtime adapters let Ultimate Harness execute the same mission through different coding agents without changing the mission semantics.
Adapters must provide structured lifecycle reporting. A shell command is not enough.
Adapter manifest
Section titled “Adapter manifest”schema_version: uh.adapter.v0id: hermesname: Hermes Agentversion: 0.1.0runtime_kind: hermescapabilities: interactive: true non_interactive: true structured_events: true sandbox_required: true subagents: true skills: true file_tools: true browser_tools: truesupported_sandbox_backends: - git-worktree - agentfsinput_formats: - uh.mission.v0output_formats: - uh.runtime-result.v0Required lifecycle methods
Section titled “Required lifecycle methods”prepare(mission, sandbox)
Section titled “prepare(mission, sandbox)”Validates mission compatibility, resolves skills/context, checks runtime availability, and returns a launch plan.
launch(prepared_mission)
Section titled “launch(prepared_mission)”Starts the runtime session and returns a runtime_session_id.
observe(runtime_session_id)
Section titled “observe(runtime_session_id)”Returns structured events: status, logs, tool calls, file changes, questions, blockers, and partial artifacts.
send(runtime_session_id, message)
Section titled “send(runtime_session_id, message)”Optional for interactive steering. Must record steering messages in the audit trail.
collect(runtime_session_id)
Section titled “collect(runtime_session_id)”Collects final artifacts: summary, changed files, diffs, logs, generated docs, verification suggestions, and open blockers.
cancel(runtime_session_id, reason)
Section titled “cancel(runtime_session_id, reason)”Stops a running mission safely and records partial state.
close(runtime_session_id)
Section titled “close(runtime_session_id)”Releases runtime resources and finalizes session metadata.
Runtime result shape
Section titled “Runtime result shape”schema_version: uh.runtime-result.v0mission_id: mission-2026-05-13-docs-spineruntime: adapter_id: hermes session_id: hermes-session-abc123status: passed # passed | failed | blocked | cancelledsummary: "Created documentation spine."artifacts: - path: docs/architecture/runtime-adapter-contract.md kind: documentation status: createdchanges: diff_ref: .harness/missions/mission-.../diff.patch files_changed: - docs/architecture/runtime-adapter-contract.mdchecks_suggested: - markdown-link-check docs/**/*.mdblockers: []logs: - .harness/missions/mission-.../runtime.logNative process supervision and accounting
Section titled “Native process supervision and accounting”OMP and Command Code use UH’s shared process runner. Configure limits in the
adapter’s config.runtime_config.limits or a mission’s
runtime_config_overrides.limits:
limits: timeout_ms: 1800000 startup_timeout_ms: 120000 stall_timeout_ms: 300000 max_output_bytes: 67108864The combined stdout/stderr capture limit defaults to 64 MiB even when omitted.
Crossing it stops the owned process tree with stop_code: output_limit; the
crossing chunk and later chunks are not captured. Previously admitted bytes
remain in the durable logs and adapter output. This is a failed, incomplete run,
not a successful truncated response. Output-limit failures do not automatically
resume under the bounded recovery policy.
Windows runs use a native Job guardian that outlives the controller, terminates the owned tree on controller loss, and records whether settlement was confirmed. A Job provides process ownership and optional committed-memory limits, not filesystem or network isolation. A stale heartbeat alone does not prove process termination. Local cancellation and saved-session recovery reconcile confirmed controller-loss receipts with canonical session/result/index artifacts.
On Windows, canonical artifact transactions use a kernel-owned named pipe keyed
by the canonical local artifact path. Controller death releases ownership without
PID guessing or stale-lock deletion. Acquisition remains bounded at ten seconds.
Legacy .lock files are retained and block updates pending owner reconciliation;
do not mix controllers from before and after this lock-protocol change. Other
platforms retain the bounded filesystem lock and fail closed on abandoned locks.
These are local-machine locks, not distributed coordination for shared storage.
Hermes CLI execution and OpenSandbox command templates also reuse the owned
runner for bounded capture and process-tree timeout settlement. On Windows,
explicit .js/.mjs/.cjs CLI entrypoints execute through Node. OpenSandbox
templates retain POSIX quoting: UH locates a native shell from Git for Windows,
or accepts an explicit executable through UH_OPENSANDBOX_SHELL; it does not
interpret those templates with cmd.exe or silently choose WSL. Local shell
fixtures do not establish an OpenSandbox provider or container-isolation claim.
Artifact writes reject observed symlinks and junctions at the target and its
ancestors through .harness, including a run directory replaced after launch.
These filesystem checks do not replace an OS isolation boundary.
Finalized lifecycle events use the Observatory’s existing artifact-age freshness policy; they are not permanently labeled fresh. Aging evidence does not turn a confirmed failed or completed operation back into an active process.
Recovery accounting follows runtime-recovery.json source attempts and counts
each canonical attempt once within its artifact root, including failed attempts.
Team parents aggregate each worker’s independent canonical artifact root; product
worktree cleanup does not remove those receipts. Missing attempt receipts or
unreported counters make the corresponding total unknown, never zero. Mixed
providers/models can still have a known combined USD amount without a fictitious
single-model attribution.
Optional cost_basis distinguishes runtime_estimate, configured_estimate,
provider_reported, and mixed. Native OMP cost figures are runtime estimates,
not billing receipts. Observatory labels costs as reported only when explicitly
backed by provider_reported; otherwise known costs are labeled estimated.
HTTP adapters preserve reported counters in canonical results and leave absent
usage unknown rather than estimating it from prompt or response length.
Native route and trust policy
Section titled “Native route and trust policy”OMP uses a mission’s runtime_config.model before the adapter’s default_model.
A qualified provider/model selects both route components; otherwise
default_provider supplies the provider when configured. Use exact native model
identifiers, not fuzzy aliases, for an assigned route. Text mode is rejected when
an OMP route is assigned because it cannot supply structured route evidence.
Command Code requires an explicit model identifier.
The native runner records expected_route. An observed assignment mismatch
stops the owned process tree with route_mismatch. Completion without the
required native route evidence fails with route_unverified; requested settings
and session banners do not count as observations. Neither stop permits saved-run
recovery. Collectors also reject mismatched or unverified route results.
These checks consume runtime-produced events: they do not guarantee that the provider’s first request has not already happened. They are not a provider authorization firewall or a filesystem/network sandbox.
UH adds Command Code’s -t auto-trust flag only when
runtime_config.trust_workspace: true; it no longer adds it unconditionally.
Operator-supplied cli_args remain part of the trusted executable configuration,
not an OS security boundary. The unsupported native worktree_mode setting is
rejected by both adapters; workspace isolation belongs to UH’s existing backend.
Configured Command Code prices
Section titled “Configured Command Code prices”Command Code accepts optional runtime_config.pricing (also supported through
mission overrides). Supply explicit USD-per-million rates and the counter overlap
semantics for the assigned model. The following numbers are synthetic examples,
not a model catalog or current provider prices:
pricing: model: fixture/model input_usd_per_million: 1 output_usd_per_million: 2 cache_read_usd_per_million: 0.1 cache_write_usd_per_million: 3 input_includes_cache_read: true input_includes_cache_write: trueAn estimate requires a terminal receipt, complete input/output/cache counters,
and exactly one observed model matching the price entry. Missing counters,
truncated output, absent terminal evidence, mixed models, or impossible cache
overlap leave the estimate unknown. Raw partial usage events remain available.
No default model prices, cache-write assumptions, or suffix-based model aliases
are substituted. The rate snapshot is retained in the canonical session/result,
and computed costs carry cost_basis: configured_estimate. Neither this estimate
nor the router’s broad cost classes establish actual billing.
Capability model
Section titled “Capability model”Adapters should declare capabilities rather than relying on implicit behavior:
structured_eventsinteractive_steeringnon_interactive_runskillssubagentsbrowserterminalfile_toolssandbox_nativejson_outputdiff_output
Mission packets may declare capabilities: [...] using the same ids.
uh mission dry-run, uh mission run, and uh mission run-all enforce
the selected runtime adapter’s declared capabilities before dispatch.
Since v0.10.0 (UH-138) a mismatch emits a [WARN] per unmet tag and the
run proceeds; pass --strict to treat mismatches as a hard error, or
--force to bypass the check entirely (it prints a [WARN] line saying so, so
a bypass is never silent). Missions without capabilities
preserve the legacy no-op behavior. This is distinct from
runtime_requirements, which are typed preconditions and always hard
errors (never relaxed by warn mode).
Adapter responsibilities
Section titled “Adapter responsibilities”Adapters must:
- Refuse missions requiring unsupported capabilities.
- Preserve mission IDs in prompts/logs/results.
- Avoid writing directly to canonical state unless promotion policy explicitly allows it.
- Return enough evidence for verification and review.
- Separate runtime errors from mission failures.
- Capture user/human steering as audit events.
Adapter non-responsibilities
Section titled “Adapter non-responsibilities”Adapters should not:
- Decide product scope.
- Rewrite specs without a workflow step.
- Promote changes without approval.
- Invent undocumented entity names.
Runtime-final-message capture protocol (UH-28)
Section titled “Runtime-final-message capture protocol (UH-28)”Every adapter participates in a uniform protocol for capturing the
mission’s final summary message into runtime-final.txt:
Prompt-side contract
Section titled “Prompt-side contract”The harness appends the following instruction block to the mission
prompt before handing it to the runtime (runtimeFinalMessageInstruction()
in src/harness/runtime-final-message.ts):
## Runtime final message
At the very end of your response, emit your one-paragraph summary insidea fenced code block tagged `uh-runtime-final-message`:
```uh-runtime-final-message<one-paragraph summary of what you did, what changed, and any caveats>This fenced block MUST be the last block in your output. The harness
extracts its content verbatim into runtime-final.txt.
### Extraction-side contract
Each adapter calls `extractRuntimeFinalMessageSentinel(text)` over thecaptured model output and writes the matched content into`runtime-final.txt`. When the sentinel is absent, the adapter falls backto its runtime-native capture path (see table below).
The extractor:
- Matches `` ```uh-runtime-final-message ``` `` fenced blocks anywhere in the captured text.- Returns the LAST occurrence (a mission may emit interim drafts; only the terminal block is authoritative).- Tolerates CRLF line endings, leading/trailing whitespace inside the fence, and optional spaces after the opening tag.- Returns `null` when no sentinel block is present.
### Per-adapter resolution
| Adapter | Sentinel scan target | Fallback when sentinel absent ||-----------|------------------------------------------------------------|---------------------------------------------------------------|| codex | Content of `--output-last-message` file (raw text) | Raw file content (Codex's native final message) || oh-my-pi | Last assistant text decoded from native messages and typed content arrays | Last decoded assistant text || hermes | Hermes stdout text | Empty file (Hermes does not produce a native summary today) |
### Status semantics
- The sentinel does NOT change `runtime-result.status`. Status remains driven by exit code, runtime-native signals (Codex's `--output-last-message` presence, Hermes' `uh.runtime-result.v0` block, oh-my-pi's native terminal errors and non-empty final message).- A mission may emit a runtime-result `status: passed` even when the sentinel is omitted, as long as the runtime-native fallback path satisfies the adapter's success criteria. The sentinel is the *preferred* summary source, not a *required* one.
### Native OMP facts and sandbox artifacts
Sandbox execution and canonical artifact persistence are separate boundaries.OMP runs and product diff capture remain in the selected sandbox; the CLI publishesrun events and terminal artifacts under the host mission so existing readers canobserve progress before exit. Publishing those facts does not promote productchanges. An active run takes precedence over an older terminal result in theObservatory.
Cancellation settles the selected run's result, runtime session, and index evenwhen its event log cannot be appended. Mission mirrors and the latest pointerchange only when they still identify that run; cancelling an older run preservesnewer run facts. Cancelled results use `cancelled`, while runtime sessions use`failed` with the signal exit code. Initial OMP event persistence failure likewisesettles writable terminal artifacts without starting the child.
Usage totals come from completed native assistant messages, not repeated progressor final-envelope copies. Explicit message identities take precedence overtimestamp/content deduplication: distinct identities count independently.Missing measurements remain unknown. Reported cost is runtime evidence, notproof of an invoice or subscription charge. Structured terminal errors fail therun even after assistant output. Public failure summaries and Observatoryprojections must not expose raw prompts, tool payloads, credentials, or transcripts.
### Why a single shared protocol
Before UH-28 each adapter rolled its own final-message capture:Codex used a side-channel file, Hermes had no `runtime-final.txt` at all,oh-my-pi did a JSON heuristic. UH-28 lets missions explicitly bound thesummary independent of runtime quirks, which:
1. Makes the summary deterministic across runtimes for cross-runtime QA comparisons.2. Removes the need for adapter-specific prompt instructions (each buildMissionPrompt now appends the same sentinel block).3. Lets the harness add structured terminal annotations in the future (e.g. `uh-runtime-blockers`, `uh-runtime-next-steps`) using the same extraction pattern.
## Independent review packets
`uh mission review-prepare <id> --sources <json> --runtime <runtime> --model <model>`emits a normal UH mission without starting a model. Sources are an array of`{"missionId":"worker-a","workspaceRoot":"optional explicit output workspace"}`.Without an explicit workspace root, preparation uses the source mission's boundworkspace. It captures the complete canonical contracts and every declared output,records missing files, and applies the same nonempty-file, JSON, and completionmarker checks as ordinary mission verification. Existing packets are not overwritten.
The request and captured files carry SHA-256 digests. Reference paths retain theirsource-workspace meaning; snapshots define the point-in-time review, not subsequentsource changes. Preparation does not copy credential stores or create a secondcontroller. Operators remain responsible for the sensitivity of declared inputs.
Create a separate workspace with`uh sandbox create <workspace-id> --mission <review-id> --backend directory`.After authorizing the model execution, run the emitted mission with the assignednative runtime through ordinary `uh mission run`. OMP and Command Code enforce theassigned runtime/model and refuse resumed reviewer sessions. OMP review disablesHoncho memory, extensions, and skills; Command Code review rejects free-form runtimearguments that could override the session contract. The canonical mission must matchits workspace copy. These are assignment and workspace guards, not OS filesystem ornetwork isolation guarantees.
`uh mission review-collect <id>` requires a successful native execution receipt boundto the request and an intact request/input snapshot in both canonical and executionworkspaces. Every source, acceptance criterion, and required check must appear exactlyonce. Missing or invalid outputs require `needs-remediation`; unverified or contradictedevidence cannot receive `pass`. Ordinary `mission verify` includes these checks andrefuses a workspace mutation that removes the review contract or changes its policy.
The resulting `review-assessment.json` is advisory and always records`human_acceptance_required: true`. It neither records an owner verdict nor promotessource work. A successful review mission means the assessment is valid, not that itssource work passed review. Local fixture execution verifies this lifecycle withoutclaiming model-review quality or provider/OS isolation acceptance.