docs: update agent and UI protocol documentation

- Update api-endpoints.md with new agent endpoints
- Update run-agent-input.md with new input schemas
- Update sse-events.md with new event types
- Update ui-schema.md with schema changes

docs/protocols/agent/api-endpoints.md

@@ -27,6 +27,8 @@ Base URL: `/api/v1/agent`
 
 - Body: `RunAgentInput`
 - 详细结构见 `docs/protocols/agent/run-agent-input.md`
+- `forwardedProps.agent_type` 必填，由调用方透传，task 不做默认赋值
+- `agent_type=memory` 仅用于自动化调度内部触发，API 入口返回 422
 
 ### Response
 
@@ -81,8 +83,9 @@ Base URL: `/api/v1/agent`
 
 当前阶段执行说明：
 
-- 公开事件阶段为 `worker` / `memory`。
-- `router` 已从运行链路移除，不再作为阶段事件对外发送。
+- `worker` 模式采用两阶段：`router` -> `worker`。
+- `memory` 模式保持单阶段：`memory`。
+- 因此阶段事件可能出现 `router` / `worker` / `memory`。
 
 ### 错误码
 
@@ -129,6 +132,11 @@ Base URL: `/api/v1/agent`
 
 tool 消息在存储层用于运行时上下文续接，不在 `/history` 对外返回。续接时以 `metadata.tool_agent_output` 作为主信源（`content` 为轻量摘要）。
 
+可见性说明：
+
+- `/history` 仅返回命中 `ui.history` 可见位的消息。
+- 内部消息（例如 memory 私有输入）可落库但不会出现在 `/history`。
+
 ### 说明
 
 - 若用户没有任何会话：返回

docs/protocols/agent/run-agent-input.md

@@ -185,12 +185,13 @@ interface Context {
 
 ---
 
-## forwardedProps Schema（当前仅支持 client_time）
+## forwardedProps Schema（支持 agent_type + client_time）
 
-`RunAgentInput.forwardedProps` 支持透传客户端时间上下文。日历相关能力必须使用以下结构：
+`RunAgentInput.forwardedProps` 支持透传运行模式与客户端时间上下文。日历相关能力必须使用以下结构：
 
 ```typescript
 interface ForwardedProps {
+  agent_type: string;               // 必填，运行模式（如 "worker" / "memory"）
   client_time?: {
     device_timezone: string;           // IANA 时区，例如 "America/Los_Angeles"
     client_now_iso: string;            // RFC3339 带偏移时间，例如 "2026-03-16T09:12:33-07:00"
@@ -213,7 +214,9 @@ interface ForwardedProps {
 - `device_timezone` 必须是有效 IANA 时区。
 - `client_now_iso` 必须是 RFC3339 且包含时区偏移。
 - `client_epoch_ms` 必须是整数毫秒时间戳。
-- `forwardedProps` 当前仅允许 `client_time`，额外字段会触发 `422 invalid RunAgentInput.forwardedProps`。
+- `forwardedProps.agent_type` 必填，且必须匹配后端已注册的 agent type。
+- `agent_type=memory` 为自动化任务内部模式，HTTP `/agent/runs` 入口不接受该值。
+- `forwardedProps` 仅允许 `agent_type` 与 `client_time`，额外字段会触发 `422 invalid RunAgentInput.forwardedProps`。
 - 业务代码不得使用服务器本地时区作为事件语义时区。
 
 ### 说明
@@ -235,6 +238,7 @@ Backend 实现了以下验证规则：
 | runId 最大 128 字符 | `runId exceeds length limit` |
 | messages ≤ 200 条 | `RunAgentInput.messages exceeds limit` |
 | user text ≤ 10,000 字符 | `RunAgentInput user message text exceeds limit` |
+| forwardedProps.agent_type 必填 | `invalid RunAgentInput.forwardedProps` |
 | **恰好 1 条 user message** | `RunAgentInput.messages must contain exactly one user message` |
 | user message 必须在第一条 | `RunAgentInput.messages[0].role must be user` |
 | binary 必须是 image/* | `binary content requires image mimeType` |
@@ -272,7 +276,9 @@ Backend 实现了以下验证规则：
   ],
   "tools": [],
   "context": [],
-  "forwardedProps": {}
+  "forwardedProps": {
+    "agent_type": "worker"
+  }
 }
 ```
 
@@ -302,7 +308,9 @@ Backend 实现了以下验证规则：
   ],
   "tools": [],
   "context": [],
