Skip to main content

Crate ocp_host

Crate ocp_host 

Source
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 and Host::query_all fans 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-host owns its own error type rather than borrowing stella’s so the crate stays industry-facing and dependency- light (02-architecture.md §2 — depends only on ocp-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 — the Envelope as the POST body, one Envelope back 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 to ocp/1.0 only at the public v1.0 release (06-context-protocol.md §3).