Skip to main content

reef_core/runtime/agent/
config.rs

1//! Consumed Agent configuration and immutable revision metadata.
2
3use std::fmt::{self, Debug, Formatter};
4use std::num::NonZeroU64;
5use std::sync::Arc;
6
7use crate::opaque::Envelope;
8use crate::redact::Presence;
9use crate::runtime::hook;
10use crate::runtime::model::{Client, SamplingParams};
11use crate::runtime::session::Binding;
12use crate::runtime::tool::{self, Gate};
13use crate::value::content::Part;
14
15/// Mutable owned assembly consumed into one immutable Agent revision.
16///
17/// Everything an Agent will hold is gathered here and then frozen: the model
18/// client, the tools, the hooks, an optional admission gate, and the default
19/// request material every Step starts from. [`Agent::new`](super::Agent::new)
20/// consumes it.
21///
22/// ```
23/// # use std::future::{Future, ready};
24/// # use std::pin::Pin;
25/// # use std::sync::Arc;
26/// # use std::task::{Context, Poll};
27/// # use reef_core::futures_core::Stream;
28/// # use reef_core::runtime::model;
29/// # #[derive(Debug)] struct Offline;
30/// # #[derive(Debug)] struct Once(bool);
31/// # impl Stream for Once {
32/// #     type Item = Result<model::Event, std::convert::Infallible>;
33/// #     fn poll_next(mut self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll<Option<Self::Item>> {
34/// #         if std::mem::replace(&mut self.0, true) { return Poll::Ready(None); }
35/// #         Poll::Ready(Some(Ok(model::Event::Done { finish_reason: "stop".to_owned(), completion: model::CompletionReason::Stop, provider_data: Vec::new() })))
36/// #     }
37/// # }
38/// # impl model::Client for Offline {
39/// #     type Error = std::convert::Infallible;
40/// #     type Stream = Once;
41/// #     fn info(&self) -> model::Info { model::Info::new("offline".to_owned(), 8_192) }
42/// #     fn generate(&self, _: model::Request) -> impl Future<Output = Result<Self::Stream, Self::Error>> + Send { ready(Ok(Once(false))) }
43/// # }
44/// use reef_core::runtime::{agent, hook, tool};
45/// use reef_core::value::content;
46///
47/// let tools = tool::RegistryBuilder::new().build().unwrap();
48/// let hooks = hook::RegistryBuilder::new();
49///
50/// let mut config = agent::Config::new(Arc::new(Offline), tools, hooks);
51/// config.push_system_instruction(content::Part::text("Be terse.".to_owned()));
52/// config.sampling_mut().temperature = Some(0.2);
53///
54/// assert_eq!(config.system_instruction().len(), 1);
55/// assert!(config.tool_gate().is_none());
56/// let agent = agent::Agent::new(config).unwrap();
57/// # let _ = agent;
58/// ```
59pub struct Config<M: Client> {
60    pub(super) model: Arc<M>,
61    pub(super) tools: tool::Registry,
62    pub(super) hooks: hook::RegistryBuilder,
63    pub(super) tool_gate: Option<Arc<dyn Gate>>,
64    pub(super) system_instruction: Vec<Part>,
65    pub(super) sampling: SamplingParams,
66    pub(super) model_extensions: Vec<Envelope>,
67}
68
69impl<M: Client> Debug for Config<M> {
70    /// Shows everything a revision will freeze except the model itself.
71    ///
72    /// `M` carries no `Debug` bound, because requiring one would make an Agent
73    /// unprintable for every provider that has not opted in — a cost paid by
74    /// users to describe the one field they already know, since they supplied
75    /// it. The trailing `..` says so rather than pretending the field is absent.
76    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
77        formatter
78            .debug_struct("Config")
79            .field("tools", &self.tools)
80            .field("hooks", &self.hooks)
81            .field("tool_gate", &Presence(self.tool_gate.is_some()))
82            .field("system_instruction", &self.system_instruction)
83            .field("sampling", &self.sampling)
84            .field("model_extensions", &self.model_extensions)
85            .finish_non_exhaustive()
86    }
87}
88
89impl<M: Client> Config<M> {
90    /// Creates a configuration with empty, provider-neutral defaults.
91    ///
92    /// # Why the two registries arrive in different states
93    ///
94    /// `tools` is a built [`tool::Registry`] and `hooks` is still a
95    /// [`hook::RegistryBuilder`], and building the second one first is a type
96    /// error rather than an oversight. A tool registry is an immutable value: it
97    /// is `Clone`, it holds no authority, and several agents may share one. A
98    /// hook registry is not — it owns `OnClose` teardown authority over its
99    /// registrations, and that authority has to belong to exactly one Agent. So
100    /// the builder is consumed here and [`Agent::new`](super::Agent::new) builds
101    /// the one Agent-private registry from it. Nothing you can reach afterwards —
102    /// [`Config`], [`Agent`](super::Agent),
103    /// [`Revision`](super::Revision) or a [`Run`](crate::runtime::run::Run) —
104    /// hands that registry back, which is what makes
105    /// [`Agent::close`](super::Agent::close) the only route to teardown.
106    #[must_use]
107    pub fn new(model: Arc<M>, tools: tool::Registry, hooks: hook::RegistryBuilder) -> Self {
108        Self {
109            model,
110            tools,
111            hooks,
112            tool_gate: None,
113            system_instruction: Vec::new(),
114            sampling: SamplingParams::default(),
115            model_extensions: Vec::new(),
116        }
117    }
118
119    /// Returns the optional admission gate.
120    #[must_use]
121    pub fn tool_gate(&self) -> Option<&Arc<dyn Gate>> {
122        self.tool_gate.as_ref()
123    }
124
125    /// Binds or clears the optional admission gate.
126    pub fn set_tool_gate(&mut self, gate: Option<Arc<dyn Gate>>) -> &mut Self {
127        self.tool_gate = gate;
128        self
129    }
130
131    /// Returns the ordered default system instruction.
132    #[must_use]
133    pub fn system_instruction(&self) -> &[Part] {
134        &self.system_instruction
135    }
136
137    /// Appends one block to the default system instruction.
138    pub fn push_system_instruction(&mut self, part: Part) -> &mut Self {
139        self.system_instruction.push(part);
140        self
141    }
142
143    /// Appends blocks to the default system instruction in iteration order.
144    pub fn extend_system_instruction(
145        &mut self,
146        parts: impl IntoIterator<Item = Part>,
147    ) -> &mut Self {
148        self.system_instruction.extend(parts);
149        self
150    }
151
152    /// Removes every default system-instruction block.
153    pub fn clear_system_instruction(&mut self) -> &mut Self {
154        self.system_instruction.clear();
155        self
156    }
157
158    /// Returns the default sampling controls.
159    pub const fn sampling_mut(&mut self) -> &mut SamplingParams {
160        &mut self.sampling
161    }
162
163    /// Returns the default provider-hosted extension lane.
164    #[must_use]
165    pub fn model_extensions(&self) -> &[Envelope] {
166        &self.model_extensions
167    }
168
169    /// Appends one provider-hosted extension.
170    pub fn push_model_extension(&mut self, extension: Envelope) -> &mut Self {
171        self.model_extensions.push(extension);
172        self
173    }
174
175    /// Appends provider-hosted extensions in iteration order.
176    pub fn extend_model_extensions(
177        &mut self,
178        extensions: impl IntoIterator<Item = Envelope>,
179    ) -> &mut Self {
180        self.model_extensions.extend(extensions);
181        self
182    }
183
184    /// Removes every provider-hosted extension.
185    pub fn clear_model_extensions(&mut self) -> &mut Self {
186        self.model_extensions.clear();
187        self
188    }
189}
190
191/// Owned immutable configuration snapshot identified within this process.
192///
193/// This is the unit that a Run freezes, and the exact extent of the rule that
194/// configuration does not change inside a Run: the model client, the tool
195/// registry *including its provider roster*, the hook roster, the gate, and
196/// the default system instruction, sampling params and model extensions.
197/// Changing any of them means stopping the Run, waiting for the Session lease
198/// to be released, and starting a successor Run with a new revision.
199///
200/// It is **not** a claim that everything downstream of those bindings is
201/// constant. Two things a revision deliberately leaves free:
202///
203/// - **The resolved tool set.**
204///   [`tool::Provider::resolve`](crate::runtime::tool::Provider::resolve) runs
205///   once per Step, so the exposed tools may differ at every Step of one Run.
206///   The roster is frozen; the resolution is a per-Step observation of it. A
207///   proposal to relax Run granularity so that the tool set can vary is
208///   therefore answering a problem that does not exist.
209/// - **The request.** System instruction, sampling params and extensions are
210///   *defaults* seeded into each Step's
211///   [`RequestPlan`](crate::runtime::model::RequestPlan);
212///   [`ModelHooks::before_model`](crate::runtime::hook::ModelHooks::before_model)
213///   and the plan's own mutators adjust this one request without touching the
214///   binding. Anything that needs to change per Turn is request content, not
215///   configuration, and almost every proposal to make configuration mutable is
216///   really this.
217pub struct Revision<M: Client> {
218    pub(super) id: NonZeroU64,
219    pub(super) model: Arc<M>,
220    pub(super) tools: tool::Registry,
221    pub(super) hook_names: Arc<[String]>,
222    pub(super) hook_bindings: Arc<[Binding]>,
223    pub(super) hooks_require_session_state: bool,
224    pub(super) tool_gate: Option<Arc<dyn Gate>>,
225    pub(super) system_instruction: Arc<[Part]>,
226    pub(super) sampling: SamplingParams,
227    pub(super) model_extensions: Arc<[Envelope]>,
228}
229
230impl<M: Client> Debug for Revision<M> {
231    /// Shows the frozen configuration, identified by its revision number.
232    ///
233    /// As with [`Config`], the model is the one field left out: `M` has no
234    /// `Debug` bound, and the trailing `..` records the omission.
235    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
236        formatter
237            .debug_struct("Revision")
238            .field("id", &self.id)
239            .field("tools", &self.tools)
240            .field("hook_names", &self.hook_names)
241            .field("hook_bindings", &self.hook_bindings)
242            .field(
243                "hooks_require_session_state",
244                &self.hooks_require_session_state,
245            )
246            .field("tool_gate", &Presence(self.tool_gate.is_some()))
247            .field("system_instruction", &self.system_instruction)
248            .field("sampling", &self.sampling)
249            .field("model_extensions", &self.model_extensions)
250            .finish_non_exhaustive()
251    }
252}
253
254impl<M: Client> Clone for Revision<M> {
255    fn clone(&self) -> Self {
256        Self {
257            id: self.id,
258            model: Arc::clone(&self.model),
259            tools: self.tools.clone(),
260            hook_names: Arc::clone(&self.hook_names),
261            hook_bindings: Arc::clone(&self.hook_bindings),
262            hooks_require_session_state: self.hooks_require_session_state,
263            tool_gate: self.tool_gate.clone(),
264            system_instruction: Arc::clone(&self.system_instruction),
265            sampling: self.sampling.clone(),
266            model_extensions: Arc::clone(&self.model_extensions),
267        }
268    }
269}
270
271impl<M: Client> Revision<M> {
272    /// Returns the process-monotonic nonzero revision identity.
273    #[must_use]
274    pub const fn id(&self) -> NonZeroU64 {
275        self.id
276    }
277
278    /// Returns the shared model implementation.
279    #[must_use]
280    pub const fn model(&self) -> &Arc<M> {
281        &self.model
282    }
283
284    /// Returns the immutable tool registry.
285    #[must_use]
286    pub const fn tools(&self) -> &tool::Registry {
287        &self.tools
288    }
289
290    /// Returns close-free hook names in registration order.
291    #[must_use]
292    pub fn hook_names(&self) -> &[String] {
293        &self.hook_names
294    }
295
296    /// Returns close-free sticky bindings in registration order.
297    #[must_use]
298    pub fn hook_bindings(&self) -> &[Binding] {
299        &self.hook_bindings
300    }
301
302    /// Reports whether any hook declared Session-state access.
303    #[must_use]
304    pub const fn hooks_require_session_state(&self) -> bool {
305        self.hooks_require_session_state
306    }
307
308    /// Returns the optional shared tool gate.
309    #[must_use]
310    pub fn tool_gate(&self) -> Option<&Arc<dyn Gate>> {
311        self.tool_gate.as_ref()
312    }
313
314    /// Returns the frozen default system instruction.
315    #[must_use]
316    pub fn system_instruction(&self) -> &[Part] {
317        &self.system_instruction
318    }
319
320    /// Returns the frozen sampling controls.
321    #[must_use]
322    pub const fn sampling(&self) -> &SamplingParams {
323        &self.sampling
324    }
325
326    /// Returns the frozen provider-hosted extensions.
327    #[must_use]
328    pub fn model_extensions(&self) -> &[Envelope] {
329        &self.model_extensions
330    }
331}