HCP — Harness Context Protocol

MCP standardized how an agent talks to a tool. HCP standardizes the harness around the agent: state that outlives the context window, verification that doesn't trust the agent's own report, least-privilege scope, and a session lifecycle that survives a process restart.

pip install hcp-protocol && python -m hcp.demo

That's real code, not staged output — scope denying by default, a false claim caught by independent verification next to a real fix that passes, and a brand-new process recovering a session's task and findings given nothing but a session id. Source: src/hcp/demo.py.

Full spec: spec/SPEC.md. Two reference SDKs: Python (this package) and TypeScript — both implement the same four interfaces against the same JSON wire format, so a state file is byte-identical in shape regardless of which SDK wrote it, and interop/ proves a session can actually hand off between them.

The four interfaces

Each is an abstract interface with reference implementations under hcp.reference — a local JSON file store, an in-memory scope table, a lifecycle built on top of the state store, and two verifiers: SubprocessVerifier (run a local command, check its exit status — good for "does the test suite pass") and HttpVerifier (hit a live endpoint, check its status and response body — good for "did the patched service actually stop leaking data"). Swap any of them out without touching the others.

Development setup

pip install -e ".[dev]"
python examples/minimal_harness.py
pytest

from hcp.reference import JsonFileStateStore, SubprocessVerifier, TableScopeEnforcer, FileLifecycle
from hcp.validator import validate

state = JsonFileStateStore("state.json")
harness = {
    "state": state,
    "verification": SubprocessVerifier(),
    "scope": TableScopeEnforcer(),
    "lifecycle": FileLifecycle(state),
}

report = validate(harness)
assert report.conformant

Status

v0.1 draft. The interfaces are the contract; the reference implementations are intentionally minimal and meant to be replaced (a git-backed StateStore, a sandboxed ScopeEnforcer, a CI-integrated Verifier, etc.) without breaking anything that depends on the interface alone.

The TypeScript SDK mirrors this one field-for-field on the wire (snake_case duration_s, session_id, etc., even though that's not idiomatic TS) but checks conformance differently: Python's validate() does a nominal isinstance check via ABCs; TypeScript's does structural duck-typing, since interfaces are erased at runtime.

interop/ now proves cross-language interop for all four interfaces, not just two: steps 1-3 hand off a real session between Python and Node.js through nothing but shared state.json (StateStore, SessionLifecycle); steps 4-5 have Python grant a Scope and run real Verifier checks, then have Node independently reconstruct the scope and re-evaluate it — including a check Python's script never ran — and assert both VerificationReports decode with the right types. What's still open: interop across different agent runtimes, not just these two reference SDKs of the same protocol (see Open Problem #4 in the course site).

License

MIT