Expand description
Unified Harness Protocol (2026-08-11).
embacle already puts twelve CLI harnesses behind one trait, which is what UHP calls a runner. This module serves that catalogue over the protocol’s HTTP contract.
§Why it mounts under a prefix
Both surfaces define GET /v1/models, and the bodies are incompatible:
the OpenAI API answers a flat {"object":"list","data":[…]}, UHP requires
{"backends":{"<id>":{"default":…,"models":[…]}}}. Serving both on one path
would mean content negotiation or breaking every existing caller.
The protocol anticipates this — its published servers: block lists
http://127.0.0.1:3000/api/harness — so UHP is designed to sit under an
arbitrary base path, and the conformance suite takes a --base-url. The
OpenAI surface keeps /v1 exactly as it was.
§What is implemented
Discovery, harnesses and the model catalogue, with version negotiation and
the structured error envelope beneath them. Tasks, streaming, sessions and
files are not yet served; discovery::Capabilities::current reports that
honestly rather than advertising surfaces that would fail on first use.
Modules§
- auth
- Authentication for the UHP surface.
- discovery
- Discovery.
- error
- Errors, in the shape the protocol requires.
- files
- Files a session produced.
- harnesses
- Harnesses and their models.
- invocation
- What a harness’s configuration adds to one task’s runner invocation.
- manage
- Configured harnesses.
- sessions
- Sessions.
- share
- Sharing a session.
- state
- What the UHP routes share.
- streaming
- Streaming a task.
- tasks
- Running a task.
- version
- Version negotiation.
Constants§
- BASE_
PATH_ ENV - Environment variable naming the base path the protocol is served under.
- DEFAULT_
BASE_ PATH - Where the protocol is served when the environment names nothing.