fix(agent): polish interrupt-resume flow for merge readiness

docs/runtime/runtime-route.md

@@ -788,42 +788,68 @@
 
 ## Agent
 
-### POST /agent
+### POST /agent/runs
 
-运行 Agent 对话（需要认证）。
+创建 Agent 运行（需要认证，SSE 响应）。
 
-**Request:**
+**Request (RunAgentInput):**
 ```json
 {
-  "message": "string (1-8000 chars)",
-  "session_id": "string? (UUID)"
+  "threadId": "string",
+  "runId": "string",
+  "parentRunId": "string?",
+  "state": {},
+  "messages": [],
+  "tools": [],
+  "context": [],
+  "forwardedProps": {},
+  "resume": null
 }
 ```
 
-**Response:** 200 OK
-```json
-{
-  "session_id": "string (UUID)",
-  "output": "string",
-  "events": [
-    {
-      "type": "string",
-      "run_id": "string?",
-      "message_id": "string?",
-      "delta": "string?",
-      "tool_name": "string?",
-      "result": "string?",
-      "output": "string?",
-      "error": "string?"
-    }
-  ]
-}
-```
+**Response:** 200 OK (`text/event-stream`)
 
 **Errors:**
 - 401: 未认证
 - 422: 请求参数无效
 
+### POST /agent/runs/{run_id}/resume
+
+恢复被中断运行（需要认证，SSE 响应）。
+
+**Request (RunAgentInput):**
+```json
+{
+  "threadId": "string",
+  "runId": "string",
+  "state": {},
+  "messages": [],
+  "tools": [],
+  "context": [],
+  "forwardedProps": {},
+  "resume": {
+    "interruptId": "string",
+    "payload": {}
+  }
+}
+```
+
+**State Snapshot Contract:**
+- `state_snapshot` 仅支持 `version = 2`
+- 顶层必须包含 `run_context` 与 `pending_tool_call`
+- 旧格式或缺失字段会被拒绝
+
+**Resume Semantics:**
+- 同一 `interrupt_id` 并发恢复仅允许一个请求成功
+- `expires_at` 超时后会标记为 `EXPIRED`，恢复请求不再生效
+
+**Errors:**
+- 401: 未认证
+- 404: 会话不存在
+- 409: `run_id` 或 `interrupt_id` 冲突，或状态已被消费
+- 410: 挂起调用已过期
+- 422: `state_snapshot` 非法或版本不匹配
+
 ---
 
 ## Infra