Module middleware 

Middleware — agent 事件拦截与处理管道

提供对 ReAct 循环内部的可插拔拦截机制，作用于 process_token_stream 和 handle_turn_finish 之后、数据写入 session 历史之前。

分为两类：

类型	特征	执行方式	影响事件流
InspectorMiddleware	只读观察	tokio::spawn 后台并行	❌ 不等待，不阻塞
MutatorMiddleware	可变处理	同步顺序执行	✅ 可 Pass/Modify/Block

架构位置

LLM Stream → process_token_stream → 聚合结果
                                        │
                         create E events │
                                        ▼
                             [middleware chain]
                          Pass / Modify / Block
                                 │
                        ┌────────┴────────┐
                        ▼                 ▼
                   session 历史         event_tx (通知/callback)
                   (下一轮用)           (聚合生成 ChatResponse)

Middleware 直接操作 session 写入前的数据，因此修改会持久化到下一轮 ReAct 循环的历史上下文中。

快速使用 (在 funera-orchestrate 层)

// 1. 定义 Inspector
struct Logger;
impl InspectorMiddleware<String> for Logger {
    fn name(&self) -> &str { "log" }
    fn inspect(&self, _: &String) -> Result<(), InspectorError> { Ok(()) }
}

// 2. 定义 Mutator
struct Censor;
impl MutatorMiddleware<String> for Censor {
    fn name(&self) -> &str { "censor" }
    fn process(&self, s: String) -> MutatorAction<String> { MutatorAction::Pass }
}

// 3. 构建链
let chain = MiddlewareChain::<String>::new()
    .with_inspectors((Logger,))
    .with_mutator(Censor);

// 4. 执行（由 react_loop 内部调用）
let result = chain.process("hello".into());

Typestate 错误通道

错误通道通过 typestate 管理：默认 ErrorsDisabled，调用 MiddlewareChain::activate_error_channel 后变为 ErrorsEnabled，编译期防止重复激活。

let chain = MiddlewareChain::<String>::new()
    .with_inspector(Insp);
let (enabled, error_rx) = chain.activate_error_channel();
// enabled 的类型是 MiddlewareChain<String, ErrorsEnabled>
// 无法再次调用 activate_error_channel()

Structs

ErrorsDisabled

错误通道尚未启用的 typestate 标记。

ErrorsEnabled

错误通道已启用的 typestate 标记。

MiddlewareBlocked

事件被 mutator 阻止时的错误信息。

MiddlewareChain

中间件链——按注册顺序逐层执行。

Enums

MiddlewareLayer

中间件链中的一层。

MutatorAction

Mutator 对事件的处理决策。

Traits

InspectorMiddleware

只读检查器——接收 &Evt，后台并行执行，不阻塞事件流。

IntoInspectors

将一组 inspector 转换为 Vec<Arc<dyn InspectorMiddleware>>。

IntoMutators

将一组 mutator 转换为 Vec<Arc<dyn MutatorMiddleware>>。

MiddlewareEvent

ReAct 循环每轮产出的中间件事件。

MutatorMiddleware

可变处理器——接收 Evt，选择放行/修改/阻止。

Type Aliases

EventSenderFn

用于 react_loop 向上层通知事件的可调用对象。

InspectorError

Inspector 错误的类型别名。