1use 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#[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 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 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 pub fn contains<T>(&self) -> bool
86 where
87 T: WasmCompatSend + WasmCompatSync + 'static,
88 {
89 self.lock().contains::<T>()
90 }
91
92 pub fn remove<T>(&self) -> Option<T>
94 where
95 T: Clone + WasmCompatSend + WasmCompatSync + 'static,
96 {
97 self.lock().remove::<T>()
98 }
99
100 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#[derive(Debug)]
124pub struct HookContext {
125 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 salvaged_patches: std::sync::Mutex<HashMap<EffectId, EffectKind>>,
138 entries: std::sync::Mutex<Vec<RunEntry>>,
140 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 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 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 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 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 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 #[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 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 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 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 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 pub fn run_id(&self) -> RunId {
269 self.run_id
270 }
271
272 pub fn turn(&self) -> usize {
274 self.turn.load(Ordering::Relaxed)
275 }
276
277 pub fn is_streaming(&self) -> bool {
279 self.is_streaming
280 }
281
282 pub fn agent_name(&self) -> Option<&str> {
284 self.agent_name.as_deref()
285 }
286
287 pub fn scratchpad(&self) -> &Scratchpad {
289 &self.scratchpad
290 }
291
292 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 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 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#[derive(Clone, Copy)]
358pub struct CompletionCallEvent<'a> {
359 pub prompt: &'a Message,
361 pub history: &'a [Message],
363 pub turn: usize,
365}
366
367#[derive(Clone, Copy)]
376pub struct ModelSelection<'a> {
377 pub prompt: &'a Message,
379 pub history: &'a [Message],
381 pub request_patch: Option<&'a RequestPatch>,
384 pub previous_model: Option<&'a ModelRef>,
386 pub default_model: &'a ModelRef,
388 pub selected_model: &'a ModelRef,
390}
391
392impl<'a> ModelSelection<'a> {
393 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#[derive(Clone, Copy)]
419pub struct ModelTurnFinished<'a> {
420 pub turn: usize,
422 pub content: &'a Vec<AssistantContent>,
424 pub usage: Usage,
426 pub identity: &'a ResponseIdentity,
430 pub finish_reason: Option<&'a FinishReason>,
434 pub max_tokens: Option<u64>,
437 pub raw: &'a serde_json::Value,
440}
441
442#[derive(Debug, Clone, PartialEq, Eq)]
450pub enum ModelTurnAction {
451 Continue,
453 Retry(RetryRequest),
455 Stop(String),
457}
458
459impl ModelTurnAction {
460 pub fn continue_run() -> Self {
462 Self::Continue
463 }
464
465 pub fn repeat() -> Self {
468 Self::Retry(RetryRequest::Repeat)
469 }
470
471 pub fn retry_with_feedback(feedback: impl Into<String>) -> Self {
473 Self::Retry(RetryRequest::Feedback(feedback.into()))
474 }
475
476 pub fn stop(reason: impl Into<String>) -> Self {
478 Self::Stop(reason.into())
479 }
480}
481
482#[derive(Clone, Copy)]
484pub struct TextDelta<'a> {
485 pub delta: &'a str,
487 pub aggregated: &'a str,
489}
490
491#[derive(Clone, Copy)]
493pub struct ReasoningDelta<'a> {
494 pub part: Part,
496 pub delta: &'a str,
498 pub aggregated: &'a str,
500}
501
502#[derive(Clone, Copy)]
504pub struct ToolCallDelta<'a> {
505 pub part: Part,
507 pub call_id: &'a CallId,
509 pub tool_name: &'a str,
511 pub delta: &'a str,
513}
514
515#[derive(Clone, Copy)]
519pub struct RunStart<'a> {
520 pub prompt: &'a Message,
523 pub history: &'a [Message],
525}
526
527#[derive(Debug, Clone, PartialEq)]
529pub enum RunStartAction {
530 Continue,
532 Rewrite(Message),
534 Stop(String),
536}
537
538impl RunStartAction {
539 pub fn continue_run() -> Self {
541 Self::Continue
542 }
543
544 pub fn rewrite(prompt: impl Into<Message>) -> Self {
546 Self::Rewrite(prompt.into())
547 }
548
549 pub fn stop(reason: impl Into<String>) -> Self {
551 Self::Stop(reason.into())
552 }
553}
554
555#[derive(Clone, Copy)]
558pub struct RunSettled<'a> {
559 pub outcome: SettledOutcome<'a>,
561 pub messages: Option<&'a [Message]>,
566}
567
568#[derive(Clone, Copy)]
570pub enum SettledOutcome<'a> {
571 Response(&'a crate::run::response::PromptResponse),
573 Error(&'a str),
575}
576
577#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
579pub enum StepEventKind {
580 RunStart,
582 RunSettled,
584 CompletionCall,
586 ModelTurnFinished,
588 InvalidToolCall,
590 TextDelta,
592 ReasoningDelta,
594 ToolCallDelta,
596 CompletionDispatch,
598 ToolDispatch,
600 EmbedDispatch,
603 RerankDispatch,
606 MemoryDispatch,
609 RetrieveDispatch,
612 CustomDispatch,
615}
616
617impl StepEventKind {
618 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#[derive(Clone, Copy)]
634pub struct DispatchEvent<'a> {
635 pub id: EffectId,
638 pub kind: &'a EffectKind,
640 pub turn: usize,
642 pub call_id: Option<&'a CallId>,
644 pub context: Option<&'a ToolContext>,
646}
647
648#[derive(Debug, Clone)]
650pub enum DispatchAction {
651 Proceed,
653 Patch(EffectKind),
658 Deny(ErrorReport),
663}
664
665pub(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 pub fn proceed() -> Self {
695 Self::Proceed
696 }
697
698 pub fn patch(kind: EffectKind) -> Self {
700 Self::Patch(kind)
701 }
702
703 pub fn deny(report: ErrorReport) -> Self {
705 Self::Deny(report)
706 }
707
708 pub fn skip(reason: impl Into<String>) -> Self {
710 Self::Deny(ErrorReport::new(ErrorKind::Other, reason))
711 }
712
713 pub fn stop(reason: impl Into<String>) -> Self {
715 Self::Deny(ErrorReport::new(ErrorKind::Cancelled, reason))
716 }
717
718 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 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 pub fn tool_name(&self) -> Option<&'a str> {
742 match self.kind {
743 EffectKind::ToolCall { name, .. } => Some(name),
744 _ => None,
745 }
746 }
747
748 pub fn tool_args(&self) -> Option<&'a str> {
750 match self.kind {
751 EffectKind::ToolCall { args, .. } => Some(args),
752 _ => None,
753 }
754 }
755
756 pub fn tool_context(&self) -> Option<&'a ToolContext> {
758 self.context
759 }
760
761 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#[derive(Clone, Copy)]
772pub struct OutcomeEvent<'a> {
773 pub id: EffectId,
775 pub kind: &'a EffectKind,
777 pub outcome: &'a Result<Outcome, ErrorReport>,
779 pub turn: usize,
781 pub call_id: Option<&'a CallId>,
783 pub context: Option<&'a ToolContext>,
785}
786
787#[derive(Debug, Clone)]
789pub enum OutcomeAction {
790 Proceed,
792 Replace(Result<Outcome, ErrorReport>),
794}
795
796impl OutcomeAction {
797 pub fn proceed() -> Self {
799 Self::Proceed
800 }
801
802 pub fn replace(outcome: Result<Outcome, ErrorReport>) -> Self {
804 Self::Replace(outcome)
805 }
806
807 pub fn stop(reason: impl Into<String>) -> Self {
813 Self::Replace(Err(ErrorReport::new(ErrorKind::Cancelled, reason)))
814 }
815
816 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 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 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 pub fn tool_context(&self) -> Option<&'a ToolContext> {
845 self.context
846 }
847
848 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 pub fn tool_name(&self) -> Option<&'a str> {
858 match self.kind {
859 EffectKind::ToolCall { name, .. } => Some(name),
860 _ => None,
861 }
862 }
863
864 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#[derive(Debug, Clone)]
877pub enum ModelSelectionAction {
878 Continue,
880 Select(ModelRef),
883 Stop(String),
885}
886
887impl ModelSelectionAction {
888 pub fn continue_run() -> Self {
890 Self::Continue
891 }
892
893 pub fn select(model: impl Into<ModelRef>) -> Self {
895 Self::Select(model.into())
896 }
897
898 pub fn stop(reason: impl Into<String>) -> Self {
903 Self::Stop(reason.into())
904 }
905}
906
907#[derive(Debug, Clone, PartialEq)]
909pub enum CompletionCallAction {
910 Continue,
912 Patch(RequestPatch),
914 Stop(String),
916}
917
918impl CompletionCallAction {
919 pub fn continue_run() -> Self {
921 Self::Continue
922 }
923
924 pub fn patch(patch: RequestPatch) -> Self {
926 Self::Patch(patch)
927 }
928
929 pub fn stop(reason: impl Into<String>) -> Self {
931 Self::Stop(reason.into())
932 }
933}
934
935#[derive(Debug, Clone, PartialEq, Eq)]
937pub enum ObservationAction {
938 Continue,
940 Stop(String),
942}
943
944impl ObservationAction {
945 pub fn continue_run() -> Self {
947 Self::Continue
948 }
949
950 pub fn stop(reason: impl Into<String>) -> Self {
952 Self::Stop(reason.into())
953 }
954}
955
956pub trait AgentHook: WasmCompatSend + WasmCompatSync {
958 fn name(&self) -> Option<String> {
961 None
962 }
963
964 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 fn on_run_settled(
982 &self,
983 _ctx: &HookContext,
984 _event: RunSettled<'_>,
985 ) -> impl Future<Output = ()> + WasmCompatSend {
986 async {}
987 }
988
989 fn on_model_select(
1001 &self,
1002 _ctx: &HookContext,
1003 _event: ModelSelection<'_>,
1004 ) -> ModelSelectionAction {
1005 ModelSelectionAction::Continue
1006 }
1007
1008 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 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 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 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 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 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 fn on_dispatch(
1093 &self,
1094 _ctx: &HookContext,
1095 _event: DispatchEvent<'_>,
1096 ) -> impl Future<Output = DispatchAction> + WasmCompatSend {
1097 async { DispatchAction::Proceed }
1098 }
1099
1100 fn on_outcome(
1103 &self,
1104 _ctx: &HookContext,
1105 _event: OutcomeEvent<'_>,
1106 ) -> impl Future<Output = OutcomeAction> + WasmCompatSend {
1107 async { OutcomeAction::Proceed }
1108 }
1109
1110 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
1132macro_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#[derive(Clone, Default)]
1275pub struct HookStack {
1276 hooks: Vec<Arc<dyn DynAgentHook>>,
1277 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
1291fn 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 pub fn new() -> Self {
1306 Self::default()
1307 }
1308
1309 pub fn with<H: AgentHook + 'static>(hook: H) -> Self {
1311 let mut stack = Self::new();
1312 stack.push(hook);
1313 stack
1314 }
1315
1316 pub fn push<H: AgentHook + 'static>(&mut self, hook: H) {
1319 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 pub fn names(&self) -> Vec<String> {
1333 self.names.clone()
1334 }
1335
1336 pub fn is_empty(&self) -> bool {
1338 self.hooks.is_empty()
1339 }
1340
1341 pub fn len(&self) -> usize {
1343 self.hooks.len()
1344 }
1345}
1346
1347trait 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
1369async 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
1385macro_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 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
1555pub 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 pub fn dispatch(&self, request: F::Request) -> crate::bus::Typed<F> {
1609 self.inner.dispatch(request)
1610 }
1611
1612 pub fn key(&self) -> &rig_core::effect::HandlerKey {
1614 self.inner.key()
1615 }
1616
1617 pub fn descriptor(&self) -> rig_core::effect::HandlerDescriptor {
1619 self.inner.descriptor()
1620 }
1621
1622 pub fn is_closed(&self) -> bool {
1624 self.inner.is_closed()
1625 }
1626}
1627
1628impl RunHandle<'_, rig_core::effect::family::Retrieve> {
1629 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 pub fn call(&self, request: rig_core::completion::CompletionRequest) -> crate::bus::Completion {
1643 self.inner.call(request)
1644 }
1645
1646 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;