Unified Harness Protocol architecture
The core UHP boundary is simple: a client speaks UHP to a server; the server drives one or more complete harnesses behind that interface. UHP 2026-09-28 retains Harness Plugins and adds optional read-only Environments beside session workspaces.
Page reviewed 4 Oct 2026 Source and review policy
The three roles
Section titled “The three roles”┌──────────┐ UHP / HTTP ┌──────────┐ internal mechanism ┌──────────┐│ Client │ ───────────────▶ │ Server │ ────────────────────▶ │ Harness │└──────────┘ └──────────┘ └──────────┘Client: the product backend, CLI, CI job or another agent that requests work. A conforming client should not need to know how the server launches a harness.
Server: the protocol implementation. It accepts tasks, drives harnesses and translates execution into UHP objects, events and errors.
Harness: the full runtime with its own agent loop, tools and session state. UHP identifies harness families by stable bases such as codex, claude-code and hermes. A harness still calls a model provider underneath UHP; for how the UHP contract relates to a direct model API such as the OpenAI Responses API, see UHP vs model APIs.
Configured harnesses
Section titled “Configured harnesses”Draw ownership before selecting an implementation
Section titled “Draw ownership before selecting an implementation”For a service that edits a repository and returns an artifact, assign each resource to a named owner before writing the adapter.
| Resource or decision | Owner at the UHP boundary | Implementation question |
|---|---|---|
| Task request and selected protocol version | Client + server negotiation | Can the client parse the version actually returned? |
| Agent loop, tool execution and provider calls | Harness behind the server | Which permissions, tools and provider configuration will it actually use? |
| Session continuation and working directory | Server-owned session | Does the client continue the known response instead of assuming a shared new request? |
| Output artifact and authorization scope | Server file/result contract | Can the caller retrieve it without gaining another principal’s data? |
| Reusable built project | Optional Environment | Is the mount read-only and distinct from writable session output? |
Use this as a design review, not a claim that UHP mandates a particular process topology. A queue or remote worker can sit behind the server, but moving execution does not move the client’s authority or remove the need for durable task identity. Review remote execution and managed-runtime attestation when a reachable worker must also prove that it is the intended runtime.
UHP treats configuration as a first-class object rather than assuming that a base name fully defines behavior. A configured harness can combine a base with a default model, instructions, tool restrictions, skills, MCP servers, execution budgets, optional Harness Plugins, and in UHP 2026-09-28 an optional Environment whose built project state is mounted read-only beside the session workspace.
A Harness Plugin is an Agent Plugins 1.0.0 package bound to that configured harness. The package can contribute skills and MCP servers without rewriting the harness’s direct skills or mcpServers fields. See Harness Plugins for the derivation, composition, stdio-MCP and export rules.
The server assigns each configured harness an id that clients use when submitting work.
Object model
Section titled “Object model”| Object | Purpose | Typical lifetime |
|---|---|---|
| Harness | Saved configured runtime, including optional plugin bindings | Until deleted |
| Environment | Built, versioned project state mounted read-only beside a session workspace | Until deleted |
| Response | One atomic task and its result | Server retention policy |
| Session | Chain of responses sharing context and workspace | Until deleted/expired |
| Container | File namespace for a session | With session |
| File | Input or artifact in a container | With container |
| Event | Progress fact in the event stream | Streamed and replayable |
Plugin packages are configuration attached to a harness rather than a replacement for these task/session objects. The server derives plugin manifest/MCP/skill state from the package and combines enabled plugin components with direct harness components at execution time.
Sessions are implicit
Section titled “Sessions are implicit”A first task can create a session automatically. Continuation uses the prior response relationship rather than requiring every client to create a session object before doing any work. A session preserves conversational context, working-directory state and the selected configured harness across tasks.
The specification requires a mismatch to fail rather than silently switching to a different configured harness inside the same conversation chain.
Transport and streaming
Section titled “Transport and streaming”UHP uses HTTP/1.1 or later. TLS is required outside loopback development. Normal request and response bodies use JSON; file upload uses multipart form data; downloads use the file media type. Streaming uses Server-Sent Events (SSE).
This choice keeps the client-facing contract web-native while leaving the server free to run local CLIs, containers or remote execution internally.
Environments and the workspace boundary
Section titled “Environments and the workspace boundary”UHP 2026-09-28 adds an Environment as reusable project state mounted read-only at a fixed path. The session working directory remains writable, private and the source of task artifacts. Harness and session objects carry environment; a per-task override travels in metadata.environment. See Environments.
Conformance classes
Section titled “Conformance classes”| Class | Required surface |
|---|---|
| Core | Discovery, harness discovery, task execution, streaming, continuation, cancellation and errors. |
| Extended | Core plus file input, artifacts and session listing/inspection. |
| Full | Extended plus harness create/update/delete, session sharing and capability-gated Harness Plugins and Environments checks when the server advertises that optional surface. |
Clients are expected to discover capabilities rather than assume optional surfaces exist. A 2026-09-28 server can remain conformant with plugins: false and/or environments: false; capability-gated checks skip rather than pass.
Security boundary
Section titled “Security boundary”Clients authenticate with bearer tokens. UHP requires every object to be scoped to the principal that created it. Cross-principal attempts to read or manipulate another party’s objects should return 404 rather than disclose whether an id exists.
Plugins add another execution boundary: packaged stdio MCP processes execute inside the agent sandbox, and exported packages omit credentials while recording those omissions. See security and Harness Plugins.
Implementation decisions behind the server boundary
Section titled “Implementation decisions behind the server boundary”UHP leaves runtime internals to the server. The following implementation studies help review those internals without promoting a product-specific mechanism to a protocol requirement.
| Failure you need to prevent | Design review |
|---|---|
| A responding worker is mistaken for the intended worker generation | Use managed-runtime attestation to distinguish reachability, identity, durable ownership and readiness. |
| A delegated child can act outside its assigned execution boundary | Review containerized subagents for host-owned approvals, child execution, shared workspace limits and cleanup responsibility. |
| An export exists but omits history before destructive deletion | Apply session export integrity to define content equivalence and place verification and deletion inside one concurrency boundary. |
| A downstream memory mirror deletes a different record from the source store | Review memory mutation identity for exact committed identity, provider delivery and reconciliation limits. |