Execute work
Negotiate a version, submit input and interpret terminal output.
Task and session lifecycle →Independent developer guide. Not affiliated with HarnessRouter or the official UHP project.
UHP specification: version 2026-09-28
The current normative UHP release is 2026-09-28 Draft, additive to 2026-09-12 and introducing the optional Environments sub-protocol.
Page reviewed 4 Oct 2026 Source and review policy
Find the contract for the operation you are building
Section titled “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.
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
Section titled “Current protocol version”The official repository publishes 2026-09-28 Draft. It is additive to 2026-09-12: existing request and object shapes remain valid, while the optional Environments capability adds reusable, versioned project state.
Environments
Section titled “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
environmentfield 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.
Upstream documentation drift: task field location
Section titled “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-09-28/tasks.md request-fields table still lists a top-level environment row. 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
Section titled “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
Section titled “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,incompleteandcancelled; - unknown request fields are accepted and reported through
metadata.ignored_fieldswhen ignored.
Conformance
Section titled “Conformance”Current package metadata is 2026.9.28.post3. Current executable source contains 85 checks:
- 40 Core
- 9 Extended
- 36 Full
The Environments checks are Full-class and capability-gated. Historical 74/74, 75/75, 76/76 and 84/84 results remain revision-bounded.
Machine-readable artifacts
Section titled “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.