Current protocol version
The official repository currently publishes 2026-08-11. UHP versions are dates, not semantic versions. A client may send a UHP-Version request header; the server returns the version actually used on every response.
If a client requests an unsupported version, the server is required to fail explicitly rather than silently substituting another protocol version.
Normative chapters
| Chapter | What it defines |
|---|---|
| Architecture | Roles, conformance classes, object model, HTTP transport and authentication. |
| Lifecycle | Version negotiation, capability discovery, task states and session lifecycle. |
| Harnesses | Discovery and management of configured harness objects. |
| Tasks | Task submission, inputs, results, status and continuation semantics. |
| Streaming | SSE event delivery, ordering and replay behavior. |
| Sessions | Listing, inspection, continuity and sharing at applicable classes. |
| Files | Input files, output artifacts, download behavior and container boundaries. |
| Errors | Machine-readable error envelope and codes. |
| Security | Threat boundaries and required protective behavior. |
| Schema | Relationship to generated OpenAPI and JSON Schema definitions. |
Capability discovery first
The discovery endpoint is GET /v1/uhp. It reports supported protocol versions, the default version, conformance class, named capability booleans and optionally implementation identity. Clients should treat missing capability keys as unsupported.
Task states
in_progress ├── completed ├── failed ├── incomplete (budget/time/step limit) └── cancelled
The terminal states are deliberately distinct. An incomplete task is not the same as a failed task, and a cancellation requested by the client should not be reported as a failure. Partial output is retained when a task terminates.
Machine-readable artifacts
The repository contains OpenAPI 3.1 and JSON Schema 2020-12 outputs generated from the protocol source. For implementers, these files reduce ambiguity around object shapes, but they do not replace behavioral conformance testing.
Implementation advice
- Implement discovery and version handling before product-specific convenience APIs.
- Keep server-internal execution mechanisms out of the wire model.
- Test streaming progressively; an SSE response that buffers until completion defeats the contract.
- Preserve stable object scoping and distinguish authorization failures without leaking object existence.
- Run the official conformance suite against a live server, not only schema tests.