Expand description
Reef is an open, provider-neutral set of Rust agent primitives.
An agent, here, is a loop: it sends a model everything the conversation has said so far, records what comes back, runs any tools the model asked for, records those too, and goes round again until something ends it. Reef owns that loop and the two things it is made of — the transcript it reads and extends, and the events it publishes while doing so — and it owns the seams that let you change what happens at every boundary.
Reef deliberately does not own a provider, a tool admission policy, a sandbox, a persistence format, a compaction strategy, or a configuration file. Those are yours, and they are written against exactly the public API documented here, with no private access.
§Start here
Agent::start is the entry point. Everything
before it is assembly, and it happens in one order:
- Tools. Register each one with
tool::RegistryBuilderandbuildan immutabletool::Registry. - Hooks. Register each one with
hook::RegistryBuilder, then pass that builder directly toConfig::new. - Configuration.
agent::Config::newtakes the model client, the tool registry and the hook builder, plus any default request material. - The agent.
agent::Agent::newfreezes that configuration into anagent::Revision. Everything in it stays fixed for as long as the agent runs; changing any of it means building a new agent. - A session.
session::Sessionowns one conversation’s transcript and admits one Run at a time. - The Run.
Agent::start_observedadmits the Session, records the caller’s input, and atomically returns arun::Runwith its unique event stream. Drain the stream, thenwaitfor therun::Terminal.
use std::future::{Future, ready};
use std::pin::Pin;
use std::sync::Arc;
use std::task::{Context, Poll};
use reef_core::cancel;
use reef_core::futures_core::Stream;
use reef_core::runtime::{agent, event, model, hook, run, session, tool};
use reef_core::value::{content, lifecycle};
// 1. A provider. Reef ships none: `model::Client` is the adapter you write
// around whatever answers your requests. This one answers offline.
#[derive(Debug)]
struct Offline;
impl model::Client for Offline {
type Error = std::convert::Infallible;
type Stream = Scripted;
fn info(&self) -> model::Info {
model::Info::new("offline".to_owned(), 8_192)
}
fn generate(
&self,
_request: model::Request,
) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send {
ready(Ok(Scripted(vec![
model::Event::Done {
finish_reason: "stop".to_owned(),
completion: model::CompletionReason::Stop,
provider_data: Vec::new(),
},
// A provider that answers in one frame needs no deltas.
model::Event::ContentFinal {
id: "answer".to_owned(),
kind: model::ContentKind::Text,
content: "Hello back.".to_owned(),
extensions: content::SegmentExtensions::new(String::new(), None, None),
},
])))
}
}
/// `futures-core` has no combinators, so a stream is a `poll_next`.
#[derive(Debug)]
struct Scripted(Vec<model::Event>);
impl Stream for Scripted {
type Item = Result<model::Event, std::convert::Infallible>;
fn poll_next(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Option<Self::Item>> {
Poll::Ready(self.0.pop().map(Ok))
}
}
// 2-4. Assemble. No tools and no hooks here; both registries are empty.
let tools = tool::RegistryBuilder::new().build().unwrap();
let hooks = hook::RegistryBuilder::new();
let config = agent::Config::new(Arc::new(Offline), tools, hooks);
let agent = agent::Agent::new(config).unwrap();
// 5-6. Run one conversation.
let session = session::Session::new("readme".to_owned(), None);
let (run, mut events) = agent
.start_observed(
session.clone(),
vec![content::Part::text("Hello.".to_owned())],
cancel::Token::new(),
)
.await
.unwrap();
while let Some(delivery) = events.recv().await {
// Three decision points are a rendezvous the Run waits on. The type says
// which, so a consumer never has to know the list.
if delivery.decision_point().is_some() {
delivery.accept().unwrap();
}
}
let terminal = run.wait().await;
assert_eq!(terminal.outcome(), lifecycle::Outcome::Completed);
// The transcript is the conversation, and it outlives the Run.
let history = session.transcript().snapshot().unwrap();
let spoken: Vec<String> = history.items().iter().map(|item| item.to_plain_text()).collect();
assert_eq!(spoken, ["Hello.", "Hello back."]);
agent.close().await.unwrap();§The pieces
runtime::agent,runtime::run,runtime::session— the lifecycle: an Agent holds frozen configuration, a Session holds one conversation, and a Run is one execution of the second under the first.runtime::model— the provider boundary. Implementmodel::Client; validate what you emit withmodel::StreamGrammar.runtime::tool— what the model may call, and who may authorise it.runtime::hook— seven runtime families plusAgentTeardownthat observe or change what the loop does at every boundary it has.runtime::event— the outward stream. Single-consumer, and three decision points are acknowledgements the Run blocks on.transcript,value— the records a conversation is made of, and the closed value vocabulary inside them.state— typed per-Run and per-Session storage for whatever your hooks need to carry.cancel,audit,opaque— cancellation, out-of-band facts, and the uninterpreted byte channel providers travel in.
§Serialization
The optional serde feature — off by default — adds Serialize and
Deserialize, as serde_core spells them and therefore as serde spells
them too, to 28 owned value types used by session files and lifecycle records:
27 are reachable from transcript::store::Snapshot,
value::lifecycle::Coord, audit::Event or runtime::event::Kind, and
value::lifecycle::Outcome is the remaining standalone lifecycle value. It
adds no format: reef depends
on serde_core and on no JSON, CBOR or postcard crate, and exposes no
to_json-shaped convenience. Picking a format, an envelope and a destination
is the composition layer’s job, and enabling the feature changes nothing
observable until that layer writes serialization code.
What the format guarantees is that nothing is lost on the way through.
Serialized values carry no schema version: compatibility is driven by their
content, not by which reef version wrote them. A reader refuses unknown fields
and unknown enum tags rather than dropping them; every declared field is
present and has no default. Thus None and Some(empty) survive, and so do
all three states of MetadataPresence.
One bound is worth knowing before you meet it:
MetadataValue nests without a limit in
memory but carries a documented maximum nesting depth of 128 in both
serialization directions, and reports a typed error past it rather than
truncating the value or overflowing the stack.
§What a serialized value contains
A serialized reef-core value contains model-visible and user-visible
content, and SegmentExtensions
additionally contains a provider-issued credential-tier token. Anything that
persists or transmits it inherits the confidentiality of the underlying
conversation. reef-core provides no encryption, no key management and no
redacted serialization mode, and will not: a redacted session file cannot be
resumed, so it would be a footgun with no valid use. At-rest and in-transit
protection are the responsibility of the layer that chose the destination.
This is deliberately the opposite of what Debug does.
{:?} is an incidental rendering reached from inside a log line nobody
audited, so it sizes content and never quotes it; serialization is reached
only by an explicit call at a site that named its destination, and a
transcript that dropped the token authenticating a reasoning block is one the
provider will reject. Redaction governs incidental rendering, not content
transport.
§Lock poisoning
Every lock in this crate guards an invariant reef maintains itself, so a
poisoned lock always means a panic already unwound out of code that was
halfway through maintaining one — reef’s own, or a callback that broke a
documented contract, such as a state::session_state::SnapshotValue whose Clone
panicked. Nothing behind such a lock can be assumed intact, so reef never
recovers one by carrying on with whatever it finds there. It fails closed,
and which of two ways it uses follows from the signature rather than from the
lock:
- Reported as data, where the operation is already fallible for reasons
the caller has to handle anyway. The transcript is the only such state:
every
transcript::storeread and mutation returnsPoisonedand leaves the stored history untouched, because a caller that cannot read or extend a transcript needs that as an outcome rather than as an unwind. - Propagated as a panic everywhere else. A poisoned session, mailbox, run-state, session-state, Agent, or Run lock leaves no recovery a caller could perform, so the observing call panics instead of inventing one. This is the rule ADR-014 already applies to core invariant panics, which stay outside the observer catch boundary so that a defect stays visible.
A poisoned lock is therefore never an expected outcome of correct use. No API
models it as a variant to match on beyond the transcript’s, no argument a
caller can pass provokes it, and the honest response to one is to treat the
process as holding a defect rather than to retry. Every public function that
can propagate one says so in its own # Panics section and links back here.
One lock is deliberately recovered rather than propagated: the session’s transcript-transaction lock guards no data of its own, and the reservation controller resumes a reservation callback’s unwind while that guard is still alive, having already resolved every reservation it held and either committed in full or not at all. Its poison is an expected consequence of a panic reef deliberately re-raises, and a successor must still be able to mutate the transcript, so the session recovers it where it takes it. That recovery is private, and it is the only one.
Re-exports§
pub use futures_core;
Modules§
- audit
- Non-model-visible audit facts.
- cancel
- The cooperative cancellation signal every reef boundary shares.
- opaque
- Owned provider-extension payloads and validated envelopes.
- runtime
- Runtime-facing primitives assembled below the Agent and Run layers.
- state
- Typed state primitives with explicit run and session ownership semantics.
- transcript
- Owned model-visible transcript records.
- value
- Owned leaf values shared by Reef primitives.