1use std::collections::HashSet;
49use std::future::Future;
50use std::sync::Arc;
51
52use async_trait::async_trait;
53use serde::{Deserialize, Serialize};
54use serde_json::Value;
55
56use crate::error::{Result, RustyError};
57use crate::llm::{ChatMessage, ChatModel, ChatResponse, ToolCall};
58use crate::node::NodeOutput;
59use crate::state::State;
60
61#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
63#[serde(rename_all = "snake_case")]
64pub enum InterceptPoint {
65 NodeRun,
67 ModelCall,
69 ToolCall,
71}
72
73impl std::fmt::Display for InterceptPoint {
74 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
75 let s = match self {
76 InterceptPoint::NodeRun => "node_run",
77 InterceptPoint::ModelCall => "model_call",
78 InterceptPoint::ToolCall => "tool_call",
79 };
80 f.write_str(s)
81 }
82}
83
84#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
93pub struct Rejection {
94 pub middleware: String,
96 pub point: InterceptPoint,
98 pub reason: String,
100 #[serde(default, skip_serializing_if = "Option::is_none")]
102 pub detail: Option<String>,
103}
104
105impl Rejection {
106 pub fn new(
108 middleware: impl Into<String>,
109 point: InterceptPoint,
110 reason: impl Into<String>,
111 ) -> Self {
112 Self {
113 middleware: middleware.into(),
114 point,
115 reason: reason.into(),
116 detail: None,
117 }
118 }
119
120 pub fn with_detail(mut self, detail: impl Into<String>) -> Self {
122 self.detail = Some(detail.into());
123 self
124 }
125}
126
127impl std::fmt::Display for Rejection {
128 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
129 write!(
130 f,
131 "rejected by middleware `{}` at {}: {}",
132 self.middleware, self.point, self.reason
133 )
134 }
135}
136
137impl Rejection {
138 pub(crate) fn into_error(self) -> RustyError {
141 let message = self.to_string();
142 match self.point {
143 InterceptPoint::NodeRun => RustyError::Node(message),
144 InterceptPoint::ModelCall => RustyError::Llm(message),
145 InterceptPoint::ToolCall => RustyError::Tool(message),
146 }
147 }
148}
149
150#[derive(Debug, Clone, PartialEq)]
155pub enum Decision<R> {
156 Continue,
159 Reject(Rejection),
161 ShortCircuit(R),
166}
167
168#[derive(Debug, Clone)]
173pub struct NodeCall {
174 thread_id: String,
175 node: String,
176 step: usize,
177 state: State,
178}
179
180impl NodeCall {
181 pub fn new(
183 thread_id: impl Into<String>,
184 node: impl Into<String>,
185 step: usize,
186 state: State,
187 ) -> Self {
188 Self {
189 thread_id: thread_id.into(),
190 node: node.into(),
191 step,
192 state,
193 }
194 }
195
196 pub fn thread_id(&self) -> &str {
198 &self.thread_id
199 }
200
201 pub fn node(&self) -> &str {
203 &self.node
204 }
205
206 pub fn step(&self) -> usize {
208 self.step
209 }
210
211 pub fn state(&self) -> &State {
213 &self.state
214 }
215
216 pub fn state_mut(&mut self) -> &mut State {
218 &mut self.state
219 }
220
221 pub fn insert(&mut self, channel: impl Into<String>, value: Value) {
223 self.state.insert(channel, value);
224 }
225}
226
227#[derive(Debug, Clone)]
230pub struct ModelCall {
231 thread_id: String,
232 node: String,
233 messages: Vec<ChatMessage>,
234 tools: Vec<Value>,
235}
236
237impl ModelCall {
238 pub fn new(
240 thread_id: impl Into<String>,
241 node: impl Into<String>,
242 messages: Vec<ChatMessage>,
243 tools: Vec<Value>,
244 ) -> Self {
245 Self {
246 thread_id: thread_id.into(),
247 node: node.into(),
248 messages,
249 tools,
250 }
251 }
252
253 pub fn thread_id(&self) -> &str {
255 &self.thread_id
256 }
257
258 pub fn node(&self) -> &str {
260 &self.node
261 }
262
263 pub fn messages(&self) -> &[ChatMessage] {
265 &self.messages
266 }
267
268 pub fn messages_mut(&mut self) -> &mut Vec<ChatMessage> {
270 &mut self.messages
271 }
272
273 pub fn tools(&self) -> &[Value] {
275 &self.tools
276 }
277
278 pub fn tools_mut(&mut self) -> &mut Vec<Value> {
280 &mut self.tools
281 }
282}
283
284#[derive(Debug, Clone)]
289pub struct ToolInvocation {
290 thread_id: String,
291 node: String,
292 call: ToolCall,
293}
294
295impl ToolInvocation {
296 pub fn new(thread_id: impl Into<String>, node: impl Into<String>, call: ToolCall) -> Self {
298 Self {
299 thread_id: thread_id.into(),
300 node: node.into(),
301 call,
302 }
303 }
304
305 pub fn thread_id(&self) -> &str {
307 &self.thread_id
308 }
309
310 pub fn node(&self) -> &str {
312 &self.node
313 }
314
315 pub fn call(&self) -> &ToolCall {
317 &self.call
318 }
319
320 pub fn call_mut(&mut self) -> &mut ToolCall {
322 &mut self.call
323 }
324
325 pub fn id(&self) -> &str {
327 &self.call.id
328 }
329
330 pub fn name(&self) -> &str {
332 &self.call.name
333 }
334
335 pub fn arguments(&self) -> &Value {
337 &self.call.arguments
338 }
339
340 pub fn set_arguments(&mut self, arguments: Value) {
342 self.call.arguments = arguments;
343 }
344}
345
346#[async_trait]
352pub trait Middleware: Send + Sync {
353 fn name(&self) -> &str;
355
356 async fn before_node(&self, call: &mut NodeCall) -> Decision<NodeOutput> {
358 let _ = call;
359 Decision::Continue
360 }
361
362 async fn after_node(&self, call: &NodeCall, output: &mut NodeOutput) -> Decision<NodeOutput> {
364 let _ = (call, output);
365 Decision::Continue
366 }
367
368 async fn before_model(&self, call: &mut ModelCall) -> Decision<ChatResponse> {
370 let _ = call;
371 Decision::Continue
372 }
373
374 async fn after_model(
376 &self,
377 call: &ModelCall,
378 response: &mut ChatResponse,
379 ) -> Decision<ChatResponse> {
380 let _ = (call, response);
381 Decision::Continue
382 }
383
384 async fn before_tool(&self, call: &mut ToolInvocation) -> Decision<Value> {
386 let _ = call;
387 Decision::Continue
388 }
389
390 async fn after_tool(&self, call: &ToolInvocation, result: &mut Value) -> Decision<Value> {
392 let _ = (call, result);
393 Decision::Continue
394 }
395}
396
397#[derive(Clone, Default)]
403pub struct MiddlewareChain {
404 layers: Vec<Arc<dyn Middleware>>,
405}
406
407impl std::fmt::Debug for MiddlewareChain {
408 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
409 f.debug_struct("MiddlewareChain")
410 .field(
411 "layers",
412 &self.layers.iter().map(|l| l.name()).collect::<Vec<_>>(),
413 )
414 .finish()
415 }
416}
417
418impl MiddlewareChain {
419 pub fn new() -> Self {
421 Self::default()
422 }
423
424 pub fn layer<M: Middleware + 'static>(mut self, middleware: M) -> Self {
427 self.push(Arc::new(middleware));
428 self
429 }
430
431 pub fn push(&mut self, middleware: Arc<dyn Middleware>) -> &mut Self {
433 self.layers.push(middleware);
434 self
435 }
436
437 pub fn is_empty(&self) -> bool {
439 self.layers.is_empty()
440 }
441
442 pub fn len(&self) -> usize {
444 self.layers.len()
445 }
446
447 pub fn names(&self) -> impl Iterator<Item = &str> {
449 self.layers.iter().map(|l| l.name())
450 }
451
452 pub async fn run_node<F, Fut>(&self, call: &mut NodeCall, op: F) -> Result<NodeOutput>
455 where
456 F: FnOnce(&NodeCall) -> Fut + Send,
457 Fut: Future<Output = Result<NodeOutput>> + Send,
458 {
459 let mut entered = 0;
460 let mut substitute = None;
461 for layer in &self.layers {
462 match layer.before_node(call).await {
463 Decision::Continue => entered += 1,
464 Decision::Reject(rejection) => return Err(rejection.into_error()),
465 Decision::ShortCircuit(output) => {
466 substitute = Some(output);
467 break;
468 }
469 }
470 }
471 let mut result = match substitute {
472 Some(output) => output,
473 None => {
474 entered = self.layers.len();
475 op(call).await?
476 }
477 };
478 for layer in self.layers[..entered].iter().rev() {
479 match layer.after_node(call, &mut result).await {
480 Decision::Continue => {}
481 Decision::Reject(rejection) => return Err(rejection.into_error()),
482 Decision::ShortCircuit(output) => {
483 result = output;
484 break;
485 }
486 }
487 }
488 Ok(result)
489 }
490
491 pub async fn run_model<F, Fut>(&self, call: &mut ModelCall, op: F) -> Result<ChatResponse>
494 where
495 F: FnOnce(&ModelCall) -> Fut + Send,
496 Fut: Future<Output = Result<ChatResponse>> + Send,
497 {
498 let mut entered = 0;
499 let mut substitute = None;
500 for layer in &self.layers {
501 match layer.before_model(call).await {
502 Decision::Continue => entered += 1,
503 Decision::Reject(rejection) => return Err(rejection.into_error()),
504 Decision::ShortCircuit(response) => {
505 substitute = Some(response);
506 break;
507 }
508 }
509 }
510 let mut result = match substitute {
511 Some(response) => response,
512 None => {
513 entered = self.layers.len();
514 op(call).await?
515 }
516 };
517 for layer in self.layers[..entered].iter().rev() {
518 match layer.after_model(call, &mut result).await {
519 Decision::Continue => {}
520 Decision::Reject(rejection) => return Err(rejection.into_error()),
521 Decision::ShortCircuit(response) => {
522 result = response;
523 break;
524 }
525 }
526 }
527 Ok(result)
528 }
529
530 pub async fn run_tool<F, Fut>(&self, call: &mut ToolInvocation, op: F) -> Result<Value>
533 where
534 F: FnOnce(&ToolInvocation) -> Fut + Send,
535 Fut: Future<Output = Result<Value>> + Send,
536 {
537 let mut entered = 0;
538 let mut substitute = None;
539 for layer in &self.layers {
540 match layer.before_tool(call).await {
541 Decision::Continue => entered += 1,
542 Decision::Reject(rejection) => return Err(rejection.into_error()),
543 Decision::ShortCircuit(value) => {
544 substitute = Some(value);
545 break;
546 }
547 }
548 }
549 let mut result = match substitute {
550 Some(value) => value,
551 None => {
552 entered = self.layers.len();
553 op(call).await?
554 }
555 };
556 for layer in self.layers[..entered].iter().rev() {
557 match layer.after_tool(call, &mut result).await {
558 Decision::Continue => {}
559 Decision::Reject(rejection) => return Err(rejection.into_error()),
560 Decision::ShortCircuit(value) => {
561 result = value;
562 break;
563 }
564 }
565 }
566 Ok(result)
567 }
568}
569
570#[derive(Clone)]
580pub struct MiddlewareChatModel {
581 inner: Arc<dyn ChatModel>,
582 chain: MiddlewareChain,
583 thread_id: String,
584 node: String,
585}
586
587impl MiddlewareChatModel {
588 pub fn new(inner: Arc<dyn ChatModel>, chain: MiddlewareChain) -> Self {
590 Self {
591 inner,
592 chain,
593 thread_id: String::new(),
594 node: String::new(),
595 }
596 }
597
598 pub fn thread(mut self, thread_id: impl Into<String>) -> Self {
600 self.thread_id = thread_id.into();
601 self
602 }
603
604 pub fn node(mut self, node: impl Into<String>) -> Self {
606 self.node = node.into();
607 self
608 }
609}
610
611#[async_trait]
612impl ChatModel for MiddlewareChatModel {
613 async fn chat(&self, messages: &[ChatMessage], tools: &[Value]) -> Result<ChatResponse> {
614 if self.chain.is_empty() {
615 return self.inner.chat(messages, tools).await;
616 }
617 let mut call = ModelCall::new(
618 self.thread_id.clone(),
619 self.node.clone(),
620 messages.to_vec(),
621 tools.to_vec(),
622 );
623 self.chain
624 .run_model(&mut call, |call| {
625 let inner = Arc::clone(&self.inner);
626 let messages = call.messages().to_vec();
627 let tools = call.tools().to_vec();
628 async move { inner.chat(&messages, &tools).await }
629 })
630 .await
631 }
632
633 fn effect(&self) -> crate::record::Effect {
634 self.inner.effect()
635 }
636}
637
638#[derive(Debug, Default)]
645pub struct RequestLogger;
646
647impl RequestLogger {
648 pub fn new() -> Self {
650 Self
651 }
652}
653
654#[async_trait]
655impl Middleware for RequestLogger {
656 fn name(&self) -> &str {
657 "request_logger"
658 }
659
660 async fn before_node(&self, call: &mut NodeCall) -> Decision<NodeOutput> {
661 tracing::info!(
662 thread_id = %call.thread_id(),
663 node = %call.node(),
664 step = call.step(),
665 "middleware: node run started"
666 );
667 Decision::Continue
668 }
669
670 async fn after_node(&self, call: &NodeCall, output: &mut NodeOutput) -> Decision<NodeOutput> {
671 tracing::info!(
672 thread_id = %call.thread_id(),
673 node = %call.node(),
674 step = call.step(),
675 channels = output.updates.len(),
676 "middleware: node run completed"
677 );
678 Decision::Continue
679 }
680
681 async fn before_model(&self, call: &mut ModelCall) -> Decision<ChatResponse> {
682 tracing::info!(
683 thread_id = %call.thread_id(),
684 node = %call.node(),
685 messages = call.messages().len(),
686 tools = call.tools().len(),
687 "middleware: model call started"
688 );
689 Decision::Continue
690 }
691
692 async fn after_model(
693 &self,
694 call: &ModelCall,
695 response: &mut ChatResponse,
696 ) -> Decision<ChatResponse> {
697 tracing::info!(
698 thread_id = %call.thread_id(),
699 node = %call.node(),
700 total_tokens = response.usage.map(|u| u.total_tokens),
701 "middleware: model call completed"
702 );
703 Decision::Continue
704 }
705
706 async fn before_tool(&self, call: &mut ToolInvocation) -> Decision<Value> {
707 tracing::info!(
708 thread_id = %call.thread_id(),
709 node = %call.node(),
710 tool = %call.name(),
711 call_id = %call.id(),
712 "middleware: tool call started"
713 );
714 Decision::Continue
715 }
716
717 async fn after_tool(&self, call: &ToolInvocation, result: &mut Value) -> Decision<Value> {
718 let _ = result;
719 tracing::info!(
720 thread_id = %call.thread_id(),
721 node = %call.node(),
722 tool = %call.name(),
723 call_id = %call.id(),
724 "middleware: tool call completed"
725 );
726 Decision::Continue
727 }
728}
729
730#[derive(Debug, Clone)]
735pub struct ToolCallBlocklist {
736 blocked: HashSet<String>,
737 reason: String,
738}
739
740impl ToolCallBlocklist {
741 pub fn new<I, S>(tools: I) -> Self
743 where
744 I: IntoIterator<Item = S>,
745 S: Into<String>,
746 {
747 Self {
748 blocked: tools.into_iter().map(Into::into).collect(),
749 reason: "tool_blocked".to_owned(),
750 }
751 }
752
753 pub fn with_reason(mut self, reason: impl Into<String>) -> Self {
755 self.reason = reason.into();
756 self
757 }
758
759 pub fn contains(&self, tool: &str) -> bool {
761 self.blocked.contains(tool)
762 }
763}
764
765#[async_trait]
766impl Middleware for ToolCallBlocklist {
767 fn name(&self) -> &str {
768 "tool_call_blocklist"
769 }
770
771 async fn before_tool(&self, call: &mut ToolInvocation) -> Decision<Value> {
772 if self.blocked.contains(call.name()) {
773 Decision::Reject(
774 Rejection::new(self.name(), InterceptPoint::ToolCall, self.reason.clone())
775 .with_detail(format!("tool `{}` is blocked by policy", call.name())),
776 )
777 } else {
778 Decision::Continue
779 }
780 }
781}
782
783#[cfg(test)]
784mod tests {
785 use super::*;
786 use serde_json::json;
787 use std::sync::Mutex;
788
789 #[derive(Clone, Default)]
791 struct Trace(Arc<Mutex<Vec<String>>>);
792
793 impl Trace {
794 fn record(&self, entry: impl Into<String>) {
795 self.0.lock().expect("trace lock").push(entry.into());
796 }
797
798 fn entries(&self) -> Vec<String> {
799 self.0.lock().expect("trace lock").clone()
800 }
801 }
802
803 struct Recorder {
805 id: &'static str,
806 trace: Trace,
807 }
808
809 #[async_trait]
810 impl Middleware for Recorder {
811 fn name(&self) -> &str {
812 self.id
813 }
814
815 async fn before_node(&self, call: &mut NodeCall) -> Decision<NodeOutput> {
816 self.trace
817 .record(format!("{}:before:{}", self.id, call.node()));
818 Decision::Continue
819 }
820
821 async fn after_node(
822 &self,
823 call: &NodeCall,
824 _output: &mut NodeOutput,
825 ) -> Decision<NodeOutput> {
826 self.trace
827 .record(format!("{}:after:{}", self.id, call.node()));
828 Decision::Continue
829 }
830 }
831
832 #[tokio::test]
833 async fn empty_chain_passes_through() {
834 let chain = MiddlewareChain::new();
835 assert!(chain.is_empty());
836 let mut call = NodeCall::new("t-1", "node-a", 0, State::new());
837 let result = chain
838 .run_node(&mut call, |_call| async {
839 Ok(NodeOutput::update("x", json!(1)))
840 })
841 .await
842 .unwrap();
843 assert_eq!(result.updates.get("x"), Some(&json!(1)));
844 }
845
846 #[tokio::test]
847 async fn before_hooks_run_in_registration_order_after_hooks_in_reverse() {
848 let trace = Trace::default();
849 let chain = MiddlewareChain::new()
850 .layer(Recorder {
851 id: "L1",
852 trace: trace.clone(),
853 })
854 .layer(Recorder {
855 id: "L2",
856 trace: trace.clone(),
857 })
858 .layer(Recorder {
859 id: "L3",
860 trace: trace.clone(),
861 });
862 assert_eq!(chain.len(), 3);
863 assert_eq!(chain.names().collect::<Vec<_>>(), ["L1", "L2", "L3"]);
864
865 let op_trace = trace.clone();
866 let mut call = NodeCall::new("t-1", "node-a", 0, State::new());
867 let result = chain
868 .run_node(&mut call, |_call| {
869 let op_trace = op_trace.clone();
870 async move {
871 op_trace.record("op");
872 Ok(NodeOutput::update("x", json!(1)))
873 }
874 })
875 .await
876 .unwrap();
877
878 assert_eq!(result.updates.get("x"), Some(&json!(1)));
879 assert_eq!(
880 trace.entries(),
881 vec![
882 "L1:before:node-a",
883 "L2:before:node-a",
884 "L3:before:node-a",
885 "op",
886 "L3:after:node-a",
887 "L2:after:node-a",
888 "L1:after:node-a",
889 ]
890 );
891 }
892
893 struct Mutate;
895
896 #[async_trait]
897 impl Middleware for Mutate {
898 fn name(&self) -> &str {
899 "mutate"
900 }
901
902 async fn before_node(&self, call: &mut NodeCall) -> Decision<NodeOutput> {
903 call.insert("injected", json!(true));
904 Decision::Continue
905 }
906
907 async fn after_node(
908 &self,
909 _call: &NodeCall,
910 output: &mut NodeOutput,
911 ) -> Decision<NodeOutput> {
912 output.updates.insert("x".into(), json!("rewritten"));
913 Decision::Continue
914 }
915 }
916
917 #[tokio::test]
918 async fn mutations_propagate_inward_and_outward() {
919 let chain = MiddlewareChain::new().layer(Mutate);
920 let mut call = NodeCall::new("t-1", "node-a", 0, State::new());
921 let result = chain
922 .run_node(&mut call, |call| {
923 assert_eq!(call.state().get("injected"), Some(&json!(true)));
925 async move { Ok(NodeOutput::update("x", json!("original"))) }
926 })
927 .await
928 .unwrap();
929 assert_eq!(result.updates.get("x"), Some(&json!("rewritten")));
931 }
932
933 struct PolicyReject {
934 reason: &'static str,
935 }
936
937 #[async_trait]
938 impl Middleware for PolicyReject {
939 fn name(&self) -> &str {
940 "policy_reject"
941 }
942
943 async fn before_node(&self, _call: &mut NodeCall) -> Decision<NodeOutput> {
944 Decision::Reject(
945 Rejection::new(self.name(), InterceptPoint::NodeRun, self.reason)
946 .with_detail("denied by test policy"),
947 )
948 }
949 }
950
951 #[tokio::test]
952 async fn reject_skips_operation_and_all_after_hooks() {
953 let trace = Trace::default();
954 let chain = MiddlewareChain::new()
955 .layer(Recorder {
956 id: "L1",
957 trace: trace.clone(),
958 })
959 .layer(PolicyReject { reason: "policy" })
960 .layer(Recorder {
961 id: "L3",
962 trace: trace.clone(),
963 });
964
965 let op_ran = Arc::new(std::sync::atomic::AtomicBool::new(false));
966 let op_flag = op_ran.clone();
967 let mut call = NodeCall::new("t-1", "node-b", 2, State::new());
968 let err = chain
969 .run_node(&mut call, |_call| {
970 let op_flag = op_flag.clone();
971 async move {
972 op_flag.store(true, std::sync::atomic::Ordering::SeqCst);
973 Ok(NodeOutput::empty())
974 }
975 })
976 .await
977 .unwrap_err();
978
979 match err {
980 RustyError::Node(message) => {
981 assert!(
984 message.contains("rejected by middleware `policy_reject` at node_run: policy"),
985 "got: {message}"
986 );
987 }
988 other => panic!("expected RustyError::Node, got {other:?}"),
989 }
990 assert!(!op_ran.load(std::sync::atomic::Ordering::SeqCst));
991 assert_eq!(trace.entries(), vec!["L1:before:node-b"]);
994 }
995
996 struct Skip;
998
999 #[async_trait]
1000 impl Middleware for Skip {
1001 fn name(&self) -> &str {
1002 "skip"
1003 }
1004
1005 async fn before_node(&self, call: &mut NodeCall) -> Decision<NodeOutput> {
1006 if call.node() == "victim" {
1007 Decision::ShortCircuit(NodeOutput::update("sub", json!("substitute")))
1008 } else {
1009 Decision::Continue
1010 }
1011 }
1012 }
1013
1014 #[tokio::test]
1015 async fn short_circuit_returns_substitute_and_unwinds_entered_layers() {
1016 let trace = Trace::default();
1017 let chain = MiddlewareChain::new()
1018 .layer(Recorder {
1019 id: "L1",
1020 trace: trace.clone(),
1021 })
1022 .layer(Skip)
1023 .layer(Recorder {
1024 id: "L3",
1025 trace: trace.clone(),
1026 });
1027
1028 let op_ran = Arc::new(std::sync::atomic::AtomicBool::new(false));
1029 let op_flag = op_ran.clone();
1030 let mut call = NodeCall::new("t-1", "victim", 1, State::new());
1031 let result = chain
1032 .run_node(&mut call, |_call| {
1033 let op_flag = op_flag.clone();
1034 async move {
1035 op_flag.store(true, std::sync::atomic::Ordering::SeqCst);
1036 Ok(NodeOutput::empty())
1037 }
1038 })
1039 .await
1040 .unwrap();
1041
1042 assert_eq!(result.updates.get("sub"), Some(&json!("substitute")));
1043 assert!(!op_ran.load(std::sync::atomic::Ordering::SeqCst));
1044 assert_eq!(trace.entries(), vec!["L1:before:victim", "L1:after:victim"]);
1048 }
1049
1050 struct Replace;
1052
1053 #[async_trait]
1054 impl Middleware for Replace {
1055 fn name(&self) -> &str {
1056 "replace"
1057 }
1058
1059 async fn after_node(
1060 &self,
1061 _call: &NodeCall,
1062 _output: &mut NodeOutput,
1063 ) -> Decision<NodeOutput> {
1064 Decision::ShortCircuit(NodeOutput::update("x", json!("replaced")))
1065 }
1066 }
1067
1068 #[tokio::test]
1069 async fn after_hook_short_circuit_replaces_result_and_skips_outer_layers() {
1070 let trace = Trace::default();
1071 let chain = MiddlewareChain::new()
1072 .layer(Recorder {
1073 id: "L1",
1074 trace: trace.clone(),
1075 })
1076 .layer(Replace);
1077
1078 let mut call = NodeCall::new("t-1", "node-a", 0, State::new());
1079 let result = chain
1080 .run_node(&mut call, |_call| async {
1081 Ok(NodeOutput::update("x", json!("original")))
1082 })
1083 .await
1084 .unwrap();
1085
1086 assert_eq!(result.updates.get("x"), Some(&json!("replaced")));
1087 assert_eq!(trace.entries(), vec!["L1:before:node-a"]);
1089 }
1090
1091 struct CountingModel {
1093 seen: Arc<Mutex<Option<usize>>>,
1094 }
1095
1096 #[async_trait]
1097 impl ChatModel for CountingModel {
1098 async fn chat(&self, messages: &[ChatMessage], _tools: &[Value]) -> Result<ChatResponse> {
1099 *self.seen.lock().unwrap() = Some(messages.len());
1100 Ok(ChatResponse {
1101 message: ChatMessage::assistant(format!("saw {} messages", messages.len())),
1102 model: None,
1103 usage: None,
1104 })
1105 }
1106 }
1107
1108 struct ModelMutate;
1110
1111 #[async_trait]
1112 impl Middleware for ModelMutate {
1113 fn name(&self) -> &str {
1114 "model_mutate"
1115 }
1116
1117 async fn before_model(&self, call: &mut ModelCall) -> Decision<ChatResponse> {
1118 call.messages_mut().insert(0, ChatMessage::system("rules"));
1119 Decision::Continue
1120 }
1121
1122 async fn after_model(
1123 &self,
1124 _call: &ModelCall,
1125 response: &mut ChatResponse,
1126 ) -> Decision<ChatResponse> {
1127 response.message.content = Some("intercepted".into());
1128 Decision::Continue
1129 }
1130 }
1131
1132 #[tokio::test]
1133 async fn model_chain_mutates_request_and_response() {
1134 let seen = Arc::new(Mutex::new(None));
1135 let model = MiddlewareChatModel::new(
1136 Arc::new(CountingModel { seen: seen.clone() }),
1137 MiddlewareChain::new().layer(ModelMutate),
1138 )
1139 .thread("t-1")
1140 .node("agent");
1141
1142 let response = model.chat(&[ChatMessage::user("hi")], &[]).await.unwrap();
1143
1144 assert_eq!(*seen.lock().unwrap(), Some(2));
1147 assert_eq!(response.message.content.as_deref(), Some("intercepted"));
1148 }
1149
1150 struct ModelReject;
1152
1153 #[async_trait]
1154 impl Middleware for ModelReject {
1155 fn name(&self) -> &str {
1156 "model_reject"
1157 }
1158
1159 async fn before_model(&self, _call: &mut ModelCall) -> Decision<ChatResponse> {
1160 Decision::Reject(Rejection::new(
1161 self.name(),
1162 InterceptPoint::ModelCall,
1163 "model_blocked",
1164 ))
1165 }
1166 }
1167
1168 #[tokio::test]
1169 async fn model_reject_skips_inner_model() {
1170 let seen = Arc::new(Mutex::new(None));
1171 let model = MiddlewareChatModel::new(
1172 Arc::new(CountingModel { seen: seen.clone() }),
1173 MiddlewareChain::new().layer(ModelReject),
1174 );
1175
1176 let err = model.chat(&[], &[]).await.unwrap_err();
1177 match err {
1178 RustyError::Llm(message) => {
1179 assert!(
1180 message.contains(
1181 "rejected by middleware `model_reject` at model_call: model_blocked"
1182 ),
1183 "got: {message}"
1184 );
1185 }
1186 other => panic!("expected RustyError::Llm, got {other:?}"),
1187 }
1188 assert_eq!(*seen.lock().unwrap(), None);
1189 }
1190
1191 struct ModelCache;
1193
1194 #[async_trait]
1195 impl Middleware for ModelCache {
1196 fn name(&self) -> &str {
1197 "model_cache"
1198 }
1199
1200 async fn before_model(&self, _call: &mut ModelCall) -> Decision<ChatResponse> {
1201 Decision::ShortCircuit(ChatResponse {
1202 message: ChatMessage::assistant("cached"),
1203 model: None,
1204 usage: None,
1205 })
1206 }
1207 }
1208
1209 #[tokio::test]
1210 async fn model_short_circuit_returns_substitute_response() {
1211 let seen = Arc::new(Mutex::new(None));
1212 let model = MiddlewareChatModel::new(
1213 Arc::new(CountingModel { seen: seen.clone() }),
1214 MiddlewareChain::new().layer(ModelCache),
1215 );
1216
1217 let response = model.chat(&[], &[]).await.unwrap();
1218 assert_eq!(response.message.content.as_deref(), Some("cached"));
1219 assert_eq!(*seen.lock().unwrap(), None);
1220 }
1221
1222 #[tokio::test]
1224 async fn model_wrapper_with_empty_chain_delegates() {
1225 let seen = Arc::new(Mutex::new(None));
1226 let model = MiddlewareChatModel::new(
1227 Arc::new(CountingModel { seen: seen.clone() }),
1228 MiddlewareChain::new(),
1229 );
1230 let response = model.chat(&[ChatMessage::user("hi")], &[]).await.unwrap();
1231 assert_eq!(response.message.content.as_deref(), Some("saw 1 messages"));
1232 assert_eq!(*seen.lock().unwrap(), Some(1));
1233 }
1234
1235 struct EchoTool;
1236
1237 #[async_trait]
1238 impl crate::tool::Tool for EchoTool {
1239 fn name(&self) -> &str {
1240 "echo"
1241 }
1242 fn description(&self) -> &str {
1243 "Echoes its `text` argument."
1244 }
1245 fn parameters_schema(&self) -> Value {
1246 json!({"type": "object", "properties": {"text": {"type": "string"}}})
1247 }
1248 async fn call(&self, args: Value) -> Result<Value> {
1249 Ok(json!(args.get("text").cloned().unwrap_or(Value::Null)))
1250 }
1251 }
1252
1253 struct DangerTool;
1254
1255 #[async_trait]
1256 impl crate::tool::Tool for DangerTool {
1257 fn name(&self) -> &str {
1258 "danger"
1259 }
1260 fn description(&self) -> &str {
1261 "Must never run."
1262 }
1263 fn parameters_schema(&self) -> Value {
1264 json!({"type": "object"})
1265 }
1266 async fn call(&self, _args: Value) -> Result<Value> {
1267 panic!("blocklisted tool executed");
1268 }
1269 }
1270
1271 fn echo_registry() -> crate::tool::ToolRegistry {
1272 let mut registry = crate::tool::ToolRegistry::new();
1273 registry.register(EchoTool);
1274 registry.register(DangerTool);
1275 registry
1276 }
1277
1278 #[tokio::test]
1279 async fn blocklist_rejects_blocked_tool_and_passes_allowed() {
1280 let executor = crate::tool::ToolExecutor::new(echo_registry())
1281 .with_middleware(MiddlewareChain::new().layer(ToolCallBlocklist::new(["danger"])));
1282
1283 let calls = vec![
1284 ToolCall::new("c1", "echo", json!({"text": "hello"})),
1285 ToolCall::new("c2", "danger", json!({})),
1286 ];
1287 let results = executor.execute_batch(&calls).await;
1288
1289 assert_eq!(results.len(), 2);
1290 assert_eq!(results[0].content.as_deref(), Some("hello"));
1291 let blocked = results[1].content.as_deref().unwrap();
1292 assert!(blocked.starts_with("ERROR:"), "got: {blocked}");
1293 assert!(blocked.contains("tool_call_blocklist"), "got: {blocked}");
1294 assert!(blocked.contains("tool_blocked"), "got: {blocked}");
1295 }
1296
1297 struct ArgsRewrite;
1299
1300 #[async_trait]
1301 impl Middleware for ArgsRewrite {
1302 fn name(&self) -> &str {
1303 "args_rewrite"
1304 }
1305
1306 async fn before_tool(&self, call: &mut ToolInvocation) -> Decision<Value> {
1307 call.set_arguments(json!({"text": "mutated"}));
1308 Decision::Continue
1309 }
1310 }
1311
1312 #[tokio::test]
1313 async fn tool_argument_mutation_propagates_to_tool() {
1314 let executor = crate::tool::ToolExecutor::new(echo_registry())
1315 .with_middleware(MiddlewareChain::new().layer(ArgsRewrite));
1316
1317 let calls = vec![ToolCall::new("c1", "echo", json!({"text": "original"}))];
1318 let results = executor.execute_batch(&calls).await;
1319 assert_eq!(results[0].content.as_deref(), Some("mutated"));
1320 }
1321
1322 struct ToolCache;
1324
1325 #[async_trait]
1326 impl Middleware for ToolCache {
1327 fn name(&self) -> &str {
1328 "tool_cache"
1329 }
1330
1331 async fn before_tool(&self, _call: &mut ToolInvocation) -> Decision<Value> {
1332 Decision::ShortCircuit(json!("cached"))
1333 }
1334 }
1335
1336 #[tokio::test]
1337 async fn tool_short_circuit_returns_substitute_result() {
1338 let executor = crate::tool::ToolExecutor::new(echo_registry())
1339 .with_middleware(MiddlewareChain::new().layer(ToolCache));
1340
1341 let calls = vec![ToolCall::new("c1", "echo", json!({"text": "ignored"}))];
1342 let results = executor.execute_batch(&calls).await;
1343 assert_eq!(results[0].content.as_deref(), Some("cached"));
1344 }
1345
1346 struct ResultRewrite;
1348
1349 #[async_trait]
1350 impl Middleware for ResultRewrite {
1351 fn name(&self) -> &str {
1352 "result_rewrite"
1353 }
1354
1355 async fn after_tool(&self, _call: &ToolInvocation, result: &mut Value) -> Decision<Value> {
1356 *result = json!("rewritten");
1357 Decision::Continue
1358 }
1359 }
1360
1361 #[tokio::test]
1362 async fn tool_result_mutation_propagates_to_caller() {
1363 let executor = crate::tool::ToolExecutor::new(echo_registry())
1364 .with_middleware(MiddlewareChain::new().layer(ResultRewrite));
1365
1366 let calls = vec![ToolCall::new("c1", "echo", json!({"text": "original"}))];
1367 let results = executor.execute_batch(&calls).await;
1368 assert_eq!(results[0].content.as_deref(), Some("rewritten"));
1369 }
1370
1371 struct ToolRecorder {
1373 id: &'static str,
1374 trace: Trace,
1375 }
1376
1377 #[async_trait]
1378 impl Middleware for ToolRecorder {
1379 fn name(&self) -> &str {
1380 self.id
1381 }
1382
1383 async fn before_tool(&self, call: &mut ToolInvocation) -> Decision<Value> {
1384 self.trace
1385 .record(format!("{}:before:{}", self.id, call.name()));
1386 Decision::Continue
1387 }
1388
1389 async fn after_tool(&self, call: &ToolInvocation, _result: &mut Value) -> Decision<Value> {
1390 self.trace
1391 .record(format!("{}:after:{}", self.id, call.name()));
1392 Decision::Continue
1393 }
1394 }
1395
1396 #[tokio::test]
1397 async fn tool_hooks_follow_onion_order() {
1398 let trace = Trace::default();
1399 let executor = crate::tool::ToolExecutor::new(echo_registry()).with_middleware(
1400 MiddlewareChain::new()
1401 .layer(ToolRecorder {
1402 id: "L1",
1403 trace: trace.clone(),
1404 })
1405 .layer(ToolRecorder {
1406 id: "L2",
1407 trace: trace.clone(),
1408 }),
1409 );
1410
1411 let calls = vec![ToolCall::new("c1", "echo", json!({"text": "hi"}))];
1412 let results = executor.execute_batch(&calls).await;
1413 assert_eq!(results[0].content.as_deref(), Some("hi"));
1414 assert_eq!(
1415 trace.entries(),
1416 vec![
1417 "L1:before:echo",
1418 "L2:before:echo",
1419 "L2:after:echo",
1420 "L1:after:echo"
1421 ]
1422 );
1423 }
1424
1425 #[tokio::test]
1426 async fn request_logger_passes_everything_through() {
1427 let chain = MiddlewareChain::new().layer(RequestLogger::new());
1428
1429 let mut node_call = NodeCall::new("t-1", "node-a", 0, State::new());
1430 let node_result = chain
1431 .run_node(&mut node_call, |_call| async {
1432 Ok(NodeOutput::update("x", json!(1)))
1433 })
1434 .await
1435 .unwrap();
1436 assert_eq!(node_result.updates.get("x"), Some(&json!(1)));
1437
1438 let mut model_call = ModelCall::new("t-1", "agent", vec![ChatMessage::user("hi")], vec![]);
1439 let model_result = chain
1440 .run_model(&mut model_call, |_call| async {
1441 Ok(ChatResponse {
1442 message: ChatMessage::assistant("hello"),
1443 model: None,
1444 usage: None,
1445 })
1446 })
1447 .await
1448 .unwrap();
1449 assert_eq!(model_result.message.content.as_deref(), Some("hello"));
1450
1451 let mut tool_call =
1452 ToolInvocation::new("t-1", "tools", ToolCall::new("c1", "echo", json!({})));
1453 let tool_result = chain
1454 .run_tool(&mut tool_call, |_call| async { Ok(json!("done")) })
1455 .await
1456 .unwrap();
1457 assert_eq!(tool_result, json!("done"));
1458 }
1459
1460 #[test]
1461 fn rejection_serde_roundtrip_display_and_error_mapping() {
1462 let rejection = Rejection::new(
1463 "tool_call_blocklist",
1464 InterceptPoint::ToolCall,
1465 "tool_blocked",
1466 )
1467 .with_detail("tool `rm_rf` is blocked by policy");
1468 let back: Rejection =
1469 serde_json::from_str(&serde_json::to_string(&rejection).unwrap()).unwrap();
1470 assert_eq!(rejection, back);
1471
1472 let msg = rejection.to_string();
1473 assert!(msg.contains("tool_call_blocklist"), "got: {msg}");
1474 assert!(msg.contains("tool_call"), "got: {msg}");
1475 assert!(msg.contains("tool_blocked"), "got: {msg}");
1476 assert_eq!(format!("{}", rejection.point), "tool_call");
1477
1478 for (point, expect) in [
1481 (InterceptPoint::NodeRun, "node error"),
1482 (InterceptPoint::ModelCall, "llm error"),
1483 (InterceptPoint::ToolCall, "tool error"),
1484 ] {
1485 let err = Rejection::new("m", point, "r").into_error();
1486 assert!(
1487 err.to_string().starts_with(expect),
1488 "{point}: expected prefix `{expect}`, got: {err}"
1489 );
1490 assert!(err.to_string().contains("rejected by middleware `m`"));
1491 }
1492 }
1493
1494 #[test]
1495 fn chain_debug_lists_layer_names() {
1496 let chain = MiddlewareChain::new()
1497 .layer(RequestLogger::new())
1498 .layer(ToolCallBlocklist::new(["danger"]));
1499 let debug = format!("{chain:?}");
1500 assert!(debug.contains("request_logger"), "got: {debug}");
1501 assert!(debug.contains("tool_call_blocklist"), "got: {debug}");
1502 }
1503}