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.
Configured harnesses
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 and execution budgets. The server assigns it an id that clients use when submitting work.
Object model
| Object | Purpose | Typical lifetime |
|---|---|---|
| Harness | Saved configured runtime | 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 |
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
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.
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 and session sharing. |
Clients are expected to discover capabilities rather than assume everything above Core exists.
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.