docs: 更新协议文档并清理过时计划文件

docs/protocols/agent/api-endpoints.md

@@ -52,7 +52,7 @@ Base URL: `/api/v1/agent`
 
 ## 2) GET `/runs/{thread_id}/events`
 
-订阅指定 thread 的实时事件流。
+订阅指定 thread 的实时事件流（按 `runId` 隔离当前 run）。
 
 ### Path
 
@@ -64,6 +64,7 @@ Base URL: `/api/v1/agent`
 
 | 参数 | 类型 | 默认 | 说明 |
 |---|---|---|---|
+| `runId` | string | - | 目标 run ID（必填）。SSE 仅输出该 run 事件 |
 | `idle_limit` | integer | `300` | 最大空闲轮询次数（1-3600） |
 
 ### Headers
@@ -81,6 +82,11 @@ Base URL: `/api/v1/agent`
 - usage 审计与成本回退策略见 `docs/protocols/agent/sse-events.md`（5) Usage 审计协议）
 - 空闲时会发送 keep-alive 注释行 `: keep-alive`
 
+run 过滤语义：
+
+- 服务端会读取 thread 的事件流游标，但仅向客户端发送 `event.runId == query.runId` 的事件。
+- SSE 连接终止条件为“目标 run 收到 `RUN_FINISHED` 或 `RUN_ERROR`”，其他 run 的 terminal 事件不会终止当前连接。
+
 当前阶段执行说明：
 
 - `chat` 模式采用两阶段：`router` -> `worker`。
@@ -91,6 +97,7 @@ Base URL: `/api/v1/agent`
 
 - `401` 未认证
 - `403` 非会话所有者
+- `422` `runId` 非法
 - `422` `Last-Event-ID` 非法
 - `429` 超过 SSE 连接数限制
 
@@ -279,6 +286,7 @@ Agent 路由的错误同样遵循统一 HTTP 错误契约，详见：
 
 - `AGENT_RUN_INPUT_INVALID`
 - `AGENT_RUN_MESSAGES_INVALID`
+- `AGENT_INVALID_RUN_ID`
 - `AGENT_INVALID_LAST_EVENT_ID`
 - `AGENT_SSE_CONNECTION_LIMIT`
 - `AGENT_ATTACHMENT_EMPTY`

docs/protocols/agent/sse-events.md

@@ -2,6 +2,8 @@
 
 本文档描述 `GET /api/v1/agent/runs/{thread_id}/events` 的事件协议。
 
+> 当前协议要求 SSE 订阅显式携带 `runId`，事件输出按 run 隔离。
+
 ---
 
 ## 1) 事件管道
@@ -13,7 +15,7 @@
 3. 事件同时：
    - 持久化到数据库（用于 history）
    - 发布到 Redis Stream（用于 SSE）
-4. `/runs/{thread_id}/events` 从 Redis Stream 读取并输出 SSE
+4. `/runs/{thread_id}/events` 从 Redis Stream 读取并输出 SSE（仅输出目标 `runId` 事件）
 
 ---
 
@@ -30,6 +32,7 @@ data: <json>
 
 - `id` 可用于断点续流（`Last-Event-ID`）
 - `event` 与 JSON 内 `type` 一致（例如 `RUN_STARTED`）
+- 仅当 payload 中 `runId` 与 query `runId` 一致时才会对外发送
 - 空闲时可能出现 keep-alive 注释帧：
 
 ```text
@@ -41,6 +44,15 @@ data: <json>
 
 ## 3) 事件类型（当前实现）
 
+### 3.0 过滤与终止规则
+
+- 请求参数 `runId` 为本次订阅目标 run。
+- 服务端只转发 `event.runId == runId` 的事件。
+- SSE 连接仅在目标 run 收到 terminal 事件后结束：
+  - `RUN_FINISHED`
+  - `RUN_ERROR`
+- 其他 run 的事件（包括 terminal）不会结束当前连接。
+
 ### 3.1 Run 生命周期
 
 #### `RUN_STARTED`