Universal Harness Protocol

UHP 1.0 is Luvus’s single public automation protocol. It exposes the complete runtime and terminal state through one method registry, one schema bundle, one event sequence, and one version identity: luvus-uhp 1.0.

UHP 1.0
├── server, config, and events
├── workspaces, tabs, panes, and layouts
├── agents and orchestration
├── terminal inventory, capture, streams, and input
├── files, Git, DIFF, and worktrees
└── modules, themes, bars, docks, and notifications

The Unix socket or Windows named pipe is only the local transport. The private binary protocol used to render attached Luvus clients is separate and is not a harness API.

Discovery

luvus session list --json
luvus uhp schema
luvus uhp capabilities
luvus uhp snapshot
luvus uhp events

uhp.capabilities is the only protocol handshake. It returns the protocol version, methods and contracts, server and event identity, bounded limits, agent authority sources, authorization scopes, and atomic operations. Consumers must use discovery rather than infer support from the Luvus release.

Framing

Ordinary UHP calls use one LF-terminated JSON request and response per connection:

{"id":"1","method":"uhp.capabilities","params":{}}

Requests require a non-empty string id, a known method, and an object params. The optional auth field carries a delegated token. Unknown envelope fields, duplicate keys, invalid parameters, and oversized frames fail before dispatch.

Event subscriptions and terminal observe/control requests turn that one connection into a bounded stream after their acknowledgment.

Identity and concurrency

Workspace and tab IDs survive reorder and restart. A terminal mutation uses:

server_generation + terminal_id + pane_id

This rejects stale servers, replaced PTYs, and obsolete layout routes. Never identify a terminal from its title, prompt text, or tab position.

State results carry revision. A mutation can provide if_revision and will fail with revision_conflict if the server changed first. Compound operations such as agent.start, agent.prompt, workspace.move_block, layout.apply, and diff.note.apply validate and commit atomically.

Events and waits

events.subscribe supports replay with after_sequence. Replay and subscriber queues are bounded. A stale cursor or slow consumer requires a new snapshot.

Prefer events.wait, agent.wait, terminal.backend.wait_change, and terminal.backend.wait_output over polling. Waits are bounded and cancelled when their connection or target disappears.

Security

The local endpoint validates same-user ownership and is the default authority boundary. UHP never opens a TCP listener. Delegated tokens are memory-only, bounded, expiring, and scope restricted.

Terminal and process responses avoid full argument vectors because they can contain prompts, credentials, or tokens. Capture, input, messages, and cwd are also bounded.

See Automating with UHP for a walkthrough and the UHP method reference for the complete namespaces.