Skip to main content

Crate reef_core

Crate reef_core 

Source
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:

  1. Tools. Register each one with tool::RegistryBuilder and build an immutable tool::Registry.
  2. Hooks. Register each one with hook::RegistryBuilder, then pass that builder directly to Config::new.
  3. Configuration. agent::Config::new takes the model client, the tool registry and the hook builder, plus any default request material.
  4. The agent. agent::Agent::new freezes that configuration into an agent::Revision. Everything in it stays fixed for as long as the agent runs; changing any of it means building a new agent.
  5. A session. session::Session owns one conversation’s transcript and admits one Run at a time.
  6. The Run. Agent::start_observed admits the Session, records the caller’s input, and atomically returns a run::Run with its unique event stream. Drain the stream, then wait for the run::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

§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::store read and mutation returns Poisoned and 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.