Reef
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.
What reef owns, and what it does not
Reef owns the run lifecycle (Agent / Session / Run), the transcript and
its compare-and-set authority, the outward event plane, the tool registry and
execution engine, typed per-run and per-session state, and the hook
mechanism the seams hang off.
Reef deliberately does not own a provider, an HTTP client, a wire format, an
approval policy, a sandbox, a persistence format, a compaction strategy, or a
configuration file. Those are yours. They are written against exactly the public
API that cargo doc renders — no consumer of it here has private access — and
that is the point rather than a gap: a primitives layer whose composition
layer is the user's is one you can put your own product policy into without
forking it.
If you want a batteries-included framework, reef is not it. If you want to own the policy and not the loop, it is.
Status
0.2.0 (2026-09-20) is the version this tree declares, and it is breaking
against the last version published to crates.io, 0.1.1. 0.1.2 was tagged in
this repository but never uploaded, so it is not a registry version and there is
nothing to upgrade from on the 0.1.2 step. The public
surface is frozen in shape — api/reef-core.txt is the snapshot the gate
compares against — and the verification gate (./scripts/check-all.sh) passes
end to end. What a 0.x release may and may not change is stated in
docs/versioning.md, which is the one document under docs/ that ships with
the crate. The breaking change is
ExecutionError::GateResolverFailed and GatePublicationFailed replaced by
ExecutionError::Gate(GateOperationError), so a 0.1 requirement will not
resolve to 0.2.
One honest caveat. Everything below was measured on aarch64-apple-darwin with
the pinned toolchains, and no other target is verified. There is no hosted CI:
the gate runs from a clone, on a machine you control, and a green tree means
somebody ran it there.
Install
The package is reef-core (the crates.io name reef belongs to an unrelated
crate); the library target is reef_core.
The version this README ships with is 0.2.0; the previous version on crates.io
was 0.1.1 (0.1.2 was tagged but never published), and 0.2.0 is breaking
against it.
[]
= "0.2"
= { = "1", = ["macros", "rt"] }
A 0.1 requirement does not resolve to 0.2.0, so upgrading from 0.1 to
0.2 is an explicit requirement change.
Requires Rust 1.85.0 or newer (edition 2024). The default build has three
production dependencies — futures-core, and tokio/tokio-util with minimal
feature sets — no default features, and #![forbid(unsafe_code)]. The one
optional feature, serde, is off by default and adds a single leaf crate.
Getting started
Everything before Agent::start is assembly, and it happens in one order:
tools, hooks, configuration, the agent, a session, the run. The program below
does all six. It registers no tools and no hooks, so the only part you have to
supply is the one reef never supplies — a model::Client, the adapter that sits
between the loop and whatever answers its requests. This one answers offline, so
the program needs no network and no credentials.
use ;
use Pin;
use Arc;
use ;
use cancel;
use Stream;
use ;
use ;
/// The provider. Reef ships none, because a provider is an HTTP client with a
/// wire format, and both of those are yours.
;
/// `futures-core` carries no combinators, so a stream is a `poll_next`.
;
async
Two things in there are obligations rather than style. You must drain
take_events(): a strong seam blocks the run until the consumer decides it, and a
successful channel send is never mistaken for acceptance. And Agent::start
must be called from inside a Tokio runtime context, because the run gets its own
task.
That program is compiled and executed by this repository's test suite, so it cannot rot.
Approval, sandboxing, persistence and resume live in the composition layer — another repository, assembled from the public API. This crate ships no sample agent, because a sample agent is one product choice and reef is the bricks.
Five ideas explain most of the API
Synchronous admission. Agent::start finishes attachment, the session
lease, the revision/input freeze, sticky binding, the prepare commit and
admitted observers before it returns. There is no "admitted later" window, so
a consumer at T=0 sees consistent state.
Strong delivery. The three decision points —
event::DecisionPoint::{ToolCall, ToolResult, AfterToolCommit} — are
rendezvous, not notifications. The run does not advance until the
consumer explicitly accepts or rejects. Kind has sixteen variants and no
AfterToolCommit; the rendezvous is the decision point, not the category.
Transcript CAS. The transcript is versioned and mutated through reserve → compare-and-set → publish, with no gap where a reservation is committed but unpublished. A tool batch executes concurrently but commits atomically in source order: all of it or none.
Cancellation and terminals. Parent cancellation, request_stop and dropping
the event stream share one first-nonfatal cause; a fatal can still upgrade it.
When a terminal becomes observable, cleanup has already happened — owners
joined, lease released, events closed.
Composition over configuration. Approval policy, sandboxing, persistence and provider integration are yours. Core provides the seams.
Lifecycle guarantees
docs/contracts.md states twenty-nine contracts
normatively. Four of them shape everything a consumer can observe.
- Admission is a barrier, not a hope (C01–C05).
Agent::startcompletes attachment, the session lease, the frozen revision/input/resources, sticky binding admission, the prepare transcript commit and the staged session-state commit, and admitted-observer fan-out, before it spawns the sole run task and returns. - Work commits atomically (C06–C09, C14, C17). Transcript versions are monotonic and a compare-and-set never overwrites a conflict; concurrent tools merge in source order; assistant output and the complete set of results commit together or not at all.
- A terminal is published behind its own cleanup (C23–C25). The sole run task performs the run-end fan-out while the lease is still held, freezes the terminal state, cancels late work, releases the lease, detaches the agent and closes the event stream — and only then makes the terminal observable. A latched fatal outranks a later cancellation, and a task-owned guard performs the same cleanup on a core panic. Every strong seam also confirms authority on the caller side after the consumer decides (C12/C13, C18), so an acceptance that raced a stop or a fatal cannot authorize later execution.
- Close is linearizable and holds the only teardown authority (C29).
Configconsumes the hook builder, the full registry and teardown authority stay private to the agent, revision and run handles expose only close-free data, and one lock orders start, retryableBusy, once-only teardown, concurrent wait and cached close results.
Verification
./scripts/check-all.sh is the single authoritative gate. It runs from a clone
of the repository rather than from the published crate — the harness is
deliberately not packaged — and it covers fmt, clippy, all targets, doctests,
rustdoc, MSRV, Loom on two tracks, Miri, per-file coverage, the bench harness
crate, cargo-deny, cargo-shear, the public-API comparison and the
package contents.
Two properties are worth calling out. Coverage is enforced per production file at 100% line and branch — there is no aggregate to hide behind. And the gate passes identically under a deliberately hostile ambient environment, because it sets its own authoritative values at each execution point rather than trusting what it inherits.
Current evidence and the commands that produce it are recorded in
docs/verification.md. Volatile totals are printed by
the gate rather than copied into prose. This paragraph used to restate them, and
two of the four had already drifted — exactly the failure mode
docs/traceability.md avoids.
Where to read next
https://docs.rs/reef-core renders the crate-level documentation, which is the
recommended starting point once the example above makes sense: it walks the same
six assembly steps with links into every type they name. Locally the same page
is cargo doc --all-features --open.
In the repository, docs/README.md indexes the rest by who
it is for. The short version: docs/contracts.md is the
behavioural specification, docs/adr/ holds the decisions with
docs/adr/README.md as its index, and
docs/verification.md is the gate's own notes. None of those four is packaged;
they live beside the source in the repository named by Cargo.toml's
repository key, which is private and requires access to read.
Some material stays in the repository and is not in the published crate: the
verification harness and its evidence (scripts/**, api/**), the scaling
bench harness (benchmarks/**), this repository's issue and dependency
configuration, toolchain pin and lint/format settings (.github/**,
rust-toolchain.toml, clippy.toml, rustfmt.toml, deny.toml), the two
documents addressed to whoever works on reef rather than to whoever depends on
it (CONTRIBUTING.md, CODE_OF_CONDUCT.md), and docs/**, which is reasoning
about how this tree reached its shape and is rendered by neither cargo doc nor
docs.rs. Cargo.toml explains each case at its exclude key.
Three documents are packaged deliberately. SECURITY.md states the security
boundary and AGENTS.md the criteria that decide the API's shape, and
docs/versioning.md is negated back out of the exclusion above because it is
the compatibility promise, and a promise readable only somewhere other than
where the version came from is not a promise.
Contributing
CONTRIBUTING.md is worth reading before the first change
rather than after it, because the gate is stricter than most: Loom models on two
toolchains, Miri on a pinned nightly, 100% line and branch coverage enforced
per production file, and a cargo public-api snapshot that a change to the
public surface has to update deliberately. None of that is discoverable from one
failing run, and no hosted CI will discover it for you. It is not packaged; it
lives beside the source.
AGENTS.md is the other half of the answer, and it is the one that
decides whether a change is accepted at all: it is this project's design
constitution, and it fixes what may enter this crate and what must stay in the
layer above it. It ships inside the published package on purpose, because it is
why the API has the shape it has.
License
Licensed under either of
- Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0; the
text also ships in the package as
LICENSE-APACHE) - MIT license (http://opensource.org/licenses/MIT; the text also ships in the
package as
LICENSE-MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.