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.

npm install unifiedharnessprotocol

import {
  PROTOCOL_VERSION, EVENTS, TASK_STATUS, ERROR_CODES,
  isTerminal, isRetryable, checkDiscovery, checkSequence,
} from 'unifiedharnessprotocol';

PROTOCOL_VERSION;                       // '2026-08-11'
isTerminal(TASK_STATUS.IN_PROGRESS);    // false
isRetryable({ 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 one obliges a server to implement | | CAPABILITIES | The capability keys of the discovery document | | TASK_STATUS, 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 of it are worth retrying | | ID_PREFIXES, objectTypeForId | 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.

const discovery = await fetch('http://localhost:3000/v1/uhp').then((r) => r.json());
const { ok, problems } = checkDiscovery(discovery);
if (!ok) console.warn(problems);

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.

const { ok, missing } = checkSequence(events);   // { ok: false, missing: [7, 8] }

Related

• harnessclientprotocol — SSE decoding, output assembly, idempotency keys and retry policy
• harnessrouterjs — the HTTP client and CLI
• uhp-protocol — all three under one import

Specification

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

Apache-2.0.