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}