rig_agent/agent/hook.rs
1//! Event-specific hooks for observing and steering an agent run.
2//!
3//! [`AgentHook`] supplies typed lifecycle actions; [`HookStack`] composes them in
4//! registration order. Blocking and streaming runs share lifecycle decisions;
5//! streamed deltas remain provisional until the model turn is accepted.
6//!
7//! ```
8//! use rig_agent::agent::{AgentHook, HookContext, OutcomeAction, OutcomeEvent};
9//!
10//! struct ResponseLogger;
11//!
12//! impl AgentHook for ResponseLogger {
13//! async fn on_outcome(&self, _ctx: &HookContext, event: OutcomeEvent<'_>) -> OutcomeAction {
14//! if let Some(response) = event.completion() {
15//! println!(
16//! "response {:?}: {:?} ({:?})",
17//! response.response_id(),
18//! response.choice,
19//! response.usage
20//! );
21//! }
22//! OutcomeAction::proceed()
23//! }
24//! }
25//! ```
26
27use rig_core::message::CallId;
28use rig_core::streaming::Part;
29use std::sync::atomic::{AtomicUsize, Ordering};
30use std::{collections::HashMap, future::Future, sync::Arc};
31
32use rig_core::tool::context::TypeMap;
33use rig_core::{
34 completion::FinishReason,
35 message::{AssistantContent, Message},
36 wasm_compat::{WasmBoxedFuture, WasmCompatSend, WasmCompatSync},
37};
38
39use rig_core::{
40 completion::ModelRef,
41 effect::{EffectFamily, EffectId, EffectKind, Outcome},
42 error::{ErrorKind, ErrorReport},
43};
44
45use crate::{
46 completion::{ResponseIdentity, Usage},
47 json_utils,
48 tool::{ToolContext, ToolOutput, ToolResult},
49};
50
51pub use rig_core::id::RunId;
52
53pub use crate::run::RunEntry;
54
55/// Run-scoped typed storage shared by hooks. Clones share in-process state;
56/// entries are neither serialized nor rewound when a run is forked.
57/// Use [`HookContext::append_entry`] for state that must travel with the run.
58#[derive(Clone, Default)]
59pub struct Scratchpad {
60 inner: Arc<std::sync::Mutex<TypeMap>>,
61}
62
63impl Scratchpad {
64 fn lock(&self) -> std::sync::MutexGuard<'_, TypeMap> {
65 self.inner
66 .lock()
67 .unwrap_or_else(std::sync::PoisonError::into_inner)
68 }
69
70 /// Insert a value.
71 pub fn insert<T>(&self, value: T) -> Option<T>
72 where
73 T: Clone + WasmCompatSend + WasmCompatSync + 'static,
74 {
75 self.lock().insert(value)
76 }
77
78 /// Get a cloned value.
79 pub fn get<T>(&self) -> Option<T>
80 where
81 T: Clone + WasmCompatSend + WasmCompatSync + 'static,
82 {
83 self.lock().get::<T>().cloned()
84 }
85
86 /// Whether a type is present.
87 pub fn contains<T>(&self) -> bool
88 where
89 T: WasmCompatSend + WasmCompatSync + 'static,
90 {
91 self.lock().contains::<T>()
92 }
93
94 /// Remove a value.
95 pub fn remove<T>(&self) -> Option<T>
96 where
97 T: Clone + WasmCompatSend + WasmCompatSync + 'static,
98 {
99 self.lock().remove::<T>()
100 }
101
102 /// Remove a value or create its default, update it outside the lock, then
103 /// insert it and return the closure's result. Reentrant access is allowed;
104 /// concurrent updates of the same type are last-writer-wins, not serialized.
105 pub fn update<T, R>(&self, update: impl FnOnce(&mut T) -> R) -> R
106 where
107 T: Clone + Default + WasmCompatSend + WasmCompatSync + 'static,
108 {
109 let mut value = self.lock().remove::<T>().unwrap_or_default();
110 let result = update(&mut value);
111 self.lock().insert(value);
112 result
113 }
114}
115
116impl std::fmt::Debug for Scratchpad {
117 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
118 f.debug_struct("Scratchpad")
119 .field("entries", &self.lock().len())
120 .finish()
121 }
122}
123
124/// Run-scoped context supplied to hooks.
125#[derive(Debug)]
126pub struct HookContext {
127 /// The bus the run dispatches through, when it has one.
128 dispatcher: Option<crate::bus::Dispatcher>,
129 run_id: RunId,
130 turn: AtomicUsize,
131 is_streaming: bool,
132 agent_name: Option<String>,
133 scratchpad: Scratchpad,
134 /// A patch a stack accumulated before one of its hooks denied the
135 /// dispatch, keyed by the effect's id. `DispatchAction::Deny` carries only
136 /// the report, so the engine reads the effective effect (the arguments a
137 /// skipped tool result reports) from here; a nested stack records into
138 /// the same slot, so the salvage survives any nesting depth.
139 salvaged_patches: std::sync::Mutex<HashMap<EffectId, EffectKind>>,
140 /// Seeded and newly appended entries, in append order.
141 entries: std::sync::Mutex<Vec<RunEntry>>,
142 /// Appends not yet flushed into the [`AgentRun`](crate::agent::AgentRun)
143 /// by the driver.
144 pending_entries: std::sync::Mutex<Vec<RunEntry>>,
145}
146
147impl HookContext {
148 pub(crate) fn new(
149 is_streaming: bool,
150 agent_name: Option<String>,
151 dispatcher: Option<crate::bus::Dispatcher>,
152 ) -> Self {
153 Self {
154 dispatcher,
155 run_id: RunId::new(),
156 turn: AtomicUsize::new(0),
157 is_streaming,
158 agent_name,
159 scratchpad: Scratchpad::default(),
160 salvaged_patches: std::sync::Mutex::new(HashMap::new()),
161 entries: std::sync::Mutex::new(Vec::new()),
162 pending_entries: std::sync::Mutex::new(Vec::new()),
163 }
164 }
165
166 /// Record the patch a stack had accumulated when one of its hooks denied
167 /// the dispatch `id`. The innermost stack records first and wins: an
168 /// enclosing stack's earlier patch was already threaded into what the
169 /// inner stack saw, so the inner accumulation is the last rewrite before
170 /// the terminal action.
171 fn salvage_patch(&self, id: EffectId, kind: EffectKind) {
172 self.salvaged_patches
173 .lock()
174 .unwrap_or_else(std::sync::PoisonError::into_inner)
175 .entry(id)
176 .or_insert(kind);
177 }
178
179 /// The effect as patched before the dispatch `id` was denied, if any.
180 pub(crate) fn take_salvaged_patch(&self, id: EffectId) -> Option<EffectKind> {
181 self.salvaged_patches
182 .lock()
183 .unwrap_or_else(std::sync::PoisonError::into_inner)
184 .remove(&id)
185 }
186
187 /// Seed the entries a resumed run carried; called by the driver at run
188 /// start, before any hook fires.
189 pub(crate) fn seed_entries(&self, entries: &[RunEntry]) {
190 self.entries
191 .lock()
192 .unwrap_or_else(std::sync::PoisonError::into_inner)
193 .extend_from_slice(entries);
194 }
195
196 /// Drain the appends not yet flushed into the run; called by the driver
197 /// at each step boundary.
198 pub(crate) fn drain_pending_entries(&self) -> Vec<RunEntry> {
199 std::mem::take(
200 &mut *self
201 .pending_entries
202 .lock()
203 .unwrap_or_else(std::sync::PoisonError::into_inner),
204 )
205 }
206
207 pub(crate) fn set_turn(&self, turn: usize) {
208 self.turn.store(turn, Ordering::Relaxed);
209 }
210
211 /// The run's bus, for a hook binding a typed view; fails when the
212 /// context was built outside a run.
213 fn bus(&self) -> Result<&crate::bus::Dispatcher, ErrorReport> {
214 self.dispatcher.as_ref().ok_or_else(|| {
215 ErrorReport::new(
216 ErrorKind::BusClosed,
217 "this hook context was built outside a run and has no bus",
218 )
219 })
220 }
221
222 /// Bind a typed key on the run's bus, borrowing this context. Fails without
223 /// a bus or when the current registration has another family. Dispatches are
224 /// served and recorded without re-entering hooks; see [`RunHandle`] for
225 /// request ownership and driver requirements.
226 #[track_caller]
227 pub fn bind<'ctx, F: rig_core::effect::Family>(
228 &'ctx self,
229 key: &rig_core::effect::Key<F>,
230 ) -> Result<RunHandle<'ctx, F>, ErrorReport> {
231 self.bus()?.bind(key).map(RunHandle::scoped)
232 }
233
234 /// Bind the retrieval index under `key` on the run's bus, for a hook
235 /// that retrieves for itself; see [`bind`](Self::bind) for the scope.
236 /// Fails when the context was built outside a run or `key` serves
237 /// another family.
238 pub fn index<'ctx>(
239 &'ctx self,
240 key: &rig_core::effect::HandlerKey,
241 ) -> Result<RunHandle<'ctx, rig_core::effect::family::Retrieve>, ErrorReport> {
242 self.bus()?.handle(key).map(RunHandle::scoped)
243 }
244
245 /// [`index`](Self::index) for a completion model.
246 pub fn model<'ctx>(
247 &'ctx self,
248 key: &rig_core::effect::HandlerKey,
249 ) -> Result<RunHandle<'ctx, rig_core::effect::family::Completion>, ErrorReport> {
250 self.bus()?.handle(key).map(RunHandle::scoped)
251 }
252
253 /// [`index`](Self::index) for a tool.
254 pub fn tool<'ctx>(
255 &'ctx self,
256 key: &rig_core::effect::HandlerKey,
257 ) -> Result<RunHandle<'ctx, rig_core::effect::family::Tool>, ErrorReport> {
258 self.bus()?.handle(key).map(RunHandle::scoped)
259 }
260
261 /// [`index`](Self::index) for conversation memory.
262 pub fn memory<'ctx>(
263 &'ctx self,
264 key: &rig_core::effect::HandlerKey,
265 ) -> Result<RunHandle<'ctx, rig_core::effect::family::Memory>, ErrorReport> {
266 self.bus()?.handle(key).map(RunHandle::scoped)
267 }
268
269 /// Stable run identifier.
270 pub fn run_id(&self) -> RunId {
271 self.run_id
272 }
273
274 /// Current one-based model-call index.
275 pub fn turn(&self) -> usize {
276 self.turn.load(Ordering::Relaxed)
277 }
278
279 /// Whether the streaming surface is driving this run.
280 pub fn is_streaming(&self) -> bool {
281 self.is_streaming
282 }
283
284 /// Configured agent name.
285 pub fn agent_name(&self) -> Option<&str> {
286 self.agent_name.as_deref()
287 }
288
289 /// Shared run scratchpad.
290 pub fn scratchpad(&self) -> &Scratchpad {
291 &self.scratchpad
292 }
293
294 /// Serialize and append an entry stamped with the current turn. Serialization
295 /// errors leave entries unchanged. The driver transfers pending entries into
296 /// the serializable run at its next step boundary; this is not a disk write.
297 /// Entries appended during `on_run_settled` remain visible locally but are not
298 /// transferred into the finished run.
299 pub fn append_entry<T: serde::Serialize>(
300 &self,
301 kind: impl Into<String>,
302 value: &T,
303 ) -> Result<(), serde_json::Error> {
304 let entry = RunEntry {
305 kind: kind.into(),
306 turn: self.turn(),
307 value: serde_json::to_value(value)?,
308 };
309 self.entries
310 .lock()
311 .unwrap_or_else(std::sync::PoisonError::into_inner)
312 .push(entry.clone());
313 self.pending_entries
314 .lock()
315 .unwrap_or_else(std::sync::PoisonError::into_inner)
316 .push(entry);
317 Ok(())
318 }
319
320 /// Clone all entries of `kind`, including resumed entries and new appends,
321 /// in append order. Reading does not consume entries.
322 pub fn entries(&self, kind: &str) -> Vec<RunEntry> {
323 self.entries
324 .lock()
325 .unwrap_or_else(std::sync::PoisonError::into_inner)
326 .iter()
327 .filter(|entry| entry.kind == kind)
328 .cloned()
329 .collect()
330 }
331
332 /// Clone the most recent entry of `kind`, if present.
333 pub fn last_entry(&self, kind: &str) -> Option<RunEntry> {
334 self.entries
335 .lock()
336 .unwrap_or_else(std::sync::PoisonError::into_inner)
337 .iter()
338 .rev()
339 .find(|entry| entry.kind == kind)
340 .cloned()
341 }
342}
343
344pub use crate::run::policy::{
345 InvalidToolCallAction, InvalidToolCallContext, InvalidToolCallReason, RetryRequest,
346};
347
348/// Completion-call event.
349///
350/// Per `CallModel` step, hook resolution is ordered: completion-call hooks run
351/// **first** and their [`RequestPatch`]es merge in registration order. Only
352/// when every completion-call hook proceeds does [`ModelSelection`] run
353/// (receiving the merged patch), after which request preparation inspects the
354/// selected model's captured
355/// [`ProviderCapabilities`](crate::completion::ProviderCapabilities) and the
356/// attempt is issued. A completion-call stop therefore suppresses model
357/// selection entirely and does not advance
358/// [`ModelSelection::previous_model`].
359#[derive(Clone, Copy)]
360pub struct CompletionCallEvent<'a> {
361 /// Prompt for this turn.
362 pub prompt: &'a Message,
363 /// History preceding the prompt.
364 pub history: &'a [Message],
365 /// One-based model-call index.
366 pub turn: usize,
367}
368
369/// Model-selection event after completion-call hooks proceed and before request
370/// preparation inspects the selected model's capabilities. The runner default is
371/// the initial candidate on every attempt, including retries; earlier selections
372/// in a stack update the candidate seen by later hooks.
373///
374/// Selection must be synchronous and non-blocking. Prepared attempts retain their
375/// chosen handle. `previous_model` advances only when an operation is invoked,
376/// including operations that fail, not on hook stops or preparation errors.
377#[derive(Clone, Copy)]
378pub struct ModelSelection<'a> {
379 /// Prompt for the pending model call.
380 pub prompt: &'a Message,
381 /// Canonical history visible to the pending model call.
382 pub history: &'a [Message],
383 /// Merged per-turn request patch from this step's completion-call hooks
384 /// (in hook registration order), when any hook patched the request.
385 pub request_patch: Option<&'a RequestPatch>,
386 /// Model that executed the preceding issued attempt in this run, if any.
387 pub previous_model: Option<&'a ModelRef>,
388 /// Runner default used as the initial candidate for this call.
389 pub default_model: &'a ModelRef,
390 /// Candidate after all earlier model-selection hooks.
391 pub selected_model: &'a ModelRef,
392}
393
394impl<'a> ModelSelection<'a> {
395 /// Construct a model-selection event from borrowed request and candidate state.
396 pub fn new(
397 prompt: &'a Message,
398 history: &'a [Message],
399 request_patch: Option<&'a RequestPatch>,
400 previous_model: Option<&'a ModelRef>,
401 default_model: &'a ModelRef,
402 selected_model: &'a ModelRef,
403 ) -> Self {
404 Self {
405 prompt,
406 history,
407 request_patch,
408 previous_model,
409 default_model,
410 selected_model,
411 }
412 }
413}
414
415/// Medium-neutral accepted model-turn event.
416///
417/// The turn is canonicalized and parked in the run state, but has not yet been
418/// advanced into tool execution or finalization. A hook may therefore reject a
419/// tool-free turn with [`ModelTurnAction::Retry`].
420#[derive(Clone, Copy)]
421pub struct ModelTurnFinished<'a> {
422 /// One-based model-call index.
423 pub turn: usize,
424 /// Canonical assistant content parked for hook acceptance.
425 pub content: &'a Vec<AssistantContent>,
426 /// Usage reported for the turn.
427 pub usage: Usage,
428 /// This exact attempt's response identity metadata, the same value the
429 /// preceding completion outcome ([`OutcomeEvent`]) carried. On a retry, this is
430 /// the retried attempt's own identity, never a previous attempt's.
431 pub identity: &'a ResponseIdentity,
432 /// This attempt's normalized terminal reason, or `None` when unreported.
433 /// Unknown reasons retain their spelling in [`FinishReason::Other`].
434 /// A reported `Stop` is reconciled to `ToolCalls` when calls are present.
435 pub finish_reason: Option<&'a FinishReason>,
436 /// This attempt's output-token cap after agent configuration, request
437 /// overrides, and completion-call patches. `None` leaves the cap to the provider.
438 pub max_tokens: Option<u64>,
439 /// This attempt's decoded provider response, serialized as JSON on both
440 /// streaming and unary surfaces. Hand-constructed responses may use `Null`.
441 pub raw: &'a serde_json::Value,
442}
443
444/// Action for the medium-neutral [`ModelTurnFinished`] event.
445///
446/// Every retry consumes the run's existing total model-call budget. Rig does
447/// not impose a separate response-retry limit; hooks that need one should keep
448/// run-scoped state in [`HookContext::scratchpad`]. Retrying a turn containing
449/// tool calls is rejected so provider-visible history never contains unanswered
450/// calls. Use tool-call hooks to steer those turns instead.
451#[derive(Debug, Clone, PartialEq, Eq)]
452pub enum ModelTurnAction {
453 /// Accept the turn and continue the run.
454 Continue,
455 /// Reject the turn and request another model call.
456 Retry(RetryRequest),
457 /// Stop the run with a reason.
458 Stop(String),
459}
460
461impl ModelTurnAction {
462 /// Accepts the completed model turn.
463 pub fn continue_run() -> Self {
464 Self::Continue
465 }
466
467 /// Discards the response and reuses the same prompt and preceding history
468 /// with fresh request preparation.
469 pub fn repeat() -> Self {
470 Self::Retry(RetryRequest::Repeat)
471 }
472
473 /// Preserves the response, appends corrective feedback, and retries.
474 pub fn retry_with_feedback(feedback: impl Into<String>) -> Self {
475 Self::Retry(RetryRequest::Feedback(feedback.into()))
476 }
477
478 /// Stops the run with the supplied reason.
479 pub fn stop(reason: impl Into<String>) -> Self {
480 Self::Stop(reason.into())
481 }
482}
483
484/// Streaming text delta.
485#[derive(Clone, Copy)]
486pub struct TextDelta<'a> {
487 /// Newly received text.
488 pub delta: &'a str,
489 /// Text accumulated for the turn.
490 pub aggregated: &'a str,
491}
492
493/// Streaming reasoning delta.
494#[derive(Clone, Copy)]
495pub struct ReasoningDelta<'a> {
496 /// The reasoning part: stable across its deltas and its end.
497 pub part: Part,
498 /// Newly received reasoning fragment.
499 pub delta: &'a str,
500 /// Reasoning text accumulated for this reasoning part through this delta.
501 pub aggregated: &'a str,
502}
503
504/// Streaming tool-call argument delta. Fires per fragment as the provider
505/// streams a call to an allowed tool; the call's id and final arguments
506/// arrive with its end, and nothing executes before it.
507#[derive(Clone, Copy)]
508pub struct ToolCallDelta<'a> {
509 /// The call's part: stable across its deltas and its end.
510 pub part: Part,
511 /// The tool the call names.
512 pub tool_name: &'a str,
513 /// The newly received fragment of argument JSON.
514 pub delta: &'a str,
515 /// The call's argument JSON accumulated through this delta. Read it with
516 /// [`parse_partial_arguments`](rig_core::streaming::parse_partial_arguments).
517 pub aggregated: &'a str,
518}
519
520/// Initial prompt event before the first completion-call hook. In a [`HookStack`],
521/// rewrites reach later hooks in registration order; the first stop prevents
522/// remaining hooks and provider calls.
523#[derive(Clone, Copy)]
524pub struct RunStart<'a> {
525 /// The prompt the run will send on its first model call, including
526 /// earlier hooks' rewrites.
527 pub prompt: &'a Message,
528 /// The input chat history preceding the prompt.
529 pub history: &'a [Message],
530}
531
532/// Action for the pre-run [`RunStart`] event.
533#[derive(Debug, Clone, PartialEq)]
534pub enum RunStartAction {
535 /// Start the run with the current prompt.
536 Continue,
537 /// Replace the prompt and pass it to later hooks.
538 Rewrite(Message),
539 /// Stop the run before any model call, with a reason.
540 Stop(String),
541}
542
543impl RunStartAction {
544 /// Starts the run with the current prompt.
545 pub fn continue_run() -> Self {
546 Self::Continue
547 }
548
549 /// Replaces the prompt; later hooks in a [`HookStack`] see the rewrite.
550 pub fn rewrite(prompt: impl Into<Message>) -> Self {
551 Self::Rewrite(prompt.into())
552 }
553
554 /// Stops the run before any provider call.
555 pub fn stop(reason: impl Into<String>) -> Self {
556 Self::Stop(reason.into())
557 }
558}
559
560/// Terminal run event carrying a final response or error. No retry, model call,
561/// or tool execution follows automatically.
562#[derive(Clone, Copy)]
563pub struct RunSettled<'a> {
564 /// How the run ended.
565 pub outcome: SettledOutcome<'a>,
566 /// Messages actually committed by this run, including its prompt and
567 /// excluding input history. Available on error as well as success;
568 /// rejected or truncated answerless turns are not committed.
569 /// `None` means the run failed before its state was constructed.
570 pub messages: Option<&'a [Message]>,
571}
572
573/// The outcome carried by [`RunSettled`].
574#[derive(Clone, Copy)]
575pub enum SettledOutcome<'a> {
576 /// The run completed with this final response.
577 Response(&'a crate::run::response::PromptResponse),
578 /// The run terminated with an error, rendered via its `Display` form.
579 Error(&'a str),
580}
581
582/// Hook event kind used only as an observation performance hint.
583#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
584pub enum StepEventKind {
585 /// `on_run_start`.
586 RunStart,
587 /// `on_run_settled`.
588 RunSettled,
589 /// `on_completion_call`.
590 CompletionCall,
591 /// `on_model_turn_finished`.
592 ModelTurnFinished,
593 /// `on_invalid_tool_call`.
594 InvalidToolCall,
595 /// `on_text_delta`.
596 TextDelta,
597 /// `on_reasoning_delta`.
598 ReasoningDelta,
599 /// `on_tool_call_delta`.
600 ToolCallDelta,
601 /// `on_dispatch`/`on_outcome` for a completion effect.
602 CompletionDispatch,
603 /// `on_dispatch`/`on_outcome` for a tool-call effect.
604 ToolDispatch,
605 /// `on_dispatch`/`on_outcome` for an embedding effect (observe-only by
606 /// default: opt in through `observes`).
607 EmbedDispatch,
608 /// `on_dispatch`/`on_outcome` for a reranking effect (observe-only by
609 /// default).
610 RerankDispatch,
611 /// `on_dispatch`/`on_outcome` for a conversation-memory effect
612 /// (observe-only by default).
613 MemoryDispatch,
614 /// `on_dispatch`/`on_outcome` for a retrieval effect (observe-only by
615 /// default).
616 RetrieveDispatch,
617 /// `on_dispatch`/`on_outcome` for a custom effect (observe-only by
618 /// default).
619 CustomDispatch,
620}
621
622impl StepEventKind {
623 /// The dispatch-boundary event kind for an effect family.
624 pub const fn for_family(family: EffectFamily) -> Self {
625 match family {
626 EffectFamily::Completion => Self::CompletionDispatch,
627 EffectFamily::Tool => Self::ToolDispatch,
628 EffectFamily::Embed => Self::EmbedDispatch,
629 EffectFamily::Rerank => Self::RerankDispatch,
630 EffectFamily::Memory => Self::MemoryDispatch,
631 EffectFamily::Retrieve => Self::RetrieveDispatch,
632 EffectFamily::Custom => Self::CustomDispatch,
633 }
634 }
635}
636
637/// An effect about to be dispatched: what `on_dispatch` sees.
638#[derive(Clone, Copy)]
639pub struct DispatchEvent<'a> {
640 /// The dispatch's id, minted before the hook runs so an observation can
641 /// be correlated with the bus-tap record.
642 pub id: EffectId,
643 /// The effect, after any earlier hook's patch.
644 pub kind: &'a EffectKind,
645 /// The turn the effect belongs to.
646 pub turn: usize,
647 /// The call the effect answers, for a tool call the model emitted.
648 pub call_id: Option<&'a CallId>,
649 /// Tool invocation context, carried separately from the effect.
650 pub context: Option<&'a ToolContext>,
651}
652
653/// Dispatch-boundary action.
654#[derive(Debug, Clone)]
655pub enum DispatchAction {
656 /// Dispatch as is.
657 Proceed,
658 /// Dispatch this effect instead. A patch must keep the family; the
659 /// stack rejects a family change as an internal error before later hooks
660 /// observe it. Tool calls must also retain their target name; only their
661 /// arguments may be patched.
662 Patch(EffectKind),
663 /// Do not dispatch: the effect resolves failed with this report and
664 /// never reaches a handler. For a tool call a report of kind
665 /// `Cancelled` cancels the run; any other kind becomes the skipped
666 /// result the model sees. For a completion any report fails the turn.
667 Deny(ErrorReport),
668}
669
670/// Validate before a patch becomes visible to policy or execution.
671pub(crate) fn validate_dispatch_patch(
672 current: &EffectKind,
673 next: &EffectKind,
674) -> Result<(), ErrorReport> {
675 if current.family() != next.family() {
676 return Err(ErrorReport::new(
677 ErrorKind::Internal,
678 format!(
679 "a hook patched a {} dispatch into a `{}` effect",
680 current.name(),
681 next.name()
682 ),
683 ));
684 }
685 if let (EffectKind::ToolCall { name: current, .. }, EffectKind::ToolCall { name: next, .. }) =
686 (current, next)
687 && current != next
688 {
689 return Err(ErrorReport::new(
690 ErrorKind::Other,
691 "a dispatch patch cannot change the tool target",
692 ));
693 }
694 Ok(())
695}
696
697impl DispatchAction {
698 /// Dispatch as is.
699 pub fn proceed() -> Self {
700 Self::Proceed
701 }
702
703 /// Dispatch this effect instead.
704 pub fn patch(kind: EffectKind) -> Self {
705 Self::Patch(kind)
706 }
707
708 /// Deny with a report.
709 pub fn deny(report: ErrorReport) -> Self {
710 Self::Deny(report)
711 }
712
713 /// Deny a tool call so the model sees it as skipped with `reason`.
714 pub fn skip(reason: impl Into<String>) -> Self {
715 Self::Deny(ErrorReport::new(ErrorKind::Other, reason))
716 }
717
718 /// Deny and cancel the run with `reason`.
719 pub fn stop(reason: impl Into<String>) -> Self {
720 Self::Deny(ErrorReport::new(ErrorKind::Cancelled, reason))
721 }
722
723 /// Patch a tool call's arguments, keeping its name and context.
724 /// `Proceed` when `kind` is not a tool call.
725 pub fn rewrite_tool_args(kind: &EffectKind, args: impl Into<serde_json::Value>) -> Self {
726 match kind {
727 EffectKind::ToolCall { name, .. } => Self::Patch(EffectKind::ToolCall {
728 name: name.clone(),
729 args: json_utils::serialize_json_value(&args.into()),
730 }),
731 _ => Self::Proceed,
732 }
733 }
734
735 /// Serialize replacement arguments and patch the tool call with them.
736 pub fn try_rewrite_tool_args<T: serde::Serialize>(
737 kind: &EffectKind,
738 args: &T,
739 ) -> Result<Self, serde_json::Error> {
740 Ok(Self::rewrite_tool_args(kind, serde_json::to_value(args)?))
741 }
742}
743
744impl<'a> DispatchEvent<'a> {
745 /// The tool name, for a tool-call effect.
746 pub fn tool_name(&self) -> Option<&'a str> {
747 match self.kind {
748 EffectKind::ToolCall { name, .. } => Some(name),
749 _ => None,
750 }
751 }
752
753 /// The JSON arguments (after earlier patches), for a tool-call effect.
754 pub fn tool_args(&self) -> Option<&'a str> {
755 match self.kind {
756 EffectKind::ToolCall { args, .. } => Some(args),
757 _ => None,
758 }
759 }
760
761 /// The dispatch context, for a tool-call effect.
762 pub fn tool_context(&self) -> Option<&'a ToolContext> {
763 self.context
764 }
765
766 /// The request about to be sent, for a completion effect.
767 pub fn completion_request(&self) -> Option<&'a rig_core::completion::CompletionRequest> {
768 match self.kind {
769 EffectKind::Completion { request, .. } => Some(request),
770 _ => None,
771 }
772 }
773}
774
775/// An effect's answer: what `on_outcome` sees.
776#[derive(Clone, Copy)]
777pub struct OutcomeEvent<'a> {
778 /// The dispatch's id.
779 pub id: EffectId,
780 /// The effect that was dispatched (after patches).
781 pub kind: &'a EffectKind,
782 /// The answer, after any earlier hook's replacement.
783 pub outcome: &'a Result<Outcome, ErrorReport>,
784 /// The turn the effect belongs to.
785 pub turn: usize,
786 /// The call the effect answered, for a tool call the model emitted.
787 pub call_id: Option<&'a CallId>,
788 /// Published tool context, carried separately from the outcome.
789 pub context: Option<&'a ToolContext>,
790}
791
792/// Outcome-boundary action.
793#[derive(Debug, Clone)]
794pub enum OutcomeAction {
795 /// Keep the answer.
796 Proceed,
797 /// Use this answer instead.
798 Replace(Result<Outcome, ErrorReport>),
799}
800
801impl OutcomeAction {
802 /// Keep the answer.
803 pub fn proceed() -> Self {
804 Self::Proceed
805 }
806
807 /// Use this answer instead.
808 pub fn replace(outcome: Result<Outcome, ErrorReport>) -> Self {
809 Self::Replace(outcome)
810 }
811
812 /// Stop the run with `reason`: a replacement whose error is `Cancelled`
813 /// terminates the run instead of being delivered. This is how a hook
814 /// that observed an answer (a completion, a tool result) ends the run.
815 /// The cancellation short-circuits nested hook stacks; later hooks cannot
816 /// replace it with a successful answer.
817 pub fn stop(reason: impl Into<String>) -> Self {
818 Self::Replace(Err(ErrorReport::new(ErrorKind::Cancelled, reason)))
819 }
820
821 /// Replace the model-visible output of a tool result, keeping the
822 /// result's status and the dispatch context. `Proceed` when `event`
823 /// did not resolve to a tool result.
824 pub fn rewrite_tool_output(event: &OutcomeEvent<'_>, output: ToolOutput) -> Self {
825 match event.outcome {
826 Ok(Outcome::ToolResult { result }) => Self::Replace(Ok(Outcome::ToolResult {
827 result: result.clone().with_output(output),
828 })),
829 _ => Self::Proceed,
830 }
831 }
832
833 /// [`OutcomeAction::rewrite_tool_output`] with a text output.
834 pub fn rewrite_tool_result(event: &OutcomeEvent<'_>, text: impl Into<String>) -> Self {
835 Self::rewrite_tool_output(event, ToolOutput::text(text))
836 }
837}
838
839impl<'a> OutcomeEvent<'a> {
840 /// The tool result this outcome carries, for a tool-call effect.
841 pub fn tool_result(&self) -> Option<&'a ToolResult> {
842 match self.outcome {
843 Ok(Outcome::ToolResult { result, .. }) => Some(result),
844 _ => None,
845 }
846 }
847
848 /// The dispatch context the tool answered with, for a tool-call effect.
849 pub fn tool_context(&self) -> Option<&'a ToolContext> {
850 self.context
851 }
852
853 /// The completion this outcome carries, for a completion effect.
854 pub fn completion(&self) -> Option<&'a rig_core::completion::CompletionResponse> {
855 match self.outcome {
856 Ok(Outcome::Completion(response)) => Some(response),
857 _ => None,
858 }
859 }
860
861 /// The tool name, for a tool-call effect.
862 pub fn tool_name(&self) -> Option<&'a str> {
863 match self.kind {
864 EffectKind::ToolCall { name, .. } => Some(name),
865 _ => None,
866 }
867 }
868
869 /// The effective JSON arguments, for a tool-call effect.
870 pub fn tool_args(&self) -> Option<&'a str> {
871 match self.kind {
872 EffectKind::ToolCall { args, .. } => Some(args),
873 _ => None,
874 }
875 }
876}
877
878pub use crate::run::patch::RequestPatch;
879
880/// Action for model-selection hooks.
881#[derive(Debug, Clone)]
882pub enum ModelSelectionAction {
883 /// Keep the candidate supplied to this hook.
884 Continue,
885 /// Replace the candidate and pass it to later hooks: the label of a
886 /// model registered on the agent's bus.
887 Select(ModelRef),
888 /// Stop the run before request preparation or model execution.
889 Stop(String),
890}
891
892impl ModelSelectionAction {
893 /// Keeps the current model candidate.
894 pub fn continue_run() -> Self {
895 Self::Continue
896 }
897
898 /// Selects `model` and passes it to later hooks.
899 pub fn select(model: impl Into<ModelRef>) -> Self {
900 Self::Select(model.into())
901 }
902
903 /// Stops the run before the pending model attempt.
904 ///
905 /// A selection stop happens before the attempt is issued, so it does not
906 /// advance [`ModelSelection::previous_model`].
907 pub fn stop(reason: impl Into<String>) -> Self {
908 Self::Stop(reason.into())
909 }
910}
911
912/// Action for completion-call hooks.
913#[derive(Debug, Clone, PartialEq)]
914pub enum CompletionCallAction {
915 /// Send the baseline request.
916 Continue,
917 /// Merge this per-turn patch into the request.
918 Patch(RequestPatch),
919 /// Stop the run with a reason.
920 Stop(String),
921}
922
923impl CompletionCallAction {
924 /// Creates an action that sends the request without adding a patch.
925 pub fn continue_run() -> Self {
926 Self::Continue
927 }
928
929 /// Creates an action that applies a per-turn request patch.
930 pub fn patch(patch: RequestPatch) -> Self {
931 Self::Patch(patch)
932 }
933
934 /// Creates an action that stops the run with the supplied reason.
935 pub fn stop(reason: impl Into<String>) -> Self {
936 Self::Stop(reason.into())
937 }
938}
939
940/// Action for observe-only lifecycle events.
941#[derive(Debug, Clone, PartialEq, Eq)]
942pub enum ObservationAction {
943 /// Continue the run.
944 Continue,
945 /// Stop the run.
946 Stop(String),
947}
948
949impl ObservationAction {
950 /// Creates an action that continues the run.
951 pub fn continue_run() -> Self {
952 Self::Continue
953 }
954
955 /// Creates an action that stops the run with the supplied reason.
956 pub fn stop(reason: impl Into<String>) -> Self {
957 Self::Stop(reason.into())
958 }
959}
960
961/// Per-run lifecycle observer and steerer.
962pub trait AgentHook: WasmCompatSend + WasmCompatSync {
963 /// Replay identity recorded by the hook stack. `None` uses the unqualified
964 /// type name; include decision-affecting configuration in an explicit name.
965 fn name(&self) -> Option<String> {
966 None
967 }
968
969 /// Runs once before the run's first model call, seeing the initial prompt.
970 ///
971 /// The hook may rewrite the prompt or stop the run before any provider
972 /// call. In a [`HookStack`], rewrites chain in registration order and the
973 /// first stop wins; see [`RunStart`]. The default action starts the run
974 /// with the current prompt.
975 fn on_run_start(
976 &self,
977 _ctx: &HookContext,
978 _event: RunStart<'_>,
979 ) -> impl Future<Output = RunStartAction> + WasmCompatSend {
980 async { RunStartAction::Continue }
981 }
982
983 /// Observe the final response or terminal error without scheduling more work.
984 /// Existing entries are visible, but entries appended here are not transferred
985 /// into the finished run.
986 fn on_run_settled(
987 &self,
988 _ctx: &HookContext,
989 _event: RunSettled<'_>,
990 ) -> impl Future<Output = ()> + WasmCompatSend {
991 async {}
992 }
993
994 /// Selects the model for the pending model-call boundary.
995 ///
996 /// Selection is synchronous, local, and non-blocking: it operates only on
997 /// already-constructed [`ModelRef`] values and may read or write the
998 /// run [`Scratchpad`], but must not perform blocking I/O. It runs once per
999 /// `CallModel` step whose completion-call hooks proceed, including
1000 /// retries and post-tool calls, never after a completion-call stop, and
1001 /// in-flight attempts never rebind. In a [`HookStack`], selections are
1002 /// passed to later hooks in registration order; the last selection wins
1003 /// and a stop is terminal. The default action keeps the current candidate.
1004 /// See [`ModelSelection`] for the full ordering contract.
1005 fn on_model_select(
1006 &self,
1007 _ctx: &HookContext,
1008 _event: ModelSelection<'_>,
1009 ) -> ModelSelectionAction {
1010 ModelSelectionAction::Continue
1011 }
1012
1013 /// Runs before a completion request is sent.
1014 ///
1015 /// Return a per-turn patch, continue without one, or stop the run. Patches
1016 /// from a [`HookStack`] are merged in hook registration order.
1017 fn on_completion_call(
1018 &self,
1019 _ctx: &HookContext,
1020 _event: CompletionCallEvent<'_>,
1021 ) -> impl Future<Output = CompletionCallAction> + WasmCompatSend {
1022 async { CompletionCallAction::Continue }
1023 }
1024
1025 /// Observes or rejects the content produced at the end of a model turn.
1026 ///
1027 /// A retry is valid only for a tool-free turn and consumes the existing
1028 /// total model-call budget. The default action accepts the turn.
1029 fn on_model_turn_finished(
1030 &self,
1031 _ctx: &HookContext,
1032 _event: ModelTurnFinished<'_>,
1033 ) -> impl Future<Output = ModelTurnAction> + WasmCompatSend {
1034 async { ModelTurnAction::Continue }
1035 }
1036
1037 /// Resolves a model-emitted tool call that cannot be dispatched as written.
1038 ///
1039 /// The call may be failed, retried, repaired, skipped, or used to stop the
1040 /// run. Return `None` to leave the decision to a later hook. If every hook
1041 /// in a [`HookStack`] returns `None`, the run's
1042 /// [`UnhandledInvalidToolCall`](crate::run::UnhandledInvalidToolCall)
1043 /// policy applies.
1044 ///
1045 /// A call whose arguments are not a JSON object
1046 /// ([`InvalidToolCallReason::MalformedArguments`]) is offered in the tool
1047 /// step, after its turn committed, and is always answered with a tool
1048 /// result. `None` answers with feedback naming the arguments, `Retry`
1049 /// with its feedback, and `Skip` with its reason. `Stop` and `Fail` end
1050 /// the run, and `Repair` is refused, since renaming the tool cannot fix
1051 /// its arguments.
1052 fn on_invalid_tool_call(
1053 &self,
1054 _ctx: &HookContext,
1055 _event: &InvalidToolCallContext,
1056 ) -> impl Future<Output = Option<InvalidToolCallAction>> + WasmCompatSend {
1057 async { None }
1058 }
1059
1060 /// Observes a text delta from a streaming response.
1061 ///
1062 /// The default action continues the run.
1063 fn on_text_delta(
1064 &self,
1065 _ctx: &HookContext,
1066 _event: TextDelta<'_>,
1067 ) -> impl Future<Output = ObservationAction> + WasmCompatSend {
1068 async { ObservationAction::Continue }
1069 }
1070
1071 /// Observes a reasoning delta from a streaming response.
1072 ///
1073 /// The aggregate is scoped to the reasoning part identified by the event's
1074 /// correlator. Like all streamed deltas, it remains provisional until the
1075 /// model turn is accepted. The default action continues the run.
1076 fn on_reasoning_delta(
1077 &self,
1078 _ctx: &HookContext,
1079 _event: ReasoningDelta<'_>,
1080 ) -> impl Future<Output = ObservationAction> + WasmCompatSend {
1081 async { ObservationAction::Continue }
1082 }
1083
1084 /// Observes an argument fragment of a streaming tool call, before the
1085 /// fragment reaches the stream. A stop cancels the run before the call
1086 /// executes. Like all streamed deltas, it remains provisional until the
1087 /// model turn is accepted.
1088 ///
1089 /// The default action continues the run.
1090 fn on_tool_call_delta(
1091 &self,
1092 _ctx: &HookContext,
1093 _event: ToolCallDelta<'_>,
1094 ) -> impl Future<Output = ObservationAction> + WasmCompatSend {
1095 async { ObservationAction::Continue }
1096 }
1097
1098 /// An effect is about to be dispatched on the agent's bus. Runs for
1099 /// every family; `Memory`, `Retrieve`, `Embed`, `Rerank` and `Custom` dispatches
1100 /// are observe-only unless the hook opts in through
1101 /// [`AgentHook::observes`] for their [`StepEventKind`].
1102 ///
1103 /// Gated by [`AgentHook::observes`]: a hook whose `observes` answers
1104 /// `false` for [`StepEventKind::CompletionDispatch`] or
1105 /// [`StepEventKind::ToolDispatch`] is **not called** for those
1106 /// dispatches and cannot deny, patch or replace them. A hook that
1107 /// overrides `observes` to trim delta noise must keep the dispatch
1108 /// kinds it means to gate.
1109 fn on_dispatch(
1110 &self,
1111 _ctx: &HookContext,
1112 _event: DispatchEvent<'_>,
1113 ) -> impl Future<Output = DispatchAction> + WasmCompatSend {
1114 async { DispatchAction::Proceed }
1115 }
1116
1117 /// An effect resolved on the agent's bus. Gated by
1118 /// [`AgentHook::observes`] like [`AgentHook::on_dispatch`].
1119 fn on_outcome(
1120 &self,
1121 _ctx: &HookContext,
1122 _event: OutcomeEvent<'_>,
1123 ) -> impl Future<Output = OutcomeAction> + WasmCompatSend {
1124 async { OutcomeAction::Proceed }
1125 }
1126
1127 /// Declare event interest. Memory, retrieval, embedding, reranking, and custom
1128 /// dispatches default to false; all other kinds default to true.
1129 /// For dispatch events, false prevents both boundary callbacks and therefore
1130 /// prevents this hook from steering that family.
1131 fn observes(&self, kind: StepEventKind) -> bool {
1132 !matches!(
1133 kind,
1134 StepEventKind::EmbedDispatch
1135 | StepEventKind::RerankDispatch
1136 | StepEventKind::MemoryDispatch
1137 | StepEventKind::RetrieveDispatch
1138 | StepEventKind::CustomDispatch
1139 )
1140 }
1141}
1142
1143impl AgentHook for () {
1144 fn observes(&self, _kind: StepEventKind) -> bool {
1145 false
1146 }
1147}
1148
1149/// The erased hook events whose dispatch is a plain `Box::pin(self.on_*(..))`.
1150/// `model_select` (sync) and `invalid_tool_call` (borrowed event) are
1151/// hand-written below.
1152macro_rules! for_each_boxed_hook_event {
1153 ($m:ident) => {
1154 $m!(
1155 completion_call,
1156 on_completion_call,
1157 CompletionCallEvent,
1158 CompletionCallAction
1159 );
1160 $m!(
1161 model_turn_finished,
1162 on_model_turn_finished,
1163 ModelTurnFinished,
1164 ModelTurnAction
1165 );
1166 $m!(text_delta, on_text_delta, TextDelta, ObservationAction);
1167 $m!(
1168 reasoning_delta,
1169 on_reasoning_delta,
1170 ReasoningDelta,
1171 ObservationAction
1172 );
1173 $m!(
1174 tool_call_delta,
1175 on_tool_call_delta,
1176 ToolCallDelta,
1177 ObservationAction
1178 );
1179 };
1180}
1181
1182macro_rules! erased_hook_decl {
1183 ($erased:ident, $on:ident, $event:ident, $action:ident) => {
1184 fn $erased<'a>(
1185 &'a self,
1186 ctx: &'a HookContext,
1187 event: $event<'a>,
1188 ) -> WasmBoxedFuture<'a, $action>;
1189 };
1190}
1191
1192macro_rules! erased_hook_forward {
1193 ($erased:ident, $on:ident, $event:ident, $action:ident) => {
1194 fn $erased<'a>(
1195 &'a self,
1196 ctx: &'a HookContext,
1197 event: $event<'a>,
1198 ) -> WasmBoxedFuture<'a, $action> {
1199 Box::pin(self.$on(ctx, event))
1200 }
1201 };
1202}
1203
1204trait DynAgentHook: WasmCompatSend + WasmCompatSync {
1205 fn run_start<'a>(
1206 &'a self,
1207 ctx: &'a HookContext,
1208 event: RunStart<'a>,
1209 ) -> WasmBoxedFuture<'a, RunStartAction>;
1210 fn run_settled<'a>(
1211 &'a self,
1212 ctx: &'a HookContext,
1213 event: RunSettled<'a>,
1214 ) -> WasmBoxedFuture<'a, ()>;
1215 fn model_select(&self, ctx: &HookContext, event: ModelSelection<'_>) -> ModelSelectionAction;
1216 fn invalid_tool_call<'a>(
1217 &'a self,
1218 ctx: &'a HookContext,
1219 event: &'a InvalidToolCallContext,
1220 ) -> WasmBoxedFuture<'a, Option<InvalidToolCallAction>>;
1221 fn dispatch<'a>(
1222 &'a self,
1223 ctx: &'a HookContext,
1224 event: DispatchEvent<'a>,
1225 ) -> WasmBoxedFuture<'a, DispatchAction>;
1226 fn outcome<'a>(
1227 &'a self,
1228 ctx: &'a HookContext,
1229 event: OutcomeEvent<'a>,
1230 ) -> WasmBoxedFuture<'a, OutcomeAction>;
1231 for_each_boxed_hook_event!(erased_hook_decl);
1232 fn observes(&self, kind: StepEventKind) -> bool;
1233}
1234
1235impl<H> DynAgentHook for H
1236where
1237 H: AgentHook,
1238{
1239 fn run_start<'a>(
1240 &'a self,
1241 ctx: &'a HookContext,
1242 event: RunStart<'a>,
1243 ) -> WasmBoxedFuture<'a, RunStartAction> {
1244 Box::pin(self.on_run_start(ctx, event))
1245 }
1246
1247 fn run_settled<'a>(
1248 &'a self,
1249 ctx: &'a HookContext,
1250 event: RunSettled<'a>,
1251 ) -> WasmBoxedFuture<'a, ()> {
1252 Box::pin(self.on_run_settled(ctx, event))
1253 }
1254
1255 fn model_select(&self, ctx: &HookContext, event: ModelSelection<'_>) -> ModelSelectionAction {
1256 self.on_model_select(ctx, event)
1257 }
1258
1259 fn invalid_tool_call<'a>(
1260 &'a self,
1261 ctx: &'a HookContext,
1262 event: &'a InvalidToolCallContext,
1263 ) -> WasmBoxedFuture<'a, Option<InvalidToolCallAction>> {
1264 Box::pin(self.on_invalid_tool_call(ctx, event))
1265 }
1266 fn dispatch<'a>(
1267 &'a self,
1268 ctx: &'a HookContext,
1269 event: DispatchEvent<'a>,
1270 ) -> WasmBoxedFuture<'a, DispatchAction> {
1271 Box::pin(self.on_dispatch(ctx, event))
1272 }
1273 fn outcome<'a>(
1274 &'a self,
1275 ctx: &'a HookContext,
1276 event: OutcomeEvent<'a>,
1277 ) -> WasmBoxedFuture<'a, OutcomeAction> {
1278 Box::pin(self.on_outcome(ctx, event))
1279 }
1280 for_each_boxed_hook_event!(erased_hook_forward);
1281 fn observes(&self, kind: StepEventKind) -> bool {
1282 AgentHook::observes(self, kind)
1283 }
1284}
1285
1286/// Ordered composable hook stack.
1287///
1288/// Model selections chain in registration order: each hook sees the candidate
1289/// selected by earlier hooks, the last selection wins, and a stop is terminal.
1290/// Nested stacks preserve the same composition semantics.
1291#[derive(Clone, Default)]
1292pub struct HookStack {
1293 hooks: Vec<Arc<dyn DynAgentHook>>,
1294 /// The name of every hook ([`AgentHook::name`], else its type name),
1295 /// in registration order, nested stacks flattened: what an effect
1296 /// log's header records as the program.
1297 names: Vec<String>,
1298}
1299
1300impl std::fmt::Debug for HookStack {
1301 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1302 f.debug_struct("HookStack")
1303 .field("len", &self.hooks.len())
1304 .finish()
1305 }
1306}
1307
1308/// `H`'s type name without its module path (generic arguments kept), the
1309/// name a [`HookStack`] records for it.
1310fn short_type_name<H>() -> &'static str {
1311 let full = std::any::type_name::<H>();
1312 let generics = full.find('<').unwrap_or(full.len());
1313 let path = &full[..generics];
1314 match path.rfind("::") {
1315 Some(at) => &full[at + 2..],
1316 None => full,
1317 }
1318}
1319
1320impl HookStack {
1321 /// Creates an empty hook stack.
1322 pub fn new() -> Self {
1323 Self::default()
1324 }
1325
1326 /// Creates a hook stack containing `hook`.
1327 pub fn with<H: AgentHook + 'static>(hook: H) -> Self {
1328 let mut stack = Self::new();
1329 stack.push(hook);
1330 stack
1331 }
1332
1333 /// Append a hook. Its recorded name is [`AgentHook::name`] or its type name
1334 /// without the module path; nested stacks contribute flattened names.
1335 pub fn push<H: AgentHook + 'static>(&mut self, hook: H) {
1336 // A nested stack contributes its members' names, flattened in
1337 // order, so two stacks that run the same hooks name the same program.
1338 match (&hook as &dyn std::any::Any).downcast_ref::<HookStack>() {
1339 Some(nested) => self.names.extend(nested.names.iter().cloned()),
1340 None => self.names.push(
1341 hook.name()
1342 .unwrap_or_else(|| short_type_name::<H>().to_owned()),
1343 ),
1344 }
1345 self.hooks.push(Arc::new(hook));
1346 }
1347
1348 /// Recorded hook names in registration order, with nested stacks flattened.
1349 pub fn names(&self) -> Vec<String> {
1350 self.names.clone()
1351 }
1352
1353 /// Returns `true` when the stack contains no hooks.
1354 pub fn is_empty(&self) -> bool {
1355 self.hooks.is_empty()
1356 }
1357
1358 /// Returns the number of hooks in the stack.
1359 pub fn len(&self) -> usize {
1360 self.hooks.len()
1361 }
1362}
1363
1364/// An action with a neutral `Continue` state that observe-only and steering
1365/// dispatch short-circuits on: the first non-`Continue` action wins and later
1366/// hooks are not invoked.
1367trait ShortCircuitAction: Sized {
1368 const CONTINUE: Self;
1369 fn is_continue(&self) -> bool;
1370}
1371
1372impl ShortCircuitAction for ObservationAction {
1373 const CONTINUE: Self = ObservationAction::Continue;
1374 fn is_continue(&self) -> bool {
1375 matches!(self, ObservationAction::Continue)
1376 }
1377}
1378
1379impl ShortCircuitAction for ModelTurnAction {
1380 const CONTINUE: Self = ModelTurnAction::Continue;
1381 fn is_continue(&self) -> bool {
1382 matches!(self, ModelTurnAction::Continue)
1383 }
1384}
1385
1386/// Dispatches to each hook in registration order, returning the first action
1387/// that is not `Continue` without invoking the remaining hooks.
1388async fn first_non_continue<'a, A, F>(hooks: &'a [Arc<dyn DynAgentHook>], mut dispatch: F) -> A
1389where
1390 A: ShortCircuitAction,
1391 F: FnMut(&'a dyn DynAgentHook) -> WasmBoxedFuture<'a, A>,
1392{
1393 for hook in hooks {
1394 let action = dispatch(hook.as_ref()).await;
1395 if !action.is_continue() {
1396 return action;
1397 }
1398 }
1399 A::CONTINUE
1400}
1401
1402/// Generate the `HookStack` methods whose dispatch is exactly
1403/// [`first_non_continue`] over the erased hooks: `(on_* name, erased name,
1404/// event type, action type)`, mirroring `for_each_boxed_hook_event!`. The
1405/// genuinely chaining events (`on_model_select`, `on_completion_call`,
1406/// `on_invalid_tool_call`, `on_dispatch`, `on_outcome`) stay hand-written.
1407macro_rules! stack_first_non_continue {
1408 ($($on:ident, $erased:ident, $event:ident, $action:ident;)+) => {
1409 $(
1410 async fn $on(&self, ctx: &HookContext, event: $event<'_>) -> $action {
1411 first_non_continue(&self.hooks, |hook| hook.$erased(ctx, event)).await
1412 }
1413 )+
1414 };
1415}
1416
1417impl AgentHook for HookStack {
1418 async fn on_run_start(&self, ctx: &HookContext, event: RunStart<'_>) -> RunStartAction {
1419 let mut rewritten: Option<Message> = None;
1420 for hook in &self.hooks {
1421 let current = RunStart {
1422 prompt: rewritten.as_ref().unwrap_or(event.prompt),
1423 ..event
1424 };
1425 match hook.run_start(ctx, current).await {
1426 RunStartAction::Continue => {}
1427 RunStartAction::Rewrite(prompt) => rewritten = Some(prompt),
1428 stop @ RunStartAction::Stop(_) => return stop,
1429 }
1430 }
1431 rewritten.map_or(RunStartAction::Continue, RunStartAction::Rewrite)
1432 }
1433
1434 async fn on_run_settled(&self, ctx: &HookContext, event: RunSettled<'_>) {
1435 for hook in &self.hooks {
1436 hook.run_settled(ctx, event).await;
1437 }
1438 }
1439
1440 fn on_model_select(
1441 &self,
1442 ctx: &HookContext,
1443 event: ModelSelection<'_>,
1444 ) -> ModelSelectionAction {
1445 let mut selected = None;
1446 for hook in &self.hooks {
1447 let action = {
1448 let selected_model = selected.as_ref().unwrap_or(event.selected_model);
1449 hook.model_select(
1450 ctx,
1451 ModelSelection {
1452 selected_model,
1453 ..event
1454 },
1455 )
1456 };
1457 match action {
1458 ModelSelectionAction::Continue => {}
1459 ModelSelectionAction::Select(model) => selected = Some(model),
1460 stop @ ModelSelectionAction::Stop(_) => return stop,
1461 }
1462 }
1463 selected.map_or(ModelSelectionAction::Continue, ModelSelectionAction::Select)
1464 }
1465
1466 async fn on_completion_call(
1467 &self,
1468 ctx: &HookContext,
1469 event: CompletionCallEvent<'_>,
1470 ) -> CompletionCallAction {
1471 let mut merged: Option<RequestPatch> = None;
1472 for hook in &self.hooks {
1473 match hook.completion_call(ctx, event).await {
1474 CompletionCallAction::Continue => {}
1475 CompletionCallAction::Patch(patch) => {
1476 merged = Some(match merged {
1477 None => patch,
1478 Some(value) => value.merge(patch),
1479 });
1480 }
1481 stop @ CompletionCallAction::Stop(_) => return stop,
1482 }
1483 }
1484 match merged {
1485 Some(patch) if !patch.is_empty() => CompletionCallAction::Patch(patch),
1486 _ => CompletionCallAction::Continue,
1487 }
1488 }
1489
1490 stack_first_non_continue! {
1491 on_model_turn_finished, model_turn_finished, ModelTurnFinished, ModelTurnAction;
1492 on_text_delta, text_delta, TextDelta, ObservationAction;
1493 on_reasoning_delta, reasoning_delta, ReasoningDelta, ObservationAction;
1494 on_tool_call_delta, tool_call_delta, ToolCallDelta, ObservationAction;
1495 }
1496 async fn on_invalid_tool_call(
1497 &self,
1498 ctx: &HookContext,
1499 event: &InvalidToolCallContext,
1500 ) -> Option<InvalidToolCallAction> {
1501 for hook in &self.hooks {
1502 if let Some(action) = hook.invalid_tool_call(ctx, event).await {
1503 return Some(action);
1504 }
1505 }
1506 None
1507 }
1508 async fn on_dispatch(&self, ctx: &HookContext, event: DispatchEvent<'_>) -> DispatchAction {
1509 let kind = StepEventKind::for_family(event.kind.family());
1510 let mut patched: Option<EffectKind> = None;
1511 for hook in &self.hooks {
1512 if !hook.observes(kind) {
1513 continue;
1514 }
1515 let current = DispatchEvent {
1516 kind: patched.as_ref().unwrap_or(event.kind),
1517 ..event
1518 };
1519 match hook.dispatch(ctx, current).await {
1520 DispatchAction::Proceed => {}
1521 DispatchAction::Patch(next) => {
1522 if let Err(report) = validate_dispatch_patch(current.kind, &next) {
1523 if let Some(kind) = patched {
1524 ctx.salvage_patch(event.id, kind);
1525 }
1526 return DispatchAction::Deny(report);
1527 }
1528 patched = Some(next);
1529 }
1530 deny @ DispatchAction::Deny(_) => {
1531 // The denial wins, but an earlier hook's patch is what
1532 // the skipped result must report: keep it for the engine.
1533 if let Some(kind) = patched {
1534 ctx.salvage_patch(event.id, kind);
1535 }
1536 return deny;
1537 }
1538 }
1539 }
1540 patched.map_or(DispatchAction::Proceed, DispatchAction::Patch)
1541 }
1542
1543 async fn on_outcome(&self, ctx: &HookContext, event: OutcomeEvent<'_>) -> OutcomeAction {
1544 let kind = StepEventKind::for_family(event.kind.family());
1545 let mut replaced: Option<Result<Outcome, ErrorReport>> = None;
1546 for hook in &self.hooks {
1547 if !hook.observes(kind) {
1548 continue;
1549 }
1550 let current = OutcomeEvent {
1551 outcome: replaced.as_ref().unwrap_or(event.outcome),
1552 ..event
1553 };
1554 match hook.outcome(ctx, current).await {
1555 OutcomeAction::Proceed => {}
1556 OutcomeAction::Replace(next) => {
1557 if matches!(&next, Err(report) if report.kind == ErrorKind::Cancelled) {
1558 return OutcomeAction::Replace(next);
1559 }
1560 replaced = Some(next);
1561 }
1562 }
1563 }
1564 replaced.map_or(OutcomeAction::Proceed, OutcomeAction::Replace)
1565 }
1566
1567 fn observes(&self, kind: StepEventKind) -> bool {
1568 self.hooks.iter().any(|hook| hook.observes(kind))
1569 }
1570}
1571
1572/// Typed bus view borrowing a hook context. It cannot be stored as `'static`
1573/// or cloned into an owned handle. Hosts needing an owned handle must bind
1574/// through their own [`Dispatcher`](crate::bus::Dispatcher).
1575///
1576/// The lifetime constrains the view, not the request futures returned by
1577/// [`dispatch`](Self::dispatch), [`call`](Self::call), or
1578/// [`top_n`](Self::top_n). Those futures own a single dispatch and can outlive
1579/// the view. They do not retain permission to create further dispatches and
1580/// do not drive the bus themselves. Await them within the hook while the run's
1581/// driver is serving, or arrange continued serving through a host-owned driver.
1582/// Dropping an unfinished request future cancels that dispatch; dropping this
1583/// view alone does not. A future retained beyond the run is not a promise that
1584/// the run's driver will continue serving it.
1585///
1586/// ```compile_fail
1587/// use rig_agent::agent::{HookContext, RunHandle};
1588/// use rig_core::effect::{Key, family};
1589///
1590/// fn escape(ctx: &HookContext, key: &Key<family::Completion>) {
1591/// let handle = ctx.bind(key).unwrap();
1592/// // `handle` borrows `ctx`; the task must be `'static`.
1593/// tokio::spawn(async move {
1594/// let _ = handle.key();
1595/// });
1596/// }
1597/// ```
1598///
1599/// ```compile_fail
1600/// use rig_agent::agent::{HookContext, RunHandle};
1601/// use rig_core::effect::{Key, family};
1602///
1603/// struct Stash {
1604/// kept: std::sync::Mutex<Option<RunHandle<'static, family::Completion>>>,
1605/// }
1606///
1607/// fn stash(stash: &Stash, ctx: &HookContext, key: &Key<family::Completion>) {
1608/// *stash.kept.lock().unwrap() = Some(ctx.bind(key).unwrap());
1609/// }
1610/// ```
1611pub struct RunHandle<'ctx, F: rig_core::effect::Family> {
1612 inner: crate::bus::Handle<F>,
1613 _run: std::marker::PhantomData<&'ctx HookContext>,
1614}
1615
1616impl<'ctx, F: rig_core::effect::Family> RunHandle<'ctx, F> {
1617 fn scoped(inner: crate::bus::Handle<F>) -> Self {
1618 Self {
1619 inner,
1620 _run: std::marker::PhantomData,
1621 }
1622 }
1623
1624 /// Dispatch a typed request of this family.
1625 pub fn dispatch(&self, request: F::Request) -> crate::bus::Typed<F> {
1626 self.inner.dispatch(request)
1627 }
1628
1629 /// The key this view dispatches to.
1630 pub fn key(&self) -> &rig_core::effect::HandlerKey {
1631 self.inner.key()
1632 }
1633
1634 /// The descriptor now (a runtime replacement under the key is visible).
1635 pub fn descriptor(&self) -> rig_core::effect::HandlerDescriptor {
1636 self.inner.descriptor()
1637 }
1638
1639 /// Whether the bus behind this view has closed.
1640 pub fn is_closed(&self) -> bool {
1641 self.inner.is_closed()
1642 }
1643}
1644
1645impl RunHandle<'_, rig_core::effect::family::Retrieve> {
1646 /// Scored documents, deserialized on this side of the bus.
1647 pub fn top_n<T: serde::de::DeserializeOwned>(
1648 &self,
1649 req: rig_core::vector_store::request::VectorSearchRequest<
1650 rig_core::vector_store::request::Filter<serde_json::Value>,
1651 >,
1652 ) -> crate::bus::Retrieval<T> {
1653 self.inner.top_n(req)
1654 }
1655}
1656
1657impl RunHandle<'_, rig_core::effect::family::Completion> {
1658 /// A unary completion.
1659 pub fn call(&self, request: rig_core::completion::CompletionRequest) -> crate::bus::Completion {
1660 self.inner.call(request)
1661 }
1662
1663 /// The model's label as the handler advertises it now.
1664 pub fn label(&self) -> ModelRef {
1665 self.inner.label()
1666 }
1667}
1668
1669impl<F: rig_core::effect::Family> std::fmt::Debug for RunHandle<'_, F> {
1670 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1671 f.debug_struct("RunHandle")
1672 .field("key", self.inner.key())
1673 .finish_non_exhaustive()
1674 }
1675}
1676
1677#[cfg(test)]
1678mod tests;