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