aster/hooks/
internal.rs

1//! 内部钩子事件系统
2//!
3//! 本模块实现内部钩子（Internal Hooks）机制，支持 Agent 生命周期、
4//! Session 管理、命令处理等事件的监听和处理。
5//!
6//! # 事件类型
7//!
8//! - `Agent`: Agent 生命周期事件（启动、停止、错误、引导）
9//! - `Session`: 会话事件（创建、恢复、结束、压缩）
10//! - `Tool`: 工具事件（执行前、执行后、错误）
11//! - `Command`: 命令事件（new、reset、status、help）
12//! - `Gateway`: 网关事件（连接、断开、消息）
13//!
14//! # 示例
15//!
16//! ```rust,ignore
17//! use aster::hooks::internal::{InternalHookEventType};
18//!
19//! let event_type = InternalHookEventType::Agent;
20//! assert_eq!(event_type.to_string(), "agent");
21//! ```
22
23use anyhow::Result;
24use chrono::{DateTime, Utc};
25use once_cell::sync::Lazy;
26use parking_lot::RwLock;
27use serde::{Deserialize, Serialize};
28use std::collections::HashMap;
29use std::fmt;
30use std::future::Future;
31use std::pin::Pin;
32use std::sync::Arc;
33
34/// 内部钩子事件类型
35///
36/// 定义系统中可监听的五种主要事件类型。每种类型对应不同的系统组件，
37/// 可以与 `InternalHookAction` 组合形成具体的事件键（如 `agent:start`）。
38///
39/// # 序列化
40///
41/// 序列化时使用小写格式（如 `"agent"`、`"session"`）。
42///
43/// # 示例
44///
45/// ```rust,ignore
46/// use aster::hooks::internal::InternalHookEventType;
47///
48/// let event_type = InternalHookEventType::Agent;
49/// assert_eq!(event_type.to_string(), "agent");
50///
51/// // 序列化为 JSON
52/// let json = serde_json::to_string(&event_type).unwrap();
53/// assert_eq!(json, "\"agent\"");
54/// ```
55#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
56#[serde(rename_all = "lowercase")]
57pub enum InternalHookEventType {
58    /// Agent 生命周期事件
59    ///
60    /// 用于监听 Agent 的启动、停止、错误和引导完成等事件。
61    Agent,
62
63    /// Session 会话事件
64    ///
65    /// 用于监听会话的创建、恢复、结束和压缩等事件。
66    Session,
67
68    /// Tool 工具事件
69    ///
70    /// 用于监听工具调用的前后事件，与现有 hooks 系统桥接。
71    Tool,
72
73    /// Command 命令事件
74    ///
75    /// 用于监听用户命令（如 /new、/reset、/status、/help）的执行。
76    Command,
77
78    /// Gateway 网关事件
79    ///
80    /// 用于监听网关的连接、断开和消息事件。
81    Gateway,
82}
83
84impl fmt::Display for InternalHookEventType {
85    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
86        let s = match self {
87            InternalHookEventType::Agent => "agent",
88            InternalHookEventType::Session => "session",
89            InternalHookEventType::Tool => "tool",
90            InternalHookEventType::Command => "command",
91            InternalHookEventType::Gateway => "gateway",
92        };
93        write!(f, "{}", s)
94    }
95}
96
97/// 内部钩子事件动作
98///
99/// 定义各种事件类型下的具体动作。不同的事件类型有不同的有效动作：
100///
101/// | 事件类型 | 有效动作 |
102/// |---------|---------|
103/// | Agent | Start, Stop, Error, Bootstrap |
104/// | Session | Create, Resume, End, Compact |
105/// | Tool | Before, After, Error |
106/// | Command | New, Reset, Status, Help |
107/// | Gateway | Connect, Disconnect, Message |
108///
109/// # 序列化
110///
111/// 序列化时使用小写格式（如 `"start"`、`"create"`）。
112///
113/// # 示例
114///
115/// ```rust,ignore
116/// use aster::hooks::internal::InternalHookAction;
117///
118/// let action = InternalHookAction::Start;
119/// assert_eq!(action.to_string(), "start");
120///
121/// // 序列化为 JSON
122/// let json = serde_json::to_string(&action).unwrap();
123/// assert_eq!(json, "\"start\"");
124/// ```
125#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
126#[serde(rename_all = "lowercase")]
127pub enum InternalHookAction {
128    // ========== Agent 动作 ==========
129    /// Agent 启动
130    ///
131    /// 当 Agent 开始运行时触发。
132    Start,
133
134    /// Agent 停止
135    ///
136    /// 当 Agent 停止运行时触发。
137    Stop,
138
139    /// Agent 错误
140    ///
141    /// 当 Agent 发生错误时触发。也可用于 Tool 错误事件。
142    Error,
143
144    /// Agent 引导完成
145    ///
146    /// 当 Agent 完成初始化引导时触发。
147    Bootstrap,
148
149    // ========== Session 动作 ==========
150    /// Session 创建
151    ///
152    /// 当新会话创建时触发。
153    Create,
154
155    /// Session 恢复
156    ///
157    /// 当会话从持久化状态恢复时触发。
158    Resume,
159
160    /// Session 结束
161    ///
162    /// 当会话结束时触发。
163    End,
164
165    /// Session 压缩
166    ///
167    /// 当会话历史被压缩时触发。
168    Compact,
169
170    // ========== Tool 动作 ==========
171    /// Tool 执行前
172    ///
173    /// 在工具执行之前触发。
174    Before,
175
176    /// Tool 执行后
177    ///
178    /// 在工具执行之后触发。
179    After,
180    // 注意：Tool 错误复用上面的 Error 动作
181
182    // ========== Command 动作 ==========
183    /// /new 命令
184    ///
185    /// 当用户执行 /new 命令时触发。
186    New,
187
188    /// /reset 命令
189    ///
190    /// 当用户执行 /reset 命令时触发。
191    Reset,
192
193    /// /status 命令
194    ///
195    /// 当用户执行 /status 命令时触发。
196    Status,
197
198    /// /help 命令
199    ///
200    /// 当用户执行 /help 命令时触发。
201    Help,
202
203    // ========== Gateway 动作 ==========
204    /// Gateway 连接
205    ///
206    /// 当网关建立连接时触发。
207    Connect,
208
209    /// Gateway 断开
210    ///
211    /// 当网关断开连接时触发。
212    Disconnect,
213
214    /// Gateway 消息
215    ///
216    /// 当网关收到或发送消息时触发。
217    Message,
218}
219
220impl fmt::Display for InternalHookAction {
221    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
222        let s = match self {
223            // Agent 动作
224            InternalHookAction::Start => "start",
225            InternalHookAction::Stop => "stop",
226            InternalHookAction::Error => "error",
227            InternalHookAction::Bootstrap => "bootstrap",
228            // Session 动作
229            InternalHookAction::Create => "create",
230            InternalHookAction::Resume => "resume",
231            InternalHookAction::End => "end",
232            InternalHookAction::Compact => "compact",
233            // Tool 动作
234            InternalHookAction::Before => "before",
235            InternalHookAction::After => "after",
236            // Command 动作
237            InternalHookAction::New => "new",
238            InternalHookAction::Reset => "reset",
239            InternalHookAction::Status => "status",
240            InternalHookAction::Help => "help",
241            // Gateway 动作
242            InternalHookAction::Connect => "connect",
243            InternalHookAction::Disconnect => "disconnect",
244            InternalHookAction::Message => "message",
245        };
246        write!(f, "{}", s)
247    }
248}
249
250/// 内部钩子事件
251///
252/// 表示系统中发生的一个内部事件，包含事件类型、动作、上下文数据等信息。
253/// 事件可以被注册的处理器监听和处理。
254///
255/// # 字段
256///
257/// - `event_type`: 事件类型（Agent、Session、Tool、Command、Gateway）
258/// - `action`: 事件动作（如 Start、Stop、Create 等）
259/// - `session_key`: 可选的会话键，用于关联特定会话
260/// - `context`: JSON 格式的上下文数据，包含事件相关的详细信息
261/// - `timestamp`: 事件发生的 UTC 时间戳
262/// - `messages`: 消息列表，处理器可以向其中推送消息
263///
264/// # 事件键
265///
266/// 事件键格式为 `type:action`（如 `agent:start`、`session:create`），
267/// 用于在注册表中匹配处理器。
268///
269/// # 示例
270///
271/// ```rust,ignore
272/// use aster::hooks::internal::{InternalHookEvent, InternalHookEventType, InternalHookAction};
273/// use serde_json::json;
274///
275/// // 创建一个 Agent 启动事件
276/// let event = InternalHookEvent::new(
277///     InternalHookEventType::Agent,
278///     InternalHookAction::Start,
279///     Some("user:session:123".to_string()),
280///     json!({
281///         "agent_id": "agent-001",
282///         "agent_type": "coding"
283///     }),
284/// );
285///
286/// assert_eq!(event.event_key(), "agent:start");
287/// ```
288#[derive(Debug, Clone, Serialize, Deserialize)]
289pub struct InternalHookEvent {
290    /// 事件类型
291    ///
292    /// 标识事件所属的系统组件类别。
293    pub event_type: InternalHookEventType,
294
295    /// 事件动作
296    ///
297    /// 描述事件的具体动作，如启动、停止、创建等。
298    pub action: InternalHookAction,
299
300    /// 会话键（可选）
301    ///
302    /// 用于关联特定会话的标识符。对于与会话相关的事件，
303    /// 此字段通常包含会话的唯一标识。
304    pub session_key: Option<String>,
305
306    /// 上下文数据
307    ///
308    /// JSON 格式的上下文数据，包含事件相关的详细信息。
309    /// 不同类型的事件有不同的上下文结构：
310    ///
311    /// - Agent 事件：`agent_id`、`agent_type`、`workspace_dir`、`error`
312    /// - Session 事件：`session_id`、`session_key`、`source`、`reason`
313    /// - Command 事件：`command_name`、`command_args`、`raw_input`
314    /// - Gateway 事件：`connection_id`、`channel`、`message`
315    pub context: serde_json::Value,
316
317    /// 时间戳
318    ///
319    /// 事件发生的 UTC 时间戳，由 `new()` 构造函数自动填充。
320    pub timestamp: DateTime<Utc>,
321
322    /// 消息列表
323    ///
324    /// 处理器可以向此列表推送消息，用于向用户反馈信息。
325    /// 初始为空列表。
326    pub messages: Vec<String>,
327}
328
329impl InternalHookEvent {
330    /// 创建新的内部钩子事件
331    ///
332    /// 自动填充 `timestamp` 为当前 UTC 时间，`messages` 初始化为空列表。
333    ///
334    /// # 参数
335    ///
336    /// - `event_type`: 事件类型
337    /// - `action`: 事件动作
338    /// - `session_key`: 可选的会话键
339    /// - `context`: 上下文数据（JSON 格式）
340    ///
341    /// # 示例
342    ///
343    /// ```rust,ignore
344    /// use aster::hooks::internal::{InternalHookEvent, InternalHookEventType, InternalHookAction};
345    /// use serde_json::json;
346    ///
347    /// let event = InternalHookEvent::new(
348    ///     InternalHookEventType::Agent,
349    ///     InternalHookAction::Start,
350    ///     None,
351    ///     json!({"agent_id": "agent-001"}),
352    /// );
353    ///
354    /// assert!(event.timestamp <= chrono::Utc::now());
355    /// assert!(event.messages.is_empty());
356    /// ```
357    pub fn new(
358        event_type: InternalHookEventType,
359        action: InternalHookAction,
360        session_key: Option<String>,
361        context: serde_json::Value,
362    ) -> Self {
363        Self {
364            event_type,
365            action,
366            session_key,
367            context,
368            timestamp: Utc::now(),
369            messages: Vec::new(),
370        }
371    }
372
373    /// 获取事件键
374    ///
375    /// 返回格式为 `type:action` 的事件键，用于在注册表中匹配处理器。
376    ///
377    /// # 返回值
378    ///
379    /// 事件键字符串，如 `"agent:start"`、`"session:create"`。
380    ///
381    /// # 示例
382    ///
383    /// ```rust,ignore
384    /// use aster::hooks::internal::{InternalHookEvent, InternalHookEventType, InternalHookAction};
385    /// use serde_json::json;
386    ///
387    /// let event = InternalHookEvent::new(
388    ///     InternalHookEventType::Session,
389    ///     InternalHookAction::Create,
390    ///     None,
391    ///     json!({}),
392    /// );
393    ///
394    /// assert_eq!(event.event_key(), "session:create");
395    /// ```
396    pub fn event_key(&self) -> String {
397        format!("{}:{}", self.event_type, self.action)
398    }
399}
400
401/// 内部钩子处理器函数类型
402///
403/// 定义为异步函数，接收可变的事件引用，返回 `Result<()>`。
404/// 处理器可以修改事件的 `messages` 字段来向用户推送消息。
405///
406/// # 类型签名
407///
408/// ```rust,ignore
409/// Arc<dyn Fn(&mut InternalHookEvent) -> Pin<Box<dyn Future<Output = Result<()>> + Send>> + Send + Sync>
410/// ```
411///
412/// # 示例
413///
414/// ```rust,ignore
415/// use aster::hooks::internal::{InternalHookHandlerFn, InternalHookEvent};
416/// use std::sync::Arc;
417///
418/// let handler: InternalHookHandlerFn = Arc::new(|event| {
419///     Box::pin(async move {
420///         event.messages.push("Handler executed".to_string());
421///         Ok(())
422///     })
423/// });
424/// ```
425pub type InternalHookHandlerFn = Arc<
426    dyn Fn(&mut InternalHookEvent) -> Pin<Box<dyn Future<Output = Result<()>> + Send>>
427        + Send
428        + Sync,
429>;
430
431/// 内部钩子注册表
432///
433/// 管理事件与处理器的映射关系。支持按事件键（`type:action`）或
434/// 事件类型（`type`）注册处理器。
435///
436/// # 线程安全
437///
438/// 使用 `RwLock` 保护内部数据结构，支持多线程并发访问。
439///
440/// # 事件键格式
441///
442/// | 注册方式 | 事件键示例 | 触发条件 |
443/// |---------|-----------|---------|
444/// | 类型级别 | `agent` | 所有 Agent 事件 |
445/// | 动作级别 | `agent:start` | 仅 Agent Start 事件 |
446///
447/// # 示例
448///
449/// ```rust,ignore
450/// use aster::hooks::internal::{InternalHookRegistry, InternalHookHandlerFn};
451/// use std::sync::Arc;
452///
453/// let registry = InternalHookRegistry::new();
454///
455/// // 注册处理器
456/// let handler: InternalHookHandlerFn = Arc::new(|event| {
457///     Box::pin(async move {
458///         println!("Event: {}", event.event_key());
459///         Ok(())
460///     })
461/// });
462/// registry.register("agent:start", handler);
463///
464/// // 查询已注册的事件键
465/// let keys = registry.get_registered_keys();
466/// assert!(keys.contains(&"agent:start".to_string()));
467/// ```
468pub struct InternalHookRegistry {
469    /// 处理器映射：event_key -> handlers
470    ///
471    /// 使用 `RwLock` 保护，支持多线程并发读写。
472    /// 每个事件键可以注册多个处理器，按注册顺序存储。
473    handlers: RwLock<HashMap<String, Vec<InternalHookHandlerFn>>>,
474}
475
476impl InternalHookRegistry {
477    /// 创建新的内部钩子注册表
478    ///
479    /// # 返回值
480    ///
481    /// 返回一个空的注册表实例。
482    ///
483    /// # 示例
484    ///
485    /// ```rust,ignore
486    /// use aster::hooks::internal::InternalHookRegistry;
487    ///
488    /// let registry = InternalHookRegistry::new();
489    /// assert!(registry.get_registered_keys().is_empty());
490    /// ```
491    pub fn new() -> Self {
492        Self {
493            handlers: RwLock::new(HashMap::new()),
494        }
495    }
496
497    /// 注册处理器
498    ///
499    /// 将处理器注册到指定的事件键。支持两种注册方式：
500    /// - 类型级别：使用事件类型作为键（如 `"agent"`），匹配该类型的所有事件
501    /// - 动作级别：使用 `type:action` 格式（如 `"agent:start"`），匹配特定事件
502    ///
503    /// 同一事件键可以注册多个处理器，按注册顺序调用。
504    ///
505    /// # 参数
506    ///
507    /// - `event_key`: 事件键，可以是类型（如 `"agent"`）或 `type:action` 格式
508    /// - `handler`: 处理器函数
509    ///
510    /// # 示例
511    ///
512    /// ```rust,ignore
513    /// use aster::hooks::internal::{InternalHookRegistry, InternalHookHandlerFn};
514    /// use std::sync::Arc;
515    ///
516    /// let registry = InternalHookRegistry::new();
517    ///
518    /// // 注册类型级别处理器（匹配所有 Agent 事件）
519    /// let type_handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
520    /// registry.register("agent", type_handler);
521    ///
522    /// // 注册动作级别处理器（仅匹配 agent:start 事件）
523    /// let action_handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
524    /// registry.register("agent:start", action_handler);
525    /// ```
526    pub fn register(&self, event_key: &str, handler: InternalHookHandlerFn) {
527        let mut handlers = self.handlers.write();
528        handlers
529            .entry(event_key.to_string())
530            .or_default()
531            .push(handler);
532    }
533
534    /// 取消注册处理器
535    ///
536    /// 从指定事件键中移除处理器。使用 `Arc::ptr_eq` 比较处理器指针。
537    ///
538    /// # 参数
539    ///
540    /// - `event_key`: 事件键
541    /// - `handler`: 要移除的处理器
542    ///
543    /// # 返回值
544    ///
545    /// - `true`: 成功移除处理器
546    /// - `false`: 未找到匹配的处理器
547    ///
548    /// # 示例
549    ///
550    /// ```rust,ignore
551    /// use aster::hooks::internal::{InternalHookRegistry, InternalHookHandlerFn};
552    /// use std::sync::Arc;
553    ///
554    /// let registry = InternalHookRegistry::new();
555    ///
556    /// let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
557    /// registry.register("agent:start", handler.clone());
558    ///
559    /// // 取消注册
560    /// let removed = registry.unregister("agent:start", &handler);
561    /// assert!(removed);
562    ///
563    /// // 再次取消注册返回 false
564    /// let removed_again = registry.unregister("agent:start", &handler);
565    /// assert!(!removed_again);
566    /// ```
567    pub fn unregister(&self, event_key: &str, handler: &InternalHookHandlerFn) -> bool {
568        let mut handlers = self.handlers.write();
569        if let Some(handler_list) = handlers.get_mut(event_key) {
570            let original_len = handler_list.len();
571            handler_list.retain(|h| !Arc::ptr_eq(h, handler));
572            let removed = handler_list.len() < original_len;
573
574            // 如果列表为空，移除该事件键
575            if handler_list.is_empty() {
576                handlers.remove(event_key);
577            }
578
579            removed
580        } else {
581            false
582        }
583    }
584
585    /// 清除所有处理器
586    ///
587    /// 移除注册表中的所有处理器和事件键。
588    ///
589    /// # 示例
590    ///
591    /// ```rust,ignore
592    /// use aster::hooks::internal::{InternalHookRegistry, InternalHookHandlerFn};
593    /// use std::sync::Arc;
594    ///
595    /// let registry = InternalHookRegistry::new();
596    ///
597    /// let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
598    /// registry.register("agent:start", handler.clone());
599    /// registry.register("session:create", handler);
600    ///
601    /// assert_eq!(registry.get_registered_keys().len(), 2);
602    ///
603    /// registry.clear();
604    /// assert!(registry.get_registered_keys().is_empty());
605    /// ```
606    pub fn clear(&self) {
607        let mut handlers = self.handlers.write();
608        handlers.clear();
609    }
610
611    /// 获取已注册的事件键
612    ///
613    /// 返回所有已注册处理器的事件键列表。
614    ///
615    /// # 返回值
616    ///
617    /// 事件键列表，顺序不保证。
618    ///
619    /// # 示例
620    ///
621    /// ```rust,ignore
622    /// use aster::hooks::internal::{InternalHookRegistry, InternalHookHandlerFn};
623    /// use std::sync::Arc;
624    ///
625    /// let registry = InternalHookRegistry::new();
626    ///
627    /// let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
628    /// registry.register("agent:start", handler.clone());
629    /// registry.register("agent:stop", handler.clone());
630    /// registry.register("session:create", handler);
631    ///
632    /// let keys = registry.get_registered_keys();
633    /// assert_eq!(keys.len(), 3);
634    /// assert!(keys.contains(&"agent:start".to_string()));
635    /// assert!(keys.contains(&"agent:stop".to_string()));
636    /// assert!(keys.contains(&"session:create".to_string()));
637    /// ```
638    pub fn get_registered_keys(&self) -> Vec<String> {
639        let handlers = self.handlers.read();
640        handlers.keys().cloned().collect()
641    }
642
643    /// 获取指定事件键的处理器列表
644    ///
645    /// 返回注册到指定事件键的所有处理器的克隆列表。
646    /// 此方法主要用于内部触发事件时获取处理器。
647    ///
648    /// # 参数
649    ///
650    /// - `event_key`: 事件键
651    ///
652    /// # 返回值
653    ///
654    /// 处理器列表，如果没有注册任何处理器则返回空列表。
655    pub fn get_handlers(&self, event_key: &str) -> Vec<InternalHookHandlerFn> {
656        let handlers = self.handlers.read();
657        handlers.get(event_key).cloned().unwrap_or_default()
658    }
659
660    /// 触发事件
661    ///
662    /// 先调用类型级别处理器（如 `"agent"`），再调用动作级别处理器（如 `"agent:start"`）。
663    /// 处理器错误会被捕获并记录日志，不影响其他处理器执行。
664    ///
665    /// # 执行顺序
666    ///
667    /// 1. 获取类型级别处理器（使用 `event.event_type.to_string()` 作为键）
668    /// 2. 获取动作级别处理器（使用 `event.event_key()` 作为键）
669    /// 3. 按注册顺序依次调用所有处理器
670    ///
671    /// # 错误处理
672    ///
673    /// - 处理器返回 `Err`: 记录错误日志，继续执行下一个处理器
674    /// - 处理器超时: 记录警告日志，继续执行下一个处理器
675    ///
676    /// # 参数
677    ///
678    /// - `event`: 可变的事件引用，处理器可以修改事件的 `messages` 字段
679    ///
680    /// # 返回值
681    ///
682    /// 始终返回 `Ok(())`，处理器错误不会导致整体失败。
683    ///
684    /// # 示例
685    ///
686    /// ```rust,ignore
687    /// use aster::hooks::internal::{InternalHookRegistry, InternalHookEvent, InternalHookEventType, InternalHookAction, InternalHookHandlerFn};
688    /// use std::sync::Arc;
689    /// use serde_json::json;
690    ///
691    /// let registry = InternalHookRegistry::new();
692    ///
693    /// // 注册类型级别处理器
694    /// let type_handler: InternalHookHandlerFn = Arc::new(|event| {
695    ///     Box::pin(async move {
696    ///         event.messages.push("Type handler called".to_string());
697    ///         Ok(())
698    ///     })
699    /// });
700    /// registry.register("agent", type_handler);
701    ///
702    /// // 注册动作级别处理器
703    /// let action_handler: InternalHookHandlerFn = Arc::new(|event| {
704    ///     Box::pin(async move {
705    ///         event.messages.push("Action handler called".to_string());
706    ///         Ok(())
707    ///     })
708    /// });
709    /// registry.register("agent:start", action_handler);
710    ///
711    /// // 触发事件
712    /// let mut event = InternalHookEvent::new(
713    ///     InternalHookEventType::Agent,
714    ///     InternalHookAction::Start,
715    ///     None,
716    ///     json!({}),
717    /// );
718    ///
719    /// // 在异步上下文中调用
720    /// // registry.trigger(&mut event).await.unwrap();
721    /// // assert_eq!(event.messages, vec!["Type handler called", "Action handler called"]);
722    /// ```
723    pub async fn trigger(&self, event: &mut InternalHookEvent) -> Result<()> {
724        use std::time::Duration;
725        use tokio::time::timeout;
726        use tracing::{debug, error, warn};
727
728        // 默认处理器超时时间：30 秒
729        const HANDLER_TIMEOUT: Duration = Duration::from_secs(30);
730
731        let type_key = event.event_type.to_string();
732        let action_key = event.event_key();
733
734        debug!(
735            event_type = %type_key,
736            action_key = %action_key,
737            "Triggering internal hook event"
738        );
739
740        // 获取类型级别处理器
741        let type_handlers = self.get_handlers(&type_key);
742        // 获取动作级别处理器
743        let action_handlers = self.get_handlers(&action_key);
744
745        // 如果没有任何处理器，静默返回
746        if type_handlers.is_empty() && action_handlers.is_empty() {
747            debug!(
748                event_type = %type_key,
749                action_key = %action_key,
750                "No handlers registered for event, skipping"
751            );
752            return Ok(());
753        }
754
755        // 先调用类型级别处理器
756        for (index, handler) in type_handlers.iter().enumerate() {
757            debug!(
758                event_type = %type_key,
759                handler_index = index,
760                "Calling type-level handler"
761            );
762
763            match timeout(HANDLER_TIMEOUT, handler(event)).await {
764                Ok(Ok(())) => {
765                    debug!(
766                        event_type = %type_key,
767                        handler_index = index,
768                        "Type-level handler completed successfully"
769                    );
770                }
771                Ok(Err(e)) => {
772                    error!(
773                        event_type = %type_key,
774                        handler_index = index,
775                        error = %e,
776                        "Type-level handler failed with error"
777                    );
778                    // 继续执行下一个处理器
779                }
780                Err(_) => {
781                    warn!(
782                        event_type = %type_key,
783                        handler_index = index,
784                        timeout_secs = HANDLER_TIMEOUT.as_secs(),
785                        "Type-level handler timed out"
786                    );
787                    // 继续执行下一个处理器
788                }
789            }
790        }
791
792        // 再调用动作级别处理器
793        for (index, handler) in action_handlers.iter().enumerate() {
794            debug!(
795                action_key = %action_key,
796                handler_index = index,
797                "Calling action-level handler"
798            );
799
800            match timeout(HANDLER_TIMEOUT, handler(event)).await {
801                Ok(Ok(())) => {
802                    debug!(
803                        action_key = %action_key,
804                        handler_index = index,
805                        "Action-level handler completed successfully"
806                    );
807                }
808                Ok(Err(e)) => {
809                    error!(
810                        action_key = %action_key,
811                        handler_index = index,
812                        error = %e,
813                        "Action-level handler failed with error"
814                    );
815                    // 继续执行下一个处理器
816                }
817                Err(_) => {
818                    warn!(
819                        action_key = %action_key,
820                        handler_index = index,
821                        timeout_secs = HANDLER_TIMEOUT.as_secs(),
822                        "Action-level handler timed out"
823                    );
824                    // 继续执行下一个处理器
825                }
826            }
827        }
828
829        debug!(
830            event_type = %type_key,
831            action_key = %action_key,
832            type_handler_count = type_handlers.len(),
833            action_handler_count = action_handlers.len(),
834            "Internal hook event trigger completed"
835        );
836
837        Ok(())
838    }
839
840    /// 检查是否有注册的处理器
841    ///
842    /// # 返回值
843    ///
844    /// - `true`: 注册表为空
845    /// - `false`: 有注册的处理器
846    pub fn is_empty(&self) -> bool {
847        let handlers = self.handlers.read();
848        handlers.is_empty()
849    }
850
851    /// 获取注册的处理器总数
852    ///
853    /// # 返回值
854    ///
855    /// 所有事件键下注册的处理器总数。
856    pub fn handler_count(&self) -> usize {
857        let handlers = self.handlers.read();
858        handlers.values().map(|v| v.len()).sum()
859    }
860}
861
862impl Default for InternalHookRegistry {
863    fn default() -> Self {
864        Self::new()
865    }
866}
867
868impl fmt::Debug for InternalHookRegistry {
869    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
870        let handlers = self.handlers.read();
871        let keys: Vec<_> = handlers.keys().collect();
872        let counts: HashMap<_, _> = handlers.iter().map(|(k, v)| (k, v.len())).collect();
873        f.debug_struct("InternalHookRegistry")
874            .field("registered_keys", &keys)
875            .field("handler_counts", &counts)
876            .finish()
877    }
878}
879
880// ============================================================================
881// 全局注册表单例
882// ============================================================================
883
884/// 全局内部钩子注册表
885///
886/// 使用 `once_cell::sync::Lazy` 实现的全局单例，在首次访问时初始化。
887/// 整个应用程序共享同一个注册表实例。
888static GLOBAL_INTERNAL_REGISTRY: Lazy<InternalHookRegistry> = Lazy::new(InternalHookRegistry::new);
889
890/// 获取全局内部钩子注册表
891///
892/// 返回全局共享的 `InternalHookRegistry` 实例的静态引用。
893/// 此函数是线程安全的，可以在任何地方调用。
894///
895/// # 返回值
896///
897/// 返回全局 `InternalHookRegistry` 实例的静态引用。
898///
899/// # 示例
900///
901/// ```rust,ignore
902/// use aster::hooks::internal::{global_internal_registry, InternalHookHandlerFn};
903/// use std::sync::Arc;
904///
905/// // 获取全局注册表
906/// let registry = global_internal_registry();
907///
908/// // 注册处理器
909/// let handler: InternalHookHandlerFn = Arc::new(|event| {
910///     Box::pin(async move {
911///         println!("Event: {}", event.event_key());
912///         Ok(())
913///     })
914/// });
915/// registry.register("agent:start", handler);
916///
917/// // 查询已注册的事件键
918/// let keys = registry.get_registered_keys();
919/// assert!(keys.contains(&"agent:start".to_string()));
920/// ```
921///
922/// # 线程安全
923///
924/// 此函数返回的引用是线程安全的，`InternalHookRegistry` 内部使用
925/// `RwLock` 保护数据结构，支持多线程并发访问。
926pub fn global_internal_registry() -> &'static InternalHookRegistry {
927    &GLOBAL_INTERNAL_REGISTRY
928}
929
930// ============================================================================
931// 辅助函数
932// ============================================================================
933
934/// 创建内部钩子事件
935///
936/// 这是一个便捷函数，用于创建 `InternalHookEvent` 实例。
937/// 内部调用 `InternalHookEvent::new()` 构造函数。
938///
939/// # 参数
940///
941/// - `event_type`: 事件类型
942/// - `action`: 事件动作
943/// - `session_key`: 可选的会话键
944/// - `context`: 上下文数据（JSON 格式）
945///
946/// # 返回值
947///
948/// 返回新创建的 `InternalHookEvent` 实例。
949///
950/// # 示例
951///
952/// ```rust,ignore
953/// use aster::hooks::internal::{
954///     create_internal_hook_event, InternalHookEventType, InternalHookAction
955/// };
956/// use serde_json::json;
957///
958/// let event = create_internal_hook_event(
959///     InternalHookEventType::Agent,
960///     InternalHookAction::Start,
961///     Some("session-123".to_string()),
962///     json!({"agent_id": "agent-001"}),
963/// );
964///
965/// assert_eq!(event.event_key(), "agent:start");
966/// ```
967pub fn create_internal_hook_event(
968    event_type: InternalHookEventType,
969    action: InternalHookAction,
970    session_key: Option<String>,
971    context: serde_json::Value,
972) -> InternalHookEvent {
973    InternalHookEvent::new(event_type, action, session_key, context)
974}
975
976/// 触发内部钩子事件（使用全局注册表）
977///
978/// 这是一个便捷函数，使用全局注册表触发事件。
979/// 先调用类型级别处理器，再调用动作级别处理器。
980///
981/// # 参数
982///
983/// - `event`: 可变的事件引用，处理器可以修改事件的 `messages` 字段
984///
985/// # 返回值
986///
987/// 始终返回 `Ok(())`，处理器错误不会导致整体失败。
988///
989/// # 示例
990///
991/// ```rust,ignore
992/// use aster::hooks::internal::{
993///     trigger_internal_hook, create_internal_hook_event,
994///     InternalHookEventType, InternalHookAction
995/// };
996/// use serde_json::json;
997///
998/// async fn example() {
999///     let mut event = create_internal_hook_event(
1000///         InternalHookEventType::Agent,
1001///         InternalHookAction::Start,
1002///         None,
1003///         json!({"agent_id": "agent-001"}),
1004///     );
1005///
1006///     trigger_internal_hook(&mut event).await.unwrap();
1007///     println!("Messages: {:?}", event.messages);
1008/// }
1009/// ```
1010pub async fn trigger_internal_hook(event: &mut InternalHookEvent) -> Result<()> {
1011    global_internal_registry().trigger(event).await
1012}
1013
1014/// 注册内部钩子处理器（使用全局注册表）
1015///
1016/// 这是一个便捷函数，将处理器注册到全局注册表。
1017/// 支持类型级别（如 `"agent"`）和动作级别（如 `"agent:start"`）注册。
1018///
1019/// # 参数
1020///
1021/// - `event_key`: 事件键，可以是类型或 `type:action` 格式
1022/// - `handler`: 处理器函数
1023///
1024/// # 示例
1025///
1026/// ```rust,ignore
1027/// use aster::hooks::internal::{register_internal_hook, InternalHookHandlerFn};
1028/// use std::sync::Arc;
1029///
1030/// // 注册动作级别处理器
1031/// let handler: InternalHookHandlerFn = Arc::new(|event| {
1032///     Box::pin(async move {
1033///         event.messages.push("Handler executed".to_string());
1034///         Ok(())
1035///     })
1036/// });
1037/// register_internal_hook("agent:start", handler);
1038///
1039/// // 注册类型级别处理器（匹配所有 Agent 事件）
1040/// let type_handler: InternalHookHandlerFn = Arc::new(|_| {
1041///     Box::pin(async move { Ok(()) })
1042/// });
1043/// register_internal_hook("agent", type_handler);
1044/// ```
1045pub fn register_internal_hook(event_key: &str, handler: InternalHookHandlerFn) {
1046    global_internal_registry().register(event_key, handler);
1047}
1048
1049/// 取消注册内部钩子处理器（使用全局注册表）
1050///
1051/// 这是一个便捷函数，从全局注册表中移除处理器。
1052/// 使用 `Arc::ptr_eq` 比较处理器指针。
1053///
1054/// # 参数
1055///
1056/// - `event_key`: 事件键
1057/// - `handler`: 要移除的处理器
1058///
1059/// # 返回值
1060///
1061/// - `true`: 成功移除处理器
1062/// - `false`: 未找到匹配的处理器
1063///
1064/// # 示例
1065///
1066/// ```rust,ignore
1067/// use aster::hooks::internal::{
1068///     register_internal_hook, unregister_internal_hook, InternalHookHandlerFn
1069/// };
1070/// use std::sync::Arc;
1071///
1072/// let handler: InternalHookHandlerFn = Arc::new(|_| {
1073///     Box::pin(async move { Ok(()) })
1074/// });
1075///
1076/// // 注册处理器
1077/// register_internal_hook("agent:start", handler.clone());
1078///
1079/// // 取消注册
1080/// let removed = unregister_internal_hook("agent:start", &handler);
1081/// assert!(removed);
1082/// ```
1083pub fn unregister_internal_hook(event_key: &str, handler: &InternalHookHandlerFn) -> bool {
1084    global_internal_registry().unregister(event_key, handler)
1085}
1086
1087/// 清除所有内部钩子处理器（使用全局注册表）
1088///
1089/// 这是一个便捷函数，清除全局注册表中的所有处理器。
1090/// 主要用于测试清理或应用程序重置。
1091///
1092/// # 警告
1093///
1094/// 此操作会移除所有已注册的处理器，请谨慎使用。
1095///
1096/// # 示例
1097///
1098/// ```rust,ignore
1099/// use aster::hooks::internal::{
1100///     register_internal_hook, clear_internal_hooks,
1101///     global_internal_registry, InternalHookHandlerFn
1102/// };
1103/// use std::sync::Arc;
1104///
1105/// let handler: InternalHookHandlerFn = Arc::new(|_| {
1106///     Box::pin(async move { Ok(()) })
1107/// });
1108///
1109/// register_internal_hook("agent:start", handler.clone());
1110/// register_internal_hook("session:create", handler);
1111///
1112/// // 清除所有处理器
1113/// clear_internal_hooks();
1114///
1115/// assert!(global_internal_registry().is_empty());
1116/// ```
1117pub fn clear_internal_hooks() {
1118    global_internal_registry().clear();
1119}
1120
1121// ============================================================================
1122// Agent 事件辅助函数
1123// ============================================================================
1124
1125/// 触发 agent:start 事件
1126///
1127/// 当 Agent 启动时调用此函数触发 `agent:start` 事件。
1128/// 事件的 context 包含 `agent_id` 和 `agent_type` 字段。
1129///
1130/// # 参数
1131///
1132/// - `agent_id`: Agent 的唯一标识符
1133/// - `agent_type`: Agent 的类型（如 "coding"、"chat" 等）
1134/// - `session_key`: 可选的会话键
1135///
1136/// # 返回值
1137///
1138/// 返回触发后的 `InternalHookEvent`，调用者可以访问处理器添加的消息。
1139///
1140/// # 示例
1141///
1142/// ```rust,ignore
1143/// use aster::hooks::internal::trigger_agent_start;
1144///
1145/// async fn start_agent() {
1146///     let event = trigger_agent_start(
1147///         "agent-001",
1148///         "coding",
1149///         Some("session-123".to_string()),
1150///     ).await.unwrap();
1151///
1152///     // 检查处理器添加的消息
1153///     for msg in &event.messages {
1154///         println!("Handler message: {}", msg);
1155///     }
1156/// }
1157/// ```
1158///
1159/// **Validates: Requirements 7.1, 7.5**
1160pub async fn trigger_agent_start(
1161    agent_id: &str,
1162    agent_type: &str,
1163    session_key: Option<String>,
1164) -> Result<InternalHookEvent> {
1165    let mut event = create_internal_hook_event(
1166        InternalHookEventType::Agent,
1167        InternalHookAction::Start,
1168        session_key,
1169        serde_json::json!({
1170            "agent_id": agent_id,
1171            "agent_type": agent_type
1172        }),
1173    );
1174
1175    trigger_internal_hook(&mut event).await?;
1176
1177    Ok(event)
1178}
1179
1180/// 触发 agent:stop 事件
1181///
1182/// 当 Agent 停止时调用此函数触发 `agent:stop` 事件。
1183/// 事件的 context 包含 `agent_id` 和 `agent_type` 字段。
1184///
1185/// # 参数
1186///
1187/// - `agent_id`: Agent 的唯一标识符
1188/// - `agent_type`: Agent 的类型（如 "coding"、"chat" 等）
1189/// - `session_key`: 可选的会话键
1190///
1191/// # 返回值
1192///
1193/// 返回触发后的 `InternalHookEvent`，调用者可以访问处理器添加的消息。
1194///
1195/// # 示例
1196///
1197/// ```rust,ignore
1198/// use aster::hooks::internal::trigger_agent_stop;
1199///
1200/// async fn stop_agent() {
1201///     let event = trigger_agent_stop(
1202///         "agent-001",
1203///         "coding",
1204///         Some("session-123".to_string()),
1205///     ).await.unwrap();
1206///
1207///     println!("Agent stopped, messages: {:?}", event.messages);
1208/// }
1209/// ```
1210///
1211/// **Validates: Requirements 7.2, 7.5**
1212pub async fn trigger_agent_stop(
1213    agent_id: &str,
1214    agent_type: &str,
1215    session_key: Option<String>,
1216) -> Result<InternalHookEvent> {
1217    let mut event = create_internal_hook_event(
1218        InternalHookEventType::Agent,
1219        InternalHookAction::Stop,
1220        session_key,
1221        serde_json::json!({
1222            "agent_id": agent_id,
1223            "agent_type": agent_type
1224        }),
1225    );
1226
1227    trigger_internal_hook(&mut event).await?;
1228
1229    Ok(event)
1230}
1231
1232/// 触发 agent:error 事件
1233///
1234/// 当 Agent 发生错误时调用此函数触发 `agent:error` 事件。
1235/// 事件的 context 包含 `agent_id`、`agent_type` 和 `error` 字段。
1236///
1237/// # 参数
1238///
1239/// - `agent_id`: Agent 的唯一标识符
1240/// - `agent_type`: Agent 的类型（如 "coding"、"chat" 等）
1241/// - `error`: 错误信息
1242/// - `session_key`: 可选的会话键
1243///
1244/// # 返回值
1245///
1246/// 返回触发后的 `InternalHookEvent`，调用者可以访问处理器添加的消息。
1247///
1248/// # 示例
1249///
1250/// ```rust,ignore
1251/// use aster::hooks::internal::trigger_agent_error;
1252///
1253/// async fn handle_agent_error() {
1254///     let event = trigger_agent_error(
1255///         "agent-001",
1256///         "coding",
1257///         "Connection timeout",
1258///         Some("session-123".to_string()),
1259///     ).await.unwrap();
1260///
1261///     println!("Error event triggered, messages: {:?}", event.messages);
1262/// }
1263/// ```
1264///
1265/// **Validates: Requirements 7.3, 7.5**
1266pub async fn trigger_agent_error(
1267    agent_id: &str,
1268    agent_type: &str,
1269    error: &str,
1270    session_key: Option<String>,
1271) -> Result<InternalHookEvent> {
1272    let mut event = create_internal_hook_event(
1273        InternalHookEventType::Agent,
1274        InternalHookAction::Error,
1275        session_key,
1276        serde_json::json!({
1277            "agent_id": agent_id,
1278            "agent_type": agent_type,
1279            "error": error
1280        }),
1281    );
1282
1283    trigger_internal_hook(&mut event).await?;
1284
1285    Ok(event)
1286}
1287
1288/// 触发 agent:bootstrap 事件
1289///
1290/// 当 Agent 完成初始化引导时调用此函数触发 `agent:bootstrap` 事件。
1291/// 事件的 context 包含 `agent_id` 和 `agent_type` 字段。
1292///
1293/// # 参数
1294///
1295/// - `agent_id`: Agent 的唯一标识符
1296/// - `agent_type`: Agent 的类型（如 "coding"、"chat" 等）
1297/// - `session_key`: 可选的会话键
1298///
1299/// # 返回值
1300///
1301/// 返回触发后的 `InternalHookEvent`，调用者可以访问处理器添加的消息。
1302///
1303/// # 示例
1304///
1305/// ```rust,ignore
1306/// use aster::hooks::internal::trigger_agent_bootstrap;
1307///
1308/// async fn bootstrap_agent() {
1309///     let event = trigger_agent_bootstrap(
1310///         "agent-001",
1311///         "coding",
1312///         Some("session-123".to_string()),
1313///     ).await.unwrap();
1314///
1315///     println!("Bootstrap complete, messages: {:?}", event.messages);
1316/// }
1317/// ```
1318///
1319/// **Validates: Requirements 7.4, 7.5**
1320pub async fn trigger_agent_bootstrap(
1321    agent_id: &str,
1322    agent_type: &str,
1323    session_key: Option<String>,
1324) -> Result<InternalHookEvent> {
1325    let mut event = create_internal_hook_event(
1326        InternalHookEventType::Agent,
1327        InternalHookAction::Bootstrap,
1328        session_key,
1329        serde_json::json!({
1330            "agent_id": agent_id,
1331            "agent_type": agent_type
1332        }),
1333    );
1334
1335    trigger_internal_hook(&mut event).await?;
1336
1337    Ok(event)
1338}
1339
1340// ============================================================================
1341// Session 事件辅助函数
1342// ============================================================================
1343
1344/// 触发 session:create 事件
1345///
1346/// 当 Session 创建时调用此函数触发 `session:create` 事件。
1347/// 事件的 context 包含 `session_id` 和 `session_key` 字段。
1348///
1349/// # 参数
1350///
1351/// - `session_id`: Session 的唯一标识符
1352/// - `session_key`: Session 的键（用于存储和检索）
1353///
1354/// # 返回值
1355///
1356/// 返回触发后的 `InternalHookEvent`，调用者可以访问处理器添加的消息。
1357///
1358/// # 示例
1359///
1360/// ```rust,ignore
1361/// use aster::hooks::internal::trigger_session_create;
1362///
1363/// async fn create_session() {
1364///     let event = trigger_session_create(
1365///         "session-001",
1366///         "user:session:123",
1367///     ).await.unwrap();
1368///
1369///     // 检查处理器添加的消息
1370///     for msg in &event.messages {
1371///         println!("Handler message: {}", msg);
1372///     }
1373/// }
1374/// ```
1375///
1376/// **Validates: Requirements 8.1, 8.5**
1377pub async fn trigger_session_create(
1378    session_id: &str,
1379    session_key: &str,
1380) -> Result<InternalHookEvent> {
1381    let mut event = create_internal_hook_event(
1382        InternalHookEventType::Session,
1383        InternalHookAction::Create,
1384        Some(session_key.to_string()),
1385        serde_json::json!({
1386            "session_id": session_id,
1387            "session_key": session_key,
1388            "source": "startup"
1389        }),
1390    );
1391
1392    trigger_internal_hook(&mut event).await?;
1393
1394    Ok(event)
1395}
1396
1397/// 触发 session:resume 事件
1398///
1399/// 当 Session 恢复时调用此函数触发 `session:resume` 事件。
1400/// 事件的 context 包含 `session_id` 和 `session_key` 字段。
1401///
1402/// # 参数
1403///
1404/// - `session_id`: Session 的唯一标识符
1405/// - `session_key`: Session 的键（用于存储和检索）
1406///
1407/// # 返回值
1408///
1409/// 返回触发后的 `InternalHookEvent`，调用者可以访问处理器添加的消息。
1410///
1411/// # 示例
1412///
1413/// ```rust,ignore
1414/// use aster::hooks::internal::trigger_session_resume;
1415///
1416/// async fn resume_session() {
1417///     let event = trigger_session_resume(
1418///         "session-001",
1419///         "user:session:123",
1420///     ).await.unwrap();
1421///
1422///     println!("Session resumed, messages: {:?}", event.messages);
1423/// }
1424/// ```
1425///
1426/// **Validates: Requirements 8.2, 8.5**
1427pub async fn trigger_session_resume(
1428    session_id: &str,
1429    session_key: &str,
1430) -> Result<InternalHookEvent> {
1431    let mut event = create_internal_hook_event(
1432        InternalHookEventType::Session,
1433        InternalHookAction::Resume,
1434        Some(session_key.to_string()),
1435        serde_json::json!({
1436            "session_id": session_id,
1437            "session_key": session_key,
1438            "source": "resume"
1439        }),
1440    );
1441
1442    trigger_internal_hook(&mut event).await?;
1443
1444    Ok(event)
1445}
1446
1447/// 触发 session:end 事件
1448///
1449/// 当 Session 结束时调用此函数触发 `session:end` 事件。
1450/// 事件的 context 包含 `session_id`、`session_key` 和可选的 `reason` 字段。
1451///
1452/// # 参数
1453///
1454/// - `session_id`: Session 的唯一标识符
1455/// - `session_key`: Session 的键（用于存储和检索）
1456/// - `reason`: 可选的结束原因（如 "clear"、"logout"、"exit"、"other"）
1457///
1458/// # 返回值
1459///
1460/// 返回触发后的 `InternalHookEvent`，调用者可以访问处理器添加的消息。
1461///
1462/// # 示例
1463///
1464/// ```rust,ignore
1465/// use aster::hooks::internal::trigger_session_end;
1466///
1467/// async fn end_session() {
1468///     let event = trigger_session_end(
1469///         "session-001",
1470///         "user:session:123",
1471///         Some("logout"),
1472///     ).await.unwrap();
1473///
1474///     println!("Session ended, messages: {:?}", event.messages);
1475/// }
1476/// ```
1477///
1478/// **Validates: Requirements 8.3, 8.5**
1479pub async fn trigger_session_end(
1480    session_id: &str,
1481    session_key: &str,
1482    reason: Option<&str>,
1483) -> Result<InternalHookEvent> {
1484    let mut event = create_internal_hook_event(
1485        InternalHookEventType::Session,
1486        InternalHookAction::End,
1487        Some(session_key.to_string()),
1488        serde_json::json!({
1489            "session_id": session_id,
1490            "session_key": session_key,
1491            "source": "clear",
1492            "reason": reason.unwrap_or("other")
1493        }),
1494    );
1495
1496    trigger_internal_hook(&mut event).await?;
1497
1498    Ok(event)
1499}
1500
1501/// 触发 session:compact 事件
1502///
1503/// 当 Session 压缩时调用此函数触发 `session:compact` 事件。
1504/// 事件的 context 包含 `session_id` 和 `session_key` 字段。
1505///
1506/// # 参数
1507///
1508/// - `session_id`: Session 的唯一标识符
1509/// - `session_key`: Session 的键（用于存储和检索）
1510///
1511/// # 返回值
1512///
1513/// 返回触发后的 `InternalHookEvent`，调用者可以访问处理器添加的消息。
1514///
1515/// # 示例
1516///
1517/// ```rust,ignore
1518/// use aster::hooks::internal::trigger_session_compact;
1519///
1520/// async fn compact_session() {
1521///     let event = trigger_session_compact(
1522///         "session-001",
1523///         "user:session:123",
1524///     ).await.unwrap();
1525///
1526///     println!("Session compacted, messages: {:?}", event.messages);
1527/// }
1528/// ```
1529///
1530/// **Validates: Requirements 8.4, 8.5**
1531pub async fn trigger_session_compact(
1532    session_id: &str,
1533    session_key: &str,
1534) -> Result<InternalHookEvent> {
1535    let mut event = create_internal_hook_event(
1536        InternalHookEventType::Session,
1537        InternalHookAction::Compact,
1538        Some(session_key.to_string()),
1539        serde_json::json!({
1540            "session_id": session_id,
1541            "session_key": session_key,
1542            "source": "compact"
1543        }),
1544    );
1545
1546    trigger_internal_hook(&mut event).await?;
1547
1548    Ok(event)
1549}
1550
1551// ============================================================================
1552// Command 事件辅助函数
1553// ============================================================================
1554
1555/// 触发 command:new 事件
1556///
1557/// 当用户执行 /new 命令时调用此函数触发 `command:new` 事件。
1558/// 事件的 context 包含 `command_name`、`command_args` 和 `raw_input` 字段。
1559///
1560/// # 参数
1561///
1562/// - `command_args`: 命令参数列表（如 `["--model", "gpt-4"]`）
1563/// - `raw_input`: 原始输入字符串（如 `/new --model gpt-4`）
1564/// - `session_key`: 可选的会话键
1565///
1566/// # 返回值
1567///
1568/// 返回触发后的 `InternalHookEvent`，调用者可以访问处理器添加的消息。
1569///
1570/// # 示例
1571///
1572/// ```rust,ignore
1573/// use aster::hooks::internal::trigger_command_new;
1574///
1575/// async fn handle_new_command() {
1576///     let event = trigger_command_new(
1577///         &["--model".to_string(), "gpt-4".to_string()],
1578///         "/new --model gpt-4",
1579///         Some("session-123".to_string()),
1580///     ).await.unwrap();
1581///
1582///     // 检查处理器添加的消息
1583///     for msg in &event.messages {
1584///         println!("Handler message: {}", msg);
1585///     }
1586/// }
1587/// ```
1588///
1589/// **Validates: Requirements 9.1, 9.5**
1590pub async fn trigger_command_new(
1591    command_args: &[String],
1592    raw_input: &str,
1593    session_key: Option<String>,
1594) -> Result<InternalHookEvent> {
1595    let mut event = create_internal_hook_event(
1596        InternalHookEventType::Command,
1597        InternalHookAction::New,
1598        session_key,
1599        serde_json::json!({
1600            "command_name": "new",
1601            "command_args": command_args,
1602            "raw_input": raw_input
1603        }),
1604    );
1605
1606    trigger_internal_hook(&mut event).await?;
1607
1608    Ok(event)
1609}
1610
1611/// 触发 command:reset 事件
1612///
1613/// 当用户执行 /reset 命令时调用此函数触发 `command:reset` 事件。
1614/// 事件的 context 包含 `command_name`、`command_args` 和 `raw_input` 字段。
1615///
1616/// # 参数
1617///
1618/// - `command_args`: 命令参数列表
1619/// - `raw_input`: 原始输入字符串（如 `/reset`）
1620/// - `session_key`: 可选的会话键
1621///
1622/// # 返回值
1623///
1624/// 返回触发后的 `InternalHookEvent`，调用者可以访问处理器添加的消息。
1625///
1626/// # 示例
1627///
1628/// ```rust,ignore
1629/// use aster::hooks::internal::trigger_command_reset;
1630///
1631/// async fn handle_reset_command() {
1632///     let event = trigger_command_reset(
1633///         &[],
1634///         "/reset",
1635///         Some("session-123".to_string()),
1636///     ).await.unwrap();
1637///
1638///     println!("Reset command triggered, messages: {:?}", event.messages);
1639/// }
1640/// ```
1641///
1642/// **Validates: Requirements 9.2, 9.5**
1643pub async fn trigger_command_reset(
1644    command_args: &[String],
1645    raw_input: &str,
1646    session_key: Option<String>,
1647) -> Result<InternalHookEvent> {
1648    let mut event = create_internal_hook_event(
1649        InternalHookEventType::Command,
1650        InternalHookAction::Reset,
1651        session_key,
1652        serde_json::json!({
1653            "command_name": "reset",
1654            "command_args": command_args,
1655            "raw_input": raw_input
1656        }),
1657    );
1658
1659    trigger_internal_hook(&mut event).await?;
1660
1661    Ok(event)
1662}
1663
1664/// 触发 command:status 事件
1665///
1666/// 当用户执行 /status 命令时调用此函数触发 `command:status` 事件。
1667/// 事件的 context 包含 `command_name`、`command_args` 和 `raw_input` 字段。
1668///
1669/// # 参数
1670///
1671/// - `command_args`: 命令参数列表
1672/// - `raw_input`: 原始输入字符串（如 `/status`）
1673/// - `session_key`: 可选的会话键
1674///
1675/// # 返回值
1676///
1677/// 返回触发后的 `InternalHookEvent`，调用者可以访问处理器添加的消息。
1678///
1679/// # 示例
1680///
1681/// ```rust,ignore
1682/// use aster::hooks::internal::trigger_command_status;
1683///
1684/// async fn handle_status_command() {
1685///     let event = trigger_command_status(
1686///         &[],
1687///         "/status",
1688///         Some("session-123".to_string()),
1689///     ).await.unwrap();
1690///
1691///     println!("Status command triggered, messages: {:?}", event.messages);
1692/// }
1693/// ```
1694///
1695/// **Validates: Requirements 9.3, 9.5**
1696pub async fn trigger_command_status(
1697    command_args: &[String],
1698    raw_input: &str,
1699    session_key: Option<String>,
1700) -> Result<InternalHookEvent> {
1701    let mut event = create_internal_hook_event(
1702        InternalHookEventType::Command,
1703        InternalHookAction::Status,
1704        session_key,
1705        serde_json::json!({
1706            "command_name": "status",
1707            "command_args": command_args,
1708            "raw_input": raw_input
1709        }),
1710    );
1711
1712    trigger_internal_hook(&mut event).await?;
1713
1714    Ok(event)
1715}
1716
1717/// 触发 command:help 事件
1718///
1719/// 当用户执行 /help 命令时调用此函数触发 `command:help` 事件。
1720/// 事件的 context 包含 `command_name`、`command_args` 和 `raw_input` 字段。
1721///
1722/// # 参数
1723///
1724/// - `command_args`: 命令参数列表（如 `["new"]` 表示查看 new 命令的帮助）
1725/// - `raw_input`: 原始输入字符串（如 `/help new`）
1726/// - `session_key`: 可选的会话键
1727///
1728/// # 返回值
1729///
1730/// 返回触发后的 `InternalHookEvent`，调用者可以访问处理器添加的消息。
1731///
1732/// # 示例
1733///
1734/// ```rust,ignore
1735/// use aster::hooks::internal::trigger_command_help;
1736///
1737/// async fn handle_help_command() {
1738///     let event = trigger_command_help(
1739///         &["new".to_string()],
1740///         "/help new",
1741///         Some("session-123".to_string()),
1742///     ).await.unwrap();
1743///
1744///     println!("Help command triggered, messages: {:?}", event.messages);
1745/// }
1746/// ```
1747///
1748/// **Validates: Requirements 9.4, 9.5**
1749pub async fn trigger_command_help(
1750    command_args: &[String],
1751    raw_input: &str,
1752    session_key: Option<String>,
1753) -> Result<InternalHookEvent> {
1754    let mut event = create_internal_hook_event(
1755        InternalHookEventType::Command,
1756        InternalHookAction::Help,
1757        session_key,
1758        serde_json::json!({
1759            "command_name": "help",
1760            "command_args": command_args,
1761            "raw_input": raw_input
1762        }),
1763    );
1764
1765    trigger_internal_hook(&mut event).await?;
1766
1767    Ok(event)
1768}
1769
1770#[cfg(test)]
1771mod tests {
1772    use super::*;
1773    use serial_test::serial;
1774
1775    #[test]
1776    fn test_internal_hook_event_type_display() {
1777        assert_eq!(InternalHookEventType::Agent.to_string(), "agent");
1778        assert_eq!(InternalHookEventType::Session.to_string(), "session");
1779        assert_eq!(InternalHookEventType::Tool.to_string(), "tool");
1780        assert_eq!(InternalHookEventType::Command.to_string(), "command");
1781        assert_eq!(InternalHookEventType::Gateway.to_string(), "gateway");
1782    }
1783
1784    #[test]
1785    fn test_internal_hook_event_type_serialize() {
1786        assert_eq!(
1787            serde_json::to_string(&InternalHookEventType::Agent).unwrap(),
1788            "\"agent\""
1789        );
1790        assert_eq!(
1791            serde_json::to_string(&InternalHookEventType::Session).unwrap(),
1792            "\"session\""
1793        );
1794        assert_eq!(
1795            serde_json::to_string(&InternalHookEventType::Tool).unwrap(),
1796            "\"tool\""
1797        );
1798        assert_eq!(
1799            serde_json::to_string(&InternalHookEventType::Command).unwrap(),
1800            "\"command\""
1801        );
1802        assert_eq!(
1803            serde_json::to_string(&InternalHookEventType::Gateway).unwrap(),
1804            "\"gateway\""
1805        );
1806    }
1807
1808    #[test]
1809    fn test_internal_hook_event_type_deserialize() {
1810        assert_eq!(
1811            serde_json::from_str::<InternalHookEventType>("\"agent\"").unwrap(),
1812            InternalHookEventType::Agent
1813        );
1814        assert_eq!(
1815            serde_json::from_str::<InternalHookEventType>("\"session\"").unwrap(),
1816            InternalHookEventType::Session
1817        );
1818        assert_eq!(
1819            serde_json::from_str::<InternalHookEventType>("\"tool\"").unwrap(),
1820            InternalHookEventType::Tool
1821        );
1822        assert_eq!(
1823            serde_json::from_str::<InternalHookEventType>("\"command\"").unwrap(),
1824            InternalHookEventType::Command
1825        );
1826        assert_eq!(
1827            serde_json::from_str::<InternalHookEventType>("\"gateway\"").unwrap(),
1828            InternalHookEventType::Gateway
1829        );
1830    }
1831
1832    #[test]
1833    fn test_internal_hook_event_type_roundtrip() {
1834        let types = [
1835            InternalHookEventType::Agent,
1836            InternalHookEventType::Session,
1837            InternalHookEventType::Tool,
1838            InternalHookEventType::Command,
1839            InternalHookEventType::Gateway,
1840        ];
1841
1842        for event_type in types {
1843            let json = serde_json::to_string(&event_type).unwrap();
1844            let deserialized: InternalHookEventType = serde_json::from_str(&json).unwrap();
1845            assert_eq!(event_type, deserialized);
1846        }
1847    }
1848
1849    #[test]
1850    fn test_internal_hook_event_type_clone_copy() {
1851        let original = InternalHookEventType::Agent;
1852        let copied1 = original; // Copy trait
1853        let copied2 = original; // Copy trait
1854
1855        assert_eq!(original, copied1);
1856        assert_eq!(original, copied2);
1857    }
1858
1859    #[test]
1860    fn test_internal_hook_event_type_hash() {
1861        use std::collections::HashSet;
1862
1863        let mut set = HashSet::new();
1864        set.insert(InternalHookEventType::Agent);
1865        set.insert(InternalHookEventType::Session);
1866        set.insert(InternalHookEventType::Tool);
1867        set.insert(InternalHookEventType::Command);
1868        set.insert(InternalHookEventType::Gateway);
1869
1870        assert_eq!(set.len(), 5);
1871        assert!(set.contains(&InternalHookEventType::Agent));
1872        assert!(set.contains(&InternalHookEventType::Session));
1873        assert!(set.contains(&InternalHookEventType::Tool));
1874        assert!(set.contains(&InternalHookEventType::Command));
1875        assert!(set.contains(&InternalHookEventType::Gateway));
1876    }
1877
1878    #[test]
1879    fn test_internal_hook_event_type_eq() {
1880        assert_eq!(InternalHookEventType::Agent, InternalHookEventType::Agent);
1881        assert_ne!(InternalHookEventType::Agent, InternalHookEventType::Session);
1882    }
1883
1884    #[test]
1885    fn test_internal_hook_event_type_debug() {
1886        let debug_str = format!("{:?}", InternalHookEventType::Agent);
1887        assert_eq!(debug_str, "Agent");
1888    }
1889
1890    // ========== InternalHookAction 测试 ==========
1891
1892    #[test]
1893    fn test_internal_hook_action_display() {
1894        // Agent 动作
1895        assert_eq!(InternalHookAction::Start.to_string(), "start");
1896        assert_eq!(InternalHookAction::Stop.to_string(), "stop");
1897        assert_eq!(InternalHookAction::Error.to_string(), "error");
1898        assert_eq!(InternalHookAction::Bootstrap.to_string(), "bootstrap");
1899
1900        // Session 动作
1901        assert_eq!(InternalHookAction::Create.to_string(), "create");
1902        assert_eq!(InternalHookAction::Resume.to_string(), "resume");
1903        assert_eq!(InternalHookAction::End.to_string(), "end");
1904        assert_eq!(InternalHookAction::Compact.to_string(), "compact");
1905
1906        // Tool 动作
1907        assert_eq!(InternalHookAction::Before.to_string(), "before");
1908        assert_eq!(InternalHookAction::After.to_string(), "after");
1909
1910        // Command 动作
1911        assert_eq!(InternalHookAction::New.to_string(), "new");
1912        assert_eq!(InternalHookAction::Reset.to_string(), "reset");
1913        assert_eq!(InternalHookAction::Status.to_string(), "status");
1914        assert_eq!(InternalHookAction::Help.to_string(), "help");
1915
1916        // Gateway 动作
1917        assert_eq!(InternalHookAction::Connect.to_string(), "connect");
1918        assert_eq!(InternalHookAction::Disconnect.to_string(), "disconnect");
1919        assert_eq!(InternalHookAction::Message.to_string(), "message");
1920    }
1921
1922    #[test]
1923    fn test_internal_hook_action_display_all_lowercase() {
1924        // 验证所有动作的 Display 输出都是小写
1925        let actions = [
1926            InternalHookAction::Start,
1927            InternalHookAction::Stop,
1928            InternalHookAction::Error,
1929            InternalHookAction::Bootstrap,
1930            InternalHookAction::Create,
1931            InternalHookAction::Resume,
1932            InternalHookAction::End,
1933            InternalHookAction::Compact,
1934            InternalHookAction::Before,
1935            InternalHookAction::After,
1936            InternalHookAction::New,
1937            InternalHookAction::Reset,
1938            InternalHookAction::Status,
1939            InternalHookAction::Help,
1940            InternalHookAction::Connect,
1941            InternalHookAction::Disconnect,
1942            InternalHookAction::Message,
1943        ];
1944
1945        for action in actions {
1946            let s = action.to_string();
1947            assert!(
1948                s.chars().all(|c| c.is_lowercase() || !c.is_alphabetic()),
1949                "Action {:?} should have lowercase display, got: {}",
1950                action,
1951                s
1952            );
1953        }
1954    }
1955
1956    #[test]
1957    fn test_internal_hook_action_serialize() {
1958        // Agent 动作
1959        assert_eq!(
1960            serde_json::to_string(&InternalHookAction::Start).unwrap(),
1961            "\"start\""
1962        );
1963        assert_eq!(
1964            serde_json::to_string(&InternalHookAction::Stop).unwrap(),
1965            "\"stop\""
1966        );
1967        assert_eq!(
1968            serde_json::to_string(&InternalHookAction::Error).unwrap(),
1969            "\"error\""
1970        );
1971        assert_eq!(
1972            serde_json::to_string(&InternalHookAction::Bootstrap).unwrap(),
1973            "\"bootstrap\""
1974        );
1975
1976        // Session 动作
1977        assert_eq!(
1978            serde_json::to_string(&InternalHookAction::Create).unwrap(),
1979            "\"create\""
1980        );
1981        assert_eq!(
1982            serde_json::to_string(&InternalHookAction::Resume).unwrap(),
1983            "\"resume\""
1984        );
1985        assert_eq!(
1986            serde_json::to_string(&InternalHookAction::End).unwrap(),
1987            "\"end\""
1988        );
1989        assert_eq!(
1990            serde_json::to_string(&InternalHookAction::Compact).unwrap(),
1991            "\"compact\""
1992        );
1993
1994        // Tool 动作
1995        assert_eq!(
1996            serde_json::to_string(&InternalHookAction::Before).unwrap(),
1997            "\"before\""
1998        );
1999        assert_eq!(
2000            serde_json::to_string(&InternalHookAction::After).unwrap(),
2001            "\"after\""
2002        );
2003
2004        // Command 动作
2005        assert_eq!(
2006            serde_json::to_string(&InternalHookAction::New).unwrap(),
2007            "\"new\""
2008        );
2009        assert_eq!(
2010            serde_json::to_string(&InternalHookAction::Reset).unwrap(),
2011            "\"reset\""
2012        );
2013        assert_eq!(
2014            serde_json::to_string(&InternalHookAction::Status).unwrap(),
2015            "\"status\""
2016        );
2017        assert_eq!(
2018            serde_json::to_string(&InternalHookAction::Help).unwrap(),
2019            "\"help\""
2020        );
2021
2022        // Gateway 动作
2023        assert_eq!(
2024            serde_json::to_string(&InternalHookAction::Connect).unwrap(),
2025            "\"connect\""
2026        );
2027        assert_eq!(
2028            serde_json::to_string(&InternalHookAction::Disconnect).unwrap(),
2029            "\"disconnect\""
2030        );
2031        assert_eq!(
2032            serde_json::to_string(&InternalHookAction::Message).unwrap(),
2033            "\"message\""
2034        );
2035    }
2036
2037    #[test]
2038    fn test_internal_hook_action_deserialize() {
2039        // Agent 动作
2040        assert_eq!(
2041            serde_json::from_str::<InternalHookAction>("\"start\"").unwrap(),
2042            InternalHookAction::Start
2043        );
2044        assert_eq!(
2045            serde_json::from_str::<InternalHookAction>("\"stop\"").unwrap(),
2046            InternalHookAction::Stop
2047        );
2048        assert_eq!(
2049            serde_json::from_str::<InternalHookAction>("\"error\"").unwrap(),
2050            InternalHookAction::Error
2051        );
2052        assert_eq!(
2053            serde_json::from_str::<InternalHookAction>("\"bootstrap\"").unwrap(),
2054            InternalHookAction::Bootstrap
2055        );
2056
2057        // Session 动作
2058        assert_eq!(
2059            serde_json::from_str::<InternalHookAction>("\"create\"").unwrap(),
2060            InternalHookAction::Create
2061        );
2062        assert_eq!(
2063            serde_json::from_str::<InternalHookAction>("\"resume\"").unwrap(),
2064            InternalHookAction::Resume
2065        );
2066        assert_eq!(
2067            serde_json::from_str::<InternalHookAction>("\"end\"").unwrap(),
2068            InternalHookAction::End
2069        );
2070        assert_eq!(
2071            serde_json::from_str::<InternalHookAction>("\"compact\"").unwrap(),
2072            InternalHookAction::Compact
2073        );
2074
2075        // Tool 动作
2076        assert_eq!(
2077            serde_json::from_str::<InternalHookAction>("\"before\"").unwrap(),
2078            InternalHookAction::Before
2079        );
2080        assert_eq!(
2081            serde_json::from_str::<InternalHookAction>("\"after\"").unwrap(),
2082            InternalHookAction::After
2083        );
2084
2085        // Command 动作
2086        assert_eq!(
2087            serde_json::from_str::<InternalHookAction>("\"new\"").unwrap(),
2088            InternalHookAction::New
2089        );
2090        assert_eq!(
2091            serde_json::from_str::<InternalHookAction>("\"reset\"").unwrap(),
2092            InternalHookAction::Reset
2093        );
2094        assert_eq!(
2095            serde_json::from_str::<InternalHookAction>("\"status\"").unwrap(),
2096            InternalHookAction::Status
2097        );
2098        assert_eq!(
2099            serde_json::from_str::<InternalHookAction>("\"help\"").unwrap(),
2100            InternalHookAction::Help
2101        );
2102
2103        // Gateway 动作
2104        assert_eq!(
2105            serde_json::from_str::<InternalHookAction>("\"connect\"").unwrap(),
2106            InternalHookAction::Connect
2107        );
2108        assert_eq!(
2109            serde_json::from_str::<InternalHookAction>("\"disconnect\"").unwrap(),
2110            InternalHookAction::Disconnect
2111        );
2112        assert_eq!(
2113            serde_json::from_str::<InternalHookAction>("\"message\"").unwrap(),
2114            InternalHookAction::Message
2115        );
2116    }
2117
2118    #[test]
2119    fn test_internal_hook_action_roundtrip() {
2120        let actions = [
2121            InternalHookAction::Start,
2122            InternalHookAction::Stop,
2123            InternalHookAction::Error,
2124            InternalHookAction::Bootstrap,
2125            InternalHookAction::Create,
2126            InternalHookAction::Resume,
2127            InternalHookAction::End,
2128            InternalHookAction::Compact,
2129            InternalHookAction::Before,
2130            InternalHookAction::After,
2131            InternalHookAction::New,
2132            InternalHookAction::Reset,
2133            InternalHookAction::Status,
2134            InternalHookAction::Help,
2135            InternalHookAction::Connect,
2136            InternalHookAction::Disconnect,
2137            InternalHookAction::Message,
2138        ];
2139
2140        for action in actions {
2141            let json = serde_json::to_string(&action).unwrap();
2142            let deserialized: InternalHookAction = serde_json::from_str(&json).unwrap();
2143            assert_eq!(action, deserialized);
2144        }
2145    }
2146
2147    #[test]
2148    fn test_internal_hook_action_clone_copy() {
2149        let original = InternalHookAction::Start;
2150        let copied1 = original; // Copy trait
2151        let copied2 = original; // Copy trait
2152
2153        assert_eq!(original, copied1);
2154        assert_eq!(original, copied2);
2155    }
2156
2157    #[test]
2158    fn test_internal_hook_action_hash() {
2159        use std::collections::HashSet;
2160
2161        let mut set = HashSet::new();
2162        set.insert(InternalHookAction::Start);
2163        set.insert(InternalHookAction::Stop);
2164        set.insert(InternalHookAction::Error);
2165        set.insert(InternalHookAction::Bootstrap);
2166        set.insert(InternalHookAction::Create);
2167        set.insert(InternalHookAction::Resume);
2168        set.insert(InternalHookAction::End);
2169        set.insert(InternalHookAction::Compact);
2170        set.insert(InternalHookAction::Before);
2171        set.insert(InternalHookAction::After);
2172        set.insert(InternalHookAction::New);
2173        set.insert(InternalHookAction::Reset);
2174        set.insert(InternalHookAction::Status);
2175        set.insert(InternalHookAction::Help);
2176        set.insert(InternalHookAction::Connect);
2177        set.insert(InternalHookAction::Disconnect);
2178        set.insert(InternalHookAction::Message);
2179
2180        assert_eq!(set.len(), 17);
2181        assert!(set.contains(&InternalHookAction::Start));
2182        assert!(set.contains(&InternalHookAction::Message));
2183    }
2184
2185    #[test]
2186    fn test_internal_hook_action_eq() {
2187        assert_eq!(InternalHookAction::Start, InternalHookAction::Start);
2188        assert_ne!(InternalHookAction::Start, InternalHookAction::Stop);
2189        assert_ne!(InternalHookAction::Create, InternalHookAction::Resume);
2190    }
2191
2192    #[test]
2193    fn test_internal_hook_action_debug() {
2194        assert_eq!(format!("{:?}", InternalHookAction::Start), "Start");
2195        assert_eq!(format!("{:?}", InternalHookAction::Bootstrap), "Bootstrap");
2196        assert_eq!(format!("{:?}", InternalHookAction::Create), "Create");
2197        assert_eq!(format!("{:?}", InternalHookAction::Connect), "Connect");
2198    }
2199
2200    #[test]
2201    fn test_internal_hook_action_count() {
2202        // 验证所有 17 个动作都已定义
2203        // Agent: 4 (Start, Stop, Error, Bootstrap)
2204        // Session: 4 (Create, Resume, End, Compact)
2205        // Tool: 2 (Before, After) - Error 复用 Agent 的
2206        // Command: 4 (New, Reset, Status, Help)
2207        // Gateway: 3 (Connect, Disconnect, Message)
2208        // 总计: 4 + 4 + 2 + 4 + 3 = 17
2209        let actions = [
2210            InternalHookAction::Start,
2211            InternalHookAction::Stop,
2212            InternalHookAction::Error,
2213            InternalHookAction::Bootstrap,
2214            InternalHookAction::Create,
2215            InternalHookAction::Resume,
2216            InternalHookAction::End,
2217            InternalHookAction::Compact,
2218            InternalHookAction::Before,
2219            InternalHookAction::After,
2220            InternalHookAction::New,
2221            InternalHookAction::Reset,
2222            InternalHookAction::Status,
2223            InternalHookAction::Help,
2224            InternalHookAction::Connect,
2225            InternalHookAction::Disconnect,
2226            InternalHookAction::Message,
2227        ];
2228        assert_eq!(actions.len(), 17);
2229    }
2230
2231    // ========== InternalHookEvent 测试 ==========
2232
2233    #[test]
2234    fn test_internal_hook_event_new() {
2235        let event = InternalHookEvent::new(
2236            InternalHookEventType::Agent,
2237            InternalHookAction::Start,
2238            Some("test-session".to_string()),
2239            serde_json::json!({"agent_id": "agent-001"}),
2240        );
2241
2242        assert_eq!(event.event_type, InternalHookEventType::Agent);
2243        assert_eq!(event.action, InternalHookAction::Start);
2244        assert_eq!(event.session_key, Some("test-session".to_string()));
2245        assert_eq!(event.context["agent_id"], "agent-001");
2246        assert!(event.messages.is_empty());
2247        // timestamp 应该是最近的时间
2248        let now = chrono::Utc::now();
2249        assert!(event.timestamp <= now);
2250        assert!(now.signed_duration_since(event.timestamp).num_seconds() < 1);
2251    }
2252
2253    #[test]
2254    fn test_internal_hook_event_new_without_session_key() {
2255        let event = InternalHookEvent::new(
2256            InternalHookEventType::Session,
2257            InternalHookAction::Create,
2258            None,
2259            serde_json::json!({}),
2260        );
2261
2262        assert_eq!(event.event_type, InternalHookEventType::Session);
2263        assert_eq!(event.action, InternalHookAction::Create);
2264        assert_eq!(event.session_key, None);
2265        assert_eq!(event.context, serde_json::json!({}));
2266        assert!(event.messages.is_empty());
2267    }
2268
2269    #[test]
2270    fn test_internal_hook_event_key() {
2271        // Agent 事件
2272        let event = InternalHookEvent::new(
2273            InternalHookEventType::Agent,
2274            InternalHookAction::Start,
2275            None,
2276            serde_json::json!({}),
2277        );
2278        assert_eq!(event.event_key(), "agent:start");
2279
2280        let event = InternalHookEvent::new(
2281            InternalHookEventType::Agent,
2282            InternalHookAction::Stop,
2283            None,
2284            serde_json::json!({}),
2285        );
2286        assert_eq!(event.event_key(), "agent:stop");
2287
2288        let event = InternalHookEvent::new(
2289            InternalHookEventType::Agent,
2290            InternalHookAction::Error,
2291            None,
2292            serde_json::json!({}),
2293        );
2294        assert_eq!(event.event_key(), "agent:error");
2295
2296        let event = InternalHookEvent::new(
2297            InternalHookEventType::Agent,
2298            InternalHookAction::Bootstrap,
2299            None,
2300            serde_json::json!({}),
2301        );
2302        assert_eq!(event.event_key(), "agent:bootstrap");
2303
2304        // Session 事件
2305        let event = InternalHookEvent::new(
2306            InternalHookEventType::Session,
2307            InternalHookAction::Create,
2308            None,
2309            serde_json::json!({}),
2310        );
2311        assert_eq!(event.event_key(), "session:create");
2312
2313        let event = InternalHookEvent::new(
2314            InternalHookEventType::Session,
2315            InternalHookAction::Resume,
2316            None,
2317            serde_json::json!({}),
2318        );
2319        assert_eq!(event.event_key(), "session:resume");
2320
2321        let event = InternalHookEvent::new(
2322            InternalHookEventType::Session,
2323            InternalHookAction::End,
2324            None,
2325            serde_json::json!({}),
2326        );
2327        assert_eq!(event.event_key(), "session:end");
2328
2329        let event = InternalHookEvent::new(
2330            InternalHookEventType::Session,
2331            InternalHookAction::Compact,
2332            None,
2333            serde_json::json!({}),
2334        );
2335        assert_eq!(event.event_key(), "session:compact");
2336
2337        // Tool 事件
2338        let event = InternalHookEvent::new(
2339            InternalHookEventType::Tool,
2340            InternalHookAction::Before,
2341            None,
2342            serde_json::json!({}),
2343        );
2344        assert_eq!(event.event_key(), "tool:before");
2345
2346        let event = InternalHookEvent::new(
2347            InternalHookEventType::Tool,
2348            InternalHookAction::After,
2349            None,
2350            serde_json::json!({}),
2351        );
2352        assert_eq!(event.event_key(), "tool:after");
2353
2354        // Command 事件
2355        let event = InternalHookEvent::new(
2356            InternalHookEventType::Command,
2357            InternalHookAction::New,
2358            None,
2359            serde_json::json!({}),
2360        );
2361        assert_eq!(event.event_key(), "command:new");
2362
2363        let event = InternalHookEvent::new(
2364            InternalHookEventType::Command,
2365            InternalHookAction::Reset,
2366            None,
2367            serde_json::json!({}),
2368        );
2369        assert_eq!(event.event_key(), "command:reset");
2370
2371        let event = InternalHookEvent::new(
2372            InternalHookEventType::Command,
2373            InternalHookAction::Status,
2374            None,
2375            serde_json::json!({}),
2376        );
2377        assert_eq!(event.event_key(), "command:status");
2378
2379        let event = InternalHookEvent::new(
2380            InternalHookEventType::Command,
2381            InternalHookAction::Help,
2382            None,
2383            serde_json::json!({}),
2384        );
2385        assert_eq!(event.event_key(), "command:help");
2386
2387        // Gateway 事件
2388        let event = InternalHookEvent::new(
2389            InternalHookEventType::Gateway,
2390            InternalHookAction::Connect,
2391            None,
2392            serde_json::json!({}),
2393        );
2394        assert_eq!(event.event_key(), "gateway:connect");
2395
2396        let event = InternalHookEvent::new(
2397            InternalHookEventType::Gateway,
2398            InternalHookAction::Disconnect,
2399            None,
2400            serde_json::json!({}),
2401        );
2402        assert_eq!(event.event_key(), "gateway:disconnect");
2403
2404        let event = InternalHookEvent::new(
2405            InternalHookEventType::Gateway,
2406            InternalHookAction::Message,
2407            None,
2408            serde_json::json!({}),
2409        );
2410        assert_eq!(event.event_key(), "gateway:message");
2411    }
2412
2413    #[test]
2414    fn test_internal_hook_event_key_format() {
2415        // 验证事件键格式为 type:action
2416        let event = InternalHookEvent::new(
2417            InternalHookEventType::Agent,
2418            InternalHookAction::Start,
2419            None,
2420            serde_json::json!({}),
2421        );
2422        let key = event.event_key();
2423        assert!(key.contains(':'), "Event key should contain ':'");
2424        let parts: Vec<&str> = key.split(':').collect();
2425        assert_eq!(parts.len(), 2, "Event key should have exactly two parts");
2426        assert_eq!(parts[0], "agent");
2427        assert_eq!(parts[1], "start");
2428    }
2429
2430    #[test]
2431    fn test_internal_hook_event_serialize() {
2432        let event = InternalHookEvent::new(
2433            InternalHookEventType::Agent,
2434            InternalHookAction::Start,
2435            Some("session-123".to_string()),
2436            serde_json::json!({"agent_id": "agent-001", "agent_type": "coding"}),
2437        );
2438
2439        let json = serde_json::to_string(&event).unwrap();
2440        assert!(json.contains("\"event_type\":\"agent\""));
2441        assert!(json.contains("\"action\":\"start\""));
2442        assert!(json.contains("\"session_key\":\"session-123\""));
2443        assert!(json.contains("\"agent_id\":\"agent-001\""));
2444        assert!(json.contains("\"agent_type\":\"coding\""));
2445        assert!(json.contains("\"timestamp\""));
2446        assert!(json.contains("\"messages\":[]"));
2447    }
2448
2449    #[test]
2450    fn test_internal_hook_event_deserialize() {
2451        let json = r#"{
2452            "event_type": "session",
2453            "action": "create",
2454            "session_key": "test-session",
2455            "context": {"session_id": "sess-001"},
2456            "timestamp": "2024-01-15T10:30:00Z",
2457            "messages": ["Hello", "World"]
2458        }"#;
2459
2460        let event: InternalHookEvent = serde_json::from_str(json).unwrap();
2461        assert_eq!(event.event_type, InternalHookEventType::Session);
2462        assert_eq!(event.action, InternalHookAction::Create);
2463        assert_eq!(event.session_key, Some("test-session".to_string()));
2464        assert_eq!(event.context["session_id"], "sess-001");
2465        assert_eq!(event.messages, vec!["Hello", "World"]);
2466    }
2467
2468    #[test]
2469    fn test_internal_hook_event_roundtrip() {
2470        let original = InternalHookEvent::new(
2471            InternalHookEventType::Command,
2472            InternalHookAction::New,
2473            Some("user:session:456".to_string()),
2474            serde_json::json!({
2475                "command_name": "new",
2476                "command_args": ["--model", "gpt-4"],
2477                "raw_input": "/new --model gpt-4"
2478            }),
2479        );
2480
2481        let json = serde_json::to_string(&original).unwrap();
2482        let deserialized: InternalHookEvent = serde_json::from_str(&json).unwrap();
2483
2484        assert_eq!(original.event_type, deserialized.event_type);
2485        assert_eq!(original.action, deserialized.action);
2486        assert_eq!(original.session_key, deserialized.session_key);
2487        assert_eq!(original.context, deserialized.context);
2488        assert_eq!(original.timestamp, deserialized.timestamp);
2489        assert_eq!(original.messages, deserialized.messages);
2490    }
2491
2492    #[test]
2493    fn test_internal_hook_event_clone() {
2494        let original = InternalHookEvent::new(
2495            InternalHookEventType::Gateway,
2496            InternalHookAction::Connect,
2497            None,
2498            serde_json::json!({"connection_id": "conn-001"}),
2499        );
2500
2501        let cloned = original.clone();
2502
2503        assert_eq!(original.event_type, cloned.event_type);
2504        assert_eq!(original.action, cloned.action);
2505        assert_eq!(original.session_key, cloned.session_key);
2506        assert_eq!(original.context, cloned.context);
2507        assert_eq!(original.timestamp, cloned.timestamp);
2508        assert_eq!(original.messages, cloned.messages);
2509    }
2510
2511    #[test]
2512    fn test_internal_hook_event_debug() {
2513        let event = InternalHookEvent::new(
2514            InternalHookEventType::Tool,
2515            InternalHookAction::Before,
2516            None,
2517            serde_json::json!({}),
2518        );
2519
2520        let debug_str = format!("{:?}", event);
2521        assert!(debug_str.contains("InternalHookEvent"));
2522        assert!(debug_str.contains("Tool"));
2523        assert!(debug_str.contains("Before"));
2524    }
2525
2526    #[test]
2527    fn test_internal_hook_event_messages_mutable() {
2528        let mut event = InternalHookEvent::new(
2529            InternalHookEventType::Agent,
2530            InternalHookAction::Start,
2531            None,
2532            serde_json::json!({}),
2533        );
2534
2535        assert!(event.messages.is_empty());
2536
2537        // 处理器可以向 messages 推送消息
2538        event
2539            .messages
2540            .push("Agent started successfully".to_string());
2541        event.messages.push("Initialization complete".to_string());
2542
2543        assert_eq!(event.messages.len(), 2);
2544        assert_eq!(event.messages[0], "Agent started successfully");
2545        assert_eq!(event.messages[1], "Initialization complete");
2546    }
2547
2548    #[test]
2549    fn test_internal_hook_event_context_types() {
2550        // 测试不同类型的 context 数据
2551
2552        // Agent 事件上下文
2553        let agent_event = InternalHookEvent::new(
2554            InternalHookEventType::Agent,
2555            InternalHookAction::Start,
2556            None,
2557            serde_json::json!({
2558                "agent_id": "agent-123",
2559                "agent_type": "coding",
2560                "workspace_dir": "/path/to/workspace"
2561            }),
2562        );
2563        assert_eq!(agent_event.context["agent_id"], "agent-123");
2564        assert_eq!(agent_event.context["agent_type"], "coding");
2565        assert_eq!(agent_event.context["workspace_dir"], "/path/to/workspace");
2566
2567        // Session 事件上下文
2568        let session_event = InternalHookEvent::new(
2569            InternalHookEventType::Session,
2570            InternalHookAction::End,
2571            Some("session-key".to_string()),
2572            serde_json::json!({
2573                "session_id": "session-456",
2574                "session_key": "user:session:key",
2575                "reason": "logout"
2576            }),
2577        );
2578        assert_eq!(session_event.context["session_id"], "session-456");
2579        assert_eq!(session_event.context["reason"], "logout");
2580
2581        // Command 事件上下文
2582        let command_event = InternalHookEvent::new(
2583            InternalHookEventType::Command,
2584            InternalHookAction::New,
2585            None,
2586            serde_json::json!({
2587                "command_name": "new",
2588                "command_args": ["--model", "gpt-4"],
2589                "raw_input": "/new --model gpt-4"
2590            }),
2591        );
2592        assert_eq!(command_event.context["command_name"], "new");
2593        assert!(command_event.context["command_args"].is_array());
2594
2595        // Gateway 事件上下文
2596        let gateway_event = InternalHookEvent::new(
2597            InternalHookEventType::Gateway,
2598            InternalHookAction::Message,
2599            None,
2600            serde_json::json!({
2601                "connection_id": "conn-789",
2602                "channel": "websocket",
2603                "message": "Hello, World!"
2604            }),
2605        );
2606        assert_eq!(gateway_event.context["connection_id"], "conn-789");
2607        assert_eq!(gateway_event.context["channel"], "websocket");
2608    }
2609
2610    #[test]
2611    fn test_internal_hook_event_empty_context() {
2612        let event = InternalHookEvent::new(
2613            InternalHookEventType::Agent,
2614            InternalHookAction::Stop,
2615            None,
2616            serde_json::json!({}),
2617        );
2618
2619        assert_eq!(event.context, serde_json::json!({}));
2620        assert!(event.context.as_object().unwrap().is_empty());
2621    }
2622
2623    #[test]
2624    fn test_internal_hook_event_null_context() {
2625        let event = InternalHookEvent::new(
2626            InternalHookEventType::Agent,
2627            InternalHookAction::Stop,
2628            None,
2629            serde_json::Value::Null,
2630        );
2631
2632        assert!(event.context.is_null());
2633    }
2634
2635    // ========== InternalHookRegistry 测试 ==========
2636
2637    #[test]
2638    fn test_internal_hook_registry_new() {
2639        let registry = InternalHookRegistry::new();
2640        assert!(registry.is_empty());
2641        assert_eq!(registry.handler_count(), 0);
2642        assert!(registry.get_registered_keys().is_empty());
2643    }
2644
2645    #[test]
2646    fn test_internal_hook_registry_default() {
2647        let registry = InternalHookRegistry::default();
2648        assert!(registry.is_empty());
2649        assert_eq!(registry.handler_count(), 0);
2650    }
2651
2652    #[test]
2653    fn test_internal_hook_registry_register() {
2654        let registry = InternalHookRegistry::new();
2655
2656        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2657        registry.register("agent:start", handler);
2658
2659        assert!(!registry.is_empty());
2660        assert_eq!(registry.handler_count(), 1);
2661        assert!(registry
2662            .get_registered_keys()
2663            .contains(&"agent:start".to_string()));
2664    }
2665
2666    #[test]
2667    fn test_internal_hook_registry_register_multiple_handlers_same_key() {
2668        let registry = InternalHookRegistry::new();
2669
2670        let handler1: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2671        let handler2: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2672        let handler3: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2673
2674        registry.register("agent:start", handler1);
2675        registry.register("agent:start", handler2);
2676        registry.register("agent:start", handler3);
2677
2678        assert_eq!(registry.handler_count(), 3);
2679        assert_eq!(registry.get_registered_keys().len(), 1);
2680        assert_eq!(registry.get_handlers("agent:start").len(), 3);
2681    }
2682
2683    #[test]
2684    fn test_internal_hook_registry_register_multiple_keys() {
2685        let registry = InternalHookRegistry::new();
2686
2687        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2688
2689        registry.register("agent:start", handler.clone());
2690        registry.register("agent:stop", handler.clone());
2691        registry.register("session:create", handler);
2692
2693        assert_eq!(registry.handler_count(), 3);
2694        assert_eq!(registry.get_registered_keys().len(), 3);
2695    }
2696
2697    #[test]
2698    fn test_internal_hook_registry_register_type_level() {
2699        let registry = InternalHookRegistry::new();
2700
2701        // 注册类型级别处理器
2702        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2703        registry.register("agent", handler);
2704
2705        assert!(registry
2706            .get_registered_keys()
2707            .contains(&"agent".to_string()));
2708        assert_eq!(registry.get_handlers("agent").len(), 1);
2709    }
2710
2711    #[test]
2712    fn test_internal_hook_registry_unregister() {
2713        let registry = InternalHookRegistry::new();
2714
2715        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2716        registry.register("agent:start", handler.clone());
2717
2718        assert_eq!(registry.handler_count(), 1);
2719
2720        let removed = registry.unregister("agent:start", &handler);
2721        assert!(removed);
2722        assert!(registry.is_empty());
2723        assert_eq!(registry.handler_count(), 0);
2724    }
2725
2726    #[test]
2727    fn test_internal_hook_registry_unregister_not_found() {
2728        let registry = InternalHookRegistry::new();
2729
2730        let handler1: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2731        let handler2: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2732
2733        registry.register("agent:start", handler1);
2734
2735        // 尝试取消注册未注册的处理器
2736        let removed = registry.unregister("agent:start", &handler2);
2737        assert!(!removed);
2738        assert_eq!(registry.handler_count(), 1);
2739    }
2740
2741    #[test]
2742    fn test_internal_hook_registry_unregister_wrong_key() {
2743        let registry = InternalHookRegistry::new();
2744
2745        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2746        registry.register("agent:start", handler.clone());
2747
2748        // 尝试从错误的事件键取消注册
2749        let removed = registry.unregister("agent:stop", &handler);
2750        assert!(!removed);
2751        assert_eq!(registry.handler_count(), 1);
2752    }
2753
2754    #[test]
2755    fn test_internal_hook_registry_unregister_one_of_multiple() {
2756        let registry = InternalHookRegistry::new();
2757
2758        let handler1: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2759        let handler2: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2760
2761        registry.register("agent:start", handler1.clone());
2762        registry.register("agent:start", handler2);
2763
2764        assert_eq!(registry.handler_count(), 2);
2765
2766        let removed = registry.unregister("agent:start", &handler1);
2767        assert!(removed);
2768        assert_eq!(registry.handler_count(), 1);
2769        // 事件键仍然存在，因为还有一个处理器
2770        assert!(registry
2771            .get_registered_keys()
2772            .contains(&"agent:start".to_string()));
2773    }
2774
2775    #[test]
2776    fn test_internal_hook_registry_clear() {
2777        let registry = InternalHookRegistry::new();
2778
2779        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2780
2781        registry.register("agent:start", handler.clone());
2782        registry.register("agent:stop", handler.clone());
2783        registry.register("session:create", handler);
2784
2785        assert_eq!(registry.handler_count(), 3);
2786
2787        registry.clear();
2788
2789        assert!(registry.is_empty());
2790        assert_eq!(registry.handler_count(), 0);
2791        assert!(registry.get_registered_keys().is_empty());
2792    }
2793
2794    #[test]
2795    fn test_internal_hook_registry_get_registered_keys() {
2796        let registry = InternalHookRegistry::new();
2797
2798        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2799
2800        registry.register("agent:start", handler.clone());
2801        registry.register("agent:stop", handler.clone());
2802        registry.register("session:create", handler.clone());
2803        registry.register("command:new", handler);
2804
2805        let keys = registry.get_registered_keys();
2806        assert_eq!(keys.len(), 4);
2807        assert!(keys.contains(&"agent:start".to_string()));
2808        assert!(keys.contains(&"agent:stop".to_string()));
2809        assert!(keys.contains(&"session:create".to_string()));
2810        assert!(keys.contains(&"command:new".to_string()));
2811    }
2812
2813    #[test]
2814    fn test_internal_hook_registry_get_handlers() {
2815        let registry = InternalHookRegistry::new();
2816
2817        let handler1: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2818        let handler2: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2819
2820        registry.register("agent:start", handler1);
2821        registry.register("agent:start", handler2);
2822
2823        let handlers = registry.get_handlers("agent:start");
2824        assert_eq!(handlers.len(), 2);
2825
2826        // 获取不存在的事件键返回空列表
2827        let empty_handlers = registry.get_handlers("nonexistent");
2828        assert!(empty_handlers.is_empty());
2829    }
2830
2831    #[test]
2832    fn test_internal_hook_registry_is_empty() {
2833        let registry = InternalHookRegistry::new();
2834        assert!(registry.is_empty());
2835
2836        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2837        registry.register("agent:start", handler.clone());
2838        assert!(!registry.is_empty());
2839
2840        registry.unregister("agent:start", &handler);
2841        assert!(registry.is_empty());
2842    }
2843
2844    #[test]
2845    fn test_internal_hook_registry_handler_count() {
2846        let registry = InternalHookRegistry::new();
2847        assert_eq!(registry.handler_count(), 0);
2848
2849        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2850
2851        registry.register("agent:start", handler.clone());
2852        assert_eq!(registry.handler_count(), 1);
2853
2854        registry.register("agent:start", handler.clone());
2855        assert_eq!(registry.handler_count(), 2);
2856
2857        registry.register("agent:stop", handler);
2858        assert_eq!(registry.handler_count(), 3);
2859    }
2860
2861    #[test]
2862    fn test_internal_hook_registry_debug() {
2863        let registry = InternalHookRegistry::new();
2864
2865        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2866        registry.register("agent:start", handler);
2867
2868        let debug_str = format!("{:?}", registry);
2869        assert!(debug_str.contains("InternalHookRegistry"));
2870        assert!(debug_str.contains("agent:start"));
2871    }
2872
2873    #[test]
2874    fn test_internal_hook_registry_register_same_handler_twice() {
2875        let registry = InternalHookRegistry::new();
2876
2877        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2878
2879        // 允许重复注册相同的处理器
2880        registry.register("agent:start", handler.clone());
2881        registry.register("agent:start", handler);
2882
2883        assert_eq!(registry.handler_count(), 2);
2884        assert_eq!(registry.get_handlers("agent:start").len(), 2);
2885    }
2886
2887    #[test]
2888    fn test_internal_hook_registry_unregister_removes_empty_key() {
2889        let registry = InternalHookRegistry::new();
2890
2891        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2892        registry.register("agent:start", handler.clone());
2893
2894        assert!(registry
2895            .get_registered_keys()
2896            .contains(&"agent:start".to_string()));
2897
2898        registry.unregister("agent:start", &handler);
2899
2900        // 取消注册后，空的事件键应该被移除
2901        assert!(!registry
2902            .get_registered_keys()
2903            .contains(&"agent:start".to_string()));
2904    }
2905
2906    // ========== 全局注册表单例测试 ==========
2907
2908    #[test]
2909    fn test_global_internal_registry_returns_same_instance() {
2910        // 多次调用应该返回同一个实例
2911        let registry1 = global_internal_registry();
2912        let registry2 = global_internal_registry();
2913
2914        // 使用指针比较确认是同一个实例
2915        assert!(std::ptr::eq(registry1, registry2));
2916    }
2917
2918    #[test]
2919    #[serial]
2920    fn test_global_internal_registry_is_functional() {
2921        let registry = global_internal_registry();
2922        registry.clear();
2923
2924        // 使用唯一的事件键避免与其他测试冲突
2925        let unique_key = format!("test:global_registry_{}", uuid::Uuid::new_v4());
2926
2927        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
2928        registry.register(&unique_key, handler.clone());
2929
2930        // 验证注册成功
2931        assert!(registry.get_registered_keys().contains(&unique_key));
2932        assert_eq!(registry.get_handlers(&unique_key).len(), 1);
2933
2934        // 清理：取消注册
2935        registry.unregister(&unique_key, &handler);
2936    }
2937
2938    #[test]
2939    fn test_global_internal_registry_type() {
2940        // 验证返回类型是 &'static InternalHookRegistry
2941        let registry: &'static InternalHookRegistry = global_internal_registry();
2942
2943        // 验证可以调用 InternalHookRegistry 的方法
2944        let _ = registry.get_registered_keys();
2945        let _ = registry.is_empty();
2946        let _ = registry.handler_count();
2947    }
2948
2949    // ========== trigger() 方法测试 ==========
2950
2951    #[tokio::test]
2952    async fn test_trigger_no_handlers() {
2953        let registry = InternalHookRegistry::new();
2954
2955        let mut event = InternalHookEvent::new(
2956            InternalHookEventType::Agent,
2957            InternalHookAction::Start,
2958            None,
2959            serde_json::json!({}),
2960        );
2961
2962        // 没有注册任何处理器时，应该静默返回
2963        let result = registry.trigger(&mut event).await;
2964        assert!(result.is_ok());
2965        assert!(event.messages.is_empty());
2966    }
2967
2968    #[tokio::test]
2969    async fn test_trigger_action_level_handler() {
2970        let registry = InternalHookRegistry::new();
2971
2972        // 使用 Arc<Mutex> 记录调用
2973        let called = Arc::new(std::sync::Mutex::new(false));
2974        let called_clone = called.clone();
2975
2976        // 注意：在闭包的同步部分修改 event，然后返回一个不捕获 event 的 Future
2977        let handler: InternalHookHandlerFn = Arc::new(move |event| {
2978            *called_clone.lock().unwrap() = true;
2979            event.messages.push("Action handler called".to_string());
2980            Box::pin(async move { Ok(()) })
2981        });
2982
2983        registry.register("agent:start", handler);
2984
2985        let mut event = InternalHookEvent::new(
2986            InternalHookEventType::Agent,
2987            InternalHookAction::Start,
2988            None,
2989            serde_json::json!({}),
2990        );
2991
2992        let result = registry.trigger(&mut event).await;
2993        assert!(result.is_ok());
2994        assert!(*called.lock().unwrap());
2995        assert_eq!(event.messages, vec!["Action handler called"]);
2996    }
2997
2998    #[tokio::test]
2999    async fn test_trigger_type_level_handler() {
3000        let registry = InternalHookRegistry::new();
3001
3002        let called = Arc::new(std::sync::Mutex::new(false));
3003        let called_clone = called.clone();
3004
3005        let handler: InternalHookHandlerFn = Arc::new(move |event| {
3006            *called_clone.lock().unwrap() = true;
3007            event.messages.push("Type handler called".to_string());
3008            Box::pin(async move { Ok(()) })
3009        });
3010
3011        // 注册类型级别处理器
3012        registry.register("agent", handler);
3013
3014        let mut event = InternalHookEvent::new(
3015            InternalHookEventType::Agent,
3016            InternalHookAction::Start,
3017            None,
3018            serde_json::json!({}),
3019        );
3020
3021        let result = registry.trigger(&mut event).await;
3022        assert!(result.is_ok());
3023        assert!(*called.lock().unwrap());
3024        assert_eq!(event.messages, vec!["Type handler called"]);
3025    }
3026
3027    #[tokio::test]
3028    async fn test_trigger_type_before_action_handlers() {
3029        let registry = InternalHookRegistry::new();
3030
3031        // 使用 Vec 记录调用顺序
3032        let call_order = Arc::new(std::sync::Mutex::new(Vec::new()));
3033
3034        // 类型级别处理器
3035        let call_order_clone = call_order.clone();
3036        let type_handler: InternalHookHandlerFn = Arc::new(move |event| {
3037            call_order_clone.lock().unwrap().push("type");
3038            event.messages.push("Type handler".to_string());
3039            Box::pin(async move { Ok(()) })
3040        });
3041
3042        // 动作级别处理器
3043        let call_order_clone = call_order.clone();
3044        let action_handler: InternalHookHandlerFn = Arc::new(move |event| {
3045            call_order_clone.lock().unwrap().push("action");
3046            event.messages.push("Action handler".to_string());
3047            Box::pin(async move { Ok(()) })
3048        });
3049
3050        // 先注册动作级别，再注册类型级别（验证调用顺序不受注册顺序影响）
3051        registry.register("agent:start", action_handler);
3052        registry.register("agent", type_handler);
3053
3054        let mut event = InternalHookEvent::new(
3055            InternalHookEventType::Agent,
3056            InternalHookAction::Start,
3057            None,
3058            serde_json::json!({}),
3059        );
3060
3061        let result = registry.trigger(&mut event).await;
3062        assert!(result.is_ok());
3063
3064        // 验证类型级别处理器先于动作级别处理器被调用
3065        let order = call_order.lock().unwrap();
3066        assert_eq!(*order, vec!["type", "action"]);
3067        assert_eq!(event.messages, vec!["Type handler", "Action handler"]);
3068    }
3069
3070    #[tokio::test]
3071    async fn test_trigger_multiple_handlers_same_level() {
3072        let registry = InternalHookRegistry::new();
3073
3074        let call_order = Arc::new(std::sync::Mutex::new(Vec::new()));
3075
3076        // 注册多个动作级别处理器
3077        for i in 1..=3 {
3078            let call_order_clone = call_order.clone();
3079            let handler: InternalHookHandlerFn = Arc::new(move |event| {
3080                call_order_clone.lock().unwrap().push(i);
3081                event.messages.push(format!("Handler {}", i));
3082                Box::pin(async move { Ok(()) })
3083            });
3084            registry.register("agent:start", handler);
3085        }
3086
3087        let mut event = InternalHookEvent::new(
3088            InternalHookEventType::Agent,
3089            InternalHookAction::Start,
3090            None,
3091            serde_json::json!({}),
3092        );
3093
3094        let result = registry.trigger(&mut event).await;
3095        assert!(result.is_ok());
3096
3097        // 验证按注册顺序调用
3098        let order = call_order.lock().unwrap();
3099        assert_eq!(*order, vec![1, 2, 3]);
3100        assert_eq!(event.messages, vec!["Handler 1", "Handler 2", "Handler 3"]);
3101    }
3102
3103    #[tokio::test]
3104    async fn test_trigger_handler_error_does_not_stop_others() {
3105        let registry = InternalHookRegistry::new();
3106
3107        let call_order = Arc::new(std::sync::Mutex::new(Vec::new()));
3108
3109        // 第一个处理器：成功
3110        let call_order_clone = call_order.clone();
3111        let handler1: InternalHookHandlerFn = Arc::new(move |event| {
3112            call_order_clone.lock().unwrap().push(1);
3113            event.messages.push("Handler 1 OK".to_string());
3114            Box::pin(async move { Ok(()) })
3115        });
3116
3117        // 第二个处理器：失败
3118        let call_order_clone = call_order.clone();
3119        let handler2: InternalHookHandlerFn = Arc::new(move |_event| {
3120            call_order_clone.lock().unwrap().push(2);
3121            Box::pin(async move { Err(anyhow::anyhow!("Handler 2 failed")) })
3122        });
3123
3124        // 第三个处理器：成功
3125        let call_order_clone = call_order.clone();
3126        let handler3: InternalHookHandlerFn = Arc::new(move |event| {
3127            call_order_clone.lock().unwrap().push(3);
3128            event.messages.push("Handler 3 OK".to_string());
3129            Box::pin(async move { Ok(()) })
3130        });
3131
3132        registry.register("agent:start", handler1);
3133        registry.register("agent:start", handler2);
3134        registry.register("agent:start", handler3);
3135
3136        let mut event = InternalHookEvent::new(
3137            InternalHookEventType::Agent,
3138            InternalHookAction::Start,
3139            None,
3140            serde_json::json!({}),
3141        );
3142
3143        // 即使有处理器失败，trigger 也应该返回 Ok
3144        let result = registry.trigger(&mut event).await;
3145        assert!(result.is_ok());
3146
3147        // 验证所有处理器都被调用
3148        let order = call_order.lock().unwrap();
3149        assert_eq!(*order, vec![1, 2, 3]);
3150
3151        // 验证成功的处理器的消息被记录
3152        assert_eq!(event.messages, vec!["Handler 1 OK", "Handler 3 OK"]);
3153    }
3154
3155    #[tokio::test]
3156    async fn test_trigger_type_handler_error_does_not_stop_action_handlers() {
3157        let registry = InternalHookRegistry::new();
3158
3159        let call_order: Arc<std::sync::Mutex<Vec<&str>>> =
3160            Arc::new(std::sync::Mutex::new(Vec::new()));
3161
3162        // 类型级别处理器：失败
3163        let call_order_clone = call_order.clone();
3164        let type_handler: InternalHookHandlerFn = Arc::new(move |_event| {
3165            call_order_clone.lock().unwrap().push("type_error");
3166            Box::pin(async move { Err(anyhow::anyhow!("Type handler failed")) })
3167        });
3168
3169        // 动作级别处理器：成功
3170        let call_order_clone = call_order.clone();
3171        let action_handler: InternalHookHandlerFn = Arc::new(move |event| {
3172            call_order_clone.lock().unwrap().push("action_ok");
3173            event.messages.push("Action handler OK".to_string());
3174            Box::pin(async move { Ok(()) })
3175        });
3176
3177        registry.register("agent", type_handler);
3178        registry.register("agent:start", action_handler);
3179
3180        let mut event = InternalHookEvent::new(
3181            InternalHookEventType::Agent,
3182            InternalHookAction::Start,
3183            None,
3184            serde_json::json!({}),
3185        );
3186
3187        let result = registry.trigger(&mut event).await;
3188        assert!(result.is_ok());
3189
3190        // 验证类型处理器失败后，动作处理器仍然被调用
3191        let order = call_order.lock().unwrap();
3192        assert_eq!(*order, vec!["type_error", "action_ok"]);
3193        assert_eq!(event.messages, vec!["Action handler OK"]);
3194    }
3195
3196    #[tokio::test]
3197    async fn test_trigger_different_event_types() {
3198        let registry = InternalHookRegistry::new();
3199
3200        let agent_called = Arc::new(std::sync::Mutex::new(false));
3201        let session_called = Arc::new(std::sync::Mutex::new(false));
3202
3203        // Agent 处理器
3204        let agent_called_clone = agent_called.clone();
3205        let agent_handler: InternalHookHandlerFn = Arc::new(move |_| {
3206            *agent_called_clone.lock().unwrap() = true;
3207            Box::pin(async move { Ok(()) })
3208        });
3209
3210        // Session 处理器
3211        let session_called_clone = session_called.clone();
3212        let session_handler: InternalHookHandlerFn = Arc::new(move |_| {
3213            *session_called_clone.lock().unwrap() = true;
3214            Box::pin(async move { Ok(()) })
3215        });
3216
3217        registry.register("agent:start", agent_handler);
3218        registry.register("session:create", session_handler);
3219
3220        // 触发 Agent 事件
3221        let mut agent_event = InternalHookEvent::new(
3222            InternalHookEventType::Agent,
3223            InternalHookAction::Start,
3224            None,
3225            serde_json::json!({}),
3226        );
3227        registry.trigger(&mut agent_event).await.unwrap();
3228
3229        // 只有 Agent 处理器被调用
3230        assert!(*agent_called.lock().unwrap());
3231        assert!(!*session_called.lock().unwrap());
3232
3233        // 重置
3234        *agent_called.lock().unwrap() = false;
3235
3236        // 触发 Session 事件
3237        let mut session_event = InternalHookEvent::new(
3238            InternalHookEventType::Session,
3239            InternalHookAction::Create,
3240            None,
3241            serde_json::json!({}),
3242        );
3243        registry.trigger(&mut session_event).await.unwrap();
3244
3245        // 只有 Session 处理器被调用
3246        assert!(!*agent_called.lock().unwrap());
3247        assert!(*session_called.lock().unwrap());
3248    }
3249
3250    #[tokio::test]
3251    async fn test_trigger_handler_can_modify_event_messages() {
3252        let registry = InternalHookRegistry::new();
3253
3254        let handler: InternalHookHandlerFn = Arc::new(|event| {
3255            event.messages.push("Message 1".to_string());
3256            event.messages.push("Message 2".to_string());
3257            Box::pin(async move { Ok(()) })
3258        });
3259
3260        registry.register("agent:start", handler);
3261
3262        let mut event = InternalHookEvent::new(
3263            InternalHookEventType::Agent,
3264            InternalHookAction::Start,
3265            None,
3266            serde_json::json!({}),
3267        );
3268
3269        registry.trigger(&mut event).await.unwrap();
3270
3271        assert_eq!(event.messages.len(), 2);
3272        assert_eq!(event.messages[0], "Message 1");
3273        assert_eq!(event.messages[1], "Message 2");
3274    }
3275
3276    #[tokio::test]
3277    async fn test_trigger_handler_can_read_event_context() {
3278        let registry = InternalHookRegistry::new();
3279
3280        let captured_agent_id = Arc::new(std::sync::Mutex::new(String::new()));
3281        let captured_clone = captured_agent_id.clone();
3282
3283        let handler: InternalHookHandlerFn = Arc::new(move |event| {
3284            // 在同步部分读取 context
3285            if let Some(agent_id) = event.context.get("agent_id").and_then(|v| v.as_str()) {
3286                *captured_clone.lock().unwrap() = agent_id.to_string();
3287            }
3288            Box::pin(async move { Ok(()) })
3289        });
3290
3291        registry.register("agent:start", handler);
3292
3293        let mut event = InternalHookEvent::new(
3294            InternalHookEventType::Agent,
3295            InternalHookAction::Start,
3296            None,
3297            serde_json::json!({"agent_id": "test-agent-123"}),
3298        );
3299
3300        registry.trigger(&mut event).await.unwrap();
3301
3302        assert_eq!(*captured_agent_id.lock().unwrap(), "test-agent-123");
3303    }
3304
3305    // ========== 辅助函数测试 ==========
3306
3307    #[test]
3308    fn test_create_internal_hook_event() {
3309        let event = create_internal_hook_event(
3310            InternalHookEventType::Agent,
3311            InternalHookAction::Start,
3312            Some("session-123".to_string()),
3313            serde_json::json!({"agent_id": "agent-001"}),
3314        );
3315
3316        assert_eq!(event.event_type, InternalHookEventType::Agent);
3317        assert_eq!(event.action, InternalHookAction::Start);
3318        assert_eq!(event.session_key, Some("session-123".to_string()));
3319        assert_eq!(event.context["agent_id"], "agent-001");
3320        assert_eq!(event.event_key(), "agent:start");
3321        assert!(event.messages.is_empty());
3322    }
3323
3324    #[test]
3325    fn test_create_internal_hook_event_without_session_key() {
3326        let event = create_internal_hook_event(
3327            InternalHookEventType::Session,
3328            InternalHookAction::Create,
3329            None,
3330            serde_json::json!({}),
3331        );
3332
3333        assert_eq!(event.event_type, InternalHookEventType::Session);
3334        assert_eq!(event.action, InternalHookAction::Create);
3335        assert_eq!(event.session_key, None);
3336        assert_eq!(event.event_key(), "session:create");
3337    }
3338
3339    #[test]
3340    #[serial]
3341    fn test_register_internal_hook() {
3342        // 使用唯一的事件键避免与其他测试冲突
3343        let unique_key = format!("test:register_{}", uuid::Uuid::new_v4());
3344
3345        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
3346        register_internal_hook(&unique_key, handler.clone());
3347
3348        // 验证注册成功
3349        let registry = global_internal_registry();
3350        assert!(registry.get_registered_keys().contains(&unique_key));
3351        assert_eq!(registry.get_handlers(&unique_key).len(), 1);
3352
3353        // 清理
3354        registry.unregister(&unique_key, &handler);
3355    }
3356
3357    #[test]
3358    #[serial]
3359    fn test_unregister_internal_hook() {
3360        let unique_key = format!("test:unregister_{}", uuid::Uuid::new_v4());
3361
3362        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
3363        register_internal_hook(&unique_key, handler.clone());
3364
3365        // 验证注册成功
3366        let registry = global_internal_registry();
3367        assert!(registry.get_registered_keys().contains(&unique_key));
3368
3369        // 取消注册
3370        let removed = unregister_internal_hook(&unique_key, &handler);
3371        assert!(removed);
3372
3373        // 验证已移除
3374        assert!(!registry.get_registered_keys().contains(&unique_key));
3375    }
3376
3377    #[test]
3378    fn test_unregister_internal_hook_not_found() {
3379        let unique_key = format!("test:unregister_not_found_{}", uuid::Uuid::new_v4());
3380
3381        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
3382
3383        // 尝试取消注册未注册的处理器
3384        let removed = unregister_internal_hook(&unique_key, &handler);
3385        assert!(!removed);
3386    }
3387
3388    #[test]
3389    #[serial]
3390    fn test_clear_internal_hooks() {
3391        // 清理全局注册表以避免干扰
3392        let registry = global_internal_registry();
3393        registry.clear();
3394
3395        // 注册一些处理器
3396        let unique_key1 = format!("test:clear1_{}", uuid::Uuid::new_v4());
3397        let unique_key2 = format!("test:clear2_{}", uuid::Uuid::new_v4());
3398
3399        let handler: InternalHookHandlerFn = Arc::new(|_| Box::pin(async { Ok(()) }));
3400        register_internal_hook(&unique_key1, handler.clone());
3401        register_internal_hook(&unique_key2, handler.clone());
3402
3403        assert!(registry.get_registered_keys().contains(&unique_key1));
3404        assert!(registry.get_registered_keys().contains(&unique_key2));
3405
3406        // 清除所有处理器
3407        clear_internal_hooks();
3408
3409        // 验证已清除
3410        assert!(!registry.get_registered_keys().contains(&unique_key1));
3411        assert!(!registry.get_registered_keys().contains(&unique_key2));
3412    }
3413
3414    #[tokio::test]
3415    #[serial]
3416    async fn test_trigger_internal_hook_function() {
3417        // 清理全局注册表以避免干扰
3418        let registry = global_internal_registry();
3419        registry.clear();
3420
3421        let unique_key = format!("test:trigger_{}", uuid::Uuid::new_v4());
3422
3423        let called = Arc::new(std::sync::Mutex::new(false));
3424        let called_clone = called.clone();
3425
3426        let handler: InternalHookHandlerFn = Arc::new(move |event| {
3427            *called_clone.lock().unwrap() = true;
3428            event.messages.push("Handler called".to_string());
3429            Box::pin(async move { Ok(()) })
3430        });
3431
3432        register_internal_hook(&unique_key, handler.clone());
3433
3434        // 创建一个匹配的事件（需要手动构造事件键）
3435        let mut event = InternalHookEvent {
3436            event_type: InternalHookEventType::Agent,
3437            action: InternalHookAction::Start,
3438            session_key: None,
3439            context: serde_json::json!({}),
3440            timestamp: chrono::Utc::now(),
3441            messages: Vec::new(),
3442        };
3443
3444        // 由于 event_key() 返回 "agent:start"，我们需要注册到正确的键
3445        // 先清理之前的注册
3446        unregister_internal_hook(&unique_key, &handler);
3447
3448        // 重新注册到正确的事件键
3449        register_internal_hook("agent:start", handler.clone());
3450
3451        let result = trigger_internal_hook(&mut event).await;
3452        assert!(result.is_ok());
3453        assert!(*called.lock().unwrap());
3454        assert!(event.messages.contains(&"Handler called".to_string()));
3455
3456        // 清理
3457        unregister_internal_hook("agent:start", &handler);
3458    }
3459
3460    #[tokio::test]
3461    #[serial]
3462    async fn test_trigger_internal_hook_no_handlers() {
3463        // 清理全局注册表以避免干扰
3464        let registry = global_internal_registry();
3465        registry.clear();
3466
3467        // 使用一个不太可能有处理器的事件
3468        let mut event = create_internal_hook_event(
3469            InternalHookEventType::Gateway,
3470            InternalHookAction::Disconnect,
3471            None,
3472            serde_json::json!({}),
3473        );
3474
3475        // 确保没有处理器（已清理）
3476        let handlers = registry.get_handlers(&event.event_key());
3477        assert!(handlers.is_empty());
3478
3479        // 没有处理器时应该静默返回
3480        let result = trigger_internal_hook(&mut event).await;
3481        assert!(result.is_ok());
3482        assert!(event.messages.is_empty());
3483    }
3484
3485    // ========== Agent 事件辅助函数测试 ==========
3486
3487    #[tokio::test]
3488    #[serial]
3489    async fn test_trigger_agent_start() {
3490        // 清理全局注册表以避免干扰
3491        let registry = global_internal_registry();
3492        registry.clear();
3493
3494        // 注册一个处理器来验证事件被触发
3495        let called = Arc::new(std::sync::Mutex::new(false));
3496        let captured_context = Arc::new(std::sync::Mutex::new(serde_json::Value::Null));
3497        let called_clone = called.clone();
3498        let context_clone = captured_context.clone();
3499
3500        let handler: InternalHookHandlerFn = Arc::new(move |event| {
3501            *called_clone.lock().unwrap() = true;
3502            *context_clone.lock().unwrap() = event.context.clone();
3503            event
3504                .messages
3505                .push("Agent start handler called".to_string());
3506            Box::pin(async move { Ok(()) })
3507        });
3508
3509        registry.register("agent:start", handler.clone());
3510
3511        // 触发 agent:start 事件
3512        let event =
3513            trigger_agent_start("test-agent-001", "coding", Some("test-session".to_string()))
3514                .await
3515                .unwrap();
3516
3517        // 验证事件被触发
3518        assert!(*called.lock().unwrap());
3519
3520        // 验证事件属性
3521        assert_eq!(event.event_type, InternalHookEventType::Agent);
3522        assert_eq!(event.action, InternalHookAction::Start);
3523        assert_eq!(event.session_key, Some("test-session".to_string()));
3524        assert_eq!(event.event_key(), "agent:start");
3525
3526        // 验证 context 包含 agent_id 和 agent_type
3527        let context = captured_context.lock().unwrap();
3528        assert_eq!(context["agent_id"], "test-agent-001");
3529        assert_eq!(context["agent_type"], "coding");
3530
3531        // 验证处理器添加的消息
3532        assert!(event
3533            .messages
3534            .contains(&"Agent start handler called".to_string()));
3535
3536        // 清理
3537        registry.unregister("agent:start", &handler);
3538    }
3539
3540    #[tokio::test]
3541    #[serial]
3542    async fn test_trigger_agent_stop() {
3543        let registry = global_internal_registry();
3544        registry.clear();
3545
3546        let called = Arc::new(std::sync::Mutex::new(false));
3547        let captured_context = Arc::new(std::sync::Mutex::new(serde_json::Value::Null));
3548        let called_clone = called.clone();
3549        let context_clone = captured_context.clone();
3550
3551        let handler: InternalHookHandlerFn = Arc::new(move |event| {
3552            *called_clone.lock().unwrap() = true;
3553            *context_clone.lock().unwrap() = event.context.clone();
3554            event.messages.push("Agent stop handler called".to_string());
3555            Box::pin(async move { Ok(()) })
3556        });
3557
3558        registry.register("agent:stop", handler.clone());
3559
3560        // 触发 agent:stop 事件
3561        let event = trigger_agent_stop("test-agent-002", "chat", None)
3562            .await
3563            .unwrap();
3564
3565        // 验证事件被触发
3566        assert!(*called.lock().unwrap());
3567
3568        // 验证事件属性
3569        assert_eq!(event.event_type, InternalHookEventType::Agent);
3570        assert_eq!(event.action, InternalHookAction::Stop);
3571        assert_eq!(event.session_key, None);
3572        assert_eq!(event.event_key(), "agent:stop");
3573
3574        // 验证 context 包含 agent_id 和 agent_type
3575        let context = captured_context.lock().unwrap();
3576        assert_eq!(context["agent_id"], "test-agent-002");
3577        assert_eq!(context["agent_type"], "chat");
3578
3579        // 验证处理器添加的消息
3580        assert!(event
3581            .messages
3582            .contains(&"Agent stop handler called".to_string()));
3583
3584        // 清理
3585        registry.unregister("agent:stop", &handler);
3586    }
3587
3588    #[tokio::test]
3589    #[serial]
3590    async fn test_trigger_agent_error() {
3591        let registry = global_internal_registry();
3592        registry.clear();
3593
3594        let called = Arc::new(std::sync::Mutex::new(false));
3595        let captured_context = Arc::new(std::sync::Mutex::new(serde_json::Value::Null));
3596        let called_clone = called.clone();
3597        let context_clone = captured_context.clone();
3598
3599        let handler: InternalHookHandlerFn = Arc::new(move |event| {
3600            *called_clone.lock().unwrap() = true;
3601            *context_clone.lock().unwrap() = event.context.clone();
3602            event
3603                .messages
3604                .push("Agent error handler called".to_string());
3605            Box::pin(async move { Ok(()) })
3606        });
3607
3608        registry.register("agent:error", handler.clone());
3609
3610        // 触发 agent:error 事件
3611        let event = trigger_agent_error(
3612            "test-agent-003",
3613            "coding",
3614            "Connection timeout",
3615            Some("error-session".to_string()),
3616        )
3617        .await
3618        .unwrap();
3619
3620        // 验证事件被触发
3621        assert!(*called.lock().unwrap());
3622
3623        // 验证事件属性
3624        assert_eq!(event.event_type, InternalHookEventType::Agent);
3625        assert_eq!(event.action, InternalHookAction::Error);
3626        assert_eq!(event.session_key, Some("error-session".to_string()));
3627        assert_eq!(event.event_key(), "agent:error");
3628
3629        // 验证 context 包含 agent_id、agent_type 和 error
3630        let context = captured_context.lock().unwrap();
3631        assert_eq!(context["agent_id"], "test-agent-003");
3632        assert_eq!(context["agent_type"], "coding");
3633        assert_eq!(context["error"], "Connection timeout");
3634
3635        // 验证处理器添加的消息
3636        assert!(event
3637            .messages
3638            .contains(&"Agent error handler called".to_string()));
3639
3640        // 清理
3641        registry.unregister("agent:error", &handler);
3642    }
3643
3644    #[tokio::test]
3645    #[serial]
3646    async fn test_trigger_agent_bootstrap() {
3647        let registry = global_internal_registry();
3648        registry.clear();
3649
3650        let called = Arc::new(std::sync::Mutex::new(false));
3651        let captured_context = Arc::new(std::sync::Mutex::new(serde_json::Value::Null));
3652        let called_clone = called.clone();
3653        let context_clone = captured_context.clone();
3654
3655        let handler: InternalHookHandlerFn = Arc::new(move |event| {
3656            *called_clone.lock().unwrap() = true;
3657            *context_clone.lock().unwrap() = event.context.clone();
3658            event
3659                .messages
3660                .push("Agent bootstrap handler called".to_string());
3661            Box::pin(async move { Ok(()) })
3662        });
3663
3664        registry.register("agent:bootstrap", handler.clone());
3665
3666        // 触发 agent:bootstrap 事件
3667        let event = trigger_agent_bootstrap(
3668            "test-agent-004",
3669            "assistant",
3670            Some("bootstrap-session".to_string()),
3671        )
3672        .await
3673        .unwrap();
3674
3675        // 验证事件被触发
3676        assert!(*called.lock().unwrap());
3677
3678        // 验证事件属性
3679        assert_eq!(event.event_type, InternalHookEventType::Agent);
3680        assert_eq!(event.action, InternalHookAction::Bootstrap);
3681        assert_eq!(event.session_key, Some("bootstrap-session".to_string()));
3682        assert_eq!(event.event_key(), "agent:bootstrap");
3683
3684        // 验证 context 包含 agent_id 和 agent_type
3685        let context = captured_context.lock().unwrap();
3686        assert_eq!(context["agent_id"], "test-agent-004");
3687        assert_eq!(context["agent_type"], "assistant");
3688
3689        // 验证处理器添加的消息
3690        assert!(event
3691            .messages
3692            .contains(&"Agent bootstrap handler called".to_string()));
3693
3694        // 清理
3695        registry.unregister("agent:bootstrap", &handler);
3696    }
3697
3698    #[tokio::test]
3699    #[serial]
3700    async fn test_trigger_agent_start_no_handlers() {
3701        // 清理全局注册表以避免干扰
3702        let registry = global_internal_registry();
3703        registry.clear();
3704
3705        // 测试没有处理器时的行为
3706        let event = trigger_agent_start("no-handler-agent", "test", None)
3707            .await
3708            .unwrap();
3709
3710        // 应该成功返回，messages 为空
3711        assert_eq!(event.event_type, InternalHookEventType::Agent);
3712        assert_eq!(event.action, InternalHookAction::Start);
3713        assert_eq!(event.context["agent_id"], "no-handler-agent");
3714        assert_eq!(event.context["agent_type"], "test");
3715        // messages 可能为空（如果没有处理器）或包含其他测试注册的处理器的消息
3716    }
3717
3718    #[tokio::test]
3719    #[serial]
3720    async fn test_trigger_agent_events_with_type_level_handler() {
3721        let registry = global_internal_registry();
3722        registry.clear();
3723
3724        // 注册类型级别处理器（匹配所有 Agent 事件）
3725        let call_count = Arc::new(std::sync::Mutex::new(0));
3726        let call_count_clone = call_count.clone();
3727
3728        let handler: InternalHookHandlerFn = Arc::new(move |event| {
3729            *call_count_clone.lock().unwrap() += 1;
3730            event.messages.push("Type-level handler called".to_string());
3731            Box::pin(async move { Ok(()) })
3732        });
3733
3734        registry.register("agent", handler.clone());
3735
3736        // 触发不同的 Agent 事件
3737        let _ = trigger_agent_start("agent-1", "coding", None)
3738            .await
3739            .unwrap();
3740        let _ = trigger_agent_stop("agent-1", "coding", None).await.unwrap();
3741        let _ = trigger_agent_error("agent-1", "coding", "error", None)
3742            .await
3743            .unwrap();
3744        let _ = trigger_agent_bootstrap("agent-1", "coding", None)
3745            .await
3746            .unwrap();
3747
3748        // 验证类型级别处理器被调用了 4 次
3749        assert_eq!(*call_count.lock().unwrap(), 4);
3750
3751        // 清理
3752        registry.unregister("agent", &handler);
3753    }
3754
3755    #[tokio::test]
3756    #[serial]
3757    async fn test_trigger_agent_error_context_contains_error_message() {
3758        // 清理全局注册表以避免干扰
3759        let registry = global_internal_registry();
3760        registry.clear();
3761
3762        // 验证 agent:error 事件的 context 包含错误信息
3763        let event = trigger_agent_error(
3764            "error-agent",
3765            "coding",
3766            "This is a detailed error message with special chars: <>&\"'",
3767            None,
3768        )
3769        .await
3770        .unwrap();
3771
3772        assert_eq!(
3773            event.context["error"],
3774            "This is a detailed error message with special chars: <>&\"'"
3775        );
3776    }
3777
3778    #[tokio::test]
3779    #[serial]
3780    async fn test_trigger_agent_events_return_event_with_messages() {
3781        let registry = global_internal_registry();
3782        registry.clear();
3783
3784        // 注册处理器添加多条消息
3785        let handler: InternalHookHandlerFn = Arc::new(|event| {
3786            event.messages.push("Message 1".to_string());
3787            event.messages.push("Message 2".to_string());
3788            event.messages.push("Message 3".to_string());
3789            Box::pin(async move { Ok(()) })
3790        });
3791
3792        registry.register("agent:start", handler.clone());
3793
3794        let event = trigger_agent_start("msg-agent", "coding", None)
3795            .await
3796            .unwrap();
3797
3798        // 验证返回的事件包含处理器添加的消息
3799        assert!(event.messages.contains(&"Message 1".to_string()));
3800        assert!(event.messages.contains(&"Message 2".to_string()));
3801        assert!(event.messages.contains(&"Message 3".to_string()));
3802
3803        // 清理
3804        registry.unregister("agent:start", &handler);
3805    }
3806
3807    // ========== Session 事件触发函数测试 ==========
3808
3809    #[tokio::test]
3810    #[serial]
3811    async fn test_trigger_session_create() {
3812        let registry = global_internal_registry();
3813        registry.clear();
3814
3815        // 注册处理器
3816        let handler: InternalHookHandlerFn = Arc::new(|event| {
3817            event
3818                .messages
3819                .push("session:create handler called".to_string());
3820            Box::pin(async move { Ok(()) })
3821        });
3822
3823        registry.register("session:create", handler.clone());
3824
3825        // 触发 session:create 事件
3826        let event = trigger_session_create("test-session-001", "user:session:123")
3827            .await
3828            .unwrap();
3829
3830        // 验证事件属性
3831        assert_eq!(event.event_type, InternalHookEventType::Session);
3832        assert_eq!(event.action, InternalHookAction::Create);
3833        assert_eq!(event.event_key(), "session:create");
3834        assert_eq!(event.session_key, Some("user:session:123".to_string()));
3835
3836        // 验证 context 包含 session_id 和 session_key
3837        assert_eq!(event.context["session_id"], "test-session-001");
3838        assert_eq!(event.context["session_key"], "user:session:123");
3839
3840        // 验证处理器被调用
3841        assert!(event
3842            .messages
3843            .contains(&"session:create handler called".to_string()));
3844
3845        // 清理
3846        registry.unregister("session:create", &handler);
3847    }
3848
3849    #[tokio::test]
3850    #[serial]
3851    async fn test_trigger_session_resume() {
3852        let registry = global_internal_registry();
3853        registry.clear();
3854
3855        // 注册处理器
3856        let handler: InternalHookHandlerFn = Arc::new(|event| {
3857            event
3858                .messages
3859                .push("session:resume handler called".to_string());
3860            Box::pin(async move { Ok(()) })
3861        });
3862
3863        registry.register("session:resume", handler.clone());
3864
3865        // 触发 session:resume 事件
3866        let event = trigger_session_resume("test-session-002", "user:session:456")
3867            .await
3868            .unwrap();
3869
3870        // 验证事件属性
3871        assert_eq!(event.event_type, InternalHookEventType::Session);
3872        assert_eq!(event.action, InternalHookAction::Resume);
3873        assert_eq!(event.event_key(), "session:resume");
3874        assert_eq!(event.session_key, Some("user:session:456".to_string()));
3875
3876        // 验证 context 包含 session_id 和 session_key
3877        assert_eq!(event.context["session_id"], "test-session-002");
3878        assert_eq!(event.context["session_key"], "user:session:456");
3879
3880        // 验证处理器被调用
3881        assert!(event
3882            .messages
3883            .contains(&"session:resume handler called".to_string()));
3884
3885        // 清理
3886        registry.unregister("session:resume", &handler);
3887    }
3888
3889    #[tokio::test]
3890    #[serial]
3891    async fn test_trigger_session_end() {
3892        let registry = global_internal_registry();
3893        registry.clear();
3894
3895        // 注册处理器
3896        let handler: InternalHookHandlerFn = Arc::new(|event| {
3897            event
3898                .messages
3899                .push("session:end handler called".to_string());
3900            Box::pin(async move { Ok(()) })
3901        });
3902
3903        registry.register("session:end", handler.clone());
3904
3905        // 触发 session:end 事件（带 reason）
3906        let event = trigger_session_end("test-session-003", "user:session:789", Some("logout"))
3907            .await
3908            .unwrap();
3909
3910        // 验证事件属性
3911        assert_eq!(event.event_type, InternalHookEventType::Session);
3912        assert_eq!(event.action, InternalHookAction::End);
3913        assert_eq!(event.event_key(), "session:end");
3914        assert_eq!(event.session_key, Some("user:session:789".to_string()));
3915
3916        // 验证 context 包含 session_id、session_key 和 reason
3917        assert_eq!(event.context["session_id"], "test-session-003");
3918        assert_eq!(event.context["session_key"], "user:session:789");
3919        assert_eq!(event.context["reason"], "logout");
3920
3921        // 验证处理器被调用
3922        assert!(event
3923            .messages
3924            .contains(&"session:end handler called".to_string()));
3925
3926        // 清理
3927        registry.unregister("session:end", &handler);
3928    }
3929
3930    #[tokio::test]
3931    #[serial]
3932    async fn test_trigger_session_end_without_reason() {
3933        // 清理全局注册表以避免干扰
3934        let registry = global_internal_registry();
3935        registry.clear();
3936
3937        // 触发 session:end 事件（不带 reason）
3938        let event = trigger_session_end("test-session-004", "user:session:abc", None)
3939            .await
3940            .unwrap();
3941
3942        // 验证 reason 默认为 "other"
3943        assert_eq!(event.context["reason"], "other");
3944    }
3945
3946    #[tokio::test]
3947    #[serial]
3948    async fn test_trigger_session_compact() {
3949        let registry = global_internal_registry();
3950        registry.clear();
3951
3952        // 注册处理器
3953        let handler: InternalHookHandlerFn = Arc::new(|event| {
3954            event
3955                .messages
3956                .push("session:compact handler called".to_string());
3957            Box::pin(async move { Ok(()) })
3958        });
3959
3960        registry.register("session:compact", handler.clone());
3961
3962        // 触发 session:compact 事件
3963        let event = trigger_session_compact("test-session-005", "user:session:xyz")
3964            .await
3965            .unwrap();
3966
3967        // 验证事件属性
3968        assert_eq!(event.event_type, InternalHookEventType::Session);
3969        assert_eq!(event.action, InternalHookAction::Compact);
3970        assert_eq!(event.event_key(), "session:compact");
3971        assert_eq!(event.session_key, Some("user:session:xyz".to_string()));
3972
3973        // 验证 context 包含 session_id 和 session_key
3974        assert_eq!(event.context["session_id"], "test-session-005");
3975        assert_eq!(event.context["session_key"], "user:session:xyz");
3976
3977        // 验证处理器被调用
3978        assert!(event
3979            .messages
3980            .contains(&"session:compact handler called".to_string()));
3981
3982        // 清理
3983        registry.unregister("session:compact", &handler);
3984    }
3985
3986    #[tokio::test]
3987    #[serial]
3988    async fn test_trigger_session_events_with_type_level_handler() {
3989        let registry = global_internal_registry();
3990        registry.clear();
3991
3992        // 注册类型级别处理器（匹配所有 Session 事件）
3993        let call_count = Arc::new(std::sync::Mutex::new(0));
3994        let call_count_clone = call_count.clone();
3995
3996        let handler: InternalHookHandlerFn = Arc::new(move |event| {
3997            // 只计数我们自己的处理器调用
3998            event.messages.push("type_level_handler_called".to_string());
3999            *call_count_clone.lock().unwrap() += 1;
4000            Box::pin(async move { Ok(()) })
4001        });
4002
4003        registry.register("session", handler.clone());
4004
4005        // 触发所有 Session 事件
4006        let e1 = trigger_session_create("s1", "key1").await.unwrap();
4007        let e2 = trigger_session_resume("s2", "key2").await.unwrap();
4008        let e3 = trigger_session_end("s3", "key3", None).await.unwrap();
4009        let e4 = trigger_session_compact("s4", "key4").await.unwrap();
4010
4011        // 验证每个事件都收到了类型级别处理器的消息
4012        assert!(e1
4013            .messages
4014            .contains(&"type_level_handler_called".to_string()));
4015        assert!(e2
4016            .messages
4017            .contains(&"type_level_handler_called".to_string()));
4018        assert!(e3
4019            .messages
4020            .contains(&"type_level_handler_called".to_string()));
4021        assert!(e4
4022            .messages
4023            .contains(&"type_level_handler_called".to_string()));
4024
4025        // 验证类型级别处理器至少被调用了 4 次
4026        assert!(*call_count.lock().unwrap() >= 4);
4027
4028        // 清理
4029        registry.unregister("session", &handler);
4030    }
4031}
aster/hooks/internal.rs

aster/hooks/
internal.rs
