UHP specification: version 2026-10-19

Find the contract for the operation you are building

Use the versioned chapter and machine-readable schema together. Start with discovery and the task lifecycle, then add only the optional surfaces your product needs. Reading every implementation-specific endpoint before selecting a protocol class makes the boundary harder to understand.

Execute work

Negotiate a version, submit input and interpret terminal output.

Task and session lifecycle →

Map operations

Locate discovery, responses, session and file endpoints.

HTTP API map →

Check an implementation

Match the declared class and advertised capabilities to evidence.

Read conformance evidence →

Implementation question	Contract family	Decision to make
What can this server do?	Discovery, versioning and lifecycle	Require a supported version and the capabilities actually needed.
Who owns the loop and continuation?	Architecture, tasks and sessions	Keep the harness’s runtime state behind the execution boundary.
How do inputs and outputs cross it?	Files and artifacts	Preserve authorization, path scoping and result identity.
Can reusable packages or project state be attached?	Plugins and Environments	Gate behavior on discovery; Full class alone does not require optional Environments.
How is behavior verified?	Conformance and security	Use the correct suite/revision; passing tests is not a deployment or security certification.

Keep a small implementation checklist: chosen version, requested class, supported capabilities, task/error states, ownership scope and exact test source. That makes a later version migration reviewable without conflating a HarnessRouter release with a UHP revision.

Current protocol version

The official repository publishes 2026-10-19 Draft. It is additive to 2026-10-04, which is additive to 2026-09-28: existing request and object shapes remain valid, while the optional Memories capability added in 2026-10-04 gives memory that outlasts a session. 2026-09-28 remains the source of the optional Environments capability, and 2026-09-12 the source of Harness Plugins.

Environments

An Environment is a project’s files plus dependencies, built once and mounted read-only into every session that names it. The session working directory remains writable, private and the artifact source.

The protocol adds:

• Environment objects with henv_ identifiers.
• file upload/import, builds and immutable versions;
• an active version pointer and rollback;
• a fixed read-only mount;
• an environment field on harness and session objects;
• a task-side override at metadata.environment;
• Environment-specific errors and capability-gated conformance checks.

See Environments for the dedicated guide.

Memories

2026-10-04 adds the optional Memories sub-protocol: a tree of memories with access granted per node, records that reference one another, recall, and providers that keep the records. A server advertises it with the memories capability; a server that does not implement it is conformant at every class.

The chapter fixes three things and leaves the rest to the provider:

• a memory is a node in a tree of records;
• a grant gives one principal privileges on one memory, and descendants inherit them;
• a harness reaches memory at four moments of a session’s life — prime, tools, observe and consolidate.

See Memories for the dedicated guide.

What 2026-10-19 adds on top of 2026-10-04

The current normative UHP release is 2026-10-19, additive to 2026-10-04 (one rule changes, the rest is additive). The deltas to read first:

