feat(agent): 按 PR #162 架构契约迭代 agent 模块（事件驱动 + 网关解耦）

[Lwwww1]

背景

PR #162 补齐了 docs/bytemind-architecture/* 的架构与接口契约，但当前 internal/agent 仍以 Runner 为中心、同步串行执行。
需要把 agent 从“可用实现”迭代到“契约一致、可扩展、可观测”的主编排层。

现状差距

1. agent 入口仍是同步 RunPrompt，缺少统一 TurnEvent 流。
2. agent 对 session/context/provider/tools/runtime/policy/storage 的边界未完全网关化，耦合偏高。
3. 工具权限评估未形成 agent 层显式前置决策链，审计事件不完整（尤其是 permission/task 关键事件）。
4. runtime 任务能力仍是占位实现，子代理编排（尤其异步归并/worktree）无法落地。
5. prompt_too_long 仅有预算前压缩，缺少“触发后 reactive compact + retry”闭环。

目标

• 对齐 PR 架构设计 #162 中 agent 契约的最小可用版本（MVP）。
• 保持现有 CLI/TUI 行为不回退，采用“适配层 + 分阶段迁移”。

迭代计划

• Phase 0（契约对齐）：统一 policy 优先级口径（hard_deny > explicit_deny > risk_rule > explicit_allow > mode_default > fallback_ask）并固化到 agent 依赖链。
• Phase 1（入口升级）：新增 Engine.HandleTurn(ctx, req) (<-chan TurnEvent, error)，Runner 作为兼容适配器调用新 Engine。
• Phase 1（网关解耦）：补齐 SessionGateway/ContextGateway/ModelGateway/PolicyGateway/ToolGateway/RuntimeGateway/StorageGateway 最小接口与默认实现。
• Phase 2（执行链路）：实现 start/delta/tool_use/tool_result/complete/error 事件流；工具调用前必须经过 PolicyGateway。
• Phase 2（agent 编排闭环）：接入 ContextGateway 的 reactive compact + retry（一次），压缩规则由 context 模块负责。
• Phase 3（子代理最小版）：先落地同步子代理（Spawn + Wait），异步归并与 worktree 隔离单独 issue。
• Phase 3（审计与恢复）：补齐关键审计事件（permission_decision、tool_execute_start/result、task_state_changed）并可回放校验。

验收标准

1. go test ./internal/agent -v 与 go test ./internal/runtime -v 通过。
2. 新增主闭环契约测试：事件顺序、终态一致性、异常分支可重现。
3. 新旧入口兼容：CLI/TUI 的现有调用方式不需要改动即可运行。
4. 工具权限决策与审计日志可关联到 session_id/task_id/trace_id。
5. 子代理 MVP 仅支持同步模式，明确不包含后台归并/worktree。

非目标

• 本 issue 不一次性实现完整五层权限细分。
• 本 issue 不实现异步子代理归并与 worktree 隔离。
• 本 issue 不做 provider 大重构。

模块架构设计（Agent 详细版）

1. 目标与边界

• agent 负责“单回合编排”与“跨模块协调”，不直接内嵌 context/policy/runtime/storage 的实现细节。
• Engine 成为唯一回合执行入口；Runner 仅做兼容适配，不再承载主编排逻辑。
• TurnEvent 是回合执行唯一对外事件契约；CLI/TUI/审计统一消费该事件流。
• 保持现有 RunPrompt/RunPromptWithInput 调用方式不变，先兼容后迁移。

2. 分层结构（建议落地到 internal/agent）

1. engine（编排层）

• 提供 HandleTurn(ctx, req) (<-chan TurnEvent, error)。
• 负责回合状态机、事件发射、错误收敛、重试策略。

2. gateway（边界层）

• 定义并注入 Session/Context/Model/Policy/Tool/Runtime/Storage 七类网关接口。
• 屏蔽底层模块差异，确保 engine 只依赖接口。

3. runner_adapter（兼容层）

• Runner 内部调用 Engine，把 TurnEvent 转为现有输出与旧 Event。
• 在迁移完成前维持旧行为与测试用例稳定。

4. event_codec（事件层）

• 统一 TurnEvent schema、序列号分配、终态判定与校验。

3. 对外契约（MVP）

建议新增（或在 issue 内冻结）如下最小契约：

// 新入口（MVP）
type Engine interface {
    HandleTurn(ctx context.Context, req TurnRequest) (<-chan TurnEvent, error)
}

type TurnRequest struct {
    SessionID   core.SessionID
    UserMessage llm.Message
    Mode        plan.AgentMode
    Workspace   string
    Assets      map[llm.AssetID]llm.ImageAsset
    TraceID     core.TraceID // 空值时由 engine 生成
}

