Skip to main content

reef_core/
lib.rs

1// Obligations of the published library surface, kept here rather than in
2// `Cargo.toml`'s lint tables for the reason ADR-018 D1 records: `[lints.*]`
3// binds every target in the package — library, tests and benches — and
4// conventions about what this crate *exports* must not bind the tests and
5// benches that are not the published surface. Conventions that are about the
6// Rust written in this repository rather than about what it exports live in
7// `Cargo.toml` instead.
8#![forbid(unsafe_code)]
9#![deny(missing_docs)]
10#![deny(missing_debug_implementations)]
11#![deny(rustdoc::missing_crate_level_docs)]
12// A returned value nobody is obliged to look at is a call that silently does
13// nothing; these three say so at the definition rather than in review.
14#![deny(clippy::must_use_candidate)]
15#![deny(clippy::return_self_not_must_use)]
16#![deny(clippy::iter_not_returning_iterator)]
17// A panic a caller was not told about is an undocumented contract. The crate
18// answers the lock-poisoning half of it once, in the section below, so that
19// affected call sites cite one decision instead of restating it independently.
20#![deny(clippy::missing_panics_doc)]
21// The Rust API Guidelines that hard constraint 6 adopts require both of these,
22// and neither restates the signature: a `# Errors` section says under what
23// condition the call fails, which is the part a caller has to act on.
24#![deny(clippy::missing_errors_doc)]
25//! Reef is an open, provider-neutral set of Rust agent primitives.
26//!
27//! An agent, here, is a loop: it sends a model everything the conversation has
28//! said so far, records what comes back, runs any tools the model asked for,
29//! records those too, and goes round again until something ends it. Reef owns
30//! that loop and the two things it is made of — the transcript it reads and
31//! extends, and the events it publishes while doing so — and it owns the seams
32//! that let you change what happens at every boundary.
33//!
34//! Reef deliberately does not own a provider, a tool admission policy, a sandbox,
35//! a persistence format, a compaction strategy, or a configuration file. Those are
36//! yours, and they are written against exactly the public API documented here,
37//! with no private access.
38//!
39//! # Start here
40//!
41//! [`Agent::start`](runtime::agent::Agent::start) is the entry point. Everything
42//! before it is assembly, and it happens in one order:
43//!
44//! 1. **Tools.** Register each one with
45//!    [`tool::RegistryBuilder`](runtime::tool::RegistryBuilder) and
46//!    [`build`](runtime::tool::RegistryBuilder::build) an immutable
47//!    [`tool::Registry`](runtime::tool::Registry).
48//! 2. **Hooks.** Register each one with
49//!    [`hook::RegistryBuilder`](runtime::hook::RegistryBuilder), then pass that
50//!    builder directly to [`Config::new`](runtime::agent::Config::new).
51//! 3. **Configuration.** [`agent::Config::new`](runtime::agent::Config::new)
52//!    takes the model client, the tool registry and the hook builder, plus any
53//!    default request material.
54//! 4. **The agent.** [`agent::Agent::new`](runtime::agent::Agent::new) freezes
55//!    that configuration into an [`agent::Revision`](runtime::agent::Revision).
56//!    Everything in it stays fixed for as long as the agent runs; changing any of
57//!    it means building a new agent.
58//! 5. **A session.** [`session::Session`](runtime::session::Session) owns one
59//!    conversation's transcript and admits one Run at a time.
60//! 6. **The Run.** [`Agent::start_observed`](runtime::agent::Agent::start_observed)
61//!    admits the Session, records the caller's input, and atomically returns a
62//!    [`run::Run`](runtime::run::Run) with its unique event stream. Drain the stream,
63//!    then [`wait`](runtime::run::Run::wait) for the
64//!    [`run::Terminal`](runtime::run::Terminal).
65//!
66//! ```
67//! use std::future::{Future, ready};
68//! use std::pin::Pin;
69//! use std::sync::Arc;
70//! use std::task::{Context, Poll};
71//!
72//! use reef_core::cancel;
73//! use reef_core::futures_core::Stream;
74//! use reef_core::runtime::{agent, event, model, hook, run, session, tool};
75//! use reef_core::value::{content, lifecycle};
76//!
77//! // 1. A provider. Reef ships none: `model::Client` is the adapter you write
78//! //    around whatever answers your requests. This one answers offline.
79//! #[derive(Debug)]
80//! struct Offline;
81//!
82//! impl model::Client for Offline {
83//!     type Error = std::convert::Infallible;
84//!     type Stream = Scripted;
85//!
86//!     fn info(&self) -> model::Info {
87//!         model::Info::new("offline".to_owned(), 8_192)
88//!     }
89//!
90//!     fn generate(
91//!         &self,
92//!         _request: model::Request,
93//!     ) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send {
94//!         ready(Ok(Scripted(vec![
95//!             model::Event::Done {
96//!                 finish_reason: "stop".to_owned(),
97//!                 completion: model::CompletionReason::Stop,
98//!                 provider_data: Vec::new(),
99//!             },
100//!             // A provider that answers in one frame needs no deltas.
101//!             model::Event::ContentFinal {
102//!                 id: "answer".to_owned(),
103//!                 kind: model::ContentKind::Text,
104//!                 content: "Hello back.".to_owned(),
105//!                 extensions: content::SegmentExtensions::new(String::new(), None, None),
106//!             },
107//!         ])))
108//!     }
109//! }
110//!
111//! /// `futures-core` has no combinators, so a stream is a `poll_next`.
112//! #[derive(Debug)]
113//! struct Scripted(Vec<model::Event>);
114//!
115//! impl Stream for Scripted {
116//!     type Item = Result<model::Event, std::convert::Infallible>;
117//!
118//!     fn poll_next(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Option<Self::Item>> {
119//!         Poll::Ready(self.0.pop().map(Ok))
120//!     }
121//! }
122//!
123//! # #[tokio::main(flavor = "current_thread")]
124//! # async fn main() {
125//! // 2-4. Assemble. No tools and no hooks here; both registries are empty.
126//! let tools = tool::RegistryBuilder::new().build().unwrap();
127//! let hooks = hook::RegistryBuilder::new();
128//! let config = agent::Config::new(Arc::new(Offline), tools, hooks);
129//! let agent = agent::Agent::new(config).unwrap();
130//!
131//! // 5-6. Run one conversation.
132//! let session = session::Session::new("readme".to_owned(), None);
133//! let (run, mut events) = agent
134//!     .start_observed(
135//!         session.clone(),
136//!         vec![content::Part::text("Hello.".to_owned())],
137//!         cancel::Token::new(),
138//!     )
139//!     .await
140//!     .unwrap();
141//!
142//! while let Some(delivery) = events.recv().await {
143//!     // Three decision points are a rendezvous the Run waits on. The type says
144//!     // which, so a consumer never has to know the list.
145//!     if delivery.decision_point().is_some() {
146//!         delivery.accept().unwrap();
147//!     }
148//! }
149//!
150//! let terminal = run.wait().await;
151//! assert_eq!(terminal.outcome(), lifecycle::Outcome::Completed);
152//!
153//! // The transcript is the conversation, and it outlives the Run.
154//! let history = session.transcript().snapshot().unwrap();
155//! let spoken: Vec<String> = history.items().iter().map(|item| item.to_plain_text()).collect();
156//! assert_eq!(spoken, ["Hello.", "Hello back."]);
157//!
158//! agent.close().await.unwrap();
159//! # }
160//! ```
161//!
162//! # The pieces
163//!
164//! - [`runtime::agent`], [`runtime::run`], [`runtime::session`] — the lifecycle:
165//!   an Agent holds frozen configuration, a Session holds one conversation, and a
166//!   Run is one execution of the second under the first.
167//! - [`runtime::model`] — the provider boundary. Implement
168//!   [`model::Client`](runtime::model::Client); validate what you emit with
169//!   [`model::StreamGrammar`](runtime::model::StreamGrammar).
170//! - [`runtime::tool`] — what the model may call, and who may authorise it.
171//! - [`runtime::hook`] — seven runtime families plus [`AgentTeardown`](runtime::hook::AgentTeardown)
172//!   that observe or change what the loop does at every boundary it has.
173//! - [`runtime::event`] — the outward stream. Single-consumer, and three
174//!   [decision points](runtime::event::DecisionPoint) are acknowledgements the
175//!   Run blocks on.
176//! - [`transcript`], [`value`] — the records a conversation is made of, and the
177//!   closed value vocabulary inside them.
178//! - [`state`] — typed per-Run and per-Session storage for whatever your hooks
179//!   need to carry.
180//! - [`cancel`], [`audit`], [`opaque`] — cancellation, out-of-band facts, and the
181//!   uninterpreted byte channel providers travel in.
182//!
183//! # Serialization
184//!
185//! The optional `serde` feature — **off by default** — adds `Serialize` and
186//! `Deserialize`, as `serde_core` spells them and therefore as `serde` spells
187//! them too, to 28 owned value types used by session files and lifecycle records:
188//! 27 are reachable from [`transcript::store::Snapshot`],
189//! [`value::lifecycle::Coord`], [`audit::Event`] or [`runtime::event::Kind`], and
190//! [`value::lifecycle::Outcome`] is the remaining standalone lifecycle value. It
191//! adds no format: reef depends
192//! on `serde_core` and on no JSON, CBOR or postcard crate, and exposes no
193//! `to_json`-shaped convenience. Picking a format, an envelope and a destination
194//! is the composition layer's job, and enabling the feature changes nothing
195//! observable until that layer writes serialization code.
196//!
197//! What the format guarantees is that nothing is lost on the way through.
198//! Serialized values carry no schema version: compatibility is driven by their
199//! content, not by which reef version wrote them. A reader refuses unknown fields
200//! and unknown enum tags rather than dropping them; every declared field is
201//! present and has no default. Thus `None` and `Some(empty)` survive, and so do
202//! all three states of [`MetadataPresence`](value::tool_call::MetadataPresence).
203//!
204//! One bound is worth knowing before you meet it:
205//! [`MetadataValue`](value::content::MetadataValue) nests without a limit in
206//! memory but carries a documented maximum nesting depth of 128 in both
207//! serialization directions, and reports a typed error past it rather than
208//! truncating the value or overflowing the stack.
209//!
210//! ## What a serialized value contains
211//!
212//! A serialized `reef-core` value contains model-visible and user-visible
213//! content, and [`SegmentExtensions`](value::content::SegmentExtensions)
214//! additionally contains a provider-issued credential-tier token. Anything that
215//! persists or transmits it inherits the confidentiality of the underlying
216//! conversation. `reef-core` provides no encryption, no key management and no
217//! redacted serialization mode, and will not: a redacted session file cannot be
218//! resumed, so it would be a footgun with no valid use. At-rest and in-transit
219//! protection are the responsibility of the layer that chose the destination.
220//!
221//! This is deliberately the opposite of what [`Debug`](std::fmt::Debug) does.
222//! `{:?}` is an incidental rendering reached from inside a log line nobody
223//! audited, so it sizes content and never quotes it; serialization is reached
224//! only by an explicit call at a site that named its destination, and a
225//! transcript that dropped the token authenticating a reasoning block is one the
226//! provider will reject. Redaction governs incidental rendering, not content
227//! transport.
228//!
229//! # Lock poisoning
230//!
231//! Every lock in this crate guards an invariant reef maintains itself, so a
232//! poisoned lock always means a panic already unwound out of code that was
233//! halfway through maintaining one — reef's own, or a callback that broke a
234//! documented contract, such as a [`state::session_state::SnapshotValue`] whose `Clone`
235//! panicked. Nothing behind such a lock can be assumed intact, so reef never
236//! recovers one by carrying on with whatever it finds there. It fails closed,
237//! and which of two ways it uses follows from the signature rather than from the
238//! lock:
239//!
240//! - **Reported as data**, where the operation is already fallible for reasons
241//!   the caller has to handle anyway. The transcript is the only such state:
242//!   every [`transcript::store`] read and mutation returns
243//!   [`Poisoned`](transcript::store::Error::Poisoned) and leaves the stored
244//!   history untouched, because a caller that cannot read or extend a transcript
245//!   needs that as an outcome rather than as an unwind.
246//! - **Propagated as a panic** everywhere else. A poisoned session, mailbox,
247//!   run-state, session-state, Agent, or Run lock leaves no recovery a caller
248//!   could perform, so the observing call panics instead of inventing one. This
249//!   is the rule ADR-014 already applies to core invariant panics, which stay
250//!   outside the observer catch boundary so that a defect stays visible.
251//!
252//! A poisoned lock is therefore never an expected outcome of correct use. No API
253//! models it as a variant to match on beyond the transcript's, no argument a
254//! caller can pass provokes it, and the honest response to one is to treat the
255//! process as holding a defect rather than to retry. Every public function that
256//! can propagate one says so in its own `# Panics` section and links back here.
257//!
258//! One lock is deliberately recovered rather than propagated: the session's
259//! transcript-transaction lock guards no data of its own, and the reservation
260//! controller resumes a reservation callback's unwind while that guard is still
261//! alive, having already resolved every reservation it held and either committed
262//! in full or not at all. Its poison is an expected consequence of a panic reef
263//! deliberately re-raises, and a successor must still be able to mutate the
264//! transcript, so the session recovers it where it takes it. That recovery is
265//! private, and it is the only one.
266
267/// The `futures-core` this crate's stream bound is written against.
268///
269/// [`model::Client::Stream`](runtime::model::Client::Stream) is bounded by
270/// [`futures_core::Stream`], which is a *different crate*, and the bound renders
271/// as `futures_core::stream::Stream` with nothing to say where that comes from.
272/// A provider author had to infer the crate name, add it to their own manifest,
273/// and pick a version that unifies with the one reef resolved — and when it did
274/// not unify, the error was an unsatisfied trait bound naming two types that
275/// print identically.
276///
277/// Implement the bound through this re-export and the version cannot disagree:
278///
279/// ```
280/// use std::pin::Pin;
281/// use std::task::{Context, Poll};
282///
283/// use reef_core::futures_core::Stream;
284///
285/// struct Empty;
286///
287/// impl Stream for Empty {
288///     type Item = ();
289///
290///     fn poll_next(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Option<Self::Item>> {
291///         Poll::Ready(None)
292///     }
293/// }
294/// ```
295///
296/// This adds nothing to reef's dependency budget: `futures-core` is already one
297/// of the three crates the default build depends on, and the bound already made
298/// it public in everything but name.
299///
300/// `futures-core` deliberately carries no combinators — no `stream::iter`, no
301/// `StreamExt` — so implementing [`Stream`](futures_core::Stream) by hand is the
302/// whole of it. [`model::Client`](runtime::model::Client) carries a worked
303/// example of the `poll_next` a scripted provider needs.
304pub use futures_core;
305
306pub mod audit;
307pub mod cancel;
308pub mod opaque;
309// This module also carries the crate's `README.md` doctest hook; the comment
310// there says why it is not in this file.
311pub(crate) mod redact;
312pub mod runtime;
313pub mod state;
314pub mod transcript;
315pub mod value;
316#[cfg(feature = "serde")]
317pub(crate) mod wire;
318
319// Declared here rather than from `redact.rs` so that the test target which
320// compiles that file through `#[path]` — `tests/miri_core.rs` — does not pull
321// these tests into the Miri baseline `scripts/miri-tests.txt` pins. This is the
322// same reason `state/mod.rs` declares its two sibling test modules.
323#[cfg(test)]
324#[path = "redact_tests.rs"]
325pub(crate) mod redact_tests;