A Harness is a native agent engine (Codex, Claude Code, MiniMax Code) that runs the model and tool loop; a Harness adapter translates the Runtime's Executor and Turn contract into that engine's SDK or protocol. The Harness protocol is the contract between the Runtime and the adapter: the adapter interfaces and their lifecycle obligations, the declaration, registration and acceptance. It is for developers who add or maintain a Harness.
| Property | Value |
|---|---|
| Caller | The Runtime (dispatch) |
| Implementations | The Codex, Claude Code and MiniMax Code adapters (Native references). Harness capabilities records what each supports. |
| Code | agent/harness.go: the execution lifecycle, the extension contracts, the protocol errors and the registration methods. internal/harnessconfig/harness.go: the Declaration every Harness provides, the registry of declarations and the shared model configuration contract. |
| Transport | In-process Go interfaces. The Runtime speaks the Core–Runtime protocol to Core. |
| Version rule | A change to the interfaces edits this page and every adapter in one change. |
Ownership
flowchart TB
Core["Core<br/>Session, Turn, immutable configuration, durable events"]
Runtime["Runtime<br/>Executor preparation, reuse, idle expiry, recovery"]
Adapter["Harness adapter package"]
Native["Native SDK, process or connection"]
Core -->|"Core-Runtime protocol"| Runtime
Runtime -->|"Executor and Turn interfaces"| Adapter
Adapter --> Native
| Component | Responsibility | Location |
|---|---|---|
| Core | Public API, authority, durable state, scheduling and configuration snapshots | services/core |
| Runtime | Authenticated connection, shared capability preparation and the common Executor and Turn lifecycle | apps/daemon/internal/dispatch |
| Adapter | Native configuration, resources, API calls, event translation and restrictions | apps/daemon/internal/agent/<package> |
| Harness | Native model and tool loop and history | Pinned SDK or executable |
| Declaration | The Harness's maximum capabilities, placements, configuration and pure admission restrictions, read by Core admission and the Runtime | internal/harnessconfig/<package>/declaration.go |
| Runtime binding | The declaration plus discovery, installed factories and verified capabilities | apps/daemon/internal/agent/<package>/declaration.go |
An Environment supplies execution resources. Managed microsandbox, E2B and OpenSandbox machines and application-owned machines differ in provisioning and connection; the connected Runtime uses this same contract. The daemon runs on Linux, macOS and Windows, managed Providers are Linux-only, and each adapter qualifies its own platforms (self-hosted platforms). Native factories receive capabilities only after the Runtime has loaded the bound installed snapshot (capability preparation). Model providers supply model communication settings, not Turn scheduling or native process ownership.
Steps
- Pin the native source. Set the upstream package version in the declaration's
Nativefield, which the adapter andmake check-harness-catalogread for every other projection of the pin. Record the source revision and document the native entry point next to the adapter. - Implement the adapter in
apps/daemon/internal/agent/<package>, where<package>is the kind without underscores: anExecutorFactory, anExecutorand aTurn(required interfaces, lifetimes). Reuse the shared process, credential, configuration and local workspace helpers. - Write the declaration in
internal/harnessconfig/<package>/declaration.goand bind it to the adapter's discovery (declare the Harness, register the adapter). Runmake generate-harness-catalogto register both. - Package native prerequisites. Add a Runtime image under
services/core/deploy/<kind>and, optionally, native installer participation. - Enable and select the engine with the
OAC_HARNESSESsetting and Harness selection. - Qualify it (qualify the adapter) and record the result in Harness capabilities.
Implement the mandatory text lifecycle and handle every extension explicitly. Qualify supported extensions one at a time; an unqualified extension returns agent.ErrUnsupportedOperation without native effects. A native cancellation may require retirement instead of reuse: Reusable=false carries a reason and the caller must confirm Executor.Close. Do not force reuse to fit a test helper, and do not copy an adapter's native limitations into the shared Core protocol.
Architecture rules
Complexity stays in the adapter and Core assembles, Harnesses run natively apply to every Harness. These rules are Harness-specific:
- Keep required lifecycle declarations, extension interfaces and registration methods in
agent/harness.go. Registry storage and helpers that are not protocol stay in focused files. - Use the existing
proto.SupportedAgentKindandAgentKindCapabilitiesschema. Do not add a second capability descriptor or a combined optional interface. - Onboarding does not require feature equality. Harnesses need not match each other's optional features, and MCP, functions, images or verbosity control are not required to register. Verify the common lifecycle obligations and use the same public assertions for each declared operation. An omitted declaration or a missing extension implementation blocks onboarding; a native difference does not.
- The declaration is the support boundary. An unregistered kind fails closed, and a Runtime heartbeat cannot authorize new public functionality or widen the declaration: discovery may only narrow it. Schema validity, declared support and the available Runtime are independent checks.
- Never equate accepted parameters with applied native behavior.
Required adapter interfaces
agent/harness.go is the interface entry point. The required lifecycle is ExecutorFactory, Executor, Turn (including DurableSteerer and FunctionResultSubmitter) and TurnSettlement. Required methods perform their native obligations; returning Unsupported is not an implementation of cancellation, receipts, settlement or cleanup. Turn extension interfaces stay small and separate, but every public adapter implements each one explicitly. All use the neutral protocol types.
For example, the Codex adapter keeps its app-server and thread, the Claude adapter one streaming Query, and the MiniMax adapter its ACP connection and native session. All expose the same Executor and Turn contract. Native callbacks and resources stay inside the adapter; the Runtime owns admission, idle expiry and replacement. Cancellation targets the exact Turn through agent.Session, and the adapter supplies native completion evidence to the Runtime.
| Interface or contract | Required handling | Obligation |
|---|---|---|
ExecutorFactory, Executor.StartTurn, Executor.Close | Real implementation | Prepare without model input; keep ownership of failed or uncertain resources; confirm cleanup |
Session, Turn, CancellationOutcome, AwaitSettlement | Real implementation | Cancel the exact Turn, keep observed results and confirm settlement independently of cancellation requests |
DurableSteerer | Real implementation on every Turn | Distinguish a complete write from the native application receipt; keep retry identity |
FunctionResultSubmitter | Explicit implementation or Unsupported | Match native call and result identity and acknowledge application |
| Neutral messages, images, MCP, structured output and Subagent observations | Explicit capability decisions | Keep each operation's protocol semantics; reject unsupported input before submission |
Each adapter's contracts.go holds an individual compile-time assertion for each small interface. Do not embed a default implementation that makes future interfaces appear implemented. Adding a contract also requires a classification in the common completeness check and an explicit assertion in every public adapter; the check follows the authored Harness catalog.
For a design-level refusal, implement the method directly:
func (s *Session) SubmitFunctionResult(context.Context, proto.FunctionResultPayload) error {
return fmt.Errorf("%w: native public function tools are not qualified", agent.ErrUnsupportedOperation)
}The reason is a fixed safe string, never submitted content, a credential or raw native diagnostics. Unsupported guarantees no native side effect and is not a successful empty operation. Installation unavailability, unknown call IDs, native failures and uncertain outcomes keep their own errors and ownership. A nil Turn still means that no input was submitted and the output stays with the caller; never use it as an Unsupported marker.
The wire request carries no working directory. The Runtime checks local_environment.workspace_directory against its binding and gives the Harness its bound workspace directory in LocalEnvironment.WorkspaceRoot; run the native Harness there.
The declaration admits public combinations and the Runtime advertises the installed combination; neither replaces schema validation or Project authorization. Native behavior tests must agree with the declarations. An advertised operation that returns Unsupported is a contract violation, never success or grounds for replay.
Executor and Turn lifetimes
| Lifetime | Owner | Ends when |
|---|---|---|
| Environment allocation | Sandbox Provider | Explicit reclamation, coordinated with Runtime execution |
| Runtime connection | Runtime transport | Disconnection or replacement by a newer connection |
| Installed capability snapshot | Runtime | Its Environment is reclaimed; never on Executor close |
| Session Executor | Runtime | Executor.Close on idle expiry, shutdown or confirmed invalidation |
| Turn | Adapter Turn, tracked by the Runtime | AwaitSettlement confirms settlement |
A Session owns one reusable Executor in its connected Runtime; a Turn owns one input execution, its output stream and its cancellation. agent.ExecutorFactory prepares the fixed configuration without model input, and Executor.StartTurn creates a new agent.Turn from the input and the Turn's proto.TurnSettings, without replacing healthy native resources. Normal completion settles only the Turn. Executor.Close releases native resources on idle expiry, Environment shutdown or confirmed invalidation; it releases neither the Environment allocation nor the workspace. Core keeps no second Executor cache. The same lifecycle applies to hosted, self-hosted and none placements.
An Executor moves through these states. Each Turn runs between StartTurn and AwaitSettlement.
stateDiagram-v2
[*] --> Idle: prepared
Idle --> Running: StartTurn
Running --> Idle: reusable
Running --> Closing: not reusable or shutdown
Idle --> Closing: idle expiry, shutdown or invalidation
Closing --> Closing: Close failed, retry
Closing --> Closed: Close confirmed
Closed --> [*]
Binding. The Runtime binds its Executor record to the Session, Environment, connection and immutable execution configuration. Resume identity and prior-Turn recovery flags are continuity assertions, not configuration changes. A supplied native identity must match the retained owner, and when existing history is required, recovery never starts a new root. A configuration conflict is an error, not a hot switch. The one exception is the turn settings the declaration marks changeable (SessionUpdates.Model, ReasoningEffort, ReasoningEffortReset, ServiceTier, and review when Execution.Reviews is not empty): a retained Executor accepts a prepare whose turn differs in those, and StartTurn receives it. An adapter applies a differing turn natively before the Turn's input, or never declares the change. An ordinary lost connection retires its owners and handles; planned suspension retains settled idle owners through exact authenticated resume. Old timers, output and cancellation cannot affect replacement owners.
Per-Turn state. Each Turn gets a fresh wrapper, output channel and receipt state. Steering and function interfaces belong to that Turn. Native callbacks capture the originating Turn before asynchronous work, so a late event is never attributed to whichever Turn is active. Native processes, query or transport connections, fixed capability configuration and native session identity belong to the Executor. Do not reset completed sync.Once values or reuse an old Turn object.
Start. A nil Turn from StartTurn guarantees that no native input was submitted and the output channel was not retained; the Runtime then closes the channel. Once input may have been submitted, return a non-nil Turn even with an error: that Turn owns exactly-once output closure and stays tracked until settlement. Unknown input is never replayed. A definite executor_unavailable Start rejection allows one common recovery attempt, only after the previous Executor has been closed and no input was submitted; the Runtime rechecks the same physical peer and the current authorization.
Cancellation and settlement. Turn.Cancel targets only that Turn and does not close a healthy Executor. AwaitSettlement applies after both natural completion and cancellation. Success means output can no longer be written and the Turn's native events, input, functions and child work have settled. Native completion or cancellation confirmation is independent of resource retirement: closing a transport cannot supply a missing native terminal or operation receipt.
Reusable=truealso confirms that the native owner can accept the next Turn.Reusable=falserequires a reason and a later confirmed Executor close.- An error means settlement is unconfirmed and frees neither ownership nor capacity. Caller deadlines stop the wait, not the tracked cleanup. Retry the same cleanup target serially; a failed cleanup blocks replacement and keeps its resource slot.
Executor.Closeconfirms resource retirement independently of the Turn outcome: an immutable Turn error must not prevent closing the native transport once its work and output have stopped.- Include owned background work in settlement and keep the exact native cleanup target after a failure. Native termination belongs to the adapter; a bulk cleanup acknowledgement alone does not establish quiescence.
- Every
SessiondeclaresCancellationOutcome.Turninherits it. The snapshot keeps observed native identity, Usage and output and remains readable after cancellation. Missing evidence stays unset; an emptyDonePayloadmeans nothing has been observed, not that cancellation succeeded or is unsupported. Reading the snapshot does not wait for settlement. Session.Cancelrequests cancellation; output closure signals teardown. Turn settlement still requiresAwaitSettlementand any requiredExecutor.Close; neither a successful cancellation request nor its snapshot replaces those waits.
What the Runtime does around a Turn. One output consumer starts before native Start, drains the bounded output channel and keeps the terminal observation until Start publication, Turn settlement and admitted operation receipts finish. Natural completion never calls Cancel. Input and function admission close before settlement; operations already admitted hold their barrier through native receipts and outbound acknowledgement. The Runtime sends cancellation to the Turn before waiting on that barrier, because a written input may need a native interrupt to produce its receipt. It joins native settlement, any required confirmed Executor close, output drain and all admitted operations before an applied acknowledgement or reuse, and only then forwards Done or an applied cancellation receipt. A failed Close can report failure while keeping the same Run and outstanding operations for retry; a closed caller wait cannot manufacture an applied input receipt. The Runtime commits native continuity and releases the old Run's admission before publishing Done, since the receiver may start another Turn at once; a late terminal-send failure belongs to the old Run and cannot invalidate a successor that already owns the Executor. Connection shutdown owns transport-loss cleanup. The settlement wait and the receipt send budget are bounded (Timeouts and limits); a timeout is not proof of quiescence.
Events, inputs and optional capabilities
Use internal/agentdaemon/proto for neutral requests, events and receipts. Each Turn emits only its own events with its Run ID, in order, and one terminal outcome. Native IDs and usage are observed, never invented; a missing measurement is unknown, not zero.
Initial input and steering use ordered proto.MessageInput. Keep user-message and content order. Text-only adapters reject images through TextOnly() instead of dropping them; image adapters translate each part natively and acknowledge an active batch only after all its messages are applied. A successful transport write is distinct from confirmed native application. Resume only the exact history bound to the Session; missing, ambiguous or foreign history fails before new model input. Device identity is not native session ownership.
Required and extension operations
The public text path requires durable Turns, applied input receipts, ordered observations, cancellation and enforcement of disabled execution controls; execution.Policy holds the exact requirements. An engine without native tools can guarantee their absence; an engine with tools must actually disable them when asked. Accepting a configuration is not proof of enforcement.
MCP, public functions, deferred function discovery, structured output, image input, verbosity controls and other optional operations need not match another engine. Reject an unqualified combination with Unsupported and record the gap; never advertise a capability to bypass selection.
- Structured output: consume
ExecutionControls.OutputFormatand publish confirmed native output through the Message contract (execution tools). The declaredStructuredOutputcapability admits it; the Runtime advertises its installed capability separately. - Images: declare
MessageImages; the Runtime advertises its installed capability separately (message input). - Workspace placements additionally need verified preparation, workspace reads and output export and the dedicated Runtime binding with the shared Files helpers. Enable a placement only after its lifecycle behavior is demonstrated.
MCP origin and native limits
Declare supported public origins in the declaration's MCPOrigins and bearer support in the MCPHTTPBearerAuth capability. The Runtime advertises its actual HTTP, bearer and required-initialization capabilities. Shared admission validates origin and placement; adapter validation keeps native label, allowlist and initialization limits.
Consume agent.ResolveMCPBindings for public and installed declarations, and keep origin, credential authority, null versus empty allowlists and required startup. Do not copy tokens into native profiles or reinterpret a service request as an Environment request. Reject unsupported native policies instead of dropping them. Follow the MCP origin contract and run public-client, failure, cancellation and cold-recovery qualification for each advertised combination. Model capability is separate from Harness transport support; never infer it from model names or silently degrade input.
Subagent observations
A Harness that supports the Subagent reads implements the neutral observation contract. It reports verified child identity, lifecycle effects and owned Turn and Item history through the authenticated Run and qualifies those facts with real execution, without routes, storage branches or a Harness-specific scheduler. Report unsupported native facts explicitly; completing a child task is not closing its Subagent. Native background work stays owned through settlement and cancellation.
Register the adapter
Registration is static and requires a build. Export one agent.Declaration from apps/daemon/internal/agent/<package>/declaration.go, and run make generate-harness-catalog, which lists it in the generated harnessDeclarations. The binding is the shared harnessconfig.Declaration plus a Discover function. Discovery receives the profile, diagnostic writers and the Runtime-resolved DiscoveryOptions.StateRoot and instance-private DiscoveryOptions.RuntimeRoot, owns native configuration and availability checks, and returns the installed agent.Runtime with its descriptor and Executor factory. Return nil when the adapter is not configured; return an unavailable descriptor without a factory when configured prerequisites fail. Discovery only narrows the declared capabilities with agent.Narrow, never widens them, and an unavailable descriptor comes from agent.Unavailable. Keep version gates and factory-selection conditions inside the adapter.
The Runtime resolves the state directory once and passes it explicitly to every adapter. Adapters that support retained native history place it beneath that root with their own namespaced layout; they do not choose a fallback root from ambient environment or put history in the workspace. An adapter without this capability keeps instance-private native state and must not declare history portable merely because a state root is supplied. Private launch homes, scratch data and instance-private native state use the supplied DiscoveryOptions.RuntimeRoot. One Runtime serves several Sessions in sequence, so every per-Session native state directory (the native history or configuration directory, the launch home and scratch data) lies beneath agent.StateDir(StateRoot, kind, key) or agent.StateDir(RuntimeRoot, kind, key), where key is the request's AgentStateKey. Nothing per-Session lives elsewhere. Device credentials and connection identity stay outside retained state. A state path alone does not qualify native continuation after compute replacement: the adapter must preserve native ownership, reject missing or foreign history before model input, and complete native shutdown before another writer attaches.
cli/agent_registration.go iterates the discovered runtimes and calls Registry.Register from agent/harness.go. It verifies that discovery retained the declared kind and registers the Runtime in this order:
| Order | Method | Registers |
|---|---|---|
| 1 | RegisterKind(proto.SupportedAgentKind, harnessconfig.Configuration) | Kind, availability, version, AgentKindCapabilities and the model configuration declaration. It resets the other registrations, so call it first. |
| 2 | RegisterExecutor(kind, agent.ExecutorFactory) | The Executor and Turn lifecycle used for execution; derives the Preparation capability |
Fill every field of the declaration's proto.AgentKindCapabilities explicitly; Capability declarations defines how declarations are encoded, validated and frozen. An installation probe may withdraw a declared field with agent.Narrow; it never grants one, and Registry.Register rejects a discovery that does. Availability stays separate in SupportedAgentKind.Available. Code that reads a declaration uses IsSupported(); an interface assertion verifies implementation, never support. Every declaration must match the behavior verified for that installation.
The admission mapping is explicit. DurableInputReceipts controls DurableSteerer input and also requires the Turn settlement contract. Workspace reads and writes are served by the Runtime from its bound local workspace, never by the adapter. Workspace declarations describe that resource owner. WorkspaceReadPreparation admits execution_prepare with workspace_read_only. The Runtime readies that preparation itself and serves its reads from the bound local workspace directory without calling the Executor factory, so an adapter declares it only when this kind's Environment workspace is that local directory. Registration does not derive it. Runtime registration does not grant Core admission; the declaration does.
The runnable test-only example testdata/onboarding/main.go registers a text-only synthetic Harness. It shows a Session-owned Executor, fresh Turns, durable steering, cancellation and history binding, and is never shipped.
Declare the Harness
Each Harness is one var Declaration = harnessconfig.Declaration{...} in internal/harnessconfig/<package>/declaration.go. The package name is the kind without underscores. Creating the file registers the Harness: make generate-harness-catalog generates the Core registry, the Runtime's harnessDeclarations, the client identifiers and display names, the Parsar example's protocols and execution options and the registration reference, and make check-harness-catalog rejects stale projections. make openapi derives the Harness enums from the same declarations, so do not add handwritten enums to DTO tags or route annotations. There is no dynamic plugin loader, and a declaration cannot state a machine's availability.
The declaration holds:
- the public
Kindand displayLabel; - the model
Configuration(native model configuration); Capabilities, aproto.AgentKindCapabilitiesthat states the most the Harness can do on a capable host, with every fieldSupportedorUnsupportedand the zero value invalid (Capability declarations);- the supported
Placementsand publicMCPOrigins, whether whitespace-only text is accepted, andMaxInstructionsBytes, the native byte limit on an Agent's instructions (zero declares none), which admission rejects above; Execution, the official execution option values the adapter maps to native settings: web search modes and whether search settings are accepted, reasoning efforts and summaries, service tiers, programmatic-tool-calling values and text verbosities. Core admission and the Runtime reject an undeclared value with the same check (tool policy). Core always sends the official default text verbosity, soTextVerbositiesmust includemedium.Reviewslists the supportedreviewvalues other thannone(onlyauto_review);SessionUpdates, whether the adapter applies a Session update natively between root Turns of a retained Executor:Model,ReasoningEffort,ReasoningEffortReset(null effort) andServiceTier, eachSupportedorUnsupported. Core rejects an update that changes an unsupported setting, and a change to a supported one reaches the adapter in the next Turn's settings;- optional pure restrictions,
ValidateConfiguration,ValidateTools,ValidateMessageInputandValidateFunctionResult, that add native limits to the common checks.ValidateMessageInputruns only for messages that carry images, after theMessageImagescapability check and before anything is stored, and decides whichimage_urlvalues the Harness accepts; Core checks only that the reference is not blank. A nil validator means the common checks suffice. They cannot query business data, decrypt credentials or control native processes. Configuration restrictions run first, and a tool-decoding error precedesValidateTools.
harnessconfig.NewRegistry validates every declaration and panics on an invalid or duplicate one: kinds and labels must be nonempty, placements must list at least one supported placement, MCP origins must be a non-nil list, unknown or duplicate choices and origins without a corresponding placement are rejected, bearer support requires an MCP origin, every SessionUpdates field must be declared, Execution.Reviews may hold only auto_review, and Execution must declare text verbosity medium. Shared dispatch checks capability combinations, never engine names.
The Runtime binding in apps/daemon/internal/agent/<package>/declaration.go embeds the same declaration and adds Discover, which owns native availability probes and factories and only narrows the declared capabilities to what the installation verified. The binding test TestDiscoveryOnlyNarrowsDeclaration checks that discovery never exceeds the declaration. harnessconfig/harnesstest.Declaration builds a synthetic declaration for tests.
Run the harnessconfig and execution tests for validation, combination and error precedence coverage, and the public onboarding tests in services/core/tests/integration for admission and Runtime dispatch.
execution.Policy supplies the registry to HTTP admission, Worker device selection and final dispatch. Custom composition gives the same Policy to api.Dependencies.Policy and the Core dispatcher's Policy. The zero value uses the built-in declarations; an explicitly empty registry authorizes none. There is no mutable global registration.
Native model configuration
internal/harnessconfig/harness.go owns the shared configuration declaration and pure preparation contract. Each declaration carries one Configuration, which Core's composition and the Runtime's RegisterKind both use. The Executor path validates through that declaration before native side effects. The wire object is proto.HarnessConfig. Model execution lists each Harness's accepted fields.
turn.model must not be blank, and an explicit model_provider requires it. The native-owned connection path may leave both out. An explicitly empty declaration accepts no provider or nonempty native parameters and advertises no provider support. Unknown protocol formats and duplicate protocol declarations fail at registration.
The declaration's ordered protocols list is the only source of accepted protocols and the default (the first entry); it also feeds Core's configuration-support descriptor, and Core and Runtime reject unsupported combinations through it. Adapters connect directly through native configuration; they never introduce a model API proxy or protocol converter, a second model capability registry, or capabilities inferred from model names. Claude's private bridge receives compiled native options and performs structural checks only, not a second copy of the declaration's rules.
Native installer participation
An adapter may supply agent.Installation from installation.go in its own package: registered kind, pinned version (read from the declaration's Native.Version), supported platforms, activation environment and a bounded readiness probe. Register it in cli/native_harness.go and add its pinned component to the native distribution builder. This optional contract does not change Executor and Turn semantics. The Runtime owns checksums, copying, locks and additive installation; adapters own native layout and probes. Validate installation and execution on each advertised platform. Missing or incompatible native content fails; it never installs itself during a Turn.
Native process ownership
The daemon's clirunner starts every native child in its own Unix process group (a Job object on Windows); other hosts reject the launch. Explicit and parent-context cancellation share a TERM grace period and a bounded KILL escalation. An internal reaper also cleans remaining group members when the direct process exits, even if a descendant still holds stdout open; during cancellation, surviving descendants keep the remaining grace after the leader exits. The daemon's stop command waits within its limit for confirmed shutdown, which covers that grace period and the pipe and owner cleanup after it.
Owned output pipes stay readable after the leader exits. Consumers drain stdout and stderr before calling Wait, which joins the cached process result and closes the readers. Done reports leader reaping and group cleanup signals; it is not a native execution receipt or proof of persisted history. SDK adapters settle each Turn and drain its observations before publishing completion, and Executor close also closes the query and awaits the native child. Process groups are lifecycle supervision, not isolation or containment of descendants that leave the group.
Adapters run native tools unattended with the launching user's permissions, and a Harness never asks a human. Codex runs with approval policy never, under which it settles MCP elicitation itself without reaching the client, and with full access; under review auto_review every Turn instead sends on-request with the auto_review reviewer, whose denials stay inside Codex, and any request that still reaches the client gets JSON-RPC -32601, a denial; the adapter also disables its blocking request_user_input tool. Claude runs through the adapter's tool callback, which allows or denies without asking; under auto_review it denies every request the native auto mode escalates to a person. MiniMax runs with bypassed permissions; the adapter disables askUser, advertises no elicitation and answers session/request_permission with the ACP cancelled outcome, which MiniMax treats as a denial. No native permission or question request reaches Core: a human in the loop goes through a function tool, the Session reads requires_action and the application submits the function result. Do not add permission profiles, bubblewrap wrappers or native sandbox settings; there is one execution path for every Environment origin. Resource paths are operator configuration, not a permission boundary.
An unreachable model host must not hold a Turn open. The adapter keeps the Harness's own connection retries bounded through native settings, and the Harness's final connection error becomes connection_failed when the Harness reports it as structured data (native failure classification). Core adds no model timeout of its own. Each adapter guide states its Harness's bound.
Network admission follows Restricted network.
Timeouts and limits
The Runtime's per-Turn limits (settlement wait, receipt send budget and output channel) are in the Core–Runtime protocol. The limits on native child processes are:
| Value | Applies to | On expiry |
|---|---|---|
| 3 seconds (default) | The TERM grace period of a native child process on explicit or parent-context cancellation | The Runtime escalates to a bounded KILL. |
| 10 seconds | The daemon's stop command waiting for confirmed shutdown, which covers the grace period and the pipe and owner cleanup after it | Shutdown is not confirmed. |
Qualify the adapter
Before starting, record the operation set, expected results, exclusions and stopping conditions. A qualification ends when its declared operations pass; it does not expand to match another Harness's feature list.
- Contract tests. Call
agent/contracttest.TextLifecyclefrom a test namedTestSharedTextLifecyclewith the adapter's prepared Executor and a deterministic native fixture;claudesdk/executor_test.gois the reference. It checks independent Turn streams, native owner and history continuity, durable write and application receipts, stale cancellation and healthy continuation after cancellation.make check-runtime-contractruns it together with the shared wire, gateway, transport and dispatcher tests and the declaration completeness check. Adapter tests also cover two ordinary Turns sharing one native process or connection and history, cancellation followed by another Turn, stale cancellation and late events, native exit, cleanup failure, input write and application receipts, unknown outcomes and fresh per-Turn usage, function, input and child-observation state. State whether a fixture is controlled or a real provider. - Shared integration.
TestThirdHarnessPublicOnboardingruns the synthetic Harness through public Session and input admission, Worker device selection, the real WebSocket gateway, the daemon Registry and Router, neutral events and durable terminal projection. It uses a custom immutable registry in the sameexecution.Policygiven to the API handler and the dispatcher, and checks applied input receipts, saved native identity, continuation, cancellation, unsupported optional requests and missing mandatory Runtime support. The fixture has no workspace, MCP or public functions, and its registration stays local to the test. It proves the integration path, not native execution. - Real acceptance. Use the pinned official Python SDK and raw HTTP against Core, a real provider API, the native Harness and a dedicated database. Verify initial execution, a warm follow-up, cancellation and restart with continuation; record native owner identity and same-condition cold and warm timing. For workspace placements also verify Files and Artifacts, workspace identity, that no credentials appear in public responses and that foreign history is rejected. Synthetic or failed runs never count. The opt-in tests below run the pinned-SDK fixtures in
services/core/testsagainst a real daemon and model; each runs whenOAC_TEST_OFFICIAL_SDK_PYTHON,OAC_TEST_NATIVE_DAEMON_BIN,OAC_TEST_NATIVE_PROOF_DIRand its private options file are set. The options file is a JSON object with exactlymodelandmodel_provider(the fields ofx_agents_core.model_provider); the test sets it as the deployment default model provider, which the fixtures'environment: noneSessions freeze at creation. - Regression. Existing Harnesses keep working. Run targeted tests, then
make check; runmake openapiafter API changes andmake sqlc-generateafter query changes. - Review. Follow the blind review workflow.
| Operation | Test in services/core/tests/integration | Options file variable, and Harness variable where the test takes one |
|---|---|---|
| Model provider protocols | TestNativeModelProtocolPublicExecution | Model execution |
| MiniMax Code text | TestNativeMCodePublicExecution | OAC_TEST_MCODE_REAL_OPTIONS |
| Message images | TestNativeMessageImagePublicExecution | OAC_TEST_MESSAGE_IMAGE_REAL_OPTIONS, OAC_TEST_MESSAGE_IMAGE_ENGINE |
| Function results with images | TestNativeFunctionImagePublicExecution | OAC_TEST_FUNCTION_IMAGE_REAL_OPTIONS, OAC_TEST_FUNCTION_IMAGE_ENGINE |
| Structured output | TestNativeStructuredOutputPublicExecution | OAC_TEST_STRUCTURED_OUTPUT_REAL_OPTIONS |
| Deferred function discovery | TestNativeToolSearchPublicExecution | OAC_TEST_TOOL_SEARCH_REAL_OPTIONS |
| Disabled web search and programmatic tool calling | TestNativeToolPolicyPublicExecution | OAC_TEST_TOOL_POLICY_REAL_OPTIONS, OAC_TEST_TOOL_POLICY_ENGINE |
Record exact source revisions, native versions and commands with each acceptance result.
Keep provider keys in private operator files, never in commits or logs. Existing focused tests, relative to apps/daemon/internal/agent:
| Boundary | Tests |
|---|---|
| Codex reuse, cancellation and unconfirmed cleanup | codex/executor_test.go, terminal_cleanup_test.go |
| Codex input receipts and strict recovery | codex/function_write_receipt_test.go, function_receipt_test.go, resume_test.go, recovery_test.go |
| Claude input ownership, cancellation and preparation cleanup | claudesdk/executor_test.go, cancellation_test.go, preparation_test.go |
| MiniMax cancellation retirement, failed Start and cleanup retry | mcode/executor_test.go, executor_backpressure_test.go |
| MiniMax native history binding | mcode/session_test.go |
Native references
| Harness | Adapter | Native transport | Runtime guide |
|---|---|---|---|
| Codex | agent/codex | app-server | Codex Runtime |
| Claude Code | agent/claudesdk | TypeScript SDK bridge | Claude Runtime |
| MiniMax Code | agent/mcode | ACP and native workspace companion | MiniMax Code Runtime |