Skip to main content

rusty_agent_runtime/
middleware.rs

1//! Middleware / Interceptor SDK: ordered layers around execution.
2//!
3//! A [`Middleware`] is an async, object-safe interception layer with six
4//! hooks — before/after at three points: **node run** ([`NodeCall`]),
5//! **model call** ([`ModelCall`]), and **tool call** ([`ToolInvocation`]).
6//! Every hook returns a [`Decision`]: continue (with any mutations applied
7//! to the context in place), reject with a structured [`Rejection`], or
8//! short-circuit with a substitute result.
9//!
10//! Layers compose into a [`MiddlewareChain`] with tower-style onion
11//! semantics:
12//!
13//! - before-hooks run in **registration order** on the way in, after-hooks
14//!   in **reverse order** on the way out;
15//! - a before-hook short-circuit at layer *i* skips the remaining
16//!   before-hooks and the operation itself; the after-hooks of the layers
17//!   that already entered (`0..i`) unwind over the substitute result;
18//! - a rejection is terminal: no after-hooks run, and the rejection surfaces
19//!   through the crate's existing error taxonomy — node-run rejections as
20//!   [`RustyError::Node`], model rejections as [`RustyError::Llm`], tool
21//!   rejections as [`RustyError::Tool`] (which the
22//!   [`crate::tool::ToolExecutor`] renders into an `ERROR:` tool message the
23//!   model can observe). The message is the [`Rejection`]'s canonical
24//!   [`Display`](std::fmt::Display) form; the typed `Rejection` itself is
25//!   the contract at the middleware API. Never a panic;
26//! - after-hooks run on the success path only; operation errors propagate
27//!   untouched. An after-hook short-circuit replaces the result and skips
28//!   the remaining (outer) after-hooks.
29//!
30//! Wiring:
31//!
32//! - **Node runs** — attach layers to the [`crate::executor::Executor`] with
33//!   `.layer(...)`; the chain wraps every node invocation at the super-step
34//!   boundary. The same chain reaches node code through
35//!   [`crate::node::NodeContext::middleware`].
36//! - **Tool calls** — hand the chain to
37//!   [`crate::tool::ToolExecutor::with_middleware`]; every dispatched call is
38//!   wrapped. A tool-level rejection follows the executor's
39//!   failure-isolation contract and becomes an `ERROR:` tool message the
40//!   model can observe and recover from.
41//! - **Model calls** — wrap a [`crate::llm::ChatModel`] in
42//!   [`MiddlewareChatModel`]; every `chat` (and, via the default fallback,
43//!   `chat_stream`) is intercepted.
44//!
45//! Two reference layers ship here: [`RequestLogger`] (tracing-based
46//! observation) and [`ToolCallBlocklist`] (reject-by-policy).
47
48use 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/// The interception point a [`Rejection`] originated at.
62#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
63#[serde(rename_all = "snake_case")]
64pub enum InterceptPoint {
65    /// A node run at the super-step boundary.
66    NodeRun,
67    /// A [`crate::llm::ChatModel`] call.
68    ModelCall,
69    /// A tool call dispatched through [`crate::tool::ToolExecutor`].
70    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/// A structured middleware rejection: which layer, at which point, and why.
85///
86/// The typed contract at the middleware API. When a rejection leaves the
87/// chain it maps onto the crate's string-payload error taxonomy by
88/// interception point (node run → [`RustyError::Node`], model call →
89/// [`RustyError::Llm`], tool call → [`RustyError::Tool`]), with this
90/// struct's canonical [`Display`](std::fmt::Display) as the message —
91/// keeping `RustyError` additive-free for downstream exhaustive matches.
92#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
93pub struct Rejection {
94    /// The rejecting layer ([`Middleware::name`]).
95    pub middleware: String,
96    /// The interception point that rejected.
97    pub point: InterceptPoint,
98    /// Machine-readable reason code (e.g. `"tool_blocked"`).
99    pub reason: String,
100    /// Optional human-readable detail.
101    #[serde(default, skip_serializing_if = "Option::is_none")]
102    pub detail: Option<String>,
103}
104
105impl Rejection {
106    /// A rejection by `middleware` at `point` with reason code `reason`.
107    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    /// Builder-style: attach human-readable detail.
121    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    /// Map onto the crate's error taxonomy by interception point; see the
139    /// struct docs.
140    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/// The verdict a middleware hook returns.
151///
152/// `R` is the result type of the intercepted operation: [`NodeOutput`] for
153/// node runs, [`ChatResponse`] for model calls, [`Value`] for tool calls.
154#[derive(Debug, Clone, PartialEq)]
155pub enum Decision<R> {
156    /// Continue through the chain (any mutations applied to the context in
157    /// place propagate to the next layer and the operation).
158    Continue,
159    /// Stop the chain and fail the operation with a structured reason.
160    Reject(Rejection),
161    /// Before-hook: skip the remaining before-hooks and the operation
162    /// itself; `R` stands in for its result while the entered layers unwind.
163    /// After-hook: replace the result with `R` and skip the remaining
164    /// (outer) after-hooks.
165    ShortCircuit(R),
166}
167
168/// Node-run interception context: the invocation a node is about to run with.
169///
170/// The `state` snapshot is the payload before-hooks may mutate; mutations
171/// propagate into the [`crate::node::NodeContext`] the node receives.
172#[derive(Debug, Clone)]
173pub struct NodeCall {
174    thread_id: String,
175    node: String,
176    step: usize,
177    state: State,
178}
179
180impl NodeCall {
181    /// A context for `node` at super-step `step` of thread `thread_id`.
182    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    /// The thread (run) this invocation belongs to.
197    pub fn thread_id(&self) -> &str {
198        &self.thread_id
199    }
200
201    /// The node about to run.
202    pub fn node(&self) -> &str {
203        &self.node
204    }
205
206    /// The current super-step index.
207    pub fn step(&self) -> usize {
208        self.step
209    }
210
211    /// The invocation's state snapshot.
212    pub fn state(&self) -> &State {
213        &self.state
214    }
215
216    /// Mutable access to the snapshot the node will receive.
217    pub fn state_mut(&mut self) -> &mut State {
218        &mut self.state
219    }
220
221    /// Convenience: insert a channel into the snapshot.
222    pub fn insert(&mut self, channel: impl Into<String>, value: Value) {
223        self.state.insert(channel, value);
224    }
225}
226
227/// Model-call interception context: the request a [`ChatModel`] is about to
228/// receive. Mutations to the messages or tool schemas propagate to the model.
229#[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    /// A context for a model call with `messages` and tool schemas `tools`.
239    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    /// The thread (run) this call belongs to, or empty when unknown.
254    pub fn thread_id(&self) -> &str {
255        &self.thread_id
256    }
257
258    /// The node making the call, or empty when unknown.
259    pub fn node(&self) -> &str {
260        &self.node
261    }
262
263    /// The conversation about to be sent.
264    pub fn messages(&self) -> &[ChatMessage] {
265        &self.messages
266    }
267
268    /// Mutable access to the conversation (inject, redact, rewrite).
269    pub fn messages_mut(&mut self) -> &mut Vec<ChatMessage> {
270        &mut self.messages
271    }
272
273    /// The OpenAI-format tool schemas about to be sent.
274    pub fn tools(&self) -> &[Value] {
275        &self.tools
276    }
277
278    /// Mutable access to the tool schemas.
279    pub fn tools_mut(&mut self) -> &mut Vec<Value> {
280        &mut self.tools
281    }
282}
283
284/// Tool-call interception context: one tool call about to be dispatched.
285///
286/// The registry lookup happens **after** before-hooks, so a layer may
287/// rewrite the arguments — or the target tool name itself.
288#[derive(Debug, Clone)]
289pub struct ToolInvocation {
290    thread_id: String,
291    node: String,
292    call: ToolCall,
293}
294
295impl ToolInvocation {
296    /// A context wrapping one [`ToolCall`].
297    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    /// The thread (run) this call belongs to, or empty when unknown.
306    pub fn thread_id(&self) -> &str {
307        &self.thread_id
308    }
309
310    /// The node dispatching the call, or empty when unknown.
311    pub fn node(&self) -> &str {
312        &self.node
313    }
314
315    /// The tool call about to be dispatched.
316    pub fn call(&self) -> &ToolCall {
317        &self.call
318    }
319
320    /// Mutable access to the tool call (id, name, arguments).
321    pub fn call_mut(&mut self) -> &mut ToolCall {
322        &mut self.call
323    }
324
325    /// The provider-assigned call id.
326    pub fn id(&self) -> &str {
327        &self.call.id
328    }
329
330    /// The target tool name.
331    pub fn name(&self) -> &str {
332        &self.call.name
333    }
334
335    /// The model-supplied arguments.
336    pub fn arguments(&self) -> &Value {
337        &self.call.arguments
338    }
339
340    /// Convenience: replace the arguments.
341    pub fn set_arguments(&mut self, arguments: Value) {
342        self.call.arguments = arguments;
343    }
344}
345
346/// The interception layer: async, object-safe hooks around execution.
347///
348/// Implement any subset of hooks; every default passes through unchanged.
349/// `Send + Sync` because layers are shared across concurrent node
350/// invocations and tool calls within a run.
351#[async_trait]
352pub trait Middleware: Send + Sync {
353    /// Human/log-friendly name, recorded on rejections.
354    fn name(&self) -> &str;
355
356    /// Node run, inbound (registration order).
357    async fn before_node(&self, call: &mut NodeCall) -> Decision<NodeOutput> {
358        let _ = call;
359        Decision::Continue
360    }
361
362    /// Node run, outbound (reverse registration order). Success path only.
363    async fn after_node(&self, call: &NodeCall, output: &mut NodeOutput) -> Decision<NodeOutput> {
364        let _ = (call, output);
365        Decision::Continue
366    }
367
368    /// Model call, inbound (registration order).
369    async fn before_model(&self, call: &mut ModelCall) -> Decision<ChatResponse> {
370        let _ = call;
371        Decision::Continue
372    }
373
374    /// Model call, outbound (reverse registration order). Success path only.
375    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    /// Tool call, inbound (registration order).
385    async fn before_tool(&self, call: &mut ToolInvocation) -> Decision<Value> {
386        let _ = call;
387        Decision::Continue
388    }
389
390    /// Tool call, outbound (reverse registration order). Success path only.
391    async fn after_tool(&self, call: &ToolInvocation, result: &mut Value) -> Decision<Value> {
392        let _ = (call, result);
393        Decision::Continue
394    }
395}
396
397/// An ordered stack of middleware layers with onion semantics.
398///
399/// Cheap to clone (`Arc` layers); empty by default, and every consumer
400/// (executor, tool executor, model wrapper) takes its original code path
401/// when the chain is empty.
402#[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    /// An empty chain.
420    pub fn new() -> Self {
421        Self::default()
422    }
423
424    /// Builder-style: append a layer (runs after the already-added layers on
425    /// the way in, before them on the way out).
426    pub fn layer<M: Middleware + 'static>(mut self, middleware: M) -> Self {
427        self.push(Arc::new(middleware));
428        self
429    }
430
431    /// Append a pre-shared layer.
432    pub fn push(&mut self, middleware: Arc<dyn Middleware>) -> &mut Self {
433        self.layers.push(middleware);
434        self
435    }
436
437    /// `true` if no layers are attached.
438    pub fn is_empty(&self) -> bool {
439        self.layers.is_empty()
440    }
441
442    /// Number of attached layers.
443    pub fn len(&self) -> usize {
444        self.layers.len()
445    }
446
447    /// The layer names, in registration order.
448    pub fn names(&self) -> impl Iterator<Item = &str> {
449        self.layers.iter().map(|l| l.name())
450    }
451
452    /// Run the onion around a node invocation: before-hooks inward, `op`,
453    /// after-hooks outward. See the module docs for the full contract.
454    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    /// Run the onion around a model call. Same contract as
492    /// [`MiddlewareChain::run_node`].
493    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    /// Run the onion around a tool call. Same contract as
531    /// [`MiddlewareChain::run_node`].
532    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/// A [`ChatModel`] wrapper that runs every call through a
571/// [`MiddlewareChain`]'s model hooks.
572///
573/// Construct per node (or per invocation) — typically with the chain from
574/// [`crate::node::NodeContext::middleware`]. The optional `thread`/`node`
575/// labels flow into the [`ModelCall`] context.
576///
577/// `chat_stream` needs no override: the [`ChatModel`] default falls back to
578/// `chat`, so streamed calls are intercepted identically.
579#[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    /// A middleware wrapper around `inner`, intercepting through `chain`.
589    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    /// Builder-style: the thread (run) label for the [`ModelCall`] context.
599    pub fn thread(mut self, thread_id: impl Into<String>) -> Self {
600        self.thread_id = thread_id.into();
601        self
602    }
603
604    /// Builder-style: the node label for the [`ModelCall`] context.
605    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/// Tracing-based observation middleware: emits an INFO event at every
639/// interception point and passes everything through unchanged.
640///
641/// Payloads are deliberately not logged — counts and ids only. Logging full
642/// model or tool payloads is a data-leak footgun; compose a redaction layer
643/// first if you need them.
644#[derive(Debug, Default)]
645pub struct RequestLogger;
646
647impl RequestLogger {
648    /// A logger layer.
649    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/// Reject-by-policy middleware: tool calls to blocklisted tools never
731/// execute; each is rejected with a structured [`Rejection`] (reason
732/// `"tool_blocked"` by default) that surfaces as an `ERROR:` tool message
733/// under the [`crate::tool::ToolExecutor`] failure-isolation contract.
734#[derive(Debug, Clone)]
735pub struct ToolCallBlocklist {
736    blocked: HashSet<String>,
737    reason: String,
738}
739
740impl ToolCallBlocklist {
741    /// Block the named tools with the default reason code.
742    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    /// Builder-style: override the rejection reason code.
754    pub fn with_reason(mut self, reason: impl Into<String>) -> Self {
755        self.reason = reason.into();
756        self
757    }
758
759    /// `true` if calls to `tool` are rejected.
760    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    /// Shared, thread-safe record of hook invocations, for order proofs.
790    #[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    /// Records before/after node hooks as `Lx:before|after:<node>`.
804    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    /// Injects state inbound, rewrites the output outbound.
894    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                // The before-hook's state mutation is visible to the node.
924                assert_eq!(call.state().get("injected"), Some(&json!(true)));
925                async move { Ok(NodeOutput::update("x", json!("original"))) }
926            })
927            .await
928            .unwrap();
929        // The after-hook's rewrite is visible to the caller.
930        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                // Node-run rejections map onto RustyError::Node carrying the
982                // Rejection's canonical Display form.
983                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        // L1 entered (before ran), L3 never ran at all, and no after-hooks
992        // unwind a rejection.
993        assert_eq!(trace.entries(), vec!["L1:before:node-b"]);
994    }
995
996    /// Short-circuits node `victim` with a substitute output.
997    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        // Only the layers that entered before the short-circuit unwind;
1045        // neither the short-circuiting layer nor the ones past it run
1046        // after-hooks.
1047        assert_eq!(trace.entries(), vec!["L1:before:victim", "L1:after:victim"]);
1048    }
1049
1050    /// After-hook short-circuits with a replacement result.
1051    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        // L2's after-hook replaced the result; L1's after-hook never ran.
1088        assert_eq!(trace.entries(), vec!["L1:before:node-a"]);
1089    }
1090
1091    /// A mock model that reports how many messages it received.
1092    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    /// Injects a system message inbound, rewrites content outbound.
1109    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        // The injected system message reached the inner model; the
1145        // after-hook rewrite reached the caller.
1146        assert_eq!(*seen.lock().unwrap(), Some(2));
1147        assert_eq!(response.message.content.as_deref(), Some("intercepted"));
1148    }
1149
1150    /// Rejects every model call.
1151    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    /// Short-circuits every model call with a canned response.
1192    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    /// A wrapper with an empty chain must delegate untouched.
1223    #[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    /// Rewrites tool arguments inbound.
1298    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    /// Answers tool calls from a cache without executing them.
1323    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    /// Rewrites the tool result outbound.
1347    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    /// Records tool hooks for order proofs.
1372    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        // The taxonomy mapping: each interception point lands on its
1479        // existing error variant, carrying the canonical Display form.
1480        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}