type TurnEvent struct {
    EventID    core.EventID
    SessionID  core.SessionID
    TaskID     core.TaskID
    TraceID    core.TraceID
    TurnID     string
    Sequence   uint64
    Type       string // start|delta|tool_use|tool_result|complete|error
    Timestamp  time.Time
    Payload    map[string]any
    ErrorCode  string
    Retryable  bool
}

4. 七类 Gateway 职责与最小方法

1. SessionGateway

• 职责：加载/持久化 session，维护会话消息 append 原子性。
• 最小方法：Load(...)、Save(...)、AppendMessages(...)。

2. ContextGateway

• 职责：系统提示组装、上下文预算评估、compact 执行与回放保真。
• 最小方法：BuildTurnMessages(...)、EstimateTokens(...)、Compact(...)。
• 约束：继续遵守 prompt 组装顺序：default -> mode -> runtime block -> active skill -> AGENTS.md。

3. ModelGateway

• 职责：封装 Create/Stream 调用与模型能力裁剪（tool use、parts 兼容）。
• 最小方法：Chat(...)、ChatStream(...)。

4. PolicyGateway

• 职责：在工具执行前输出显式 allow/deny/ask 决策与理由。
• 最小方法：DecideTool(ctx, in) (Decision, error)。
• 约束：决策优先级固定为：
  hard_deny > explicit_deny > risk_rule > explicit_allow > mode_default > fallback_ask。

5. ToolGateway

• 职责：执行工具、返回结构化结果，屏蔽 registry/executor 细节。
• 最小方法：Execute(ctx, call, execCtx)。
• 约束：不得绕过 PolicyGateway 直接执行。

6. RuntimeGateway

• 职责：任务/子代理编排入口（MVP 先同步）。
• 最小方法：Submit(...)、Wait(...)、Cancel(...)、Stream(...)。
• 约束：子代理先支持 Spawn + Wait；异步归并/worktree 隔离后续 issue。

7. StorageGateway

• 职责：审计与提示历史写入，保证 event->audit 映射一致。
• 最小方法：AppendAudit(...)、AppendPromptHistory(...)。

5. 回合状态机与事件顺序

回合状态机（engine 内部唯一真源）：

• initialized -> preparing -> model_calling -> (tool_authorizing -> tool_executing -> model_calling)* -> completing -> completed
• 异常路径：任意中间态可转 failed。

事件顺序约束（单个 TurnID 内严格单调）：

1. start
2. delta（可 0..N）
3. tool_use（可 0..N）
4. tool_result（与 tool_use 成对，允许 error 结果）
5. complete 或 error（二选一终态）

补充约束：

• 每个事件必须带 session_id + trace_id + sequence。
• 若存在 runtime 任务，补 task_id 并透传到审计事件。
• complete/error 发出后 channel 关闭。

6. 权限前置决策链（工具调用前）

对每个 tool call 执行以下流程：

1. 归一化工具名与参数（空名直接 deny）。
2. PolicyGateway.DecideTool 返回 {decision, reason_code, risk_level}。
3. 发射 permission_decision 审计事件。
4. allow 才进入 tool_use -> tool_result；deny/ask 直接回写结构化 tool_result（error）并继续回合。

说明：

• ask 在 CLI/TUI 可映射交互确认；本 issue MVP 可先按配置降级为 deny 或 allow（需文档固定）。
• 决策结果必须可重放（相同输入得到同类决策）。

7. prompt_too_long 的 reactive compact + retry（一次）

触发点：ModelGateway.Chat/ChatStream 返回 context too long（含本地预算与 provider 错误）。

处理流程：

1. 首次命中 prompt_too_long 时，发 error（code=prompt_too_long_pre_retry）内部标记，不对外终止。
2. 调用 ContextGateway.Compact(reason=reactive_prompt_too_long, keep_latest_user=true)。
3. 重新构建消息并重试模型调用一次。
4. 若仍失败，发终态 error（code=prompt_too_long），结束回合。

一致性约束：

• 只允许一次 reactive retry，避免无限循环。
• 压缩后必须保留当前回合用户输入与必要 tool_use/tool_result 配对语义。

8. Runtime/子代理集成（MVP）

• engine 不直接管理子代理线程，统一通过 RuntimeGateway 触发。
• 同步子代理路径：
  1. Spawn 返回 task_id
  2. 发射 task_state_changed(pending/running) 审计事件
  3. Wait 收敛结果并映射为 tool_result 或 error
• 父回合取消时调用 RuntimeGateway.Cancel(task_id)，并发射 task_state_changed(killed)。

9. 审计模型与可回放要求

最小审计动作集合：

• permission_decision
• tool_execute_start
• tool_execute_result
• task_state_changed
• turn_complete / turn_error

关联键要求：

• 必带：session_id, trace_id
• 有任务时必带：task_id
• 同回合内建议记录：turn_id, sequence

10. Runner 兼容适配设计

