ocp_host/lib.rs
1//! `ocp-host` — the Open Context Protocol host runtime.
2//!
3//! An OCP **host** is the side of the protocol that asks for context: it
4//! discovers providers, negotiates capabilities, routes a
5//! [`ContextQuery`](ocp_types::ContextQuery) to the ones that can answer,
6//! budgets and cites what comes back, and gates what may leave the machine.
7//! This crate is that host runtime: today it is exercised by the OCP
8//! conformance suite and drives the `ocp-inspect` tool, and it is usable by
9//! any Rust agent that wants OCP support (`02-architecture.md` §2). Note that
10//! the in-tree context providers do **not** yet route through this host —
11//! they share `ocp-types` values via in-process calls — so this is the host
12//! runtime and conformance harness for the protocol, not (yet) the path every
13//! built-in source is served through.
14//! `docs/specs/stella-rust-cli/06-context-protocol.md` is the normative
15//! specification; every module cites the section it implements.
16//!
17//! # Shape
18//!
19//! - [`Envelope`] + [`wire`] — the versioned NDJSON message envelope and its
20//! framing (§3.1). Version mismatch is a named error, never a hang.
21//! - [`ContextProvider`] — the one trait every source implements, whether
22//! in-process, a stdio child, or a remote HTTP endpoint (§3.2, §3.3).
23//! - [`StdioProvider`] / [`RawStdioConnection`] — child-process transport
24//! with scrubbed-environment isolation and process-group teardown (§3.5).
25//! - [`HttpProvider`] — remote streamable-HTTP transport (§3.2).
26//! - [`ConsentStore`] — the gate that keeps an egress provider un-queried
27//! until the user consents, naming what leaves (§3.5).
28//! - [`Host`] — registers all three provider kinds behind one handle and
29//! [`Host::query_all`] fans a query out concurrently, enforcing timeouts,
30//! consent, and budget honesty (§2.3, §7).
31//!
32//! # Isolation invariants (`06-context-protocol.md` §3.5)
33//!
34//! What is enforced today: a stdio child is spawned with a **scrubbed
35//! environment** (`env_clear` plus a `PATH`/`HOME` allowlist), so it inherits
36//! no credentials or secrets the host holds via environment variables; each
37//! call is bounded by a timeout, and on Unix the child leads its own process
38//! group so a crash or hang is contained and reaped without touching its
39//! siblings. An `egress` provider is never auto-enabled. Frame content is
40//! untrusted data; this crate only ever *transports* it — it never executes
41//! frame content, and a host composing frames into a prompt must delimit them
42//! as quoted material.
43//!
44//! **Not yet enforced — filesystem confinement.** A child runs with the
45//! host's working directory and ordinary filesystem access; there is no cwd
46//! jail, chroot, mount namespace, or seccomp sandbox. Environment scrubbing
47//! blocks credentials passed *via env vars*, but a provider can still read
48//! files the host user can read. Treat a stdio provider as trusted code you
49//! chose to run, not as a sandboxed principal — real filesystem isolation is
50//! future work.
51
52pub mod consent;
53pub mod error;
54pub mod host;
55pub mod http;
56pub mod provider;
57pub mod stdio;
58pub mod wire;
59
60pub use consent::{ConsentRecord, ConsentStore};
61pub use error::HostError;
62pub use host::{FanOut, Host, ProviderOutcome, ProviderResult};
63pub use http::HttpProvider;
64pub use provider::{ContextProvider, capability_matches, frame_kind_name};
65pub use stdio::{RawStdioConnection, StdioProvider};
66pub use wire::{Envelope, decode_line, encode_line, envelope_kind, versions_compatible};
67
68/// The OCP protocol version this host speaks, re-exported from `ocp-types`
69/// (`06-context-protocol.md` §3).
70pub use ocp_types::PROTOCOL_VERSION;