事件时序表

1. 纯文本 Agent Run

agent_start
turn_start
message_start(user)
message_end(user)
message_start(assistant)
message_update(assistant) × N
message_end(assistant)
turn_end
agent_end
agent_settled        # AgentSession 层稳定

agent_settled 不是 agent-core 通用事件的简单别名，它表达 AgentSession 自动延续已经停止。

2. 带一个 Tool 的 Run

agent_start
turn_start
message_start(user)
message_end(user)
message_start(assistant)
message_update(assistant/toolcall)
message_end(assistant)
tool_execution_start
tool_execution_update × N
tool_execution_end
message_start(toolResult)
message_end(toolResult)
turn_end
turn_start
message_start(assistant)
message_update × N
message_end(assistant)
turn_end
agent_end
agent_settled

ToolResult 是 Message，但没有 Assistant 式流式 message_update。

3. 并行 Tool

tool_execution_start A
tool_execution_start B
tool_execution_update B
tool_execution_update A
tool_execution_end B
tool_execution_end A

Start/Update/End 可交错。只能用 toolCallId 归并。

4. Message Role 规则

Reducer 必须先判断 Role，不能让 User/ToolResult 覆盖 Assistant Draft。

5. Prompt Preflight 旁路

prompt()
→ extension command handled
→ response

或：

prompt()
→ input handler handled
→ response

这两种路径不一定启动 Agent Run，因此不会为该输入统一产生新的 agent_settled。

6. Steering

Agent 正在运行
→ enqueue steering
→ 当前 Assistant Turn/Tool Batch 到边界
→ Steering Message 进入下一 LLM Call

Follow-up 在当前 Run 原本要停止时、agent_end/agent_settled 之前注入，并继续同一个 Agent Loop。具体 Queue Mode 由 AgentSession 配置决定。

7. Retry/Compaction

agent_end
→ provider/recovery policy
→ retry 或 compaction
→ 新的自动 Agent 活动
→ agent_settled

所以 UI 不应在 agent_end 立即置 Idle。

8. Extension Tool 拦截

raw ToolCall
→ tool_execution_start(raw args)
→ prepare / validate
→ tool_call handlers（validated input，可原地修改 event.input）
→ block / transformed args / allow
→ execute
→ tool_result handlers（顺序）
→ final ToolResult

tool_call Throw 会使 Tool 失败且不执行；普通 tool_result Throw 会报告后继续已有结果。

9. Session 启动/关闭

factory/load
→ bind runtime
→ session_start
→ resources_discover
→ normal events
→ session_shutdown
→ host beforeSessionInvalidate
→ session.dispose

session_start/resources_discover/session_shutdown 是 Extension Runner 生命周期事件，不是都属于 公共 AgentSessionEvent。

10. Runtime Replacement

session_before_switch/fork（可能取消）
→ session_shutdown
→ beforeSessionInvalidate（同步宿主拆除）
→ old session.dispose
→ create services/session
→ rebindSession
→ bind extensions

旧 Subscription、Context、Approval 与 Generation 不可复用。

11. RPC 时序

stdin command(id=a)
stdin command(id=b)
stdout response(id=b)
stdout response(id=a)
stdout agent events...

RPC Command 可并发、Response 可乱序；有依赖的 Command 必须等待前一 Response。Prompt Response 只确认 Preflight/接受。

12. Extension UI Request

worker → extension_ui_request(id=ui1)
desktop → dialog
desktop → extension_ui_response(id=ui1)

Worker Exit/Timeout/Window Close 都必须结束 Pending Request。标准 Confirm Request 不自带 ToolCall Canonical Args；安全审批映射由宿主维护。

13. 桌面 Rehydrate

increment generation
→ subscribe/buffer live events
→ get_state/get_messages
→ get_entries(full or since cursor)
→ apply entry snapshot
→ replay buffered local sequence
→ open live gate

Entry ID 用于持久消息去重，Local Sequence 用于排列本次连接中的 Buffer。