Docs · Internals
One contract for every coding agent
Project Orchestrator reaches Claude Code, an OpenAI-compatible model, Codex or any ACP agent through the same small set of types. This page walks through that contract, which lives in the nexus SDK.
What it does
The backend never speaks a vendor protocol. It opens a session on a provider and reads a stream of neutral events.
Each provider declares what it can do, model by model. When a capability is missing, the contract applies a written fallback or answers Unsupported, never a silent success.
Permissions, errors and resume tokens have neutral shapes too, so the dashboard shows the same cards whichever agent runs underneath.
The diagram
Drag to move. Pinch, Ctrl + wheel or the + and - keys to zoom; arrow keys to move; 0 to fit; double-click to fit. Select a node to light up its links.
Text description of the diagram
Flow diagram. The backend ChatManager asks the ProviderRegistry for a provider. The registry keeps model providers apart from harnesses and checks the pair before any launch. An AgentProvider opens or resumes an AgentSession. The session produces AgentEvents, applies a ToolPolicy, and reports ProviderErrors. The provider exposes Capabilities per model and the session can emit a ResumeToken. At the bottom, the older Claude Code client types are mapped onto the neutral ones.
Guided reading
Step 1. One registry
A single ProviderRegistry in nexus maps an instance id to an AgentProvider, built on demand and cached. Instance configuration holds no secret, only a reference: vault:name, env:VAR or none. The built-in claude-code instance cannot be removed, and a changed configuration reloads without disturbing sessions already open.
Step 2. Harness and model are paired, and the pair is checked
A model provider is kept apart from the harness. Before anything launches, open_session checks that the harness consumes the protocol the model provider speaks (anthropic_messages, openai_chat or openai_responses). A mismatch is refused with model_protocol_mismatch.
Step 3. AgentProvider
A provider exposes its id and kind, a health check that returns a value instead of failing, the model catalog, the capabilities of a given model, and open or resume to create a session.
Step 4. AgentSession
A session drives the conversation: send_turn, answer_permission, answer_question, interrupt and cancel_tools with a scope, set_model, set_policy_mode, out_of_band and close. A turn ends with exactly one terminal event, Done or Error.
Step 5. The neutral types
AgentEvent has 17 variants. ToolPolicy combines a mode with allow and deny lists, and deny wins. Capabilities has 18 fields per model, each with a written fallback. A ResumeToken is opaque to everything except the provider that issued it. ProviderError has 17 kinds; each knows whether it is retryable, and its details are redacted.
Step 6. What the contract wraps
The boxes at the left are the code that existed before: the Claude Code client, its messages, permission modes and errors. Each one maps onto a neutral type, which is how the first provider was written without changing what the dashboard receives.
Why it is built this way
Refuse rather than pretend
A missing capability returns Unsupported or applies the written fallback. A provider that cannot cancel tools says so. The contract never reports a success that did not happen.
Deny wins, and a malformed rule is an error
In a ToolPolicy a deny always beats an allow. A malformed pattern or an unknown mode fails at construction: a deny rule silently dropped would widen the policy.
A version you can test
CONTRACT_VERSION goes up whenever a serialised shape or a trait signature changes. JSON snapshots in the tests carry the version, so changing a shape without bumping it fails the build. The constant reads 3 today, and the bumps so far were additive.
No secret in configuration
Configuration carries references only. The credential resolver turns vault:name into a secret at the last moment. A locked vault answers credentials_locked instead of falling back to another provider, and error messages never repeat an identifier.
One turn at a time
send_turn during an active turn returns turn_in_progress. There is no hidden queue and no implicit interruption: queueing stays in the backend.
What is not established
- Model binding is not applied to Codex (its custom-provider configuration has not been checked against a real app-server) nor to ACP (the agent chooses its own model). No real third-party gateway has been tried.
Public sources
Where to check each statement, in the public repositories.