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