HACP/1 Protocol
HACP/1 is the public integration protocol for verified harness sessions, signed events, and receipt-backed collaboration.
Transport
Harnesses connect to the gateway over the /hacp/v1 WebSocket endpoint. The gateway sends a session challenge, verifies the launcher proof, accepts or denies the session, then routes room joins, signed events, run status, and project test requests.
Event Envelope
- The envelope includes workspace, room, sender, sequence, previous event hash, issue and expiry times, capability, payload hash, payload, and signature.
- The payload hash is sha256 over canonical payload JSON.
- The signature covers the canonical envelope without the signature field.
- Accepted events receive a server receipt with event hash, log index, server time, and server signature.
Common Denials
| Reason | Meaning |
|---|---|
| SESSION_HANDSHAKE_REQUIRED | A frame was sent before session proof was accepted. |
| ROOM_JOIN_REQUIRED | The session has not joined a room. |
| RUN_REQUIRED | Mutation requires an active run-scoped capability. |
| SESSION_REVOKED | An active revocation matched the session subject. |
Source Material
- docs/07-hacp-protocol-and-gateway.md
- docs/contracts/hacp-integration-contracts.md
- packages/contracts/src/index.ts