Extend a coding harness

When to use thisCopy Anchor Link

Read this if you want to put another coding agent, such as a vendor CLI or an open-weight loop, behind Numinance, or if you want to know precisely what an adapter is allowed to claim. The adapter is the least trusted piece in the architecture: it runs a model-driven process and reports on it. Everything it says is a claim. See Harnesses vs runtime for the product-level split.

PrerequisitesCopy Anchor Link

• The plugin lifecycle and the custom plugin walk-through. An adapter is a plugin whose port is authorexecutor.
• Familiarity with Agent harnesses.
• You cannot run an adapter end to end without the proprietary engine, which supplies the sandbox, the egress proxy and the broker. What you can do in the open tree is read the contract, validate the shapes, and run the offline stream rules.

The mechanismCopy Anchor Link

The execution context is the only caller. It dispatches one Execute per run of one work unit, inside a disposable work-unit sandbox, as an author-agent run. A reviewer-agent run goes through the same port but is read-only, and the host refuses every other actor kind.

The port, exactlyCopy Anchor Link

The service has three RPCs.

service AuthorExecutorService {
  rpc Capabilities(CapabilitiesRequest) returns (CapabilitiesResponse) { /* RISK_CLASS_READ */ }
  rpc Execute(ExecuteRequest) returns (stream ExecuteResponse)       { /* RISK_CLASS_MEDIUM, EXEC_MODE_OPERATION */ }
  rpc Plan(PlanRequest) returns (stream PlanResponse)                { /* RISK_CLASS_READ, EXEC_MODE_OPERATION */ }
}

• Capabilities returns the ExecutorCapability values the adapter claims. The host calls it just before Execute and keeps the answer for that run only. The router reads the ExecutorManifest pinned in the lockfile, never this answer, and an answer that names a capability the pinned manifest does not declare is a provider fault.
• Execute runs the harness for one run of one work unit and streams ExecutionEvent messages. It is MEDIUM because the harness writes only inside the sandbox; the decision for a dispatch takes the higher of MEDIUM and the risk of every granted credential intent and egress destination.
• Plan runs the harness read-only, in state Classified, before any plan exists. It streams the same events in PlanResponse. An adapter that serves it claims STRUCTURED_PLAN.

The request: what the host gives the adapterCopy Anchor Link

ChangeExecutionRequest is everything a run is given. Nothing in it is advisory.

Payloads carry references and digests, never file contents, prompt text or credential material. The adapter fetches the task or the plan by reference, and the host checks plan_ref.sha256 against ActionContext.plan_digest.

The response: the canonical event streamCopy Anchor Link

An adapter maps whatever its CLI emits onto these events. A stream holds 1 to 1023 events; the first is EXECUTION_STARTED at sequence 1; sequences are consecutive; the last, and only the last, is EXECUTION_COMPLETED or EXECUTION_FAILED; each message is at most 32 KiB.

Events carry a subject only for specific types (a tool name, a path, a credential intent) and references that point at content such as a diff or a test report, never the content itself. The subject is untrusted: the host rejects a FILE_CHANGED path outside allowed_paths or absent from its own diff of the worktree.

On the plugin protocol each event rides one RUNNING Invoke message, and the terminal Invoke message is SUCCEEDED after EXECUTION_COMPLETED and FAILED after EXECUTION_FAILED. sdk/go/ports/authorexecutor provides NewExecuteRule and NewPlanRule, which check exactly those stream rules offline, and ValidatePlanRequest for the planning request bounds.

The mapping, in proseCopy Anchor Link

An adapter for a native CLI typically does five things, in order:

1. Translate the grant. Turn allowed_capabilities, allowed_paths and the tool inventory into the CLI's own allowlist, configuration and instruction files. This is telemetry and convenience. The deny that counts is enforced by the broker, the egress proxy and the read-only filesystem, not by the CLI's settings.
2. Start the CLI inside the sandbox with the pinned model, using the CLI's streaming protocol.
3. Map its events. Each tool call becomes TOOL_INTENT, then the broker's answer arrives as TOOL_ALLOWED or TOOL_DENIED, then TOOL_RESULT. Commands, file changes and test runs map to their own types. Anything the adapter cannot place is dropped, not guessed.
4. Route permission prompts to the broker. The CLI asks to run a tool; the adapter forwards that to the host's permission path and returns the decision.
5. Emit one terminal event and stop. Never emit events after it.

The designed adapters follow this shape: fake is an in-process deterministic executor that applies scripted diffs for lifecycle tests, claude-cli supervises the Claude Code CLI, and codex-cli supervises the Codex CLI. All three are designed. Their ids appear in specification examples (the ExecutorManifest example binds dev.numinance.official/claude-cli), but there is no adapter source in the open tree and nothing resolves those ids.

The manifest the router readsCopy Anchor Link

The adapter is selected through an ExecutorManifest pinned in the lockfile. The shipped example:

apiVersion: numinance.dev/v1
kind: ExecutorManifest
metadata: {name: claude-cli-bedrock, scope: SCOPE_ORG}
spec:
  provider: dev.numinance.official/claude-cli
  capabilities: [EXECUTOR_CAPABILITY_FILESYSTEM_READ, EXECUTOR_CAPABILITY_FILESYSTEM_WRITE, EXECUTOR_CAPABILITY_SHELL, EXECUTOR_CAPABILITY_SUBAGENTS,
    EXECUTOR_CAPABILITY_MCP, EXECUTOR_CAPABILITY_STRUCTURED_PLAN, EXECUTOR_CAPABILITY_APPROVAL_CALLBACKS]
  models:
    - {id: eu.anthropic.claude-sonnet-v1:0, max_context: 200000}
  cost_class: EXECUTOR_COST_CLASS_MEDIUM

This validates with numi validate --files as an example document. It declares capabilities and models; it declares no residency, because the residency field is deliberately held back for a later minor. The provider id here is an example shape, not an installable adapter.

Residency is derived, not declaredCopy Anchor Link

Where data goes has more than one dimension, and a cloud's name settles none of them:

A ResidencyPolicy sets floors (IN_ACCOUNT, PRIVATE_ENDPOINT, VENDOR_ZDR, ...) plus regions, cross_region, retention_max and training_use. The class that is compared with the floor is derived from the live runtime configuration at Change start, not copied from a static manifest. Until the manifest carries residency fields, a manifest that cannot be checked against a floor fails it.

"On AWS" and "through Bedrock" are therefore not IN_ACCOUNT. A model reached through a cloud provider can still run in another region, retain prompts, or be reached over a public path. The class is whatever the dimensions add up to, and a mismatch with the floor refuses the Change before work starts. An adapter must never write a residency claim into its own events as if it settled the question; ActionContext.residency is informational, host-derived, and never a grant.

ConformanceCopy Anchor Link

The authorexecutor kit is a written list of cases, not a runnable harness. CORE-001 to CORE-018 cover Capabilities, Execute and bounds; the live cases (egress to link-local and metadata addresses, credential intents outside the grant, deadline enforcement, a planted canary secret, inference endpoint overrides) need a real sandbox, proxy and broker. HOST-001 to HOST-014 describe what every host does with a request and with a provider's answer: a stream whose first event is not EXECUTION_STARTED is rejected, a TOOL_ALLOWED for a denied intent grants nothing, a second Execute with a used run_id is not dispatched, and a reviewer-agent run with write capability is refused.

What runs today, offline, is the stream half of PLAN-001/PLAN-002 and PLAN-003 through NewPlanRule and ValidatePlanRequest. Until the plugin host work lands, treat full adapter conformance as designed.

Failure modes and safeguardsCopy Anchor Link

Next stepsCopy Anchor Link