• Runner.RunPrompt* 保留签名。
• Runner 内部流程改为：
  1. 组装 TurnRequest
  2. 调用 Engine.HandleTurn
  3. 消费 TurnEvent 并映射旧 Event（run_started/assistant_delta/tool_call_started/...）
  4. 保持当前 stdout 输出行为与测试快照不变

迁移完成判定：

• runner.go 仅剩参数组装与适配逻辑，不再承担核心状态机。

11. 并发与故障收敛策略

• 单回合事件流由一个主 goroutine 串行发射，保证序号严格递增。
• 工具执行可并发扩展，但 MVP 先保持串行（行为兼容优先）。
• 任一不可恢复错误统一落为 error 终态事件并关闭流，禁止悬挂 channel。

12. 与阶段计划的映射

• Phase 0：冻结 PolicyGateway 优先级与 reason_code 字典。
• Phase 1：落地 Engine + RunnerAdapter + Gateway 接口骨架。
• Phase 2：打通 TurnEvent 主链路与 reactive compact + retry。
• Phase 3：接入同步子代理 + 审计回放校验。

13. 测试矩阵（新增建议）

1. 事件流契约

• 顺序：start -> delta* -> tool_use* -> tool_result* -> complete|error
• 终态唯一性与 channel close。

2. 权限链路

• 覆盖 hard_deny/explicit_deny/risk_rule/explicit_allow/mode_default/fallback_ask 六级优先级。
• deny/ask 不执行工具，且有 permission_decision 审计。

3. reactive compact

• 首次 prompt too long -> compact -> retry 成功。
• 二次失败 -> prompt_too_long 终态错误。

4. 兼容层

• 旧 Runner 入口输出与关键 Event 序列不回归。

5. 子代理 MVP

• Spawn + Wait 正常闭环。
• 父回合取消能传播到 runtime 任务。

[Lwwww1]

@xgopilot 这个agent模块迭代计划怎么样？有没有偏离方向？

[fennoai]

结论

整体方向没有偏离，而且和你在 issue 里定义的 MVP 边界是一致的：Engine.HandleTurn 事件化入口、网关解耦、策略前置、prompt_too_long 闭环、子代理先做同步版，这条主线是对的。

主要风险点（建议提前收敛）

1. Phase 1 同时做“入口升级 + 七类 Gateway”范围偏大，建议先把 Runner -> Engine 适配打通，再逐个替换网关实现，避免一次性改动过深导致 CLI/TUI 回归。
2. 事件契约需要先冻结最小字段（至少 session_id/task_id/trace_id + event sequence），否则 Phase 2/3 的审计和回放会反复返工。
3. reactive compact + retry 建议明确只重试一次，并规定 tool_use/tool_result 保留规则（你已提出“成对保留”，这是关键），否则容易出现非确定性。
4. 子代理 MVP 虽只做同步 Spawn + Wait，但建议在 RuntimeGateway 里预留统一任务状态机接口（哪怕先单实现），避免后续异步化时改协议。

我建议的落地顺序（更稳）

1. 先落 Engine.HandleTurn + Runner 兼容适配（行为不变）。
2. 固化 TurnEvent 最小 schema 与顺序测试（start -> delta -> tool_use -> tool_result -> complete/error）。
3. 把 PolicyGateway 前置到工具调用链，再补审计事件。
4. 最后接 prompt_too_long reactive retry 和同步子代理。

以上顺序能更好满足你的验收标准 1/2/3，同时降低“改完难验证”的风险。

View job run

[Lwwww1]

已将 #178 拆分为以下可认领子 issue：

1. feat(agent): Phase 1-1 引入 Engine.HandleTurn 与 Runner 兼容适配骨架 #192 feat(agent): Phase 1-1 引入 Engine.HandleTurn 与 Runner 兼容适配骨架
2. feat(agent): Phase 1-2 冻结 TurnEvent 契约并补齐事件顺序测试 #193 feat(agent): Phase 1-2 冻结 TurnEvent 契约并补齐事件顺序测试
3. feat(agent/policy): Phase 2-1 工具权限前置决策链与 permission_decision 审计 #194 feat(agent/policy): Phase 2-1 工具权限前置决策链与 permission_decision 审计
4. feat(agent/context): Phase 2-2 prompt_too_long 的 reactive compact + retry 一次闭环 #195 feat(agent/context): Phase 2-2 prompt_too_long 的 reactive compact + retry 一次闭环
5. feat(agent/runtime): Phase 3 接入同步子代理 Spawn+Wait 与 task_state_changed 审计 #196 feat(agent/runtime): Phase 3 接入同步子代理 Spawn+Wait 与 task_state_changed 审计

建议执行顺序：#192 -> #193 -> (#194 和 #195 可并行) -> #196。

[Lwwww1]

已检查 #178 及已拆分子项（#192~#196，均已关闭）。

结论：#178 尚未完成。主要缺口是 Engine.HandleTurn 尚未承载完整 turn 编排，Runner 仍有较多编排逻辑。

已创建后续子 issue：#237。