Expand description
ocp-host — the Open Context Protocol host runtime.
An OCP host is the side of the protocol that asks for context: it
discovers providers, negotiates capabilities, routes a
ContextQuery to the ones that can answer,
budgets and cites what comes back, and gates what may leave the machine.
This crate is that host runtime: today it is exercised by the OCP
conformance suite and drives the ocp-inspect tool, and it is usable by
any Rust agent that wants OCP support (02-architecture.md §2). Note that
the in-tree context providers do not yet route through this host —
they share ocp-types values via in-process calls — so this is the host
runtime and conformance harness for the protocol, not (yet) the path every
built-in source is served through.
docs/specs/stella-rust-cli/06-context-protocol.md is the normative
specification; every module cites the section it implements.
§Shape
Envelope+wire— the versioned NDJSON message envelope and its framing (§3.1). Version mismatch is a named error, never a hang.ContextProvider— the one trait every source implements, whether in-process, a stdio child, or a remote HTTP endpoint (§3.2, §3.3).StdioProvider/RawStdioConnection— child-process transport with scrubbed-environment isolation and process-group teardown (§3.5).HttpProvider— remote streamable-HTTP transport (§3.2).ConsentStore— the gate that keeps an egress provider un-queried until the user consents, naming what leaves (§3.5).Host— registers all three provider kinds behind one handle andHost::query_allfans a query out concurrently, enforcing timeouts, consent, and budget honesty (§2.3, §7).
§Isolation invariants (06-context-protocol.md §3.5)
What is enforced today: a stdio child is spawned with a scrubbed
environment (env_clear plus a PATH/HOME allowlist), so it inherits
no credentials or secrets the host holds via environment variables; each
call is bounded by a timeout, and on Unix the child leads its own process
group so a crash or hang is contained and reaped without touching its
siblings. An egress provider is never auto-enabled. Frame content is
untrusted data; this crate only ever transports it — it never executes
frame content, and a host composing frames into a prompt must delimit them
as quoted material.
Not yet enforced — filesystem confinement. A child runs with the host’s working directory and ordinary filesystem access; there is no cwd jail, chroot, mount namespace, or seccomp sandbox. Environment scrubbing blocks credentials passed via env vars, but a provider can still read files the host user can read. Treat a stdio provider as trusted code you chose to run, not as a sandboxed principal — real filesystem isolation is future work.
Re-exports§
pub use consent::ConsentRecord;pub use consent::ConsentStore;pub use error::HostError;pub use host::FanOut;pub use host::Host;pub use host::ProviderOutcome;pub use host::ProviderResult;pub use http::HttpProvider;pub use provider::ContextProvider;pub use provider::capability_matches;pub use provider::frame_kind_name;pub use stdio::RawStdioConnection;pub use stdio::StdioProvider;pub use wire::Envelope;pub use wire::decode_line;pub use wire::encode_line;pub use wire::envelope_kind;pub use wire::versions_compatible;
Modules§
- consent
- Consent gating for egress providers (
06-context-protocol.md§3.5;02-architecture.md§7 point 4). - error
HostError— the one typed error the host runtime raises (02-architecture.md§1.5 “fail loud”). Everything a fan-out or a single provider exchange can go wrong with is a named variant here; nothing in the hot path panics.ocp-hostowns its own error type rather than borrowingstella’s so the crate stays industry-facing and dependency- light (02-architecture.md§2 — depends only onocp-types+ transport crates).- host
- The
Host— one uniform handle over every provider, and the fan-out router (06-context-protocol.md§2.3, §3.3;02-architecture.md§7). - http
- Streamable-HTTP transport: a remote OCP provider reached by POSTing the
envelope to its URL (
06-context-protocol.md§3.2 “remote providers: streamable HTTP”). The reference host uses request/response JSON — theEnvelopeas the POST body, oneEnvelopeback as the response body — which any streamable-HTTP server satisfies; chunked frame streaming is a documented forward extension, not needed for the v1 shape. - provider
- The uniform provider handle.
- stdio
- Stdio transport: a child-process OCP provider spoken to over its
stdin/stdout (
06-context-protocol.md§3.2 “local providers: child processes over stdio”). - wire
- The OCP wire envelope and its framing.
Constants§
- PROTOCOL_
VERSION - The OCP protocol version this host speaks, re-exported from
ocp-types(06-context-protocol.md§3). The protocol version string this crate implements. Frozen toocp/1.0only at the public v1.0 release (06-context-protocol.md§3).