feat: 支持 agent 运行取消功能

docs/protocols/agent/api-endpoints.md

@@ -11,6 +11,7 @@ Base URL: `/api/v1/agent`
 | 方法 | 路径 | 说明 |
 |---|---|---|
 | POST | `/runs` | 创建一次 agent run（异步入队） |
+| POST | `/runs/{thread_id}/cancel` | 请求取消指定 run |
 | GET | `/runs/{thread_id}/events` | 订阅 SSE 事件流 |
 | GET | `/history` | 获取历史快照（按天分页） |
 | POST | `/attachments` | 上传用户图片附件 |
@@ -95,7 +96,43 @@ Base URL: `/api/v1/agent`
 
 ---
 
-## 3) GET `/history`
+## 3) POST `/runs/{thread_id}/cancel`
+
+请求取消指定 run。该接口返回 `202` 仅表示取消请求已被后端接收，不保证运行已在同一时刻停止。
+
+### Path
+
+| 参数 | 类型 | 说明 |
+|---|---|---|
+| `thread_id` | string | 会话 ID |
+
+### Query
+
+| 参数 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `runId` | string | 是 | 需要取消的 run ID |
+
+### Response
+
+`202 Accepted`
+
+```ts
+{
+  threadId: string;
+  runId: string;
+  accepted: true;
+}
+```
+
+### 错误码
+
+- `401` 未认证
+- `403` 非会话所有者
+- `422` 参数非法
+
+---
+
+## 4) GET `/history`
 
 返回历史快照（`HistorySnapshotResponse`），不是 SSE 包装事件。
 
@@ -146,7 +183,7 @@ tool 消息在存储层用于运行时上下文续接，不在 `/history` 对外
 
 ---
 
-## 4) POST `/attachments`
+## 5) POST `/attachments`
 
 上传图片附件，返回可直接用于 `RunAgentInput.messages[].content[].url` 的签名链接。
 
@@ -182,7 +219,7 @@ tool 消息在存储层用于运行时上下文续接，不在 `/history` 对外
 
 ---
 
-## 5) GET `/attachments/signed-url`
+## 6) GET `/attachments/signed-url`
 
 对已有存储对象重新签名。
 
@@ -205,7 +242,7 @@ tool 消息在存储层用于运行时上下文续接，不在 `/history` 对外
 
 ---
 
-## 6) POST `/transcribe`
+## 7) POST `/transcribe`
 
 WAV 音频转写。
 

docs/protocols/agent/sse-events.md

@@ -75,6 +75,20 @@ data: <json>
 }
 ```
 
+取消语义（当前实现）：
+
+```json
+{
+  "type": "RUN_ERROR",
+  "threadId": "...",
+  "runId": "...",
+  "message": "run canceled by user",
+  "code": "RUN_CANCELED"
+}
+```
+
+说明：`RUN_CANCELED` 表示用户主动中断，本阶段后端仍复用会话 `failed` 状态以保持兼容。
+
 ### 3.2 阶段事件
 
 #### `STEP_STARTED`