feat(agent): 实现 Agent Runtime 核心胶水层 (Phase 4a)

- 添加 Agent trait、AgentSession、RuntimeBundle、AgentBuilder
- 添加 Plan/Step/StepStatus 任务规划数据结构
- 添加 AgentError 统一错误类型（聚合 LlmError/ToolError/MemoryError）
- 实现 submit_turn 单轮对话流程（含 hook 触发与 cost 累计）
- 扩展 LlmCycle 支持 Arc<dyn LlmProvider>
- 扩展 HookEvent 添加 OnTurnStart/OnTurnEnd
- 更新 roadmap 状态

src/llm/cycle.rs

@@ -63,7 +63,7 @@ impl Default for CycleConfig {
 
 /// LLM 调用周期 —— 管理一次或多次 LLM 请求的生命周期。
 pub struct LlmCycle {
-    provider: Box<dyn LlmProvider>,
+    provider: Arc<dyn LlmProvider>,
     config: CycleConfig,
     usage: CostTracker,
     messages: Vec<OpenaiChatMessage>,
@@ -74,8 +74,18 @@ pub struct LlmCycle {
 }
 
 impl LlmCycle {
-    /// 创建一个新的 LlmCycle。
+    /// 创建一个新的 LlmCycle（持有 `Box<dyn LlmProvider>` 的独占所有权）。
+    ///
+    /// 内部将 Box 转为 `Arc<dyn LlmProvider>` 以便 `new_with_arc` 复用句柄。
+    /// 公共签名保持不变，向后兼容。
     pub fn new(provider: Box<dyn LlmProvider>, config: CycleConfig) -> Self {
+        Self::new_with_arc(Arc::from(provider), config)
+    }
+
+    /// 创建一个新的 LlmCycle，共享传入的 `Arc<dyn LlmProvider>` 句柄。
+    ///
+    /// **新增**（Phase 4a 引入）：用于 `AgentSession::submit_turn` 在多 session 间共享 provider。
+    pub fn new_with_arc(provider: Arc<dyn LlmProvider>, config: CycleConfig) -> Self {
         Self {
             provider,
             config,

src/llm/hooks.rs

@@ -16,6 +16,10 @@ pub enum HookEvent {
     OnRetry,
     /// 不可恢复错误返回之前。
     OnError,
+    /// Agent 会话开始一轮 turn 之前（Phase 4a 新增）。
+    OnTurnStart,
+    /// Agent 会话完成一轮 turn 之后（Phase 4a 新增）。
+    OnTurnEnd,
 }
 
 /// 此次钩子调用的上下文。
@@ -29,6 +33,8 @@ pub struct HookContext<'a> {
     pub error: Option<&'a LlmError>,
     /// 当前重试次数（从 1 开始，仅 OnRetry 可用）。
     pub attempt: u32,
+    /// 当前 turn 序号（0-based，仅 OnTurnStart / OnTurnEnd 可用，Phase 4a 新增）。
+    pub turn_index: Option<u32>,
 }
 
 impl<'a> HookContext<'a> {
@@ -38,6 +44,7 @@ impl<'a> HookContext<'a> {
             request: None,
             error: None,
             attempt: 0,
+            turn_index: None,
         }
     }
 
@@ -55,6 +62,12 @@ impl<'a> HookContext<'a> {
         self.attempt = attempt;
         self
     }
+
+    /// 设置 turn 序号（仅 OnTurnStart / OnTurnEnd 使用）。
+    pub(crate) fn with_turn_index(mut self, turn_index: u32) -> Self {
+        self.turn_index = Some(turn_index);
+        self
+    }
 }
 
 /// 钩子执行结果。