Skip to main content

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;