harnessclientprotocol

The client half of the Unified Harness Protocol, without the HTTP.

Agent tasks take minutes, arrive as a stream of fragments, and fail in ways that are sometimes worth retrying and sometimes not. This package is the mechanics of getting that right — decoding the event stream, noticing a dropped event, assembling text out of deltas, generating idempotency keys, and classifying failures.

There is no network code here. Give it bytes or events; it gives you facts. Bring your own transport, or use harnessrouter, which is this plus HTTP.

pip install harnessclientprotocol

Decode a stream

from harnessclientprotocol import SseDecoder, TaskAccumulator

task = TaskAccumulator()
decoder = SseDecoder()

for chunk in response:                     # any iterable of body chunks
    for event in decoder.push(chunk):
        task.add(event)
        if event["type"] == "response.output_text.delta":
            print(event["delta"], end="", flush=True)

task.status        # 'completed' | 'failed' | 'incomplete' | 'cancelled'
task.text          # the assistant's text, from the terminal event where available
task.tool_calls    # the tools the agent invoked
task.annotations   # artifact citations — the files it wrote
task.sequence      # (False, [7]) when the stream dropped an event

TaskAccumulator treats the terminal event as authoritative and the deltas as an optimisation, which is the right way round: a dropped connection mid-stream should cost latency, not correctness.

Retry without running the agent twice

from harnessclientprotocol import idempotency_key, is_retryable, backoff_seconds

key = idempotency_key()                    # attach to every attempt of the same task
is_retryable(code="session_busy")          # True  — wait for the in-flight task, then retry
is_retryable(code="quota_exhausted")       # False — nothing changes until the quota does
backoff_seconds(2, retry_after=30)         # 30.0 — the server's own answer wins

Reuse the key across retries. A retry after a timeout without one runs the task a second time, and the first may still be running, editing the same files. It is the most damaging mistake a UHP client can make, and one header prevents it.

Everything exported

Specification

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

Apache-2.0.