1use rig_core::conversation::{Aside, Author};
28use rig_core::message::CallId;
29use rig_core::streaming::Part;
30use std::sync::atomic::{AtomicUsize, Ordering};
31use std::{
32 any::{Any, TypeId},
33 collections::HashMap,
34 future::Future,
35 sync::Arc,
36};
37
38use rig_core::{
39 completion::FinishReason,
40 message::{AssistantContent, Message},
41 wasm_compat::{WasmBoxedFuture, WasmCompatSend, WasmCompatSync},
42};
43
44use rig_core::{
45 completion::ModelRef,
46 effect::{Answered, EffectFamily, EffectId, EffectKind},
47 error::{ErrorKind, ErrorReport},
48};
49
50use crate::{
51 completion::{ResponseIdentity, Usage},
52 handlers::{Handle, Handlers, IndexHandle, ModelHandle, ToolHandle},
53 tool::{ToolContext, ToolOutput, ToolResult},
54};
55
56pub use rig_core::id::RunId;
57
58#[derive(Clone, Default)]
62pub struct Scratchpad {
63 inner: Arc<std::sync::Mutex<HashMap<TypeId, Box<dyn Entry>>>>,
64}
65
66trait Entry: Any + WasmCompatSend + WasmCompatSync {}
68
69impl<T: Any + WasmCompatSend + WasmCompatSync> Entry for T {}
70
71fn take<T: 'static>(entry: Box<dyn Entry>) -> Option<T> {
72 (entry as Box<dyn Any>).downcast().ok().map(|value| *value)
73}
74
75impl Scratchpad {
76 fn lock(&self) -> std::sync::MutexGuard<'_, HashMap<TypeId, Box<dyn Entry>>> {
77 self.inner
78 .lock()
79 .unwrap_or_else(std::sync::PoisonError::into_inner)
80 }
81
82 pub fn insert<T>(&self, value: T) -> Option<T>
84 where
85 T: Clone + WasmCompatSend + WasmCompatSync + 'static,
86 {
87 self.lock()
88 .insert(TypeId::of::<T>(), Box::new(value))
89 .and_then(take)
90 }
91
92 pub fn get<T>(&self) -> Option<T>
94 where
95 T: Clone + WasmCompatSend + WasmCompatSync + 'static,
96 {
97 let entries = self.lock();
98 let entry = entries.get(&TypeId::of::<T>())?;
99 (&**entry as &dyn Any).downcast_ref::<T>().cloned()
100 }
101
102 pub fn contains<T>(&self) -> bool
104 where
105 T: WasmCompatSend + WasmCompatSync + 'static,
106 {
107 self.lock().contains_key(&TypeId::of::<T>())
108 }
109
110 pub fn remove<T>(&self) -> Option<T>
112 where
113 T: Clone + WasmCompatSend + WasmCompatSync + 'static,
114 {
115 self.lock().remove(&TypeId::of::<T>()).and_then(take)
116 }
117
118 pub fn update<T, R>(&self, update: impl FnOnce(&mut T) -> R) -> R
122 where
123 T: Clone + Default + WasmCompatSend + WasmCompatSync + 'static,
124 {
125 let mut value = self.remove::<T>().unwrap_or_default();
126 let result = update(&mut value);
127 self.insert(value);
128 result
129 }
130}
131
132impl std::fmt::Debug for Scratchpad {
133 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
134 f.debug_struct("Scratchpad")
135 .field("entries", &self.lock().len())
136 .finish()
137 }
138}
139
140#[derive(Debug)]
142pub struct HookContext {
143 handlers: Handlers,
145 run_id: RunId,
146 turn: AtomicUsize,
147 is_streaming: bool,
148 agent_name: Option<String>,
149 scratchpad: Scratchpad,
150 salvaged_patches: std::sync::Mutex<HashMap<EffectId, EffectKind>>,
156 entries: std::sync::Mutex<Vec<Aside>>,
158 pending_entries: std::sync::Mutex<Vec<Aside>>,
161}
162
163impl HookContext {
164 pub(crate) fn new(is_streaming: bool, agent_name: Option<String>, handlers: Handlers) -> Self {
165 Self {
166 handlers,
167 run_id: RunId::new(),
168 turn: AtomicUsize::new(0),
169 is_streaming,
170 agent_name,
171 scratchpad: Scratchpad::default(),
172 salvaged_patches: std::sync::Mutex::new(HashMap::new()),
173 entries: std::sync::Mutex::new(Vec::new()),
174 pending_entries: std::sync::Mutex::new(Vec::new()),
175 }
176 }
177
178 fn salvage_patch(&self, id: EffectId, kind: EffectKind) {
184 self.salvaged_patches
185 .lock()
186 .unwrap_or_else(std::sync::PoisonError::into_inner)
187 .entry(id)
188 .or_insert(kind);
189 }
190
191 pub(crate) fn take_salvaged_patch(&self, id: EffectId) -> Option<EffectKind> {
193 self.salvaged_patches
194 .lock()
195 .unwrap_or_else(std::sync::PoisonError::into_inner)
196 .remove(&id)
197 }
198
199 pub(crate) fn seed_entries(&self, entries: &[Aside]) {
202 self.entries
203 .lock()
204 .unwrap_or_else(std::sync::PoisonError::into_inner)
205 .extend_from_slice(entries);
206 }
207
208 pub(crate) fn drain_pending_entries(&self) -> Vec<Aside> {
211 std::mem::take(
212 &mut *self
213 .pending_entries
214 .lock()
215 .unwrap_or_else(std::sync::PoisonError::into_inner),
216 )
217 }
218
219 pub(crate) fn set_turn(&self, turn: usize) {
220 self.turn.store(turn, Ordering::Relaxed);
221 }
222
223 #[cfg(any(test, feature = "test-utils"))]
224 pub(crate) fn set_streaming(&mut self, is_streaming: bool) {
225 self.is_streaming = is_streaming;
226 }
227
228 #[cfg(any(test, feature = "test-utils"))]
229 pub(crate) fn set_agent_name(&mut self, name: String) {
230 self.agent_name = Some(name);
231 }
232
233 pub fn bind<F: rig_core::effect::Family>(
237 &self,
238 key: &rig_core::effect::Key<F>,
239 ) -> Result<Handle<F>, ErrorReport> {
240 self.handlers.bind(key)
241 }
242
243 pub fn index(&self, key: &rig_core::effect::HandlerKey) -> Result<IndexHandle, ErrorReport> {
246 self.handlers.handle(key)
247 }
248
249 pub fn model(&self, key: &rig_core::effect::HandlerKey) -> Result<ModelHandle, ErrorReport> {
251 self.handlers.handle(key)
252 }
253
254 pub fn tool(&self, key: &rig_core::effect::HandlerKey) -> Result<ToolHandle, ErrorReport> {
256 self.handlers.handle(key)
257 }
258
259 pub fn run_id(&self) -> RunId {
261 self.run_id
262 }
263
264 pub fn turn(&self) -> usize {
266 self.turn.load(Ordering::Relaxed)
267 }
268
269 pub fn is_streaming(&self) -> bool {
271 self.is_streaming
272 }
273
274 pub fn agent_name(&self) -> Option<&str> {
276 self.agent_name.as_deref()
277 }
278
279 pub fn scratchpad(&self) -> &Scratchpad {
281 &self.scratchpad
282 }
283
284 pub fn append_entry<T: serde::Serialize>(
291 &self,
292 kind: impl Into<String>,
293 value: &T,
294 ) -> Result<(), serde_json::Error> {
295 let entry = Aside::new(kind, Author::rig(), serde_json::to_value(value)?);
296 self.entries
297 .lock()
298 .unwrap_or_else(std::sync::PoisonError::into_inner)
299 .push(entry.clone());
300 self.pending_entries
301 .lock()
302 .unwrap_or_else(std::sync::PoisonError::into_inner)
303 .push(entry);
304 Ok(())
305 }
306
307 pub fn entries(&self, kind: &str) -> Vec<Aside> {
310 self.entries
311 .lock()
312 .unwrap_or_else(std::sync::PoisonError::into_inner)
313 .iter()
314 .filter(|entry| entry.kind == kind)
315 .cloned()
316 .collect()
317 }
318
319 pub fn last_entry(&self, kind: &str) -> Option<Aside> {
321 self.entries
322 .lock()
323 .unwrap_or_else(std::sync::PoisonError::into_inner)
324 .iter()
325 .rev()
326 .find(|entry| entry.kind == kind)
327 .cloned()
328 }
329}
330
331pub use crate::run::policy::{
332 InvalidToolCallAction, InvalidToolCallContext, InvalidToolCallReason, RetryRequest,
333};
334
335#[derive(Clone, Copy)]
347pub struct CompletionCallEvent<'a> {
348 pub prompt: &'a Message,
350 pub history: &'a [Arc<Message>],
352 pub turn: usize,
354}
355
356#[derive(Clone, Copy)]
365pub struct ModelSelection<'a> {
366 pub prompt: &'a Message,
368 pub history: &'a [Arc<Message>],
370 pub request_patch: Option<&'a RequestPatch>,
373 pub previous_model: Option<&'a ModelRef>,
375 pub default_model: &'a ModelRef,
377 pub selected_model: &'a ModelRef,
379}
380
381impl<'a> ModelSelection<'a> {
382 pub fn new(
384 prompt: &'a Message,
385 history: &'a [Arc<Message>],
386 request_patch: Option<&'a RequestPatch>,
387 previous_model: Option<&'a ModelRef>,
388 default_model: &'a ModelRef,
389 selected_model: &'a ModelRef,
390 ) -> Self {
391 Self {
392 prompt,
393 history,
394 request_patch,
395 previous_model,
396 default_model,
397 selected_model,
398 }
399 }
400}
401
402#[derive(Clone, Copy)]
408pub struct ModelTurnFinished<'a> {
409 pub turn: usize,
411 pub content: &'a Vec<AssistantContent>,
413 pub usage: Usage,
415 pub identity: &'a ResponseIdentity,
419 pub finish_reason: Option<&'a FinishReason>,
423 pub max_tokens: Option<u64>,
426 pub raw: &'a serde_json::Value,
429}
430
431#[derive(Debug, Clone, PartialEq, Eq)]
439pub enum ModelTurnAction {
440 Continue,
442 Retry(RetryRequest),
444 Stop(String),
446}
447
448impl ModelTurnAction {
449 pub fn continue_run() -> Self {
451 Self::Continue
452 }
453
454 pub fn repeat() -> Self {
457 Self::Retry(RetryRequest::Repeat)
458 }
459
460 pub fn retry_with_feedback(feedback: impl Into<String>) -> Self {
462 Self::Retry(RetryRequest::Feedback(feedback.into()))
463 }
464
465 pub fn stop(reason: impl Into<String>) -> Self {
467 Self::Stop(reason.into())
468 }
469}
470
471#[derive(Clone, Copy)]
473pub struct TextDelta<'a> {
474 pub delta: &'a str,
476 pub aggregated: &'a str,
478}
479
480#[derive(Clone, Copy)]
482pub struct ReasoningDelta<'a> {
483 pub part: Part,
485 pub delta: &'a str,
487 pub aggregated: &'a str,
489}
490
491#[derive(Clone, Copy)]
495pub struct ToolCallDelta<'a> {
496 pub part: Part,
498 pub tool_name: &'a str,
500 pub delta: &'a str,
502 pub aggregated: &'a str,
505}
506
507#[derive(Clone, Copy)]
511pub struct RunStart<'a> {
512 pub prompt: &'a Message,
515 pub history: &'a [Arc<Message>],
517}
518
519#[derive(Debug, Clone, PartialEq)]
521pub enum RunStartAction {
522 Continue,
524 Rewrite(Message),
526 Stop(String),
528}
529
530impl RunStartAction {
531 pub fn continue_run() -> Self {
533 Self::Continue
534 }
535
536 pub fn rewrite(prompt: impl Into<Message>) -> Self {
538 Self::Rewrite(prompt.into())
539 }
540
541 pub fn stop(reason: impl Into<String>) -> Self {
543 Self::Stop(reason.into())
544 }
545}
546
547#[derive(Clone, Copy)]
550pub struct RunSettled<'a> {
551 pub outcome: SettledOutcome<'a>,
553 pub messages: Option<&'a [Arc<Message>]>,
558}
559
560#[derive(Clone, Copy)]
562pub enum SettledOutcome<'a> {
563 Response(&'a crate::run::response::PromptResponse),
565 Error(&'a str),
567}
568
569#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
571pub enum StepEventKind {
572 RunStart,
574 RunSettled,
576 CompletionCall,
578 ModelTurnFinished,
580 InvalidToolCall,
582 TextDelta,
584 ReasoningDelta,
586 ToolCallDelta,
588 CompletionDispatch,
591 ToolDispatch,
593 EmbedDispatch,
596 RerankDispatch,
599 RetrieveDispatch,
602 CustomDispatch,
605}
606
607impl StepEventKind {
608 pub const fn for_family(family: EffectFamily) -> Self {
610 match family {
611 EffectFamily::Completion => Self::CompletionDispatch,
612 EffectFamily::Tool => Self::ToolDispatch,
613 EffectFamily::Embed => Self::EmbedDispatch,
614 EffectFamily::Rerank => Self::RerankDispatch,
615 EffectFamily::Retrieve => Self::RetrieveDispatch,
616 EffectFamily::Custom => Self::CustomDispatch,
617 }
618 }
619}
620
621#[derive(Clone, Copy)]
623pub struct DispatchEvent<'a> {
624 pub id: EffectId,
627 pub kind: &'a EffectKind,
629 pub turn: usize,
631 pub call_id: Option<&'a CallId>,
633 pub context: Option<&'a ToolContext>,
635}
636
637#[derive(Debug, Clone)]
639pub enum DispatchAction {
640 Proceed,
642 Patch(EffectKind),
647 Deny(ErrorReport),
652}
653
654pub(crate) fn validate_dispatch_patch(
656 current: &EffectKind,
657 next: &EffectKind,
658) -> Result<(), ErrorReport> {
659 if current.family() != next.family() {
660 return Err(ErrorReport::new(
661 ErrorKind::Internal,
662 format!(
663 "a hook patched a {} dispatch into a `{}` effect",
664 current.name(),
665 next.name()
666 ),
667 ));
668 }
669 if let (EffectKind::ToolCall { name: current, .. }, EffectKind::ToolCall { name: next, .. }) =
670 (current, next)
671 && current != next
672 {
673 return Err(ErrorReport::new(
674 ErrorKind::Other,
675 "a dispatch patch cannot change the tool target",
676 ));
677 }
678 Ok(())
679}
680
681impl DispatchAction {
682 pub fn proceed() -> Self {
684 Self::Proceed
685 }
686
687 pub fn patch(kind: EffectKind) -> Self {
689 Self::Patch(kind)
690 }
691
692 pub fn deny(report: ErrorReport) -> Self {
694 Self::Deny(report)
695 }
696
697 pub fn skip(reason: impl Into<String>) -> Self {
699 Self::Deny(ErrorReport::new(ErrorKind::Other, reason))
700 }
701
702 pub fn stop(reason: impl Into<String>) -> Self {
704 Self::Deny(ErrorReport::new(ErrorKind::Cancelled, reason))
705 }
706
707 pub fn rewrite_tool_args(kind: &EffectKind, args: impl Into<serde_json::Value>) -> Self {
710 match kind {
711 EffectKind::ToolCall { name, .. } => Self::Patch(EffectKind::ToolCall {
712 name: name.clone(),
713 args: Into::<serde_json::Value>::into(args).to_string(),
714 }),
715 _ => Self::Proceed,
716 }
717 }
718}
719
720impl<'a> DispatchEvent<'a> {
721 pub fn tool_name(&self) -> Option<&'a str> {
723 match self.kind {
724 EffectKind::ToolCall { name, .. } => Some(name),
725 _ => None,
726 }
727 }
728
729 pub fn tool_args(&self) -> Option<&'a str> {
731 match self.kind {
732 EffectKind::ToolCall { args, .. } => Some(args),
733 _ => None,
734 }
735 }
736
737 pub fn tool_context(&self) -> Option<&'a ToolContext> {
739 self.context
740 }
741
742 pub fn completion_request(&self) -> Option<&'a rig_core::completion::CompletionRequest> {
744 match self.kind {
745 EffectKind::Completion { request, .. } => Some(request),
746 _ => None,
747 }
748 }
749}
750
751#[derive(Clone, Copy)]
753pub struct OutcomeEvent<'a> {
754 pub id: EffectId,
756 pub kind: &'a EffectKind,
758 pub outcome: &'a Result<Answered, ErrorReport>,
760 pub turn: usize,
762 pub call_id: Option<&'a CallId>,
764 pub context: Option<&'a ToolContext>,
766}
767
768#[derive(Debug, Clone)]
770pub enum OutcomeAction {
771 Proceed,
773 Replace(Result<Answered, ErrorReport>),
775}
776
777impl OutcomeAction {
778 pub fn proceed() -> Self {
780 Self::Proceed
781 }
782
783 pub fn replace(outcome: Result<Answered, ErrorReport>) -> Self {
785 Self::Replace(outcome)
786 }
787
788 pub fn stop(reason: impl Into<String>) -> Self {
794 Self::Replace(Err(ErrorReport::new(ErrorKind::Cancelled, reason)))
795 }
796
797 pub fn rewrite_tool_output(event: &OutcomeEvent<'_>, output: ToolOutput) -> Self {
801 match event.outcome {
802 Ok(Answered::ToolResult { result }) => Self::Replace(Ok(Answered::ToolResult {
803 result: result.clone().with_output(output),
804 })),
805 _ => Self::Proceed,
806 }
807 }
808
809 pub fn rewrite_tool_result(event: &OutcomeEvent<'_>, text: impl Into<String>) -> Self {
811 Self::rewrite_tool_output(event, ToolOutput::text(text))
812 }
813}
814
815impl<'a> OutcomeEvent<'a> {
816 pub fn tool_result(&self) -> Option<&'a ToolResult> {
818 match self.outcome {
819 Ok(Answered::ToolResult { result, .. }) => Some(result),
820 _ => None,
821 }
822 }
823
824 pub fn tool_context(&self) -> Option<&'a ToolContext> {
826 self.context
827 }
828
829 pub fn completion(&self) -> Option<&'a rig_core::completion::CompletionResponse> {
831 match self.outcome {
832 Ok(Answered::Completion(response)) => Some(response),
833 _ => None,
834 }
835 }
836
837 pub fn tool_name(&self) -> Option<&'a str> {
839 match self.kind {
840 EffectKind::ToolCall { name, .. } => Some(name),
841 _ => None,
842 }
843 }
844
845 pub fn tool_args(&self) -> Option<&'a str> {
847 match self.kind {
848 EffectKind::ToolCall { args, .. } => Some(args),
849 _ => None,
850 }
851 }
852}
853
854pub use crate::run::patch::RequestPatch;
855
856#[derive(Debug, Clone)]
858pub enum ModelSelectionAction {
859 Continue,
861 Select(ModelRef),
864 Stop(String),
866}
867
868impl ModelSelectionAction {
869 pub fn continue_run() -> Self {
871 Self::Continue
872 }
873
874 pub fn select(model: impl Into<ModelRef>) -> Self {
876 Self::Select(model.into())
877 }
878
879 pub fn stop(reason: impl Into<String>) -> Self {
884 Self::Stop(reason.into())
885 }
886}
887
888#[derive(Debug, Clone, PartialEq)]
890pub enum CompletionCallAction {
891 Continue,
893 Patch(RequestPatch),
895 Stop(String),
897}
898
899impl CompletionCallAction {
900 pub fn continue_run() -> Self {
902 Self::Continue
903 }
904
905 pub fn patch(patch: RequestPatch) -> Self {
907 Self::Patch(patch)
908 }
909
910 pub fn stop(reason: impl Into<String>) -> Self {
912 Self::Stop(reason.into())
913 }
914}
915
916#[derive(Debug, Clone, PartialEq, Eq)]
918pub enum ObservationAction {
919 Continue,
921 Stop(String),
923}
924
925impl ObservationAction {
926 pub fn continue_run() -> Self {
928 Self::Continue
929 }
930
931 pub fn stop(reason: impl Into<String>) -> Self {
933 Self::Stop(reason.into())
934 }
935}
936
937pub trait AgentHook: WasmCompatSend + WasmCompatSync {
939 fn name(&self) -> Option<String> {
942 None
943 }
944
945 fn on_run_start(
952 &self,
953 _ctx: &HookContext,
954 _event: RunStart<'_>,
955 ) -> impl Future<Output = RunStartAction> + WasmCompatSend {
956 async { RunStartAction::Continue }
957 }
958
959 fn on_run_settled(
963 &self,
964 _ctx: &HookContext,
965 _event: RunSettled<'_>,
966 ) -> impl Future<Output = ()> + WasmCompatSend {
967 async {}
968 }
969
970 fn on_model_select(
982 &self,
983 _ctx: &HookContext,
984 _event: ModelSelection<'_>,
985 ) -> ModelSelectionAction {
986 ModelSelectionAction::Continue
987 }
988
989 fn on_completion_call(
994 &self,
995 _ctx: &HookContext,
996 _event: CompletionCallEvent<'_>,
997 ) -> impl Future<Output = CompletionCallAction> + WasmCompatSend {
998 async { CompletionCallAction::Continue }
999 }
1000
1001 fn on_model_turn_finished(
1006 &self,
1007 _ctx: &HookContext,
1008 _event: ModelTurnFinished<'_>,
1009 ) -> impl Future<Output = ModelTurnAction> + WasmCompatSend {
1010 async { ModelTurnAction::Continue }
1011 }
1012
1013 fn on_invalid_tool_call(
1029 &self,
1030 _ctx: &HookContext,
1031 _event: &InvalidToolCallContext,
1032 ) -> impl Future<Output = Option<InvalidToolCallAction>> + WasmCompatSend {
1033 async { None }
1034 }
1035
1036 fn on_text_delta(
1040 &self,
1041 _ctx: &HookContext,
1042 _event: TextDelta<'_>,
1043 ) -> impl Future<Output = ObservationAction> + WasmCompatSend {
1044 async { ObservationAction::Continue }
1045 }
1046
1047 fn on_reasoning_delta(
1053 &self,
1054 _ctx: &HookContext,
1055 _event: ReasoningDelta<'_>,
1056 ) -> impl Future<Output = ObservationAction> + WasmCompatSend {
1057 async { ObservationAction::Continue }
1058 }
1059
1060 fn on_tool_call_delta(
1067 &self,
1068 _ctx: &HookContext,
1069 _event: ToolCallDelta<'_>,
1070 ) -> impl Future<Output = ObservationAction> + WasmCompatSend {
1071 async { ObservationAction::Continue }
1072 }
1073
1074 fn on_dispatch(
1086 &self,
1087 _ctx: &HookContext,
1088 _event: DispatchEvent<'_>,
1089 ) -> impl Future<Output = DispatchAction> + WasmCompatSend {
1090 async { DispatchAction::Proceed }
1091 }
1092
1093 fn on_outcome(
1105 &self,
1106 _ctx: &HookContext,
1107 _event: OutcomeEvent<'_>,
1108 ) -> impl Future<Output = OutcomeAction> + WasmCompatSend {
1109 async { OutcomeAction::Proceed }
1110 }
1111
1112 fn observes(&self, kind: StepEventKind) -> bool {
1117 !matches!(
1118 kind,
1119 StepEventKind::EmbedDispatch
1120 | StepEventKind::RerankDispatch
1121 | StepEventKind::RetrieveDispatch
1122 | StepEventKind::CustomDispatch
1123 )
1124 }
1125}
1126
1127impl AgentHook for () {
1128 fn observes(&self, _kind: StepEventKind) -> bool {
1129 false
1130 }
1131}
1132
1133macro_rules! for_each_boxed_hook_event {
1137 ($m:ident) => {
1138 $m!(
1139 completion_call,
1140 on_completion_call,
1141 CompletionCallEvent,
1142 CompletionCallAction
1143 );
1144 $m!(
1145 model_turn_finished,
1146 on_model_turn_finished,
1147 ModelTurnFinished,
1148 ModelTurnAction
1149 );
1150 $m!(text_delta, on_text_delta, TextDelta, ObservationAction);
1151 $m!(
1152 reasoning_delta,
1153 on_reasoning_delta,
1154 ReasoningDelta,
1155 ObservationAction
1156 );
1157 $m!(
1158 tool_call_delta,
1159 on_tool_call_delta,
1160 ToolCallDelta,
1161 ObservationAction
1162 );
1163 };
1164}
1165
1166macro_rules! erased_hook_decl {
1167 ($erased:ident, $on:ident, $event:ident, $action:ident) => {
1168 fn $erased<'a>(
1169 &'a self,
1170 ctx: &'a HookContext,
1171 event: $event<'a>,
1172 ) -> WasmBoxedFuture<'a, $action>;
1173 };
1174}
1175
1176macro_rules! erased_hook_forward {
1177 ($erased:ident, $on:ident, $event:ident, $action:ident) => {
1178 fn $erased<'a>(
1179 &'a self,
1180 ctx: &'a HookContext,
1181 event: $event<'a>,
1182 ) -> WasmBoxedFuture<'a, $action> {
1183 Box::pin(self.$on(ctx, event))
1184 }
1185 };
1186}
1187
1188trait DynAgentHook: WasmCompatSend + WasmCompatSync {
1189 fn run_start<'a>(
1190 &'a self,
1191 ctx: &'a HookContext,
1192 event: RunStart<'a>,
1193 ) -> WasmBoxedFuture<'a, RunStartAction>;
1194 fn run_settled<'a>(
1195 &'a self,
1196 ctx: &'a HookContext,
1197 event: RunSettled<'a>,
1198 ) -> WasmBoxedFuture<'a, ()>;
1199 fn model_select(&self, ctx: &HookContext, event: ModelSelection<'_>) -> ModelSelectionAction;
1200 fn invalid_tool_call<'a>(
1201 &'a self,
1202 ctx: &'a HookContext,
1203 event: &'a InvalidToolCallContext,
1204 ) -> WasmBoxedFuture<'a, Option<InvalidToolCallAction>>;
1205 fn dispatch<'a>(
1206 &'a self,
1207 ctx: &'a HookContext,
1208 event: DispatchEvent<'a>,
1209 ) -> WasmBoxedFuture<'a, DispatchAction>;
1210 fn outcome<'a>(
1211 &'a self,
1212 ctx: &'a HookContext,
1213 event: OutcomeEvent<'a>,
1214 ) -> WasmBoxedFuture<'a, OutcomeAction>;
1215 for_each_boxed_hook_event!(erased_hook_decl);
1216 fn observes(&self, kind: StepEventKind) -> bool;
1217}
1218
1219impl<H> DynAgentHook for H
1220where
1221 H: AgentHook,
1222{
1223 fn run_start<'a>(
1224 &'a self,
1225 ctx: &'a HookContext,
1226 event: RunStart<'a>,
1227 ) -> WasmBoxedFuture<'a, RunStartAction> {
1228 Box::pin(self.on_run_start(ctx, event))
1229 }
1230
1231 fn run_settled<'a>(
1232 &'a self,
1233 ctx: &'a HookContext,
1234 event: RunSettled<'a>,
1235 ) -> WasmBoxedFuture<'a, ()> {
1236 Box::pin(self.on_run_settled(ctx, event))
1237 }
1238
1239 fn model_select(&self, ctx: &HookContext, event: ModelSelection<'_>) -> ModelSelectionAction {
1240 self.on_model_select(ctx, event)
1241 }
1242
1243 fn invalid_tool_call<'a>(
1244 &'a self,
1245 ctx: &'a HookContext,
1246 event: &'a InvalidToolCallContext,
1247 ) -> WasmBoxedFuture<'a, Option<InvalidToolCallAction>> {
1248 Box::pin(self.on_invalid_tool_call(ctx, event))
1249 }
1250 fn dispatch<'a>(
1251 &'a self,
1252 ctx: &'a HookContext,
1253 event: DispatchEvent<'a>,
1254 ) -> WasmBoxedFuture<'a, DispatchAction> {
1255 Box::pin(self.on_dispatch(ctx, event))
1256 }
1257 fn outcome<'a>(
1258 &'a self,
1259 ctx: &'a HookContext,
1260 event: OutcomeEvent<'a>,
1261 ) -> WasmBoxedFuture<'a, OutcomeAction> {
1262 Box::pin(self.on_outcome(ctx, event))
1263 }
1264 for_each_boxed_hook_event!(erased_hook_forward);
1265 fn observes(&self, kind: StepEventKind) -> bool {
1266 AgentHook::observes(self, kind)
1267 }
1268}
1269
1270#[derive(Clone, Default)]
1276pub struct HookStack {
1277 hooks: Vec<Arc<dyn DynAgentHook>>,
1278 names: Vec<String>,
1282}
1283
1284impl std::fmt::Debug for HookStack {
1285 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1286 f.debug_struct("HookStack")
1287 .field("len", &self.hooks.len())
1288 .finish()
1289 }
1290}
1291
1292fn short_type_name<H>() -> &'static str {
1295 let full = std::any::type_name::<H>();
1296 let generics = full.find('<').unwrap_or(full.len());
1297 let path = &full[..generics];
1298 match path.rfind("::") {
1299 Some(at) => &full[at + 2..],
1300 None => full,
1301 }
1302}
1303
1304impl HookStack {
1305 pub fn new() -> Self {
1307 Self::default()
1308 }
1309
1310 pub fn with<H: AgentHook + 'static>(hook: H) -> Self {
1312 let mut stack = Self::new();
1313 stack.push(hook);
1314 stack
1315 }
1316
1317 pub fn push<H: AgentHook + 'static>(&mut self, hook: H) {
1320 match (&hook as &dyn std::any::Any).downcast_ref::<HookStack>() {
1323 Some(nested) => self.names.extend(nested.names.iter().cloned()),
1324 None => self.names.push(
1325 hook.name()
1326 .unwrap_or_else(|| short_type_name::<H>().to_owned()),
1327 ),
1328 }
1329 self.hooks.push(Arc::new(hook));
1330 }
1331
1332 pub fn names(&self) -> Vec<String> {
1334 self.names.clone()
1335 }
1336
1337 pub fn is_empty(&self) -> bool {
1339 self.hooks.is_empty()
1340 }
1341
1342 pub fn len(&self) -> usize {
1344 self.hooks.len()
1345 }
1346}
1347
1348trait ShortCircuitAction: Sized {
1352 const CONTINUE: Self;
1353 fn is_continue(&self) -> bool;
1354}
1355
1356impl ShortCircuitAction for ObservationAction {
1357 const CONTINUE: Self = ObservationAction::Continue;
1358 fn is_continue(&self) -> bool {
1359 matches!(self, ObservationAction::Continue)
1360 }
1361}
1362
1363impl ShortCircuitAction for ModelTurnAction {
1364 const CONTINUE: Self = ModelTurnAction::Continue;
1365 fn is_continue(&self) -> bool {
1366 matches!(self, ModelTurnAction::Continue)
1367 }
1368}
1369
1370async fn first_non_continue<'a, A, F>(hooks: &'a [Arc<dyn DynAgentHook>], mut dispatch: F) -> A
1373where
1374 A: ShortCircuitAction,
1375 F: FnMut(&'a dyn DynAgentHook) -> WasmBoxedFuture<'a, A>,
1376{
1377 for hook in hooks {
1378 let action = dispatch(hook.as_ref()).await;
1379 if !action.is_continue() {
1380 return action;
1381 }
1382 }
1383 A::CONTINUE
1384}
1385
1386macro_rules! stack_first_non_continue {
1392 ($($on:ident, $erased:ident, $event:ident, $action:ident;)+) => {
1393 $(
1394 async fn $on(&self, ctx: &HookContext, event: $event<'_>) -> $action {
1395 first_non_continue(&self.hooks, |hook| hook.$erased(ctx, event)).await
1396 }
1397 )+
1398 };
1399}
1400
1401impl AgentHook for HookStack {
1402 async fn on_run_start(&self, ctx: &HookContext, event: RunStart<'_>) -> RunStartAction {
1403 let mut rewritten: Option<Message> = None;
1404 for hook in &self.hooks {
1405 let current = RunStart {
1406 prompt: rewritten.as_ref().unwrap_or(event.prompt),
1407 ..event
1408 };
1409 match hook.run_start(ctx, current).await {
1410 RunStartAction::Continue => {}
1411 RunStartAction::Rewrite(prompt) => rewritten = Some(prompt),
1412 stop @ RunStartAction::Stop(_) => return stop,
1413 }
1414 }
1415 rewritten.map_or(RunStartAction::Continue, RunStartAction::Rewrite)
1416 }
1417
1418 async fn on_run_settled(&self, ctx: &HookContext, event: RunSettled<'_>) {
1419 for hook in &self.hooks {
1420 hook.run_settled(ctx, event).await;
1421 }
1422 }
1423
1424 fn on_model_select(
1425 &self,
1426 ctx: &HookContext,
1427 event: ModelSelection<'_>,
1428 ) -> ModelSelectionAction {
1429 let mut selected = None;
1430 for hook in &self.hooks {
1431 let action = {
1432 let selected_model = selected.as_ref().unwrap_or(event.selected_model);
1433 hook.model_select(
1434 ctx,
1435 ModelSelection {
1436 selected_model,
1437 ..event
1438 },
1439 )
1440 };
1441 match action {
1442 ModelSelectionAction::Continue => {}
1443 ModelSelectionAction::Select(model) => selected = Some(model),
1444 stop @ ModelSelectionAction::Stop(_) => return stop,
1445 }
1446 }
1447 selected.map_or(ModelSelectionAction::Continue, ModelSelectionAction::Select)
1448 }
1449
1450 async fn on_completion_call(
1451 &self,
1452 ctx: &HookContext,
1453 event: CompletionCallEvent<'_>,
1454 ) -> CompletionCallAction {
1455 let mut merged: Option<RequestPatch> = None;
1456 for hook in &self.hooks {
1457 match hook.completion_call(ctx, event).await {
1458 CompletionCallAction::Continue => {}
1459 CompletionCallAction::Patch(patch) => {
1460 merged = Some(match merged {
1461 None => patch,
1462 Some(value) => value.merge(patch),
1463 });
1464 }
1465 stop @ CompletionCallAction::Stop(_) => return stop,
1466 }
1467 }
1468 match merged {
1469 Some(patch) if !patch.is_empty() => CompletionCallAction::Patch(patch),
1470 _ => CompletionCallAction::Continue,
1471 }
1472 }
1473
1474 stack_first_non_continue! {
1475 on_model_turn_finished, model_turn_finished, ModelTurnFinished, ModelTurnAction;
1476 on_text_delta, text_delta, TextDelta, ObservationAction;
1477 on_reasoning_delta, reasoning_delta, ReasoningDelta, ObservationAction;
1478 on_tool_call_delta, tool_call_delta, ToolCallDelta, ObservationAction;
1479 }
1480 async fn on_invalid_tool_call(
1481 &self,
1482 ctx: &HookContext,
1483 event: &InvalidToolCallContext,
1484 ) -> Option<InvalidToolCallAction> {
1485 for hook in &self.hooks {
1486 if let Some(action) = hook.invalid_tool_call(ctx, event).await {
1487 return Some(action);
1488 }
1489 }
1490 None
1491 }
1492 async fn on_dispatch(&self, ctx: &HookContext, event: DispatchEvent<'_>) -> DispatchAction {
1493 let kind = StepEventKind::for_family(event.kind.family());
1494 let mut patched: Option<EffectKind> = None;
1495 for hook in &self.hooks {
1496 if !hook.observes(kind) {
1497 continue;
1498 }
1499 let current = DispatchEvent {
1500 kind: patched.as_ref().unwrap_or(event.kind),
1501 ..event
1502 };
1503 match hook.dispatch(ctx, current).await {
1504 DispatchAction::Proceed => {}
1505 DispatchAction::Patch(next) => {
1506 if let Err(report) = validate_dispatch_patch(current.kind, &next) {
1507 if let Some(kind) = patched {
1508 ctx.salvage_patch(event.id, kind);
1509 }
1510 return DispatchAction::Deny(report);
1511 }
1512 patched = Some(next);
1513 }
1514 deny @ DispatchAction::Deny(_) => {
1515 if let Some(kind) = patched {
1518 ctx.salvage_patch(event.id, kind);
1519 }
1520 return deny;
1521 }
1522 }
1523 }
1524 patched.map_or(DispatchAction::Proceed, DispatchAction::Patch)
1525 }
1526
1527 async fn on_outcome(&self, ctx: &HookContext, event: OutcomeEvent<'_>) -> OutcomeAction {
1528 let kind = StepEventKind::for_family(event.kind.family());
1529 let mut replaced: Option<Result<Answered, ErrorReport>> = None;
1530 for hook in &self.hooks {
1531 if !hook.observes(kind) {
1532 continue;
1533 }
1534 let current = OutcomeEvent {
1535 outcome: replaced.as_ref().unwrap_or(event.outcome),
1536 ..event
1537 };
1538 match hook.outcome(ctx, current).await {
1539 OutcomeAction::Proceed => {}
1540 OutcomeAction::Replace(next) => {
1541 if matches!(&next, Err(report) if report.kind == ErrorKind::Cancelled) {
1542 return OutcomeAction::Replace(next);
1543 }
1544 replaced = Some(next);
1545 }
1546 }
1547 }
1548 replaced.map_or(OutcomeAction::Proceed, OutcomeAction::Replace)
1549 }
1550
1551 fn observes(&self, kind: StepEventKind) -> bool {
1552 self.hooks.iter().any(|hook| hook.observes(kind))
1553 }
1554}
1555
1556#[cfg(test)]
1557mod tests;