• Harnesses §5.3 (delete). A server that reports the new harness_retirement capability true may retire a harness’s sessions and responses with it once a restore window it stated when the harness was retired has passed; a restore inside the window brings them back; a server that reports it false, or says nothing, must keep them, as every earlier version required. The delete response gains sessions: "retired" and restorableUntil. A harness with a task in progress is not retired while it runs.
• Tasks §2.1 (earlier turns). With the input_history capability, the messages before the last user message are the conversation so far, kept as the session’s first turns marked imported: true. Beyond a server’s bound the request is read as without the capability, never refused.
• Harnesses §5.1 (create / update). A field the harness does not have, and a default_model its base does not run, are now 422. Both maintained servers have done this since 2026-10-10 inside the 2026-10-04 spec; this version states it.
• Errors §3.1. model_unavailable (the model the request named cannot be served on this harness) is separate from model_not_available (a harness create or update named a default_model its base does not run). Both are 422.
• Sessions §3. Each turn now carries created_at and completed_at in Unix seconds, with completed_at null while the turn runs or when its end is not known. Added after publication; additive.
• Harnesses §3 (deprecation). The harness models view’s fallback field is deprecated: it only ever repeats default, nothing changes on the wire, and it is removed no earlier than the second version after 2026-10-19. Read default and each model’s available instead. A deprecation is not a removal — a client reading fallback keeps working through 2026-10-19.
• Capability discovery (Lifecycle §2). Discovery now lists 2026-10-19 among the supported versions, alongside 2026-10-04, 2026-09-28, 2026-09-12 and 2026-08-11. A server reports harness_retirement and input_history only when it implements them.
• Harnesses §5.1 (a create’s Idempotency-Key). POST /v1/harnesses takes an optional Idempotency-Key, as a task does. A client whose create answer was lost cannot tell whether its first create reached the server, and without a key its retry makes a second harness. A server that reports the new harness_idempotency capability keeps a create’s key for at least 24 hours in the caller’s scope, answers a repeat with the harness the first request created, waits for it while it is still being created, and refuses 409 with code: "idempotency_key_reused" when the repeat carries a different request. Once the harness a key created is deleted, the key names none and a repeat creates one. A server without the capability ignores the header, as every server did before — an optional request header and a new capability fit within a version under UHP’s versioning rules.
• Tasks §3.2 (asking the person). Added after publication and additive: with the new input_requests capability, a harness that needs one answer — a choice, a confirmation, a value, a secret — ends its turn incomplete with incomplete_details.reason input_required and the question as an input_request item, and the answer is an input_response item on the next task, chained on that response. The turn’s last message carries the question as text too, so a client that renders only message items shows it; and a task chained on a response that ended on a question carries either the answer or anything else, which passes the question over, with the server saying which happened. Three refusals name what went wrong with an answer: input_not_pending (409), input_request_expired (410) and input_response_invalid (422).
• Conformance. The current executable package is 2026.10.19.post5 (41 Core, 9 Extended, 54 Full, 104 total). The F-09 Full check exercises the harness_retirement behavior, the F-10 Full check the create-key contract, on a server that reports harness_idempotency, and the two new T-13 and T-14 checks the asking-the-person flow; the 13 ME- Memories checks are unchanged.

The chapter list still names Architecture, Lifecycle, Harnesses, Plugins, Environments, Memories, Tasks, Streaming, Sessions, Files, Errors, Security, and Schema. Nothing in 2026-10-19 changes the OpenAI Responses compatibility surface or the schema.

Memories

2026-10-04 adds the optional Memories sub-protocol: a tree of memories with access granted per node, records that reference one another, recall, and providers that keep the records. A server advertises it with the memories capability; a server that does not implement it is conformant at every class.

The chapter fixes three things and leaves the rest to the provider:

• a memory is a node in a tree of records;
• a grant gives one principal privileges on one memory, and descendants inherit them;
• a harness reaches memory at four moments of a session’s life — prime, tools, observe and consolidate.

See Memories for the dedicated guide.

Upstream documentation drift: task field location

PR #331 moved the task override from a top-level environment property to metadata.environment. The protocol changelog, generated JSON Schema, Environments chapter, conformance checks and HarnessRouter implementation all use that form.

The current 2026-10-04/tasks.md request-fields table still lists a top-level environment row, unchanged from 2026-09-28. That row is stale relative to the patch sources above. A top-level environment is therefore documented here as an unknown/ignored request field, not as an alternate supported form.

Harness Plugins remain part of the protocol

The 2026-09-12 Harness Plugins sub-protocol remains inherited unchanged. UHP reuses Agent Plugins 1.0.0 packages and capability-gates plugin behavior. See Harness Plugins.

Lifecycle and task model

The core task/session model remains Responses-compatible:

• tasks use POST /v1/responses;
• configured harness selection travels in metadata.harness_id;
• Environment task override travels in metadata.environment;
• session continuation uses previous_response_id;
• task states remain in_progress, completed, failed, incomplete and cancelled;
• unknown request fields are accepted and reported through metadata.ignored_fields when ignored.

Conformance

Current package metadata is 2026.10.19.post5. Current executable source contains 104 checks:

• 41 Core
• 9 Extended
• 54 Full

The Environments checks are Full-class and capability-gated, as are the 13 ME- memories checks that 2026-10-04 adds. A server that does not advertise the optional memories capability is conformant at every class. Historical 74/74, 75/75, 76/76 and 84/84 results remain revision-bounded.

Machine-readable artifacts

The repository publishes OpenAPI and JSON Schema artifacts alongside the prose. For the task Environment field, the current schema is one of the primary pieces of evidence establishing metadata.environment.

Primary sources

• UHP 2026-10-19 directory
• Environments chapter
• Tasks chapter — contains the stale table row
• Protocol changelog
• Current JSON Schema
• PR #331
• Current conformance source