-  "forwardedProps": {}
+  "forwardedProps": {
+    "agent_type": "worker"
+  }
 }
 ```
 
@@ -337,7 +345,9 @@ Backend 实现了以下验证规则：
     }
   ],
   "context": [],
-  "forwardedProps": {}
+  "forwardedProps": {
+    "agent_type": "worker"
+  }
 }
 ```
 
@@ -358,6 +368,7 @@ Backend 实现了以下验证规则：
   "tools": [],
   "context": [],
   "forwardedProps": {
+    "agent_type": "worker",
     "client_time": {
       "device_timezone": "America/Los_Angeles",
       "client_now_iso": "2026-03-16T09:12:33-07:00",
@@ -520,5 +531,5 @@ interface UiSchemaRenderer {
 - `tools` 是前端工具通道字段；当前后端运行时不基于该字段构造后端工具 prompt
 - `RunAgentInput` 同时接受 camelCase 与 snake_case 别名输入（推荐统一使用 camelCase）
 - 日历能力依赖 `forwardedProps.client_time` 透传设备时间上下文；缺失时回退用户 profile 时区
-- `forwardedProps` 不支持业务私有控制字段（例如 `system_agent_mode`）
+- `forwardedProps.agent_type` 是受控路由字段，必须由调用方显式传入；后端 task 不做默认赋值
 - tool 消息在存储层用于运行时上下文续接，不在 `/history` 对外返回

docs/protocols/agent/sse-events.md

@@ -84,7 +84,7 @@ data: <json>
   "type": "STEP_STARTED",
   "threadId": "...",
   "runId": "...",
-  "stepName": "worker" | "memory"
+  "stepName": "router" | "worker" | "memory"
 }
 ```
 
@@ -95,7 +95,7 @@ data: <json>
   "type": "STEP_FINISHED",
   "threadId": "...",
   "runId": "...",
-  "stepName": "worker" | "memory"
+  "stepName": "router" | "worker" | "memory"
 }
 ```
 
@@ -111,7 +111,7 @@ data: <json>
   "messageId": "...",
   "toolCallId": "...",
   "toolCallName": "...",
-  "stage": "worker"
+  "stage": "worker" | "memory"
 }
 ```
 
@@ -126,7 +126,7 @@ data: <json>
   "toolCallId": "...",
   "toolCallName": "...",
   "args": {},
-  "stage": "worker"
+  "stage": "worker" | "memory"
 }
 ```
 
@@ -140,7 +140,7 @@ data: <json>
   "messageId": "...",
   "toolCallId": "...",
   "toolCallName": "...",
-  "stage": "worker"
+  "stage": "worker" | "memory"
 }
 ```
 
@@ -153,7 +153,7 @@ data: <json>
   "runId": "...",
   "messageId": "...",
   "role": "tool",
-  "stage": "worker",
+  "stage": "worker" | "memory",
   "tool_name": "...",
   "tool_call_id": "...",
   "tool_call_args": {},
@@ -184,7 +184,7 @@ data: <json>
   "runId": "...",
   "messageId": "...",
   "role": "assistant",
-  "stage": "worker",
+  "stage": "worker" | "memory",
   "status": "success" | "partial_success" | "failed",
   "answer": "...",
   "key_points": [],
@@ -323,3 +323,9 @@ cost = uncached_prompt_tokens * input_cost_per_token
   - `ui_schema`
 
 这部分命名属于当前后端实现约束，文档与实现保持一致。
+
+## 8) 可见性与上下文装载说明
+
+- 持久化消息使用单字段 `visibility_mask`（位掩码）控制 consumer 可见性。
+- `/history` 仅投影 `ui.history` 可见消息。
+- 运行时上下文按当前 stage 对应 consumer 位过滤装载，不依赖前端展示可见性。