Metadata-Version: 2.4
Name: unifiedharnessprotocol
Version: 0.1.0
Summary: The Unified Harness Protocol (UHP) as data: versions, conformance classes, task states, the streaming event vocabulary, the error taxonomy, and the endpoint map.
Author: HarnessRouter
License: Apache-2.0
Project-URL: Homepage, https://github.com/HarnessRouter/harnessrouter/tree/main/protocol
Project-URL: Source, https://github.com/HarnessRouter/harnessrouter
Project-URL: Issues, https://github.com/HarnessRouter/harnessrouter/issues
Keywords: uhp,unified-harness-protocol,agent,harness,protocol,specification,ai-agents
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# unifiedharnessprotocol

**The Unified Harness Protocol, as data.**

A *harness* is a complete agent runtime — a loop that plans, calls tools, edits files and reports
back. UHP is the HTTP contract for driving one: start a task, follow it, continue the conversation,
cancel it, collect the files it produced.

This package contains no network code. It is the specification's vocabulary in machine-readable
form, so that a client, a server, or a test suite can agree on the strings without each one
retyping them out of the prose and getting one subtly wrong.

```bash
pip install unifiedharnessprotocol
```

```python
from unifiedharnessprotocol import (
    PROTOCOL_VERSION, Events, TaskStatus, ERROR_CODES,
    is_terminal, is_retryable, check_discovery, check_sequence,
)

PROTOCOL_VERSION                          # '2026-08-11'
is_terminal(TaskStatus.IN_PROGRESS)       # False
is_retryable(code="quota_exhausted")      # False — nothing changes until the quota does
```

## What's in it

| Export | What it is |
|---|---|
| `PROTOCOL_VERSION`, `VERSION_HEADER` | The version this package describes, and the header that carries it |
| `CONFORMANCE_CLASSES`, `CLASS_CAPABILITIES` | `core` / `extended` / `full`, and what each obliges a server to implement |
| `CAPABILITIES` | The capability keys of the discovery document |
| `TaskStatus`, `TERMINAL_STATUSES` | `in_progress`, `completed`, `failed`, `incomplete`, `cancelled` |
| `Events`, `TERMINAL_EVENTS` | The streaming event vocabulary |
| `ERROR_TYPES`, `ERROR_CODES`, `RETRYABLE_CODES` | The failure taxonomy and which parts are worth retrying |
| `ID_PREFIXES`, `object_type_for_id` | Which kind of object an id points at |
| `Endpoints` | Every path, so nobody spells one wrong |

## Two checks worth running

**Does the server's class claim match its capabilities?** A class claim that contradicts the
capability list tells a client two different things, and it is cheap to notice.

```python
import json, urllib.request
from unifiedharnessprotocol import check_discovery

with urllib.request.urlopen("http://localhost:3000/v1/uhp") as response:
    ok, problems = check_discovery(json.load(response))
```

**Did the stream drop an event?** `sequence_number` starts at 0 and increases by exactly 1. That
rule exists so a client can tell a lost event from a quiet agent — but only if it checks.

```python
check_sequence(events)     # (False, [7, 8])
```

## Related

- [`harnessclientprotocol`](https://pypi.org/project/harnessclientprotocol/) — SSE decoding, output assembly, idempotency keys and retry policy
- [`harnessrouter`](https://pypi.org/project/harnessrouter/) — the HTTP client and CLI
- [`uhp`](https://pypi.org/project/uhp/) — all three under one import

## Specification

<https://github.com/HarnessRouter/harnessrouter/tree/main/protocol>

Apache-2.0.
