Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

feat(agent): persist human-in-the-loop prompts with a shared broker (#4250)

lyingbug383d26535adc
diff --git a/client/mcp_service.go b/client/mcp_service.go
index 269dd667d..5ff543af8 100644
--- a/client/mcp_service.go
+++ b/client/mcp_service.go
@@ -298,3 +298,36 @@ func (c *Client) ResolveToolApproval(ctx context.Context, pendingID string, req
}
return parseResponse(resp, &response)
}
+
+// ResolveAgentPromptRequest answers a prompt an agent run is waiting on. Kind
+// must match the prompt ("ask_user" or "tool_approval"); Response is the
+// kind's answer, e.g. {"text": "..."} or {"selected": ["..."]} for ask_user,
+// {"approved": true} or {"approved": false, "reason": "..."} for
+// tool_approval (approval may add "modified_args": {...}). Unknown fields are
+// rejected.
+type ResolveAgentPromptRequest struct {
+ Kind string `json:"kind"`
+ Response json.RawMessage `json:"response"`
+}
+
+// ResolveAgentPrompt answers a pending agent prompt by id. Resumed reports
+// that the run had been suspended and now continues in the background; its
+// output lands in the same assistant message.
+// Server route: POST /api/v1/agent/prompts/{prompt_id}.
+func (c *Client) ResolveAgentPrompt(
+ ctx context.Context, promptID string, req *ResolveAgentPromptRequest,
+) (resumed bool, err error) {
+ path := fmt.Sprintf("/api/v1/agent/prompts/%s", promptID)
+ resp, err := c.doRequest(ctx, http.MethodPost, path, req, nil)
+ if err != nil {
+ return false, err
+ }
+ var response struct {
+ Success bool `json:"success"`
+ Resumed bool `json:"resumed"`
+ }
+ if err := parseResponse(resp, &response); err != nil {
+ return false, err
+ }
+ return response.Resumed, nil
+}
diff --git a/config/builtin_agents.yaml b/config/builtin_agents.yaml
index fcea12421..93ee8f760 100644
--- a/config/builtin_agents.yaml
+++ b/config/builtin_agents.yaml
@@ -79,6 +79,7 @@ builtin_agents:
- "read_document"
- "list_documents"
- "query_knowledge_graph"
+ - "ask_user"
web_search_enabled: true
web_search_max_results: 5
reflection_enabled: false
@@ -126,6 +127,7 @@ builtin_agents:
allowed_tools:
- "data_schema"
- "data_analysis"
+ - "ask_user"
web_search_enabled: false
web_search_max_results: 0
reflection_enabled: true
diff --git a/docs/design/agent-hitl-suspend-resume.md b/docs/design/agent-hitl-suspend-resume.md
new file mode 100644
index 000000000..e4db100af
--- /dev/null
+++ b/docs/design/agent-hitl-suspend-resume.md
@@ -0,0 +1,467 @@
+# Agent 人工交互(HITL):两段式挂起与恢复
+
+状态:草案(P1 已实现) 关联:issue #1173(MCP 工具人工审批)
+
+## 0. 范围:通用人工交互,而不只是工具审批
+
+“Agent 停下来等人”有多种形态,本设计把它们统一成一个模型:**交互请求(prompt)**。一条交互请求有类型(`kind`)、请求载荷(`request`)和用户回答(`response`),由通用核心 `internal/agent/hitl.Broker` 负责持久化、等待、跨副本投递和挂起恢复;各类型只提供载荷结构、回答校验和前端卡片。
+
+| kind | 场景 | 回答 | 可挂起(`suspendable`) |
+|---|---|---|---|
+| `tool_approval` | MCP 工具执行前审批 | 批准/拒绝、修改后的参数、理由 | 是 |
+| `mcp_oauth` | MCP 服务需要用户先完成 OAuth 授权 | 已授权/放弃 | 是 |
+| `ask_user`(规划) | Agent 主动向用户提问,弹窗或表单收集答案 | 按问题的 schema 填写 | 是 |
+| MCP elicitation(规划) | MCP 服务端在工具调用**进行中**向用户索取输入 | 按 elicitation schema | **否** |
+| 浏览器人工接手(规划) | 登录、验证码等需要人在浏览器里操作 | 完成/放弃 | **否** |
+
+**可挂起的边界**:交互发生在外部调用**之前**(审批、OAuth、提问),运行可以安全地落库结束,之后从快照恢复;交互发生在外部调用**进行中**(elicitation 期间 MCP 会话和工具调用都开着;浏览器接手依赖副本上的连接),运行状态无法序列化,只能在内存里短等待,超时即按失败处理。记录上的 `suspendable` 标记由发起方填写,Broker 据此决定短等待到期后是挂起还是关闭。
+
+下文以工具审批为主线描述流程,其他可挂起的类型走完全相同的路径,只是“恢复时如何把回答交给被阻塞的调用”不同(见 6.1 的 `PreDecided`)。
+
+## 1. 背景与目标
+
+当前 `approval.Gate.RequestAndWait` 是同步阻塞式审批:Agent 运行的 goroutine 原地等待,进程内存里保存着完整的 ReAct 状态,等待上限默认 10 分钟(`tool_approval_timeout_seconds`)。这带来四个限制:
+
+1. 超时只是防止 goroutine 泄漏的保险丝,无法支持“第二天再审批”。
+2. waiter 只在进程内存里,发版、OOM、Pod 调度后待审批状态全部丢失。
+3. `AgentSteps` 只在轮次结束时由 `handleComplete` 写库,等待期间进程崩溃会丢掉整轮已完成的步骤。
+4. 等待期间会话一直处于“运行中”。
+
+目标:
+
+- 用户就在旁边时体验不变:短时间内仍在内存里等待,零额外延迟。
+- 超过短等待阈值后,把运行状态持久化并结束本次运行,释放 goroutine 和会话占用。
+- 用户任意时间(在过期时间内)批准或拒绝后,由任意副本发起一次新的运行,接着执行被打断的那一轮,然后继续 ReAct 循环,输出写入**同一条**助手消息。
+- 多副本部署下正确:状态以数据库为准,Redis 只用于唤醒和事件流。
+
+不在本期范围:
+
+- 非阻塞的延迟审批模式(工具立即返回“待审批”)。它依赖本设计的基础设施,以后作为个别工具的可选模式单独设计。
+- 内置工具的审批(审批仍只接入 MCP 工具)。
+- MCP elicitation 与浏览器人工接手的具体接入(只保证模型能承载它们,见第 0 节)。
+
+## 2. 现状要点(设计依据)
+
+| 事实 | 位置 | 对设计的影响 |
+|---|---|---|
+| 引擎跨轮无状态,`Execute` 总是追加一条新 user 消息并从第 0 轮开始 | `internal/agent/engine.go:326` | 需要新增恢复入口,不能复用 `Execute` |
+| 本轮 user 内容经 `RenderUserTurnContent` 渲染(含 runtime context),不落库;渲染结果含本次请求 Registry 的 cN/dN 句柄 | `internal/agent/observe.go:1032` | 快照保存原始 query 与图片 URL,恢复时用新 Registry 重新渲染 |
+| step 在一轮工具全部结束后才 append;此前只在局部变量里 | `engine.go:1056` | 需要引擎显式跟踪“进行中的一轮” |
+| MCP 工具不在 `CanRunConcurrently` 白名单,是并行执行中的屏障 | `act.go:306-316` | 同一时刻一次运行最多只有一个待审批调用 |
+| `response.ToolCalls` 的参数含 cN/dN/res:// 等临时句柄,在 `runToolCall` 里才解码 | `act.go:418` 起、`internal/modelcontext/registry.go` | 未执行调用的参数必须在挂起时用当前 Registry 解码后再持久化 |
+| `LoadAgentHistory` 只回放 `IsCompleted=true` 的轮次 | `agent_history.go:237` | 挂起的轮次不会进入后续轮次的历史,恢复时由快照提供 |
+| `Message` 没有状态字段;仓储 `Updates(struct)` 跳过零值 | `internal/types/message.go`、`repository/message.go:263` | 新增 `run_state` 列和列级更新方法 |
+| 引用由 handler 在 `EventAgentReferences` 上累积;complete 时仅非空才覆盖 | `agent_stream_handler.go:712` 起 | 恢复时 handler 要以已持久化的引用为初值 |
+| live-run 标记在 StreamManager,`SetLiveRun` 是 SetNX,`ClearLiveRun` 是 CAS | `internal/stream/redis_manager.go:358-496` | 直接复用为会话级互斥 |
+| 事件流 key 为 `{prefix}:{session}:{message}`,TTL 1h;没有清空接口 | `interfaces/stream_manager.go` | 需要新增 `ResetEvents` |
+| asynq 仅在 `REDIS_ADDR` 非空时启用;否则为进程内 `SyncTaskExecutor`(不做 TaskID 去重) | `internal/container/container.go:442-473` | 去重不能只靠 TaskID,必须叠加数据库 CAS |
+| 沙箱绑定在 Redis,客户端为远程接口;每条退出路径都会给 `/workspace` 打检查点 | `internal/sandbox/session_binding_redis.go`、`agent_stream_handler.go:754` | 挂起路径同样打检查点,恢复时沙箱已回收则从检查点还原 |
+| 前端刷新后从 `agent_steps` 重建时间线,不会还原审批卡片;`is_completed=false` 会立即调用 `continue-stream` | `useChatStreamHandler.ts:324-472`、`chat/index.vue:949-984` | 前端需要识别新状态,并从持久化数据渲染卡片 |
+
+## 3. 总体方案
+
+一次交互经历两个阶段:
+
+- **短等待阶段(hot)**:与现在一致,运行 goroutine 在内存里等待,默认最长 120 秒。用户在此期间回答,结果直接投递给 waiter,运行原地继续。
+- **挂起阶段(suspended)**:超过短等待阈值后,可挂起的交互把运行状态落库,运行以 `awaiting_input` 结束。用户回答后,由恢复任务在任意副本上重建引擎,继续执行。不可挂起的交互在短等待到期后直接关闭为 `expired`。
+
+进入交互的那一刻(而不是超时时)就把完整快照写库。因此短等待阶段的进程崩溃也能被回收任务转成挂起状态,不丢步骤。
+
+```mermaid
+stateDiagram-v2
+ [*] --> pending: 进入交互,写快照,持有租约
+ pending --> answered: 用户回答(任意副本 CAS)
+ pending --> suspended: 短等待超时且可挂起(持有者 CAS)\n或租约过期(回收任务 CAS)
+ pending --> expired: 短等待超时且不可挂起
+ pending --> canceled: 用户停止运行
+ suspended --> answered: 用户回答
+ suspended --> superseded: 用户发新消息 / 回溯 / 删除会话
+ suspended --> expired: 超过过期时间(回收任务)
+ answered --> executing: 回答需要触发外部副作用(如批准的工具调用)
+ answered --> done: 回答已交给模型(拒绝、OAuth、提问)
+ executing --> done: 工具结果已持久化
+ executing --> failed: 执行中断,结果未知
+ done --> [*]
+ failed --> [*]
+ canceled --> [*]
+ superseded --> [*]
+ expired --> [*]
+```
+
+`answered` 只表示“用户已回答”,回答内容(批准还是拒绝、填了什么)在 `response` 里,与“由谁继续执行”无关:如果持有者 waiter 还活着,就由它在内存中继续;否则由恢复任务继续。系统侧关闭(超时、取消、取代)的原因写在 `close_reason`,与用户回答分开存放。
+
+## 4. 数据模型
+
+### 4.1 新表 `agent_prompts`
+
+一条记录对应一次交互请求(主键即现有前端字段 `pending_id`)。与类型相关的内容全部放在 `request` / `response` 两个 JSON 列里,新增类型不需要改表。
+
+| 列 | 类型 | 说明 |
+|---|---|---|
+| `id` | varchar(36) PK | 即 `pending_id` |
+| `tenant_id` | bigint | 发起运行的租户(执行租户) |
+| `user_id` | varchar | 会话所有者,Resolve 授权用;记录上有值时调用方必须是同一用户(调用方为空视为不匹配),记录上为空时只校验租户(与原审批行为一致) |
+| `session_id` | varchar(36) | Resolve 时与路由中的会话比对 |
+| `assistant_message_id` | varchar(36) | |
+| `request_id` | varchar | 发起运行的 request id,用于追踪 |
+| `kind` | varchar(32) | `tool_approval`、`mcp_oauth`,后续 `ask_user` 等;Resolve 时与接口声明的类型比对 |
+| `tool_call_id` | varchar | 被阻塞的工具调用 |
+| `suspendable` | boolean | 见第 0 节 |
+| `request` | jsonb / text | 类型相关的请求载荷,例如审批的服务、工具名和**已解码**参数(不含临时句柄) |
+| `response` | jsonb / text | 用户回答,例如 `{approved, modified_args, reason}` |
+| `status` | varchar(32) | 见第 3 节状态机 |
+| `close_reason` | text | 系统侧关闭的原因(超时、取消、取代) |
+| `resolved_by` | varchar | 作答的用户 |
+| `resolved_at` | timestamptz | |
+| `owner_instance` | varchar | 当前等待或恢复运行的唯一所有权令牌(同一副本接管时也更换) |
+| `lease_until` | timestamptz | 持有者租约,持有者每 10s 续约 |
+| `expires_at` | timestamptz | 挂起后的过期时间;为空表示不过期 |
+| `created_at` / `updated_at` | timestamptz | |
+
+索引:
+
+- `(session_id, status)`:新消息到来时查找待处理的交互。
+- `(status, lease_until)`、`(status, expires_at)`:回收任务扫描。
+- `(assistant_message_id)`。
+
+各类型的载荷结构定义在 `internal/types/agent_prompt.go`(如 `ToolApprovalPromptRequest` / `ToolApprovalPromptResponse`),回答校验函数通过 `Broker.RegisterKind` 注册;未注册的类型一律拒绝回答。
+
+### 4.2 新表 `agent_run_suspensions`
+
+一条记录对应一条处于挂起或执行中的助手消息,保存恢复所需的全部运行状态。与交互表分开,原因是交互表承载“回答”,这张表承载“运行状态”,生命周期不同:恢复完成后快照即可删除,交互记录作为审计保留。
+
+| 列 | 类型 | 说明 |
+|---|---|---|
+| `assistant_message_id` | varchar(36) PK | |
+| `tenant_id` / `session_id` | | |
+| `prompt_id` | varchar(36) | 当前阻塞它的交互 |
+| `snapshot_version` | int | 快照格式版本,当前为 1 |
+| `snapshot` | jsonb / text | 见 4.4 |
+| `created_at` / `updated_at` | timestamptz | |
+
+### 4.3 `messages` 表新增列
+
+| 列 | 类型 | 说明 |
+|---|---|---|
+| `run_state` | varchar(32),默认 `''` | `''` 表示沿用 `is_completed` 语义;`awaiting_input` 表示已挂起,等待用户回答 |
+
+挂起的消息:`is_completed=false`、`run_state='awaiting_input'`、`agent_steps` 为挂起前已完成的步骤(供展示)。
+
+新增仓储列级方法,避免 `Updates(struct)` 跳过零值:
+
+- `MarkMessageAwaitingInput(ctx, sessionID, messageID, steps, refs, usage, sandboxCheckpoint)`
+- `ClearMessageRunState(ctx, sessionID, messageID)`
+
+`SessionHasIncompleteAssistant`(回溯时判断会话是否忙碌)改为排除 `run_state='awaiting_input'`,由回溯流程先取代挂起再继续(见 8.3)。
+
+### 4.4 快照格式(版本 1)
+
+定义在 `internal/agent/suspend.go`:
+
+```go
+type RunSnapshot struct {
+ Version int `json:"version"`
+ // 调用方的 types.ResumableAgentRequest(只存持久标识)
+ Request json.RawMessage `json:"request,omitempty"`
+ // 原始 query 与图片 URL;恢复时用新 Registry 重新渲染本轮 user 消息
+ Query string `json:"query"`
+ ImageURLs []string `json:"image_urls,omitempty"`
+
+ // 已完成的轮次,与将来写入 Message.AgentSteps 的内容一致
+ CompletedSteps []types.AgentStep `json:"completed_steps"`
+ KnowledgeRefs []*types.SearchResult `json:"knowledge_refs,omitempty"`
+ CurrentRound int `json:"current_round"`
+ TurnUsage types.TokenUsage `json:"turn_usage"`
+
+ // 被打断的那一轮
+ PendingRound PendingRound `json:"pending_round"`
+}
+
+type PendingRound struct {
+ // 本轮的 thought / reasoning;ToolCalls 只含阻塞调用之前已完成的调用
+ Step types.AgentStep `json:"step"`
+ // 模型在这一轮发出的全部调用,参数均为已解码的持久形式
+ Calls []PendingCall `json:"calls"`
+ // 被交互阻塞的调用下标,之后的调用尚未执行
+ BlockedIndex int `json:"blocked_index"`
+}
+
+type PendingCall struct {
+ ID string `json:"id"` // 已规范化
+ Name string `json:"name"`
+ Arguments string `json:"arguments"` // 已解码
+ UnresolvedHandles []string `json:"unresolved_handles,omitempty"`
+ ProviderMetadata types.ToolCallMetadata `json:"provider_metadata,omitempty"`
+}
+```
+
+`types.ResumableAgentRequest` 保存原始 Query、AgentID、SummaryModelID、ReasoningEffort、SharedAgentReadOnly、KnowledgeBaseIDs、KnowledgeIDs、TagScopes、MCPServiceIDs、SkillNames、WebSearchEnabled、QuestionOrigin、UserMessageID、Language。会话、附件和图片在恢复时从存储重新读取;本机浏览器连接绑定在某个副本的 WebSocket 上,恢复时一律视为不可用。`AgentTenantID`(P3 新增)记录智能体所属工作区,用来在恢复时解析共享智能体。快照中的 `UserMessages` 保存 `UserMessagesBefore` 引用的补充消息正文,恢复时按原轮次边界插入;旧快照缺少正文时,从同一会话的消息记录补齐。已消费事件仍由 steer 列表中的 consumed 标记去重。
+
+**临时句柄的处理(关键)**:模型输出里的 cN/dN/res:// 句柄只在本次运行的 `modelcontext.Registry` 中有效,恢复后 Registry 是新建的,编号可能不同。本轮 user 消息和工具结果在发给模型前都被编码过,所以快照里不存渲染后的消息,只存原始 query 和已解码的步骤。`think.go` 在拿到模型响应时已经对 `response.ToolCalls` 执行 `DecodeToolCalls`,`Function.Arguments` 即解码后的参数(`ModelArguments` 不落库),快照直接保存它和 `UnresolvedHandles`。恢复时跳过解码步骤;`UnresolvedHandles` 非空的调用照旧在执行前失败。
+
+已完成步骤里的 thought、工具参数和结果本来就以解码后的形式存储(`modelcontext` 的约定是“模型输出在被工具、存储、UI 消费前先解码”)。恢复后每次调用 LLM 前 `EncodeMessages` 会重新编码,编号一致性由新 Registry 自己保证。
+
+恢复 MCP 工具注册表时,同时读取已完成历史和挂起轮次中已发出的调用,确保首次调用的延迟加载工具也能重建。
+
+## 5. 后端流程
+
+### 5.1 进入交互(持有者,短等待阶段)
+
+分两层:通用核心 `hitl.Broker.Await(ctx, Spec)` 负责持久化与等待;各类型的适配层负责构造载荷、发出类型专属事件、解释回答。工具审批的适配层是 `approval.Gate`,`MCPTool.Execute` 判断需要审批后调用 `Gate.RequestAndWait`,后者构造 `ToolApprovalPromptRequest` 再调用 `Broker.Await`。`Broker.Await` 的步骤:
+
+1. 调用方通过 `ToolExecContext.Snapshot` 取得当前运行快照(见 6.1),放进 `Spec.Suspend`。取快照失败时不挂起,退回内存等待。
+2. 有快照时先写 `agent_run_suspensions`,再写 `agent_prompts`(`status=pending`、`suspendable=true`、`owner_instance`、`lease_until=now+30s`)。两步不在同一事务里:快照先落库,回收任务看到交互记录时快照一定已存在;交互记录写失败时快照随后被删除。交互没有以挂起结束(回答、超时、取消、写库失败)时,`Await` 退出前按 `(assistant_message_id, prompt_id)` 条件删除快照,不会误删同一消息上更新的快照。
+3. 本地登记 waiter,调用适配层的 `Emit` 发出事件(工具审批仍是 `tool_approval_required`,新增字段 `hot_wait_seconds`;`timeout_seconds` 保留为同一值,兼容旧前端)。
+4. 等待以下任一事件:
+ - Pub/Sub 唤醒(频道 `weknora:agent_prompt:wake`):从数据库读取回答,以数据库为准。
+ - 每 3 秒轮询一次数据库状态,兜底 Pub/Sub 丢消息。
+ - 短等待计时器到期:可挂起时执行 `pending → suspended` 的 CAS,同时写入 `expires_at`;不可挂起时执行 `pending → expired`。CAS 失败说明用户刚好回答,转为读取回答。
+ - ctx 取消(用户停止):执行 `pending → canceled` 的 CAS。失败同样转为读取回答。
+5. 后台每 10 秒续约 `lease_until`,续约 CAS 同时校验可续约状态和本次运行的 `owner_instance` 令牌。
+6. 拿到回答后由适配层 `Consume`,CAS 必须匹配本次运行的所有权令牌且成功后才能继续。失去所有权的等待者退出,不再落库或发布完成事件。存储出错不算失去所有权:先重试,必要时重新读取记录确认同一所有者的目标状态已落库。仍为 answered 或读取失败时返回存储错误,不执行工具;按所有权令牌尽力关闭交互,并走普通失败收尾、发布失败事件,避免错误地 detach 后遗留未完成消息:
+ - 需要外部副作用(批准的工具调用):CAS `answered → executing`,执行工具,再 CAS `executing → done`(`MarkExecuted`),删除快照。
+ - 其他(拒绝、OAuth、提问):CAS `answered → done`,把回答交给调用方,删除快照。
+ - 挂起:返回带 `Suspend` 标记的结果(见 6.2),引擎停止本轮并结束运行。
+
+关闭挂起功能时(`prompt_suspend_enabled=false`),第 4 步的短等待计时器使用原有的 `tool_approval_timeout_seconds`,到期后按现在的逻辑记为超时。数据库记录照样写,便于审计和跨实例 Resolve。
+
+P1 已实现第 2 至 6 步中除快照与挂起以外的部分:超时一律关闭为 `expired`。P2 补上了快照与挂起:只有 HTTP 流式入口(Web、嵌入页、API)的请求设置 `QARequest.Suspendable`,并且开关打开时,引擎才提供 `Snapshot`;IM 与 MCP server 入口不设置,仍按原有超时阻塞。持有者在短等待中发现记录已被回收任务改为 `suspended`(自己的租约已过期),同样按挂起返回。
+
+### 5.2 用户回答(任意副本)
+
+现有接口 `POST /agent/tool-approvals/{pending_id}` 与 MCP OAuth 回调保留,内部都走 `Broker.Resolve`。通用接口 `POST /agent/prompts/{prompt_id}`(嵌入页为 `POST /embed/.../sessions/{session_id}/prompts/{prompt_id}`)的请求体为 `{kind, response}`,`response` 是该类型的回答(P4.5 已实现)。它接受 `ask_user` 与 `tool_approval`;`mcp_oauth` 只能经 OAuth 回调完成,按 400 拒绝。旧接口作为兼容层保留。`Broker.Resolve` 的步骤:
+
+1. 按 id 读取记录。`kind` 与接口声明的类型不符、`session_id` 与路由中的会话不符时,一律返回 `not_found`,不暴露记录存在与否。再校验 `tenant_id` 和 `user_id`(调用方 userID 为空视为不匹配)。嵌入页接口额外校验 channel 与 session 的归属。
+2. 调用该类型注册的校验函数。两类回答都拒绝未知字段。工具审批:回答为 `{approved, modified_args?, reason?}`,`approved` 必填;`modified_args` 只在批准时生效,必须是 JSON 对象;P2 起再按工具的 InputSchema 校验,工具定义取自 MCP 元数据快照,取不到就拒绝请求。提问:按问题的 schema 校验。校验失败返回 400。
+3. 记录仍为 `pending` 但持有者租约已过期(持有者已退出、回收任务尚未扫到)时,先按回收任务的规则把它转为 `suspended`(清空 `owner_instance`,并把消息改为等待输入),再走下面的 CAS,使这次回答直接恢复运行,而不是记给一个已经不存在的 waiter。
+4. 依次尝试两个 CAS,以区分之前的状态,同时兼容不支持 `RETURNING` 的场景:
+ - `UPDATE … SET status='answered', response=?, resolved_* WHERE id=? AND status='suspended' AND (expires_at IS NULL OR expires_at > now)`,同时生成新的 `owner_instance` 令牌并设置 `lease_until`,交给回答所在的副本。成功则由该副本恢复运行(5.4)。(P3 已实现)
+ - `UPDATE … WHERE id=? AND status='pending'`。成功则通过 Pub/Sub 唤醒持有者,不等待 ack,因为持有者会轮询数据库兜底。(P1 已实现)
+ - 两者都失败:重新读取记录,返回 `already_resolved`、`expired` 或 `not_found`。
+5. 响应体新增 `resumed: bool`。为 `true` 时,前端需要从偏移 0 重新接入该消息的事件流(旧事件已被清空)。(P3 已实现于 `POST /agent/tool-approvals/{id}`;MCP OAuth 回调不会挂起,忽略恢复结果。)
+
+原先基于 Pub/Sub ack 的跨实例投递已在 P1 移除,Pub/Sub 只保留唤醒职责。
+
+### 5.3 挂起并结束运行(持有者)
+
+引擎收到 `Suspend` 信号后(6.2)停止当前轮,跳过“合成最终答案”的路径,发出 `EventAgentComplete`,其中新增 `Suspended`(`*types.PromptSuspension`,含 `pending_id`、`kind`、`expires_at`)。
+
+`AgentStreamHandler.handleComplete` 在 `Suspended` 时:
+
+- 不设置 `IsCompleted`,改为设置 `RunState=awaiting_input`;已完成步骤、引用、用量照常写入。
+- 照常打沙箱检查点。
+- **不**收集产物(artifacts),不补发兜底答案,留到恢复后真正完成时再处理。
+- 消息落库成功后,向事件流发布 `run_suspended` 事件(带 `pending_id`、`kind`、`expires_at`),再发布 `complete`(`data.suspended` 同样带挂起信息),让当前 SSE 正常结束。
+
+外层 defer:
+
+- 落库只调用 `UpdateMessage`(`Updates` 会写入非空的 `run_state`),**不**写入聊天历史知识库、不生成追问建议、不记录长期记忆,这些留到恢复后完成时再做。
+- 处理 steer 队列:未消费的 `after` 类消息照常触发 `kickNextRunFromSteerBacklog`。新一轮启动时会按 8.1 取代这次审批,语义与“用户发了新消息”一致。未消费的 `inject` 类消息按 `after` 处理。下一轮清空 `Resume`,不重放上一轮快照。
+- `ClearLiveRun`。`liveAgentRun` 把 `awaiting_input` 的消息视为没有运行中的任务,残留的 live-run 标记会被清掉。
+
+### 5.4 恢复运行(回答所在的副本)
+
+最初计划用 asynq 任务 `agent:resume_run` 投递恢复。实现时改为由回答请求所在的副本在进程内直接恢复,用交互记录的租约代替任务去重:`Resolve` 的 CAS 成功时该副本就持有了租约,恢复期间持续续约;副本中途崩溃时租约过期,由回收任务收尾(5.6 第 2 条)。这样不依赖 Redis 队列,单机和多机行为一致。
+
+入口为 `session.Handler.ResumeSuspendedRun`,由 `MCPServiceHandler` 在 `resumed=true` 时调用,立即返回,运行在后台进行:
+
+1. `Broker.KeepLease` 按新的所有权令牌续约,直到运行结束或交互离开 answered / executing。先等待旧运行落库并释放 live-run 标记;旧持有者失联或其租约到期后,从持久快照恢复尚未落库的等待消息,再清理残留标记。
+2. 读取快照,确认属于该交互;从快照的 `Request` 解出 `ResumableAgentRequest`,恢复语言设置。
+3. 用回答请求的身份(已在 `Resolve` 中校验为会话所有者)读取会话和助手消息,消息必须仍是 `awaiting_input` 且未完成;用 `AgentID` 和 `AgentTenantID` 重新解析智能体(共享智能体按原工作区解析)。
+4. 把消息的 `run_state` 清空后再发布 live run:`liveAgentRun` 把 `awaiting_input` 视为空闲,不先清空的话恢复中的运行会被当成残留标记清掉。
+5. `StreamManager.ResetEvents` 清空该消息的事件列表(steer 列表保留)。恢复请求沿用原始 Query 和 RequestID,确保记忆、追问和历史分组保留本轮语义。
+6. 以 `skipSSE=true` 走 `executeQA`,和 steer 接力的服务端发起运行同一路径:会话互斥、沙箱 turn lease、`setupSSEStream`、完成落库都复用。`setupSSEStream` 在 `agent_query` 之后追加 `run_resumed`。`AgentQA` 看到 `QARequest.Resume` 时调用 `engine.Resume` 而不是 `Execute`。
+7. 运行结束后检查交互:仍是 `answered` 说明运行在执行工具之前就失败了(会话被占用、智能体加载失败等),此时把交互标记为 `failed`,并按 5.6 的方式收尾消息;否则按 `(assistant_message_id, prompt_id)` 条件删除快照。再次挂起时新快照属于新的交互,不会被删除。
+8. 第 2、3 步失败(快照缺失、智能体已删除、消息状态不符)时同样标记 `failed` 并收尾消息。
+
+`run_resumed` 只包含 `pending_id`。挂起前的步骤不重放,前端保留已经显示的部分,再追加恢复后的事件;完成事件里的 `agent_steps` 是完整列表。
+
+### 5.5 工具至多执行一次
+
+- 被阻塞的调用拿到回答时 CAS `answered → executing`(批准)或 `answered → done`(拒绝),工具执行结束后 `executing → done`。
+- 恢复运行的副本在 `executing` 期间失联:回收任务把交互标记为 `failed`,消息收尾时该调用写为“结果未知”,**不重放**工具。
+- 恢复失败(智能体不可用等,发生在执行工具之前):当场标记为 `failed` 并收尾,不重试。
+
+### 5.6 回收任务
+
+复用 housekeeping 的 cron 方式,每分钟执行一次。租约过期后的状态更新同时校验扫描时的所有权令牌和当前租约仍已过期,避免误回收扫描后续约或接管的运行:
+
+1. `status='pending' AND lease_until < now`:持有者已失联。可挂起且快照属于该交互时,CAS 为 `suspended`(写入 `expires_at`),用快照的 `DisplaySteps()` 覆盖消息的 `agent_steps` 并标记为 `awaiting_input`;否则 CAS 为 `expired`。快照在进入审批时已经写入,此处直接可用。(P2 已实现,由容器里每分钟一次的 `AgentPromptReaper` 执行;开关关闭时同样运行,用来关闭崩溃遗留的 pending 记录。)
+2. `status IN ('answered','executing') AND lease_until < now` 且快照仍属于该交互:恢复运行的副本已失联。CAS 为 `failed`,消息收尾为已完成,被阻塞的调用及之后的调用写为失败(`executing` 时说明结果未知),删除快照。短等待中回答的交互快照已被持有者删除,不受影响。
+3. `status='suspended' AND expires_at < now`:CAS 为 `expired`,消息收尾为已完成(不调用 LLM),被阻塞的调用及之后的调用写为“已过期”,删除快照。
+
+收尾由 `service.SuspendedRunService` 统一完成(回收任务、8.1 取代、恢复失败共用):步骤取 `RunSnapshot.ClosedSteps(reason)`,保证每个 tool_call 都有结果;`IsCompleted=true`、`run_state` 清空。`UpdateMessage` 单独写 `run_state` 列,因为 GORM 的 `Updates` 会跳过空字符串。正文不追加说明文字,原因写在失败的工具结果里。(P3 已实现第 2、3 条。)
+
+租约和过期时间由应用侧时钟写入和比较(Postgres 与 SQLite 的时间表达式不通用)。部署要求各副本通过 NTP 校时;30 秒租约配合 10 秒续约,足以容忍常见的秒级时钟偏差。
+
+## 6. 引擎改动
+
+### 6.1 跟踪进行中的一轮
+
+`AgentEngine` 新增 `roundProgress`,用互斥锁保护:
+
+- 在 `executeToolCalls` 之前登记本轮的 thought、reasoning 和完整的 `response.ToolCalls`。
+- 顺序路径和并行路径在每个调用完成时写入结果。并行路径中 MCP 调用是屏障,执行到它时,之前的调用都已经完成(`g.Wait()`),所以快照是确定的。
+- `snapshot(blockedIndex)` 生成 `RunSnapshot`;阻塞调用之前有未完成的调用时报错(此时不挂起)。参数本来就是解码后的形式(4.4)。
+
+`ToolExecContext` 新增两个字段:
+
+- `Snapshot func() ([]byte, int, error)`:返回编码后的快照和格式版本;运行不可挂起时为 nil。(P2)
+- `Answered *types.AgentPrompt`:恢复时传给被阻塞的那个调用(按 `tool_call_id` 匹配),即已回答的交互记录。发起交互的工具见到它就跳过等待,由各自的适配层把 `response` 解释为结果:`MCPTool.Execute` 仍执行开头的 `IsEnabled` 校验(管理员在此期间禁用了工具时以禁用为准),然后通过 `Gate.ResumeDecision` 得到审批决定并发出 `tool_approval_resolved`。即使工具此后不再需要审批,也按用户的决定执行,因为用户可能修改了参数。`ask_user` 直接把答案作为工具结果返回。(P3 已实现 MCP 部分。)
+
+能发起可挂起交互的工具都必须是并行执行中的屏障(MCP 工具已经是,`ask_user` 不进 `CanRunConcurrently` 白名单),这样一次运行同一时刻最多只有一个阻塞中的交互,快照才是确定的。
+
+### 6.2 挂起信号
+
+`types.ToolResult` 新增 `Suspend *types.PromptSuspension`(`json:"-"`)。
+
+- 顺序路径:调用返回 `Suspend` 后,后面的调用不再执行,被阻塞的调用不 append、不发 tool_result 事件,`executeToolCalls` 返回该挂起信息。
+- 并行路径:在屏障调用返回后检查标记,先按原顺序 append 并发出之前已完成的调用,再停止。
+- `runReActIteration` 收到后不把本轮 step 并入 `RoundSteps`、不再调用 LLM,记入 `state.Suspended` 与 `state.SuspendedStep` 后退出循环;`executeLoop` 跳过 `handleMaxIterations`。
+- `emitCompletionEvent` 在挂起时带 `RoundSteps` 加上被打断那一轮已完成的部分(`SuspendedStep`),供消息展示。
+
+### 6.3 恢复入口
+
+```go
+func (e *AgentEngine) Resume(
+ ctx context.Context,
+ sessionID, messageID string,
+ llmContext []chat.Message,
+ snapshot []byte,
+ answered *types.AgentPrompt,
+) (*types.AgentState, error)
+```
+
+快照以字节传入并在引擎内解码,`interfaces.AgentEngine` 因此不需要引用 `agent` 包。`answered.ToolCallID` 必须与快照中被阻塞的调用一致,否则拒绝恢复。
+
+1. 消息列表:system(重新计算)+ `llmContext` + `snap.UserTurn` + 由 `snap.CompletedSteps` 经 `appendToolResults` 展开的消息。
+2. 在完整消息列表上调用 `RememberMCPHistory`,恢复本轮已经 describe 或调用过的 MCP 工具,再 `RefreshMCPTools`。
+3. `state` 初始化:`RoundSteps = snap.CompletedSteps`、`CurrentRound = snap.CurrentRound`、`TurnUsage = snap.TurnUsage`。
+4. 完成被打断的那一轮:
+ - 已有结果的调用直接沿用。
+ - 被阻塞的调用以 `PreAnswered=answered` 执行。
+ - 之后的调用使用解码后的参数按原顺序**顺序**执行(剩余调用通常很少,顺序执行天然满足屏障规则)。其中的调用可能再次发起交互乃至再次挂起:此时直接发出带 `Suspended` 的完成事件并返回,按 5.3 处理。
+ - 发出与正常执行相同的 tool_call / tool_result 事件,然后 append step。
+5. 进入正常的 `executeLoop`,从下一轮开始。
+
+`executeLoop` 本身就接受初始状态和消息列表,`Resume` 直接调用它。
+
+## 7. 事件与接口变更
+
+| 变更 | 说明 |
+|---|---|
+| 新事件 `agent_prompt_required` / `agent_prompt_resolved` | 通用交互事件,`{pending_id, kind, request, tool_call_id, timeout_seconds, hot_wait_seconds, suspendable, requested_at}` / `{pending_id, kind, answered, response, reason, timed_out, canceled}`。目前只有 `ask_user` 使用;工具审批与 OAuth 仍只发各自的旧事件(P4.5 已实现) |
+| `tool_approval_required` 新增 `hot_wait_seconds`、`suspendable` | 前端倒计时归零时显示“已转入后台等待”,而不是“已超时” |
+| 新事件 `run_suspended` | `{pending_id, kind, expires_at}`,紧接着发 `complete` |
+| 新事件 `run_resumed` | `{pending_id}`,紧跟在恢复运行的 `agent_query` 之后(P3 已实现) |
+| `tool_approval_resolved` 新增 `superseded`、`expired` | |
+| 新接口 `POST /agent/prompts/{prompt_id}`(含嵌入页版本) | 请求体 `{kind, response}`,响应含 `resumed`;SDK 方法 `Client.ResolveAgentPrompt`(P4.5 已实现) |
+| `POST /agent/tool-approvals/{id}` 响应新增 `resumed` | 保留为兼容层;嵌入页接口同步 |
+| 消息列表接口:消息新增 `run_state`、`pending_prompt` | `pending_prompt` 只对会话所有者返回,包含卡片所需字段和 `expires_at` |
+| 新增 `StreamManager.ResetEvents` | Redis 实现为 `DEL` 事件列表;memory 实现为清空事件切片。两者都保留 steer 列表(P3 已实现) |
+
+API 文档、Swagger、`client/` SDK 同步更新(按 `weknora-api-docs-sync` 流程处理)。
+
+## 8. 会话级语义
+
+### 8.1 挂起期间用户发新消息
+
+`executeQA` 在 `rejectIfOtherAgentRunLive` 和回溯检查之后、`holdQATurn` 之前(恢复运行本身跳过这一步;steer 接力的新一轮同样会取代):
+
+1. 查找本会话 `status='suspended'` 的交互,CAS 为 `superseded`。
+2. 把对应消息收尾为已完成:被阻塞的调用及之后的调用结果写为“用户未回答就继续了对话”,补成一个完整的 step,正文不变,然后删除快照。(P3 已实现,见 `SuspendedRunService.SupersedeSession`。)
+3. 这样新一轮的 `LoadAgentHistory` 能看到完整、合规的上一轮(每个 tool_call 都有对应的 tool 结果)。
+
+前端提示语明确说明“发送新消息会放弃待处理的操作”。`ask_user` 例外:卡片上可直接作答;如果用户选择在输入框回复,按普通新消息处理(取代该提问),模型在新一轮的历史里能看到问题和新消息。
+
+### 8.2 用户停止
+
+- 短等待阶段:与现在一致,按 `canceled` 处理。
+- 挂起阶段:没有运行中的任务,界面不显示停止按钮;用户可直接点拒绝。
+
+### 8.3 回溯、分叉、删除
+
+- 回溯:`SessionRewindService.Rewind` 在校验会话归属之后、读取回溯点之前按 8.1 取代挂起,再执行原有逻辑。(P3 已实现)
+- 分叉:不取代。分叉只复制回溯点之前的消息,未完成的回溯点照旧被拒绝,源会话的挂起不受影响。
+- 删除消息或会话:不做专门处理。交互仍会在过期时被回收任务关闭;收尾时消息已不存在,只删除快照。
+
+## 9. 前端改动
+
+1. `handleMsgList`:消息 `run_state==='awaiting_input'` 时:
+ - 从 `agent_steps` 重建时间线,并在末尾追加由 `pending_prompt` 构造的交互卡片(按 `kind` 渲染);
+ - **不**调用 `continue-stream`,`isReplying=false`,输入框可用;
+ - 时间线不显示“进行中”的占位动画。
+2. 交互卡片按 `kind` 注册渲染组件(工具审批、OAuth 复用现有卡片,`ask_user` 为问题表单):
+ - 短等待阶段的倒计时归零后,文案改为“已转入后台等待,可稍后处理”,按钮仍然可用;
+ - 挂起阶段显示过期时间。
+3. 作答后,如果响应 `resumed=true`:设置 `isReplying=true`,对该消息调用 `continue-stream`。恢复任务的投递有延迟,404 时按 500ms 间隔重试,最多重试 10 次。从 `run_resumed` 事件开始追加到现有时间线,不替换已重建的步骤。
+4. `run_suspended`:结束当前流,卡片切换为挂起样式,`isReplying=false`。
+5. 挂起状态下发送新消息:先弹出确认提示,发送成功后刷新消息列表,旧卡片显示“已放弃”。
+6. 侧栏会话列表:可选显示“待处理”角标(第二期)。
+7. i18n:新增文案,按 `i18n-locale-align` 流程同步到全部语言。
+
+## 10. 配置
+
+| 配置项 | 默认值 | 说明 |
+|---|---|---|
+| `agent.prompt_suspend_enabled` | 未配置时为 `true`(P4 起) | 设为 `false` 恢复为纯阻塞式(仍写数据库记录);对所有可挂起类型生效。环境变量 `WEKNORA_AGENT_PROMPT_SUSPEND=true/false` 可覆盖 |
+| `agent.prompt_hot_wait_seconds` | `120` | 短等待时长;`0` 取默认值 |
+| `agent.prompt_expire_seconds` | `604800`(7 天) | 挂起后的过期时间;`0` 取默认值,负数表示不过期 |
+| `agent.tool_approval_timeout_seconds` | `600` | 保留;仅在关闭挂起时作为阻塞上限 |
+
+部署检查:进程无法自行判断是否有多个副本,因此只在启动时对 `STREAM_MANAGER_TYPE=memory` 且 `REDIS_ADDR` 非空的组合打警告。配了 Redis 通常意味着多副本部署,而这种组合下副本之间的事件流和 live-run 标记不共享。
+
+## 11. 安全
+
+- Resolve 按资源鉴权:路由中的会话与接口声明的类型必须与记录一致(不一致按不存在处理,防止跨会话或跨类型作答),租户、会话所有者都必须匹配;嵌入页额外校验 channel 与 session。
+- 回答必须通过该类型注册的校验函数,未注册的类型一律拒绝。
+- `pending_prompt` 与请求载荷只返回给会话所有者,与现有 SSE 可见范围一致。
+- `modified_args` 按 InputSchema 校验,校验通过后完整替换原参数,不保留旧键(与现有逻辑一致)。
+- `ask_user` 的答案是用户输入,交给模型时按不可信数据包裹(与工具结果同等对待),不拼进系统提示。
+- 恢复时重新校验:工具是否启用、是否仍需审批、智能体是否仍可访问、会话是否仍属于该用户。任何一项不满足都不执行工具。
+- 快照只存持久 ID 和已解码参数,不存凭据;MCP 凭据在执行时按现有方式解析。
+- 过期、取代、停止都会留下交互记录,满足审计需要。
+
+## 12. 内置提问工具 `ask_user`
+
+Agent 需要用户补充信息或做选择时调用,作为 P4 之后的单独一期。
+
+- 参数中的 options 必须是逐项列出的字符串数组。合法的数组字符串仍可兼容解析;以 `[` 开头却无法解析的字符串不再包装成单个选项,选项数组内嵌的序列化列表同样被拒绝,并返回工具参数错误供模型重试。
+- 参数:`question`(必填),可选 `options`(单选或多选)、`fields`(简单表单,限定为文本、数字、单选、多选几种类型),以及 `allow_free_text`。参数 schema 严格限定,字段数与选项数设上限,防止模型生成超大表单。
+- 执行:构造 `kind='ask_user'` 的交互,走 `Gate.AskUser` → `Broker.Await`;有快照时短等待后挂起,否则阻塞到超时。回答校验按本次的 `fields` / `options` 检查必填项、类型与取值范围,未知字段一律拒绝。用户也可以选择“不回答”(`{"declined": true}`)。
+- 结果:答案按“The user answered. / Selected / Fields / Text”格式作为工具结果返回给模型;用户拒绝、超时或被取代时,返回明确的“用户未回答(原因)”,由模型决定下一步。工具结果的 `data` 同时保存问题与答案,历史重建时据此把这次调用渲染成已作答的卡片,而不是一行工具调用。
+- 挂起与恢复:与工具审批相同,恢复时通过 `ToolExecContext.Answered` 直接返回答案。
+- 非交互渠道:只有 Web 与嵌入页的 HTTP 流式问答标记为可交互(`QARequest.Interactive` → `engine.SetInteractive`)。API Key 调用方无法访问作答接口,因此即使能挂起审批也不算可交互。IM、API Key 等渠道调用时,工具不发卡片,直接告诉模型“在本轮回复里直接提问并结束本轮”;用户的下一条消息就是答案。
+- 开关:加入 `DefaultAllowedTools` 与内置智能体(智能推理、数据分析师)的工具列表;智能体配置中可取消勾选。显式配置了 `allowed_tools` 的自定义智能体需手动加入。
+- 前端:`AskUserCard` 按选项(单选/多选)、表单字段、自由文本渲染;与审批卡片共用倒计时与“已转入后台等待”逻辑(`usePromptCountdown`)。等待输入的消息不折叠步骤,卡片始终可见。
+
+## 13. 分期实施
+
+| 期 | 内容 | 对外行为变化 |
+|---|---|---|
+| P1 | 两张新表与 `messages.run_state` 迁移(Postgres 000119、SQLite 000037);通用核心 `hitl.Broker`(持久化、租约、轮询兜底、Pub/Sub 唤醒、按 kind 校验回答);工具审批与 OAuth 改为其上的适配层;Resolve 绑定 session 与 kind | 无,仍是阻塞式 |
+| P2(已实现) | 引擎 `roundProgress`、快照、`Suspend` 信号;handler 挂起收尾;`run_suspended` 事件;回收任务第 1 条 | 超过短等待后挂起,但暂时无法恢复(功能开关默认关闭) |
+| P3(已实现) | `engine.Resume`、进程内恢复与租约、`ResetEvents`、`run_resumed`;8.1 新消息与回溯取代;回收任务第 2、3 条;`SuspendedRunService` 统一收尾 | 后端功能完整(功能开关默认关闭,前端未适配) |
+| P4(已实现) | 功能开关默认打开;消息列表为 `awaiting_input` 消息附带 `pending_prompt`(只对发起人可见,含卡片字段与 `expires_at`);前端处理 `run_suspended` / `run_resumed`,挂起卡片显示“已转入后台等待”与截止时间,回答返回 `resumed: true` 后 Web 端经 continue-stream 重新接上同一条消息(短暂重试等待恢复流出现),嵌入页无 continue-stream,改为轮询消息列表、结束后重新加载;发送新消息时挂起卡片显示“已放弃”;i18n | 工具审批可长时间挂起并在任意副本恢复 |
+| P4.5(部分实现) | 已实现:`ask_user` 内置工具(第 12 节)及其表单卡片;通用接口 `POST /agent/prompts/{prompt_id}`(含嵌入页)与 SDK 方法。未实现:MCP OAuth 接入挂起(OAuth 仍只做阻塞等待) | Agent 可以向用户提问 |
+| P5 | 文档、Swagger 产物重新生成(当前主干的 Swagger 产物已落后较多,单独提交) | |
+
+## 14. 测试要点
+
+- 通用核心(P1 已覆盖):跨副本作答经数据库送达持有者;会话、类型、租户、用户绑定;未注册类型被拒;回答校验失败;回答与超时同时发生时回答胜出;超时与取消留下记录;`executing → done`。
+- 状态机:每条 CAS 转换的成功与失败分支,包括并发 Resolve、Resolve 与短等待超时同时发生、Resolve 与用户停止同时发生。
+- 快照:顺序路径和并行路径下,阻塞调用位于一轮的开头、中间、末尾;未执行调用含临时句柄时,恢复后参数正确。
+- 恢复:恢复后发给 LLM 的消息序列与未挂起时逐条一致(以 golden 测试固定);恢复中再次挂起;恢复时工具已被禁用;恢复时智能体已被删除。
+- 至多执行一次:在 `executing` 阶段模拟崩溃,重试时不重放。
+- 多副本:两个 Gate 实例共用一个数据库和 Redis,Resolve 打到非持有者;持有者在短等待阶段消失后,由回收任务转为挂起,再恢复。
+- 会话语义:挂起时发新消息、回溯、删除会话;历史重建结果合规。
+- 前端:刷新后卡片正确显示;批准后接入事件流;`run_suspended` / `run_resumed` 的渲染。
+
+## 15. 已确认的决定
+
+1. 短等待默认 120 秒,挂起后默认 7 天过期。
+2. 过期后不调用 LLM,直接收尾并附一行说明。
+3. 本期只对 Web、嵌入页、API 渠道开放挂起;IM 渠道(`Channel` 为 IM 类)保持阻塞式,不进入挂起分支(`ask_user` 在 IM 渠道的降级见第 12 节)。
+4. 挂起时 steer 队列里的消息按“新消息取代待处理的交互”处理。
+5. P1 直接做成通用的人工交互模型(`agent_prompts` + `hitl.Broker`),工具审批与 OAuth 是其上的适配层。
+6. `ask_user` 放进本次范围,作为前端一期之后的单独一期。
diff --git a/frontend/src/api/embed/index.ts b/frontend/src/api/embed/index.ts
index d0f9c038e..5afd9e7d8 100644
--- a/frontend/src/api/embed/index.ts
+++ b/frontend/src/api/embed/index.ts
@@ -407,12 +407,31 @@ export async function resolveEmbedToolApproval(
visitorId: string,
pendingId: string,
body: { decision: 'approve' | 'reject'; modified_args?: Record<string, unknown>; reason?: string },
-): Promise<void> {
- await post(
+): Promise<{ resumed: boolean }> {
+ const res: any = await post(
`/api/v1/embed/${channelId}/sessions/${encodeURIComponent(sessionId)}/tool-approvals/${encodeURIComponent(pendingId)}`,
body,
{ headers: embedSessionHeaders(token, sessionSig, visitorId) },
)
+ return { resumed: Boolean(res?.resumed) }
+}
+
+export async function resolveEmbedAgentPrompt(
+ channelId: string,
+ token: string,
+ sessionId: string,
+ sessionSig: string,
+ visitorId: string,
+ promptId: string,
+ kind: string,
+ response: Record<string, unknown>,
+): Promise<{ resumed: boolean }> {
+ const res: any = await post(
+ `/api/v1/embed/${channelId}/sessions/${encodeURIComponent(sessionId)}/prompts/${encodeURIComponent(promptId)}`,
+ { kind, response },
+ { headers: embedSessionHeaders(token, sessionSig, visitorId) },
+ )
+ return { resumed: Boolean(res?.resumed) }
}
export async function getEmbedMessageList(
diff --git a/frontend/src/api/mcp-service.ts b/frontend/src/api/mcp-service.ts
index 2dd758419..7383c5438 100644
--- a/frontend/src/api/mcp-service.ts
+++ b/frontend/src/api/mcp-service.ts
@@ -292,8 +292,22 @@ export async function revokeMCPOAuthToken(serviceId: string): Promise<void> {
export async function resolveToolApproval(
pendingId: string,
body: { decision: 'approve' | 'reject'; modified_args?: Record<string, unknown>; reason?: string }
-): Promise<void> {
- await post(`/api/v1/agent/tool-approvals/${encodeURIComponent(pendingId)}`, body)
+): Promise<{ resumed: boolean }> {
+ const res: any = await post(`/api/v1/agent/tool-approvals/${encodeURIComponent(pendingId)}`, body)
+ // resumed: the run had been suspended and now continues on the server;
+ // the client must re-attach to the message's stream.
+ return { resumed: Boolean(res?.resumed) }
+}
+
+// Answer a prompt the agent raised (ask_user, tool approval) with the kind's
+// response object.
+export async function resolveAgentPrompt(
+ promptId: string,
+ kind: string,
+ response: Record<string, unknown>,
+): Promise<{ resumed: boolean }> {
+ const res: any = await post(`/api/v1/agent/prompts/${encodeURIComponent(promptId)}`, { kind, response })
+ return { resumed: Boolean(res?.resumed) }
}
// Resume an agent run that paused on an in-conversation MCP OAuth prompt.
diff --git a/frontend/src/composables/useChatStreamHandler.suspend.test.ts b/frontend/src/composables/useChatStreamHandler.suspend.test.ts
new file mode 100644
index 000000000..c5ee57f83
--- /dev/null
+++ b/frontend/src/composables/useChatStreamHandler.suspend.test.ts
@@ -0,0 +1,201 @@
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import test from 'node:test'
+import vm from 'node:vm'
+import ts from 'typescript'
+import * as vue from 'vue'
+import * as finalContent from '../utils/finalArtifactContent.ts'
+import * as history from '../utils/rag-pipeline-history.ts'
+import * as timestamps from '../utils/messageTimestamp.ts'
+import * as steering from '../utils/steerStreamFork.ts'
+import type { useChatStreamHandler as StreamHandler } from './useChatStreamHandler.ts'
+
+const source = readFileSync(new URL('./useChatStreamHandler.ts', import.meta.url), 'utf8')
+const compiled = ts.transpileModule(source, {
+ compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 },
+}).outputText
+const modules: Record<string, unknown> = {
+ vue, 'vue-i18n': { useI18n: () => ({ t: (key: string) => key }) },
+ '@/utils/finalArtifactContent': finalContent,
+ '@/utils/rag-pipeline-history': history,
+ '@/utils/messageTimestamp': timestamps,
+ '@/utils/steerStreamFork': steering,
+}
+const exports: { useChatStreamHandler?: typeof StreamHandler } = {}
+vm.runInNewContext(compiled, {
+ exports, console,
+ require: (id: string) => {
+ assert.ok(id in modules, `unexpected import ${id}`)
+ return modules[id]
+ },
+})
+const useChatStreamHandler = exports.useChatStreamHandler!
+
+function setup() {
+ const messagesList = vue.reactive<Record<string, any>[]>([])
+ const loading = vue.ref(false), isReplying = vue.ref(false)
+ const currentAssistantMessageId = vue.ref(''), fullContent = vue.ref('')
+ const turns: unknown[] = []
+ const handler = useChatStreamHandler({
+ messagesList, loading, isReplying, currentAssistantMessageId, fullContent,
+ isAgentStreamSession: () => true, scrollToBottom() {},
+ onTurnComplete: (m) => turns.push(m),
+ preserveIncompleteStreamReactive: true,
+ })
+ return { handler, messagesList, isReplying, currentAssistantMessageId, turns }
+}
+
+const awaitingRow = () => ({
+ id: 'a1', request_id: 'r1', role: 'assistant', content: '', is_completed: false,
+ run_state: 'awaiting_input', agent_duration_ms: 1200,
+ agent_steps: [{ iteration: 0, thought: 'checking', tool_calls: [{ id: 'call-1', name: 'mcp_x', args: {} }] }],
+ pending_prompt: {
+ id: 'p1', kind: 'tool_approval', tool_call_id: 'call-1', created_at: '2026-10-13T08:00:00Z',
+ expires_at: '2026-10-20T08:00:00Z',
+ request: { service_name: 'svc', mcp_tool_name: 'delete', args: { id: 7 } },
+ },
+})
+
+const cards = (m: Record<string, any>) =>
+ (m.agentEventStream as Record<string, any>[]).filter((e) => e.type === 'tool_approval_required')
+
+test('history renders a suspended message as settled with its pending card', async () => {
+ const { handler, messagesList } = setup()
+ await handler.handleMsgList([awaitingRow()])
+ const m = messagesList[0]
+ assert.equal(m.is_completed, true)
+ const stream = m.agentEventStream as Record<string, any>[]
+ assert.ok(!stream.some((e) => e.type === 'stop' || e.type === 'agent_complete'))
+ const [card] = cards(m)
+ assert.equal(card.pending_id, 'p1')
+ assert.equal(card.suspended, true)
+ assert.equal(card.args_json, '{"id":7}')
+ assert.equal(card.requested_at, Date.parse('2026-10-13T08:00:00Z') / 1000)
+})
+
+test('a live run that suspends parks its card and ends without completion', () => {
+ const { handler, messagesList, isReplying, turns } = setup()
+ isReplying.value = true
+ handler.processStreamChunk({ response_type: 'agent_query', id: 'r1', assistant_message_id: 'a1' })
+ handler.processStreamChunk({
+ response_type: 'tool_approval_required', id: 'r1',
+ data: { pending_id: 'p1', tool_call_id: 'call-1', suspendable: true, hot_wait_seconds: 120 },
+ })
+ handler.processStreamChunk({
+ response_type: 'run_suspended', id: 'r1', data: { pending_id: 'p1', expires_at: '2026-10-20T08:00:00Z' },
+ })
+ handler.processStreamChunk({ response_type: 'complete', id: 'r1', data: { total_duration_ms: 5 } })
+ const m = messagesList[0]
+ const [card] = cards(m)
+ assert.equal(card.suspendable, true)
+ assert.equal(card.hot_wait_seconds, 120)
+ assert.equal(card.suspended, true)
+ assert.equal(m.run_state, 'awaiting_input')
+ assert.equal(isReplying.value, false)
+ assert.ok(!(m.agentEventStream as Record<string, any>[]).some((e) => e.type === 'agent_complete'))
+ assert.equal(turns.length, 1)
+})
+
+test('a resumed run streams into the suspended message', async () => {
+ const { handler, messagesList, currentAssistantMessageId } = setup()
+ await handler.handleMsgList([awaitingRow()])
+ const m = messagesList[0]
+ handler.prepareResumedMessage(m, 'p1')
+ assert.equal(m.is_completed, false)
+ assert.equal(m.run_state, '')
+ assert.ok(!(m.agentEventStream as Record<string, any>[]).some(
+ (e) => e.type === 'tool_call' && e.tool_call_id === 'call-1',
+ ))
+ currentAssistantMessageId.value = 'a1'
+ handler.processStreamChunk({ response_type: 'agent_query', id: 'r2', assistant_message_id: 'a1' })
+ handler.processStreamChunk({ response_type: 'run_resumed', id: 'r2', data: { pending_id: 'p1' } })
+ handler.processStreamChunk({
+ response_type: 'tool_approval_resolved', id: 'r2', data: { pending_id: 'p1', approved: true },
+ })
+ handler.processStreamChunk({ response_type: 'complete', id: 'r2', data: { total_duration_ms: 9 } })
+ assert.equal(messagesList.length, 1)
+ const [card] = cards(m)
+ assert.equal(card.resolved, true)
+ assert.equal(card.approved, true)
+ assert.equal(m.is_completed, true)
+ assert.ok((m.agentEventStream as Record<string, any>[]).some((e) => e.type === 'agent_complete'))
+})
+
+test('a new message abandons the prompt a suspended run waits on', async () => {
+ const { handler, messagesList } = setup()
+ await handler.handleMsgList([awaitingRow()])
+ handler.prepareForNewOutgoingMessage()
+ const m = messagesList[0]
+ const [card] = cards(m)
+ assert.equal(card.resolved, true)
+ assert.equal(card.abandoned, true)
+ assert.equal(m.run_state, '')
+})
+
+const prompts = (m: Record<string, any>) =>
+ (m.agentEventStream as Record<string, any>[]).filter((e) => e.type === 'agent_prompt_required')
+
+test('a question card follows the prompt events of a live run', () => {
+ const { handler, messagesList } = setup()
+ handler.processStreamChunk({ response_type: 'agent_query', id: 'r1', assistant_message_id: 'a1' })
+ handler.processStreamChunk({
+ response_type: 'agent_prompt_required', id: 'r1',
+ data: { pending_id: 'q1', kind: 'ask_user', tool_call_id: 'call-2', request: { question: 'Which?' } },
+ })
+ handler.processStreamChunk({
+ response_type: 'agent_prompt_resolved', id: 'r1',
+ data: { pending_id: 'q1', kind: 'ask_user', answered: true, response: { text: 'this one' } },
+ })
+ const [card] = prompts(messagesList[0])
+ assert.equal(card.kind, 'ask_user')
+ assert.equal(card.request.question, 'Which?')
+ assert.equal(card.resolved, true)
+ assert.equal(card.answered, true)
+ assert.deepEqual(card.response, { text: 'this one' })
+})
+
+test('history shows a pending question and turns answered ones into cards', async () => {
+ const { handler, messagesList } = setup()
+ const row = awaitingRow()
+ row.agent_steps = [{
+ iteration: 0, thought: '',
+ tool_calls: [
+ { id: 'call-0', name: 'ask_user', args: {}, result: { success: true, output: 'x', data: {
+ display_type: 'ask_user', question: { question: 'First?' }, answered: false,
+ reason: 'the user declined to answer',
+ } } },
+ { id: 'call-1', name: 'ask_user', args: {} },
+ ],
+ }] as any
+ row.pending_prompt = {
+ id: 'q2', kind: 'ask_user', tool_call_id: 'call-1', created_at: '2026-10-13T08:00:00Z',
+ expires_at: '2026-10-20T08:00:00Z', request: { question: 'Second?' },
+ } as any
+ await handler.handleMsgList([row])
+ const m = messagesList[0]
+ const [answered, pending] = prompts(m)
+ assert.equal(answered.request.question, 'First?')
+ assert.equal(answered.resolved, true)
+ assert.equal(answered.answered, false)
+ assert.equal(answered.resolve_reason, 'the user declined to answer')
+ assert.ok(!(m.agentEventStream as Record<string, any>[]).some(
+ (e) => e.type === 'tool_call' && e.tool_call_id === 'call-0',
+ ))
+ assert.equal(pending.pending_id, 'q2')
+ assert.equal(pending.suspended, true)
+ assert.equal(pending.request.question, 'Second?')
+ handler.prepareForNewOutgoingMessage()
+ assert.equal(prompts(m)[1].abandoned, true)
+})
+
+test('a prompt without display steps remains answerable after orphan recovery', async () => {
+ const { handler, messagesList } = setup()
+ const row = awaitingRow()
+ row.agent_steps = []
+ await handler.handleMsgList([row])
+ const message = messagesList[0]
+ assert.equal(message.isAgentMode, true)
+ assert.equal(message.is_completed, true)
+ assert.equal(cards(message).length, 1)
+ assert.equal(cards(message)[0].pending_id, 'p1')
+})
diff --git a/frontend/src/composables/useChatStreamHandler.ts b/frontend/src/composables/useChatStreamHandler.ts
index d5c6e1840..46fe7ecd0 100644
--- a/frontend/src/composables/useChatStreamHandler.ts
+++ b/frontend/src/composables/useChatStreamHandler.ts
@@ -50,6 +50,74 @@ function mergeToolCallArguments(previous: unknown, incoming: unknown): Record<st
return { ...prev, ...next }
}
+const AWAITING_INPUT = 'awaiting_input'
+
+const PROMPT_CARD_TYPES = new Set(['tool_approval_required', 'agent_prompt_required'])
+
+/** Whether e is the card of a prompt the user answers (approval, question). */
+export function isPromptCard(e: ChatMessage | undefined): boolean {
+ return PROMPT_CARD_TYPES.has(String(e?.type || ''))
+}
+
+export function isAwaitingInput(message: ChatMessage | undefined): boolean {
+ return message?.run_state === AWAITING_INPUT
+}
+
+/** Rebuilds the card of the prompt a suspended run waits on, from history. */
+export function pendingPromptEvents(prompt: unknown): ChatMessage[] {
+ const p = prompt as Record<string, any> | undefined
+ if (!p?.id) return []
+ const request = (p.request || {}) as Record<string, any>
+ const createdAt = Date.parse(String(p.created_at || ''))
+ const requestedAt = Number.isNaN(createdAt) ? undefined : Math.floor(createdAt / 1000)
+ if (p.kind === 'ask_user') {
+ return [{
+ type: 'agent_prompt_required',
+ pending_id: p.id,
+ kind: p.kind,
+ request,
+ tool_call_id: p.tool_call_id,
+ requested_at: requestedAt,
+ suspendable: true,
+ suspended: true,
+ expires_at: p.expires_at,
+ resolved: false,
+ }]
+ }
+ if (p.kind !== 'tool_approval') return []
+ return [{
+ type: 'tool_approval_required',
+ pending_id: p.id,
+ service_name: request.service_name,
+ mcp_tool_name: request.mcp_tool_name,
+ description: request.description,
+ args_json: request.args === undefined ? '' : JSON.stringify(request.args),
+ tool_call_id: p.tool_call_id,
+ requested_at: requestedAt,
+ suspendable: true,
+ suspended: true,
+ expires_at: p.expires_at,
+ resolved: false,
+ }]
+}
+
+/** The card of an ask_user call that finished, from the stored tool result. */
+function askUserHistoryCard(toolCallId: string, data: ChatMessage): ChatMessage {
+ return {
+ type: 'agent_prompt_required',
+ pending_id: `history-${toolCallId}`,
+ kind: 'ask_user',
+ request: data.question,
+ tool_call_id: toolCallId,
+ resolved: true,
+ answered: Boolean(data.answered),
+ response: data.answer,
+ resolve_reason: data.reason,
+ timed_out: Boolean(data.timed_out),
+ canceled: Boolean(data.canceled),
+ }
+}
+
export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
const { t } = useI18n()
const {
@@ -130,11 +198,21 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
if (msg.role === 'assistant' && !msg.is_completed) {
markAssistantStopped(msg)
}
+ if (msg.role === 'assistant' && isAwaitingInput(msg)) abandonPendingPrompts(msg)
}
fullContent.value = ''
currentAssistantMessageId.value = ''
}
+ /** A new message supersedes the prompt a suspended run waits on. */
+ const abandonPendingPrompts = (msg: ChatMessage) => {
+ const stream = (msg.agentEventStream as ChatMessage[] | undefined) || []
+ msg.agentEventStream = stream.map((e) =>
+ isPromptCard(e) && !e.resolved ? { ...e, resolved: true, abandoned: true } : e,
+ )
+ msg.run_state = ''
+ }
+
/** Mark the assistant row being stopped without clearing its id (stop API still needs it). */
const markInFlightAssistantStopped = (messageId?: string) => {
let target: ChatMessage | undefined
@@ -376,6 +454,10 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
const result = toolCall.result as ChatMessage | undefined
const resultData = result?.data as ChatMessage | undefined
const target = toolCall.target as ChatMessage | undefined
+ if (resultData?.display_type === 'ask_user') {
+ events.push(askUserHistoryCard(String(toolCall.id || ''), resultData))
+ return
+ }
events.push({
type: 'tool_call',
tool_call_id: toolCall.id,
@@ -428,6 +510,26 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
return events
}
+ /**
+ * Readies a suspended message to stream again after its prompt was answered
+ * and the server resumed the run. The resumed stream carries only new events,
+ * so the timeline built from history stays and the blocked tool call is
+ * dropped: the resumed run reports it afresh.
+ */
+ const prepareResumedMessage = (message: ChatMessage, pendingId: string) => {
+ const stream = (message.agentEventStream as ChatMessage[] | undefined) || []
+ const card = stream.find((e) => isPromptCard(e) && e.pending_id === pendingId)
+ const blockedCall = card?.tool_call_id
+ message.agentEventStream = stream.filter((e) => {
+ if (e.type === 'agent_complete' || e.type === 'stop') return false
+ return !(blockedCall && e.type === 'tool_call' && e.tool_call_id === blockedCall)
+ })
+ message._eventMap = new Map()
+ message._pendingToolCalls = new Map()
+ message.run_state = ''
+ message.is_completed = false
+ }
+
const handleMsgList = async (
data: ChatMessage[],
isScrollType = false,
@@ -443,6 +545,9 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
if (item.id) existingIds.add(item.id)
item.isAgentMode = false
+ // A run awaiting input has ended for now: nothing streams until its
+ // prompt is answered, so it renders as settled.
+ const awaiting = isAwaitingInput(item)
const willContinueStream = preserveIncompleteStreamReactive && !item.is_completed
if (willContinueStream) {
item.agentEventStream = item.agentEventStream || []
@@ -471,6 +576,16 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
if (agentStepsAreTruncated(item.agent_steps as unknown[])) item.truncated = true
}
+ if (awaiting) {
+ item.isAgentMode = true
+ item.hideContent = true
+ item.agentEventStream = markRaw(
+ (item.agentEventStream as ChatMessage[])
+ .filter((e) => e.type !== 'agent_complete')
+ .concat(pendingPromptEvents(item.pending_prompt)),
+ )
+ item.is_completed = true
+ }
restoreQuickAnswerFlags(item)
if (item.content) {
@@ -601,7 +716,8 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
(data.response_type === 'thinking' ||
data.response_type === 'answer' ||
data.response_type === 'tool_call' ||
- data.response_type === 'tool_approval_required')
+ data.response_type === 'tool_approval_required' ||
+ data.response_type === 'agent_prompt_required')
) {
log('[Agent Chunk] Closing loading for continued stream')
loading.value = false
@@ -689,12 +805,64 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
description: d.description,
args_json: d.args_json,
timeout_seconds: d.timeout_seconds,
+ hot_wait_seconds: d.hot_wait_seconds,
+ suspendable: d.suspendable,
+ requested_at: d.requested_at,
+ tool_call_id: d.tool_call_id,
+ resolved: false,
+ })
+ break
+ }
+ case 'agent_prompt_required': {
+ if (!message.agentEventStream) message.agentEventStream = []
+ const d = dataPayload || {}
+ ;(message.agentEventStream as ChatMessage[]).push({
+ type: 'agent_prompt_required',
+ pending_id: d.pending_id,
+ kind: d.kind,
+ request: d.request,
+ timeout_seconds: d.timeout_seconds,
+ hot_wait_seconds: d.hot_wait_seconds,
+ suspendable: d.suspendable,
requested_at: d.requested_at,
tool_call_id: d.tool_call_id,
resolved: false,
})
break
}
+ case 'agent_prompt_resolved': {
+ const d = dataPayload || {}
+ const ev = (message.agentEventStream as ChatMessage[] | undefined)?.find(
+ (e) => e.type === 'agent_prompt_required' && e.pending_id === d.pending_id,
+ )
+ if (ev) {
+ ev.resolved = true
+ ev.answered = d.answered
+ ev.response = d.response
+ ev.resolve_reason = d.reason
+ ev.timed_out = d.timed_out
+ ev.canceled = d.canceled
+ }
+ break
+ }
+ case 'run_suspended': {
+ // The run ended waiting on this prompt; answering it resumes the run.
+ const d = dataPayload || {}
+ const card = (message.agentEventStream as ChatMessage[] | undefined)?.find(
+ (e) => isPromptCard(e) && e.pending_id === d.pending_id,
+ )
+ if (card) {
+ card.suspended = true
+ card.expires_at = d.expires_at
+ }
+ message.run_state = AWAITING_INPUT
+ break
+ }
+ case 'run_resumed': {
+ message.run_state = ''
+ message.is_completed = false
+ break
+ }
case 'tool_approval_resolved': {
const d = dataPayload || {}
const pid = d.pending_id
@@ -1046,7 +1214,7 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
if (usage) {
message.usage = usage
}
- if (message.agentEventStream) {
+ if (message.agentEventStream && !isAwaitingInput(message)) {
;(message.agentEventStream as ChatMessage[]).push({
type: 'agent_complete',
total_duration_ms: dataPayload?.total_duration_ms || 0,
@@ -1138,7 +1306,9 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
let existingMessage = replay || findLastMessage(
(item) =>
item.role === 'assistant' &&
- (item.id === data.id || item.request_id === data.id),
+ (item.id === data.id ||
+ item.request_id === data.id ||
+ (!!data.assistant_message_id && item.id === data.assistant_message_id)),
)
const created = !existingMessage
if (!existingMessage) {
@@ -1187,7 +1357,11 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
data.response_type === 'reflection' ||
data.response_type === 'artifacts_pending' ||
data.response_type === 'context_compacted' ||
- data.response_type === 'user_message_injected'
+ data.response_type === 'user_message_injected' ||
+ data.response_type === 'run_suspended' ||
+ data.response_type === 'run_resumed' ||
+ data.response_type === 'agent_prompt_required' ||
+ data.response_type === 'agent_prompt_resolved'
const activeAssistant = getTrailingIncompleteAssistant()
const isCurrentlyAgentMode = activeAssistant?.isAgentMode === true
@@ -1334,6 +1508,7 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
handleMsgList,
processStreamChunk,
prepareForNewOutgoingMessage,
+ prepareResumedMessage,
markInFlightAssistantStopped,
}
}
diff --git a/frontend/src/composables/useEmbedChatSession.ts b/frontend/src/composables/useEmbedChatSession.ts
index 552991de2..5876cbffc 100644
--- a/frontend/src/composables/useEmbedChatSession.ts
+++ b/frontend/src/composables/useEmbedChatSession.ts
@@ -5,6 +5,7 @@ import {
nextTick,
onMounted,
onUnmounted,
+ provide,
type Ref,
} from 'vue'
import { useStream } from '@/api/chat/streame'
@@ -19,7 +20,8 @@ import { embedToast } from '@/utils/embedToast'
import { buildQueryWithHostContext } from '@/utils/embedContext'
import { fileToDataURI } from '@/utils/embedFile'
import { useI18n } from 'vue-i18n'
-import { useChatStreamHandler } from '@/composables/useChatStreamHandler'
+import { useChatStreamHandler, isPromptCard } from '@/composables/useChatStreamHandler'
+import { resumeSuspendedRunKey } from '@/utils/suspendedRun'
import { useStickyBottomOnResize } from '@/composables/useStickyBottomOnResize'
export function useEmbedChatSession(options: {
@@ -123,6 +125,7 @@ export function useEmbedChatSession(options: {
handleMsgList,
processStreamChunk,
prepareForNewOutgoingMessage,
+ prepareResumedMessage,
markInFlightAssistantStopped,
} = useChatStreamHandler({
messagesList,
@@ -328,6 +331,44 @@ export function useEmbedChatSession(options: {
})
}
+ // Embed has no stream to re-attach to, so a resumed run is followed by
+ // polling history until its message settles, then reloading it.
+ let resumePoll: ReturnType<typeof setTimeout> | null = null
+ const stopResumePoll = () => {
+ if (resumePoll) clearTimeout(resumePoll)
+ resumePoll = null
+ }
+ const followResumedRun = (pendingId: string) => {
+ const sid = options.sessionId.value
+ const message = messagesList.find((m) => m.role === 'assistant' && ((m.agentEventStream as Record<string, unknown>[] | undefined) || []).some(
+ (e) => isPromptCard(e) && e.pending_id === pendingId,
+ ))
+ const messageId = String(message?.id || '')
+ if (!message || !sid || !messageId || isReplying.value) return
+ prepareResumedMessage(message, pendingId)
+ isReplying.value = true
+ stopResumePoll()
+ const deadline = Date.now() + 30 * 60 * 1000
+ const poll = async () => {
+ if (options.sessionId.value !== sid) return
+ try {
+ const res = await getEmbedMessageList(
+ options.channelId, options.token, sid, limit.value, undefined, options.sessionSig.value,
+ )
+ const latest = (res?.data as Record<string, unknown>[] | undefined)?.find((m) => m.id === messageId)
+ if (!latest || latest.is_completed || latest.run_state === 'awaiting_input' || Date.now() > deadline) {
+ resetAndLoad(sid)
+ return
+ }
+ } catch (err) {
+ console.error('Failed to poll resumed run:', err)
+ }
+ resumePoll = setTimeout(poll, 2000)
+ }
+ resumePoll = setTimeout(poll, 1000)
+ }
+ provide(resumeSuspendedRunKey, followResumedRun)
+
watch(error, (newError) => {
if (newError) {
embedToast(newError)
@@ -349,6 +390,7 @@ export function useEmbedChatSession(options: {
})
const resetAndLoad = (sid: string) => {
+ stopResumePoll()
messagesList.splice(0)
historyLoading.value = true
historyLoadingMore.value = false
@@ -379,6 +421,7 @@ export function useEmbedChatSession(options: {
})
onUnmounted(() => {
+ stopResumePoll()
stopStream()
fullContent.value = ''
})
diff --git a/frontend/src/composables/usePromptCountdown.ts b/frontend/src/composables/usePromptCountdown.ts
new file mode 100644
index 000000000..589e38fa2
--- /dev/null
+++ b/frontend/src/composables/usePromptCountdown.ts
@@ -0,0 +1,65 @@
+import { computed, onBeforeUnmount, onMounted, ref } from 'vue'
+import { useI18n } from 'vue-i18n'
+
+export interface PromptTiming {
+ requestedAt?: number
+ timeoutSeconds?: number
+ hotWaitSeconds?: number
+ suspendable?: boolean
+ suspended?: boolean
+ expiresAt?: string
+ resolved?: boolean
+}
+
+/**
+ * Countdown of a prompt card. A suspendable prompt counts down its hot wait;
+ * past it (or once suspended) it is parked: the run no longer waits in
+ * memory, and answering later resumes it until expiresAt.
+ */
+export function usePromptCountdown(props: PromptTiming) {
+ const { t, locale } = useI18n()
+ const now = ref(Date.now())
+ let timer: ReturnType<typeof setInterval> | null = null
+ onMounted(() => {
+ timer = setInterval(() => { now.value = Date.now() }, 1000)
+ })
+ onBeforeUnmount(() => {
+ if (timer) clearInterval(timer)
+ })
+
+ const deadline = computed(() => {
+ const base = (props.requestedAt || 0) * 1000
+ const wait = props.suspendable ? props.hotWaitSeconds || props.timeoutSeconds : props.timeoutSeconds
+ return base + (wait || 600) * 1000
+ })
+
+ const parked = computed(() => Boolean(props.suspended || (props.suspendable && now.value >= deadline.value)))
+
+ const secondsLeft = computed(() => {
+ if (props.resolved) return -1
+ return Math.max(0, Math.floor((deadline.value - now.value) / 1000))
+ })
+
+ const timerClass = computed(() => {
+ if (secondsLeft.value <= 30) return 'timer-critical'
+ if (secondsLeft.value <= 120) return 'timer-warning'
+ return ''
+ })
+
+ const countdownText = computed(() => {
+ const s = secondsLeft.value
+ if (s < 60) return t('agentStream.toolApproval.countdownShort', { seconds: s })
+ return `${Math.floor(s / 60)}:${(s % 60).toString().padStart(2, '0')}`
+ })
+
+ const parkedText = computed(() => {
+ const expires = props.expiresAt ? new Date(props.expiresAt) : null
+ if (!expires || Number.isNaN(expires.getTime())) return t('agentStream.toolApproval.parked')
+ const time = expires.toLocaleString(locale.value, {
+ month: 'numeric', day: 'numeric', hour: '2-digit', minute: '2-digit',
+ })
+ return t('agentStream.toolApproval.parkedUntil', { time })
+ })
+
+ return { parked, secondsLeft, timerClass, countdownText, parkedText }
+}
diff --git a/frontend/src/composables/usePromptDock.test.mjs b/frontend/src/composables/usePromptDock.test.mjs
new file mode 100644
index 000000000..0d1da193f
--- /dev/null
+++ b/frontend/src/composables/usePromptDock.test.mjs
@@ -0,0 +1,178 @@
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import test from 'node:test'
+import vm from 'node:vm'
+import ts from 'typescript'
+import * as vue from 'vue'
+import { isSubmitKey, optionIndexForKey, optionKey } from '../utils/promptKeys.ts'
+
+const source = readFileSync(new URL('./usePromptDock.ts', import.meta.url), 'utf8')
+const compiled = ts.transpileModule(source, {
+ compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 },
+}).outputText
+const modules = {
+ vue,
+ '@/composables/useChatStreamHandler': {
+ isAwaitingInput: (m) => m?.run_state === 'awaiting_input',
+ },
+}
+const exports = {}
+vm.runInNewContext(compiled, {
+ exports, Date,
+ require: (id) => {
+ assert.ok(id in modules, `unexpected import ${id}`)
+ return modules[id]
+ },
+})
+const { pendingPrompts, markPromptSubmitted, promptSubmission } = exports
+
+// pendingPrompts runs in the vm realm; its arrays are rebuilt here to compare.
+const ids = (list) => Array.from(list, (p) => p.pending_id)
+
+const approval = (id, extra = {}) =>
+ ({ type: 'tool_approval_required', pending_id: id, resolved: false, ...extra })
+
+test('docks the open prompts of streaming and suspended runs, oldest first', () => {
+ const prompts = pendingPrompts([
+ { role: 'user', agentEventStream: [approval('user-row')] },
+ { role: 'assistant', is_completed: true, run_state: 'awaiting_input', agentEventStream: [approval('a')] },
+ {
+ role: 'assistant', is_completed: false, agentEventStream: [
+ { type: 'tool_call', pending_id: 'x' },
+ { type: 'agent_prompt_required', kind: 'ask_user', pending_id: 'b', resolved: false },
+ { type: 'mcp_oauth_required', pending_id: 'c', resolved: false },
+ ],
+ },
+ ])
+ assert.deepEqual(ids(prompts), ['a', 'b', 'c'])
+})
+
+test('leaves settled runs, resolved prompts and unknown kinds in the timeline', () => {
+ const prompts = pendingPrompts([
+ { role: 'assistant', is_completed: true, agentEventStream: [approval('settled')] },
+ {
+ role: 'assistant', is_completed: false, agentEventStream: [
+ approval('resolved', { resolved: true }),
+ { type: 'agent_prompt_required', kind: 'something_else', pending_id: 'other', resolved: false },
+ approval(''),
+ ],
+ },
+ ])
+ assert.deepEqual(ids(prompts), [])
+})
+
+test('drops a suspended prompt once it expired', () => {
+ const past = new Date(Date.now() - 60_000).toISOString()
+ const future = new Date(Date.now() + 60_000).toISOString()
+ const prompts = pendingPrompts([{
+ role: 'assistant', is_completed: true, run_state: 'awaiting_input', agentEventStream: [
+ approval('expired', { suspended: true, expires_at: past }),
+ approval('live', { suspended: true, expires_at: future }),
+ ],
+ }])
+ assert.deepEqual(ids(prompts), ['live'])
+})
+
+test('a prompt answered on this page leaves the dock before the stream confirms it', () => {
+ const messages = vue.reactive([
+ { role: 'assistant', is_completed: false, agentEventStream: [approval('answered-here'), approval('next')] },
+ ])
+ const docked = vue.computed(() => ids(pendingPrompts(messages)))
+ assert.deepEqual(docked.value, ['answered-here', 'next'])
+
+ markPromptSubmitted('answered-here', { approved: true })
+ assert.deepEqual(docked.value, ['next'])
+ assert.deepEqual(promptSubmission('answered-here'), { approved: true })
+})
+
+test('both chat views mount the dock above their composer and feed it their messages', () => {
+ const read = (path) => readFileSync(new URL(path, import.meta.url), 'utf8')
+ const chat = read('../views/chat/index.vue')
+ assert.match(chat, /providePromptDock\(messagesList\)/)
+ assert.match(chat, /<PendingPromptDock[^>]*\/>\s*<InputField/)
+
+ const embed = read('../views/embed/EmbedChatCore.vue')
+ assert.match(embed, /providePromptDock\(messagesList\)/)
+ assert.match(embed, /<PendingPromptDock[\s\S]*?:embed-session-sig="sessionSig"[\s\S]*?\/>\s*<EmbedInputField/)
+})
+
+test('option keys are letters, and a letter key picks its option', () => {
+ assert.equal(optionKey(0), 'A')
+ assert.equal(optionKey(25), 'Z')
+ assert.equal(optionKey(26), '')
+ assert.equal(optionIndexForKey('b'), 1)
+ assert.equal(optionIndexForKey('C'), 2)
+ assert.equal(optionIndexForKey('1'), -1)
+ assert.equal(optionIndexForKey('Enter'), -1)
+})
+
+test('Enter submits unless it inserts a line break or confirms an IME candidate', () => {
+ const key = (init) => ({ key: 'Enter', shiftKey: false, isComposing: false, keyCode: 13, ...init })
+ assert.equal(isSubmitKey(key({})), true)
+ assert.equal(isSubmitKey(key({ shiftKey: true })), false)
+ assert.equal(isSubmitKey(key({ isComposing: true })), false)
+ assert.equal(isSubmitKey(key({ keyCode: 229 })), false)
+ assert.equal(isSubmitKey(key({ key: 'a' })), false)
+})
+
+test('Enter on a focused control keeps its native action instead of submitting the prompt', () => {
+ for (const control of ['reject', 'skip', 'args-toggle', 'dock-next']) {
+ const key = {
+ key: 'Enter', shiftKey: false, isComposing: false, keyCode: 13,
+ target: { closest: (selector) => selector.includes('button') ? { control, getAttribute: () => null } : null },
+ }
+ assert.equal(isSubmitKey(key), false, control)
+ }
+})
+
+test('Enter on the option just picked submits it rather than toggling it off', () => {
+ const option = { getAttribute: (name) => ({ role: 'option', 'aria-selected': 'true' })[name] }
+ const key = {
+ key: 'Enter', shiftKey: false, isComposing: false, keyCode: 13,
+ target: { closest: (selector) => (selector.includes('button') ? option : null) },
+ }
+ assert.equal(isSubmitKey(key), true)
+})
+
+test('the approval handler does not approve when Enter targets Reject', () => {
+ const card = readFileSync(new URL('../views/chat/components/ToolApprovalCard.vue', import.meta.url), 'utf8')
+ const handler = card.slice(card.indexOf('const handleKey ='), card.indexOf('defineExpose'))
+ const decisions = []
+ const compiled = ts.transpileModule(handler, { compilerOptions: { target: ts.ScriptTarget.ES2022 } }).outputText
+ const handleKey = vm.runInNewContext(compiled + '\nhandleKey', {
+ interactive: { value: true }, isJsonValid: { value: true }, isSubmitKey,
+ submit: (decision) => decisions.push(decision),
+ })
+ const key = { key: 'Enter', shiftKey: false, isComposing: false, keyCode: 13,
+ target: { tagName: 'BUTTON', closest: () => ({ textContent: 'Reject' }) } }
+ assert.equal(handleKey(key), false)
+ assert.deepEqual(decisions, [])
+ assert.equal(handleKey({ ...key, target: { tagName: 'SECTION', closest: () => null } }), true)
+ assert.deepEqual(decisions, ['approve'])
+})
+
+
+test('Enter on an unselected option selects it instead of submitting the previous answer', () => {
+ const card = readFileSync(new URL('../views/chat/components/AskUserCard.vue', import.meta.url), 'utf8')
+ const source = card.slice(card.indexOf('const handleKey ='), card.indexOf('defineExpose'))
+ const compiled = ts.transpileModule(source, { compilerOptions: { target: ts.ScriptTarget.ES2022 } }).outputText
+ for (const initial of [[], ['A']]) {
+ let selected = [...initial]
+ const submitted = []
+ const handleKey = vm.runInNewContext(compiled + '\nhandleKey', {
+ interactive: { value: true }, isSubmitKey, isTextEntry: () => false,
+ optionIndexForKey, options: { value: ['A', 'B'] },
+ submit: () => submitted.push([...selected]), toggleOption: (value) => { selected = [value] },
+ })
+ const control = { getAttribute: (name) => ({ role: 'option', 'aria-selected': String(selected.includes('B')) })[name] }
+ const key = { key: 'Enter', shiftKey: false, isComposing: false, keyCode: 13,
+ target: { closest: (selector) => selector.includes('button') ? control : null } }
+ // Returning false preserves the native button click; the dock must not
+ // preventDefault or submit A while the user's focus is on B.
+ assert.equal(handleKey(key), false)
+ assert.deepEqual(submitted, [])
+ selected = ['B'] // The button's native click selects B.
+ assert.equal(handleKey(key), true)
+ assert.deepEqual(submitted, [['B']])
+ }
+})
diff --git a/frontend/src/composables/usePromptDock.ts b/frontend/src/composables/usePromptDock.ts
new file mode 100644
index 000000000..a6044e8b6
--- /dev/null
+++ b/frontend/src/composables/usePromptDock.ts
@@ -0,0 +1,87 @@
+import { computed, inject, provide, reactive, ref, type ComputedRef, type InjectionKey, type Ref } from 'vue'
+import { isAwaitingInput } from '@/composables/useChatStreamHandler'
+
+type PromptEvent = Record<string, any>
+type ChatRow = Record<string, unknown>
+
+const DOCKED_TYPES = new Set(['tool_approval_required', 'agent_prompt_required', 'mcp_oauth_required'])
+
+// Answers given on this page, by pending id. The stream reports a prompt
+// resolved only once its run consumes the answer, which for a suspended run
+// is after it resumes; until then this keeps the prompt out of the dock and
+// lets its timeline row show what was sent.
+const submissions = reactive(new Map<string, Record<string, unknown>>())
+
+export function markPromptSubmitted(pendingId: string, answer: Record<string, unknown> = {}) {
+ submissions.set(pendingId, answer)
+}
+
+export function promptSubmission(pendingId: string): Record<string, unknown> | undefined {
+ return submissions.get(pendingId)
+}
+
+function isDockable(e: PromptEvent): boolean {
+ if (!DOCKED_TYPES.has(String(e?.type || '')) || e.resolved || !e.pending_id) return false
+ if (e.type === 'agent_prompt_required' && e.kind !== 'ask_user') return false
+ if (submissions.has(e.pending_id)) return false
+ if (e.suspended && e.expires_at) {
+ const expires = Date.parse(String(e.expires_at))
+ if (!Number.isNaN(expires) && expires <= Date.now()) return false
+ }
+ return true
+}
+
+/**
+ * Prompts still waiting on the user, oldest first. Only a run that is
+ * streaming or suspended on input can be waiting; cards in settled messages
+ * are history.
+ */
+export function pendingPrompts(messages: ChatRow[]): PromptEvent[] {
+ const out: PromptEvent[] = []
+ for (const message of messages) {
+ if (message.role !== 'assistant') continue
+ if (message.is_completed && !isAwaitingInput(message)) continue
+ for (const e of (message.agentEventStream as PromptEvent[] | undefined) || []) {
+ if (isDockable(e)) out.push(e)
+ }
+ }
+ return out
+}
+
+export interface PromptDock {
+ prompts: ComputedRef<PromptEvent[]>
+ activeId: Ref<string>
+ collapsed: Ref<boolean>
+ /** Bumped when something asks the dock to take focus. */
+ focusRequest: Ref<number>
+ isDocked: (pendingId: string) => boolean
+ focus: (pendingId: string) => void
+}
+
+const promptDockKey: InjectionKey<PromptDock> = Symbol('promptDock')
+
+/** Called by a chat view; its timeline cards and its dock share the result. */
+export function providePromptDock(messages: ChatRow[]): PromptDock {
+ const prompts = computed(() => pendingPrompts(messages))
+ const activeId = ref('')
+ const collapsed = ref(false)
+ const focusRequest = ref(0)
+ const dock: PromptDock = {
+ prompts,
+ activeId,
+ collapsed,
+ focusRequest,
+ isDocked: (pendingId) => prompts.value.some((e) => e.pending_id === pendingId),
+ focus: (pendingId) => {
+ activeId.value = pendingId
+ collapsed.value = false
+ focusRequest.value++
+ },
+ }
+ provide(promptDockKey, dock)
+ return dock
+}
+
+export function usePromptDock(): PromptDock | null {
+ return inject(promptDockKey, null)
+}
diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts
index bafb398c7..e70ee24be 100755
--- a/frontend/src/i18n/locales/en-US.ts
+++ b/frontend/src/i18n/locales/en-US.ts
@@ -6148,7 +6148,8 @@ export default {
getDocumentInfo: 'Get Document Info',
queryKnowledgeGraph: 'Query Knowledge Graph',
think: 'Deep Thinking',
- todoWrite: 'Make Plan'
+ todoWrite: 'Make Plan',
+ askUser: 'Ask User'
},
vectorStoreBadge: {
systemDefault: 'System default',
@@ -6246,10 +6247,37 @@ export default {
}
},
agentStream: {
+ askUser: {
+ title: 'Question for you',
+ selectPlaceholder: 'Select',
+ textPlaceholder: 'Type your answer',
+ otherPlaceholder: 'Other (optional)',
+ decline: 'Skip',
+ submit: 'Submit',
+ declinedTag: 'Declined to answer',
+ submitted: 'Submitted',
+ answeredTag: 'Answered',
+ timedOutTag: 'No answer in time',
+ canceledTag: 'Canceled',
+ unansweredTag: 'Not answered',
+ submitFailed: 'Failed to submit',
+ },
+ promptDock: {
+ approvalTitle: 'Needs your review',
+ oauthTitle: 'Needs your authorization',
+ waiting: 'Waiting for you',
+ handle: 'Respond',
+ pager: '{current} / {total}',
+ previous: 'Previous',
+ next: 'Next',
+ collapse: 'Collapse',
+ expand: 'Expand'
+ },
toolApproval: {
waiting: 'Awaiting review · {target}',
waitingStatus: 'Awaiting review',
targetWithTool: '{service} › {tool}',
+ dockQuestion: 'Allow {target} to run?',
titleWithTarget: 'Review · {service} › {tool}',
argsLabel: 'Arguments',
argsModified: 'Modified',
@@ -6258,6 +6286,9 @@ export default {
reject: 'Reject',
approvedTag: 'Approved',
rejectedTag: 'Rejected',
+ parked: 'Waiting in the background — answer any time',
+ parkedUntil: 'Waiting in the background — answer before {time}',
+ abandonedTag: 'Abandoned',
invalidJson: 'Arguments must be valid JSON',
submitted: 'Submitted',
submitFailed: 'Submit failed',
@@ -6267,6 +6298,7 @@ export default {
waiting: 'Awaiting authorization · {target}',
waitingStatus: 'Awaiting authorization',
targetWithTool: '{service} › {tool}',
+ dockQuestion: 'Authorize {target} to continue',
titleWithService: 'OAuth · {service}',
titleWithTool: 'OAuth · {service} › {tool}',
desc: 'Authorizing opens a new window to sign in. The tool call resumes automatically once authorization succeeds.',
@@ -6294,6 +6326,7 @@ export default {
readDocument: 'Read document',
listDocuments: 'List documents',
todoWrite: 'Plan Management',
+ askUser: 'Ask User',
knowledgeGraphExtract: 'Knowledge Graph Extraction',
thinking: 'Thinking',
attachmentParsing: 'Parsing Attachment',
@@ -6587,6 +6620,8 @@ export default {
thinkingDesc: 'Dynamic and reflective problem-solving thinking tool',
todoWrite: 'Plan',
todoWriteDesc: 'Create structured research plans',
+ askUser: 'Ask User',
+ askUserDesc: 'Ask the user for missing information and wait for the answer before continuing',
searchKnowledge: 'Search knowledge',
searchKnowledgeDesc: 'Semantic, keyword or hybrid search over knowledge-base chunks',
readDocument: 'Read document',
diff --git a/frontend/src/i18n/locales/ja-JP.ts b/frontend/src/i18n/locales/ja-JP.ts
index f269ff18c..9d6a2a340 100644
--- a/frontend/src/i18n/locales/ja-JP.ts
+++ b/frontend/src/i18n/locales/ja-JP.ts
@@ -6148,7 +6148,8 @@ export default {
getDocumentInfo: 'ドキュメント情報の取得',
queryKnowledgeGraph: 'ナレッジグラフの照会',
think: '深い思考',
- todoWrite: '計画の作成'
+ todoWrite: '計画の作成',
+ askUser: 'ユーザーに質問'
},
vectorStoreBadge: {
systemDefault: 'システムデフォルト',
@@ -6246,10 +6247,37 @@ export default {
}
},
agentStream: {
+ askUser: {
+ title: 'あなたへの質問',
+ selectPlaceholder: '選択してください',
+ textPlaceholder: '回答を入力',
+ otherPlaceholder: 'その他(任意)',
+ decline: '回答しない',
+ submit: '送信',
+ declinedTag: '回答を辞退しました',
+ submitted: '送信済み',
+ answeredTag: '回答済み',
+ timedOutTag: '時間内に回答なし',
+ canceledTag: 'キャンセル済み',
+ unansweredTag: '未回答',
+ submitFailed: '送信に失敗しました',
+ },
+ promptDock: {
+ approvalTitle: '承認が必要です',
+ oauthTitle: '認可が必要です',
+ waiting: 'あなたの対応待ち',
+ handle: '対応する',
+ pager: '{current} / {total}',
+ previous: '前へ',
+ next: '次へ',
+ collapse: '折りたたむ',
+ expand: '展開'
+ },
toolApproval: {
waiting: '承認待ち · {target}',
waitingStatus: '承認待ち',
targetWithTool: '{service} › {tool}',
+ dockQuestion: '{target} の実行を許可しますか?',
titleWithTarget: '承認 · {service} › {tool}',
argsLabel: '引数',
argsModified: '変更あり',
@@ -6258,6 +6286,9 @@ export default {
reject: '拒否',
approvedTag: '承認済み',
rejectedTag: '拒否済み',
+ parked: 'バックグラウンドで待機中。後で対応できます',
+ parkedUntil: 'バックグラウンドで待機中。{time} までに対応してください',
+ abandonedTag: '破棄済み',
invalidJson: '引数は有効なJSONである必要があります',
submitted: '送信しました',
submitFailed: '送信に失敗しました',
@@ -6267,6 +6298,7 @@ export default {
waiting: '認可待ち · {target}',
waitingStatus: '認可待ち',
targetWithTool: '{service} › {tool}',
+ dockQuestion: '続行するには {target} を認可してください',
titleWithService: 'OAuth · {service}',
titleWithTool: 'OAuth · {service} › {tool}',
desc: '認可すると、サインイン用の新しいウィンドウが開きます。認可が成功すると、ツール呼び出しは自動的に再開されます。',
@@ -6294,6 +6326,7 @@ export default {
readDocument: 'ドキュメントを読む',
listDocuments: 'ドキュメント一覧',
todoWrite: '計画管理',
+ askUser: 'ユーザーに質問',
knowledgeGraphExtract: 'ナレッジグラフ抽出',
thinking: '思考',
attachmentParsing: '添付ファイルを解析',
@@ -6587,6 +6620,8 @@ export default {
thinkingDesc: '動的かつ内省的に問題を解決する思考ツール',
todoWrite: '計画',
todoWriteDesc: '構造化された調査計画を作成します',
+ askUser: 'ユーザーに質問',
+ askUserDesc: '必要な情報が不足しているときにユーザーへ質問し、回答を待ってから続行します',
searchKnowledge: 'ナレッジベースを検索',
searchKnowledgeDesc: 'セマンティック・キーワード・ハイブリッド検索でナレッジベースのチャンクを検索します',
readDocument: 'ドキュメントを読む',
diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.ts
index 6ca61b063..abb6ac765 100755
--- a/frontend/src/i18n/locales/ko-KR.ts
+++ b/frontend/src/i18n/locales/ko-KR.ts
@@ -1497,6 +1497,8 @@ export default {
thinkingDesc: '동적이고 반성적인 문제 해결 사고 도구',
todoWrite: '계획 수립',
todoWriteDesc: '구조화된 연구 계획 생성',
+ askUser: '사용자에게 질문',
+ askUserDesc: '필요한 정보가 부족할 때 사용자에게 질문하고 답변을 기다린 후 계속합니다',
searchKnowledge: '지식베이스 검색',
searchKnowledgeDesc: '의미, 키워드 또는 하이브리드 방식으로 지식베이스 청크 검색',
readDocument: '문서 읽기',
@@ -1809,6 +1811,7 @@ export default {
readDocument: '문서 읽기',
listDocuments: '문서 목록 보기',
todoWrite: '계획 관리',
+ askUser: '사용자에게 질문',
knowledgeGraphExtract: '지식 그래프 추출',
thinking: '사고',
attachmentParsing: '첨부 파일 파싱',
@@ -1871,6 +1874,7 @@ export default {
waiting: '인증 대기 · {target}',
waitingStatus: '인증 대기',
targetWithTool: '{service} › {tool}',
+ dockQuestion: '계속하려면 {target} 인증이 필요합니다',
titleWithService: 'OAuth · {service}',
titleWithTool: 'OAuth · {service} › {tool}',
desc: '인증을 누르면 새 창에서 로그인합니다. 인증이 완료되면 이 도구 호출이 자동으로 계속됩니다.',
@@ -1885,10 +1889,37 @@ export default {
resumeFailed: '실행 재개 실패, 다시 시도하세요',
skipFailed: '건너뛰기 실패, 다시 시도하세요'
},
+ askUser: {
+ title: '질문이 있습니다',
+ selectPlaceholder: '선택하세요',
+ textPlaceholder: '답변을 입력하세요',
+ otherPlaceholder: '기타(선택)',
+ decline: '답변 안 함',
+ submit: '제출',
+ declinedTag: '답변 거절함',
+ submitted: '제출됨',
+ answeredTag: '답변함',
+ timedOutTag: '시간 내 답변 없음',
+ canceledTag: '취소됨',
+ unansweredTag: '답변 없음',
+ submitFailed: '제출 실패',
+ },
+ promptDock: {
+ approvalTitle: '검토가 필요합니다',
+ oauthTitle: '인증이 필요합니다',
+ waiting: '응답 대기 중',
+ handle: '응답하기',
+ pager: '{current} / {total}',
+ previous: '이전',
+ next: '다음',
+ collapse: '접기',
+ expand: '펼치기'
+ },
toolApproval: {
waiting: '승인 대기 · {target}',
waitingStatus: '승인 대기',
targetWithTool: '{service} › {tool}',
+ dockQuestion: '{target} 실행을 허용할까요?',
titleWithTarget: '검토 · {service} › {tool}',
argsLabel: '인수',
argsModified: '수정됨',
@@ -1897,6 +1928,9 @@ export default {
reject: '거부',
approvedTag: '승인됨',
rejectedTag: '거부됨',
+ parked: '백그라운드에서 대기 중 — 나중에 처리할 수 있습니다',
+ parkedUntil: '백그라운드에서 대기 중 — {time} 전에 처리하세요',
+ abandonedTag: '포기됨',
invalidJson: '유효한 JSON이 아닙니다',
submitted: '제출됨',
submitFailed: '제출 실패',
@@ -2011,7 +2045,8 @@ export default {
getDocumentInfo: '문서 정보 조회',
queryKnowledgeGraph: '지식 그래프 쿼리',
think: '깊이 생각하기',
- todoWrite: '계획 수립'
+ todoWrite: '계획 수립',
+ askUser: '사용자에게 질문'
},
commandPalette: {
placeholder: '지식베이스, 파일, 대화 검색…',
diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts
index 43ff93d55..591a063ad 100755
--- a/frontend/src/i18n/locales/ru-RU.ts
+++ b/frontend/src/i18n/locales/ru-RU.ts
@@ -1497,6 +1497,8 @@ export default {
thinkingDesc: 'Динамический инструмент рефлексивного решения проблем',
todoWrite: 'Планирование',
todoWriteDesc: 'Создание структурированных исследовательских планов',
+ askUser: 'Вопрос пользователю',
+ askUserDesc: 'Задаёт пользователю вопрос, когда не хватает данных, и ждёт ответа',
searchKnowledge: 'Поиск по базе знаний',
searchKnowledgeDesc: 'Семантический, ключевой или гибридный поиск по фрагментам базы знаний',
readDocument: 'Чтение документа',
@@ -1809,6 +1811,7 @@ export default {
readDocument: 'Чтение документа',
listDocuments: 'Список документов',
todoWrite: 'Управление планами',
+ askUser: 'Вопрос пользователю',
knowledgeGraphExtract: 'Извлечение графа знаний',
thinking: 'Размышление',
attachmentParsing: 'Разбор вложения',
@@ -1871,6 +1874,7 @@ export default {
waiting: 'Ожидание авторизации · {target}',
waitingStatus: 'Ожидание авторизации',
targetWithTool: '{service} › {tool}',
+ dockQuestion: 'Авторизуйте {target}, чтобы продолжить',
titleWithService: 'OAuth · {service}',
titleWithTool: 'OAuth · {service} › {tool}',
desc: 'Авторизация откроет новое окно для входа. После успешной авторизации вызов инструмента продолжится автоматически.',
@@ -1885,10 +1889,37 @@ export default {
resumeFailed: 'Не удалось возобновить выполнение, повторите попытку',
skipFailed: 'Не удалось пропустить, повторите попытку'
},
+ askUser: {
+ title: 'Вопрос к вам',
+ selectPlaceholder: 'Выберите',
+ textPlaceholder: 'Введите ответ',
+ otherPlaceholder: 'Другое (необязательно)',
+ decline: 'Не отвечать',
+ submit: 'Отправить',
+ declinedTag: 'Отказ от ответа',
+ submitted: 'Отправлено',
+ answeredTag: 'Ответ дан',
+ timedOutTag: 'Нет ответа вовремя',
+ canceledTag: 'Отменено',
+ unansweredTag: 'Без ответа',
+ submitFailed: 'Не удалось отправить',
+ },
+ promptDock: {
+ approvalTitle: 'Требуется ваша проверка',
+ oauthTitle: 'Требуется авторизация',
+ waiting: 'Ожидает вашего ответа',
+ handle: 'Ответить',
+ pager: '{current} / {total}',
+ previous: 'Назад',
+ next: 'Далее',
+ collapse: 'Свернуть',
+ expand: 'Развернуть'
+ },
toolApproval: {
waiting: 'Ожидание проверки · {target}',
waitingStatus: 'Ожидание проверки',
targetWithTool: '{service} › {tool}',
+ dockQuestion: 'Разрешить вызов {target}?',
titleWithTarget: 'Проверка · {service} › {tool}',
argsLabel: 'Аргументы',
argsModified: 'Изменено',
@@ -1897,6 +1928,9 @@ export default {
reject: 'Отклонить',
approvedTag: 'Подтверждено',
rejectedTag: 'Отклонено',
+ parked: 'Ожидает в фоне — можно ответить позже',
+ parkedUntil: 'Ожидает в фоне — ответьте до {time}',
+ abandonedTag: 'Отменено',
invalidJson: 'Некорректный JSON',
submitted: 'Отправлено',
submitFailed: 'Ошибка отправки',
@@ -2011,7 +2045,8 @@ export default {
getDocumentInfo: 'Получить информацию о документе',
queryKnowledgeGraph: 'Запрос к графу знаний',
think: 'Глубокое размышление',
- todoWrite: 'Составить план'
+ todoWrite: 'Составить план',
+ askUser: 'Вопрос пользователю'
},
commandPalette: {
placeholder: 'Поиск по базам знаний, файлам, диалогам…',
diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts
index ff894cf2e..79e7bbe76 100755
--- a/frontend/src/i18n/locales/zh-CN.ts
+++ b/frontend/src/i18n/locales/zh-CN.ts
@@ -1499,6 +1499,8 @@ export default {
thinkingDesc: '动态和反思性的问题解决思考工具',
todoWrite: '制定计划',
todoWriteDesc: '创建结构化的研究计划',
+ askUser: '向用户提问',
+ askUserDesc: '在缺少关键信息时向用户提问,并等待回答后继续',
searchKnowledge: '检索知识库',
searchKnowledgeDesc: '语义、关键词或混合检索知识库分块',
readDocument: '阅读文档',
@@ -1811,6 +1813,7 @@ export default {
readDocument: '阅读文档',
listDocuments: '浏览文档列表',
todoWrite: '计划管理',
+ askUser: '向用户提问',
knowledgeGraphExtract: '知识图谱抽取',
thinking: '思考',
attachmentParsing: '解析附件',
@@ -1873,6 +1876,7 @@ export default {
waiting: '等待授权 · {target}',
waitingStatus: '等待授权',
targetWithTool: '{service} › {tool}',
+ dockQuestion: '需要授权 {target} 才能继续',
titleWithService: 'OAuth 授权 · {service}',
titleWithTool: 'OAuth 授权 · {service} › {tool}',
desc: '点击授权将打开新窗口完成登录,授权成功后会自动继续本次工具调用。',
@@ -1887,10 +1891,37 @@ export default {
resumeFailed: '恢复执行失败,请重试',
skipFailed: '跳过失败,请重试'
},
+ askUser: {
+ title: '向你提问',
+ selectPlaceholder: '请选择',
+ textPlaceholder: '输入你的回答',
+ otherPlaceholder: '其他(可选)',
+ decline: '不回答',
+ submit: '提交',
+ declinedTag: '已拒绝回答',
+ submitted: '已提交',
+ answeredTag: '已回答',
+ timedOutTag: '超时未回答',
+ canceledTag: '已取消',
+ unansweredTag: '未回答',
+ submitFailed: '提交失败',
+ },
+ promptDock: {
+ approvalTitle: '需要你审核',
+ oauthTitle: '需要你授权',
+ waiting: '等待你处理',
+ handle: '去处理',
+ pager: '{current} / {total}',
+ previous: '上一个',
+ next: '下一个',
+ collapse: '收起',
+ expand: '展开'
+ },
toolApproval: {
waiting: '等待审核 · {target}',
waitingStatus: '等待审核',
targetWithTool: '{service} › {tool}',
+ dockQuestion: '允许调用 {target}?',
titleWithTarget: '人工审核 · {service} › {tool}',
argsLabel: '调用参数',
argsModified: '已修改',
@@ -1899,6 +1930,9 @@ export default {
reject: '拒绝',
approvedTag: '已通过',
rejectedTag: '已拒绝',
+ parked: '已转入后台等待,可稍后处理',
+ parkedUntil: '已转入后台等待,{time} 前可处理',
+ abandonedTag: '已放弃',
invalidJson: '参数不是合法 JSON',
submitted: '已提交',
submitFailed: '提交失败',
@@ -2013,7 +2047,8 @@ export default {
getDocumentInfo: '获取文档信息',
queryKnowledgeGraph: '查询知识图谱',
think: '深度思考',
- todoWrite: '制定计划'
+ todoWrite: '制定计划',
+ askUser: '向用户提问'
},
commandPalette: {
placeholder: '搜索知识库、文件、对话…',
diff --git a/frontend/src/i18n/locales/zh-TW.ts b/frontend/src/i18n/locales/zh-TW.ts
index 7f31ffaeb..ca069c27c 100644
--- a/frontend/src/i18n/locales/zh-TW.ts
+++ b/frontend/src/i18n/locales/zh-TW.ts
@@ -1499,6 +1499,8 @@ export default {
thinkingDesc: '動態和反思性的問題解決思考工具',
todoWrite: '制定計劃',
todoWriteDesc: '建立結構化的研究計劃',
+ askUser: '向使用者提問',
+ askUserDesc: '在缺少關鍵資訊時向使用者提問,並等待回答後繼續',
searchKnowledge: '檢索知識庫',
searchKnowledgeDesc: '語義、關鍵字或混合檢索知識庫切塊',
readDocument: '閱讀文件',
@@ -1811,6 +1813,7 @@ export default {
readDocument: '閱讀文件',
listDocuments: '瀏覽文件清單',
todoWrite: '計劃管理',
+ askUser: '向使用者提問',
knowledgeGraphExtract: '知識圖譜抽取',
thinking: '思考',
attachmentParsing: '解析附件',
@@ -1873,6 +1876,7 @@ export default {
waiting: '等待授權 · {target}',
waitingStatus: '等待授權',
targetWithTool: '{service} › {tool}',
+ dockQuestion: '需要授權 {target} 才能繼續',
titleWithService: 'OAuth 授權 · {service}',
titleWithTool: 'OAuth 授權 · {service} › {tool}',
desc: '點擊授權將打開新視窗完成登入,授權成功後會自動繼續本次工具呼叫。',
@@ -1887,10 +1891,37 @@ export default {
resumeFailed: '復原執行失敗,請重試',
skipFailed: '跳過失敗,請重試'
},
+ askUser: {
+ title: '向你提問',
+ selectPlaceholder: '請選擇',
+ textPlaceholder: '輸入你的回答',
+ otherPlaceholder: '其他(選填)',
+ decline: '不回答',
+ submit: '提交',
+ declinedTag: '已拒絕回答',
+ submitted: '已提交',
+ answeredTag: '已回答',
+ timedOutTag: '逾時未回答',
+ canceledTag: '已取消',
+ unansweredTag: '未回答',
+ submitFailed: '提交失敗',
+ },
+ promptDock: {
+ approvalTitle: '需要你審核',
+ oauthTitle: '需要你授權',
+ waiting: '等待你處理',
+ handle: '去處理',
+ pager: '{current} / {total}',
+ previous: '上一個',
+ next: '下一個',
+ collapse: '收起',
+ expand: '展開'
+ },
toolApproval: {
waiting: '等待審核 · {target}',
waitingStatus: '等待審核',
targetWithTool: '{service} › {tool}',
+ dockQuestion: '允許呼叫 {target}?',
titleWithTarget: '人工審核 · {service} › {tool}',
argsLabel: '呼叫參數',
argsModified: '已修改',
@@ -1899,6 +1930,9 @@ export default {
reject: '拒絕',
approvedTag: '已透過',
rejectedTag: '已拒絕',
+ parked: '已轉入背景等待,可稍後處理',
+ parkedUntil: '已轉入背景等待,{time} 前可處理',
+ abandonedTag: '已放棄',
invalidJson: '參數不是合法 JSON',
submitted: '已提交',
submitFailed: '提交失敗',
@@ -2013,7 +2047,8 @@ export default {
getDocumentInfo: '獲取文件資訊',
queryKnowledgeGraph: '查詢知識圖譜',
think: '深度思考',
- todoWrite: '制定計劃'
+ todoWrite: '制定計劃',
+ askUser: '向使用者提問'
},
commandPalette: {
placeholder: '搜尋知識庫、檔案、對話…',
diff --git a/frontend/src/utils/askUser.test.ts b/frontend/src/utils/askUser.test.ts
new file mode 100644
index 000000000..101836448
--- /dev/null
+++ b/frontend/src/utils/askUser.test.ts
@@ -0,0 +1,41 @@
+import assert from 'node:assert/strict'
+import test from 'node:test'
+import { buildAskUserResponse, canSubmitAskUser, summarizeAskUserAnswer, type AskUserQuestion } from './askUser.ts'
+
+const form: AskUserQuestion = {
+ question: 'Trip?',
+ fields: [
+ { name: 'city', label: 'City', type: 'text', required: true },
+ { name: 'days', type: 'number' },
+ { name: 'tags', type: 'multiselect', options: ['a', 'b'] },
+ ],
+}
+
+test('a form answer keeps filled fields only', () => {
+ const r = buildAskUserResponse(form, { selected: [], values: { city: ' Paris ', days: 3, tags: [] }, text: 'ignored' })
+ assert.deepEqual(r, { values: { city: 'Paris', days: 3 } })
+ assert.equal(canSubmitAskUser(form, r), true)
+ assert.equal(summarizeAskUserAnswer(form, r), 'City: Paris\ndays: 3')
+})
+
+test('a form waits for its required fields', () => {
+ const r = buildAskUserResponse(form, { selected: [], values: { days: 2 }, text: '' })
+ assert.equal(canSubmitAskUser(form, r), false)
+})
+
+test('options accept a choice or, when allowed, typed text', () => {
+ const q: AskUserQuestion = { question: 'Pick', options: ['x', 'y'], allow_free_text: true }
+ assert.equal(canSubmitAskUser(q, buildAskUserResponse(q, { selected: [], values: {}, text: '' })), false)
+ assert.deepEqual(buildAskUserResponse(q, { selected: ['y'], values: {}, text: '' }), { selected: ['y'] })
+ const typed = buildAskUserResponse(q, { selected: [], values: {}, text: 'z' })
+ assert.deepEqual(typed, { text: 'z' })
+ assert.equal(canSubmitAskUser(q, typed), true)
+ const strict: AskUserQuestion = { question: 'Pick', options: ['x'] }
+ assert.deepEqual(buildAskUserResponse(strict, { selected: [], values: {}, text: 'z' }), {})
+})
+
+test('a free-text question needs text', () => {
+ const q: AskUserQuestion = { question: 'Why?' }
+ assert.equal(canSubmitAskUser(q, buildAskUserResponse(q, { selected: [], values: {}, text: ' ' })), false)
+ assert.deepEqual(buildAskUserResponse(q, { selected: [], values: {}, text: ' because ' }), { text: 'because' })
+})
diff --git a/frontend/src/utils/askUser.ts b/frontend/src/utils/askUser.ts
new file mode 100644
index 000000000..f9c539548
--- /dev/null
+++ b/frontend/src/utils/askUser.ts
@@ -0,0 +1,67 @@
+export interface AskUserField {
+ name: string
+ label?: string
+ type: 'text' | 'number' | 'select' | 'multiselect'
+ required?: boolean
+ options?: string[]
+}
+
+/** Request of an ask_user prompt; mirrors types.AskUserPromptRequest. */
+export interface AskUserQuestion {
+ question: string
+ options?: string[]
+ multi_select?: boolean
+ fields?: AskUserField[]
+ allow_free_text?: boolean
+}
+
+export interface AskUserDraft {
+ selected: string[]
+ values: Record<string, unknown>
+ text: string
+}
+
+const isEmpty = (v: unknown) =>
+ v === undefined || v === null || (typeof v === 'string' && !v.trim()) || (Array.isArray(v) && v.length === 0)
+
+/** Builds the response the server validates, dropping untouched inputs. */
+export function buildAskUserResponse(q: AskUserQuestion, draft: AskUserDraft): Record<string, unknown> {
+ const response: Record<string, unknown> = {}
+ if (q.options?.length && draft.selected.length) response.selected = [...draft.selected]
+ if (q.fields?.length) {
+ const values: Record<string, unknown> = {}
+ for (const f of q.fields) {
+ const v = draft.values[f.name]
+ if (!isEmpty(v)) values[f.name] = typeof v === 'string' ? v.trim() : v
+ }
+ if (Object.keys(values).length) response.values = values
+ }
+ const freeTextOnly = !q.options?.length && !q.fields?.length
+ const text = draft.text.trim()
+ if (text && (freeTextOnly || q.allow_free_text)) response.text = text
+ return response
+}
+
+/** Whether a response answers the question well enough to send. */
+export function canSubmitAskUser(q: AskUserQuestion, response: Record<string, unknown>): boolean {
+ const values = (response.values || {}) as Record<string, unknown>
+ if (q.fields?.some((f) => f.required && isEmpty(values[f.name]))) return false
+ if (q.options?.length) return Boolean((response.selected as string[] | undefined)?.length || response.text)
+ if (q.fields?.length) return true
+ return Boolean(response.text)
+}
+
+/** One line per part of an answer, labelled the way the question was. */
+export function summarizeAskUserAnswer(q: AskUserQuestion, answer: Record<string, unknown>): string {
+ const lines: string[] = []
+ const selected = answer.selected as string[] | undefined
+ if (selected?.length) lines.push(selected.join(', '))
+ const values = (answer.values || {}) as Record<string, unknown>
+ for (const f of q.fields || []) {
+ const v = values[f.name]
+ if (isEmpty(v)) continue
+ lines.push(`${f.label || f.name}: ${Array.isArray(v) ? v.join(', ') : String(v)}`)
+ }
+ if (typeof answer.text === 'string' && answer.text.trim()) lines.push(answer.text.trim())
+ return lines.join('\n')
+}
diff --git a/frontend/src/utils/promptKeys.ts b/frontend/src/utils/promptKeys.ts
new file mode 100644
index 000000000..9ac92944f
--- /dev/null
+++ b/frontend/src/utils/promptKeys.ts
@@ -0,0 +1,29 @@
+/** Letter shown beside the i-th option of a docked prompt: A, B, C… */
+export function optionKey(index: number): string {
+ return index >= 0 && index < 26 ? String.fromCharCode(65 + index) : ''
+}
+
+/** Index of the option a key press picks, or -1. */
+export function optionIndexForKey(key: string): number {
+ if (key.length !== 1) return -1
+ const code = key.toUpperCase().charCodeAt(0)
+ return code >= 65 && code <= 90 ? code - 65 : -1
+}
+
+/** Whether key presses on el are typing rather than shortcuts. */
+export function isTextEntry(el: EventTarget | null): boolean {
+ if (!(el instanceof HTMLElement)) return false
+ return el.isContentEditable || el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.tagName === 'SELECT'
+}
+
+/** Enter that submits: not composing an IME candidate, not a soft line break. */
+export function isSubmitKey(e: KeyboardEvent): boolean {
+ // Let focused controls perform their own action (especially Reject/Skip).
+ // The dock receives bubbled keydowns from both its cards and its header.
+ // A picked option keeps focus after the click, and Enter then submits it.
+ const target = e.target as Element | null
+ const control = target?.closest?.('button, a, [role="button"]')
+ if (control && (control.getAttribute?.('role') !== 'option'
+ || control.getAttribute?.('aria-selected') !== 'true')) return false
+ return e.key === 'Enter' && !e.shiftKey && !e.isComposing && e.keyCode !== 229
+}
diff --git a/frontend/src/utils/suspendedRun.ts b/frontend/src/utils/suspendedRun.ts
new file mode 100644
index 000000000..7ecd07966
--- /dev/null
+++ b/frontend/src/utils/suspendedRun.ts
@@ -0,0 +1,7 @@
+import type { InjectionKey } from 'vue'
+
+/**
+ * Provided by a chat view: re-attaches to a suspended run after its prompt was
+ * answered and the server resumed it. Takes the prompt's pending id.
+ */
+export const resumeSuspendedRunKey: InjectionKey<(pendingId: string) => void> = Symbol('resumeSuspendedRun')
diff --git a/frontend/src/utils/tool-capabilities.ts b/frontend/src/utils/tool-capabilities.ts
index 68d98e849..bb3e1af2f 100644
--- a/frontend/src/utils/tool-capabilities.ts
+++ b/frontend/src/utils/tool-capabilities.ts
@@ -53,6 +53,7 @@ export const TOOL_CAPABILITY_REQUIREMENTS: Record<string, ToolRequirement> = {
// ---- base / reasoning (no KB dependency) ----
thinking: {},
todo_write: {},
+ ask_user: {},
// ---- RAG / chunk retrieval (need at least one chunk-indexed KB) ----
// We use vector|keyword as the canonical "has RAG chunks" signal. FAQ KBs
diff --git a/frontend/src/views/agent/AgentEditorModal.vue b/frontend/src/views/agent/AgentEditorModal.vue
index 50dccda1c..15ff71af4 100644
--- a/frontend/src/views/agent/AgentEditorModal.vue
+++ b/frontend/src/views/agent/AgentEditorModal.vue
@@ -2494,6 +2494,7 @@ const keepAllowedToolsUnset = ref(false);
const toolTexts = computed<Record<string, ToolText>>(() => ({
thinking: { label: t('agentEditor.tools.thinking'), description: t('agentEditor.tools.thinkingDesc') },
todo_write: { label: t('agentEditor.tools.todoWrite'), description: t('agentEditor.tools.todoWriteDesc') },
+ ask_user: { label: t('agentEditor.tools.askUser'), description: t('agentEditor.tools.askUserDesc') },
search_conversations: { label: t('agentEditor.tools.searchConversations'), description: t('agentEditor.tools.searchConversationsDesc') },
search_knowledge: { label: t('agentEditor.tools.searchKnowledge'), description: t('agentEditor.tools.searchKnowledgeDesc') },
read_document: { label: t('agentEditor.tools.readDocument'), description: t('agentEditor.tools.readDocumentDesc') },
@@ -3922,7 +3923,7 @@ watch(agentMode, (val, _oldVal) => {
// 用户主动切换模式后列表即为显式选择,不再保持未设置。
if (!isInitializing.value) keepAllowedToolsUnset.value = false;
if (!isInitializing.value && formData.value.config.allowed_tools.length === 0) {
- const tools: string[] = [];
+ const tools: string[] = ['ask_user'];
if (hasRagKnowledgeBase.value) {
tools.push(...knowledgeBaseTools);
}
diff --git a/frontend/src/views/chat/components/AgentStreamDisplay.style.test.mjs b/frontend/src/views/chat/components/AgentStreamDisplay.style.test.mjs
index 70385d909..61fc2576b 100644
--- a/frontend/src/views/chat/components/AgentStreamDisplay.style.test.mjs
+++ b/frontend/src/views/chat/components/AgentStreamDisplay.style.test.mjs
@@ -20,6 +20,7 @@ test('steer seals animation while keeping the preceding timeline open without co
const props = reactive({ ragMode: false, session: { steerForked: true, is_completed: true } })
const state = vm.runInNewContext(`${stateBlock}\n${collapseBlock}\n({ isConversationDone, isSegmentDone, shouldShowCollapsedSteps })`, {
props, computed, isAssistantTurnComplete, intermediateStepsCount: { value: 2 },
+ isAwaitingInput: (m) => m?.run_state === 'awaiting_input',
})
assert.equal(state.isSegmentDone.value, true)
assert.equal(state.isConversationDone.value, false)
@@ -27,6 +28,9 @@ test('steer seals animation while keeping the preceding timeline open without co
props.session.steerForked = false
assert.equal(state.isConversationDone.value, true)
assert.equal(state.shouldShowCollapsedSteps.value, true)
+ props.session.run_state = 'awaiting_input'
+ assert.equal(state.isConversationDone.value, false)
+ assert.equal(state.shouldShowCollapsedSteps.value, false)
})
test('agent steps use compact muted timeline styling', () => {
@@ -145,7 +149,10 @@ test('agent mode shows a native placeholder before answer whenever nothing is pe
assert.match(source, /return !hasPendingStreamingActivity\.value/)
assert.match(source, /const hasPendingStreamingActivity = computed/)
assert.match(source, /event\.thinking === true \|\| isThinkingActive\(event\.event_id\)/)
- assert.match(source, /event\.type === 'tool_approval_required' \|\| event\.type === 'mcp_oauth_required'/)
+ assert.match(
+ source,
+ /event\.type === 'tool_approval_required' \|\|\s*event\.type === 'mcp_oauth_required' \|\|\s*event\.type === 'agent_prompt_required'/,
+ )
assert.match(source, /class="action-card action-pending"/)
assert.match(source, /t\('chat\.thinkingAlt'\)/)
assert.match(source, /chat-timeline-loading\.less/)
diff --git a/frontend/src/views/chat/components/AgentStreamDisplay.vue b/frontend/src/views/chat/components/AgentStreamDisplay.vue
index f85930710..5a3a2d657 100644
--- a/frontend/src/views/chat/components/AgentStreamDisplay.vue
+++ b/frontend/src/views/chat/components/AgentStreamDisplay.vue
@@ -117,7 +117,19 @@
:mcp-tool-name="event.mcp_tool_name || ''" :description="event.description"
:args-json="event.args_json" :timeout-seconds="event.timeout_seconds"
:requested-at="event.requested_at" :resolved="event.resolved" :approved="event.approved"
- :resolve-reason="event.resolve_reason" v-bind="embedAuthProps" />
+ :resolve-reason="event.resolve_reason" :suspendable="event.suspendable"
+ :hot-wait-seconds="event.hot_wait_seconds" :suspended="event.suspended"
+ :expires-at="event.expires_at" :abandoned="event.abandoned" v-bind="embedAuthProps" />
+ </div>
+
+ <!-- Question the agent asked the user (ask_user) -->
+ <div v-else-if="event.type === 'agent_prompt_required' && event.kind === 'ask_user'" class="tool-event">
+ <AskUserCard :pending-id="event.pending_id" :request="event.request"
+ :timeout-seconds="event.timeout_seconds" :hot-wait-seconds="event.hot_wait_seconds"
+ :suspendable="event.suspendable" :suspended="event.suspended" :expires-at="event.expires_at"
+ :requested-at="event.requested_at" :resolved="event.resolved" :answered="event.answered"
+ :response="event.response" :resolve-reason="event.resolve_reason" :timed-out="event.timed_out"
+ :canceled="event.canceled" :abandoned="event.abandoned" v-bind="embedAuthProps" />
</div>
<!-- MCP OAuth in-conversation authorization prompt -->
@@ -341,7 +353,19 @@
<ToolApprovalCard :pending-id="event.pending_id" :service-name="event.service_name || ''"
:mcp-tool-name="event.mcp_tool_name || ''" :description="event.description" :args-json="event.args_json"
:timeout-seconds="event.timeout_seconds" :requested-at="event.requested_at" :resolved="event.resolved"
- :approved="event.approved" :resolve-reason="event.resolve_reason" v-bind="embedAuthProps" />
+ :approved="event.approved" :resolve-reason="event.resolve_reason" :suspendable="event.suspendable"
+ :hot-wait-seconds="event.hot_wait_seconds" :suspended="event.suspended" :expires-at="event.expires_at"
+ :abandoned="event.abandoned" v-bind="embedAuthProps" />
+ </div>
+
+ <!-- Question the agent asked the user (ask_user) -->
+ <div v-else-if="event.type === 'agent_prompt_required' && event.kind === 'ask_user'" class="tool-event">
+ <AskUserCard :pending-id="event.pending_id" :request="event.request"
+ :timeout-seconds="event.timeout_seconds" :hot-wait-seconds="event.hot_wait_seconds"
+ :suspendable="event.suspendable" :suspended="event.suspended" :expires-at="event.expires_at"
+ :requested-at="event.requested_at" :resolved="event.resolved" :answered="event.answered"
+ :response="event.response" :resolve-reason="event.resolve_reason" :timed-out="event.timed_out"
+ :canceled="event.canceled" :abandoned="event.abandoned" v-bind="embedAuthProps" />
</div>
<!-- MCP OAuth in-conversation authorization prompt -->
@@ -634,6 +658,7 @@
<script setup lang="ts">
import { readDocumentReferences } from '@/utils/readDocumentReferences';
import { isAssistantTurnComplete } from '@/utils/steerStreamFork';
+import { isAwaitingInput } from '@/composables/useChatStreamHandler';
import { ref, computed, watch, onMounted, onBeforeUnmount, onUpdated, nextTick } from 'vue';
import { useRouter, useRoute } from 'vue-router';
import { marked } from 'marked';
@@ -642,6 +667,7 @@ import SandboxCommandProgress from '@/components/SandboxCommandProgress.vue';
import ToolResultRenderer from './ToolResultRenderer.vue';
import ToolApprovalCard from './ToolApprovalCard.vue';
import McpOAuthCard from './McpOAuthCard.vue';
+import AskUserCard from './AskUserCard.vue';
import ChatRequestInfoButton from '@/components/ChatRequestInfoButton.vue';
import ChatCitationFloat from '@/components/ChatCitationFloat.vue';
import picturePreview from '@/components/picture-preview.vue';
@@ -758,6 +784,7 @@ const TOOL_NAME_KEYS: Record<string, string> = {
wiki_read_issue: 'agentEditor.tools.wikiReadIssue',
wiki_update_issue: 'agentEditor.tools.wikiUpdateIssue',
todo_write: 'agentStream.tools.todoWrite',
+ ask_user: 'agentStream.tools.askUser',
knowledge_graph_extract: 'agentStream.tools.knowledgeGraphExtract',
thinking: 'agentStream.tools.thinking',
attachment_parsing: 'agentStream.tools.attachmentParsing',
@@ -1562,7 +1589,11 @@ watch(eventStream, (stream) => {
// A steer boundary stops local animation without completing or folding the task.
-const isConversationDone = computed(() => isAssistantTurnComplete(props.session));
+// A run awaiting input keeps its steps in the timeline: the card it waits on
+// must stay in view rather than fold into the collapsed steps.
+const isConversationDone = computed(
+ () => isAssistantTurnComplete(props.session) && !isAwaitingInput(props.session),
+);
const isSegmentDone = computed(() => Boolean(props.session?.steerForked) || isConversationDone.value);
const streamingMermaidSvgCache = ref<string[]>([]);
@@ -1669,7 +1700,11 @@ const hasPendingStreamingActivity = computed(() => {
) {
return true;
}
- return event.type === 'tool_approval_required' || event.type === 'mcp_oauth_required';
+ return (
+ event.type === 'tool_approval_required' ||
+ event.type === 'mcp_oauth_required' ||
+ event.type === 'agent_prompt_required'
+ );
});
});
@@ -1764,9 +1799,10 @@ const finalContent = computed(() => {
// Count intermediate steps (after merging consecutive thinking events, matching what user sees in tree)
const intermediateStepsCount = computed(() => {
if (!hasAnswerStarted.value && !isSegmentDone.value) return 0;
- // Count only thinking and tool_call events (exclude plan_task_change, etc.)
+ // Count only thinking and tool_call events (exclude plan_task_change, etc.);
+ // a question card stands in for its ask_user call.
return intermediateEvents.value.filter(
- (e: any) => e.type === 'thinking' || e.type === 'tool_call'
+ (e: any) => e.type === 'thinking' || e.type === 'tool_call' || e.type === 'agent_prompt_required'
).length;
});
@@ -1781,7 +1817,9 @@ const reasoningRoundsCount = computed(() => {
const toolCallsCount = computed(() => {
if (!hasAnswerStarted.value && !isSegmentDone.value) return 0;
- return intermediateEvents.value.filter((e: any) => e.type === 'tool_call').length;
+ return intermediateEvents.value.filter(
+ (e: any) => e.type === 'tool_call' || e.type === 'agent_prompt_required'
+ ).length;
});
const intermediateStepsSummary = computed(() => {
@@ -1874,7 +1912,17 @@ const getThinkingSummary = (event: any): string => {
// Helper: build the full result list with plan_task_change injections and thinking merging
const buildFullEventList = (stream: any[]) => {
- const validStream = stream.filter((e: any) => e && typeof e === 'object' && e.type);
+ // An ask_user call is shown by its card; its tool row would repeat it.
+ const askedCalls = new Set(
+ stream
+ .filter((e: any) => e?.type === 'agent_prompt_required' && e.tool_call_id)
+ .map((e: any) => e.tool_call_id),
+ );
+ const validStream = stream.filter(
+ (e: any) =>
+ e && typeof e === 'object' && e.type &&
+ !(e.type === 'tool_call' && askedCalls.has(e.tool_call_id)),
+ );
let lastTask: string | null = null;
const result: any[] = [];
@@ -2130,13 +2178,18 @@ const displayEvents = computed(() => {
const getEventKey = (event: any, index: number): string => {
if (!event) return `event-${index}`;
if (event.event_id) return `event-${event.event_id}`;
- if (event.tool_call_id) return `tool-${event.tool_call_id}`;
+ // Prompt cards carry the tool_call_id of the call they block, so they are
+ // keyed by their own id to stay distinct from that call's row.
if (event.type === 'tool_approval_required' && event.pending_id) {
return `approval-${event.pending_id}`;
}
if (event.type === 'mcp_oauth_required' && event.pending_id) {
return `mcp-oauth-${event.pending_id}`;
}
+ if (event.type === 'agent_prompt_required' && event.pending_id) {
+ return `prompt-${event.pending_id}`;
+ }
+ if (event.tool_call_id) return `tool-${event.tool_call_id}`;
return `event-${index}-${event.type || 'unknown'}`;
};
diff --git a/frontend/src/views/chat/components/AskUserCard.vue b/frontend/src/views/chat/components/AskUserCard.vue
new file mode 100644
index 000000000..a69a026d2
--- /dev/null
+++ b/frontend/src/views/chat/components/AskUserCard.vue
@@ -0,0 +1,286 @@
+<template>
+ <div v-if="interactive" class="prompt-panel" @click.stop>
+ <div class="prompt-question">{{ question.question }}</div>
+
+ <div v-if="options.length" class="prompt-options" role="listbox" :aria-multiselectable="multiSelect">
+ <button v-for="(option, index) in options" :key="option" type="button" role="option" class="prompt-option"
+ :class="{ 'is-selected': isSelected(option) }" :aria-selected="isSelected(option)" :disabled="submitting"
+ @click="toggleOption(option)">
+ <span class="prompt-option-key">{{ optionKey(index) }}</span>
+ <span class="prompt-option-label">{{ option }}</span>
+ <t-icon v-if="isSelected(option)" class="prompt-option-check" name="check" />
+ </button>
+ </div>
+
+ <div v-for="field in fields" :key="field.name" class="ask-field">
+ <label class="ask-field-label">
+ {{ field.label || field.name }}<span v-if="field.required" class="ask-required">*</span>
+ </label>
+ <t-input-number v-if="field.type === 'number'" v-model="values[field.name]" :disabled="submitting"
+ theme="normal" size="small" class="ask-number" />
+ <t-select v-else-if="field.type === 'select' || field.type === 'multiselect'" v-model="values[field.name]"
+ :multiple="field.type === 'multiselect'" :disabled="submitting" size="small" clearable
+ :placeholder="$t('agentStream.askUser.selectPlaceholder')">
+ <t-option v-for="option in field.options || []" :key="option" :value="option" :label="option" />
+ </t-select>
+ <t-input v-else v-model="values[field.name]" :disabled="submitting" size="small" :maxlength="maxTextLen" />
+ </div>
+
+ <t-textarea v-if="acceptsText" v-model="text" class="ask-text" :disabled="submitting" :maxlength="maxTextLen"
+ :autosize="{ minRows: 1, maxRows: 6 }"
+ :placeholder="freeTextOnly ? $t('agentStream.askUser.textPlaceholder') : $t('agentStream.askUser.otherPlaceholder')" />
+
+ <div class="prompt-footer">
+ <div class="prompt-footer-meta">
+ <span v-if="parked" class="action-timer">{{ parkedText }}</span>
+ <span v-else-if="secondsLeft >= 0" class="action-timer" :class="timerClass">{{ countdownText }}</span>
+ </div>
+ <div class="prompt-footer-actions">
+ <button type="button" class="prompt-btn" :disabled="submitting" @click="submit(true)">
+ {{ $t('agentStream.askUser.decline') }}
+ </button>
+ <button type="button" class="prompt-btn is-primary" :disabled="submitting || !canSubmit" @click="submit(false)">
+ {{ $t('agentStream.askUser.submit') }}<span class="prompt-btn-key" aria-hidden="true">↵</span>
+ </button>
+ </div>
+ </div>
+ </div>
+
+ <div v-else class="action-card interaction-inline" :class="{ 'action-pending': !resolved }">
+ <div class="action-header no-results">
+ <div class="action-title">
+ <t-icon class="action-title-icon" :name="headerIcon" />
+ <span class="action-name">{{ $t('agentStream.askUser.title') }}</span>
+ </div>
+ </div>
+
+ <div class="ask-question">{{ question.question }}</div>
+
+ <div class="interaction-status-summary">
+ <div class="results-summary-text">
+ <template v-if="awaitingInDock">
+ <span class="status-label">{{ $t('agentStream.promptDock.waiting') }}</span>
+ <span class="inline-dot">·</span>
+ <button type="button" class="inline-action is-primary" @click.stop="dock?.focus(pendingId)">
+ {{ $t('agentStream.promptDock.handle') }}
+ </button>
+ </template>
+ <span v-else class="status-label">{{ statusLine }}</span>
+ </div>
+ </div>
+
+ <div v-if="answerSummary" class="ask-answer">{{ answerSummary }}</div>
+ </div>
+</template>
+
+<script setup lang="ts">
+import { computed, inject, reactive, ref } from 'vue'
+import { MessagePlugin } from 'tdesign-vue-next'
+import { useI18n } from 'vue-i18n'
+import { resolveAgentPrompt } from '@/api/mcp-service'
+import { resolveEmbedAgentPrompt } from '@/api/embed'
+import { resumeSuspendedRunKey } from '@/utils/suspendedRun'
+import { usePromptCountdown } from '@/composables/usePromptCountdown'
+import { markPromptSubmitted, promptSubmission, usePromptDock } from '@/composables/usePromptDock'
+import { buildAskUserResponse, canSubmitAskUser, summarizeAskUserAnswer, type AskUserQuestion } from '@/utils/askUser'
+import { isSubmitKey, isTextEntry, optionIndexForKey, optionKey } from '@/utils/promptKeys'
+
+const props = defineProps<{
+ pendingId: string
+ // dock: the answer form, shown above the composer. inline: the timeline row.
+ variant?: 'dock' | 'inline'
+ request?: AskUserQuestion
+ timeoutSeconds?: number
+ hotWaitSeconds?: number
+ suspendable?: boolean
+ suspended?: boolean
+ expiresAt?: string
+ requestedAt?: number
+ resolved?: boolean
+ answered?: boolean
+ response?: Record<string, unknown>
+ resolveReason?: string
+ timedOut?: boolean
+ canceled?: boolean
+ abandoned?: boolean
+ embeddedMode?: boolean
+ embedChannelId?: string
+ embedToken?: string
+ embedSessionId?: string
+ embedSessionSig?: string
+ embedVisitorId?: string
+}>()
+
+const { t } = useI18n()
+const resumeSuspendedRun = inject(resumeSuspendedRunKey, undefined)
+const dock = usePromptDock()
+const { parked, secondsLeft, timerClass, countdownText, parkedText } = usePromptCountdown(props)
+
+const maxTextLen = 4000
+const question = computed<AskUserQuestion>(() => props.request || { question: '' })
+const options = computed(() => question.value.options || [])
+const fields = computed(() => question.value.fields || [])
+const multiSelect = computed(() => Boolean(question.value.multi_select))
+const freeTextOnly = computed(() => !options.value.length && !fields.value.length)
+const acceptsText = computed(() => freeTextOnly.value || Boolean(question.value.allow_free_text))
+
+const submission = computed(() => promptSubmission(props.pendingId))
+const open = computed(() => !props.resolved && !submission.value)
+// Without a dock (a view that does not provide one) the row stays answerable.
+const interactive = computed(() => open.value && (props.variant === 'dock' || !dock))
+const awaitingInDock = computed(() => open.value && props.variant !== 'dock' && Boolean(dock?.isDocked(props.pendingId)))
+
+const selectedOne = ref('')
+const selectedMany = ref<string[]>([])
+const values = reactive<Record<string, unknown>>({})
+const text = ref('')
+const submitting = ref(false)
+
+const isSelected = (option: string) =>
+ multiSelect.value ? selectedMany.value.includes(option) : selectedOne.value === option
+
+const toggleOption = (option: string) => {
+ if (submitting.value) return
+ if (!multiSelect.value) {
+ selectedOne.value = selectedOne.value === option ? '' : option
+ return
+ }
+ selectedMany.value = selectedMany.value.includes(option)
+ ? selectedMany.value.filter((o) => o !== option)
+ : [...selectedMany.value, option]
+}
+
+const draft = () => buildAskUserResponse(question.value, {
+ selected: multiSelect.value ? selectedMany.value : (selectedOne.value ? [selectedOne.value] : []),
+ values,
+ text: text.value,
+})
+const canSubmit = computed(() => canSubmitAskUser(question.value, draft()))
+
+const headerIcon = computed(() => {
+ if (!props.resolved) return 'help-circle'
+ return props.answered ? 'check-circle' : 'minus-circle'
+})
+
+const statusLine = computed(() => {
+ if (!props.resolved) {
+ if (submission.value?.declined) return t('agentStream.askUser.declinedTag')
+ if (submission.value) return t('agentStream.askUser.submitted')
+ return t('agentStream.askUser.unansweredTag')
+ }
+ if (props.abandoned) return t('agentStream.toolApproval.abandonedTag')
+ if (props.answered) return t('agentStream.askUser.answeredTag')
+ if (props.timedOut) return t('agentStream.askUser.timedOutTag')
+ if (props.canceled) return t('agentStream.askUser.canceledTag')
+ if (props.resolveReason?.includes('declined')) return t('agentStream.askUser.declinedTag')
+ return t('agentStream.askUser.unansweredTag')
+})
+
+const answerSummary = computed(() => {
+ const answer = props.resolved ? props.response : submission.value
+ if (!answer || answer.declined) return ''
+ return summarizeAskUserAnswer(question.value, answer)
+})
+
+const embedTarget = () =>
+ props.embeddedMode && props.embedChannelId && props.embedToken && props.embedSessionId
+ && props.embedSessionSig && props.embedVisitorId
+
+const submit = async (decline: boolean) => {
+ if (!open.value || submitting.value) return
+ if (!decline && !canSubmit.value) return
+ const response = decline ? { declined: true } : draft()
+ submitting.value = true
+ try {
+ const { resumed } = await (embedTarget()
+ ? resolveEmbedAgentPrompt(
+ props.embedChannelId!, props.embedToken!, props.embedSessionId!, props.embedSessionSig!,
+ props.embedVisitorId!, props.pendingId, 'ask_user', response,
+ )
+ : resolveAgentPrompt(props.pendingId, 'ask_user', response))
+ markPromptSubmitted(props.pendingId, response)
+ if (resumed) resumeSuspendedRun?.(props.pendingId)
+ } catch (e: any) {
+ const msg = e?.response?.data?.error?.message || e?.error?.message || e?.message
+ || t('agentStream.askUser.submitFailed')
+ MessagePlugin.error(msg)
+ } finally {
+ submitting.value = false
+ }
+}
+
+/** Keyboard shortcuts while docked: a letter picks an option, Enter submits. */
+const handleKey = (e: KeyboardEvent): boolean => {
+ if (!interactive.value) return false
+ const target = e.target as HTMLElement | null
+ if (isSubmitKey(e)) {
+ // Enter inside a select picks from its dropdown.
+ if (target?.closest('.t-select, .t-select__wrap')) return false
+ void submit(false)
+ return true
+ }
+ if (isTextEntry(target) || e.metaKey || e.ctrlKey || e.altKey) return false
+ const index = optionIndexForKey(e.key)
+ if (index < 0 || index >= options.value.length) return false
+ toggleOption(options.value[index])
+ return true
+}
+
+defineExpose({ handleKey })
+</script>
+
+<style scoped lang="less">
+@import './agent-interaction-card.less';
+
+// The question reads like the agent's other step text in the timeline.
+.ask-question {
+ padding: 2px 0 0;
+ font-size: var(--agent-step-text-size, 14px);
+ line-height: 1.55;
+ color: var(--td-text-color-secondary);
+ white-space: pre-wrap;
+ word-break: break-word;
+}
+
+.ask-field {
+ display: flex;
+ flex-direction: column;
+ gap: 4px;
+}
+
+.ask-field-label {
+ font-size: var(--agent-step-summary-size, 13px);
+ line-height: 1.55;
+ color: var(--td-text-color-secondary);
+}
+
+.ask-number {
+ width: 100%;
+}
+
+.ask-text {
+ :deep(.t-textarea__inner) {
+ font-size: var(--agent-step-summary-size, 13px);
+ }
+
+ // The limit is far above a typical answer; the counter is noise here.
+ :deep(.t-textarea__info_wrapper),
+ :deep(.t-textarea__limit) {
+ display: none;
+ }
+}
+
+.ask-answer {
+ padding: 2px 0 0;
+ font-size: var(--agent-step-summary-size, 13px);
+ line-height: 1.55;
+ color: var(--td-text-color-secondary);
+ white-space: pre-wrap;
+ word-break: break-word;
+}
+
+.ask-required {
+ margin-left: 2px;
+ color: var(--td-error-color);
+}
+</style>
diff --git a/frontend/src/views/chat/components/McpOAuthCard.vue b/frontend/src/views/chat/components/McpOAuthCard.vue
index 20bda2fab..c91b63410 100644
--- a/frontend/src/views/chat/components/McpOAuthCard.vue
+++ b/frontend/src/views/chat/components/McpOAuthCard.vue
@@ -1,5 +1,24 @@
<template>
- <div class="action-card interaction-inline" :class="{ 'action-pending': !resolved }">
+ <div v-if="interactive" class="prompt-panel" @click.stop>
+ <div class="prompt-question">{{ $t('agentStream.mcpOAuth.dockQuestion', { target: targetLabel }) }}</div>
+ <div class="prompt-desc">{{ $t('agentStream.mcpOAuth.desc') }}</div>
+
+ <div class="prompt-footer">
+ <div class="prompt-footer-meta">
+ <span v-if="secondsLeft >= 0" class="action-timer" :class="timerClass">{{ formatCountdown(secondsLeft) }}</span>
+ </div>
+ <div class="prompt-footer-actions">
+ <button type="button" class="prompt-btn" :disabled="canceling || authorizing" @click="skip">
+ {{ $t('agentStream.mcpOAuth.skip') }}
+ </button>
+ <button type="button" class="prompt-btn is-primary" :disabled="authorizing || canceling" @click="authorize">
+ {{ $t('agentStream.mcpOAuth.authorize') }}<span class="prompt-btn-key" aria-hidden="true">↵</span>
+ </button>
+ </div>
+ </div>
+ </div>
+
+ <div v-else class="action-card interaction-inline" :class="{ 'action-pending': !resolved }">
<div class="action-header no-results">
<div class="action-title">
<t-icon class="action-title-icon" :name="headerIcon" />
@@ -8,23 +27,14 @@
</div>
<div class="interaction-status-summary">
<div class="results-summary-text">
- <span v-if="resolved" class="status-label">{{ statusLine }}</span>
- <span v-if="!resolved" class="inline-actions">
- <button type="button" class="inline-action" :disabled="canceling || authorizing" @click="skip">
- {{ $t('agentStream.mcpOAuth.skip') }}
- </button>
+ <template v-if="awaitingInDock">
+ <span class="status-label">{{ $t('agentStream.promptDock.waiting') }}</span>
<span class="inline-dot">·</span>
- <button type="button" class="inline-action is-primary" :disabled="authorizing || canceling"
- @click="authorize">
- {{ $t('agentStream.mcpOAuth.authorize') }}
+ <button type="button" class="inline-action is-primary" @click.stop="dock?.focus(pendingId)">
+ {{ $t('agentStream.promptDock.handle') }}
</button>
- </span>
- <template v-if="!resolved && secondsLeft >= 0">
- <span class="inline-dot">·</span>
- <span class="action-timer" :class="timerClass">
- {{ formatCountdown(secondsLeft) }}
- </span>
</template>
+ <span v-else class="status-label">{{ statusLine }}</span>
</div>
</div>
</div>
@@ -48,9 +58,13 @@ import {
getEmbedMCPOAuthStatus,
resolveEmbedMCPOAuth,
} from '@/api/embed'
+import { markPromptSubmitted, promptSubmission, usePromptDock } from '@/composables/usePromptDock'
+import { isSubmitKey } from '@/utils/promptKeys'
const props = defineProps<{
pendingId: string
+ // dock: the authorize prompt, shown above the composer. inline: the timeline row.
+ variant?: 'dock' | 'inline'
serviceId: string
serviceName: string
mcpToolName?: string
@@ -78,6 +92,13 @@ const useEmbedOAuth = () =>
&& props.embedVisitorId
const { t } = useI18n()
+const dock = usePromptDock()
+
+const submission = computed(() => promptSubmission(props.pendingId))
+const open = computed(() => !props.resolved && !submission.value)
+// Without a dock (a view that does not provide one) the row stays answerable.
+const interactive = computed(() => open.value && (props.variant === 'dock' || !dock))
+const awaitingInDock = computed(() => open.value && props.variant !== 'dock' && Boolean(dock?.isDocked(props.pendingId)))
const authorizing = ref(false)
const canceling = ref(false)
@@ -124,7 +145,11 @@ const mainTitle = computed(() => {
})
const statusLine = computed(() => {
- if (!props.resolved) return t('agentStream.mcpOAuth.waitingStatus')
+ if (!props.resolved) {
+ if (submission.value?.authorized) return t('agentStream.mcpOAuth.authorizedTag')
+ if (submission.value) return t('agentStream.mcpOAuth.canceledTag')
+ return t('agentStream.mcpOAuth.waitingStatus')
+ }
if (props.authorized) return t('agentStream.mcpOAuth.authorizedTag')
if (props.timedOut) return t('agentStream.mcpOAuth.timedOutTag')
return t('agentStream.mcpOAuth.canceledTag')
@@ -160,6 +185,7 @@ const skip = async () => {
} else {
await cancelMCPOAuth(props.pendingId)
}
+ markPromptSubmitted(props.pendingId, { authorized: false })
} catch (e: any) {
const msg = e?.response?.data?.error?.message || e?.message || t('agentStream.mcpOAuth.skipFailed')
MessagePlugin.error(msg)
@@ -236,6 +262,7 @@ const authorize = async () => {
/* next describe/list will live-fill this user's directory */
}
}
+ markPromptSubmitted(props.pendingId, { authorized: true })
MessagePlugin.success(t('agentStream.mcpOAuth.authorizedToast'))
} catch (e: any) {
const msg = e?.response?.data?.error?.message || e?.message || t('agentStream.mcpOAuth.resumeFailed')
@@ -264,6 +291,15 @@ onBeforeUnmount(() => {
if (clock) window.clearInterval(clock)
stopPoll()
})
+
+/** Enter starts authorization while docked. */
+const handleKey = (e: KeyboardEvent): boolean => {
+ if (!interactive.value || !isSubmitKey(e) || authorizing.value || canceling.value) return false
+ void authorize()
+ return true
+}
+
+defineExpose({ handleKey })
</script>
<style scoped lang="less">
diff --git a/frontend/src/views/chat/components/PendingPromptDock.vue b/frontend/src/views/chat/components/PendingPromptDock.vue
new file mode 100644
index 000000000..e1ac8b1bd
--- /dev/null
+++ b/frontend/src/views/chat/components/PendingPromptDock.vue
@@ -0,0 +1,287 @@
+<template>
+ <transition name="prompt-dock">
+ <section v-if="dock && prompts.length" ref="root" class="prompt-dock" :class="{ 'is-collapsed': collapsed }"
+ tabindex="-1" :aria-label="title" @keydown="onKeydown">
+ <header class="prompt-dock__header" @click="collapsed && expand()">
+ <t-icon class="prompt-dock__icon" :name="icon" />
+ <span class="prompt-dock__title">{{ title }}</span>
+ <div class="prompt-dock__tools" @click.stop>
+ <div v-if="prompts.length > 1" class="prompt-dock__pager">
+ <button type="button" class="prompt-dock__btn" :disabled="index === 0"
+ :aria-label="$t('agentStream.promptDock.previous')" @click="step(-1)">
+ <t-icon name="chevron-left" />
+ </button>
+ <span class="prompt-dock__count">
+ {{ $t('agentStream.promptDock.pager', { current: index + 1, total: prompts.length }) }}
+ </span>
+ <button type="button" class="prompt-dock__btn" :disabled="index === prompts.length - 1"
+ :aria-label="$t('agentStream.promptDock.next')" @click="step(1)">
+ <t-icon name="chevron-right" />
+ </button>
+ </div>
+ <button type="button" class="prompt-dock__btn"
+ :aria-label="collapsed ? $t('agentStream.promptDock.expand') : $t('agentStream.promptDock.collapse')"
+ @click="collapsed ? expand() : (dock.collapsed.value = true)">
+ <t-icon :name="collapsed ? 'chevron-up' : 'remove'" />
+ </button>
+ </div>
+ </header>
+
+ <div v-show="!collapsed" class="prompt-dock__body">
+ <div v-for="prompt in prompts" v-show="prompt.pending_id === activeId" :key="prompt.pending_id">
+ <ToolApprovalCard v-if="prompt.type === 'tool_approval_required'" :ref="(el) => setCard(prompt, el)"
+ variant="dock" v-bind="{ ...timing(prompt), ...authProps }" :service-name="prompt.service_name || ''"
+ :mcp-tool-name="prompt.mcp_tool_name || ''" :description="prompt.description"
+ :args-json="prompt.args_json" />
+ <AskUserCard v-else-if="prompt.type === 'agent_prompt_required'" :ref="(el) => setCard(prompt, el)"
+ variant="dock" v-bind="{ ...timing(prompt), ...authProps }" :request="prompt.request" />
+ <McpOAuthCard v-else :ref="(el) => setCard(prompt, el)" variant="dock" v-bind="authProps"
+ :pending-id="prompt.pending_id" :service-id="prompt.service_id || ''"
+ :service-name="prompt.service_name || ''" :mcp-tool-name="prompt.mcp_tool_name || ''"
+ :timeout-seconds="prompt.timeout_seconds" :requested-at="prompt.requested_at" />
+ </div>
+ </div>
+ </section>
+ </transition>
+</template>
+
+<script setup lang="ts">
+import { computed, nextTick, ref, watch } from 'vue'
+import { useI18n } from 'vue-i18n'
+import { usePromptDock } from '@/composables/usePromptDock'
+import { isTextEntry } from '@/utils/promptKeys'
+import AskUserCard from './AskUserCard.vue'
+import McpOAuthCard from './McpOAuthCard.vue'
+import ToolApprovalCard from './ToolApprovalCard.vue'
+
+const props = defineProps<{
+ embeddedMode?: boolean
+ embedChannelId?: string
+ embedToken?: string
+ embedSessionId?: string
+ embedSessionSig?: string
+ embedVisitorId?: string
+}>()
+
+type Prompt = Record<string, any>
+type DockCard = { handleKey?: (e: KeyboardEvent) => boolean }
+
+const { t } = useI18n()
+const dock = usePromptDock()
+const root = ref<HTMLElement | null>(null)
+const cards = new Map<string, DockCard>()
+
+const prompts = computed<Prompt[]>(() => dock?.prompts.value || [])
+const collapsed = computed(() => Boolean(dock?.collapsed.value))
+const activeId = computed(() => {
+ const chosen = dock?.activeId.value
+ return prompts.value.some((p) => p.pending_id === chosen) ? chosen : prompts.value[0]?.pending_id || ''
+})
+const index = computed(() => Math.max(0, prompts.value.findIndex((p) => p.pending_id === activeId.value)))
+const active = computed(() => prompts.value[index.value])
+
+const authProps = computed(() => ({
+ embeddedMode: props.embeddedMode,
+ embedChannelId: props.embedChannelId,
+ embedToken: props.embedToken,
+ embedSessionId: props.embedSessionId,
+ embedSessionSig: props.embedSessionSig,
+ embedVisitorId: props.embedVisitorId,
+}))
+
+const timing = (p: Prompt) => ({
+ pendingId: p.pending_id,
+ timeoutSeconds: p.timeout_seconds,
+ hotWaitSeconds: p.hot_wait_seconds,
+ suspendable: p.suspendable,
+ suspended: p.suspended,
+ expiresAt: p.expires_at,
+ requestedAt: p.requested_at,
+})
+
+const title = computed(() => {
+ switch (active.value?.type) {
+ case 'tool_approval_required': return t('agentStream.promptDock.approvalTitle')
+ case 'mcp_oauth_required': return t('agentStream.promptDock.oauthTitle')
+ default: return t('agentStream.askUser.title')
+ }
+})
+
+const icon = computed(() => {
+ switch (active.value?.type) {
+ case 'tool_approval_required': return 'secured'
+ case 'mcp_oauth_required': return 'lock-on'
+ default: return 'help-circle'
+ }
+})
+
+const setCard = (prompt: Prompt, el: unknown) => {
+ if (el) cards.set(prompt.pending_id, el as DockCard)
+ else cards.delete(prompt.pending_id)
+}
+
+const step = (delta: number) => {
+ const next = prompts.value[index.value + delta]
+ if (next && dock) dock.activeId.value = next.pending_id
+}
+
+const takeFocus = async () => {
+ await nextTick()
+ root.value?.focus({ preventScroll: true })
+}
+
+const expand = () => {
+ if (!dock) return
+ dock.collapsed.value = false
+ void takeFocus()
+}
+
+const onKeydown = (e: KeyboardEvent) => {
+ if (!dock) return
+ if (e.key === 'Escape') {
+ dock.collapsed.value = true
+ e.preventDefault()
+ return
+ }
+ if (collapsed.value) return
+ if (e.altKey && (e.key === 'ArrowLeft' || e.key === 'ArrowRight')) {
+ step(e.key === 'ArrowLeft' ? -1 : 1)
+ e.preventDefault()
+ return
+ }
+ if (cards.get(activeId.value)?.handleKey?.(e)) e.preventDefault()
+}
+
+watch(() => dock?.focusRequest.value, () => { void takeFocus() })
+
+// A new prompt opens the dock; it takes focus unless the user is typing.
+watch(() => prompts.value.map((p) => p.pending_id), (ids, previous = []) => {
+ const arrived = ids.filter((id) => !previous.includes(id))
+ if (!dock || !arrived.length) return
+ if (!ids.includes(dock.activeId.value)) dock.activeId.value = arrived[0]
+ dock.collapsed.value = false
+ if (!isTextEntry(document.activeElement)) void takeFocus()
+})
+</script>
+
+<style scoped lang="less">
+.prompt-dock {
+ width: 100%;
+ max-width: 960px;
+ margin: 0 auto 8px;
+ box-sizing: border-box;
+ background: var(--td-bg-color-container);
+ border: 1px solid var(--td-component-stroke);
+ border-radius: var(--app-radius-xl);
+ box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04), 0 8px 16px -4px rgba(0, 0, 0, 0.06);
+ outline: none;
+ transition: border-color var(--app-motion-fast) ease;
+
+ &:focus-within {
+ border-color: color-mix(in srgb, var(--td-brand-color) 45%, var(--td-component-stroke));
+ }
+
+ &.is-collapsed .prompt-dock__header {
+ padding-bottom: 6px;
+ cursor: pointer;
+ }
+}
+
+.prompt-dock__header {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+ min-height: 34px;
+ padding: 6px 8px 0 14px;
+ box-sizing: border-box;
+ user-select: none;
+}
+
+.prompt-dock__icon {
+ flex-shrink: 0;
+ font-size: var(--app-text-base, 14px);
+ color: var(--td-text-color-placeholder);
+}
+
+.prompt-dock__title {
+ flex: 1;
+ min-width: 0;
+ font-size: var(--app-text-sm);
+ color: var(--td-text-color-secondary);
+ white-space: nowrap;
+ overflow: hidden;
+ text-overflow: ellipsis;
+}
+
+.prompt-dock__tools,
+.prompt-dock__pager {
+ display: flex;
+ align-items: center;
+ gap: 2px;
+ flex-shrink: 0;
+}
+
+.prompt-dock__pager {
+ margin-right: 4px;
+}
+
+.prompt-dock__count {
+ min-width: 36px;
+ font-size: var(--app-text-sm);
+ font-variant-numeric: tabular-nums;
+ text-align: center;
+ color: var(--td-text-color-secondary);
+}
+
+.prompt-dock__btn {
+ appearance: none;
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: 24px;
+ height: 24px;
+ padding: 0;
+ border: 0;
+ border-radius: var(--app-radius-sm);
+ background: transparent;
+ font-size: var(--app-text-base, 14px);
+ color: var(--td-text-color-placeholder);
+ cursor: pointer;
+ transition: background var(--app-motion-fast) ease, color var(--app-motion-fast) ease;
+
+ &:hover:not(:disabled) {
+ background: var(--td-bg-color-container-hover);
+ color: var(--td-text-color-primary);
+ }
+
+ &:disabled {
+ opacity: 0.35;
+ cursor: default;
+ }
+}
+
+.prompt-dock__body {
+ max-height: min(50vh, 440px);
+ overflow-y: auto;
+ padding: 6px 14px 12px;
+ overscroll-behavior: contain;
+}
+
+.prompt-dock-enter-active,
+.prompt-dock-leave-active {
+ transition: opacity var(--app-motion-base) ease, transform var(--app-motion-base) ease;
+}
+
+.prompt-dock-enter-from,
+.prompt-dock-leave-to {
+ opacity: 0;
+ transform: translateY(6px);
+}
+
+@media (prefers-reduced-motion: reduce) {
+ .prompt-dock-enter-active,
+ .prompt-dock-leave-active {
+ transition: none;
+ }
+}
+</style>
diff --git a/frontend/src/views/chat/components/ToolApprovalCard.vue b/frontend/src/views/chat/components/ToolApprovalCard.vue
index e1d3d498c..7218e5dbe 100644
--- a/frontend/src/views/chat/components/ToolApprovalCard.vue
+++ b/frontend/src/views/chat/components/ToolApprovalCard.vue
@@ -1,5 +1,42 @@
<template>
- <div class="action-card interaction-inline" :class="{ 'action-pending': !resolved }">
+ <div v-if="interactive" class="prompt-panel" @click.stop>
+ <div class="prompt-question">{{ $t('agentStream.toolApproval.dockQuestion', { target: targetLabel }) }}</div>
+ <div v-if="description" class="prompt-desc">{{ description }}</div>
+
+ <div v-if="hasArgs" class="prompt-args">
+ <button type="button" class="prompt-args-toggle" :aria-expanded="argsExpanded" @click="toggleArgs">
+ <span>{{ $t('agentStream.toolApproval.argsLabel') }}</span>
+ <t-icon class="args-toggle-icon" :name="argsExpanded ? 'chevron-down' : 'chevron-right'" />
+ <span v-if="!isJsonValid" class="args-status args-invalid">
+ <t-icon name="error-circle" />
+ {{ $t('agentStream.toolApproval.invalidJson') }}
+ </span>
+ <span v-else-if="argsDirty" class="args-status args-dirty">
+ {{ $t('agentStream.toolApproval.argsModified') }}
+ </span>
+ </button>
+ <t-textarea v-if="argsExpanded" v-model="argsText" class="prompt-args-input"
+ :autosize="{ minRows: 2, maxRows: 10 }" placeholder="{}" />
+ </div>
+
+ <div class="prompt-footer">
+ <div class="prompt-footer-meta">
+ <span v-if="parked" class="action-timer">{{ parkedText }}</span>
+ <span v-else-if="secondsLeft >= 0" class="action-timer" :class="timerClass">{{ countdownText }}</span>
+ </div>
+ <div class="prompt-footer-actions">
+ <button type="button" class="prompt-btn" :disabled="submitting" @click="submit('reject')">
+ {{ $t('agentStream.toolApproval.reject') }}
+ </button>
+ <button type="button" class="prompt-btn is-primary" :disabled="submitting || !isJsonValid"
+ @click="submit('approve')">
+ {{ $t('agentStream.toolApproval.approve') }}<span class="prompt-btn-key" aria-hidden="true">↵</span>
+ </button>
+ </div>
+ </div>
+ </div>
+
+ <div v-else class="action-card interaction-inline" :class="{ 'action-pending': !resolved }">
<div class="action-header no-results">
<div class="action-title">
<t-icon class="action-title-icon" :name="headerIcon" />
@@ -9,35 +46,14 @@
<div class="interaction-status-summary">
<div class="results-summary-text">
- <span v-if="resolved" class="status-label">{{ statusLine }}</span>
- <span v-if="!resolved" class="inline-actions">
- <button type="button" class="inline-action" :disabled="submitting" @click.stop="submit('reject')">
- {{ $t('agentStream.toolApproval.reject') }}
- </button>
+ <template v-if="awaitingInDock">
+ <span class="status-label">{{ $t('agentStream.promptDock.waiting') }}</span>
<span class="inline-dot">·</span>
- <button type="button" class="inline-action is-primary" :disabled="submitting || !isJsonValid"
- @click.stop="submit('approve')">
- {{ $t('agentStream.toolApproval.approve') }}
+ <button type="button" class="inline-action is-primary" @click.stop="dock?.focus(pendingId)">
+ {{ $t('agentStream.promptDock.handle') }}
</button>
- </span>
- <template v-if="!resolved && secondsLeft >= 0">
- <span class="inline-dot">·</span>
- <span class="action-timer" :class="timerClass">
- {{ formatCountdown(secondsLeft) }}
- </span>
</template>
- </div>
- </div>
-
- <div v-if="!resolved && !argsExpanded && (!isJsonValid || argsDirty)" class="interaction-status-summary">
- <div class="results-summary-text">
- <span v-if="!isJsonValid" class="args-status args-invalid">
- <t-icon name="error-circle" />
- {{ $t('agentStream.toolApproval.invalidJson') }}
- </span>
- <span v-else-if="argsDirty" class="args-status args-dirty">
- {{ $t('agentStream.toolApproval.argsModified') }}
- </span>
+ <span v-else class="status-label">{{ statusLine }}</span>
</div>
</div>
@@ -49,35 +65,26 @@
</div>
<div v-if="hasArgs && argsExpanded" class="action-details">
- <div v-if="!resolved && (!isJsonValid || argsDirty)" class="interaction-args-meta">
- <span v-if="!isJsonValid" class="args-status args-invalid">
- <t-icon name="error-circle" />
- {{ $t('agentStream.toolApproval.invalidJson') }}
- </span>
- <span v-else-if="argsDirty" class="args-status args-dirty">
- {{ $t('agentStream.toolApproval.argsModified') }}
- </span>
- </div>
-
- <div v-if="!resolved" class="interaction-args-block">
- <t-textarea v-model="argsText" class="interaction-args-input" :autosize="{ minRows: 2, maxRows: 8 }"
- placeholder="{}" @click.stop />
- </div>
-
- <div v-else class="interaction-args-preview">{{ argsText }}</div>
+ <div class="interaction-args-preview">{{ argsText }}</div>
</div>
</div>
</template>
<script setup lang="ts">
-import { ref, computed, onMounted, onBeforeUnmount } from 'vue'
+import { ref, computed, inject } from 'vue'
import { MessagePlugin } from 'tdesign-vue-next'
import { useI18n } from 'vue-i18n'
import { resolveToolApproval } from '@/api/mcp-service'
import { resolveEmbedToolApproval } from '@/api/embed'
+import { resumeSuspendedRunKey } from '@/utils/suspendedRun'
+import { usePromptCountdown } from '@/composables/usePromptCountdown'
+import { markPromptSubmitted, promptSubmission, usePromptDock } from '@/composables/usePromptDock'
+import { isSubmitKey } from '@/utils/promptKeys'
const props = defineProps<{
pendingId: string
+ // dock: the approval form, shown above the composer. inline: the timeline row.
+ variant?: 'dock' | 'inline'
serviceName: string
mcpToolName: string
description?: string
@@ -87,6 +94,13 @@ const props = defineProps<{
resolved?: boolean
approved?: boolean
resolveReason?: string
+ // suspendable: past hotWaitSeconds the run is suspended rather than failed,
+ // and the prompt stays answerable until expiresAt.
+ suspendable?: boolean
+ hotWaitSeconds?: number
+ suspended?: boolean
+ expiresAt?: string
+ abandoned?: boolean
embeddedMode?: boolean
embedChannelId?: string
embedToken?: string
@@ -104,6 +118,8 @@ const useEmbedApproval = () =>
&& props.embedVisitorId
const { t } = useI18n()
+const resumeSuspendedRun = inject(resumeSuspendedRunKey, undefined)
+const dock = usePromptDock()
function formatJson(raw: string): string {
try {
@@ -117,8 +133,13 @@ const initialArgs = formatJson(props.argsJson || '{}')
const argsText = ref(initialArgs)
const argsExpanded = ref(false)
const submitting = ref(false)
-const now = ref(Date.now())
-let timer: ReturnType<typeof setInterval> | null = null
+const { parked, secondsLeft, timerClass, countdownText, parkedText } = usePromptCountdown(props)
+
+const submission = computed(() => promptSubmission(props.pendingId))
+const open = computed(() => !props.resolved && !submission.value)
+// Without a dock (a view that does not provide one) the row stays answerable.
+const interactive = computed(() => open.value && (props.variant === 'dock' || !dock))
+const awaitingInDock = computed(() => open.value && props.variant !== 'dock' && Boolean(dock?.isDocked(props.pendingId)))
const hasArgs = computed(() => argsText.value.trim().length > 0)
@@ -134,25 +155,9 @@ const isJsonValid = computed(() => {
const argsDirty = computed(() => argsText.value.trim() !== initialArgs.trim())
-const deadline = computed(() => {
- const base = (props.requestedAt || 0) * 1000
- const add = (props.timeoutSeconds || 600) * 1000
- return base + add
-})
-
-const secondsLeft = computed(() => {
- if (props.resolved) return -1
- return Math.max(0, Math.floor((deadline.value - now.value) / 1000))
-})
-
-const timerClass = computed(() => {
- if (secondsLeft.value <= 30) return 'timer-critical'
- if (secondsLeft.value <= 120) return 'timer-warning'
- return ''
-})
-
const headerIcon = computed(() => {
if (!props.resolved) return 'secured'
+ if (props.abandoned) return 'minus-circle'
if (props.approved) return 'check-circle'
return 'close-circle'
})
@@ -175,7 +180,10 @@ const mainTitle = computed(() => {
})
const statusLine = computed(() => {
- if (!props.resolved) return t('agentStream.toolApproval.waitingStatus')
+ if (!props.resolved) {
+ return submission.value ? t('agentStream.toolApproval.submitted') : t('agentStream.toolApproval.waitingStatus')
+ }
+ if (props.abandoned) return t('agentStream.toolApproval.abandonedTag')
if (props.approved) return t('agentStream.toolApproval.approvedTag')
return t('agentStream.toolApproval.rejectedTag')
})
@@ -184,25 +192,8 @@ function toggleArgs() {
argsExpanded.value = !argsExpanded.value
}
-function formatCountdown(s: number): string {
- if (s < 60) return t('agentStream.toolApproval.countdownShort', { seconds: s })
- const m = Math.floor(s / 60)
- const r = s % 60
- return `${m}:${r.toString().padStart(2, '0')}`
-}
-
-onMounted(() => {
- timer = setInterval(() => {
- now.value = Date.now()
- }, 1000)
-})
-
-onBeforeUnmount(() => {
- if (timer) clearInterval(timer)
-})
-
const submit = async (decision: 'approve' | 'reject') => {
- if (props.resolved || submitting.value) return
+ if (!open.value || submitting.value) return
submitting.value = true
try {
let modified: Record<string, unknown> | undefined
@@ -215,7 +206,7 @@ const submit = async (decision: 'approve' | 'reject') => {
return
}
}
- await (useEmbedApproval()
+ const { resumed } = await (useEmbedApproval()
? resolveEmbedToolApproval(
props.embedChannelId!,
props.embedToken!,
@@ -234,7 +225,9 @@ const submit = async (decision: 'approve' | 'reject') => {
modified_args: decision === 'approve' ? modified : undefined,
reason: decision === 'reject' ? t('agentStream.toolApproval.userRejected') : undefined,
}))
+ markPromptSubmitted(props.pendingId, { approved: decision === 'approve' })
MessagePlugin.success(t('agentStream.toolApproval.submitted'))
+ if (resumed) resumeSuspendedRun?.(props.pendingId)
} catch (e: any) {
const msg = e?.response?.data?.error?.message || e?.message || t('agentStream.toolApproval.submitFailed')
MessagePlugin.error(msg)
@@ -242,6 +235,18 @@ const submit = async (decision: 'approve' | 'reject') => {
submitting.value = false
}
}
+
+/** Enter approves while docked; in the args editor it needs Cmd/Ctrl. */
+const handleKey = (e: KeyboardEvent): boolean => {
+ if (!interactive.value || !isSubmitKey(e)) return false
+ const inArgs = (e.target as HTMLElement | null)?.tagName === 'TEXTAREA'
+ if (inArgs && !e.metaKey && !e.ctrlKey) return false
+ if (!isJsonValid.value) return false
+ void submit('approve')
+ return true
+}
+
+defineExpose({ handleKey })
</script>
<style scoped lang="less">
diff --git a/frontend/src/views/chat/components/agent-interaction-card.less b/frontend/src/views/chat/components/agent-interaction-card.less
index e39cdc5c6..08e6a0434 100644
--- a/frontend/src/views/chat/components/agent-interaction-card.less
+++ b/frontend/src/views/chat/components/agent-interaction-card.less
@@ -254,3 +254,226 @@
font-size: var(--app-text-sm);
color: var(--td-text-color-placeholder);
}
+
+// The answerable form of a prompt, rendered in the dock above the composer.
+.prompt-panel {
+ display: flex;
+ flex-direction: column;
+ gap: 10px;
+}
+
+.prompt-question {
+ font-size: var(--app-text-base, 14px);
+ line-height: 1.55;
+ font-weight: 500;
+ color: var(--td-text-color-primary);
+ white-space: pre-wrap;
+ word-break: break-word;
+}
+
+.prompt-desc {
+ margin-top: -4px;
+ font-size: var(--agent-step-summary-size, 13px);
+ line-height: 1.55;
+ color: var(--td-text-color-secondary);
+ word-break: break-word;
+ display: -webkit-box;
+ -webkit-line-clamp: 3;
+ -webkit-box-orient: vertical;
+ overflow: hidden;
+}
+
+.prompt-options {
+ display: flex;
+ flex-direction: column;
+ gap: 2px;
+ margin: 0 -8px;
+}
+
+.prompt-option {
+ appearance: none;
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ width: 100%;
+ padding: 6px 8px;
+ border: 0;
+ border-radius: var(--app-radius-md);
+ background: transparent;
+ font: inherit;
+ font-size: var(--app-text-base, 14px);
+ line-height: 1.5;
+ text-align: left;
+ color: var(--td-text-color-primary);
+ cursor: pointer;
+ transition: background var(--app-motion-fast) ease;
+
+ &:hover:not(:disabled),
+ &:focus-visible {
+ background: var(--td-bg-color-container-hover);
+ outline: none;
+ }
+
+ &:disabled {
+ opacity: 0.6;
+ cursor: not-allowed;
+ }
+
+ &.is-selected {
+ background: var(--td-bg-color-container-hover);
+
+ .prompt-option-key {
+ background: var(--td-brand-color);
+ color: var(--td-text-color-anti);
+ }
+ }
+}
+
+.prompt-option-key {
+ flex-shrink: 0;
+ display: inline-flex;
+ align-items: center;
+ justify-content: center;
+ width: 20px;
+ height: 20px;
+ border-radius: var(--app-radius-sm);
+ background: var(--td-bg-color-secondarycontainer);
+ font-size: var(--app-text-sm);
+ font-weight: 500;
+ color: var(--td-text-color-secondary);
+ transition: background var(--app-motion-fast) ease, color var(--app-motion-fast) ease;
+}
+
+.prompt-option-label {
+ flex: 1;
+ min-width: 0;
+ word-break: break-word;
+}
+
+.prompt-option-check {
+ flex-shrink: 0;
+ color: var(--td-brand-color);
+}
+
+.prompt-args {
+ display: flex;
+ flex-direction: column;
+ gap: 6px;
+}
+
+.prompt-args-toggle {
+ appearance: none;
+ display: inline-flex;
+ align-items: center;
+ gap: 4px;
+ align-self: flex-start;
+ padding: 0;
+ border: 0;
+ background: transparent;
+ font: inherit;
+ font-size: var(--agent-step-summary-size, 13px);
+ line-height: 1.55;
+ color: var(--td-text-color-secondary);
+ cursor: pointer;
+
+ &:hover {
+ color: var(--td-text-color-primary);
+ }
+
+ .args-status {
+ margin-left: 6px;
+ }
+}
+
+.prompt-args-input {
+ :deep(.t-textarea__inner) {
+ font-family: var(--app-font-family-mono, ui-monospace, SFMono-Regular, Menlo, monospace);
+ font-size: var(--agent-step-summary-size, 13px);
+ line-height: 1.55;
+ background: var(--td-bg-color-secondarycontainer);
+ border-color: transparent;
+ border-radius: var(--app-radius-md);
+ color: var(--td-text-color-secondary);
+ }
+}
+
+.prompt-footer {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 12px;
+}
+
+.prompt-footer-meta {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ min-width: 0;
+
+ .action-timer {
+ font-size: var(--app-text-sm);
+ line-height: 1.55;
+ font-variant-numeric: tabular-nums;
+ color: var(--td-text-color-placeholder);
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+
+ &.timer-warning {
+ color: var(--td-warning-color);
+ }
+
+ &.timer-critical {
+ color: var(--td-error-color);
+ }
+ }
+}
+
+.prompt-footer-actions {
+ display: flex;
+ align-items: center;
+ gap: 4px;
+ flex-shrink: 0;
+}
+
+.prompt-btn {
+ appearance: none;
+ display: inline-flex;
+ align-items: center;
+ height: 28px;
+ padding: 0 12px;
+ border: 0;
+ border-radius: var(--app-radius-md);
+ background: transparent;
+ font: inherit;
+ font-size: var(--agent-step-summary-size, 13px);
+ color: var(--td-text-color-secondary);
+ cursor: pointer;
+ transition: background var(--app-motion-fast) ease, color var(--app-motion-fast) ease;
+
+ &:hover:not(:disabled) {
+ background: var(--td-bg-color-container-hover);
+ color: var(--td-text-color-primary);
+ }
+
+ &.is-primary {
+ background: var(--td-brand-color);
+ color: var(--td-text-color-anti);
+
+ &:hover:not(:disabled) {
+ background: var(--td-brand-color-hover);
+ color: var(--td-text-color-anti);
+ }
+ }
+
+ &:disabled {
+ opacity: 0.45;
+ cursor: not-allowed;
+ }
+}
+
+.prompt-btn-key {
+ margin-left: 6px;
+ font-size: var(--app-text-sm);
+ opacity: 0.75;
+}
diff --git a/frontend/src/views/chat/index.vue b/frontend/src/views/chat/index.vue
index cd75f8c73..6ce5454ac 100644
--- a/frontend/src/views/chat/index.vue
+++ b/frontend/src/views/chat/index.vue
@@ -160,6 +160,7 @@
<t-icon name="chevron-down" size="18px" />
</div>
</transition>
+ <PendingPromptDock :embedded-mode="embeddedMode" />
<InputField ref="inputFieldRef" :auto-focus="focusComposerOnMount" :compact="!embeddedMode"
@send-msg="(query, modelId, mentionedItems, imageFiles, attachmentFiles, options) => sendMsg(query, modelId, mentionedItems, imageFiles, attachmentFiles, options)"
@steer-msg="(query, mentionedItems, delivery) => handleSteerMsg(query, mentionedItems, delivery)"
@@ -196,7 +197,7 @@
<script setup>
import { makeSteerClientId } from '@/utils/steerId';
import { storeToRefs } from 'pinia';
-import { ref, onMounted, onBeforeMount, onUnmounted, nextTick, watch, reactive, computed } from 'vue';
+import { ref, onMounted, onBeforeMount, onUnmounted, nextTick, watch, reactive, computed, provide } from 'vue';
import { useRoute, useRouter, onBeforeRouteLeave, onBeforeRouteUpdate } from 'vue-router';
import InputField from '../../components/Input-field.vue';
import botmsg from './components/botmsg.vue';
@@ -211,6 +212,7 @@ import { deleteTemporaryAttachment, uploadTemporaryAttachment } from '@/api/chat
import { useStream } from '../../api/chat/streame'
import { listSteerSession, promoteSteerSession, removeSteerSession, steerSession } from '@/api/chat/steer';
import { persistedAssistantId, previewSteerMessage, discardSteerPreview, reconcileSteerMessageId } from '@/utils/steerStreamFork';
+import { resumeSuspendedRunKey } from '@/utils/suspendedRun';
import { useMenuStore } from '@/stores/menu';
import { useSettingsStore } from '@/stores/settings';
import { useBrowserConnectionStore } from '@/stores/browserConnection';
@@ -219,7 +221,7 @@ import { useI18n } from 'vue-i18n';
import { useUIStore } from '@/stores/ui';
import KnowledgeBaseEditorModal from '@/views/knowledge/KnowledgeBaseEditorModal.vue';
import { useKnowledgeBaseCreationNavigation } from '@/hooks/useKnowledgeBaseCreationNavigation';
-import { useChatStreamHandler } from '@/composables/useChatStreamHandler';
+import { useChatStreamHandler, isAwaitingInput, isPromptCard } from '@/composables/useChatStreamHandler';
import { useStickyBottomOnResize } from '@/composables/useStickyBottomOnResize';
import { clearCitationChunkCache } from '@/utils/citationChunkCache';
import ChatReferencesDrawer from '@/components/ChatReferencesDrawer.vue';
@@ -244,6 +246,8 @@ import { useSessionActivityStore } from '@/stores/sessionActivity';
import { provideChatSandboxPanel } from '@/composables/useChatSandboxPanel';
import SandboxSidePanel from '@/components/chat/SandboxSidePanel.vue';
import BrowserTaskPreview from './components/BrowserTaskPreview.vue';
+import PendingPromptDock from './components/PendingPromptDock.vue';
+import { providePromptDock } from '@/composables/usePromptDock';
import { collectSessionArtifacts, markSessionArtifactDeleted } from '@/utils/sessionArtifacts';
import { isCollectingSkillArtifacts } from '@/utils/skillArtifacts';
const referencesDrawer = provideChatReferencesDrawer();
@@ -329,6 +333,7 @@ const inputFieldRef = ref();
const created_at = ref('');
const limit = ref(20);
const messagesList = reactive([]);
+providePromptDock(messagesList);
function forkAffordanceOf(messageId) {
if (!messageId) return { canFork: false }
@@ -711,6 +716,7 @@ const loadFollowUpSuggestions = async (message, ensure = false, regenerate = fal
const messageId = resolveAssistantMessageId(message);
const targetSessionId = session_id.value;
if (!messageId || !targetSessionId || message.suggestionsDismissed) return;
+ if (isAwaitingInput(message)) return;
message.suggestionLoading = true;
try {
let response = ensure
@@ -925,6 +931,7 @@ const {
handleMsgList,
processStreamChunk,
prepareForNewOutgoingMessage,
+ prepareResumedMessage,
markInFlightAssistantStopped,
} = useChatStreamHandler({
messagesList,
@@ -1302,7 +1309,7 @@ const attachSteerFollowUp = async (completedAssistantId) => {
if (sessionChanged()) return;
const batch = res?.data || [];
const newAssistant = [...batch].reverse().find((m) =>
- m.role === 'assistant' && !m.is_completed && m.id && m.id !== completedAssistantId
+ m.role === 'assistant' && !m.is_completed && !isAwaitingInput(m) && m.id && m.id !== completedAssistantId
);
if (newAssistant) {
// The follow-up run persists its query under its own
@@ -1609,8 +1616,48 @@ const recoverIncompleteMessage = () => {
};
// Watch for stream errors and show message
+// Answering a suspended prompt resumes its run on the server; follow it on
+// the same assistant message. The resumed stream may not exist yet when the
+// answer returns, so attaching retries briefly.
+let attachingResumedRun = false;
+const resumeSuspendedRun = async (pendingId) => {
+ const sessionId = session_id.value;
+ const message = findLastMessage((m) => m.role === 'assistant' && (m.agentEventStream || []).some(
+ (e) => isPromptCard(e) && e.pending_id === pendingId,
+ ));
+ if (!message || !sessionId || isReplying.value) return;
+ const resumeId = persistedAssistantId(message);
+ prepareResumedMessage(message, pendingId);
+ isReplying.value = true;
+ currentAssistantMessageId.value = resumeId;
+ attachingResumedRun = true;
+ try {
+ for (let attempt = 0; attempt < 10; attempt++) {
+ await new Promise((resolve) => setTimeout(resolve, 500));
+ if (session_id.value !== sessionId) return;
+ await startStream({
+ session_id: sessionId,
+ query: resumeId,
+ method: 'GET',
+ url: '/api/v1/sessions/continue-stream',
+ });
+ if (!error.value) return;
+ }
+ } finally {
+ attachingResumedRun = false;
+ }
+ if (error.value && session_id.value === sessionId) {
+ MessagePlugin.error(error.value);
+ isReplying.value = false;
+ loading.value = false;
+ currentAssistantMessageId.value = '';
+ }
+};
+provide(resumeSuspendedRunKey, resumeSuspendedRun);
+
watch(error, (newError) => {
if (!newError) return;
+ if (attachingResumedRun) return;
// A failed attach to an in-flight IM reply isn't a real error — the answer is
// produced on the IM side and never streams here. Recover quietly by polling to
// completion instead of flashing a "stream failed" toast. Web/api replies fall
diff --git a/frontend/src/views/embed/EmbedChatCore.vue b/frontend/src/views/embed/EmbedChatCore.vue
index 1a8dcbd0f..afac806ad 100644
--- a/frontend/src/views/embed/EmbedChatCore.vue
+++ b/frontend/src/views/embed/EmbedChatCore.vue
@@ -100,6 +100,14 @@
</transition>
<div class="embed-chat__input">
+ <PendingPromptDock
+ embedded-mode
+ :embed-channel-id="channelId"
+ :embed-token="token"
+ :embed-session-id="sessionId"
+ :embed-session-sig="sessionSig"
+ :embed-visitor-id="visitorId"
+ />
<EmbedInputField
:isReplying="isReplying"
:show-web-search-toggle="showWebSearchToggle"
@@ -128,8 +136,11 @@ import EmbedInputField from '@/components/EmbedInputField.vue'
import EmbedBotMessage from '@/views/embed/EmbedBotMessage.vue'
import EmbedUserMessage from '@/views/embed/EmbedUserMessage.vue'
import ChatReferencesDrawer from '@/components/ChatReferencesDrawer.vue'
+import PendingPromptDock from '@/views/chat/components/PendingPromptDock.vue'
+import { providePromptDock } from '@/composables/usePromptDock'
import { provideChatReferencesDrawer } from '@/composables/useChatReferencesDrawer'
import { useEmbedChatSession } from '@/composables/useEmbedChatSession'
+import { isAwaitingInput } from '@/composables/useChatStreamHandler'
import FollowUpSuggestions from '@/components/chat/FollowUpSuggestions.vue'
import MessageTimestamp from '@/components/chat/MessageTimestamp.vue'
import { shouldShowConversationTimestamp } from '@/utils/messageTimestamp'
@@ -179,6 +190,7 @@ const loadFollowUpSuggestions = async (
const messageId = String(message.id || message.assistant_message_id || '')
const targetSessionId = props.sessionId
if (!props.showSuggestedQuestions || !messageId || !targetSessionId || message.suggestionsDismissed) return
+ if (isAwaitingInput(message)) return
message.suggestionLoading = true
try {
let response = ensure
@@ -293,6 +305,7 @@ const {
onTurnComplete: (message) => { void loadFollowUpSuggestions(message, true) },
onMessagesLoaded: loadPersistedFollowUps,
})
+providePromptDock(messagesList)
const welcomeText = computed(() => props.welcomeMessage?.trim() || '')
const hasWelcomeText = computed(() => welcomeText.value.length > 0)
@@ -550,6 +563,10 @@ watch(
box-sizing: border-box;
}
+.embed-chat__input :deep(.prompt-dock) {
+ max-width: 800px;
+}
+
.msg-skeleton-list {
display: flex;
flex-direction: column;
diff --git a/internal/agent/act.go b/internal/agent/act.go
index f8b283b13..d7b0208c2 100644
--- a/internal/agent/act.go
+++ b/internal/agent/act.go
@@ -176,6 +176,7 @@ var toolDisplayNames = map[string]string{
agenttools.LegacyToolListKnowledgeChunks: "查看文档分块",
agenttools.LegacyToolGetDocumentInfo: "获取文档信息",
agenttools.ToolSearchConversations: "回顾历史对话",
+ agenttools.ToolAskUser: "向用户提问",
agenttools.ToolSearchMemory: "查询长期记忆",
agenttools.ToolDatabaseQuery: "查询数据",
agenttools.ToolDataAnalysis: "数据分析",
@@ -223,12 +224,15 @@ func formatToolHint(name string, args map[string]any) string {
// executeToolCalls runs every tool call in the LLM response, appending results to step.ToolCalls.
// It also emits tool-call and tool-result events, and optionally runs reflection after each call.
// When ParallelToolCalls is enabled and there are 2+ tool calls, they execute concurrently.
+//
+// A call that suspends on a user prompt stops the round: it and the calls
+// after it do not run and are not appended, and the suspension is returned.
func (e *AgentEngine) executeToolCalls(
ctx context.Context, response *types.ChatResponse,
step *types.AgentStep, iteration int, sessionID, assistantMessageID string,
-) {
+) *types.PromptSuspension {
if len(response.ToolCalls) == 0 {
- return
+ return nil
}
round := iteration + 1
@@ -243,20 +247,22 @@ func (e *AgentEngine) executeToolCalls(
"refusing %d tool call(s) with possibly truncated arguments",
round, response.FinishReason, n)
e.failTruncatedToolCalls(ctx, response, step, iteration, sessionID)
- return
+ return nil
}
logger.Infof(ctx, "[Agent][Round-%d] Executing %d tool call(s)", round, n)
// Use parallel execution when enabled and there are multiple tool calls
if e.config.ParallelToolCalls && n >= 2 {
- e.executeToolCallsParallel(ctx, response, step, iteration, sessionID, assistantMessageID)
- return
+ return e.executeToolCallsParallel(ctx, response, step, iteration, sessionID, assistantMessageID)
}
for i, tc := range response.ToolCalls {
- e.executeSingleToolCall(ctx, tc, i, step, iteration, round, sessionID, assistantMessageID)
+ if s := e.executeSingleToolCall(ctx, tc, i, step, iteration, round, sessionID, assistantMessageID); s != nil {
+ return s
+ }
}
+ return nil
}
// truncatedArgumentsError is handed to the model instead of a tool result when
@@ -293,7 +299,7 @@ func (e *AgentEngine) failTruncatedToolCalls(
func (e *AgentEngine) executeToolCallsParallel(
ctx context.Context, response *types.ChatResponse,
step *types.AgentStep, iteration int, sessionID, assistantMessageID string,
-) {
+) *types.PromptSuspension {
round := iteration + 1
n := len(response.ToolCalls)
logger.Infof(ctx, "[Agent][Round-%d] Parallel execution of %d tool calls", round, n)
@@ -310,6 +316,12 @@ func (e *AgentEngine) executeToolCallsParallel(
// before starting later reads. Preserve model order across barriers.
_ = g.Wait()
results[i] = e.runToolCall(ctx, tc, i, iteration, round, sessionID, assistantMessageID)
+ if s := suspensionOf(results[i]); s != nil {
+ // Everything before the barrier has finished; keep it.
+ e.appendToolOutcomes(ctx, step, results[:i], iteration, sessionID)
+ return s
+ }
+ e.recordCall(i, results[i])
g, gCtx = errgroup.WithContext(ctx)
g.SetLimit(8)
continue
@@ -326,20 +338,30 @@ func (e *AgentEngine) executeToolCallsParallel(
mu.Lock()
results[i] = panickedToolCall(tc, i)
mu.Unlock()
+ e.recordCall(i, results[i])
}
}()
toolCall := e.runToolCall(readCtx, tc, i, iteration, round, sessionID, assistantMessageID)
mu.Lock()
results[i] = toolCall
mu.Unlock()
+ e.recordCall(i, toolCall)
return nil // best-effort: don't cancel siblings on failure
})
}
_ = g.Wait()
- // Append results and emit events in original order
- for _, toolCall := range results {
+ e.appendToolOutcomes(ctx, step, results, iteration, sessionID)
+ return nil
+}
+
+// appendToolOutcomes appends finished calls to step and emits their events
+// in original order.
+func (e *AgentEngine) appendToolOutcomes(
+ ctx context.Context, step *types.AgentStep, calls []types.ToolCall, iteration int, sessionID string,
+) {
+ for _, toolCall := range calls {
step.ToolCalls = append(step.ToolCalls, toolCall)
e.emitToolOutcome(ctx, toolCall, iteration, sessionID)
}
@@ -404,13 +426,20 @@ func (e *AgentEngine) emitToolOutcome(
}
// executeSingleToolCall runs one tool call sequentially (original behavior).
+// A call suspended on a user prompt is not appended; its suspension is
+// returned instead.
func (e *AgentEngine) executeSingleToolCall(
ctx context.Context, tc types.LLMToolCall, i int,
step *types.AgentStep, iteration, round int, sessionID, assistantMessageID string,
-) {
+) *types.PromptSuspension {
toolCall := e.runToolCall(ctx, tc, i, iteration, round, sessionID, assistantMessageID)
+ if s := suspensionOf(toolCall); s != nil {
+ return s
+ }
+ e.recordCall(i, toolCall)
step.ToolCalls = append(step.ToolCalls, toolCall)
e.emitToolOutcome(ctx, toolCall, iteration, sessionID)
+ return nil
}
// runToolCall handles argument parsing, execution, logging, and pipeline events for a single tool call.
@@ -418,6 +447,15 @@ func (e *AgentEngine) executeSingleToolCall(
func (e *AgentEngine) runToolCall(
ctx context.Context, tc types.LLMToolCall, i int,
iteration, round int, sessionID, assistantMessageID string,
+) types.ToolCall {
+ return e.runToolCallAnswered(ctx, tc, i, iteration, round, sessionID, assistantMessageID, nil)
+}
+
+// runToolCallAnswered is runToolCall for a call whose prompt may already be
+// answered (see ToolExecContext.Answered).
+func (e *AgentEngine) runToolCallAnswered(
+ ctx context.Context, tc types.LLMToolCall, i int,
+ iteration, round int, sessionID, assistantMessageID string, answered *types.AgentPrompt,
) types.ToolCall {
tc.ID = agenttools.NormalizeToolCallID(tc.ID, tc.Function.Name, i)
total := "?" // unknown in isolation; callers log the batch size
@@ -572,6 +610,9 @@ func (e *AgentEngine) runToolCall(
// so MCP tool human-approval (issue #1173) can legitimately block longer.
ApprovalCtx: toolCtx,
ExecTimeout: execTimeout,
+ Snapshot: e.snapshotFunc(i),
+ Answered: answered,
+ Interactive: e.interactive,
})
var result *types.ToolResult
diff --git a/internal/agent/approval/ask_user.go b/internal/agent/approval/ask_user.go
new file mode 100644
index 000000000..0a688aac5
--- /dev/null
+++ b/internal/agent/approval/ask_user.go
@@ -0,0 +1,200 @@
+package approval
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/agent/hitl"
+ "github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// AskRequest raises an ask_user prompt.
+type AskRequest struct {
+ TenantID uint64
+ UserID string
+ SessionID string
+ AssistantMessageID string
+ RequestID string
+ ToolCallID string
+ EventBus *event.EventBus
+ Question types.AskUserPromptRequest
+ // Snapshot, when set, lets the run suspend after the hot wait.
+ Snapshot []byte
+ SnapshotVersion int
+}
+
+// Answer is how an ask_user prompt ended.
+type Answer struct {
+ owner string
+ answered bool
+ PromptID string
+ Answered bool
+ Response types.AskUserPromptResponse
+ Reason string
+ TimedOut bool
+ Canceled bool
+ // Suspended is set when the run must end and wait for the answer.
+ Suspended *types.PromptSuspension
+}
+
+// UserAsker is the surface the ask_user tool uses (mockable in tests).
+type UserAsker interface {
+ AskUser(ctx context.Context, req AskRequest) (Answer, error)
+ // ResumeAnswer is the answer carried by the prompt a resumed run was
+ // suspended on.
+ ResumeAnswer(ctx context.Context, prompt *types.AgentPrompt, bus *event.EventBus) Answer
+}
+
+var _ UserAsker = (*Gate)(nil)
+
+// AskUser shows the question and waits for the answer, the timeout, or the
+// suspension of the run.
+func (g *Gate) AskUser(ctx context.Context, req AskRequest) (Answer, error) {
+ if g == nil {
+ return Answer{}, fmt.Errorf("ask user: nil gate")
+ }
+ if req.EventBus == nil {
+ return Answer{}, fmt.Errorf("ask user: EventBus is nil")
+ }
+ request, err := json.Marshal(req.Question)
+ if err != nil {
+ return Answer{}, fmt.Errorf("encode question: %w", err)
+ }
+ wait := g.timeout
+ var suspend *hitl.SuspendSpec
+ if req.Snapshot != nil {
+ wait = g.hotWait
+ suspend = &hitl.SuspendSpec{Snapshot: req.Snapshot, SnapshotVersion: req.SnapshotVersion}
+ }
+ out, err := g.broker.Await(ctx, hitl.Spec{
+ Suspend: suspend,
+ FallbackTimeout: g.timeout,
+ Prompt: &types.AgentPrompt{
+ TenantID: req.TenantID,
+ UserID: req.UserID,
+ SessionID: req.SessionID,
+ AssistantMessageID: req.AssistantMessageID,
+ RequestID: req.RequestID,
+ Kind: types.AgentPromptKindAskUser,
+ ToolCallID: req.ToolCallID,
+ Request: types.JSON(request),
+ },
+ Timeout: wait,
+ TimeoutReason: "no answer in time",
+ Emit: func(ctx context.Context, p *types.AgentPrompt) error {
+ waitSec := promptWaitSeconds(p, wait, g.timeout)
+ return req.EventBus.Emit(ctx, event.Event{
+ ID: p.ID + "-prompt-required",
+ Type: event.EventAgentPromptRequired,
+ SessionID: req.SessionID,
+ Data: event.AgentPromptRequiredData{
+ PendingID: p.ID,
+ Kind: types.AgentPromptKindAskUser,
+ SessionID: req.SessionID,
+ AssistantMessageID: req.AssistantMessageID,
+ Request: request,
+ TimeoutSeconds: waitSec,
+ HotWaitSeconds: waitSec,
+ Suspendable: p.Suspendable,
+ RequestedAtUnix: time.Now().Unix(),
+ ToolCallID: req.ToolCallID,
+ RequestID: req.RequestID,
+ },
+ Metadata: map[string]interface{}{
+ "assistant_message_id": req.AssistantMessageID,
+ "pending_id": p.ID,
+ },
+ RequestID: req.RequestID,
+ })
+ },
+ })
+ if err != nil {
+ return Answer{}, fmt.Errorf("ask user: %w", err)
+ }
+ if out.Suspended {
+ return Answer{
+ PromptID: out.Prompt.ID,
+ Suspended: &types.PromptSuspension{
+ Detached: out.Detached,
+ PromptID: out.Prompt.ID,
+ Kind: types.AgentPromptKindAskUser,
+ ExpiresAt: out.ExpiresAt,
+ },
+ }, nil
+ }
+ a := askAnswer(out)
+ g.consumeAnswer(ctx, &a, req.EventBus, req.SessionID, req.AssistantMessageID, req.RequestID)
+ return a, nil
+}
+
+// ResumeAnswer implements UserAsker.
+func (g *Gate) ResumeAnswer(ctx context.Context, prompt *types.AgentPrompt, bus *event.EventBus) Answer {
+ a := askAnswer(hitl.Outcome{Prompt: prompt, Answered: true})
+ g.consumeAnswer(ctx, &a, bus, prompt.SessionID, prompt.AssistantMessageID, prompt.RequestID)
+ return a
+}
+
+func (g *Gate) consumeAnswer(
+ ctx context.Context, a *Answer, bus *event.EventBus, sessionID, assistantMessageID, requestID string,
+) {
+ consumed, consumeErr := g.broker.Consume(ctx, a.PromptID, types.AgentPromptDone, a.owner)
+ if !consumed && a.answered {
+ a.Answered = false
+ a.Response = types.AskUserPromptResponse{}
+ a.Reason = "answer is no longer owned or was already consumed"
+ if consumeErr == nil {
+ a.Suspended = &types.PromptSuspension{
+ PromptID: a.PromptID, Kind: types.AgentPromptKindAskUser, Detached: true,
+ }
+ return
+ }
+ a.Reason = "could not confirm the user answer"
+ }
+ if bus == nil {
+ return
+ }
+ var response json.RawMessage
+ if a.Answered {
+ response, _ = json.Marshal(a.Response)
+ }
+ _ = bus.Emit(context.WithoutCancel(ctx), event.Event{
+ ID: a.PromptID + "-prompt-resolved",
+ Type: event.EventAgentPromptResolved,
+ SessionID: sessionID,
+ Data: event.AgentPromptResolvedData{
+ PendingID: a.PromptID,
+ Kind: types.AgentPromptKindAskUser,
+ Answered: a.Answered,
+ Response: response,
+ Reason: a.Reason,
+ TimedOut: a.TimedOut,
+ Canceled: a.Canceled,
+ },
+ Metadata: map[string]interface{}{
+ "assistant_message_id": assistantMessageID,
+ },
+ RequestID: requestID,
+ })
+}
+
+func askAnswer(out hitl.Outcome) Answer {
+ a := Answer{
+ owner: out.Prompt.OwnerInstance, answered: out.Answered, PromptID: out.Prompt.ID,
+ Reason: out.Reason, TimedOut: out.TimedOut, Canceled: out.Canceled,
+ }
+ if !out.Answered {
+ return a
+ }
+ if err := json.Unmarshal(out.Prompt.Response, &a.Response); err != nil {
+ a.Reason = "unreadable answer"
+ return a
+ }
+ a.Answered = !a.Response.Declined
+ if a.Response.Declined {
+ a.Reason = "the user declined to answer"
+ }
+ return a
+}
diff --git a/internal/agent/approval/ask_user_test.go b/internal/agent/approval/ask_user_test.go
new file mode 100644
index 000000000..ae6cffc4d
--- /dev/null
+++ b/internal/agent/approval/ask_user_test.go
@@ -0,0 +1,114 @@
+package approval
+
+import (
+ "context"
+ "encoding/json"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+
+ "github.com/Tencent/WeKnora/internal/agent/hitl"
+ "github.com/Tencent/WeKnora/internal/config"
+ "github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+func askRequest(bus *event.EventBus) AskRequest {
+ return AskRequest{
+ TenantID: 1, UserID: "user:u1", SessionID: "s1", AssistantMessageID: "m1", ToolCallID: "tc1",
+ EventBus: bus,
+ Question: types.AskUserPromptRequest{Question: "which env?", Options: []string{"dev", "prod"}},
+ }
+}
+
+func answerPrompt(g *Gate, id, response string) (hitl.Resolution, error) {
+ return g.ResolveResponse(context.Background(), hitl.ResolveRequest{
+ TenantID: 1, UserID: "user:u1", SessionID: "s1", Kind: types.AgentPromptKindAskUser,
+ PromptID: id, Response: json.RawMessage(response),
+ })
+}
+
+func TestGate_AskUserAnsweredLive(t *testing.T) {
+ bus := event.NewEventBus()
+ g := NewGate(&config.Config{Agent: &config.AgentConfig{ToolApprovalTimeoutSeconds: 5}}, nil, nil)
+ invalid := make(chan error, 1)
+ bus.On(event.EventAgentPromptRequired, func(_ context.Context, evt event.Event) error {
+ data := evt.Data.(event.AgentPromptRequiredData)
+ assert.Equal(t, types.AgentPromptKindAskUser, data.Kind)
+ assert.JSONEq(t, `{"question":"which env?","options":["dev","prod"]}`, string(data.Request))
+ assert.False(t, data.Suspendable)
+ go func() {
+ _, err := answerPrompt(g, data.PendingID, `{"selected":["staging"]}`)
+ invalid <- err
+ _, _ = answerPrompt(g, data.PendingID, `{"selected":["prod"]}`)
+ }()
+ return nil
+ })
+ var resolved event.AgentPromptResolvedData
+ bus.On(event.EventAgentPromptResolved, func(_ context.Context, evt event.Event) error {
+ resolved = evt.Data.(event.AgentPromptResolvedData)
+ return nil
+ })
+
+ a, err := g.AskUser(context.Background(), askRequest(bus))
+ require.NoError(t, err)
+ require.ErrorIs(t, <-invalid, ErrInvalidDecision, "an answer outside the options is rejected")
+ require.True(t, a.Answered)
+ assert.Equal(t, []string{"prod"}, a.Response.Selected)
+ assert.True(t, resolved.Answered)
+ assert.JSONEq(t, `{"selected":["prod"]}`, string(resolved.Response))
+
+ row, err := g.broker.Store().Get(context.Background(), a.PromptID)
+ require.NoError(t, err)
+ assert.Equal(t, types.AgentPromptDone, row.Status)
+}
+
+func TestGate_AskUserDeclined(t *testing.T) {
+ bus := event.NewEventBus()
+ g := NewGate(&config.Config{Agent: &config.AgentConfig{ToolApprovalTimeoutSeconds: 5}}, nil, nil)
+ bus.On(event.EventAgentPromptRequired, func(_ context.Context, evt event.Event) error {
+ id := evt.Data.(event.AgentPromptRequiredData).PendingID
+ go func() { _, _ = answerPrompt(g, id, `{"declined":true}`) }()
+ return nil
+ })
+ a, err := g.AskUser(context.Background(), askRequest(bus))
+ require.NoError(t, err)
+ assert.False(t, a.Answered)
+ assert.Contains(t, a.Reason, "declined")
+}
+
+func TestGate_AskUserSuspendsThenResumes(t *testing.T) {
+ g := NewGate(&config.Config{Agent: &config.AgentConfig{
+ ToolApprovalTimeoutSeconds: 60, PromptHotWaitSeconds: 1,
+ }}, nil, nil)
+ req := askRequest(event.NewEventBus())
+ req.Snapshot, req.SnapshotVersion = []byte(`{"version":1}`), 1
+ a, err := g.AskUser(context.Background(), req)
+ require.NoError(t, err)
+ require.NotNil(t, a.Suspended)
+ assert.Equal(t, types.AgentPromptKindAskUser, a.Suspended.Kind)
+
+ _, err = g.ResolveResponse(context.Background(), hitl.ResolveRequest{
+ TenantID: 1, UserID: "user:someone-else", SessionID: "s1", Kind: types.AgentPromptKindAskUser,
+ PromptID: a.PromptID, Response: json.RawMessage(`{"selected":["dev"]}`),
+ })
+ require.ErrorIs(t, err, ErrUserMismatch)
+
+ res, err := answerPrompt(g, a.PromptID, `{"selected":["dev"]}`)
+ require.NoError(t, err)
+ require.True(t, res.Resume)
+
+ got := g.ResumeAnswer(context.Background(), res.Prompt, event.NewEventBus())
+ require.True(t, got.Answered)
+ assert.Equal(t, []string{"dev"}, got.Response.Selected)
+}
+
+func TestGate_ResolveResponseRefusesOAuth(t *testing.T) {
+ g := NewGate(nil, nil, nil)
+ _, err := g.ResolveResponse(context.Background(), hitl.ResolveRequest{
+ TenantID: 1, UserID: "user:u1", Kind: types.AgentPromptKindMCPOAuth,
+ PromptID: "p1", Response: json.RawMessage(`{"authorized":true}`),
+ })
+ require.ErrorIs(t, err, ErrInvalidDecision)
+}
diff --git a/internal/agent/approval/consume_failure_test.go b/internal/agent/approval/consume_failure_test.go
new file mode 100644
index 000000000..a11abf562
--- /dev/null
+++ b/internal/agent/approval/consume_failure_test.go
@@ -0,0 +1,100 @@
+package approval
+
+import (
+ "context"
+ "errors"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/agent/hitl"
+ "github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+)
+
+type consumeFailureStore struct{ hitl.Store }
+
+func (s consumeFailureStore) Transition(ctx context.Context, id string, tr types.AgentPromptTransition) (bool, error) {
+ if tr.To == types.AgentPromptExecuting || tr.To == types.AgentPromptDone {
+ return false, errors.New("consume unavailable")
+ }
+ return s.Store.Transition(ctx, id, tr)
+}
+
+func TestConsumeFailureDoesNotDetachOrAuthorizeRun(t *testing.T) {
+ for _, kind := range []string{types.AgentPromptKindToolApproval, types.AgentPromptKindAskUser} {
+ t.Run(kind, func(t *testing.T) {
+ ctx := t.Context()
+ store := consumeFailureStore{hitl.NewMemoryStore()}
+ g := NewGate(nil, nil, hitl.NewBroker(store, nil))
+ response := types.JSON(`{"approved":true,"modified_args":{"dangerous":true}}`)
+ if kind == types.AgentPromptKindAskUser {
+ response = types.JSON(`{"text":"staging"}`)
+ }
+ prompt := &types.AgentPrompt{
+ ID: "p", Kind: kind, Status: types.AgentPromptAnswered, OwnerInstance: "owner", Response: response,
+ }
+ require.NoError(t, store.Create(ctx, prompt))
+ bus := event.NewEventBus()
+ var emitted bool
+ bus.On(event.EventToolApprovalResolved, func(_ context.Context, e event.Event) error {
+ emitted = true
+ require.False(t, e.Data.(event.ToolApprovalResolvedData).Approved)
+ return nil
+ })
+ bus.On(event.EventAgentPromptResolved, func(_ context.Context, e event.Event) error {
+ emitted = true
+ require.False(t, e.Data.(event.AgentPromptResolvedData).Answered)
+ return nil
+ })
+ if kind == types.AgentPromptKindToolApproval {
+ decision := g.ResumeDecision(ctx, prompt, bus)
+ require.False(t, decision.Approved)
+ require.Empty(t, decision.ModifiedArgs)
+ require.Nil(t, decision.Suspended,
+ "storage failure must complete normally, not detach and strand the message")
+ require.Contains(t, decision.Reason, "could not confirm")
+ } else {
+ answer := g.ResumeAnswer(ctx, prompt, bus)
+ require.False(t, answer.Answered)
+ require.Empty(t, answer.Response)
+ require.Nil(t, answer.Suspended)
+ require.Contains(t, answer.Reason, "could not confirm")
+ }
+ require.True(t, emitted, "the client must learn that the interaction ended")
+ row, err := store.Get(ctx, "p")
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptFailed, row.Status)
+ })
+ }
+}
+
+func TestOAuthConsumeFailureReportsFailureWithoutRetryingTool(t *testing.T) {
+ ctx := t.Context()
+ store := consumeFailureStore{hitl.NewMemoryStore()}
+ g := NewGate(nil, nil, hitl.NewBroker(store, nil))
+ bus := event.NewEventBus()
+ var promptID string
+ var emitted bool
+ bus.On(event.EventMCPOAuthRequired, func(_ context.Context, e event.Event) error {
+ promptID = e.Data.(event.MCPOAuthRequiredData).PendingID
+ return g.Resolve(ctx, ResolveRequest{
+ TenantID: 1, PendingID: promptID, Kind: types.AgentPromptKindMCPOAuth, Decision: Decision{Approved: true},
+ })
+ })
+ bus.On(event.EventMCPOAuthResolved, func(_ context.Context, e event.Event) error {
+ emitted = true
+ require.False(t, e.Data.(event.MCPOAuthResolvedData).Authorized)
+ return nil
+ })
+ decision, err := g.RequestOAuthAndWait(ctx, OAuthPendingRequest{
+ TenantID: 1, SessionID: "s", ServiceID: "svc", EventBus: bus, WaitTimeout: time.Second,
+ })
+ require.NoError(t, err)
+ require.False(t, decision.Approved)
+ require.Contains(t, decision.Reason, "could not confirm")
+ require.True(t, emitted)
+ row, err := store.Get(ctx, promptID)
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptFailed, row.Status)
+}
diff --git a/internal/agent/approval/gate.go b/internal/agent/approval/gate.go
index a8fdcb6f7..6307d8eea 100644
--- a/internal/agent/approval/gate.go
+++ b/internal/agent/approval/gate.go
@@ -1,72 +1,27 @@
// Package approval implements human-in-the-loop gating for dangerous MCP tool calls (issue #1173).
+//
+// Gate owns the per-tool policy (enabled / requires approval) and adapts tool
+// approvals and in-conversation MCP OAuth to the generic prompt broker in
+// package hitl, which handles persistence, waiting and cross-replica resolve.
package approval
import (
+ "bytes"
"context"
"encoding/json"
"errors"
"fmt"
"os"
"strings"
- "sync"
- "sync/atomic"
"time"
+ "github.com/Tencent/WeKnora/internal/agent/hitl"
"github.com/Tencent/WeKnora/internal/config"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/logger"
- "github.com/google/uuid"
- "github.com/redis/go-redis/v9"
+ "github.com/Tencent/WeKnora/internal/types"
)
-// pubsubChannelBase is the Redis channel prefix used to fan-out Resolve calls
-// across backend replicas (issue #1173 cross-instance support). The actual
-// channel is suffixed with WEKNORA_REDIS_NAMESPACE (when set) so multiple
-// deployments sharing the same Redis don't cross-talk.
-const pubsubChannelBase = "weknora:mcp_approval:resolve"
-
-// instanceID is a process-unique id used to ignore self-published pubsub
-// messages (avoids "pending not found" log noise on the publisher side).
-var instanceID = uuid.New().String()
-
-// resolveMessage is the JSON payload published when one instance receives a
-// Resolve API call but the pending wait may live on another instance.
-type resolveMessage struct {
- TenantID uint64 `json:"tenant_id"`
- UserID string `json:"user_id,omitempty"`
- PendingID string `json:"pending_id"`
- Approved bool `json:"approved"`
- ModifiedArgs json.RawMessage `json:"modified_args,omitempty"`
- Reason string `json:"reason,omitempty"`
- TimedOut bool `json:"timed_out,omitempty"`
- Canceled bool `json:"canceled,omitempty"`
- // ReplyChannel, when non-empty, asks the owning instance to publish a
- // resolveAck so the caller can know if delivery actually happened.
- ReplyChannel string `json:"reply_channel,omitempty"`
- OriginID string `json:"origin_id,omitempty"`
- // RequestNonce uniquely identifies this Resolve call. The owning
- // instance echoes it back in resolveAck so concurrent Resolve callers
- // for the same pendingID don't consume each other's acks.
- RequestNonce string `json:"request_nonce,omitempty"`
-}
-
-// resolveAck is published by the owning instance back to the caller's
-// per-pending reply channel so HTTP semantics stay accurate cross-instance.
-type resolveAck struct {
- PendingID string `json:"pending_id"`
- Status string `json:"status"` // ok | not_found | tenant_mismatch | user_mismatch | already_resolved
- OriginID string `json:"origin_id,omitempty"`
- RequestNonce string `json:"request_nonce,omitempty"`
-}
-
-// pubsubChannel returns the namespaced pubsub channel name.
-func pubsubChannel() string {
- if ns := strings.TrimSpace(os.Getenv("WEKNORA_REDIS_NAMESPACE")); ns != "" {
- return pubsubChannelBase + ":" + ns
- }
- return pubsubChannelBase
-}
-
// Checker answers per-tool MCP policy questions used during registration and execution.
type Checker interface {
IsRequired(ctx context.Context, tenantID uint64, serviceID, toolName string) (bool, error)
@@ -75,11 +30,19 @@ type Checker interface {
// Decision is the outcome of a pending tool approval.
type Decision struct {
+ owner string // execution token of the waiter or resumed run
+ answered bool
+ // PendingID identifies the prompt the decision belongs to; callers that
+ // execute an approved call report back with MarkExecuted(PendingID).
+ PendingID string
Approved bool
ModifiedArgs json.RawMessage // optional JSON object; when set and Approved, replaces original args
Reason string
TimedOut bool
ContextCanceled bool
+ // Suspended is set when no decision arrived during the in-memory wait
+ // and the prompt now outlives the run; the call must not execute.
+ Suspended *types.PromptSuspension
}
// PendingRequest carries everything needed to block and notify the UI.
@@ -97,6 +60,10 @@ type PendingRequest struct {
Description string
Args json.RawMessage
ToolCallID string
+ // Snapshot, when set, is the run state to resume from: the wait is cut
+ // to the hot-wait window and then suspends instead of timing out.
+ Snapshot []byte
+ SnapshotVersion int
}
// MCPApproval is the surface used by MCPTool (mockable in tests).
@@ -104,6 +71,12 @@ type MCPApproval interface {
NeedsApproval(ctx context.Context, tenantID uint64, serviceID, toolName string) bool
IsEnabled(ctx context.Context, tenantID uint64, serviceID, toolName string) (bool, error)
RequestAndWait(ctx context.Context, req PendingRequest) (Decision, error)
+ // ResumeDecision is the decision carried by the answered prompt a resumed
+ // run was suspended on.
+ ResumeDecision(ctx context.Context, prompt *types.AgentPrompt, bus *event.EventBus) Decision
+ // MarkExecuted records that an approved call has finished running, so an
+ // approval is never mistaken for one still in flight.
+ MarkExecuted(ctx context.Context, pendingID string)
}
// OAuthPendingRequest carries everything needed to prompt the user to authorize
@@ -125,166 +98,59 @@ type OAuthPendingRequest struct {
WaitTimeout time.Duration
}
+// ResolveRequest is a user decision on a tool approval or OAuth prompt.
+// SessionID, when set, must match the prompt. Kind selects how Decision is
+// encoded and must match the prompt; empty means a tool approval.
+type ResolveRequest struct {
+ TenantID uint64
+ UserID string
+ SessionID string
+ Kind string
+ PendingID string
+ Decision Decision
+}
+
var _ MCPApproval = (*Gate)(nil)
-// Gate coordinates wait/resolve for MCP tool approvals.
-//
-// Pending waiters live in-memory on the instance that started RequestAndWait.
-// When a redis client is supplied, Resolve calls hitting any replica are
-// published over Redis Pub/Sub so the owning instance can deliver the decision
-// (issue #1173 cross-instance support). Without redis, the gate degrades to
-// single-process behavior (deployments must use sticky sessions).
+// Gate applies per-tool MCP policy and raises approval / OAuth prompts.
type Gate struct {
- mu sync.Mutex
- pending map[string]*waiter
checker Checker
timeout time.Duration
- rdb *redis.Client // optional; nil disables cross-instance fan-out
- failClose bool // when true, NeedsApproval errors block (require approval) instead of skip
-}
-
-type waiter struct {
- ch chan Decision
- tenantID uint64
- userID string // empty means "skip user check"
- once sync.Once
- // resolved is atomic so deliverLocal can read it without holding g.mu
- // (deliver writes it from timer/ctx branches that don't take g.mu).
- resolved atomic.Bool
-}
-
-// deliver returns true when this call won the race and actually delivered the
-// decision; false when a previous deliver already happened. Callers can use
-// the return value to map to ErrAlreadyResolved for HTTP feedback.
-func (w *waiter) deliver(d Decision) bool {
- if w == nil {
- return false
- }
- delivered := false
- w.once.Do(func() {
- select {
- case w.ch <- d:
- w.resolved.Store(true)
- delivered = true
- default:
- }
- })
- return delivered
+ hotWait time.Duration // in-memory wait before a suspendable approval suspends the run
+ broker *hitl.Broker
+ failClose bool // when true, NeedsApproval errors block (require approval) instead of skip
}
+// Errors returned by Resolve; they alias the prompt broker's errors.
var (
- // ErrPendingNotFound is returned when Resolve is called with an unknown id.
- ErrPendingNotFound = errors.New("tool approval pending not found")
- // ErrTenantMismatch is returned when Resolve tenant does not match the pending request.
- ErrTenantMismatch = errors.New("workspace mismatch for tool approval")
- // ErrAlreadyResolved is returned when Resolve loses the race against a
- // timeout / cancellation: the waiter is still in the map but its decision
- // channel was already consumed by the timer/ctx branch.
- ErrAlreadyResolved = errors.New("tool approval already resolved")
- // ErrUserMismatch is returned when Resolve is invoked by a user that does
- // not own the originating session.
- ErrUserMismatch = errors.New("user mismatch for tool approval")
+ ErrPendingNotFound = hitl.ErrPromptNotFound
+ ErrTenantMismatch = hitl.ErrTenantMismatch
+ ErrAlreadyResolved = hitl.ErrAlreadyResolved
+ ErrUserMismatch = hitl.ErrUserMismatch
+ ErrInvalidDecision = hitl.ErrInvalidResponse
)
// NewGate builds a gate. checker may be nil (disables gating). cfg may be nil
-// (defaults apply). rdb may be nil (single-instance mode).
-func NewGate(cfg *config.Config, checker Checker, rdb *redis.Client) *Gate {
+// (defaults apply). broker may be nil (process-local prompts, single replica).
+func NewGate(cfg *config.Config, checker Checker, broker *hitl.Broker) *Gate {
timeout := 10 * time.Minute
- if cfg != nil && cfg.Agent != nil && cfg.Agent.ToolApprovalTimeoutSeconds > 0 {
- timeout = time.Duration(cfg.Agent.ToolApprovalTimeoutSeconds) * time.Second
+ hotWait := config.DefaultPromptHotWait
+ if cfg != nil && cfg.Agent != nil {
+ if cfg.Agent.ToolApprovalTimeoutSeconds > 0 {
+ timeout = time.Duration(cfg.Agent.ToolApprovalTimeoutSeconds) * time.Second
+ }
+ hotWait = cfg.Agent.PromptHotWait()
}
+ if broker == nil {
+ broker = hitl.NewBroker(nil, nil)
+ }
+ broker.RegisterKind(types.AgentPromptKindToolApproval, validateToolApprovalResponse)
+ broker.RegisterKind(types.AgentPromptKindMCPOAuth, validateMCPOAuthResponse)
+ broker.RegisterKind(types.AgentPromptKindAskUser, types.ValidateAskUserResponse)
// Default fail-close: if the checker errors, require approval (safer for a
// HITL feature). Set WEKNORA_AGENT_TOOL_APPROVAL_FAIL_OPEN=true to revert.
failClose := !strings.EqualFold(strings.TrimSpace(os.Getenv("WEKNORA_AGENT_TOOL_APPROVAL_FAIL_OPEN")), "true")
- g := &Gate{
- pending: make(map[string]*waiter),
- checker: checker,
- timeout: timeout,
- rdb: rdb,
- failClose: failClose,
- }
- if rdb != nil {
- go g.runSubscriber()
- }
- return g
-}
-
-// runSubscriber listens for cross-instance Resolve fan-outs and delivers
-// decisions to local waiters. Runs for the lifetime of the process.
-func (g *Gate) runSubscriber() {
- ctx := context.Background()
- channel := pubsubChannel()
- backoff := time.Second
- const maxBackoff = 30 * time.Second
- for {
- sub := g.rdb.Subscribe(ctx, channel)
- ch := sub.Channel()
- // Reset backoff once we have an active subscription.
- backoff = time.Second
- for msg := range ch {
- var m resolveMessage
- if err := json.Unmarshal([]byte(msg.Payload), &m); err != nil {
- logger.GetLogger(ctx).Warnf("mcp approval pubsub: bad payload: %v", err)
- continue
- }
- // Skip messages we published ourselves; they would always miss
- // locally and produce noisy ErrPendingNotFound.
- if m.OriginID == instanceID {
- continue
- }
- err := g.deliverLocal(m.TenantID, m.UserID, m.PendingID, Decision{
- Approved: m.Approved,
- ModifiedArgs: m.ModifiedArgs,
- Reason: m.Reason,
- TimedOut: m.TimedOut,
- ContextCanceled: m.Canceled,
- })
- // Reply to the originating instance so it can return accurate HTTP
- // status codes. Only the owning instance (or one that detects a
- // real conflict) replies; other replicas stay silent on NotFound.
- if m.ReplyChannel != "" {
- status := ""
- switch {
- case err == nil:
- status = "ok"
- case errors.Is(err, ErrTenantMismatch):
- status = "tenant_mismatch"
- case errors.Is(err, ErrUserMismatch):
- status = "user_mismatch"
- case errors.Is(err, ErrAlreadyResolved):
- status = "already_resolved"
- }
- if status != "" {
- ackPayload, _ := json.Marshal(resolveAck{
- PendingID: m.PendingID,
- Status: status,
- OriginID: instanceID,
- RequestNonce: m.RequestNonce,
- })
- pubCtx, pubCancel := context.WithTimeout(ctx, 2*time.Second)
- if pErr := g.rdb.Publish(pubCtx, m.ReplyChannel, ackPayload).Err(); pErr != nil {
- logger.GetLogger(ctx).Warnf("mcp approval pubsub reply: %v", pErr)
- }
- pubCancel()
- }
- }
- switch {
- case err == nil, errors.Is(err, ErrPendingNotFound):
- // Either delivered or this isn't the owning replica — quiet.
- default:
- logger.GetLogger(ctx).Warnf("mcp approval pubsub deliver: %v", err)
- }
- }
- _ = sub.Close()
- // Reconnect with capped exponential backoff if Redis hiccups.
- time.Sleep(backoff)
- if backoff < maxBackoff {
- backoff *= 2
- if backoff > maxBackoff {
- backoff = maxBackoff
- }
- }
- }
+ return &Gate{checker: checker, timeout: timeout, hotWait: hotWait, broker: broker, failClose: failClose}
}
// NeedsApproval returns whether execution should pause for human confirmation.
@@ -333,105 +199,154 @@ func (g *Gate) RequestAndWait(ctx context.Context, req PendingRequest) (Decision
return Decision{}, fmt.Errorf("tool approval: EventBus is nil")
}
- pendingID := uuid.New().String()
- w := &waiter{
- ch: make(chan Decision, 1),
- tenantID: req.TenantID,
- userID: req.UserID,
+ request, err := json.Marshal(types.ToolApprovalPromptRequest{
+ ServiceID: req.ServiceID,
+ ServiceName: req.ServiceName,
+ MCPToolName: req.MCPToolName,
+ RegisteredToolName: req.RegisteredToolName,
+ Description: req.Description,
+ Args: req.Args,
+ })
+ if err != nil {
+ return Decision{}, fmt.Errorf("encode tool approval: %w", err)
}
-
- g.mu.Lock()
- g.pending[pendingID] = w
- g.mu.Unlock()
-
- defer func() {
- g.mu.Lock()
- delete(g.pending, pendingID)
- g.mu.Unlock()
- }()
-
var argsObj interface{}
if len(req.Args) > 0 {
_ = json.Unmarshal(req.Args, &argsObj)
}
-
- timeoutSec := int(g.timeout / time.Second)
- if timeoutSec < 1 {
- timeoutSec = 1
+ wait := g.timeout
+ var suspend *hitl.SuspendSpec
+ if req.Snapshot != nil {
+ wait = g.hotWait
+ suspend = &hitl.SuspendSpec{Snapshot: req.Snapshot, SnapshotVersion: req.SnapshotVersion}
+ }
+ out, err := g.broker.Await(ctx, hitl.Spec{
+ Suspend: suspend,
+ FallbackTimeout: g.timeout,
+ Prompt: &types.AgentPrompt{
+ TenantID: req.TenantID,
+ UserID: req.UserID,
+ SessionID: req.SessionID,
+ AssistantMessageID: req.AssistantMessageID,
+ RequestID: req.RequestID,
+ Kind: types.AgentPromptKindToolApproval,
+ ToolCallID: req.ToolCallID,
+ Request: types.JSON(request),
+ },
+ Timeout: wait,
+ TimeoutReason: "approval timeout",
+ Emit: func(ctx context.Context, p *types.AgentPrompt) error {
+ timeoutSec := promptWaitSeconds(p, wait, g.timeout)
+ return req.EventBus.Emit(ctx, event.Event{
+ ID: p.ID + "-approval-required",
+ Type: event.EventToolApprovalRequired,
+ SessionID: req.SessionID,
+ Data: event.ToolApprovalRequiredData{
+ PendingID: p.ID,
+ TenantID: req.TenantID,
+ SessionID: req.SessionID,
+ AssistantMessageID: req.AssistantMessageID,
+ ServiceID: req.ServiceID,
+ ServiceName: req.ServiceName,
+ MCPToolName: req.MCPToolName,
+ RegisteredToolName: req.RegisteredToolName,
+ Description: req.Description,
+ Args: argsObj,
+ ArgsJSON: string(req.Args),
+ TimeoutSeconds: timeoutSec,
+ HotWaitSeconds: timeoutSec,
+ Suspendable: p.Suspendable,
+ RequestedAtUnix: time.Now().Unix(),
+ ToolCallID: req.ToolCallID,
+ RequestID: req.RequestID,
+ },
+ Metadata: map[string]interface{}{
+ "assistant_message_id": req.AssistantMessageID,
+ "pending_id": p.ID,
+ },
+ RequestID: req.RequestID,
+ })
+ },
+ })
+ if err != nil {
+ return Decision{}, fmt.Errorf("tool approval: %w", err)
+ }
+ if out.Suspended {
+ // Still open: the run ends here and the decision resumes it later.
+ return Decision{
+ PendingID: out.Prompt.ID,
+ Suspended: &types.PromptSuspension{
+ Detached: out.Detached,
+ PromptID: out.Prompt.ID,
+ Kind: types.AgentPromptKindToolApproval,
+ ExpiresAt: out.ExpiresAt,
+ },
+ }, nil
}
- evtData := event.ToolApprovalRequiredData{
- PendingID: pendingID,
- TenantID: req.TenantID,
- SessionID: req.SessionID,
- AssistantMessageID: req.AssistantMessageID,
- ServiceID: req.ServiceID,
- ServiceName: req.ServiceName,
- MCPToolName: req.MCPToolName,
- RegisteredToolName: req.RegisteredToolName,
- Description: req.Description,
- Args: argsObj,
- ArgsJSON: string(req.Args),
- TimeoutSeconds: timeoutSec,
- RequestedAtUnix: time.Now().Unix(),
- ToolCallID: req.ToolCallID,
- RequestID: req.RequestID,
+ d := toolApprovalDecision(out)
+ g.consumeDecision(ctx, &d, req.EventBus, req.SessionID, req.AssistantMessageID, req.RequestID)
+ return d, nil
+}
+
+// promptWaitSeconds is how long the UI should count down for p: the hot wait
+// while it can suspend, the full timeout once it fell back to a plain wait.
+func promptWaitSeconds(p *types.AgentPrompt, wait, fallback time.Duration) int {
+ if !p.Suspendable {
+ wait = fallback
}
+ return max(int(wait/time.Second), 1)
+}
- if err := req.EventBus.Emit(ctx, event.Event{
- ID: pendingID + "-approval-required",
- Type: event.EventToolApprovalRequired,
- SessionID: req.SessionID,
- Data: evtData,
+// ResumeDecision turns the answered prompt a resumed run was suspended on
+// into the decision for its blocked call, as if RequestAndWait had just
+// returned it.
+func (g *Gate) ResumeDecision(ctx context.Context, prompt *types.AgentPrompt, bus *event.EventBus) Decision {
+ d := toolApprovalDecision(hitl.Outcome{Prompt: prompt, Answered: true})
+ g.consumeDecision(ctx, &d, bus, prompt.SessionID, prompt.AssistantMessageID, prompt.RequestID)
+ return d
+}
+
+func (g *Gate) consumeDecision(
+ ctx context.Context, d *Decision, bus *event.EventBus, sessionID, assistantMessageID, requestID string,
+) {
+ // An approved call stays "executing" until MarkExecuted.
+ consumeTo := types.AgentPromptDone
+ if d.Approved {
+ consumeTo = types.AgentPromptExecuting
+ }
+ consumed, consumeErr := g.broker.Consume(ctx, d.PendingID, consumeTo, d.owner)
+ if !consumed && d.answered {
+ d.Approved = false
+ d.ModifiedArgs = nil
+ d.Reason = "approval is no longer owned or was already consumed"
+ if consumeErr == nil {
+ d.Suspended = &types.PromptSuspension{
+ PromptID: d.PendingID, Kind: types.AgentPromptKindToolApproval, Detached: true,
+ }
+ return
+ }
+ d.Reason = "could not confirm tool approval; tool was not executed"
+ }
+ if bus == nil {
+ return
+ }
+ _ = bus.Emit(context.WithoutCancel(ctx), event.Event{
+ ID: d.PendingID + "-approval-resolved",
+ Type: event.EventToolApprovalResolved,
+ SessionID: sessionID,
+ Data: event.ToolApprovalResolvedData{
+ PendingID: d.PendingID,
+ Approved: d.Approved,
+ Reason: d.Reason,
+ TimedOut: d.TimedOut,
+ Canceled: d.ContextCanceled,
+ },
Metadata: map[string]interface{}{
- "assistant_message_id": req.AssistantMessageID,
- "pending_id": pendingID,
+ "assistant_message_id": assistantMessageID,
},
- RequestID: req.RequestID,
- }); err != nil {
- return Decision{}, fmt.Errorf("emit tool approval required: %w", err)
- }
-
- timer := time.NewTimer(g.timeout)
- defer timer.Stop()
-
- emitResolved := func(d Decision) {
- _ = req.EventBus.Emit(context.WithoutCancel(ctx), event.Event{
- ID: pendingID + "-approval-resolved",
- Type: event.EventToolApprovalResolved,
- SessionID: req.SessionID,
- Data: event.ToolApprovalResolvedData{
- PendingID: pendingID,
- Approved: d.Approved,
- Reason: d.Reason,
- TimedOut: d.TimedOut,
- Canceled: d.ContextCanceled,
- },
- Metadata: map[string]interface{}{
- "assistant_message_id": req.AssistantMessageID,
- },
- RequestID: req.RequestID,
- })
- }
-
- var d Decision
- select {
- case d = <-w.ch:
- emitResolved(d)
- return d, nil
- case <-timer.C:
- d = Decision{Approved: false, Reason: "approval timeout", TimedOut: true}
- _ = w.deliver(d)
- d = <-w.ch
- emitResolved(d)
- return d, nil
- case <-ctx.Done():
- d = Decision{Approved: false, Reason: "request canceled", ContextCanceled: true}
- _ = w.deliver(d)
- d = <-w.ch
- emitResolved(d)
- return d, nil
- }
+ RequestID: requestID,
+ })
}
// RequestOAuthAndWait emits an "MCP OAuth required" UI event, then blocks
@@ -449,239 +364,244 @@ func (g *Gate) RequestOAuthAndWait(ctx context.Context, req OAuthPendingRequest)
return Decision{}, fmt.Errorf("oauth gate: EventBus is nil")
}
- pendingID := uuid.New().String()
- w := &waiter{
- ch: make(chan Decision, 1),
- tenantID: req.TenantID,
- userID: req.UserID,
+ request, err := json.Marshal(types.MCPOAuthPromptRequest{
+ ServiceID: req.ServiceID,
+ ServiceName: req.ServiceName,
+ MCPToolName: req.MCPToolName,
+ })
+ if err != nil {
+ return Decision{}, fmt.Errorf("encode oauth prompt: %w", err)
}
-
- g.mu.Lock()
- g.pending[pendingID] = w
- g.mu.Unlock()
-
- defer func() {
- g.mu.Lock()
- delete(g.pending, pendingID)
- g.mu.Unlock()
- }()
-
waitTimeout := g.timeout
if req.WaitTimeout > 0 {
waitTimeout = req.WaitTimeout
}
+ timeoutSec := max(int(waitTimeout/time.Second), 1)
- timeoutSec := int(waitTimeout / time.Second)
- if timeoutSec < 1 {
- timeoutSec = 1
- }
-
- if err := req.EventBus.Emit(ctx, event.Event{
- ID: pendingID + "-mcp-oauth-required",
- Type: event.EventMCPOAuthRequired,
- SessionID: req.SessionID,
- Data: event.MCPOAuthRequiredData{
- PendingID: pendingID,
+ out, err := g.broker.Await(ctx, hitl.Spec{
+ Prompt: &types.AgentPrompt{
TenantID: req.TenantID,
+ UserID: req.UserID,
SessionID: req.SessionID,
AssistantMessageID: req.AssistantMessageID,
- ServiceID: req.ServiceID,
- ServiceName: req.ServiceName,
- MCPToolName: req.MCPToolName,
- TimeoutSeconds: timeoutSec,
- RequestedAtUnix: time.Now().Unix(),
- ToolCallID: req.ToolCallID,
RequestID: req.RequestID,
+ Kind: types.AgentPromptKindMCPOAuth,
+ ToolCallID: req.ToolCallID,
+ Request: types.JSON(request),
+ },
+ Timeout: waitTimeout,
+ TimeoutReason: "authorization timeout",
+ Emit: func(ctx context.Context, p *types.AgentPrompt) error {
+ return req.EventBus.Emit(ctx, event.Event{
+ ID: p.ID + "-mcp-oauth-required",
+ Type: event.EventMCPOAuthRequired,
+ SessionID: req.SessionID,
+ Data: event.MCPOAuthRequiredData{
+ PendingID: p.ID,
+ TenantID: req.TenantID,
+ SessionID: req.SessionID,
+ AssistantMessageID: req.AssistantMessageID,
+ ServiceID: req.ServiceID,
+ ServiceName: req.ServiceName,
+ MCPToolName: req.MCPToolName,
+ TimeoutSeconds: timeoutSec,
+ RequestedAtUnix: time.Now().Unix(),
+ ToolCallID: req.ToolCallID,
+ RequestID: req.RequestID,
+ },
+ Metadata: map[string]interface{}{
+ "assistant_message_id": req.AssistantMessageID,
+ "pending_id": p.ID,
+ },
+ RequestID: req.RequestID,
+ })
+ },
+ })
+ if err != nil {
+ return Decision{}, fmt.Errorf("oauth gate: %w", err)
+ }
+
+ d := oauthDecision(out)
+ consumed, consumeErr := g.broker.Consume(ctx, d.PendingID, types.AgentPromptDone, d.owner)
+ if !consumed && d.answered {
+ d.Approved = false
+ d.Reason = "authorization is no longer owned or was already consumed"
+ if consumeErr != nil {
+ d.Reason = "could not confirm authorization; tool was not retried"
+ }
+ }
+ _ = req.EventBus.Emit(context.WithoutCancel(ctx), event.Event{
+ ID: d.PendingID + "-mcp-oauth-resolved",
+ Type: event.EventMCPOAuthResolved,
+ SessionID: req.SessionID,
+ Data: event.MCPOAuthResolvedData{
+ PendingID: d.PendingID,
+ ServiceID: req.ServiceID,
+ Authorized: d.Approved,
+ Reason: d.Reason,
+ TimedOut: d.TimedOut,
+ Canceled: d.ContextCanceled,
},
Metadata: map[string]interface{}{
"assistant_message_id": req.AssistantMessageID,
- "pending_id": pendingID,
},
RequestID: req.RequestID,
- }); err != nil {
- return Decision{}, fmt.Errorf("emit mcp oauth required: %w", err)
- }
-
- emitResolved := func(d Decision) {
- _ = req.EventBus.Emit(context.WithoutCancel(ctx), event.Event{
- ID: pendingID + "-mcp-oauth-resolved",
- Type: event.EventMCPOAuthResolved,
- SessionID: req.SessionID,
- Data: event.MCPOAuthResolvedData{
- PendingID: pendingID,
- ServiceID: req.ServiceID,
- Authorized: d.Approved,
- Reason: d.Reason,
- TimedOut: d.TimedOut,
- Canceled: d.ContextCanceled,
- },
- Metadata: map[string]interface{}{
- "assistant_message_id": req.AssistantMessageID,
- },
- RequestID: req.RequestID,
- })
- }
-
- timer := time.NewTimer(waitTimeout)
- defer timer.Stop()
-
- var d Decision
- select {
- case d = <-w.ch:
- emitResolved(d)
- return d, nil
- case <-timer.C:
- d = Decision{Approved: false, Reason: "authorization timeout", TimedOut: true}
- _ = w.deliver(d)
- d = <-w.ch
- emitResolved(d)
- return d, nil
- case <-ctx.Done():
- d = Decision{Approved: false, Reason: "request canceled", ContextCanceled: true}
- _ = w.deliver(d)
- d = <-w.ch
- emitResolved(d)
- return d, nil
- }
+ })
+ return d, nil
}
-// Resolve completes a pending approval. tenantID must match the tenant that
-// started the wait; userID, when non-zero, must match the session owner.
-//
-// If the waiter is not on this instance and Redis Pub/Sub is configured, the
-// decision is fanned out to all replicas and ack'd via a reply key in Redis
-// so the caller can distinguish "delivered elsewhere" from "no instance had
-// the pending" (issue #1173 follow-up).
-func (g *Gate) Resolve(tenantID uint64, userID, pendingID string, d Decision) error {
+// MarkExecuted records that an approved call has finished running.
+func (g *Gate) MarkExecuted(ctx context.Context, pendingID string) {
if g == nil {
- return fmt.Errorf("gate is nil")
+ return
}
- switch err := g.deliverLocal(tenantID, userID, pendingID, d); {
- case err == nil:
- return nil
- case errors.Is(err, ErrTenantMismatch),
- errors.Is(err, ErrUserMismatch),
- errors.Is(err, ErrAlreadyResolved):
- return err
- case errors.Is(err, ErrPendingNotFound):
- if g.rdb == nil {
- return err
+ g.broker.MarkExecuted(ctx, pendingID)
+}
+
+// Resolve records a user decision on a pending prompt and wakes its waiter.
+// A suspended prompt answered this way is not resumed; use ResolveForResume.
+func (g *Gate) Resolve(ctx context.Context, req ResolveRequest) error {
+ _, err := g.ResolveForResume(ctx, req)
+ return err
+}
+
+// ResolveForResume records a user decision. When the prompt was suspended,
+// the returned resolution asks the caller to resume its run.
+func (g *Gate) ResolveForResume(ctx context.Context, req ResolveRequest) (hitl.Resolution, error) {
+ if g == nil {
+ return hitl.Resolution{}, fmt.Errorf("gate is nil")
+ }
+ kind := req.Kind
+ if kind == "" {
+ kind = types.AgentPromptKindToolApproval
+ }
+ var response any
+ switch kind {
+ case types.AgentPromptKindToolApproval:
+ r := types.ToolApprovalPromptResponse{Approved: req.Decision.Approved, Reason: req.Decision.Reason}
+ if r.Approved {
+ r.ModifiedArgs = req.Decision.ModifiedArgs
}
- return g.resolveCrossInstance(tenantID, userID, pendingID, d)
+ response = r
+ case types.AgentPromptKindMCPOAuth:
+ response = types.MCPOAuthPromptResponse{Authorized: req.Decision.Approved, Reason: req.Decision.Reason}
default:
- return err
+ return hitl.Resolution{}, fmt.Errorf("%w: unsupported prompt kind %q", ErrInvalidDecision, kind)
}
+ payload, err := json.Marshal(response)
+ if err != nil {
+ return hitl.Resolution{}, err
+ }
+ return g.broker.Resolve(ctx, hitl.ResolveRequest{
+ TenantID: req.TenantID,
+ UserID: req.UserID,
+ SessionID: req.SessionID,
+ Kind: kind,
+ PromptID: req.PendingID,
+ Response: payload,
+ })
}
-// resolveCrossInstance publishes a resolve request and waits briefly for an
-// ack from the instance that owns the pending. The ack is sent over a
-// per-pending Redis pub/sub reply channel and contains the same error codes
-// the local path would return, so HTTP responses stay accurate even when the
-// session lives on a different replica.
-func (g *Gate) resolveCrossInstance(tenantID uint64, userID, pendingID string, d Decision) error {
- // Per-call nonce so concurrent Resolve callers for the same pendingID
- // don't consume each other's acks on the shared reply channel.
- nonce := uuid.New().String()
- replyChannel := pubsubChannel() + ":reply:" + pendingID
- sub := g.rdb.Subscribe(context.Background(), replyChannel)
- defer func() { _ = sub.Close() }()
- // Wait for the subscription to be active before publishing so we don't
- // miss the ack.
- subCtx, subCancel := context.WithTimeout(context.Background(), 2*time.Second)
- defer subCancel()
- if _, err := sub.Receive(subCtx); err != nil {
- return fmt.Errorf("subscribe approval reply: %w", err)
- }
-
- payload, mErr := json.Marshal(resolveMessage{
- TenantID: tenantID,
- UserID: userID,
- PendingID: pendingID,
- Approved: d.Approved,
- ModifiedArgs: d.ModifiedArgs,
- Reason: d.Reason,
- TimedOut: d.TimedOut,
- Canceled: d.ContextCanceled,
- ReplyChannel: replyChannel,
- OriginID: instanceID,
- RequestNonce: nonce,
- })
- if mErr != nil {
- return fmt.Errorf("encode pubsub payload: %w", mErr)
- }
- pubCtx, pubCancel := context.WithTimeout(context.Background(), 2*time.Second)
- defer pubCancel()
- if pErr := g.rdb.Publish(pubCtx, pubsubChannel(), payload).Err(); pErr != nil {
- return fmt.Errorf("publish approval resolve: %w", pErr)
- }
-
- // Wait for the owning instance to ack. Window is short (3s) — UX wins
- // from getting an accurate 404/409 over slowly returning 200.
- ackCtx, ackCancel := context.WithTimeout(context.Background(), 3*time.Second)
- defer ackCancel()
- for {
- msg, err := sub.ReceiveMessage(ackCtx)
- if err != nil {
- // Timeout or subscription error: nobody confirmed, treat as not found.
- return ErrPendingNotFound
- }
- var ack resolveAck
- if jErr := json.Unmarshal([]byte(msg.Payload), &ack); jErr != nil {
- continue
- }
- // Ignore acks intended for a different concurrent Resolve call.
- if ack.RequestNonce != "" && ack.RequestNonce != nonce {
- continue
- }
- switch ack.Status {
- case "ok":
- return nil
- case "tenant_mismatch":
- return ErrTenantMismatch
- case "user_mismatch":
- return ErrUserMismatch
- case "already_resolved":
- return ErrAlreadyResolved
- case "not_found":
- return ErrPendingNotFound
- default:
- return fmt.Errorf("approval reply: unexpected status %q", ack.Status)
- }
+// AnswerableKinds are the prompt kinds a user may answer with a raw
+// response. MCP OAuth is absent: only the OAuth callback may report an
+// authorization, never the user's own claim.
+var AnswerableKinds = map[string]bool{
+ types.AgentPromptKindAskUser: true,
+ types.AgentPromptKindToolApproval: true,
+}
+
+// ResolveResponse records a user's answer given as the kind's response
+// JSON. Authorization and validation are the same as ResolveForResume.
+func (g *Gate) ResolveResponse(ctx context.Context, req hitl.ResolveRequest) (hitl.Resolution, error) {
+ if g == nil {
+ return hitl.Resolution{}, fmt.Errorf("gate is nil")
}
+ if !AnswerableKinds[req.Kind] {
+ return hitl.Resolution{}, fmt.Errorf("%w: prompt kind %q cannot be answered here", ErrInvalidDecision, req.Kind)
+ }
+ return g.broker.Resolve(ctx, req)
}
-// deliverLocal attempts to satisfy a waiter on this instance only.
-func (g *Gate) deliverLocal(tenantID uint64, userID, pendingID string, d Decision) error {
- g.mu.Lock()
- w, ok := g.pending[pendingID]
- if !ok {
- g.mu.Unlock()
- return ErrPendingNotFound
+func toolApprovalDecision(out hitl.Outcome) Decision {
+ d := Decision{
+ PendingID: out.Prompt.ID,
+ owner: out.Prompt.OwnerInstance,
+ answered: out.Answered,
+ Reason: out.Reason,
+ TimedOut: out.TimedOut,
+ ContextCanceled: out.Canceled,
+ }
+ if !out.Answered {
+ return d
}
- if w.tenantID != tenantID {
- g.mu.Unlock()
- return ErrTenantMismatch
+ var r types.ToolApprovalPromptResponse
+ if err := json.Unmarshal(out.Prompt.Response, &r); err != nil {
+ d.Reason = "unreadable approval response"
+ return d
}
- // Authorization: when the pending was registered with a userID, the
- // caller MUST present the same non-empty userID. An empty caller
- // userID is treated as a mismatch (fail-close) so a missing auth
- // middleware cannot bypass the per-user check.
- if w.userID != "" && w.userID != userID {
- g.mu.Unlock()
- return ErrUserMismatch
+ d.Approved, d.Reason = r.Approved, r.Reason
+ if r.Approved && len(r.ModifiedArgs) > 0 {
+ d.ModifiedArgs = r.ModifiedArgs
}
- g.mu.Unlock()
- already := w.resolved.Load()
+ return d
+}
+
+func oauthDecision(out hitl.Outcome) Decision {
+ d := Decision{
+ PendingID: out.Prompt.ID,
+ owner: out.Prompt.OwnerInstance,
+ answered: out.Answered,
+ Reason: out.Reason,
+ TimedOut: out.TimedOut,
+ ContextCanceled: out.Canceled,
+ }
+ if !out.Answered {
+ return d
+ }
+ var r types.MCPOAuthPromptResponse
+ if err := json.Unmarshal(out.Prompt.Response, &r); err != nil {
+ d.Reason = "unreadable authorization response"
+ return d
+ }
+ d.Approved, d.Reason = r.Authorized, r.Reason
+ return d
+}
- if already {
- return ErrAlreadyResolved
+func validateToolApprovalResponse(_, response json.RawMessage) error {
+ // Strict decoding with a required "approved": a misspelled or missing
+ // field must not read as a rejection.
+ var r struct {
+ Approved *bool `json:"approved"`
+ ModifiedArgs json.RawMessage `json:"modified_args,omitempty"`
+ Reason string `json:"reason,omitempty"`
+ }
+ dec := json.NewDecoder(bytes.NewReader(response))
+ dec.DisallowUnknownFields()
+ if err := dec.Decode(&r); err != nil {
+ return err
+ }
+ if r.Approved == nil {
+ return errors.New(`"approved" is required`)
+ }
+ trimmed := strings.TrimSpace(string(r.ModifiedArgs))
+ if trimmed == "" {
+ return nil
+ }
+ if !*r.Approved {
+ return errors.New("modified_args is only allowed on approval")
}
- if !w.deliver(d) {
- return ErrAlreadyResolved
+ var probe map[string]any
+ if err := json.Unmarshal(r.ModifiedArgs, &probe); err != nil || probe == nil {
+ return errors.New("modified_args must be a non-null JSON object")
}
return nil
}
+func validateMCPOAuthResponse(_, response json.RawMessage) error {
+ var r types.MCPOAuthPromptResponse
+ return json.Unmarshal(response, &r)
+}
+
// Adapter makes MCPToolApprovalService satisfy Checker without importing the service package here.
type Adapter struct {
Svc interface {
diff --git a/internal/agent/approval/gate_test.go b/internal/agent/approval/gate_test.go
index 89e1d1499..839a8d2e1 100644
--- a/internal/agent/approval/gate_test.go
+++ b/internal/agent/approval/gate_test.go
@@ -8,9 +8,16 @@ import (
"github.com/Tencent/WeKnora/internal/config"
"github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/require"
)
+func resolveFor(g *Gate, tenantID uint64, userID, pendingID string, d Decision) error {
+ return g.Resolve(context.Background(), ResolveRequest{
+ TenantID: tenantID, UserID: userID, PendingID: pendingID, Decision: d,
+ })
+}
+
type stubChecker struct {
required bool
err error
@@ -56,7 +63,7 @@ func TestGate_RequestAndWait_Approve(t *testing.T) {
require.True(t, ok)
require.NotEmpty(t, data.PendingID)
go func() {
- _ = g.Resolve(1, "", data.PendingID, Decision{Approved: true, ModifiedArgs: json.RawMessage(`{"a":2}`)})
+ _ = resolveFor(g, 1, "", data.PendingID, Decision{Approved: true, ModifiedArgs: json.RawMessage(`{"a":2}`)})
}()
return nil
})
@@ -94,7 +101,7 @@ func TestGate_NeedsApproval_NoChecker(t *testing.T) {
func TestGate_Resolve_NotFound(t *testing.T) {
g := NewGate(&config.Config{Agent: &config.AgentConfig{ToolApprovalTimeoutSeconds: 1}}, &stubChecker{required: true}, nil)
- err := g.Resolve(1, "", "no-such-id", Decision{Approved: true})
+ err := resolveFor(g, 1, "", "no-such-id", Decision{Approved: true})
require.ErrorIs(t, err, ErrPendingNotFound)
}
@@ -108,8 +115,8 @@ func TestGate_Resolve_TenantMismatch(t *testing.T) {
bus.On(event.EventToolApprovalRequired, func(_ context.Context, evt event.Event) error {
data := evt.Data.(event.ToolApprovalRequiredData)
go func() {
- require.ErrorIs(t, g.Resolve(999, "", data.PendingID, Decision{Approved: true}), ErrTenantMismatch)
- _ = g.Resolve(1, "", data.PendingID, Decision{Approved: false, Reason: "no"})
+ require.ErrorIs(t, resolveFor(g, 999, "", data.PendingID, Decision{Approved: true}), ErrTenantMismatch)
+ _ = resolveFor(g, 1, "", data.PendingID, Decision{Approved: false, Reason: "no"})
}()
return nil
})
@@ -129,8 +136,8 @@ func TestGate_Resolve_UserMismatch(t *testing.T) {
bus.On(event.EventToolApprovalRequired, func(_ context.Context, evt event.Event) error {
data := evt.Data.(event.ToolApprovalRequiredData)
go func() {
- require.ErrorIs(t, g.Resolve(1, "bob", data.PendingID, Decision{Approved: true}), ErrUserMismatch)
- _ = g.Resolve(1, "alice", data.PendingID, Decision{Approved: true})
+ require.ErrorIs(t, resolveFor(g, 1, "bob", data.PendingID, Decision{Approved: true}), ErrUserMismatch)
+ _ = resolveFor(g, 1, "alice", data.PendingID, Decision{Approved: true})
}()
return nil
})
@@ -153,8 +160,8 @@ func TestGate_Resolve_EmptyUserIDRejectedWhenWaiterHasUser(t *testing.T) {
bus.On(event.EventToolApprovalRequired, func(_ context.Context, evt event.Event) error {
data := evt.Data.(event.ToolApprovalRequiredData)
go func() {
- require.ErrorIs(t, g.Resolve(1, "", data.PendingID, Decision{Approved: true}), ErrUserMismatch)
- _ = g.Resolve(1, "alice", data.PendingID, Decision{Approved: false, Reason: "no"})
+ require.ErrorIs(t, resolveFor(g, 1, "", data.PendingID, Decision{Approved: true}), ErrUserMismatch)
+ _ = resolveFor(g, 1, "alice", data.PendingID, Decision{Approved: false, Reason: "no"})
}()
return nil
})
@@ -175,16 +182,13 @@ func TestGate_Resolve_AlreadyResolvedAfterTimeout(t *testing.T) {
return nil
})
+ lateErr := make(chan error, 1)
go func() {
<-gotPending
- // Wait until timeout has fired and the pending entry is still there
- // (defer delete only happens after RequestAndWait returns).
- // 1s timeout + small slack.
+ // 1s timeout + small slack: the prompt row outlives the wait and
+ // records the timeout, so a late decision cannot reopen it.
<-time.After(1500 * time.Millisecond)
- require.ErrorIs(t,
- g.Resolve(1, "", pendingID, Decision{Approved: true}),
- ErrPendingNotFound, // entry already removed by RequestAndWait's defer
- )
+ lateErr <- resolveFor(g, 1, "", pendingID, Decision{Approved: true})
}()
d, err := g.RequestAndWait(context.Background(), PendingRequest{
@@ -193,6 +197,50 @@ func TestGate_Resolve_AlreadyResolvedAfterTimeout(t *testing.T) {
})
require.NoError(t, err)
require.True(t, d.TimedOut)
+ require.ErrorIs(t, <-lateErr, ErrAlreadyResolved)
+
+ row, err := g.broker.Store().Get(context.Background(), pendingID)
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptExpired, row.Status)
+}
+
+func TestGate_ApprovedCallStaysExecutingUntilMarked(t *testing.T) {
+ g := NewGate(&config.Config{Agent: &config.AgentConfig{ToolApprovalTimeoutSeconds: 5}},
+ &stubChecker{required: true}, nil)
+ bus := event.NewEventBus()
+ bus.On(event.EventToolApprovalRequired, func(_ context.Context, evt event.Event) error {
+ pendingID := evt.Data.(event.ToolApprovalRequiredData).PendingID
+ go func() {
+ require.ErrorIs(t,
+ resolveFor(g, 1, "", pendingID, Decision{Approved: true, ModifiedArgs: json.RawMessage(`[1]`)}),
+ ErrInvalidDecision)
+ require.ErrorIs(t, g.Resolve(context.Background(), ResolveRequest{
+ TenantID: 1, Kind: types.AgentPromptKindMCPOAuth, PendingID: pendingID,
+ Decision: Decision{Approved: true},
+ }), ErrPendingNotFound)
+ require.NoError(t, resolveFor(g, 1, "", pendingID, Decision{Approved: true}))
+ }()
+ return nil
+ })
+
+ d, err := g.RequestAndWait(context.Background(), PendingRequest{
+ TenantID: 1, EventBus: bus, SessionID: "s",
+ ServiceID: "svc", MCPToolName: "t", Args: json.RawMessage(`{}`),
+ })
+ require.NoError(t, err)
+ require.True(t, d.Approved)
+
+ row, err := g.broker.Store().Get(context.Background(), d.PendingID)
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptExecuting, row.Status)
+ var request types.ToolApprovalPromptRequest
+ require.NoError(t, json.Unmarshal(row.Request, &request))
+ require.Equal(t, "svc", request.ServiceID)
+
+ g.MarkExecuted(context.Background(), d.PendingID)
+ row, err = g.broker.Store().Get(context.Background(), d.PendingID)
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptDone, row.Status)
}
func TestGate_Resolve_RaceWinsAlreadyResolved(t *testing.T) {
@@ -208,8 +256,8 @@ func TestGate_Resolve_RaceWinsAlreadyResolved(t *testing.T) {
bus.On(event.EventToolApprovalRequired, func(_ context.Context, evt event.Event) error {
pendingID := evt.Data.(event.ToolApprovalRequiredData).PendingID
go func() {
- err1 := g.Resolve(1, "", pendingID, Decision{Approved: true})
- err2 := g.Resolve(1, "", pendingID, Decision{Approved: false})
+ err1 := resolveFor(g, 1, "", pendingID, Decision{Approved: true})
+ err2 := resolveFor(g, 1, "", pendingID, Decision{Approved: false})
resCh <- result{first: err1, second: err2}
}()
return nil
@@ -223,14 +271,7 @@ func TestGate_Resolve_RaceWinsAlreadyResolved(t *testing.T) {
require.True(t, d.Approved)
r := <-resCh
require.NoError(t, r.first)
- // Second call must surface either AlreadyResolved or NotFound (depending
- // on whether the defer-delete already ran).
- require.True(t,
- r.second == nil || // RequestAndWait removed the entry: NotFound is possible too
- r.second.Error() == ErrAlreadyResolved.Error() ||
- r.second.Error() == ErrPendingNotFound.Error(),
- "unexpected error: %v", r.second,
- )
+ require.ErrorIs(t, r.second, ErrAlreadyResolved)
}
func boolPtr(v bool) *bool { return &v }
@@ -274,3 +315,158 @@ func TestAdapter_IsEnabled(t *testing.T) {
require.NoError(t, err)
require.True(t, enabled)
}
+
+func TestGate_RequestAndWait_SuspendsAfterHotWait(t *testing.T) {
+ bus := event.NewEventBus()
+ g := NewGate(&config.Config{Agent: &config.AgentConfig{
+ ToolApprovalTimeoutSeconds: 60, PromptHotWaitSeconds: 1,
+ }}, &stubChecker{required: true}, nil)
+
+ var required event.ToolApprovalRequiredData
+ bus.On(event.EventToolApprovalRequired, func(_ context.Context, evt event.Event) error {
+ required = evt.Data.(event.ToolApprovalRequiredData)
+ return nil
+ })
+ resolved := false
+ bus.On(event.EventToolApprovalResolved, func(context.Context, event.Event) error {
+ resolved = true
+ return nil
+ })
+
+ d, err := g.RequestAndWait(context.Background(), PendingRequest{
+ TenantID: 1, SessionID: "s1", AssistantMessageID: "m1", EventBus: bus,
+ ServiceID: "svc", ServiceName: "svcname", MCPToolName: "t", RegisteredToolName: "mcp_svcname_t",
+ Args: json.RawMessage(`{}`), ToolCallID: "tc1",
+ Snapshot: []byte(`{"version":1}`), SnapshotVersion: 1,
+ })
+ require.NoError(t, err)
+ require.False(t, d.Approved)
+ require.False(t, d.TimedOut)
+ require.NotNil(t, d.Suspended)
+ require.Equal(t, d.PendingID, d.Suspended.PromptID)
+ require.Equal(t, types.AgentPromptKindToolApproval, d.Suspended.Kind)
+ require.NotNil(t, d.Suspended.ExpiresAt)
+
+ require.True(t, required.Suspendable)
+ require.Equal(t, 1, required.HotWaitSeconds)
+ require.False(t, resolved, "a suspended approval is still open")
+}
+
+func TestGate_ResolveSuspendedThenResumeDecision(t *testing.T) {
+ bus := event.NewEventBus()
+ g := NewGate(&config.Config{Agent: &config.AgentConfig{
+ ToolApprovalTimeoutSeconds: 60, PromptHotWaitSeconds: 1,
+ }}, &stubChecker{required: true}, nil)
+ d, err := g.RequestAndWait(context.Background(), PendingRequest{
+ TenantID: 1, SessionID: "s1", AssistantMessageID: "m1", EventBus: bus,
+ ServiceID: "svc", ServiceName: "svcname", MCPToolName: "t", RegisteredToolName: "mcp_svcname_t",
+ Args: json.RawMessage(`{"a":1}`), ToolCallID: "tc1",
+ Snapshot: []byte(`{"version":1}`), SnapshotVersion: 1,
+ })
+ require.NoError(t, err)
+ require.NotNil(t, d.Suspended)
+
+ res, err := g.ResolveForResume(context.Background(), ResolveRequest{
+ TenantID: 1, PendingID: d.PendingID,
+ Decision: Decision{Approved: true, ModifiedArgs: json.RawMessage(`{"a":2}`)},
+ })
+ require.NoError(t, err)
+ require.True(t, res.Resume)
+
+ var resolved event.ToolApprovalResolvedData
+ resumeBus := event.NewEventBus()
+ resumeBus.On(event.EventToolApprovalResolved, func(_ context.Context, evt event.Event) error {
+ resolved = evt.Data.(event.ToolApprovalResolvedData)
+ return nil
+ })
+ got := g.ResumeDecision(context.Background(), res.Prompt, resumeBus)
+ require.True(t, got.Approved)
+ require.JSONEq(t, `{"a":2}`, string(got.ModifiedArgs))
+ require.Equal(t, d.PendingID, resolved.PendingID)
+ require.True(t, resolved.Approved)
+ require.False(t, g.ResumeDecision(context.Background(), res.Prompt, nil).Approved,
+ "an approval can execute only once")
+
+ row, err := g.broker.Store().Get(context.Background(), d.PendingID)
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptExecuting, row.Status)
+ g.MarkExecuted(context.Background(), d.PendingID)
+ row, err = g.broker.Store().Get(context.Background(), d.PendingID)
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptDone, row.Status)
+}
+
+func TestValidateToolApprovalResponse_IsStrict(t *testing.T) {
+ for body, ok := range map[string]bool{
+ `{"approved":true}`: true,
+ `{"approved":false,"reason":"no"}`: true,
+ `{"approved":true,"modified_args":{"q":"x"}}`: true,
+ `{"decision":"approve"}`: false,
+ `{}`: false,
+ `{"approved":true,"extra":1}`: false,
+ `{"approved":false,"modified_args":{"q":"x"}}`: false,
+ `{"approved":true,"modified_args":null}`: false,
+ `{"approved":true,"modified_args":["not","obj"]}`: false,
+ } {
+ err := validateToolApprovalResponse(nil, json.RawMessage(body))
+ if ok {
+ require.NoError(t, err, body)
+ } else {
+ require.Error(t, err, body)
+ }
+ }
+}
+
+func TestAnsweredPromptOnlyCurrentOwnerCanContinue(t *testing.T) {
+ for _, kind := range []string{types.AgentPromptKindToolApproval, types.AgentPromptKindAskUser} {
+ for _, accept := range []bool{true, false} {
+ name := kind + "/decline"
+ if accept {
+ name = kind + "/accept"
+ }
+ t.Run(name, func(t *testing.T) {
+ ctx := t.Context()
+ g := NewGate(nil, nil, nil)
+ response := `{"approved":false}`
+ if kind == types.AgentPromptKindAskUser {
+ response = `{"declined":true}`
+ if accept {
+ response = `{"text":"staging"}`
+ }
+ } else if accept {
+ response = `{"approved":true}`
+ }
+ current := &types.AgentPrompt{
+ ID: "p", Kind: kind, Status: types.AgentPromptAnswered,
+ OwnerInstance: "new-run", Response: types.JSON(response),
+ }
+ require.NoError(t, g.broker.Store().Create(ctx, current))
+ stale := *current
+ stale.OwnerInstance = "old-run"
+ if kind == types.AgentPromptKindAskUser {
+ denied := g.ResumeAnswer(ctx, &stale, nil)
+ require.False(t, denied.Answered)
+ require.NotNil(t, denied.Suspended)
+ require.True(t, denied.Suspended.Detached)
+ winner := g.ResumeAnswer(ctx, current, nil)
+ require.Nil(t, winner.Suspended)
+ require.Equal(t, accept, winner.Answered)
+ duplicate := g.ResumeAnswer(ctx, current, nil)
+ require.NotNil(t, duplicate.Suspended)
+ require.True(t, duplicate.Suspended.Detached)
+ } else {
+ denied := g.ResumeDecision(ctx, &stale, nil)
+ require.False(t, denied.Approved)
+ require.NotNil(t, denied.Suspended)
+ require.True(t, denied.Suspended.Detached)
+ winner := g.ResumeDecision(ctx, current, nil)
+ require.Nil(t, winner.Suspended)
+ require.Equal(t, accept, winner.Approved)
+ duplicate := g.ResumeDecision(ctx, current, nil)
+ require.NotNil(t, duplicate.Suspended)
+ require.True(t, duplicate.Suspended.Detached)
+ }
+ })
+ }
+ }
+}
diff --git a/internal/agent/engine.go b/internal/agent/engine.go
index be8eb19e9..942b63bc8 100644
--- a/internal/agent/engine.go
+++ b/internal/agent/engine.go
@@ -82,6 +82,13 @@ type AgentEngine struct {
allowSteerOverrun bool // one extra ReAct round after a loop-end inject past MaxIterations
steerOverruns int // how many times this turn has already used the extra round
workspaceLayout sandbox.WorkspaceLayout
+ // suspendable lets a user prompt end the run so it can be resumed later;
+ // suspendRequest is saved with the run for that (see EnableSuspension).
+ suspendable bool
+ suspendRequest []byte
+ // interactive: the client renders prompt cards and can answer them.
+ interactive bool
+ progress turnProgress
}
// maxSteerOverruns caps loop-end injects past MaxIterations. One extra round
@@ -399,6 +406,7 @@ func (e *AgentEngine) Execute(
if len(imageURLs) > 0 {
imgs = imageURLs[0]
}
+ e.beginTurn(query, imgs, state)
messages := e.buildMessagesWithLLMContext(systemPrompt, query, sessionID, llmContext, imgs)
if e.toolRegistry != nil {
e.toolRegistry.RememberMCPHistory(messages)
@@ -688,7 +696,9 @@ loop:
// state.FinalAnswer to the generic "Sorry, I was unable to generate a
// complete answer." message, which then leaks to the UI as the final
// answer for a conversation the user deliberately stopped.
- if !state.IsComplete && ctx.Err() == nil {
+ // A suspended run has not finished either; it resumes once the user
+ // answers, so no answer is synthesized for it.
+ if !state.IsComplete && ctx.Err() == nil && state.Suspended == nil {
e.handleMaxIterations(ctx, query, state, sessionID, messages)
}
@@ -1049,8 +1059,18 @@ func (e *AgentEngine) runReActIteration(
// Thought.
// 3. Act: Execute tool calls
- e.executeToolCalls(ctx, response, &step, state.CurrentRound, sessionID, assistantMessageID)
+ e.beginRound(step, response.ToolCalls)
+ suspended := e.executeToolCalls(ctx, response, &step, state.CurrentRound, sessionID, assistantMessageID)
+ e.endRound()
toolCallCount = len(step.ToolCalls)
+ if suspended != nil {
+ // The blocked call and the ones after it have not run, so the round
+ // is not part of the transcript yet; it is completed on resume.
+ logger.Infof(ctx, "[Agent][Round-%d] Suspended waiting on prompt %s", round, suspended.PromptID)
+ state.Suspended = suspended
+ state.SuspendedStep = &step
+ return iterOutcomeBreak, nil
+ }
// 4. Observe: Add tool results to messages and write to context
state.RoundSteps = append(state.RoundSteps, step)
diff --git a/internal/agent/finalize.go b/internal/agent/finalize.go
index 372bc7cf7..eacdf40e0 100644
--- a/internal/agent/finalize.go
+++ b/internal/agent/finalize.go
@@ -145,6 +145,9 @@ func (e *AgentEngine) emitCompletionEvent(
ctx context.Context, state *types.AgentState, sessionID, messageID string, startTime time.Time,
) {
steps := state.RoundSteps
+ if state.SuspendedStep != nil {
+ steps = append(append([]types.AgentStep(nil), steps...), *state.SuspendedStep)
+ }
if len(state.PendingSteerMessages) > 0 {
// A stop or model failure can arrive after delivery but before the next
// response exists. Preserve that boundary without inventing an answer.
@@ -174,6 +177,9 @@ func (e *AgentEngine) emitCompletionEvent(
if e.chatModel != nil {
data.ModelID = e.chatModel.GetModelID()
}
+ if state.Suspended != nil {
+ data.Suspended = state.Suspended
+ }
e.eventBus.Emit(ctx, event.Event{
ID: generateEventID("complete"),
Type: event.EventAgentComplete,
diff --git a/internal/agent/hitl/broker.go b/internal/agent/hitl/broker.go
new file mode 100644
index 000000000..27b173c35
--- /dev/null
+++ b/internal/agent/hitl/broker.go
@@ -0,0 +1,727 @@
+// Package hitl coordinates human-in-the-loop prompts raised by agent runs:
+// tool approvals, in-conversation authorizations, questions for the user.
+//
+// The prompt row in Store is the source of truth for every answer. The
+// replica that raised a prompt keeps an in-memory waiter only as a wake-up
+// hook: Resolve records the answer with a compare-and-set, then wakes the
+// waiter locally or over Redis pub/sub, and the waiter also polls the row in
+// case a wake-up is lost. Kind-specific behaviour (request/response shape and
+// validation) is registered per kind; the broker never interprets payloads.
+package hitl
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "os"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/config"
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/google/uuid"
+ "github.com/redis/go-redis/v9"
+)
+
+// pubsubChannelBase is the Redis channel prefix used to wake the replica that
+// holds a waiter after another replica recorded the answer. The actual
+// channel is suffixed with WEKNORA_REDIS_NAMESPACE (when set) so multiple
+// deployments sharing the same Redis don't cross-talk.
+const pubsubChannelBase = "weknora:agent_prompt:wake"
+
+// instanceID identifies this process for pub/sub wake-up suppression.
+var instanceID = uuid.New().String()
+
+// Timing of the owner-side wait loop. The poll covers lost pub/sub wake-ups;
+// the lease lets other replicas notice an owner that disappeared.
+const (
+ defaultPollInterval = 3 * time.Second
+ defaultLeaseTTL = 30 * time.Second
+ defaultRenewInterval = 10 * time.Second
+)
+
+// consumeRetryDelays spaces the retries of a Consume the store failed to record.
+var consumeRetryDelays = []time.Duration{100 * time.Millisecond, 400 * time.Millisecond}
+
+var (
+ // ErrPromptNotFound is returned when Resolve targets an unknown prompt,
+ // or one outside the caller's session or kind.
+ ErrPromptNotFound = errors.New("agent prompt not found")
+ // ErrTenantMismatch is returned when the caller's tenant does not own the prompt.
+ ErrTenantMismatch = errors.New("workspace mismatch for agent prompt")
+ // ErrUserMismatch is returned when the caller does not own the session.
+ ErrUserMismatch = errors.New("user mismatch for agent prompt")
+ // ErrAlreadyResolved is returned when the prompt was already answered or
+ // ended by timeout / cancellation.
+ ErrAlreadyResolved = errors.New("agent prompt already resolved")
+ // ErrInvalidResponse wraps a kind validator's rejection of an answer.
+ ErrInvalidResponse = errors.New("invalid agent prompt response")
+)
+
+// ResponseValidator checks an answer against the prompt that asked for it.
+type ResponseValidator func(request, response json.RawMessage) error
+
+// Outcome is how an awaited prompt ended. Prompt is the row as last read.
+type Outcome struct {
+ Prompt *types.AgentPrompt
+ // Answered means the user responded; Prompt.Response holds the answer.
+ Answered bool
+ TimedOut bool
+ Canceled bool
+ // Suspended means the prompt outlived the in-memory wait: the run must
+ // end now and be resumed once the prompt is answered.
+ Suspended bool
+ // Detached means another owner already took over this run. The old
+ // waiter must exit without publishing or persisting completion.
+ Detached bool
+ ExpiresAt *time.Time
+ Reason string
+}
+
+// Spec describes a prompt to raise and wait on.
+type Spec struct {
+ // Prompt carries kind, scope and request. Status, ownership and lease are
+ // filled in by Await; an empty ID is generated.
+ Prompt *types.AgentPrompt
+ Timeout time.Duration
+ TimeoutReason string
+ // Emit notifies the UI. It runs after the row is persisted and the
+ // waiter is registered, so an immediate answer is never missed.
+ Emit func(ctx context.Context, prompt *types.AgentPrompt) error
+ // Suspend makes the prompt suspendable: when Timeout elapses the run is
+ // suspended instead of the prompt expiring. Nil keeps a plain wait.
+ Suspend *SuspendSpec
+ // FallbackTimeout, when set, turns a suspendable prompt whose run state
+ // cannot be saved into a plain wait of this length instead of failing.
+ // Emit sees the downgrade as Prompt.Suspendable == false.
+ FallbackTimeout time.Duration
+}
+
+// SuspendSpec carries the run state saved with a suspendable prompt. It is
+// written before the prompt is raised, so a replica that dies while waiting
+// still leaves a resumable run behind.
+type SuspendSpec struct {
+ Snapshot []byte
+ SnapshotVersion int
+}
+
+// ResolveRequest is a user answer to a prompt. SessionID and Kind, when set,
+// must match the prompt; a mismatch reads as not found so callers cannot
+// probe prompts outside the session or surface they are authorized for.
+type ResolveRequest struct {
+ TenantID uint64
+ UserID string
+ SessionID string
+ Kind string
+ PromptID string
+ Response json.RawMessage
+}
+
+// Broker raises, awaits and resolves prompts.
+type Broker struct {
+ store Store
+ suspensions SuspensionStore
+ rdb *redis.Client
+
+ mu sync.Mutex
+ waiters map[string]chan struct{}
+ validators map[string]ResponseValidator
+
+ pollInterval time.Duration
+ leaseTTL time.Duration
+ renewInterval time.Duration
+ // suspendExpiry bounds how long a suspended prompt stays answerable;
+ // zero never expires.
+ suspendExpiry time.Duration
+ // runHooks finish the message of a run Resolve takes over from an owner
+ // that stopped renewing its lease; see SetRunHooks.
+ runHooks RunHooks
+}
+
+// SetRunHooks installs the hooks Resolve uses when it suspends a prompt on
+// behalf of an owner that disappeared, as the reaper would.
+func (b *Broker) SetRunHooks(h RunHooks) {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+ b.runHooks = h
+}
+
+func (b *Broker) hooks() RunHooks {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+ return b.runHooks
+}
+
+// Option customizes a Broker.
+type Option func(*Broker)
+
+// WithPollInterval overrides how often a waiter re-reads its row.
+func WithPollInterval(d time.Duration) Option {
+ return func(b *Broker) {
+ if d > 0 {
+ b.pollInterval = d
+ }
+ }
+}
+
+// WithSuspensionStore sets where suspendable prompts save their run state.
+func WithSuspensionStore(s SuspensionStore) Option {
+ return func(b *Broker) {
+ if s != nil {
+ b.suspensions = s
+ }
+ }
+}
+
+// WithSuspendExpiry sets how long a suspended prompt stays answerable; zero
+// never expires.
+func WithSuspendExpiry(d time.Duration) Option {
+ return func(b *Broker) { b.suspendExpiry = d }
+}
+
+// withLease shortens lease timing for tests.
+func withLease(ttl, renew time.Duration) Option {
+ return func(b *Broker) { b.leaseTTL, b.renewInterval = ttl, renew }
+}
+
+// NewBroker builds a broker. store may be nil (process memory; single
+// replica only). rdb may be nil (no cross-instance wake-ups; waiters still
+// observe answers by polling the store).
+func NewBroker(store Store, rdb *redis.Client, opts ...Option) *Broker {
+ if store == nil {
+ store = NewMemoryStore()
+ }
+ b := &Broker{
+ store: store,
+ suspensions: NewMemorySuspensionStore(),
+ rdb: rdb,
+ waiters: make(map[string]chan struct{}),
+ validators: make(map[string]ResponseValidator),
+ pollInterval: defaultPollInterval,
+ leaseTTL: defaultLeaseTTL,
+ renewInterval: defaultRenewInterval,
+ suspendExpiry: config.DefaultPromptExpire,
+ }
+ for _, opt := range opts {
+ opt(b)
+ }
+ if rdb != nil {
+ go b.runSubscriber()
+ }
+ return b
+}
+
+// Store exposes the backing store to kind adapters and tests.
+func (b *Broker) Store() Store { return b.store }
+
+// Suspensions exposes the run-state store.
+func (b *Broker) Suspensions() SuspensionStore { return b.suspensions }
+
+// RegisterKind installs the answer validator for kind. Resolve rejects
+// answers to kinds without a validator.
+func (b *Broker) RegisterKind(kind string, validate ResponseValidator) {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+ b.validators[kind] = validate
+}
+
+// Await persists the prompt as pending and owned by this process, emits it,
+// and blocks until it is answered, the timeout elapses, or ctx ends. The
+// outcome always reflects the row's final state, so an answer that lands
+// concurrently with a timeout or cancellation is never lost.
+//
+// A suspendable prompt's run state is kept only while the run may still be
+// resumed from it: it is dropped when the prompt ends any other way.
+func (b *Broker) Await(ctx context.Context, spec Spec) (out Outcome, err error) {
+ p := spec.Prompt
+ if p == nil {
+ return Outcome{}, errors.New("agent prompt: nil prompt")
+ }
+ if p.ID == "" {
+ p.ID = uuid.New().String()
+ }
+ dbCtx := context.WithoutCancel(ctx)
+ // A fresh token also fences a takeover by another run on this same replica.
+ owner := uuid.NewString()
+ if spec.Suspend != nil {
+ if p.AssistantMessageID == "" {
+ return Outcome{}, errors.New("agent prompt: a suspendable prompt needs an assistant message")
+ }
+ p.Suspendable = true
+ err := b.suspensions.Save(dbCtx, &types.AgentRunSuspension{
+ AssistantMessageID: p.AssistantMessageID,
+ TenantID: p.TenantID,
+ SessionID: p.SessionID,
+ PromptID: p.ID,
+ SnapshotVersion: spec.Suspend.SnapshotVersion,
+ Snapshot: types.JSON(spec.Suspend.Snapshot),
+ })
+ switch {
+ case err == nil:
+ defer func() {
+ if !out.Suspended {
+ row, readErr := b.store.Get(dbCtx, p.ID)
+ if readErr == nil && (row == nil || row.OwnerInstance == owner) {
+ b.dropSnapshot(dbCtx, p.AssistantMessageID, p.ID)
+ }
+ }
+ }()
+ case spec.FallbackTimeout > 0:
+ logger.GetLogger(ctx).Warnf("persist run state of prompt %s, waiting in memory instead: %v", p.ID, err)
+ spec.Suspend, spec.Timeout, p.Suspendable = nil, spec.FallbackTimeout, false
+ default:
+ return Outcome{}, fmt.Errorf("persist run state: %w", err)
+ }
+ }
+ lease := time.Now().Add(b.leaseTTL)
+ p.Status = types.AgentPromptPending
+ p.OwnerInstance = owner
+ p.LeaseUntil = &lease
+ if err := b.store.Create(dbCtx, p); err != nil {
+ return Outcome{}, fmt.Errorf("persist agent prompt: %w", err)
+ }
+
+ wake := b.register(p.ID)
+ defer b.unregister(p.ID)
+
+ if spec.Emit != nil {
+ if err := spec.Emit(ctx, p); err != nil {
+ b.closeAsOwner(dbCtx, p.ID, owner, types.AgentPromptCanceled, "prompt could not be delivered")
+ return Outcome{}, fmt.Errorf("emit agent prompt: %w", err)
+ }
+ }
+
+ timer := time.NewTimer(spec.Timeout)
+ defer timer.Stop()
+ poll := time.NewTicker(b.pollInterval)
+ defer poll.Stop()
+ renew := time.NewTicker(b.renewInterval)
+ defer renew.Stop()
+
+ for {
+ select {
+ case <-wake:
+ if out, ok := b.closed(dbCtx, p.ID, owner); ok {
+ return out, nil
+ }
+ case <-poll.C:
+ if out, ok := b.closed(dbCtx, p.ID, owner); ok {
+ return out, nil
+ }
+ case <-renew.C:
+ if _, err := b.store.RenewLease(dbCtx, p.ID, owner, time.Now().Add(b.leaseTTL)); err != nil {
+ logger.GetLogger(ctx).Warnf("renew agent prompt lease %s: %v", p.ID, err)
+ }
+ case <-timer.C:
+ if spec.Suspend != nil {
+ return b.suspend(dbCtx, p.ID, owner), nil
+ }
+ return b.closeAsOwner(dbCtx, p.ID, owner, types.AgentPromptExpired, spec.TimeoutReason), nil
+ case <-ctx.Done():
+ return b.closeAsOwner(dbCtx, p.ID, owner, types.AgentPromptCanceled, "request canceled"), nil
+ }
+ }
+}
+
+// suspend moves a pending prompt to suspended. When an answer won the race,
+// that answer is returned instead.
+func (b *Broker) suspend(ctx context.Context, id, owner string) Outcome {
+ expiresAt := b.expiresAt(time.Now())
+ ok, err := b.store.Transition(ctx, id, types.AgentPromptTransition{
+ From: []string{types.AgentPromptPending},
+ To: types.AgentPromptSuspended,
+ ExpiresAt: expiresAt,
+ ExpectedOwner: &owner,
+ })
+ if err != nil {
+ logger.GetLogger(ctx).Warnf("suspend agent prompt %s: %v", id, err)
+ }
+ if !ok {
+ if out, closed := b.closed(ctx, id, owner); closed {
+ return out
+ }
+ // The row could not be read or moved; fail the prompt rather than
+ // leave a run suspended on state nobody can confirm.
+ return b.closeAsOwner(ctx, id, owner, types.AgentPromptExpired, "prompt could not be suspended")
+ }
+ return Outcome{
+ Prompt: &types.AgentPrompt{ID: id, Status: types.AgentPromptSuspended, ExpiresAt: expiresAt},
+ Suspended: true,
+ ExpiresAt: expiresAt,
+ }
+}
+
+func (b *Broker) expiresAt(now time.Time) *time.Time {
+ if b.suspendExpiry <= 0 {
+ return nil
+ }
+ at := now.Add(b.suspendExpiry)
+ return &at
+}
+
+func (b *Broker) dropSnapshot(ctx context.Context, messageID, promptID string) {
+ if err := b.suspensions.Delete(ctx, messageID, promptID); err != nil {
+ logger.GetLogger(ctx).Warnf("drop run state of message %s: %v", messageID, err)
+ }
+}
+
+// closeAsOwner ends a pending prompt from the waiting side. When an answer
+// won the race, that answer is returned instead.
+func (b *Broker) closeAsOwner(ctx context.Context, id, owner, status, reason string) Outcome {
+ ok, err := b.store.Transition(ctx, id, types.AgentPromptTransition{
+ From: []string{types.AgentPromptPending},
+ To: status,
+ CloseReason: &reason,
+ ExpectedOwner: &owner,
+ })
+ if err != nil {
+ logger.GetLogger(ctx).Warnf("close agent prompt %s as %s: %v", id, status, err)
+ }
+ if !ok {
+ if out, closed := b.closed(ctx, id, owner); closed {
+ return out
+ }
+ }
+ return Outcome{
+ Prompt: &types.AgentPrompt{ID: id, Status: status, CloseReason: reason},
+ TimedOut: status == types.AgentPromptExpired,
+ Canceled: status == types.AgentPromptCanceled,
+ Reason: reason,
+ }
+}
+
+// closed reads the row and reports its outcome once the owner should stop
+// waiting: the prompt ended, or another replica suspended it after this
+// owner's lease lapsed.
+func (b *Broker) closed(ctx context.Context, id, owner string) (Outcome, bool) {
+ row, err := b.store.Get(ctx, id)
+ if err != nil {
+ logger.GetLogger(ctx).Warnf("read agent prompt %s: %v", id, err)
+ return Outcome{}, false
+ }
+ if row == nil || row.Status == types.AgentPromptPending {
+ return Outcome{}, false
+ }
+ if row.OwnerInstance != owner {
+ return Outcome{Prompt: row, Suspended: true, Detached: true, ExpiresAt: row.ExpiresAt}, true
+ }
+ if row.Status == types.AgentPromptSuspended {
+ return Outcome{Prompt: row, Suspended: true, ExpiresAt: row.ExpiresAt}, true
+ }
+ return Outcome{
+ Prompt: row,
+ Answered: row.Status == types.AgentPromptAnswered,
+ TimedOut: row.Status == types.AgentPromptExpired,
+ Canceled: row.Status == types.AgentPromptCanceled,
+ Reason: row.CloseReason,
+ }, true
+}
+
+// Consume claims an answered prompt before its owner acts on it:
+// AgentPromptExecuting when the answer authorized a side effect still to run,
+// AgentPromptDone otherwise. Only the winner may continue the run.
+// Prompts closed by the system are left alone.
+//
+// A storage error is distinct from a lost claim: callers must fail the tool
+// without detaching the run, so ordinary completion can persist its message.
+// Neither outcome permits executing the authorized side effect.
+func (b *Broker) Consume(ctx context.Context, id, to, owner string) (bool, error) {
+ ctx = context.WithoutCancel(ctx)
+ transition := types.AgentPromptTransition{
+ From: []string{types.AgentPromptAnswered},
+ To: to,
+ ExpectedOwner: &owner,
+ }
+ var lastErr error
+ for attempt := 0; ; attempt++ {
+ ok, err := b.store.Transition(ctx, id, transition)
+ if err == nil && (ok || attempt == 0) {
+ return ok, nil
+ }
+ if err == nil {
+ // An earlier attempt may have committed before failing.
+ break
+ }
+ lastErr = err
+ if attempt == len(consumeRetryDelays) {
+ break
+ }
+ time.Sleep(consumeRetryDelays[attempt])
+ }
+ row, readErr := b.store.Get(ctx, id)
+ if readErr == nil {
+ if row == nil || row.OwnerInstance != owner {
+ return false, nil
+ }
+ if row.Status == to {
+ return true, nil
+ }
+ if row.Status != types.AgentPromptAnswered {
+ return false, nil
+ }
+ }
+ // We could not confirm a durable claim. Close only this owner's prompt;
+ // a concurrent takeover must not be canceled by the stale caller.
+ reason := "could not persist prompt consumption; tool was not executed"
+ _, closeErr := b.store.Transition(ctx, id, types.AgentPromptTransition{
+ From: []string{types.AgentPromptAnswered, types.AgentPromptExecuting},
+ To: types.AgentPromptFailed,
+ ExpectedOwner: &owner,
+ CloseReason: &reason,
+ })
+ err := fmt.Errorf("consume agent prompt %s: %w", id, errors.Join(lastErr, readErr, closeErr))
+ logger.GetLogger(ctx).Warnf("%v", err)
+ return false, err
+}
+
+// MarkExecuted records that the side effect an answer authorized has run.
+func (b *Broker) MarkExecuted(ctx context.Context, id string) {
+ if id == "" {
+ return
+ }
+ _, err := b.store.Transition(context.WithoutCancel(ctx), id, types.AgentPromptTransition{
+ From: []string{types.AgentPromptExecuting},
+ To: types.AgentPromptDone,
+ })
+ if err != nil {
+ logger.GetLogger(ctx).Warnf("mark agent prompt %s executed: %v", id, err)
+ }
+}
+
+// Resolution is the result of a recorded answer.
+type Resolution struct {
+ // Prompt is the answered row.
+ Prompt *types.AgentPrompt
+ // Resume means the prompt was suspended: its run has ended and the
+ // caller must resume it. This replica now holds the prompt's lease; see
+ // KeepLease.
+ Resume bool
+ // OwnerGone means the run was suspended on behalf of an owner that
+ // stopped renewing its lease, so nothing will tear down what that owner
+ // left behind (such as its live-run marker). Otherwise the owner suspended
+ // the run itself and may still be finishing it.
+ OwnerGone bool
+ // OwnerLeaseUntil bounds how long the previous waiter may still finish.
+ OwnerLeaseUntil *time.Time
+}
+
+// Resolve records a user answer on an open prompt. A pending prompt's waiter
+// is woken; a suspended prompt is handed to the caller to resume. The tenant
+// must match the prompt; when the prompt was registered with a user, the
+// caller must present that same non-empty user.
+func (b *Broker) Resolve(ctx context.Context, req ResolveRequest) (Resolution, error) {
+ row, err := b.store.Get(ctx, req.PromptID)
+ if err != nil {
+ return Resolution{}, err
+ }
+ if row == nil ||
+ (req.Kind != "" && row.Kind != req.Kind) ||
+ (req.SessionID != "" && row.SessionID != req.SessionID) {
+ return Resolution{}, ErrPromptNotFound
+ }
+ if row.TenantID != req.TenantID {
+ return Resolution{}, ErrTenantMismatch
+ }
+ // An empty caller userID is a mismatch (fail-close) so a missing auth
+ // middleware cannot bypass the per-user check.
+ if row.UserID != "" && row.UserID != req.UserID {
+ return Resolution{}, ErrUserMismatch
+ }
+ if !row.IsOpen() {
+ return Resolution{}, ErrAlreadyResolved
+ }
+
+ b.mu.Lock()
+ validate := b.validators[row.Kind]
+ b.mu.Unlock()
+ if validate == nil {
+ return Resolution{}, fmt.Errorf("%w: unsupported prompt kind %q", ErrInvalidResponse, row.Kind)
+ }
+ if err := validate(json.RawMessage(row.Request), req.Response); err != nil {
+ return Resolution{}, fmt.Errorf("%w: %v", ErrInvalidResponse, err)
+ }
+
+ now := time.Now()
+ // A pending prompt whose owner stopped renewing has no waiter left to
+ // wake. Suspend it as the reaper would, so the answer resumes the run
+ // instead of being recorded for nobody.
+ if row.Status == types.AgentPromptPending && row.Suspendable &&
+ row.LeaseUntil != nil && row.LeaseUntil.Before(now) {
+ b.reapPending(ctx, now, row, b.hooks())
+ if row, err = b.store.Get(ctx, req.PromptID); err != nil {
+ return Resolution{}, err
+ }
+ if row == nil {
+ return Resolution{}, ErrPromptNotFound
+ }
+ if !row.IsOpen() {
+ return Resolution{}, ErrAlreadyResolved
+ }
+ }
+ ownerLeaseUntil := row.LeaseUntil
+ ownerGone := row.OwnerInstance == "" ||
+ (row.Status == types.AgentPromptSuspended && ownerLeaseUntil != nil && ownerLeaseUntil.Before(now))
+ resolvedBy := req.UserID
+ answer := func(t types.AgentPromptTransition) (bool, error) {
+ t.To = types.AgentPromptAnswered
+ t.Response = types.JSON(req.Response)
+ t.ResolvedBy = &resolvedBy
+ t.ResolvedAt = &now
+ return b.store.Transition(ctx, req.PromptID, t)
+ }
+
+ owner, lease := uuid.NewString(), now.Add(b.leaseTTL)
+ ok, err := answer(types.AgentPromptTransition{
+ From: []string{types.AgentPromptSuspended},
+ UnexpiredAt: &now,
+ Owner: &owner,
+ LeaseUntil: &lease,
+ })
+ if err != nil {
+ return Resolution{}, err
+ }
+ if ok {
+ row.Status, row.Response = types.AgentPromptAnswered, types.JSON(req.Response)
+ row.ResolvedBy, row.ResolvedAt = resolvedBy, &now
+ row.OwnerInstance, row.LeaseUntil = owner, &lease
+ return Resolution{Prompt: row, Resume: true, OwnerGone: ownerGone, OwnerLeaseUntil: ownerLeaseUntil}, nil
+ }
+
+ ok, err = answer(types.AgentPromptTransition{From: []string{types.AgentPromptPending}})
+ if err != nil {
+ return Resolution{}, err
+ }
+ if !ok {
+ return Resolution{}, ErrAlreadyResolved
+ }
+ b.wake(ctx, req.PromptID)
+ row.Status, row.Response = types.AgentPromptAnswered, types.JSON(req.Response)
+ row.ResolvedBy, row.ResolvedAt = resolvedBy, &now
+ return Resolution{Prompt: row}, nil
+}
+
+// KeepLease renews this replica's lease on a prompt it resumes until stop is
+// called or the prompt leaves the leased states. Without it the reaper
+// treats the resumed run as abandoned.
+func (b *Broker) KeepLease(ctx context.Context, id, owner string) (stop func()) {
+ ctx, cancel := context.WithCancel(context.WithoutCancel(ctx))
+ go func() {
+ ticker := time.NewTicker(b.renewInterval)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-ctx.Done():
+ return
+ case <-ticker.C:
+ ok, err := b.store.RenewLease(ctx, id, owner, time.Now().Add(b.leaseTTL))
+ if err != nil {
+ logger.GetLogger(ctx).Warnf("renew agent prompt lease %s: %v", id, err)
+ continue
+ }
+ if !ok {
+ return
+ }
+ }
+ }
+ }()
+ return cancel
+}
+
+// Fail closes a prompt the caller holds (answered or executing) whose run
+// could not go on.
+func (b *Broker) Fail(ctx context.Context, id, reason string) {
+ _, err := b.store.Transition(context.WithoutCancel(ctx), id, types.AgentPromptTransition{
+ From: []string{types.AgentPromptAnswered, types.AgentPromptExecuting},
+ To: types.AgentPromptFailed,
+ CloseReason: &reason,
+ })
+ if err != nil {
+ logger.GetLogger(ctx).Warnf("fail agent prompt %s: %v", id, err)
+ }
+}
+
+func (b *Broker) register(id string) <-chan struct{} {
+ ch := make(chan struct{}, 1)
+ b.mu.Lock()
+ b.waiters[id] = ch
+ b.mu.Unlock()
+ return ch
+}
+
+func (b *Broker) unregister(id string) {
+ b.mu.Lock()
+ delete(b.waiters, id)
+ b.mu.Unlock()
+}
+
+// wakeLocal nudges a waiter on this process; it reports whether one exists.
+func (b *Broker) wakeLocal(id string) bool {
+ b.mu.Lock()
+ ch, ok := b.waiters[id]
+ b.mu.Unlock()
+ if !ok {
+ return false
+ }
+ select {
+ case ch <- struct{}{}:
+ default:
+ }
+ return true
+}
+
+type wakeMessage struct {
+ PromptID string `json:"prompt_id"`
+ OriginID string `json:"origin_id,omitempty"`
+}
+
+func pubsubChannel() string {
+ if ns := strings.TrimSpace(os.Getenv("WEKNORA_REDIS_NAMESPACE")); ns != "" {
+ return pubsubChannelBase + ":" + ns
+ }
+ return pubsubChannelBase
+}
+
+// wake nudges the waiter wherever it lives. Delivery is best-effort: the
+// waiter's poll observes the answer even if the pub/sub message is lost.
+func (b *Broker) wake(ctx context.Context, id string) {
+ if b.wakeLocal(id) || b.rdb == nil {
+ return
+ }
+ payload, err := json.Marshal(wakeMessage{PromptID: id, OriginID: instanceID})
+ if err != nil {
+ return
+ }
+ pubCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 2*time.Second)
+ defer cancel()
+ if err := b.rdb.Publish(pubCtx, pubsubChannel(), payload).Err(); err != nil {
+ logger.GetLogger(ctx).Warnf("agent prompt pubsub wake: %v", err)
+ }
+}
+
+// runSubscriber listens for cross-instance wake-ups for the process lifetime.
+func (b *Broker) runSubscriber() {
+ ctx := context.Background()
+ channel := pubsubChannel()
+ backoff := time.Second
+ const maxBackoff = 30 * time.Second
+ for {
+ sub := b.rdb.Subscribe(ctx, channel)
+ for msg := range sub.Channel() {
+ backoff = time.Second
+ var m wakeMessage
+ if err := json.Unmarshal([]byte(msg.Payload), &m); err != nil {
+ logger.GetLogger(ctx).Warnf("agent prompt pubsub: bad payload: %v", err)
+ continue
+ }
+ if m.OriginID != instanceID {
+ b.wakeLocal(m.PromptID)
+ }
+ }
+ _ = sub.Close()
+ time.Sleep(backoff)
+ backoff = min(backoff*2, maxBackoff)
+ }
+}
diff --git a/internal/agent/hitl/broker_test.go b/internal/agent/hitl/broker_test.go
new file mode 100644
index 000000000..45e28148d
--- /dev/null
+++ b/internal/agent/hitl/broker_test.go
@@ -0,0 +1,366 @@
+package hitl
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+)
+
+// testKind stands in for any prompt kind: the broker must not care what the
+// request and response mean.
+const testKind = "test_question"
+
+func validateTestAnswer(_, response json.RawMessage) error {
+ var r struct {
+ Answer string `json:"answer"`
+ }
+ if err := json.Unmarshal(response, &r); err != nil {
+ return err
+ }
+ if r.Answer == "" {
+ return errors.New("answer is required")
+ }
+ return nil
+}
+
+func newTestBroker(store Store) *Broker {
+ b := NewBroker(store, nil, WithPollInterval(20*time.Millisecond))
+ b.RegisterKind(testKind, validateTestAnswer)
+ return b
+}
+
+func testSpec(timeout time.Duration, emit func(ctx context.Context, p *types.AgentPrompt) error) Spec {
+ return Spec{
+ Prompt: &types.AgentPrompt{
+ TenantID: 1, UserID: "alice", SessionID: "s1", AssistantMessageID: "m1",
+ Kind: testKind, Request: types.JSON(`{"question":"which?"}`),
+ },
+ Timeout: timeout,
+ TimeoutReason: "no answer",
+ Emit: emit,
+ }
+}
+
+func answer(promptID, text string) ResolveRequest {
+ return ResolveRequest{
+ TenantID: 1, UserID: "alice", SessionID: "s1", Kind: testKind, PromptID: promptID,
+ Response: json.RawMessage(`{"answer":"` + text + `"}`),
+ }
+}
+
+func TestBroker_AnswerOnOtherReplicaReachesOwnerThroughStore(t *testing.T) {
+ store := NewMemoryStore()
+ owner, other := newTestBroker(store), newTestBroker(store)
+
+ out, err := owner.Await(context.Background(), testSpec(5*time.Second,
+ func(_ context.Context, p *types.AgentPrompt) error {
+ go func() { require.NoError(t, resolveErr(context.Background(), other, answer(p.ID, "blue"))) }()
+ return nil
+ }))
+ require.NoError(t, err)
+ require.True(t, out.Answered)
+ require.JSONEq(t, `{"answer":"blue"}`, string(out.Prompt.Response))
+ require.Equal(t, "alice", out.Prompt.ResolvedBy)
+
+ require.True(t, consumeWithoutError(context.Background(), t, owner,
+ out.Prompt.ID, types.AgentPromptDone, out.Prompt.OwnerInstance))
+ row, err := store.Get(context.Background(), out.Prompt.ID)
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptDone, row.Status)
+}
+
+func TestBroker_ResolveChecksScopeOwnershipAndAnswer(t *testing.T) {
+ b := newTestBroker(NewMemoryStore())
+ out, err := b.Await(context.Background(), testSpec(5*time.Second,
+ func(_ context.Context, p *types.AgentPrompt) error {
+ go func() {
+ ctx := context.Background()
+ otherSession := answer(p.ID, "x")
+ otherSession.SessionID = "s2"
+ require.ErrorIs(t, resolveErr(ctx, b, otherSession), ErrPromptNotFound)
+
+ otherKind := answer(p.ID, "x")
+ otherKind.Kind = "something_else"
+ require.ErrorIs(t, resolveErr(ctx, b, otherKind), ErrPromptNotFound)
+
+ otherTenant := answer(p.ID, "x")
+ otherTenant.TenantID = 2
+ require.ErrorIs(t, resolveErr(ctx, b, otherTenant), ErrTenantMismatch)
+
+ anonymous := answer(p.ID, "x")
+ anonymous.UserID = ""
+ require.ErrorIs(t, resolveErr(ctx, b, anonymous), ErrUserMismatch)
+
+ require.ErrorIs(t, resolveErr(ctx, b, answer(p.ID, "")), ErrInvalidResponse)
+
+ require.NoError(t, resolveErr(ctx, b, answer(p.ID, "red")))
+ require.ErrorIs(t, resolveErr(ctx, b, answer(p.ID, "green")), ErrAlreadyResolved)
+ }()
+ return nil
+ }))
+ require.NoError(t, err)
+ require.True(t, out.Answered)
+ require.JSONEq(t, `{"answer":"red"}`, string(out.Prompt.Response))
+}
+
+func TestBroker_UnregisteredKindIsRejected(t *testing.T) {
+ b := NewBroker(nil, nil, WithPollInterval(20*time.Millisecond))
+ out, err := b.Await(context.Background(), testSpec(200*time.Millisecond,
+ func(_ context.Context, p *types.AgentPrompt) error {
+ require.ErrorIs(t, resolveErr(context.Background(), b, answer(p.ID, "x")), ErrInvalidResponse)
+ return nil
+ }))
+ require.NoError(t, err)
+ require.True(t, out.TimedOut)
+}
+
+// An answer recorded without a wake-up must win over the owner's timeout.
+func TestBroker_AnswerRecordedBeforeTimeoutWins(t *testing.T) {
+ store := NewMemoryStore()
+ b := NewBroker(store, nil, WithPollInterval(time.Hour))
+ out, err := b.Await(context.Background(), testSpec(300*time.Millisecond,
+ func(_ context.Context, p *types.AgentPrompt) error {
+ _, err := store.Transition(context.Background(), p.ID, types.AgentPromptTransition{
+ From: []string{types.AgentPromptPending}, To: types.AgentPromptAnswered,
+ Response: types.JSON(`{"answer":"late"}`),
+ })
+ return err
+ }))
+ require.NoError(t, err)
+ require.True(t, out.Answered)
+ require.False(t, out.TimedOut)
+}
+
+func TestBroker_TimeoutAndCancelAreRecorded(t *testing.T) {
+ b := newTestBroker(NewMemoryStore())
+
+ var timedOutID string
+ out, err := b.Await(context.Background(), testSpec(100*time.Millisecond,
+ func(_ context.Context, p *types.AgentPrompt) error { timedOutID = p.ID; return nil }))
+ require.NoError(t, err)
+ require.True(t, out.TimedOut)
+ require.Equal(t, "no answer", out.Reason)
+ require.ErrorIs(t, resolveErr(context.Background(), b, answer(timedOutID, "x")), ErrAlreadyResolved)
+
+ ctx, cancel := context.WithCancel(context.Background())
+ out, err = b.Await(ctx, testSpec(time.Minute,
+ func(context.Context, *types.AgentPrompt) error { cancel(); return nil }))
+ require.NoError(t, err)
+ require.True(t, out.Canceled)
+ row, err := b.Store().Get(context.Background(), out.Prompt.ID)
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptCanceled, row.Status)
+}
+
+func TestBroker_ExecutingUntilMarkedExecuted(t *testing.T) {
+ b := newTestBroker(NewMemoryStore())
+ out, err := b.Await(context.Background(), testSpec(5*time.Second,
+ func(_ context.Context, p *types.AgentPrompt) error {
+ go func() { require.NoError(t, resolveErr(context.Background(), b, answer(p.ID, "go"))) }()
+ return nil
+ }))
+ require.NoError(t, err)
+
+ require.True(t, consumeWithoutError(context.Background(), t, b,
+ out.Prompt.ID, types.AgentPromptExecuting, out.Prompt.OwnerInstance))
+ row, _ := b.Store().Get(context.Background(), out.Prompt.ID)
+ require.Equal(t, types.AgentPromptExecuting, row.Status)
+
+ b.MarkExecuted(context.Background(), out.Prompt.ID)
+ row, _ = b.Store().Get(context.Background(), out.Prompt.ID)
+ require.Equal(t, types.AgentPromptDone, row.Status)
+}
+
+func resolveErr(ctx context.Context, b *Broker, req ResolveRequest) error {
+ _, err := b.Resolve(ctx, req)
+ return err
+}
+
+func TestBrokerConsumeFencesOwnerAndOnlyWinsOnce(t *testing.T) {
+ b := newTestBroker(NewMemoryStore())
+ ctx := t.Context()
+ require.NoError(t, b.store.Create(ctx, &types.AgentPrompt{
+ ID: "p", Status: types.AgentPromptAnswered, OwnerInstance: "new-run",
+ }))
+ require.False(t, consumeWithoutError(ctx, t, b, "p", types.AgentPromptExecuting, "old-run"))
+ require.True(t, consumeWithoutError(ctx, t, b, "p", types.AgentPromptExecuting, "new-run"))
+ require.False(t, consumeWithoutError(ctx, t, b, "p", types.AgentPromptExecuting, "new-run"))
+}
+
+func TestBrokerWaiterDetachesAfterTakeoverOnSameReplica(t *testing.T) {
+ b := newTestBroker(NewMemoryStore())
+ ctx := t.Context()
+ var resumed Resolution
+ out, err := b.Await(ctx, suspendableSpec(time.Second, func(_ context.Context, p *types.AgentPrompt) error {
+ oldOwner := p.OwnerInstance
+ past := time.Now().Add(-time.Second)
+ _, err := b.store.Transition(ctx, p.ID, types.AgentPromptTransition{
+ From: []string{types.AgentPromptPending}, To: types.AgentPromptPending, LeaseUntil: &past,
+ })
+ require.NoError(t, err)
+ resumed, err = b.Resolve(ctx, answer(p.ID, "blue"))
+ require.NoError(t, err)
+ require.True(t, resumed.Resume)
+ require.NotEqual(t, oldOwner, resumed.Prompt.OwnerInstance)
+ return nil
+ }))
+ require.NoError(t, err)
+ require.True(t, out.Detached)
+ require.True(t, out.Suspended)
+ require.False(t, out.Answered)
+ snapshot, err := b.suspensions.Get(ctx, out.Prompt.AssistantMessageID)
+ require.NoError(t, err)
+ require.NotNil(t, snapshot, "the stale waiter must not delete the new owner's state")
+ require.True(t, consumeWithoutError(ctx, t, b,
+ resumed.Prompt.ID, types.AgentPromptExecuting, resumed.Prompt.OwnerInstance))
+}
+
+type renewBeforeTransitionStore struct {
+ Store
+ renew bool
+}
+
+func (s *renewBeforeTransitionStore) Transition(
+ ctx context.Context, id string, tr types.AgentPromptTransition,
+) (bool, error) {
+ if s.renew {
+ s.renew = false
+ row, err := s.Get(ctx, id)
+ if err != nil {
+ return false, err
+ }
+ if _, err := s.RenewLease(ctx, id, row.OwnerInstance, time.Now().Add(time.Hour)); err != nil {
+ return false, err
+ }
+ }
+ return s.Store.Transition(ctx, id, tr)
+}
+
+func TestReaperDoesNotTakeOverLeaseRenewedAfterScan(t *testing.T) {
+ for _, status := range []string{types.AgentPromptPending, types.AgentPromptAnswered, types.AgentPromptExecuting} {
+ t.Run(status, func(t *testing.T) {
+ ctx := t.Context()
+ store := &renewBeforeTransitionStore{Store: NewMemoryStore(), renew: true}
+ b := NewBroker(store, nil)
+ past := time.Now().Add(-time.Minute)
+ require.NoError(t, store.Create(ctx, &types.AgentPrompt{
+ ID: "p", Status: status, OwnerInstance: "owner", LeaseUntil: &past,
+ Suspendable: true, AssistantMessageID: "m",
+ }))
+ require.NoError(t, b.suspensions.Save(ctx, &types.AgentRunSuspension{
+ AssistantMessageID: "m", PromptID: "p", Snapshot: types.JSON(`{"version":1}`),
+ }))
+ n, err := b.Reap(ctx, time.Now(), RunHooks{Closed: func(
+ context.Context, *types.AgentPrompt, *types.AgentRunSuspension, string,
+ ) error {
+ t.Fatal("must not close a renewed run")
+ return nil
+ }})
+ require.NoError(t, err)
+ require.Zero(t, n)
+ row, err := store.Get(ctx, "p")
+ require.NoError(t, err)
+ require.Equal(t, status, row.Status)
+ saved, err := b.suspensions.Get(ctx, "m")
+ require.NoError(t, err)
+ require.NotNil(t, saved)
+ })
+ }
+}
+
+// flakyTransitionStore fails the next failures Transition calls; with
+// committed set, each failing call still applies before reporting its error.
+type flakyTransitionStore struct {
+ Store
+ failures int
+ committed bool
+ readError bool
+}
+
+func (s *flakyTransitionStore) Transition(
+ ctx context.Context, id string, tr types.AgentPromptTransition,
+) (bool, error) {
+ if s.failures > 0 {
+ s.failures--
+ if s.committed {
+ _, _ = s.Store.Transition(ctx, id, tr)
+ }
+ return false, errors.New("database unavailable")
+ }
+ return s.Store.Transition(ctx, id, tr)
+}
+
+func consumeWithoutError(ctx context.Context, t *testing.T, b *Broker, id, to, owner string) bool {
+ t.Helper()
+ ok, err := b.Consume(ctx, id, to, owner)
+ require.NoError(t, err)
+ return ok
+}
+
+func (s *flakyTransitionStore) Get(ctx context.Context, id string) (*types.AgentPrompt, error) {
+ if s.readError {
+ return nil, errors.New("read unavailable")
+ }
+ return s.Store.Get(ctx, id)
+}
+
+func TestBroker_ConsumeTellsAStoreFailureFromALostClaim(t *testing.T) {
+ saved := consumeRetryDelays
+ consumeRetryDelays = []time.Duration{0, 0}
+ t.Cleanup(func() { consumeRetryDelays = saved })
+ cases := map[string]struct {
+ failures int
+ committed, readError bool
+ rowOwner string
+ want, wantErr bool
+ status string
+ }{
+ "confirms a claim committed before its error": {
+ failures: 1, committed: true, rowOwner: "me", want: true, status: types.AgentPromptExecuting,
+ },
+ "recovers after transient failures": {
+ failures: 2, rowOwner: "me", want: true, status: types.AgentPromptExecuting,
+ },
+ "does not execute through a write outage": {
+ failures: 10, rowOwner: "me", wantErr: true, status: types.AgentPromptAnswered,
+ },
+ "closes an unclaimed answer when storage recovers": {
+ failures: 3, rowOwner: "me", wantErr: true, status: types.AgentPromptFailed,
+ },
+ "does not execute through a read outage": {
+ failures: 10, readError: true, rowOwner: "me", wantErr: true, status: types.AgentPromptAnswered,
+ },
+ "unknown owner cannot execute or cancel a takeover": {
+ failures: 3, readError: true, rowOwner: "other", wantErr: true, status: types.AgentPromptAnswered,
+ },
+ "gives up an answer another owner holds": {
+ failures: 10, rowOwner: "other", status: types.AgentPromptAnswered,
+ },
+ "gives up without any failure when not owned": {
+ rowOwner: "other", status: types.AgentPromptAnswered,
+ },
+ }
+ for name, tc := range cases {
+ t.Run(name, func(t *testing.T) {
+ ctx := t.Context()
+ store := &flakyTransitionStore{
+ Store: NewMemoryStore(), failures: tc.failures, committed: tc.committed, readError: tc.readError,
+ }
+ require.NoError(t, store.Create(ctx, &types.AgentPrompt{
+ ID: "p", Status: types.AgentPromptAnswered, OwnerInstance: tc.rowOwner,
+ }))
+ b := NewBroker(store, nil)
+ ok, err := b.Consume(ctx, "p", types.AgentPromptExecuting, "me")
+ require.Equal(t, tc.want, ok)
+ require.Equal(t, tc.wantErr, err != nil)
+ row, err := store.Store.Get(ctx, "p")
+ require.NoError(t, err)
+ require.Equal(t, tc.status, row.Status)
+ })
+ }
+}
diff --git a/internal/agent/hitl/reaper.go b/internal/agent/hitl/reaper.go
new file mode 100644
index 000000000..8aa9a38bf
--- /dev/null
+++ b/internal/agent/hitl/reaper.go
@@ -0,0 +1,208 @@
+package hitl
+
+import (
+ "context"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// reapBatch bounds how many prompts one sweep handles per rule.
+const reapBatch = 100
+
+// Reasons recorded on prompts the system closes, and shown for the calls
+// they blocked.
+const (
+ ReasonOwnerStopped = "the replica waiting on this prompt stopped"
+ ReasonResumeStopped = "the run resuming after this prompt was interrupted before the tool ran"
+ ReasonExecuteStopped = "the run was interrupted while the approved tool was running; its outcome is unknown"
+ ReasonPromptExpired = "the prompt expired before it was answered"
+ ReasonPromptSupersede = "the user moved on without answering this prompt"
+)
+
+// RunHooks finish the assistant message of a run the reaper or a supersede
+// takes over.
+type RunHooks struct {
+ // Suspended shows a run whose owner disappeared while waiting the way a
+ // run that suspended itself looks: the saved steps, waiting on prompt.
+ Suspended func(ctx context.Context, prompt *types.AgentPrompt, state *types.AgentRunSuspension) error
+ // Closed completes a run that will never resume. reason explains what
+ // happened to the blocked call and the calls after it.
+ Closed func(ctx context.Context, prompt *types.AgentPrompt, state *types.AgentRunSuspension, reason string) error
+}
+
+// Reap takes over prompts their owner can no longer finish:
+//
+// 1. pending, lease lapsed: the owner died during the in-memory wait. A
+// suspendable prompt with saved state is suspended, any other expires.
+// 2. answered or executing, lease lapsed, saved state present: the replica
+// resuming the run died. The prompt fails and the run is closed; an
+// executing tool is never replayed.
+// 3. suspended past its expiry: the prompt expires and the run is closed.
+//
+// It returns how many prompts it took over.
+func (b *Broker) Reap(ctx context.Context, now time.Time, hooks RunHooks) (int, error) {
+ reaped := 0
+
+ pending, err := b.store.ListStaleLeases(ctx, []string{types.AgentPromptPending}, now, reapBatch)
+ if err != nil {
+ return 0, err
+ }
+ for _, row := range pending {
+ if b.reapPending(ctx, now, row, hooks) {
+ reaped++
+ }
+ }
+
+ resuming, err := b.store.ListStaleLeases(ctx,
+ []string{types.AgentPromptAnswered, types.AgentPromptExecuting}, now, reapBatch)
+ if err != nil {
+ return reaped, err
+ }
+ for _, row := range resuming {
+ state := b.runState(ctx, row)
+ if state == nil {
+ // An in-memory waiter consumed it; nothing to resume or close.
+ continue
+ }
+ reason := ReasonResumeStopped
+ if row.Status == types.AgentPromptExecuting {
+ reason = ReasonExecuteStopped
+ }
+ if b.closeRun(ctx, row, state, []string{row.Status}, types.AgentPromptFailed, reason, hooks, now) {
+ reaped++
+ }
+ }
+
+ expired, err := b.store.ListExpired(ctx, now, reapBatch)
+ if err != nil {
+ return reaped, err
+ }
+ for _, row := range expired {
+ if b.closeRun(ctx, row, b.runState(ctx, row),
+ []string{types.AgentPromptSuspended}, types.AgentPromptExpired, ReasonPromptExpired, hooks) {
+ reaped++
+ }
+ }
+ return reaped, nil
+}
+
+// SupersedeSession closes the session's suspended prompts because the user
+// moved on (sent a new message, rewound), completing their runs so the
+// conversation history stays well formed. It returns how many it closed.
+func (b *Broker) SupersedeSession(ctx context.Context, sessionID string, hooks RunHooks) (int, error) {
+ rows, err := b.store.ListBySession(ctx, sessionID, []string{types.AgentPromptSuspended})
+ if err != nil {
+ return 0, err
+ }
+ n := 0
+ for _, row := range rows {
+ if b.closeRun(ctx, row, b.runState(ctx, row),
+ []string{types.AgentPromptSuspended}, types.AgentPromptSuperseded, ReasonPromptSupersede, hooks) {
+ n++
+ }
+ }
+ return n, nil
+}
+
+// runState returns the saved state of row's run, or nil when there is none
+// or it belongs to another prompt.
+func (b *Broker) runState(ctx context.Context, row *types.AgentPrompt) *types.AgentRunSuspension {
+ if !row.Suspendable || row.AssistantMessageID == "" {
+ return nil
+ }
+ saved, err := b.suspensions.Get(ctx, row.AssistantMessageID)
+ if err != nil {
+ logger.GetLogger(ctx).Warnf("read run state of prompt %s: %v", row.ID, err)
+ return nil
+ }
+ if saved == nil || saved.PromptID != row.ID {
+ return nil
+ }
+ return saved
+}
+
+func (b *Broker) reapPending(ctx context.Context, now time.Time, row *types.AgentPrompt, hooks RunHooks) bool {
+ log := logger.GetLogger(ctx)
+ state := b.runState(ctx, row)
+ if state == nil {
+ reason := ReasonOwnerStopped
+ ok, err := b.store.Transition(ctx, row.ID, types.AgentPromptTransition{
+ From: []string{types.AgentPromptPending},
+ To: types.AgentPromptExpired,
+ ExpectedOwner: &row.OwnerInstance,
+ LeaseBefore: &now,
+ CloseReason: &reason,
+ })
+ if err != nil {
+ log.Warnf("expire orphaned agent prompt %s: %v", row.ID, err)
+ }
+ return ok
+ }
+
+ expiresAt := b.expiresAt(now)
+ // Clearing the owner records that the run was suspended for it, which
+ // Resolve reports as Resolution.OwnerGone.
+ noOwner := ""
+ ok, err := b.store.Transition(ctx, row.ID, types.AgentPromptTransition{
+ From: []string{types.AgentPromptPending},
+ To: types.AgentPromptSuspended,
+ ExpiresAt: expiresAt,
+ Owner: &noOwner,
+ ExpectedOwner: &row.OwnerInstance,
+ LeaseBefore: &now,
+ })
+ if err != nil {
+ log.Warnf("suspend orphaned agent prompt %s: %v", row.ID, err)
+ }
+ if !ok {
+ return false
+ }
+ row.Status = types.AgentPromptSuspended
+ row.ExpiresAt = expiresAt
+ row.OwnerInstance = ""
+ if hooks.Suspended != nil {
+ if err := hooks.Suspended(ctx, row, state); err != nil {
+ log.Warnf("finish suspended run of message %s: %v", row.AssistantMessageID, err)
+ }
+ }
+ return true
+}
+
+// closeRun moves row from one of from to `to`, then completes its run and
+// drops the saved state. state may be nil when the run left none.
+func (b *Broker) closeRun(
+ ctx context.Context, row *types.AgentPrompt, state *types.AgentRunSuspension,
+ from []string, to, reason string, hooks RunHooks, staleBefore ...time.Time,
+) bool {
+ log := logger.GetLogger(ctx)
+ transition := types.AgentPromptTransition{
+ From: from,
+ To: to,
+ CloseReason: &reason,
+ }
+ if len(staleBefore) > 0 {
+ transition.ExpectedOwner = &row.OwnerInstance
+ transition.LeaseBefore = &staleBefore[0]
+ }
+ ok, err := b.store.Transition(ctx, row.ID, transition)
+ if err != nil {
+ log.Warnf("close agent prompt %s as %s: %v", row.ID, to, err)
+ }
+ if !ok {
+ return false
+ }
+ row.Status, row.CloseReason = to, reason
+ if state == nil {
+ return true
+ }
+ if hooks.Closed != nil {
+ if err := hooks.Closed(ctx, row, state, reason); err != nil {
+ log.Warnf("close run of message %s: %v", row.AssistantMessageID, err)
+ return true
+ }
+ }
+ b.dropSnapshot(ctx, row.AssistantMessageID, row.ID)
+ return true
+}
diff --git a/internal/agent/hitl/resume_test.go b/internal/agent/hitl/resume_test.go
new file mode 100644
index 000000000..841bdce6e
--- /dev/null
+++ b/internal/agent/hitl/resume_test.go
@@ -0,0 +1,175 @@
+package hitl
+
+import (
+ "context"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+)
+
+// seedSuspended stores a suspended prompt for message msgID with saved run
+// state, expiring at expires.
+func seedSuspended(
+ t *testing.T, b *Broker, id, msgID string, expires time.Time,
+) {
+ t.Helper()
+ ctx := context.Background()
+ require.NoError(t, b.Store().Create(ctx, &types.AgentPrompt{
+ ID: id, TenantID: 1, SessionID: "s1", AssistantMessageID: msgID, Kind: testKind,
+ Status: types.AgentPromptSuspended, Suspendable: true, ExpiresAt: &expires,
+ Request: types.JSON(`{"question":"color?"}`),
+ }))
+ require.NoError(t, b.Suspensions().Save(ctx, &types.AgentRunSuspension{
+ AssistantMessageID: msgID, TenantID: 1, SessionID: "s1", PromptID: id,
+ SnapshotVersion: 1, Snapshot: types.JSON(`{"version":1}`),
+ }))
+}
+
+type hookLog struct {
+ suspended []string
+ closed map[string]string
+}
+
+func (h *hookLog) hooks() RunHooks {
+ h.closed = map[string]string{}
+ return RunHooks{
+ Suspended: func(_ context.Context, p *types.AgentPrompt, _ *types.AgentRunSuspension) error {
+ h.suspended = append(h.suspended, p.ID)
+ return nil
+ },
+ Closed: func(_ context.Context, p *types.AgentPrompt, _ *types.AgentRunSuspension, reason string) error {
+ h.closed[p.ID] = reason
+ return nil
+ },
+ }
+}
+
+func TestBroker_ResolveSuspendedHandsRunToCaller(t *testing.T) {
+ ctx := context.Background()
+ b := newTestBroker(NewMemoryStore())
+ seedSuspended(t, b, "p1", "m1", time.Now().Add(time.Hour))
+
+ res, err := b.Resolve(ctx, answer("p1", "blue"))
+ require.NoError(t, err)
+ require.True(t, res.Resume)
+ require.Equal(t, types.AgentPromptAnswered, res.Prompt.Status)
+
+ row, err := b.Store().Get(ctx, "p1")
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptAnswered, row.Status)
+ require.Equal(t, res.Prompt.OwnerInstance, row.OwnerInstance, "the resuming replica holds the lease")
+ require.NotNil(t, row.LeaseUntil)
+ require.True(t, row.LeaseUntil.After(time.Now()))
+
+ require.ErrorIs(t, resolveErr(ctx, b, answer("p1", "red")), ErrAlreadyResolved)
+}
+
+func TestBroker_ResolveRejectsExpiredSuspension(t *testing.T) {
+ ctx := context.Background()
+ b := newTestBroker(NewMemoryStore())
+ seedSuspended(t, b, "p1", "m1", time.Now().Add(-time.Second))
+
+ require.ErrorIs(t, resolveErr(ctx, b, answer("p1", "blue")), ErrAlreadyResolved)
+ row, err := b.Store().Get(ctx, "p1")
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptSuspended, row.Status, "left for the reaper to expire")
+}
+
+func TestBroker_KeepLeaseRenewsUntilPromptCloses(t *testing.T) {
+ ctx := context.Background()
+ b := NewBroker(nil, nil, withLease(80*time.Millisecond, 10*time.Millisecond))
+ b.RegisterKind(testKind, validateTestAnswer)
+ seedSuspended(t, b, "p1", "m1", time.Now().Add(time.Hour))
+ res, err := b.Resolve(ctx, answer("p1", "blue"))
+ require.NoError(t, err)
+
+ stop := b.KeepLease(ctx, "p1", res.Prompt.OwnerInstance)
+ defer stop()
+ time.Sleep(200 * time.Millisecond)
+ row, err := b.Store().Get(ctx, "p1")
+ require.NoError(t, err)
+ require.True(t, row.LeaseUntil.After(time.Now()), "lease kept past its TTL")
+
+ n, err := b.Reap(ctx, time.Now(), RunHooks{})
+ require.NoError(t, err)
+ require.Zero(t, n, "a run with a live lease is not reaped")
+}
+
+func TestBroker_ReapClosesAbandonedResumeAndExpiredSuspension(t *testing.T) {
+ ctx := context.Background()
+ b := newTestBroker(NewMemoryStore())
+ past, future := time.Now().Add(-time.Minute), time.Now().Add(time.Hour)
+
+ // Resumed, then the resuming replica died before and during the tool.
+ for id, status := range map[string]string{
+ "answered": types.AgentPromptAnswered, "executing": types.AgentPromptExecuting,
+ } {
+ seedSuspended(t, b, id, "m-"+id, future)
+ ok, err := b.Store().Transition(ctx, id, types.AgentPromptTransition{
+ From: []string{types.AgentPromptSuspended}, To: status, LeaseUntil: &past,
+ })
+ require.NoError(t, err)
+ require.True(t, ok)
+ }
+ // Answered in the hot wait: its waiter dropped the run state.
+ require.NoError(t, b.Store().Create(ctx, &types.AgentPrompt{
+ ID: "hot", TenantID: 1, SessionID: "s1", AssistantMessageID: "m-hot", Kind: testKind,
+ Status: types.AgentPromptExecuting, Suspendable: true, LeaseUntil: &past,
+ }))
+ seedSuspended(t, b, "old", "m-old", past)
+ seedSuspended(t, b, "fresh", "m-fresh", future)
+
+ log := &hookLog{}
+ n, err := b.Reap(ctx, time.Now(), log.hooks())
+ require.NoError(t, err)
+ require.Equal(t, 3, n)
+ require.Equal(t, map[string]string{
+ "answered": ReasonResumeStopped,
+ "executing": ReasonExecuteStopped,
+ "old": ReasonPromptExpired,
+ }, log.closed)
+
+ for id, want := range map[string]string{
+ "answered": types.AgentPromptFailed,
+ "executing": types.AgentPromptFailed,
+ "hot": types.AgentPromptExecuting,
+ "old": types.AgentPromptExpired,
+ "fresh": types.AgentPromptSuspended,
+ } {
+ row, err := b.Store().Get(ctx, id)
+ require.NoError(t, err)
+ require.Equal(t, want, row.Status, id)
+ }
+ for msg, kept := range map[string]bool{"m-answered": false, "m-old": false, "m-fresh": true} {
+ saved, err := b.Suspensions().Get(ctx, msg)
+ require.NoError(t, err)
+ require.Equal(t, kept, saved != nil, msg)
+ }
+}
+
+func TestBroker_SupersedeSessionClosesOnlyItsSuspendedPrompts(t *testing.T) {
+ ctx := context.Background()
+ b := newTestBroker(NewMemoryStore())
+ seedSuspended(t, b, "p1", "m1", time.Now().Add(time.Hour))
+ require.NoError(t, b.Store().Create(ctx, &types.AgentPrompt{
+ ID: "other", TenantID: 1, SessionID: "s2", AssistantMessageID: "m2", Kind: testKind,
+ Status: types.AgentPromptSuspended, Suspendable: true,
+ }))
+
+ log := &hookLog{}
+ n, err := b.SupersedeSession(ctx, "s1", log.hooks())
+ require.NoError(t, err)
+ require.Equal(t, 1, n)
+ require.Equal(t, map[string]string{"p1": ReasonPromptSupersede}, log.closed)
+
+ row, err := b.Store().Get(ctx, "p1")
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptSuperseded, row.Status)
+ require.ErrorIs(t, resolveErr(ctx, b, answer("p1", "blue")), ErrAlreadyResolved)
+
+ other, err := b.Store().Get(ctx, "other")
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptSuspended, other.Status)
+}
diff --git a/internal/agent/hitl/store.go b/internal/agent/hitl/store.go
new file mode 100644
index 000000000..7614e5cdf
--- /dev/null
+++ b/internal/agent/hitl/store.go
@@ -0,0 +1,210 @@
+package hitl
+
+import (
+ "context"
+ "errors"
+ "slices"
+ "sync"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+)
+
+// Store persists prompts. Production wiring passes the GORM repository; the
+// in-memory store keeps single-process callers and tests on the same code path.
+type Store = interfaces.AgentPromptRepository
+
+// memoryStore is a process-local Store. It cannot coordinate replicas.
+type memoryStore struct {
+ mu sync.Mutex
+ rows map[string]types.AgentPrompt
+}
+
+// NewMemoryStore returns a process-local Store.
+func NewMemoryStore() Store {
+ return &memoryStore{rows: make(map[string]types.AgentPrompt)}
+}
+
+func (s *memoryStore) Create(_ context.Context, row *types.AgentPrompt) error {
+ if row == nil || row.ID == "" {
+ return errors.New("agent prompt row requires an id")
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ if _, exists := s.rows[row.ID]; exists {
+ return errors.New("agent prompt already exists")
+ }
+ now := time.Now()
+ stored := *row
+ stored.CreatedAt, stored.UpdatedAt = now, now
+ s.rows[row.ID] = stored
+ return nil
+}
+
+func (s *memoryStore) Get(_ context.Context, id string) (*types.AgentPrompt, error) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ row, ok := s.rows[id]
+ if !ok {
+ return nil, nil
+ }
+ return &row, nil
+}
+
+func (s *memoryStore) Transition(_ context.Context, id string, t types.AgentPromptTransition) (bool, error) {
+ if len(t.From) == 0 || t.To == "" {
+ return false, errors.New("transition requires from and to states")
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ row, ok := s.rows[id]
+ if !ok || !slices.Contains(t.From, row.Status) {
+ return false, nil
+ }
+ if t.UnexpiredAt != nil && row.ExpiresAt != nil && !row.ExpiresAt.After(*t.UnexpiredAt) {
+ return false, nil
+ }
+ if t.ExpectedOwner != nil && row.OwnerInstance != *t.ExpectedOwner {
+ return false, nil
+ }
+ if t.LeaseBefore != nil && (row.LeaseUntil == nil || !row.LeaseUntil.Before(*t.LeaseBefore)) {
+ return false, nil
+ }
+ if t.Owner != nil {
+ row.OwnerInstance = *t.Owner
+ }
+ if t.LeaseUntil != nil {
+ at := *t.LeaseUntil
+ row.LeaseUntil = &at
+ }
+ row.Status = t.To
+ row.UpdatedAt = time.Now()
+ if len(t.Response) > 0 {
+ row.Response = t.Response
+ }
+ if t.CloseReason != nil {
+ row.CloseReason = *t.CloseReason
+ }
+ if t.ResolvedBy != nil {
+ row.ResolvedBy = *t.ResolvedBy
+ }
+ if t.ResolvedAt != nil {
+ at := *t.ResolvedAt
+ row.ResolvedAt = &at
+ }
+ if t.ExpiresAt != nil {
+ at := *t.ExpiresAt
+ row.ExpiresAt = &at
+ }
+ s.rows[id] = row
+ return true, nil
+}
+
+func (s *memoryStore) RenewLease(_ context.Context, id, owner string, until time.Time) (bool, error) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ row, ok := s.rows[id]
+ if !ok || !slices.Contains(leasedStatuses, row.Status) || row.OwnerInstance != owner {
+ return false, nil
+ }
+ row.LeaseUntil = &until
+ row.UpdatedAt = time.Now()
+ s.rows[id] = row
+ return true, nil
+}
+
+// leasedStatuses are the states whose row is held by an owner replica.
+var leasedStatuses = []string{types.AgentPromptPending, types.AgentPromptAnswered, types.AgentPromptExecuting}
+
+func (s *memoryStore) ListStaleLeases(
+ _ context.Context, statuses []string, before time.Time, limit int,
+) ([]*types.AgentPrompt, error) {
+ return s.list(limit, func(row types.AgentPrompt) bool {
+ return slices.Contains(statuses, row.Status) && row.LeaseUntil != nil && row.LeaseUntil.Before(before)
+ }, func(row types.AgentPrompt) time.Time { return *row.LeaseUntil }), nil
+}
+
+func (s *memoryStore) ListExpired(_ context.Context, before time.Time, limit int) ([]*types.AgentPrompt, error) {
+ return s.list(limit, func(row types.AgentPrompt) bool {
+ return row.Status == types.AgentPromptSuspended && row.ExpiresAt != nil && row.ExpiresAt.Before(before)
+ }, func(row types.AgentPrompt) time.Time { return *row.ExpiresAt }), nil
+}
+
+func (s *memoryStore) ListBySession(
+ _ context.Context, sessionID string, statuses []string,
+) ([]*types.AgentPrompt, error) {
+ return s.list(0, func(row types.AgentPrompt) bool {
+ return row.SessionID == sessionID && slices.Contains(statuses, row.Status)
+ }, func(row types.AgentPrompt) time.Time { return row.CreatedAt }), nil
+}
+
+// list returns matching rows ordered by key; limit 0 is unlimited.
+func (s *memoryStore) list(
+ limit int, match func(types.AgentPrompt) bool, key func(types.AgentPrompt) time.Time,
+) []*types.AgentPrompt {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ var out []*types.AgentPrompt
+ for _, row := range s.rows {
+ if match(row) {
+ r := row
+ out = append(out, &r)
+ }
+ }
+ slices.SortFunc(out, func(a, b *types.AgentPrompt) int { return key(*a).Compare(key(*b)) })
+ if limit > 0 && len(out) > limit {
+ out = out[:limit]
+ }
+ return out
+}
+
+// SuspensionStore persists the state of runs blocked on a prompt.
+type SuspensionStore = interfaces.AgentRunSuspensionRepository
+
+// memorySuspensionStore is a process-local SuspensionStore.
+type memorySuspensionStore struct {
+ mu sync.Mutex
+ rows map[string]types.AgentRunSuspension
+}
+
+// NewMemorySuspensionStore returns a process-local SuspensionStore.
+func NewMemorySuspensionStore() SuspensionStore {
+ return &memorySuspensionStore{rows: make(map[string]types.AgentRunSuspension)}
+}
+
+func (s *memorySuspensionStore) Save(_ context.Context, row *types.AgentRunSuspension) error {
+ if row == nil || row.AssistantMessageID == "" {
+ return errors.New("agent run suspension requires an assistant message id")
+ }
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ stored := *row
+ stored.UpdatedAt = time.Now()
+ if prev, ok := s.rows[row.AssistantMessageID]; ok {
+ stored.CreatedAt = prev.CreatedAt
+ } else {
+ stored.CreatedAt = stored.UpdatedAt
+ }
+ s.rows[row.AssistantMessageID] = stored
+ return nil
+}
+
+func (s *memorySuspensionStore) Get(_ context.Context, assistantMessageID string) (*types.AgentRunSuspension, error) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ row, ok := s.rows[assistantMessageID]
+ if !ok {
+ return nil, nil
+ }
+ return &row, nil
+}
+
+func (s *memorySuspensionStore) Delete(_ context.Context, assistantMessageID, promptID string) error {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ if row, ok := s.rows[assistantMessageID]; ok && row.PromptID == promptID {
+ delete(s.rows, assistantMessageID)
+ }
+ return nil
+}
diff --git a/internal/agent/hitl/suspend_test.go b/internal/agent/hitl/suspend_test.go
new file mode 100644
index 000000000..176d61041
--- /dev/null
+++ b/internal/agent/hitl/suspend_test.go
@@ -0,0 +1,270 @@
+package hitl
+
+import (
+ "context"
+ "errors"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+)
+
+func suspendableSpec(hotWait time.Duration, emit func(ctx context.Context, p *types.AgentPrompt) error) Spec {
+ spec := testSpec(hotWait, emit)
+ spec.Suspend = &SuspendSpec{Snapshot: []byte(`{"version":1}`), SnapshotVersion: 1}
+ return spec
+}
+
+func TestBroker_HotWaitEndsInSuspensionAndKeepsRunState(t *testing.T) {
+ b := NewBroker(nil, nil, WithPollInterval(20*time.Millisecond), WithSuspendExpiry(time.Hour))
+ b.RegisterKind(testKind, validateTestAnswer)
+
+ before := time.Now()
+ out, err := b.Await(context.Background(), suspendableSpec(100*time.Millisecond, nil))
+ require.NoError(t, err)
+ require.True(t, out.Suspended)
+ require.False(t, out.TimedOut)
+ require.NotNil(t, out.ExpiresAt)
+ require.WithinDuration(t, before.Add(time.Hour), *out.ExpiresAt, 5*time.Second)
+
+ row, err := b.Store().Get(context.Background(), out.Prompt.ID)
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptSuspended, row.Status)
+ require.True(t, row.Suspendable)
+
+ saved, err := b.Suspensions().Get(context.Background(), "m1")
+ require.NoError(t, err)
+ require.NotNil(t, saved)
+ require.Equal(t, out.Prompt.ID, saved.PromptID)
+ require.JSONEq(t, `{"version":1}`, string(saved.Snapshot))
+}
+
+func TestBroker_NegativeExpiryNeverExpires(t *testing.T) {
+ b := NewBroker(nil, nil, WithPollInterval(20*time.Millisecond), WithSuspendExpiry(0))
+ out, err := b.Await(context.Background(), suspendableSpec(50*time.Millisecond, nil))
+ require.NoError(t, err)
+ require.True(t, out.Suspended)
+ require.Nil(t, out.ExpiresAt)
+}
+
+func TestBroker_AnsweredInHotWaitDropsRunState(t *testing.T) {
+ b := newTestBroker(NewMemoryStore())
+ out, err := b.Await(context.Background(), suspendableSpec(5*time.Second,
+ func(_ context.Context, p *types.AgentPrompt) error {
+ go func() { require.NoError(t, resolveErr(context.Background(), b, answer(p.ID, "blue"))) }()
+ return nil
+ }))
+ require.NoError(t, err)
+ require.True(t, out.Answered)
+ require.False(t, out.Suspended)
+
+ saved, err := b.Suspensions().Get(context.Background(), "m1")
+ require.NoError(t, err)
+ require.Nil(t, saved)
+}
+
+func TestBroker_CanceledInHotWaitDropsRunState(t *testing.T) {
+ b := newTestBroker(NewMemoryStore())
+ ctx, cancel := context.WithCancel(context.Background())
+ out, err := b.Await(ctx, suspendableSpec(time.Minute,
+ func(context.Context, *types.AgentPrompt) error { cancel(); return nil }))
+ require.NoError(t, err)
+ require.True(t, out.Canceled)
+
+ saved, err := b.Suspensions().Get(context.Background(), "m1")
+ require.NoError(t, err)
+ require.Nil(t, saved)
+}
+
+func TestBroker_SuspendableNeedsAssistantMessage(t *testing.T) {
+ b := newTestBroker(NewMemoryStore())
+ spec := suspendableSpec(time.Second, nil)
+ spec.Prompt.AssistantMessageID = ""
+ _, err := b.Await(context.Background(), spec)
+ require.Error(t, err)
+}
+
+// An owner whose lease lapsed sees another replica's takeover as a
+// suspension, not as a prompt still waiting on it.
+func TestBroker_OwnerSeesTakeoverAsSuspension(t *testing.T) {
+ store := NewMemoryStore()
+ owner := NewBroker(store, nil, WithPollInterval(20*time.Millisecond), withLease(time.Millisecond, time.Hour))
+ reaper := NewBroker(store, nil, WithSuspendExpiry(time.Hour))
+ reaper.suspensions = owner.suspensions
+
+ out, err := owner.Await(context.Background(), suspendableSpec(time.Minute,
+ func(context.Context, *types.AgentPrompt) error {
+ go func() {
+ time.Sleep(10 * time.Millisecond)
+ n, err := reaper.Reap(context.Background(), time.Now(), RunHooks{})
+ require.NoError(t, err)
+ require.Equal(t, 1, n)
+ }()
+ return nil
+ }))
+ require.NoError(t, err)
+ require.True(t, out.Suspended)
+
+ saved, err := owner.Suspensions().Get(context.Background(), "m1")
+ require.NoError(t, err)
+ require.NotNil(t, saved, "the run state must survive for the resume")
+}
+
+func TestBroker_ReapSuspendsOrphanedSuspendablePrompt(t *testing.T) {
+ ctx := context.Background()
+ store, suspensions := NewMemoryStore(), NewMemorySuspensionStore()
+ b := NewBroker(store, nil, WithSuspensionStore(suspensions), WithSuspendExpiry(time.Hour))
+
+ past := time.Now().Add(-time.Minute)
+ require.NoError(t, store.Create(ctx, &types.AgentPrompt{
+ ID: "p1", TenantID: 1, SessionID: "s1", AssistantMessageID: "m1", Kind: testKind,
+ Status: types.AgentPromptPending, Suspendable: true, LeaseUntil: &past,
+ }))
+ require.NoError(t, suspensions.Save(ctx, &types.AgentRunSuspension{
+ AssistantMessageID: "m1", TenantID: 1, SessionID: "s1", PromptID: "p1",
+ SnapshotVersion: 1, Snapshot: types.JSON(`{"version":1}`),
+ }))
+
+ var hooked *types.AgentRunSuspension
+ n, err := b.Reap(ctx, time.Now(), RunHooks{Suspended: func(
+ _ context.Context, p *types.AgentPrompt, s *types.AgentRunSuspension,
+ ) error {
+ require.Equal(t, "p1", p.ID)
+ hooked = s
+ return nil
+ }})
+ require.NoError(t, err)
+ require.Equal(t, 1, n)
+ require.NotNil(t, hooked)
+
+ row, err := store.Get(ctx, "p1")
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptSuspended, row.Status)
+ require.NotNil(t, row.ExpiresAt)
+
+ n, err = b.Reap(ctx, time.Now(), RunHooks{})
+ require.NoError(t, err)
+ require.Zero(t, n, "a suspended prompt is not reaped again")
+}
+
+func TestBroker_ReapExpiresOrphanWithoutRunState(t *testing.T) {
+ ctx := context.Background()
+ store, suspensions := NewMemoryStore(), NewMemorySuspensionStore()
+ b := NewBroker(store, nil, WithSuspensionStore(suspensions))
+
+ past, future := time.Now().Add(-time.Minute), time.Now().Add(time.Minute)
+ require.NoError(t, store.Create(ctx, &types.AgentPrompt{
+ ID: "plain", TenantID: 1, SessionID: "s1", AssistantMessageID: "m1", Kind: testKind,
+ Status: types.AgentPromptPending, LeaseUntil: &past,
+ }))
+ // Suspendable, but its saved state belongs to a newer prompt.
+ require.NoError(t, store.Create(ctx, &types.AgentPrompt{
+ ID: "stale", TenantID: 1, SessionID: "s1", AssistantMessageID: "m2", Kind: testKind,
+ Status: types.AgentPromptPending, Suspendable: true, LeaseUntil: &past,
+ }))
+ require.NoError(t, suspensions.Save(ctx, &types.AgentRunSuspension{
+ AssistantMessageID: "m2", PromptID: "newer", Snapshot: types.JSON(`{}`),
+ }))
+ require.NoError(t, store.Create(ctx, &types.AgentPrompt{
+ ID: "alive", TenantID: 1, SessionID: "s1", AssistantMessageID: "m3", Kind: testKind,
+ Status: types.AgentPromptPending, LeaseUntil: &future,
+ }))
+
+ called := false
+ n, err := b.Reap(ctx, time.Now(), RunHooks{Suspended: func(
+ context.Context, *types.AgentPrompt, *types.AgentRunSuspension,
+ ) error {
+ called = true
+ return nil
+ }})
+ require.NoError(t, err)
+ require.Equal(t, 2, n)
+ require.False(t, called)
+
+ for id, want := range map[string]string{
+ "plain": types.AgentPromptExpired,
+ "stale": types.AgentPromptExpired,
+ "alive": types.AgentPromptPending,
+ } {
+ row, err := store.Get(ctx, id)
+ require.NoError(t, err)
+ require.Equal(t, want, row.Status, id)
+ }
+}
+
+// An answer to a pending prompt whose owner stopped renewing suspends it as
+// the reaper would and resumes the run, instead of waking nobody.
+func TestBroker_ResolveTakesOverPromptOfVanishedOwner(t *testing.T) {
+ ctx := context.Background()
+ store, suspensions := NewMemoryStore(), NewMemorySuspensionStore()
+ b := NewBroker(store, nil, WithSuspensionStore(suspensions), WithSuspendExpiry(time.Hour))
+ b.RegisterKind(testKind, validateTestAnswer)
+ var hooked bool
+ b.SetRunHooks(RunHooks{Suspended: func(context.Context, *types.AgentPrompt, *types.AgentRunSuspension) error {
+ hooked = true
+ return nil
+ }})
+
+ past := time.Now().Add(-time.Minute)
+ require.NoError(t, store.Create(ctx, &types.AgentPrompt{
+ ID: "p1", TenantID: 1, UserID: "alice", SessionID: "s1", AssistantMessageID: "m1", Kind: testKind,
+ Status: types.AgentPromptPending, Suspendable: true, LeaseUntil: &past, OwnerInstance: "dead",
+ }))
+ require.NoError(t, suspensions.Save(ctx, &types.AgentRunSuspension{
+ AssistantMessageID: "m1", TenantID: 1, SessionID: "s1", PromptID: "p1",
+ SnapshotVersion: 1, Snapshot: types.JSON(`{"version":1}`),
+ }))
+
+ res, err := b.Resolve(ctx, answer("p1", "blue"))
+ require.NoError(t, err)
+ require.True(t, res.Resume)
+ require.True(t, res.OwnerGone)
+ require.True(t, hooked, "the message must be shown as awaiting input before it resumes")
+
+ row, err := store.Get(ctx, "p1")
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptAnswered, row.Status)
+ require.Equal(t, res.Prompt.OwnerInstance, row.OwnerInstance)
+}
+
+// A run that suspended itself still has an owner tearing it down.
+func TestBroker_ResolveOfSelfSuspendedPromptKeepsOwner(t *testing.T) {
+ b := NewBroker(nil, nil, WithPollInterval(20*time.Millisecond), WithSuspendExpiry(time.Hour))
+ b.RegisterKind(testKind, validateTestAnswer)
+ out, err := b.Await(context.Background(), suspendableSpec(50*time.Millisecond, nil))
+ require.NoError(t, err)
+ require.True(t, out.Suspended)
+
+ res, err := b.Resolve(context.Background(), answer(out.Prompt.ID, "blue"))
+ require.NoError(t, err)
+ require.True(t, res.Resume)
+ require.False(t, res.OwnerGone)
+}
+
+type failingSuspensionStore struct{ SuspensionStore }
+
+func (failingSuspensionStore) Save(context.Context, *types.AgentRunSuspension) error {
+ return errors.New("jsonb rejected the snapshot")
+}
+
+func TestBroker_UnsavableRunStateFallsBackToPlainWait(t *testing.T) {
+ b := NewBroker(nil, nil, WithPollInterval(20*time.Millisecond),
+ WithSuspensionStore(failingSuspensionStore{NewMemorySuspensionStore()}))
+ spec := suspendableSpec(10*time.Millisecond, func(_ context.Context, p *types.AgentPrompt) error {
+ require.False(t, p.Suspendable)
+ return nil
+ })
+ spec.FallbackTimeout = 80 * time.Millisecond
+
+ start := time.Now()
+ out, err := b.Await(context.Background(), spec)
+ require.NoError(t, err)
+ require.False(t, out.Suspended)
+ require.True(t, out.TimedOut)
+ require.GreaterOrEqual(t, time.Since(start), 80*time.Millisecond)
+
+ spec = suspendableSpec(10*time.Millisecond, nil)
+ _, err = b.Await(context.Background(), spec)
+ require.Error(t, err, "without a fallback the failure is reported")
+}
diff --git a/internal/agent/resume.go b/internal/agent/resume.go
new file mode 100644
index 000000000..cf5a03f57
--- /dev/null
+++ b/internal/agent/resume.go
@@ -0,0 +1,170 @@
+package agent
+
+import (
+ "context"
+ "fmt"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// Resume continues a run that was suspended on a prompt, now answered. It
+// rebuilds the transcript from the snapshot, finishes the interrupted round
+// with the answer delivered to the blocked call, then carries on with the
+// ReAct loop. The run may suspend again; completion is emitted either way.
+func (e *AgentEngine) Resume(
+ ctx context.Context,
+ sessionID, messageID string,
+ llmContext []chat.Message,
+ snapshot []byte,
+ answered *types.AgentPrompt,
+) (*types.AgentState, error) {
+ if answered == nil {
+ return nil, fmt.Errorf("resume needs an answered prompt")
+ }
+ snap, err := DecodeRunSnapshot(snapshot)
+ if err != nil {
+ return nil, err
+ }
+ p := snap.PendingRound
+ if p.BlockedIndex < 0 || p.BlockedIndex >= len(p.Calls) || len(p.Step.ToolCalls) != p.BlockedIndex {
+ return nil, fmt.Errorf("snapshot round is inconsistent: blocked %d of %d calls, %d done",
+ p.BlockedIndex, len(p.Calls), len(p.Step.ToolCalls))
+ }
+ if p.Calls[p.BlockedIndex].ID != answered.ToolCallID {
+ return nil, fmt.Errorf("prompt %s answers call %s, run is blocked on %s",
+ answered.ID, answered.ToolCallID, p.Calls[p.BlockedIndex].ID)
+ }
+ logger.Infof(ctx, "[Agent] Resuming: session=%s, message=%s, prompt=%s, round=%d",
+ sessionID, messageID, answered.ID, snap.CurrentRound+1)
+ defer e.toolRegistry.Cleanup(ctx)
+
+ state := &types.AgentState{
+ RoundSteps: append([]types.AgentStep{}, snap.CompletedSteps...),
+ KnowledgeRefs: append([]*types.SearchResult{}, snap.KnowledgeRefs...),
+ CurrentRound: snap.CurrentRound,
+ TurnUsage: snap.TurnUsage,
+ }
+ systemPrompt := e.buildSystemPrompt(ctx)
+ e.beginTurn(snap.Query, snap.ImageURLs, state)
+ for id, content := range snap.UserMessages {
+ e.recordSteerMessage(id, content)
+ }
+ messages := e.buildMessagesWithLLMContext(systemPrompt, snap.Query, sessionID, llmContext, snap.ImageURLs)
+ appendUsers := func(step types.AgentStep) error {
+ for _, id := range step.UserMessagesBefore {
+ content, ok := snap.UserMessages[id]
+ if !ok {
+ return fmt.Errorf("missing steered message %s in run snapshot", id)
+ }
+ messages = append(messages, chat.Message{Role: "user", Content: types.SteerMessageContent(content)})
+ }
+ return nil
+ }
+ for _, step := range state.RoundSteps {
+ if err := appendUsers(step); err != nil {
+ return nil, err
+ }
+ messages = e.appendToolResults(messages, step)
+ messages = e.appendToolImages(ctx, messages, step)
+ }
+ if err := appendUsers(p.Step); err != nil {
+ return nil, err
+ }
+ if e.toolRegistry != nil {
+ e.toolRegistry.RememberMCPHistory(messages)
+ // These calls were issued before suspension, including the first call
+ // to a tool whose definition was only exposed by a describe round.
+ e.toolRegistry.RememberMCPHistory(pendingCallHistory(p))
+ e.toolRegistry.RefreshMCPTools(ctx)
+ }
+ tools := e.buildToolsForLLM()
+
+ startTime := time.Now()
+ step, suspended := e.finishPendingRound(ctx, p, answered, state.CurrentRound, sessionID, messageID)
+ if suspended != nil {
+ logger.Infof(ctx, "[Agent][Round-%d] Suspended again waiting on prompt %s",
+ state.CurrentRound+1, suspended.PromptID)
+ state.Suspended = suspended
+ state.SuspendedStep = &step
+ e.emitCompletionEvent(context.WithoutCancel(ctx), state, sessionID, messageID, startTime)
+ return state, nil
+ }
+ state.RoundSteps = append(state.RoundSteps, step)
+ messages = e.appendToolResults(messages, step)
+ messages = e.appendToolImages(ctx, messages, step)
+ state.CurrentRound++
+
+ if _, err := e.executeLoop(ctx, state, snap.Query, messages, tools, sessionID, messageID); err != nil {
+ logger.Errorf(ctx, "[Agent] Resumed execution failed: %v", err)
+ if emitErr := e.eventBus.Emit(ctx, event.Event{
+ ID: generateEventID("error"),
+ Type: event.EventError,
+ SessionID: sessionID,
+ Data: event.ErrorData{
+ Error: err.Error(),
+ Stage: "agent_execution",
+ SessionID: sessionID,
+ },
+ }); emitErr != nil {
+ logger.Warnf(ctx, "[Agent] Failed to emit resumed execution error: %v", emitErr)
+ }
+ return nil, err
+ }
+ return state, nil
+}
+
+func pendingCallHistory(p PendingRound) []chat.Message {
+ calls := make([]chat.ToolCall, len(p.Calls))
+ for i, c := range p.Calls {
+ calls[i] = chat.ToolCall{ID: c.ID, Type: "function", Function: chat.FunctionCall{
+ Name: c.Name, Arguments: c.Arguments,
+ }}
+ }
+ return []chat.Message{{Role: "assistant", ToolCalls: calls}}
+}
+
+// finishPendingRound runs the interrupted round from its blocked call on,
+// sequentially. The blocked call receives the answer; a later call may raise
+// a prompt of its own and suspend the round again.
+func (e *AgentEngine) finishPendingRound(
+ ctx context.Context, p PendingRound, answered *types.AgentPrompt,
+ iteration int, sessionID, messageID string,
+) (types.AgentStep, *types.PromptSuspension) {
+ step := p.Step
+ step.ToolCalls = append([]types.ToolCall(nil), p.Step.ToolCalls...)
+ calls := make([]types.LLMToolCall, len(p.Calls))
+ for i, c := range p.Calls {
+ calls[i] = types.LLMToolCall{
+ ID: c.ID,
+ Type: "function",
+ Function: types.FunctionCall{Name: c.Name, Arguments: c.Arguments},
+ UnresolvedHandles: c.UnresolvedHandles,
+ ProviderMetadata: c.ProviderMetadata,
+ }
+ }
+
+ round := iteration + 1
+ e.beginRound(step, calls)
+ defer e.endRound()
+ for i, done := range step.ToolCalls {
+ e.recordCall(i, done)
+ }
+ for i := p.BlockedIndex; i < len(calls); i++ {
+ var answer *types.AgentPrompt
+ if i == p.BlockedIndex {
+ answer = answered
+ }
+ toolCall := e.runToolCallAnswered(ctx, calls[i], i, iteration, round, sessionID, messageID, answer)
+ if s := suspensionOf(toolCall); s != nil {
+ return step, s
+ }
+ e.recordCall(i, toolCall)
+ step.ToolCalls = append(step.ToolCalls, toolCall)
+ e.emitToolOutcome(ctx, toolCall, iteration, sessionID)
+ }
+ return step, nil
+}
diff --git a/internal/agent/resume_mcp_test.go b/internal/agent/resume_mcp_test.go
new file mode 100644
index 000000000..aba14aa95
--- /dev/null
+++ b/internal/agent/resume_mcp_test.go
@@ -0,0 +1,83 @@
+package agent
+
+import (
+ "context"
+ "encoding/json"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/agent/approval"
+ "github.com/Tencent/WeKnora/internal/agent/tools"
+ "github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+)
+
+type resumeMCPGate struct{ resumed bool }
+
+func (*resumeMCPGate) IsEnabled(context.Context, uint64, string, string) (bool, error) {
+ return true, nil
+}
+func (*resumeMCPGate) NeedsApproval(context.Context, uint64, string, string) bool { return true }
+func (*resumeMCPGate) RequestAndWait(context.Context, approval.PendingRequest) (approval.Decision, error) {
+ return approval.Decision{Reason: "unexpected new approval"}, nil
+}
+
+func (g *resumeMCPGate) ResumeDecision(context.Context, *types.AgentPrompt, *event.EventBus) approval.Decision {
+ g.resumed = true
+ return approval.Decision{Reason: "test rejects before external execution"}
+}
+func (*resumeMCPGate) MarkExecuted(context.Context, string) {}
+
+func TestResumeRestoresFirstDeferredMCPCall(t *testing.T) {
+ for _, proxy := range []bool{false, true} {
+ t.Run(map[bool]string{false: "direct", true: "proxy"}[proxy], func(t *testing.T) {
+ ctx := context.WithValue(t.Context(), types.TenantIDContextKey, uint64(1))
+ ctx = types.WithPrincipal(ctx, types.Principal{Type: "user", ID: "u"})
+ gate := &resumeMCPGate{}
+ newRegistry := func() *tools.ToolRegistry {
+ r := tools.NewToolRegistry()
+ services := []*types.MCPService{{ID: "svc", Name: "service", TenantID: 1, Enabled: true}}
+ _, err := tools.RegisterMCPTools(ctx, r, services, nil, gate, 0, nil, &tools.MCPMetadataIO{
+ Get: func(context.Context, uint64, string) (*types.MCPMetadata, error) {
+ return &types.MCPMetadata{Tools: []*types.MCPTool{
+ {Name: "write", InputSchema: json.RawMessage(`{"type":"object"}`)},
+ }}, nil
+ },
+ })
+ require.NoError(t, err)
+ r.PrepareMCPTools(ctx)
+ return r
+ }
+ original := newRegistry()
+ described, err := original.ExecuteTool(ctx, tools.ToolDiscoverMCPTools,
+ json.RawMessage(`{"mode":"describe","server_id":"svc","tool_name":"write"}`))
+ require.NoError(t, err)
+ require.True(t, described.Success, described.Error)
+ var definition map[string]any
+ require.NoError(t, json.Unmarshal([]byte(described.Output), &definition))
+ name, args := definition["function_name"].(string), `{}`
+ if proxy {
+ name = tools.ToolCallMCPTool
+ data, err := json.Marshal(map[string]any{
+ "tool_ref": definition["tool_ref"], "arguments": map[string]any{},
+ })
+ require.NoError(t, err)
+ args = string(data)
+ }
+ snap := RunSnapshot{
+ Version: RunSnapshotVersion, Query: "do the work",
+ PendingRound: PendingRound{Calls: []PendingCall{{ID: "call", Name: name, Arguments: args}}},
+ }
+ data, err := json.Marshal(snap)
+ require.NoError(t, err)
+ model := &mockChat{responses: []mockResponse{{chunks: []types.StreamResponse{
+ {ResponseType: types.ResponseTypeAnswer, Content: "done", Done: true, FinishReason: "stop"},
+ }}}}
+ e := newTestEngine(t, model)
+ e.toolRegistry = newRegistry()
+ _, err = e.Resume(ctx, "s", "m", nil, data, answeredPrompt("call"))
+ require.NoError(t, err)
+ require.True(t, gate.resumed, "must find the deferred tool and deliver the existing decision")
+ })
+ }
+}
diff --git a/internal/agent/resume_test.go b/internal/agent/resume_test.go
new file mode 100644
index 000000000..8f4b6aa3c
--- /dev/null
+++ b/internal/agent/resume_test.go
@@ -0,0 +1,195 @@
+package agent
+
+import (
+ "context"
+ "encoding/json"
+ "strings"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+)
+
+// suspendedSnapshot runs a turn until it suspends on call-b and returns the
+// saved run state.
+func suspendedSnapshot(t *testing.T) []byte {
+ t.Helper()
+ f := newSuspendFixture(t, "first_tool", false)
+ f.engine.EnableSuspension(json.RawMessage(`{"agent_id":"a1"}`))
+ state := f.run(t)
+ require.NotNil(t, state.Suspended)
+ require.NoError(t, f.blocked.err)
+ return f.blocked.snapshot
+}
+
+func answeredPrompt(callID string) *types.AgentPrompt {
+ return &types.AgentPrompt{
+ ID: "p1", Kind: types.AgentPromptKindToolApproval, ToolCallID: callID,
+ Status: types.AgentPromptAnswered, Response: types.JSON(`{"approved":true}`),
+ }
+}
+
+func TestResumeFinishesInterruptedRoundAndContinues(t *testing.T) {
+ snapshot := suspendedSnapshot(t)
+
+ // Another replica: fresh engine, the model only answers.
+ f := newSuspendFixture(t, "first_tool", false)
+ model := f.engine.chatModel.(*mockChat)
+ model.responses = []mockResponse{{chunks: []types.StreamResponse{
+ {ResponseType: types.ResponseTypeAnswer, Content: "all done", Done: true, FinishReason: "stop"},
+ }}}
+ f.engine.EnableSuspension(json.RawMessage(`{"agent_id":"a1"}`))
+
+ state, err := f.engine.Resume(context.Background(), "sess-1", "msg-1", nil, snapshot, answeredPrompt("call-b"))
+ require.NoError(t, err)
+ require.True(t, state.IsComplete)
+ require.Nil(t, state.Suspended)
+ require.Equal(t, "all done", state.FinalAnswer)
+
+ require.Zero(t, f.first.calls, "calls that finished before the suspension are not rerun")
+ require.NotNil(t, f.blocked.answered)
+ require.Equal(t, "p1", f.blocked.answered.ID)
+ require.Equal(t, 1, f.after.calls)
+
+ require.Len(t, state.RoundSteps, 2)
+ round := state.RoundSteps[0]
+ require.Equal(t, "checking first", round.Thought)
+ require.Len(t, round.ToolCalls, 3)
+ for i, id := range []string{"call-a", "call-b", "call-c"} {
+ require.Equal(t, id, round.ToolCalls[i].ID)
+ require.True(t, round.ToolCalls[i].Result.Success, id)
+ }
+
+ // The model sees the original turn and every tool result of the round.
+ require.Len(t, model.calls, 1)
+ sent := model.calls[0]
+ var toolResults []string
+ sawQuery := false
+ for _, m := range sent {
+ if m.Role == "tool" {
+ toolResults = append(toolResults, m.ToolCallID)
+ }
+ if m.Role == "user" && m.Content != "" {
+ sawQuery = true
+ }
+ }
+ require.True(t, sawQuery)
+ require.Equal(t, []string{"call-a", "call-b", "call-c"}, toolResults)
+
+ require.NotNil(t, f.completed)
+ require.Nil(t, f.completed.Suspended)
+}
+
+func TestResumeRejectsPromptForAnotherCall(t *testing.T) {
+ snapshot := suspendedSnapshot(t)
+ f := newSuspendFixture(t, "first_tool", false)
+ _, err := f.engine.Resume(context.Background(), "sess-1", "msg-1", nil, snapshot, answeredPrompt("call-c"))
+ require.Error(t, err)
+ require.Nil(t, f.blocked.answered)
+ require.Zero(t, f.after.calls)
+}
+
+func TestResumeSuspendsAgainOnALaterPrompt(t *testing.T) {
+ snapshot := suspendedSnapshot(t)
+ snap, err := DecodeRunSnapshot(snapshot)
+ require.NoError(t, err)
+ // The call after the blocked one raises a prompt of its own.
+ snap.PendingRound.Calls[2].Name = suspendingToolName
+ snap.PendingRound.Calls[2].ID = "call-d"
+ snapshot, err = json.Marshal(snap)
+ require.NoError(t, err)
+
+ f := newSuspendFixture(t, "first_tool", false)
+ f.engine.EnableSuspension(json.RawMessage(`{"agent_id":"a1"}`))
+ model := f.engine.chatModel.(*mockChat)
+ model.responses = nil
+
+ // The blocked call consumes the answer; the next one suspends.
+ state, err := f.engine.Resume(context.Background(), "sess-1", "msg-1", nil, snapshot,
+ answeredPrompt("call-b"))
+ require.NoError(t, err)
+ require.NotNil(t, f.blocked.answered)
+ require.NotNil(t, state.Suspended)
+ require.Empty(t, model.calls, "a re-suspended run makes no model call")
+
+ again, err := DecodeRunSnapshot(f.blocked.snapshot)
+ require.NoError(t, err)
+ require.Equal(t, 2, again.PendingRound.BlockedIndex)
+ require.Len(t, again.PendingRound.Step.ToolCalls, 2)
+ require.Equal(t, "call-b", again.PendingRound.Step.ToolCalls[1].ID)
+
+ require.NotNil(t, f.completed)
+ require.Equal(t, state.Suspended, f.completed.Suspended)
+}
+
+func TestClosedStepsFailUnfinishedCalls(t *testing.T) {
+ snap, err := DecodeRunSnapshot(suspendedSnapshot(t))
+ require.NoError(t, err)
+ steps := snap.ClosedSteps("expired")
+ require.Len(t, steps, 1)
+ calls := steps[0].ToolCalls
+ require.Len(t, calls, 3)
+ require.True(t, calls[0].Result.Success)
+ for _, c := range calls[1:] {
+ require.False(t, c.Result.Success)
+ require.Equal(t, "expired", c.Result.Error)
+ }
+ require.Equal(t, "/etc", calls[1].Args["path"])
+}
+
+func TestResumeReplaysSteeringAtItsOriginalBoundaries(t *testing.T) {
+ snap, err := DecodeRunSnapshot(suspendedSnapshot(t))
+ require.NoError(t, err)
+ snap.CompletedSteps = []types.AgentStep{{Thought: "previous round", UserMessagesBefore: []string{"u1"}}}
+ snap.PendingRound.Step.UserMessagesBefore = []string{"u2"}
+ snap.UserMessages = map[string]string{"u1": "use staging", "u2": "only two replicas"}
+ data, err := json.Marshal(snap)
+ require.NoError(t, err)
+ f := newSuspendFixture(t, "first_tool", false)
+ model := f.engine.chatModel.(*mockChat)
+ model.responses = []mockResponse{{chunks: []types.StreamResponse{{
+ ResponseType: types.ResponseTypeAnswer, Content: "done", Done: true, FinishReason: "stop",
+ }}}}
+ _, err = f.engine.Resume(t.Context(), "sess-1", "msg-1", nil, data, answeredPrompt("call-b"))
+ require.NoError(t, err)
+ var contents []string
+ for _, m := range model.calls[0] {
+ contents = append(contents, m.Content)
+ }
+ // The provider normalization can merge adjacent user messages, including
+ // the original query and the first steering message.
+ transcript := strings.Join(contents, "\n")
+ previous := -1
+ for _, content := range []string{
+ types.SteerMessageContent("use staging"), "previous round",
+ types.SteerMessageContent("only two replicas"), "checking first",
+ } {
+ position := strings.Index(transcript, content)
+ require.Greater(t, position, previous, "missing or misplaced content: %s", content)
+ previous = position
+ }
+}
+
+func TestSteeringTextSurvivesAnotherSuspension(t *testing.T) {
+ f := newSuspendFixture(t, "first_tool", false)
+ f.engine.EnableSuspension(nil)
+ f.engine.SetSteerSink(&fakeSteerSink{queued: []map[string]interface{}{steerEntry("s1", "use staging")}})
+ state := f.run(t)
+ require.NotNil(t, state.Suspended)
+ snap, err := DecodeRunSnapshot(f.blocked.snapshot)
+ require.NoError(t, err)
+ require.Len(t, snap.PendingRound.Step.UserMessagesBefore, 1)
+ id := snap.PendingRound.Step.UserMessagesBefore[0]
+ require.Equal(t, "use staging", snap.UserMessages[id])
+ // A second suspension retains the already-consumed steering text.
+ snap.PendingRound.Calls[2].Name = suspendingToolName
+ data, err := json.Marshal(snap)
+ require.NoError(t, err)
+ f2 := newSuspendFixture(t, "first_tool", false)
+ f2.engine.EnableSuspension(nil)
+ _, err = f2.engine.Resume(t.Context(), "sess-1", "msg-1", nil, data, answeredPrompt("call-b"))
+ require.NoError(t, err)
+ again, err := DecodeRunSnapshot(f2.blocked.snapshot)
+ require.NoError(t, err)
+ require.Equal(t, snap.UserMessages, again.UserMessages)
+}
diff --git a/internal/agent/steer.go b/internal/agent/steer.go
index 2b3c9bcc4..41a9746d6 100644
--- a/internal/agent/steer.go
+++ b/internal/agent/steer.go
@@ -70,6 +70,7 @@ func (e *AgentEngine) drainSteerMessages(
}
*messagesPtr = append(*messagesPtr, chat.Message{Role: "user", Content: types.SteerMessageContent(content)})
state.PendingSteerMessages = append(state.PendingSteerMessages, userMessageID)
+ e.recordSteerMessage(userMessageID, content)
_ = e.eventBus.Emit(ctx, event.Event{
ID: generateEventID("injected"),
Type: event.EventUserMessageInjected,
diff --git a/internal/agent/suspend.go b/internal/agent/suspend.go
new file mode 100644
index 000000000..c31848b26
--- /dev/null
+++ b/internal/agent/suspend.go
@@ -0,0 +1,272 @@
+package agent
+
+import (
+ "bytes"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "maps"
+ "sync"
+
+ agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// RunSnapshotVersion is the format version written into RunSnapshot.
+const RunSnapshotVersion = 1
+
+// RunSnapshot is everything needed to resume a run that ended waiting on a
+// user prompt. It holds durable values only: request-local model handles
+// (cN, dN, res://, msN, mtN) do not survive the run, so the user turn is kept
+// as the raw query and re-rendered on resume, and tool arguments are kept in
+// their decoded form.
+type RunSnapshot struct {
+ Version int `json:"version"`
+ // Request is the caller's types.ResumableAgentRequest.
+ Request json.RawMessage `json:"request,omitempty"`
+ Query string `json:"query"`
+ ImageURLs []string `json:"image_urls,omitempty"`
+ // UserMessages holds the raw text referenced by UserMessagesBefore.
+ UserMessages map[string]string `json:"user_messages,omitempty"`
+
+ CompletedSteps []types.AgentStep `json:"completed_steps"`
+ KnowledgeRefs []*types.SearchResult `json:"knowledge_refs,omitempty"`
+ CurrentRound int `json:"current_round"`
+ TurnUsage types.TokenUsage `json:"turn_usage"`
+
+ PendingRound PendingRound `json:"pending_round"`
+}
+
+// PendingRound is the round interrupted by the prompt.
+type PendingRound struct {
+ // Step carries the round's thought and reasoning; its ToolCalls are the
+ // calls that finished before the blocked one.
+ Step types.AgentStep `json:"step"`
+ Calls []PendingCall `json:"calls"`
+ // BlockedIndex is the call waiting on the prompt. Calls after it have
+ // not run.
+ BlockedIndex int `json:"blocked_index"`
+}
+
+// PendingCall is one tool call of the interrupted round.
+type PendingCall struct {
+ ID string `json:"id"`
+ Name string `json:"name"`
+ // Arguments is the decoded JSON the call executes with.
+ Arguments string `json:"arguments"`
+ UnresolvedHandles []string `json:"unresolved_handles,omitempty"`
+ ProviderMetadata types.ToolCallMetadata `json:"provider_metadata,omitempty"`
+}
+
+// DecodeRunSnapshot parses a saved snapshot, rejecting unknown versions.
+func DecodeRunSnapshot(data []byte) (*RunSnapshot, error) {
+ var snap RunSnapshot
+ if err := json.Unmarshal(data, &snap); err != nil {
+ return nil, fmt.Errorf("decode run snapshot: %w", err)
+ }
+ if snap.Version != RunSnapshotVersion {
+ return nil, fmt.Errorf("unsupported run snapshot version %d", snap.Version)
+ }
+ return &snap, nil
+}
+
+// DisplaySteps returns the steps a suspended message shows: the completed
+// rounds plus whatever the interrupted round produced so far.
+func (s *RunSnapshot) DisplaySteps() []types.AgentStep {
+ steps := append([]types.AgentStep(nil), s.CompletedSteps...)
+ if p := s.PendingRound.Step; p.Thought != "" || len(p.ToolCalls) > 0 ||
+ p.ReasoningContent != "" || len(p.UserMessagesBefore) > 0 {
+ steps = append(steps, p)
+ }
+ return steps
+}
+
+// ClosedSteps returns the steps of a run that will never resume: the
+// interrupted round's unfinished calls are recorded as failed with reason, so
+// the transcript keeps one result per tool call the model issued.
+func (s *RunSnapshot) ClosedSteps(reason string) []types.AgentStep {
+ steps := append([]types.AgentStep(nil), s.CompletedSteps...)
+ p := s.PendingRound
+ step := p.Step
+ step.ToolCalls = append([]types.ToolCall(nil), p.Step.ToolCalls...)
+ for i := len(step.ToolCalls); i < len(p.Calls); i++ {
+ c := p.Calls[i]
+ var args map[string]any
+ if err := json.Unmarshal([]byte(c.Arguments), &args); err != nil {
+ args = map[string]any{"_raw": c.Arguments}
+ }
+ step.ToolCalls = append(step.ToolCalls, types.ToolCall{
+ ID: c.ID,
+ Name: c.Name,
+ Args: args,
+ ProviderMetadata: c.ProviderMetadata,
+ Result: &types.ToolResult{Success: false, Error: reason},
+ })
+ }
+ return append(steps, step)
+}
+
+// turnProgress tracks the turn so it can be captured mid-round. Tool calls
+// finish on errgroup goroutines, hence the lock.
+type turnProgress struct {
+ mu sync.Mutex
+ query string
+ imageURLs []string
+ state *types.AgentState
+ userMessages map[string]string
+ // round is the round executing tools, nil between rounds.
+ round *roundProgress
+}
+
+type roundProgress struct {
+ step types.AgentStep
+ calls []types.LLMToolCall
+ done map[int]types.ToolCall
+}
+
+// EnableSuspension lets prompts raised by this run suspend it instead of
+// blocking. request is the caller's types.ResumableAgentRequest, saved with
+// the run so another replica can rebuild it. Must be called before Execute.
+func (e *AgentEngine) EnableSuspension(request json.RawMessage) {
+ e.suspendRequest = request
+ e.suspendable = true
+}
+
+// SetInteractive marks the run's client as able to render and answer
+// prompts such as ask_user, whether or not the run may also suspend.
+func (e *AgentEngine) SetInteractive(interactive bool) {
+ e.interactive = interactive
+}
+
+func (e *AgentEngine) beginTurn(query string, imageURLs []string, state *types.AgentState) {
+ e.progress.mu.Lock()
+ defer e.progress.mu.Unlock()
+ e.progress.query, e.progress.imageURLs, e.progress.state = query, imageURLs, state
+ e.progress.userMessages = make(map[string]string)
+}
+
+func (e *AgentEngine) recordSteerMessage(id, content string) {
+ e.progress.mu.Lock()
+ defer e.progress.mu.Unlock()
+ if e.progress.userMessages == nil {
+ e.progress.userMessages = make(map[string]string)
+ }
+ e.progress.userMessages[id] = content
+}
+
+func (e *AgentEngine) beginRound(step types.AgentStep, calls []types.LLMToolCall) {
+ e.progress.mu.Lock()
+ defer e.progress.mu.Unlock()
+ e.progress.round = &roundProgress{step: step, calls: calls, done: make(map[int]types.ToolCall)}
+}
+
+func (e *AgentEngine) endRound() {
+ e.progress.mu.Lock()
+ defer e.progress.mu.Unlock()
+ e.progress.round = nil
+}
+
+func (e *AgentEngine) recordCall(i int, call types.ToolCall) {
+ e.progress.mu.Lock()
+ defer e.progress.mu.Unlock()
+ if e.progress.round != nil {
+ e.progress.round.done[i] = call
+ }
+}
+
+// snapshotFunc returns the ToolExecContext.Snapshot hook for call i, or nil
+// when this run cannot be suspended.
+func (e *AgentEngine) snapshotFunc(i int) func() ([]byte, int, error) {
+ if !e.suspendable {
+ return nil
+ }
+ return func() ([]byte, int, error) {
+ snap, err := e.snapshot(i)
+ if err != nil {
+ return nil, 0, err
+ }
+ data, err := json.Marshal(snap)
+ if err != nil {
+ return nil, 0, fmt.Errorf("encode run snapshot: %w", err)
+ }
+ return stripJSONNUL(data), RunSnapshotVersion, nil
+ }
+}
+
+// stripJSONNUL drops \u0000 escapes from encoded JSON; PostgreSQL rejects
+// them in jsonb, and tool output (documents, web pages) can carry them.
+// Escape pairs are copied whole so an escaped backslash followed by the text
+// "u0000" is left alone.
+func stripJSONNUL(data []byte) []byte {
+ const nul = `\u0000`
+ if !bytes.Contains(data, []byte(nul)) {
+ return data
+ }
+ out := make([]byte, 0, len(data))
+ for i := 0; i < len(data); i++ {
+ if data[i] != '\\' || i+1 >= len(data) {
+ out = append(out, data[i])
+ continue
+ }
+ if bytes.HasPrefix(data[i:], []byte(nul)) {
+ i += len(nul) - 1
+ continue
+ }
+ out = append(out, data[i], data[i+1])
+ i++
+ }
+ return out
+}
+
+// snapshot captures the run as it stands while call blocked waits.
+func (e *AgentEngine) snapshot(blocked int) (*RunSnapshot, error) {
+ e.progress.mu.Lock()
+ defer e.progress.mu.Unlock()
+ p := &e.progress
+ if p.state == nil || p.round == nil {
+ return nil, errors.New("no round in progress")
+ }
+ r := p.round
+ if blocked < 0 || blocked >= len(r.calls) {
+ return nil, fmt.Errorf("blocked call %d outside round of %d calls", blocked, len(r.calls))
+ }
+ step := r.step
+ step.ToolCalls = nil
+ calls := make([]PendingCall, len(r.calls))
+ for i, tc := range r.calls {
+ calls[i] = PendingCall{
+ ID: agenttools.NormalizeToolCallID(tc.ID, tc.Function.Name, i),
+ Name: tc.Function.Name,
+ Arguments: tc.Function.Arguments,
+ UnresolvedHandles: tc.UnresolvedHandles,
+ ProviderMetadata: tc.ProviderMetadata,
+ }
+ if i < blocked {
+ done, ok := r.done[i]
+ if !ok {
+ return nil, fmt.Errorf("call %d before the blocked call has not finished", i)
+ }
+ step.ToolCalls = append(step.ToolCalls, done)
+ }
+ }
+ return &RunSnapshot{
+ Version: RunSnapshotVersion,
+ Request: e.suspendRequest,
+ Query: p.query,
+ ImageURLs: p.imageURLs,
+ UserMessages: maps.Clone(p.userMessages),
+ CompletedSteps: append([]types.AgentStep(nil), p.state.RoundSteps...),
+ KnowledgeRefs: append([]*types.SearchResult(nil), p.state.KnowledgeRefs...),
+ CurrentRound: p.state.CurrentRound,
+ TurnUsage: p.state.TurnUsage,
+ PendingRound: PendingRound{Step: step, Calls: calls, BlockedIndex: blocked},
+ }, nil
+}
+
+// suspensionOf reports whether a finished call is in fact waiting on a prompt.
+func suspensionOf(call types.ToolCall) *types.PromptSuspension {
+ if call.Result == nil {
+ return nil
+ }
+ return call.Result.Suspend
+}
diff --git a/internal/agent/suspend_test.go b/internal/agent/suspend_test.go
new file mode 100644
index 000000000..7e2b251c8
--- /dev/null
+++ b/internal/agent/suspend_test.go
@@ -0,0 +1,168 @@
+package agent
+
+import (
+ "context"
+ "encoding/json"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/agent/tools"
+ "github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+)
+
+const suspendingToolName = "mcp_svc_danger"
+
+// suspendingTool stands in for an approval-gated MCP tool whose approval
+// outlived the hot wait: it saves the run state and suspends.
+type suspendingTool struct {
+ tools.BaseTool
+ snapshot []byte
+ err error
+ answered *types.AgentPrompt
+}
+
+func (t *suspendingTool) Execute(ctx context.Context, _ json.RawMessage) (*types.ToolResult, error) {
+ meta, ok := tools.ToolExecFromContext(ctx)
+ if ok && meta.Answered != nil {
+ t.answered = meta.Answered
+ return &types.ToolResult{Success: true, Output: "approved and ran"}, nil
+ }
+ if !ok || meta.Snapshot == nil {
+ return &types.ToolResult{Success: true, Output: "ran without suspension"}, nil
+ }
+ t.snapshot, _, t.err = meta.Snapshot()
+ return &types.ToolResult{
+ Error: "waiting for the user to approve this tool call",
+ Suspend: &types.PromptSuspension{PromptID: "p1", Kind: types.AgentPromptKindToolApproval},
+ }, nil
+}
+
+type suspendFixture struct {
+ engine *AgentEngine
+ first *countingTool
+ blocked *suspendingTool
+ after *countingTool
+ completed *event.AgentCompleteData
+}
+
+func newSuspendFixture(t *testing.T, firstName string, parallel bool) *suspendFixture {
+ t.Helper()
+ model := &mockChat{responses: []mockResponse{{chunks: []types.StreamResponse{{
+ ResponseType: types.ResponseTypeAnswer,
+ Content: "checking first",
+ ToolCalls: []types.LLMToolCall{
+ {ID: "call-a", Type: "function", Function: types.FunctionCall{Name: firstName, Arguments: `{"q":"a"}`}},
+ {
+ ID: "call-b", Type: "function",
+ Function: types.FunctionCall{Name: suspendingToolName, Arguments: `{"path":"/etc"}`},
+ },
+ {ID: "call-c", Type: "function", Function: types.FunctionCall{Name: firstName + "_after", Arguments: `{}`}},
+ },
+ Done: true,
+ FinishReason: "tool_calls",
+ }}}}}
+ f := &suspendFixture{
+ engine: newTestEngine(t, model),
+ first: newCountingTool(firstName),
+ blocked: &suspendingTool{
+ BaseTool: tools.NewBaseTool(suspendingToolName, "", json.RawMessage(`{"type":"object"}`)),
+ },
+ after: newCountingTool(firstName + "_after"),
+ }
+ f.engine.config.ParallelToolCalls = parallel
+ f.engine.toolRegistry = tools.NewToolRegistry()
+ f.engine.toolRegistry.RegisterTool(f.first)
+ f.engine.toolRegistry.RegisterTool(f.blocked)
+ f.engine.toolRegistry.RegisterTool(f.after)
+ f.engine.eventBus.On(event.EventAgentComplete, func(_ context.Context, evt event.Event) error {
+ data := evt.Data.(event.AgentCompleteData)
+ f.completed = &data
+ return nil
+ })
+ return f
+}
+
+func (f *suspendFixture) run(t *testing.T) *types.AgentState {
+ t.Helper()
+ state := &types.AgentState{}
+ f.engine.beginTurn("test query", []string{"https://img/1.png"}, state)
+ _, err := f.engine.executeLoop(context.Background(), state, "test query",
+ emptyMessages(), emptyTools(), "sess-1", "msg-1")
+ require.NoError(t, err)
+ return state
+}
+
+func TestSuspendedToolCallEndsTheRun(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ firstTool string
+ parallel bool
+ }{
+ {name: "sequential", firstTool: "first_tool"},
+ {name: "parallel", firstTool: tools.ToolSearchKnowledge, parallel: true},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ f := newSuspendFixture(t, tc.firstTool, tc.parallel)
+ f.engine.EnableSuspension(json.RawMessage(`{"agent_id":"a1"}`))
+ state := f.run(t)
+
+ require.NotNil(t, state.Suspended)
+ require.Equal(t, "p1", state.Suspended.PromptID)
+ require.False(t, state.IsComplete)
+ require.Empty(t, state.FinalAnswer, "a suspended run synthesizes no answer")
+ require.Empty(t, state.RoundSteps, "the interrupted round finishes on resume")
+ require.Equal(t, 1, f.first.calls)
+ require.Zero(t, f.after.calls, "calls after the blocked one must not run")
+
+ require.NotNil(t, f.completed)
+ require.Equal(t, state.Suspended, f.completed.Suspended)
+ steps := f.completed.AgentSteps.([]types.AgentStep)
+ require.Len(t, steps, 1)
+ require.Len(t, steps[0].ToolCalls, 1)
+ require.Equal(t, tc.firstTool, steps[0].ToolCalls[0].Name)
+
+ require.NoError(t, f.blocked.err)
+ snap, err := DecodeRunSnapshot(f.blocked.snapshot)
+ require.NoError(t, err)
+ require.JSONEq(t, `{"agent_id":"a1"}`, string(snap.Request))
+ require.Equal(t, "test query", snap.Query)
+ require.Equal(t, []string{"https://img/1.png"}, snap.ImageURLs)
+ require.Equal(t, 1, snap.PendingRound.BlockedIndex)
+ require.Len(t, snap.PendingRound.Calls, 3)
+ require.Equal(t, suspendingToolName, snap.PendingRound.Calls[1].Name)
+ require.JSONEq(t, `{"path":"/etc"}`, snap.PendingRound.Calls[1].Arguments)
+ require.Len(t, snap.PendingRound.Step.ToolCalls, 1)
+ require.Equal(t, tc.firstTool, snap.PendingRound.Step.ToolCalls[0].Name)
+ require.Len(t, snap.DisplaySteps(), 1)
+ })
+ }
+}
+
+func TestRunWithoutSuspensionHasNoSnapshotHook(t *testing.T) {
+ f := newSuspendFixture(t, "first_tool", false)
+ // One more response: the run continues after the tools.
+ model := f.engine.chatModel.(*mockChat)
+ model.responses = append(model.responses, mockResponse{chunks: []types.StreamResponse{
+ {ResponseType: types.ResponseTypeAnswer, Content: "done", Done: true, FinishReason: "stop"},
+ }})
+
+ state := f.run(t)
+ require.Nil(t, state.Suspended)
+ require.True(t, state.IsComplete)
+ require.Nil(t, f.blocked.snapshot)
+ require.Equal(t, 1, f.after.calls)
+}
+
+func TestStripJSONNUL(t *testing.T) {
+ data, err := json.Marshal(map[string]string{"a": "x\x00y", "b": `lit\u0000`})
+ require.NoError(t, err)
+ out := stripJSONNUL(data)
+ var got map[string]string
+ require.NoError(t, json.Unmarshal(out, &got))
+ require.Equal(t, "xy", got["a"])
+ require.Equal(t, `lit\u0000`, got["b"], "an escaped backslash is not a NUL escape")
+
+ clean := []byte(`{"a":"b"}`)
+ require.Equal(t, clean, stripJSONNUL(clean))
+}
diff --git a/internal/agent/tools/ask_user.go b/internal/agent/tools/ask_user.go
new file mode 100644
index 000000000..f5112c244
--- /dev/null
+++ b/internal/agent/tools/ask_user.go
@@ -0,0 +1,183 @@
+package tools
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "strings"
+
+ "github.com/Tencent/WeKnora/internal/agent/approval"
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+const askUserDescription = `Ask the user a question and wait for the answer before continuing.
+
+Use it only when you cannot proceed without information or a decision that only the user can provide, such as:
+- choosing between options that lead to different work;
+- details that are missing and cannot be found with other tools;
+- confirming a consequential choice.
+
+Do not use it for anything you can look up, infer reasonably, or that you could simply ask at the end of your answer.
+Ask one focused question at a time.
+
+Shapes of a question:
+- free text: only "question";
+- choices: "options": ["first choice", "second choice"] — a JSON array, never an array encoded inside a string
+ (set "multi_select" for several, "allow_free_text" to also accept a typed answer);
+- a short form: "fields" with types text, number, select or multiselect.
+
+The user may take a long time, decline, or not answer at all; then you are told so and must decide how to continue
+without the answer.`
+
+var askUserSchema = json.RawMessage(fmt.Sprintf(`{
+ "type": "object",
+ "properties": {
+ "question": {"type": "string", "description": "The question shown to the user", "maxLength": %[1]d},
+ "options": {
+ "type": "array", "maxItems": %[2]d,
+ "items": {"type": "string", "maxLength": %[3]d},
+ "description": "Choices the user picks from"
+ },
+ "multi_select": {"type": "boolean", "description": "Allow choosing several options"},
+ "allow_free_text": {"type": "boolean", "description": "Also accept a typed answer besides the options"},
+ "fields": {
+ "type": "array", "maxItems": %[4]d,
+ "description": "A short form; use instead of options",
+ "items": {
+ "type": "object",
+ "properties": {
+ "name": {"type": "string", "maxLength": %[5]d, "description": "Key of the value in the answer"},
+ "label": {"type": "string", "maxLength": %[3]d},
+ "type": {"type": "string", "enum": ["text", "number", "select", "multiselect"]},
+ "required": {"type": "boolean"},
+ "options": {"type": "array", "maxItems": %[2]d, "items": {"type": "string", "maxLength": %[3]d}}
+ },
+ "required": ["name", "type"]
+ }
+ }
+ },
+ "required": ["question"]
+}`, types.AskUserMaxQuestionLen, types.AskUserMaxOptions, types.AskUserMaxOptionLen,
+ types.AskUserMaxFields, types.AskUserMaxNameLen))
+
+// AskUserTool asks the user a question through a card in the conversation.
+type AskUserTool struct {
+ BaseTool
+ asker approval.UserAsker
+}
+
+// NewAskUserTool builds the ask_user tool.
+func NewAskUserTool(asker approval.UserAsker) *AskUserTool {
+ return &AskUserTool{BaseTool: NewBaseTool(ToolAskUser, askUserDescription, askUserSchema), asker: asker}
+}
+
+// Execute implements types.Tool.
+func (t *AskUserTool) Execute(ctx context.Context, args json.RawMessage) (*types.ToolResult, error) {
+ var question types.AskUserPromptRequest
+ if err := json.Unmarshal(args, &question); err != nil {
+ return &types.ToolResult{Success: false, Error: fmt.Sprintf("Failed to parse args: %v", err)}, nil
+ }
+ if err := question.Validate(); err != nil {
+ return &types.ToolResult{Success: false, Error: fmt.Sprintf("Invalid question: %v", err)}, nil
+ }
+ meta, _ := ToolExecFromContext(ctx)
+ resumed := meta != nil && meta.Answered != nil && meta.Answered.Kind == types.AgentPromptKindAskUser
+ if !resumed && (meta == nil || !meta.Interactive || meta.EventBus == nil || t.asker == nil) {
+ return &types.ToolResult{
+ Success: true,
+ Output: "This conversation cannot show an interactive question. Ask the user directly in your " +
+ "reply, then end your turn; their next message will be the answer.",
+ }, nil
+ }
+
+ var answer approval.Answer
+ if resumed {
+ answer = t.asker.ResumeAnswer(ctx, meta.Answered, meta.EventBus)
+ } else {
+ waitCtx := ctx
+ if meta.ApprovalCtx != nil {
+ waitCtx = meta.ApprovalCtx
+ }
+ var snapshot []byte
+ var snapshotVersion int
+ if meta.Snapshot != nil {
+ var err error
+ if snapshot, snapshotVersion, err = meta.Snapshot(); err != nil {
+ logger.Warnf(ctx, "[Tool][AskUser] capture run state: %v", err)
+ snapshot = nil
+ }
+ }
+ tenantID := types.CallerFromContext(ctx).TenantID
+ var err error
+ answer, err = t.asker.AskUser(waitCtx, approval.AskRequest{
+ TenantID: tenantID,
+ UserID: meta.UserID,
+ SessionID: meta.SessionID,
+ AssistantMessageID: meta.AssistantMessageID,
+ RequestID: meta.RequestID,
+ ToolCallID: meta.ToolCallID,
+ EventBus: meta.EventBus,
+ Question: question,
+ Snapshot: snapshot,
+ SnapshotVersion: snapshotVersion,
+ })
+ if err != nil {
+ return &types.ToolResult{Success: false, Error: fmt.Sprintf("Asking the user failed: %v", err)}, nil
+ }
+ }
+ if answer.Suspended != nil {
+ return &types.ToolResult{
+ Success: false,
+ Error: "waiting for the user to answer",
+ Suspend: answer.Suspended,
+ }, nil
+ }
+ data := map[string]interface{}{
+ "display_type": "ask_user",
+ "question": question,
+ "answered": answer.Answered,
+ }
+ if !answer.Answered {
+ reason := answer.Reason
+ if reason == "" {
+ reason = "no answer"
+ }
+ data["reason"] = reason
+ data["timed_out"] = answer.TimedOut
+ data["canceled"] = answer.Canceled
+ return &types.ToolResult{
+ Success: true,
+ Output: fmt.Sprintf("The user did not answer (%s). Continue without this information, "+
+ "or tell the user what you need.", reason),
+ Data: data,
+ }, nil
+ }
+ data["answer"] = answer.Response
+ return &types.ToolResult{Success: true, Output: formatAskUserAnswer(question, answer.Response), Data: data}, nil
+}
+
+func formatAskUserAnswer(q types.AskUserPromptRequest, a types.AskUserPromptResponse) string {
+ var b strings.Builder
+ b.WriteString("The user answered.\n")
+ if len(a.Selected) > 0 {
+ fmt.Fprintf(&b, "Selected: %s\n", strings.Join(a.Selected, ", "))
+ }
+ if len(a.Values) > 0 {
+ b.WriteString("Fields:\n")
+ order := make([]string, 0, len(a.Values))
+ for _, f := range q.Fields {
+ if _, ok := a.Values[f.Name]; ok {
+ order = append(order, f.Name)
+ }
+ }
+ for _, name := range order {
+ v, _ := json.Marshal(a.Values[name])
+ fmt.Fprintf(&b, "- %s: %s\n", name, v)
+ }
+ }
+ if text := strings.TrimSpace(a.Text); text != "" {
+ fmt.Fprintf(&b, "Text: %s\n", text)
+ }
+ return strings.TrimRight(b.String(), "\n")
+}
diff --git a/internal/agent/tools/ask_user_test.go b/internal/agent/tools/ask_user_test.go
new file mode 100644
index 000000000..f0e44830e
--- /dev/null
+++ b/internal/agent/tools/ask_user_test.go
@@ -0,0 +1,172 @@
+package tools
+
+import (
+ "context"
+ "encoding/json"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+
+ "github.com/Tencent/WeKnora/internal/agent/approval"
+ "github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+type fakeAsker struct {
+ answer approval.Answer
+ asked []approval.AskRequest
+ resumed []*types.AgentPrompt
+}
+
+func (f *fakeAsker) AskUser(_ context.Context, req approval.AskRequest) (approval.Answer, error) {
+ f.asked = append(f.asked, req)
+ return f.answer, nil
+}
+
+func (f *fakeAsker) ResumeAnswer(_ context.Context, p *types.AgentPrompt, _ *event.EventBus) approval.Answer {
+ f.resumed = append(f.resumed, p)
+ return f.answer
+}
+
+func askCtx(meta *ToolExecContext) context.Context {
+ return WithToolExecContext(context.Background(), meta)
+}
+
+const formArgs = `{"question":"deploy where?","fields":[
+ {"name":"env","type":"select","options":["dev","prod"],"required":true},
+ {"name":"replicas","type":"number"}]}`
+
+func TestAskUserTool_NotInteractiveAsksInReply(t *testing.T) {
+ asker := &fakeAsker{}
+ res, err := NewAskUserTool(asker).Execute(
+ askCtx(&ToolExecContext{EventBus: event.NewEventBus()}), json.RawMessage(`{"question":"q"}`))
+ require.NoError(t, err)
+ assert.True(t, res.Success)
+ assert.Contains(t, res.Output, "Ask the user directly in your reply")
+ assert.Empty(t, asker.asked)
+}
+
+func TestAskUserTool_RejectsInvalidQuestion(t *testing.T) {
+ res, err := NewAskUserTool(&fakeAsker{}).Execute(
+ askCtx(&ToolExecContext{Interactive: true, EventBus: event.NewEventBus()}),
+ json.RawMessage(`{"question":"q","options":["a"],"fields":[{"name":"n","type":"text"}]}`))
+ require.NoError(t, err)
+ assert.False(t, res.Success)
+ assert.Contains(t, res.Error, "Invalid question")
+}
+
+func TestAskUserTool_ReturnsAnswer(t *testing.T) {
+ asker := &fakeAsker{answer: approval.Answer{PromptID: "p1", Answered: true, Response: types.AskUserPromptResponse{
+ Values: map[string]any{"replicas": float64(3), "env": "prod"},
+ }}}
+ meta := &ToolExecContext{
+ Interactive: true, EventBus: event.NewEventBus(), SessionID: "s1", AssistantMessageID: "m1",
+ ToolCallID: "tc1", UserID: "user:u1",
+ Snapshot: func() ([]byte, int, error) { return []byte("state"), 1, nil },
+ }
+ res, err := NewAskUserTool(asker).Execute(askCtx(meta), json.RawMessage(formArgs))
+ require.NoError(t, err)
+ require.True(t, res.Success)
+ assert.Equal(t, "The user answered.\nFields:\n- env: \"prod\"\n- replicas: 3", res.Output)
+ require.Len(t, asker.asked, 1)
+ assert.Equal(t, []byte("state"), asker.asked[0].Snapshot)
+ assert.Equal(t, "tc1", asker.asked[0].ToolCallID)
+ assert.Equal(t, "deploy where?", asker.asked[0].Question.Question)
+}
+
+func TestAskUserTool_Suspends(t *testing.T) {
+ suspension := &types.PromptSuspension{PromptID: "p1", Kind: types.AgentPromptKindAskUser}
+ asker := &fakeAsker{answer: approval.Answer{PromptID: "p1", Suspended: suspension}}
+ res, err := NewAskUserTool(asker).Execute(
+ askCtx(&ToolExecContext{Interactive: true, EventBus: event.NewEventBus()}), json.RawMessage(`{"question":"q"}`))
+ require.NoError(t, err)
+ assert.Same(t, suspension, res.Suspend)
+}
+
+func TestAskUserTool_ResumedUsesStoredAnswer(t *testing.T) {
+ asker := &fakeAsker{answer: approval.Answer{PromptID: "p1", Answered: true, Response: types.AskUserPromptResponse{
+ Text: "blue",
+ }}}
+ answered := &types.AgentPrompt{ID: "p1", Kind: types.AgentPromptKindAskUser}
+ // A resumed run is served even if the client could not show a new prompt.
+ res, err := NewAskUserTool(asker).Execute(
+ askCtx(&ToolExecContext{Answered: answered, EventBus: event.NewEventBus()}),
+ json.RawMessage(`{"question":"q"}`))
+ require.NoError(t, err)
+ assert.Equal(t, "The user answered.\nText: blue", res.Output)
+ assert.Empty(t, asker.asked)
+ assert.Equal(t, []*types.AgentPrompt{answered}, asker.resumed)
+}
+
+func TestAskUserTool_NoAnswer(t *testing.T) {
+ asker := &fakeAsker{answer: approval.Answer{PromptID: "p1", Reason: "the user declined to answer"}}
+ res, err := NewAskUserTool(asker).Execute(
+ askCtx(&ToolExecContext{Interactive: true, EventBus: event.NewEventBus()}), json.RawMessage(`{"question":"q"}`))
+ require.NoError(t, err)
+ assert.True(t, res.Success)
+ assert.Contains(t, res.Output, "did not answer (the user declined to answer)")
+}
+
+func TestAskUserUsesCallerTenantForSharedAgent(t *testing.T) {
+ asker := &fakeAsker{}
+ ctx := context.WithValue(t.Context(), types.TenantIDContextKey, uint64(1))
+ ctx = types.WithExecutionTenant(ctx, 2)
+ ctx = WithToolExecContext(ctx, &ToolExecContext{Interactive: true, EventBus: event.NewEventBus()})
+ _, err := NewAskUserTool(asker).Execute(ctx, json.RawMessage(`{"question":"which?"}`))
+ require.NoError(t, err)
+ require.Len(t, asker.asked, 1)
+ require.Equal(t, uint64(1), asker.asked[0].TenantID)
+}
+
+func TestAskUserRegistryValidatesSerializedOptions(t *testing.T) {
+ malformed := `["first", "depends on "rules""]`
+ cases := []struct {
+ name string
+ options any
+ valid bool
+ count int
+ }{
+ {"real array", []string{"first", `depends on "rules"`}, true, 2},
+ {"valid serialized array", `["first","second"]`, true, 2},
+ {"single text", "first", true, 1},
+ {"ordinary bracket label", []string{"[staging]"}, true, 1},
+ {"malformed serialized array", malformed, false, 0},
+ {"truncated serialized array", `["first",`, false, 0},
+ {"wrapped malformed array", []string{malformed}, false, 0},
+ {"wrapped valid array", []string{`["first","second"]`}, false, 0},
+ }
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ asker := &fakeAsker{}
+ registry := NewToolRegistry()
+ registry.RegisterTool(NewAskUserTool(asker))
+ ctx := askCtx(&ToolExecContext{Interactive: true, EventBus: event.NewEventBus()})
+ args, err := json.Marshal(map[string]any{"question": "which?", "options": tc.options})
+ require.NoError(t, err)
+ result, err := registry.ExecuteTool(ctx, ToolAskUser, args)
+ require.NoError(t, err)
+ require.Equal(t, tc.valid, result.Success, result.Error)
+ if tc.valid {
+ require.Len(t, asker.asked, 1)
+ require.Len(t, asker.asked[0].Question.Options, tc.count)
+ } else {
+ require.Empty(t, asker.asked, "invalid input must never create a prompt")
+ require.Contains(t, result.Error, "options")
+ }
+ })
+ }
+}
+
+func TestAskUserRejectsSerializedFormChoices(t *testing.T) {
+ asker := &fakeAsker{}
+ result, err := NewAskUserTool(asker).Execute(
+ askCtx(&ToolExecContext{Interactive: true, EventBus: event.NewEventBus()}),
+ json.RawMessage(`{"question":"which?","fields":[
+ {"name":"env","type":"select","options":["[\"dev\",\"prod\"]"]}
+ ]}`))
+ require.NoError(t, err)
+ require.False(t, result.Success)
+ require.Contains(t, result.Error, "one choice per string")
+ require.Empty(t, asker.asked)
+}
diff --git a/internal/agent/tools/capabilities.go b/internal/agent/tools/capabilities.go
index 273924883..0ebe541b3 100644
--- a/internal/agent/tools/capabilities.go
+++ b/internal/agent/tools/capabilities.go
@@ -60,6 +60,7 @@ var ToolCapabilityRequirements = map[string]ToolRequirement{
// ---- base / reasoning (no KB dependency, no file consumption) ----
"thinking": {},
"todo_write": {},
+ "ask_user": {},
// ---- RAG / chunk retrieval (need at least one chunk-indexed KB) ----
"search_knowledge": {AnyOf: []KBCapability{CapVector, CapKeyword}, ConsumesFiles: true},
diff --git a/internal/agent/tools/definitions.go b/internal/agent/tools/definitions.go
index 67be74c5b..be3aaaa68 100644
--- a/internal/agent/tools/definitions.go
+++ b/internal/agent/tools/definitions.go
@@ -11,6 +11,9 @@ const (
ToolCallMCPTool = "call_mcp_tool"
ToolThinking = "thinking"
ToolTodoWrite = "todo_write"
+ // ToolAskUser asks the user a question through a card and waits for the
+ // answer; the run may suspend until it arrives.
+ ToolAskUser = "ask_user"
// Knowledge retrieval surface. search_knowledge covers semantic, keyword
// and hybrid retrieval over chunk-indexed knowledge bases; read_document
// reads a document's metadata and chunks (by page, by chunk handle, or by
@@ -106,6 +109,7 @@ func AvailableToolDefinitions() []AvailableTool {
return []AvailableTool{
{Name: ToolThinking, Label: "思考", Description: "动态和反思性的问题解决思考工具", Group: ToolGroupBase},
{Name: ToolTodoWrite, Label: "制定计划", Description: "创建结构化的研究计划", Group: ToolGroupBase},
+ {Name: ToolAskUser, Label: "向用户提问", Description: "需要用户补充信息或做选择时,弹出卡片等待回答", Group: ToolGroupBase},
{
Name: ToolSearchConversations,
Label: "回顾历史对话",
@@ -194,6 +198,9 @@ func DefaultAllowedTools() []string {
// own history, and it is what lets "上次你给我的那个配置" resolve at all
// without stuffing every past conversation into the context window.
ToolSearchConversations,
+ // Asking the user only reaches someone on clients that render the
+ // card; elsewhere the tool tells the model to ask in its reply.
+ ToolAskUser,
// ToolSearchMemory is deliberately absent here and from
// AvailableToolDefinitions. Like web_search it is not chosen from this
// list at all: registerTools injects it whenever the workspace, the
diff --git a/internal/agent/tools/exec_context.go b/internal/agent/tools/exec_context.go
index dca3684c6..cb9ef2bde 100644
--- a/internal/agent/tools/exec_context.go
+++ b/internal/agent/tools/exec_context.go
@@ -5,6 +5,7 @@ import (
"time"
"github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/types"
)
type execCtxKey struct{}
@@ -26,6 +27,17 @@ type ToolExecContext struct {
// approval) can re-derive a fresh timeout from ApprovalCtx using this
// value instead of hard-coding a duration. Zero means "fallback to 60s".
ExecTimeout time.Duration
+ // Snapshot, when set, captures the run so it can be resumed from this
+ // call. A tool that raises a suspendable prompt passes the result along;
+ // nil means the run cannot be suspended and prompts wait synchronously.
+ Snapshot func() (data []byte, version int, err error)
+ // Answered is set on the call a resumed run was suspended on: the prompt
+ // it raised, now answered. The tool acts on the answer instead of
+ // raising the prompt again.
+ Answered *types.AgentPrompt
+ // Interactive is set when the client can show and answer prompts; IM
+ // and MCP-server runs have no such surface.
+ Interactive bool
}
// WithToolExecContext returns ctx that carries ToolExecContext for MCP approval and similar features.
diff --git a/internal/agent/tools/mcp_catalog_integration_test.go b/internal/agent/tools/mcp_catalog_integration_test.go
index e632b4b56..420e8330a 100644
--- a/internal/agent/tools/mcp_catalog_integration_test.go
+++ b/internal/agent/tools/mcp_catalog_integration_test.go
@@ -37,6 +37,12 @@ func (g *proxyApprovalGate) RequestAndWait(
return approval.Decision{Approved: !g.reject, Reason: "rejected by test user"}, nil
}
+func (*proxyApprovalGate) ResumeDecision(_ context.Context, p *types.AgentPrompt, _ *event.EventBus) approval.Decision {
+ return approval.Decision{PendingID: p.ID, Approved: true}
+}
+
+func (*proxyApprovalGate) MarkExecuted(context.Context, string) {}
+
func TestMCPProxyHTTPApprovalArgumentsAndImages(t *testing.T) {
utils.SetSSRFWhitelistFromRaw("127.0.0.1")
t.Cleanup(utils.ResetSSRFWhitelistForTest)
diff --git a/internal/agent/tools/mcp_catalog_test.go b/internal/agent/tools/mcp_catalog_test.go
index b906302d3..d486da6e5 100644
--- a/internal/agent/tools/mcp_catalog_test.go
+++ b/internal/agent/tools/mcp_catalog_test.go
@@ -11,6 +11,7 @@ import (
"time"
"github.com/Tencent/WeKnora/internal/agent/approval"
+ "github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/require"
)
@@ -28,6 +29,12 @@ func (*catalogPolicy) RequestAndWait(context.Context, approval.PendingRequest) (
return approval.Decision{Approved: true}, nil
}
+func (*catalogPolicy) ResumeDecision(_ context.Context, p *types.AgentPrompt, _ *event.EventBus) approval.Decision {
+ return approval.Decision{PendingID: p.ID, Approved: true}
+}
+
+func (*catalogPolicy) MarkExecuted(context.Context, string) {}
+
func catalogTestContext() context.Context {
ctx := context.WithValue(context.Background(), types.TenantIDContextKey, uint64(7))
return types.WithPrincipal(ctx, types.Principal{Type: types.PrincipalWebUser, ID: "catalog-user"})
diff --git a/internal/agent/tools/mcp_oauth.go b/internal/agent/tools/mcp_oauth.go
index 3ec61954d..aef190fde 100644
--- a/internal/agent/tools/mcp_oauth.go
+++ b/internal/agent/tools/mcp_oauth.go
@@ -165,7 +165,9 @@ func waitForMCPOAuthAuthorization(
}
decision, waitErr := ow.RequestOAuthAndWait(waitCtx, approval.OAuthPendingRequest{
- TenantID: tenantID,
+ // The user answers from their own workspace, which differs from
+ // tenantID (the agent's) when the agent is shared.
+ TenantID: types.CallerFromContext(ctx).TenantID,
UserID: userID,
SessionID: sess.SessionID,
AssistantMessageID: sess.AssistantMessageID,
diff --git a/internal/agent/tools/mcp_oauth_test.go b/internal/agent/tools/mcp_oauth_test.go
index 6d1ba98fb..32c9e88b0 100644
--- a/internal/agent/tools/mcp_oauth_test.go
+++ b/internal/agent/tools/mcp_oauth_test.go
@@ -98,6 +98,12 @@ func (approvedOAuthGate) RequestAndWait(context.Context, approval.PendingRequest
return approval.Decision{Approved: true}, nil
}
+func (approvedOAuthGate) ResumeDecision(_ context.Context, p *types.AgentPrompt, _ *event.EventBus) approval.Decision {
+ return approval.Decision{PendingID: p.ID, Approved: true}
+}
+
+func (approvedOAuthGate) MarkExecuted(context.Context, string) {}
+
func (g approvedOAuthGate) RequestOAuthAndWait(
ctx context.Context, req approval.OAuthPendingRequest,
) (approval.Decision, error) {
@@ -214,3 +220,81 @@ func TestOAuthRetryRecyclesOnlyOutdatedConnections(t *testing.T) {
})
}
}
+
+// tenantRecordingGate records the workspace each prompt is filed under.
+type tenantRecordingGate struct {
+ approvedOAuthGate
+ approvalTenant, oauthTenant *uint64
+}
+
+func (g tenantRecordingGate) RequestAndWait(
+ ctx context.Context, req approval.PendingRequest,
+) (approval.Decision, error) {
+ *g.approvalTenant = req.TenantID
+ return g.approvedOAuthGate.RequestAndWait(ctx, req)
+}
+
+func (g tenantRecordingGate) RequestOAuthAndWait(
+ ctx context.Context, req approval.OAuthPendingRequest,
+) (approval.Decision, error) {
+ *g.oauthTenant = req.TenantID
+ return g.approvedOAuthGate.RequestOAuthAndWait(ctx, req)
+}
+
+// A shared agent runs in its owner's workspace, but the user answers its
+// prompts from their own: the prompts must be filed under the user's, while
+// the service and its tokens are still looked up in the agent's.
+func TestMCPToolFilesPromptsUnderCallerWorkspaceForSharedAgent(t *testing.T) {
+ utils.SetSSRFWhitelistFromRaw("127.0.0.1")
+ t.Cleanup(utils.ResetSSRFWhitelistForTest)
+ mcpServer := sdkserver.NewMCPServer("test", "1")
+ mcpServer.AddTool(mcpgo.NewTool("echo"),
+ func(context.Context, mcpgo.CallToolRequest) (*mcpgo.CallToolResult, error) {
+ return mcpgo.NewToolResultText("pong"), nil
+ })
+ server := httptest.NewServer(sdkserver.NewStreamableHTTPServer(mcpServer, sdkserver.WithStateLess(true)))
+ t.Cleanup(server.Close)
+ service := &types.MCPService{
+ ID: "svc-shared",
+ Name: "km",
+ Enabled: true,
+ TransportType: types.MCPTransportHTTPStreamable,
+ URL: &server.URL,
+ AuthConfig: &types.MCPAuthConfig{AuthType: types.MCPAuthOAuth},
+ }
+ repo := &oauthRetryTestRepo{clients: map[string]*types.MCPOAuthClient{}, tokens: map[string]*types.MCPOAuthToken{}}
+ repo.registerClient(service.ID, "client-1")
+ manager := mcp.NewMCPManager(repo)
+ t.Cleanup(manager.Shutdown)
+
+ alice := types.Principal{Type: types.PrincipalWebUser, ID: "alice"}
+ const callerTenant = uint64(3)
+ var approvalTenant, oauthTenant uint64
+ prompts := 0
+ gate := tenantRecordingGate{
+ approvedOAuthGate: approvedOAuthGate{
+ oauthRetryTestGate: oauthRetryTestGate{authorized: func() { repo.saveToken(alice, service.ID) }},
+ oauthPrompts: &prompts,
+ },
+ approvalTenant: &approvalTenant,
+ oauthTenant: &oauthTenant,
+ }
+ tool := NewMCPTool(service, &types.MCPTool{Name: "echo"}, manager, gate, 0)
+
+ caller := types.WithPrincipal(
+ context.WithValue(context.Background(), types.TenantIDContextKey, callerTenant), alice)
+ base := types.WithExecutionTenant(caller, oauthRetryTestTenant)
+ ctx := WithToolExecContext(base, &ToolExecContext{
+ EventBus: event.NewEventBus(),
+ ToolCallID: "call-1",
+ UserID: alice.StorageID(),
+ ApprovalCtx: base,
+ ExecTimeout: 5 * time.Second,
+ })
+ result, err := tool.Execute(ctx, json.RawMessage(`{}`))
+ require.NoError(t, err)
+ require.True(t, result.Success, result.Error)
+ require.Equal(t, 1, prompts)
+ require.Equal(t, callerTenant, approvalTenant)
+ require.Equal(t, callerTenant, oauthTenant)
+}
diff --git a/internal/agent/tools/mcp_tool.go b/internal/agent/tools/mcp_tool.go
index b381682d8..1e81b4f31 100644
--- a/internal/agent/tools/mcp_tool.go
+++ b/internal/agent/tools/mcp_tool.go
@@ -176,7 +176,11 @@ func (t *MCPTool) Execute(ctx context.Context, args json.RawMessage) (*types.Too
if t.gate != nil {
if meta := execMeta; meta != nil && meta.EventBus != nil {
tenantID, _ := types.TenantIDFromContext(ctx)
- if t.gate.NeedsApproval(ctx, tenantID, t.service.ID, t.mcpTool.Name) {
+ // A resumed call already holds the user's decision. It is honored
+ // even if the tool stopped requiring approval meanwhile, since the
+ // user may have edited the arguments.
+ resumed := meta.Answered != nil && meta.Answered.Kind == types.AgentPromptKindToolApproval
+ if resumed || t.gate.NeedsApproval(ctx, tenantID, t.service.ID, t.mcpTool.Name) {
// Use ApprovalCtx (round-level ctx WITHOUT defaultToolExecTimeout) so
// human approval can legitimately wait longer than the per-tool 60s.
// User-stop / request cancel still propagates because ApprovalCtx is a
@@ -185,27 +189,54 @@ func (t *MCPTool) Execute(ctx context.Context, args json.RawMessage) (*types.Too
if meta.ApprovalCtx != nil {
waitCtx = meta.ApprovalCtx
}
- decision, waitErr := t.gate.RequestAndWait(waitCtx, approval.PendingRequest{
- TenantID: tenantID,
- UserID: meta.UserID,
- SessionID: meta.SessionID,
- AssistantMessageID: meta.AssistantMessageID,
- RequestID: meta.RequestID,
- EventBus: meta.EventBus,
- ServiceID: t.service.ID,
- ServiceName: t.service.Name,
- MCPToolName: t.mcpTool.Name,
- RegisteredToolName: t.Name(),
- Description: t.mcpTool.Description,
- Args: args,
- ToolCallID: meta.ToolCallID,
- })
+ var decision approval.Decision
+ var waitErr error
+ if resumed {
+ decision = t.gate.ResumeDecision(waitCtx, meta.Answered, meta.EventBus)
+ } else {
+ var snapshot []byte
+ var snapshotVersion int
+ if meta.Snapshot != nil {
+ var snapErr error
+ if snapshot, snapshotVersion, snapErr = meta.Snapshot(); snapErr != nil {
+ // Without run state the approval can still block in memory.
+ logger.Warnf(ctx, "[Tool][MCPTool] capture run state for approval: %v", snapErr)
+ snapshot = nil
+ }
+ }
+ decision, waitErr = t.gate.RequestAndWait(waitCtx, approval.PendingRequest{
+ Snapshot: snapshot,
+ SnapshotVersion: snapshotVersion,
+ // The user answers from their own workspace, which differs
+ // from tenantID (the agent's) when the agent is shared.
+ TenantID: types.CallerFromContext(ctx).TenantID,
+ UserID: meta.UserID,
+ SessionID: meta.SessionID,
+ AssistantMessageID: meta.AssistantMessageID,
+ RequestID: meta.RequestID,
+ EventBus: meta.EventBus,
+ ServiceID: t.service.ID,
+ ServiceName: t.service.Name,
+ MCPToolName: t.mcpTool.Name,
+ RegisteredToolName: t.Name(),
+ Description: t.mcpTool.Description,
+ Args: args,
+ ToolCallID: meta.ToolCallID,
+ })
+ }
if waitErr != nil {
return &types.ToolResult{
Success: false,
Error: fmt.Sprintf("Tool approval failed: %v", waitErr),
}, nil
}
+ if decision.Suspended != nil {
+ return &types.ToolResult{
+ Success: false,
+ Error: "waiting for the user to approve this tool call",
+ Suspend: decision.Suspended,
+ }, nil
+ }
if !decision.Approved {
msg := decision.Reason
if msg == "" {
@@ -216,6 +247,7 @@ func (t *MCPTool) Execute(ctx context.Context, args json.RawMessage) (*types.Too
Error: msg,
}, nil
}
+ defer t.gate.MarkExecuted(ctx, decision.PendingID)
if len(decision.ModifiedArgs) > 0 {
args = decision.ModifiedArgs
if err := t.ValidateArguments(args); err != nil {
diff --git a/internal/agent/tools/mcp_tool_enabled_test.go b/internal/agent/tools/mcp_tool_enabled_test.go
index 375d8960c..61fd0a454 100644
--- a/internal/agent/tools/mcp_tool_enabled_test.go
+++ b/internal/agent/tools/mcp_tool_enabled_test.go
@@ -7,6 +7,7 @@ import (
"testing"
"github.com/Tencent/WeKnora/internal/agent/approval"
+ "github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/types"
"github.com/stretchr/testify/require"
)
@@ -28,6 +29,12 @@ func (g staticPolicyGate) RequestAndWait(context.Context, approval.PendingReques
return approval.Decision{Approved: true}, nil
}
+func (staticPolicyGate) ResumeDecision(_ context.Context, p *types.AgentPrompt, _ *event.EventBus) approval.Decision {
+ return approval.Decision{PendingID: p.ID, Approved: true}
+}
+
+func (staticPolicyGate) MarkExecuted(context.Context, string) {}
+
var _ approval.MCPApproval = staticPolicyGate{}
func TestMCPToolExecuteDisabledByPolicy(t *testing.T) {
diff --git a/internal/agent/tools/param_cast.go b/internal/agent/tools/param_cast.go
index d1b8152a6..a77a1d005 100644
--- a/internal/agent/tools/param_cast.go
+++ b/internal/agent/tools/param_cast.go
@@ -85,6 +85,11 @@ func castValue(val interface{}, targetType string) (interface{}, bool) {
if err := json.Unmarshal([]byte(s), &parsed); err == nil {
return parsed, true
}
+ // An attempted array with invalid JSON must reach validation as an
+ // error, not silently become one option/path/query containing the list.
+ if strings.HasPrefix(strings.TrimSpace(s), "[") {
+ return val, false
+ }
// Fall back: single string → string array
return []string{s}, true
}
diff --git a/internal/application/repository/agent_prompt_repository.go b/internal/application/repository/agent_prompt_repository.go
new file mode 100644
index 000000000..f0b35abd6
--- /dev/null
+++ b/internal/application/repository/agent_prompt_repository.go
@@ -0,0 +1,219 @@
+package repository
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+ "gorm.io/gorm"
+ "gorm.io/gorm/clause"
+)
+
+// AgentPromptRepository implements interfaces.AgentPromptRepository.
+type AgentPromptRepository struct {
+ db *gorm.DB
+}
+
+// NewAgentPromptRepository creates a repository backed by GORM.
+func NewAgentPromptRepository(db *gorm.DB) interfaces.AgentPromptRepository {
+ return &AgentPromptRepository{db: db}
+}
+
+// Create inserts a new prompt row.
+func (r *AgentPromptRepository) Create(ctx context.Context, row *types.AgentPrompt) error {
+ if row == nil {
+ return errors.New("agent prompt row is nil")
+ }
+ if err := r.db.WithContext(ctx).Create(row).Error; err != nil {
+ return fmt.Errorf("create agent prompt: %w", err)
+ }
+ return nil
+}
+
+// Get returns the row, or nil when it does not exist.
+func (r *AgentPromptRepository) Get(ctx context.Context, id string) (*types.AgentPrompt, error) {
+ var row types.AgentPrompt
+ err := r.db.WithContext(ctx).Where("id = ?", id).First(&row).Error
+ if errors.Is(err, gorm.ErrRecordNotFound) {
+ return nil, nil
+ }
+ if err != nil {
+ return nil, fmt.Errorf("get agent prompt: %w", err)
+ }
+ return &row, nil
+}
+
+// Transition applies a compare-and-set state change.
+func (r *AgentPromptRepository) Transition(
+ ctx context.Context, id string, t types.AgentPromptTransition,
+) (bool, error) {
+ if len(t.From) == 0 || t.To == "" {
+ return false, errors.New("transition requires from and to states")
+ }
+ // A map keeps empty values that a struct update would skip.
+ updates := map[string]interface{}{
+ "status": t.To,
+ "updated_at": time.Now(),
+ }
+ if len(t.Response) > 0 {
+ updates["response"] = t.Response
+ }
+ if t.CloseReason != nil {
+ updates["close_reason"] = *t.CloseReason
+ }
+ if t.ResolvedBy != nil {
+ updates["resolved_by"] = *t.ResolvedBy
+ }
+ if t.ResolvedAt != nil {
+ updates["resolved_at"] = *t.ResolvedAt
+ }
+ if t.ExpiresAt != nil {
+ updates["expires_at"] = *t.ExpiresAt
+ }
+ if t.Owner != nil {
+ updates["owner_instance"] = *t.Owner
+ }
+ if t.LeaseUntil != nil {
+ updates["lease_until"] = *t.LeaseUntil
+ }
+ q := r.db.WithContext(ctx).Model(&types.AgentPrompt{}).
+ Where("id = ? AND status IN ?", id, t.From)
+ if t.UnexpiredAt != nil {
+ q = q.Where("expires_at IS NULL OR expires_at > ?", *t.UnexpiredAt)
+ }
+ if t.ExpectedOwner != nil {
+ q = q.Where("owner_instance = ?", *t.ExpectedOwner)
+ }
+ if t.LeaseBefore != nil {
+ q = q.Where("lease_until < ?", *t.LeaseBefore)
+ }
+ res := q.Updates(updates)
+ if res.Error != nil {
+ return false, fmt.Errorf("transition agent prompt: %w", res.Error)
+ }
+ return res.RowsAffected == 1, nil
+}
+
+// leasedStatuses are the states whose row is held by an owner replica.
+var leasedStatuses = []string{types.AgentPromptPending, types.AgentPromptAnswered, types.AgentPromptExecuting}
+
+// RenewLease extends the lease of a leased row still held by owner.
+func (r *AgentPromptRepository) RenewLease(
+ ctx context.Context, id, owner string, until time.Time,
+) (bool, error) {
+ res := r.db.WithContext(ctx).Model(&types.AgentPrompt{}).
+ Where("id = ? AND status IN ? AND owner_instance = ?", id, leasedStatuses, owner).
+ Updates(map[string]interface{}{"lease_until": until, "updated_at": time.Now()})
+ if res.Error != nil {
+ return false, fmt.Errorf("renew agent prompt lease: %w", res.Error)
+ }
+ return res.RowsAffected == 1, nil
+}
+
+// ListStaleLeases returns rows in statuses whose owner stopped renewing.
+func (r *AgentPromptRepository) ListStaleLeases(
+ ctx context.Context, statuses []string, before time.Time, limit int,
+) ([]*types.AgentPrompt, error) {
+ var rows []*types.AgentPrompt
+ err := r.db.WithContext(ctx).
+ Where("status IN ? AND lease_until < ?", statuses, before).
+ Order("lease_until").
+ Limit(limit).
+ Find(&rows).Error
+ if err != nil {
+ return nil, fmt.Errorf("list stale agent prompts: %w", err)
+ }
+ return rows, nil
+}
+
+// ListExpired returns suspended rows past their expiry.
+func (r *AgentPromptRepository) ListExpired(
+ ctx context.Context, before time.Time, limit int,
+) ([]*types.AgentPrompt, error) {
+ var rows []*types.AgentPrompt
+ err := r.db.WithContext(ctx).
+ Where("status = ? AND expires_at < ?", types.AgentPromptSuspended, before).
+ Order("expires_at").
+ Limit(limit).
+ Find(&rows).Error
+ if err != nil {
+ return nil, fmt.Errorf("list expired agent prompts: %w", err)
+ }
+ return rows, nil
+}
+
+// ListBySession returns the session's rows in statuses.
+func (r *AgentPromptRepository) ListBySession(
+ ctx context.Context, sessionID string, statuses []string,
+) ([]*types.AgentPrompt, error) {
+ var rows []*types.AgentPrompt
+ err := r.db.WithContext(ctx).
+ Where("session_id = ? AND status IN ?", sessionID, statuses).
+ Order("created_at").
+ Find(&rows).Error
+ if err != nil {
+ return nil, fmt.Errorf("list session agent prompts: %w", err)
+ }
+ return rows, nil
+}
+
+// AgentRunSuspensionRepository implements interfaces.AgentRunSuspensionRepository.
+type AgentRunSuspensionRepository struct {
+ db *gorm.DB
+}
+
+// NewAgentRunSuspensionRepository creates a repository backed by GORM.
+func NewAgentRunSuspensionRepository(db *gorm.DB) interfaces.AgentRunSuspensionRepository {
+ return &AgentRunSuspensionRepository{db: db}
+}
+
+// Save inserts or replaces the run state of a message.
+func (r *AgentRunSuspensionRepository) Save(ctx context.Context, row *types.AgentRunSuspension) error {
+ if row == nil || row.AssistantMessageID == "" {
+ return errors.New("agent run suspension requires an assistant message id")
+ }
+ now := time.Now()
+ if row.CreatedAt.IsZero() {
+ row.CreatedAt = now
+ }
+ row.UpdatedAt = now
+ err := r.db.WithContext(ctx).Clauses(clause.OnConflict{
+ Columns: []clause.Column{{Name: "assistant_message_id"}},
+ DoUpdates: clause.AssignmentColumns([]string{
+ "tenant_id", "session_id", "prompt_id", "snapshot_version", "snapshot", "updated_at",
+ }),
+ }).Create(row).Error
+ if err != nil {
+ return fmt.Errorf("save agent run suspension: %w", err)
+ }
+ return nil
+}
+
+// Get returns the run state of a message, or nil when there is none.
+func (r *AgentRunSuspensionRepository) Get(
+ ctx context.Context, assistantMessageID string,
+) (*types.AgentRunSuspension, error) {
+ var row types.AgentRunSuspension
+ err := r.db.WithContext(ctx).Where("assistant_message_id = ?", assistantMessageID).First(&row).Error
+ if errors.Is(err, gorm.ErrRecordNotFound) {
+ return nil, nil
+ }
+ if err != nil {
+ return nil, fmt.Errorf("get agent run suspension: %w", err)
+ }
+ return &row, nil
+}
+
+// Delete removes the run state while it still belongs to promptID.
+func (r *AgentRunSuspensionRepository) Delete(ctx context.Context, assistantMessageID, promptID string) error {
+ err := r.db.WithContext(ctx).
+ Where("assistant_message_id = ? AND prompt_id = ?", assistantMessageID, promptID).
+ Delete(&types.AgentRunSuspension{}).Error
+ if err != nil {
+ return fmt.Errorf("delete agent run suspension: %w", err)
+ }
+ return nil
+}
diff --git a/internal/application/repository/agent_prompt_repository_test.go b/internal/application/repository/agent_prompt_repository_test.go
new file mode 100644
index 000000000..d2588f109
--- /dev/null
+++ b/internal/application/repository/agent_prompt_repository_test.go
@@ -0,0 +1,224 @@
+package repository
+
+import (
+ "context"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+ "gorm.io/driver/sqlite"
+ "gorm.io/gorm"
+)
+
+func newAgentPromptTestRepo(t *testing.T) *AgentPromptRepository {
+ t.Helper()
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ require.NoError(t, err)
+ sqlDB, err := db.DB()
+ require.NoError(t, err)
+ sqlDB.SetMaxOpenConns(1)
+ t.Cleanup(func() { require.NoError(t, sqlDB.Close()) })
+ require.NoError(t, db.AutoMigrate(&types.AgentPrompt{}))
+ return NewAgentPromptRepository(db).(*AgentPromptRepository)
+}
+
+func TestAgentPromptRepositoryTransitionIsCompareAndSet(t *testing.T) {
+ ctx := context.Background()
+ repo := newAgentPromptTestRepo(t)
+ lease := time.Now().Add(time.Minute)
+ require.NoError(t, repo.Create(ctx, &types.AgentPrompt{
+ ID: "p1", TenantID: 7, UserID: "alice", SessionID: "s1",
+ Kind: types.AgentPromptKindToolApproval, Status: types.AgentPromptPending,
+ Request: types.JSON(`{"args":{"a":1}}`), OwnerInstance: "owner", LeaseUntil: &lease,
+ }))
+
+ resolvedBy := "alice"
+ ok, err := repo.Transition(ctx, "p1", types.AgentPromptTransition{
+ From: []string{types.AgentPromptPending}, To: types.AgentPromptAnswered,
+ Response: types.JSON(`{"approved":true}`), ResolvedBy: &resolvedBy,
+ })
+ require.NoError(t, err)
+ require.True(t, ok)
+
+ ok, err = repo.Transition(ctx, "p1", types.AgentPromptTransition{
+ From: []string{types.AgentPromptPending}, To: types.AgentPromptAnswered,
+ Response: types.JSON(`{"approved":false}`),
+ })
+ require.NoError(t, err)
+ require.False(t, ok, "a second answer must lose")
+
+ row, err := repo.Get(ctx, "p1")
+ require.NoError(t, err)
+ require.Equal(t, types.AgentPromptAnswered, row.Status)
+ require.JSONEq(t, `{"approved":true}`, string(row.Response))
+ require.JSONEq(t, `{"args":{"a":1}}`, string(row.Request))
+ require.Equal(t, "alice", row.ResolvedBy)
+
+ missing, err := repo.Get(ctx, "nope")
+ require.NoError(t, err)
+ require.Nil(t, missing)
+}
+
+func TestAgentPromptRepositoryRenewLeaseRequiresPendingOwner(t *testing.T) {
+ ctx := context.Background()
+ repo := newAgentPromptTestRepo(t)
+ require.NoError(t, repo.Create(ctx, &types.AgentPrompt{
+ ID: "p1", TenantID: 7, SessionID: "s1",
+ Kind: types.AgentPromptKindToolApproval, Status: types.AgentPromptPending,
+ OwnerInstance: "owner",
+ }))
+
+ until := time.Now().Add(time.Minute)
+ ok, err := repo.RenewLease(ctx, "p1", "intruder", until)
+ require.NoError(t, err)
+ require.False(t, ok)
+
+ ok, err = repo.RenewLease(ctx, "p1", "owner", until)
+ require.NoError(t, err)
+ require.True(t, ok)
+
+ _, err = repo.Transition(ctx, "p1", types.AgentPromptTransition{
+ From: []string{types.AgentPromptPending}, To: types.AgentPromptExpired,
+ })
+ require.NoError(t, err)
+ ok, err = repo.RenewLease(ctx, "p1", "owner", until)
+ require.NoError(t, err)
+ require.False(t, ok, "a closed row has no lease to renew")
+}
+
+func TestAgentPromptRepositoryListStaleLeasesOnlyPendingAndLapsed(t *testing.T) {
+ ctx := context.Background()
+ repo := newAgentPromptTestRepo(t)
+ now := time.Now()
+ lease := func(d time.Duration) *time.Time { at := now.Add(d); return &at }
+ for _, row := range []*types.AgentPrompt{
+ {ID: "older", Status: types.AgentPromptPending, LeaseUntil: lease(-2 * time.Minute)},
+ {ID: "old", Status: types.AgentPromptPending, LeaseUntil: lease(-time.Minute)},
+ {ID: "alive", Status: types.AgentPromptPending, LeaseUntil: lease(time.Minute)},
+ {ID: "closed", Status: types.AgentPromptSuspended, LeaseUntil: lease(-time.Minute)},
+ } {
+ row.TenantID, row.SessionID, row.Kind = 7, "s1", types.AgentPromptKindToolApproval
+ require.NoError(t, repo.Create(ctx, row))
+ }
+
+ rows, err := repo.ListStaleLeases(ctx, []string{types.AgentPromptPending}, now, 10)
+ require.NoError(t, err)
+ require.Len(t, rows, 2)
+ require.Equal(t, "older", rows[0].ID)
+ require.Equal(t, "old", rows[1].ID)
+
+ rows, err = repo.ListStaleLeases(ctx, []string{types.AgentPromptPending}, now, 1)
+ require.NoError(t, err)
+ require.Len(t, rows, 1)
+}
+
+func TestAgentRunSuspensionRepositorySaveReplacesAndDeleteIsConditional(t *testing.T) {
+ ctx := context.Background()
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ require.NoError(t, err)
+ sqlDB, err := db.DB()
+ require.NoError(t, err)
+ sqlDB.SetMaxOpenConns(1)
+ t.Cleanup(func() { require.NoError(t, sqlDB.Close()) })
+ require.NoError(t, db.AutoMigrate(&types.AgentRunSuspension{}))
+ repo := NewAgentRunSuspensionRepository(db)
+
+ missing, err := repo.Get(ctx, "m1")
+ require.NoError(t, err)
+ require.Nil(t, missing)
+
+ require.NoError(t, repo.Save(ctx, &types.AgentRunSuspension{
+ AssistantMessageID: "m1", TenantID: 7, SessionID: "s1", PromptID: "p1",
+ SnapshotVersion: 1, Snapshot: types.JSON(`{"round":1}`),
+ }))
+ require.NoError(t, repo.Save(ctx, &types.AgentRunSuspension{
+ AssistantMessageID: "m1", TenantID: 7, SessionID: "s1", PromptID: "p2",
+ SnapshotVersion: 1, Snapshot: types.JSON(`{"round":2}`),
+ }))
+ row, err := repo.Get(ctx, "m1")
+ require.NoError(t, err)
+ require.Equal(t, "p2", row.PromptID)
+ require.JSONEq(t, `{"round":2}`, string(row.Snapshot))
+
+ require.NoError(t, repo.Delete(ctx, "m1", "p1"))
+ row, err = repo.Get(ctx, "m1")
+ require.NoError(t, err)
+ require.NotNil(t, row, "an older prompt must not drop a newer prompt's state")
+
+ require.NoError(t, repo.Delete(ctx, "m1", "p2"))
+ row, err = repo.Get(ctx, "m1")
+ require.NoError(t, err)
+ require.Nil(t, row)
+
+ require.Error(t, repo.Save(ctx, &types.AgentRunSuspension{}))
+}
+
+func TestAgentPromptRepositoryExpiryAndSessionQueries(t *testing.T) {
+ ctx := context.Background()
+ repo := newAgentPromptTestRepo(t)
+ now := time.Now()
+ at := func(d time.Duration) *time.Time { v := now.Add(d); return &v }
+ for _, row := range []*types.AgentPrompt{
+ {ID: "expired", SessionID: "s1", Status: types.AgentPromptSuspended, ExpiresAt: at(-time.Minute)},
+ {ID: "open", SessionID: "s1", Status: types.AgentPromptSuspended, ExpiresAt: at(time.Hour)},
+ {ID: "forever", SessionID: "s2", Status: types.AgentPromptSuspended},
+ {ID: "done", SessionID: "s1", Status: types.AgentPromptDone, ExpiresAt: at(-time.Minute)},
+ } {
+ row.TenantID, row.Kind = 7, types.AgentPromptKindToolApproval
+ require.NoError(t, repo.Create(ctx, row))
+ }
+
+ expired, err := repo.ListExpired(ctx, now, 10)
+ require.NoError(t, err)
+ require.Len(t, expired, 1)
+ require.Equal(t, "expired", expired[0].ID)
+
+ inSession, err := repo.ListBySession(ctx, "s1", []string{types.AgentPromptSuspended})
+ require.NoError(t, err)
+ ids := []string{}
+ for _, r := range inSession {
+ ids = append(ids, r.ID)
+ }
+ require.ElementsMatch(t, []string{"expired", "open"}, ids)
+
+ answer := func(id string) bool {
+ ok, err := repo.Transition(ctx, id, types.AgentPromptTransition{
+ From: []string{types.AgentPromptSuspended}, To: types.AgentPromptAnswered, UnexpiredAt: &now,
+ })
+ require.NoError(t, err)
+ return ok
+ }
+ require.False(t, answer("expired"), "an expired prompt cannot be answered")
+ require.True(t, answer("open"))
+ require.True(t, answer("forever"), "a prompt without expiry stays answerable")
+}
+
+func TestAgentPromptTransitionRechecksOwnerAndLease(t *testing.T) {
+ repo := newAgentPromptTestRepo(t)
+ ctx := t.Context()
+ past, now, future := time.Now().Add(-time.Minute), time.Now(), time.Now().Add(time.Minute)
+ owner, other := "owner", "other"
+ require.NoError(t, repo.Create(ctx, &types.AgentPrompt{
+ ID: "p", TenantID: 1, SessionID: "s", Kind: "ask_user",
+ Status: types.AgentPromptPending, OwnerInstance: owner, LeaseUntil: &past,
+ }))
+ transition := types.AgentPromptTransition{
+ From: []string{types.AgentPromptPending}, To: types.AgentPromptSuspended,
+ ExpectedOwner: &other, LeaseBefore: &now,
+ }
+ ok, err := repo.Transition(ctx, "p", transition)
+ require.NoError(t, err)
+ require.False(t, ok)
+ transition.ExpectedOwner = &owner
+ _, err = repo.RenewLease(ctx, "p", owner, future)
+ require.NoError(t, err)
+ ok, err = repo.Transition(ctx, "p", transition)
+ require.NoError(t, err)
+ require.False(t, ok)
+ _, err = repo.RenewLease(ctx, "p", owner, past)
+ require.NoError(t, err)
+ ok, err = repo.Transition(ctx, "p", transition)
+ require.NoError(t, err)
+ require.True(t, ok)
+}
diff --git a/internal/application/repository/message.go b/internal/application/repository/message.go
index 1adef0851..f4efc900d 100644
--- a/internal/application/repository/message.go
+++ b/internal/application/repository/message.go
@@ -267,6 +267,13 @@ func (r *messageRepository) UpdateMessage(ctx context.Context, message *types.Me
).Updates(message).Error; err != nil {
return err
}
+ // Updates skips zero values; written on its own so a resumed or
+ // closed run can clear it.
+ if err := tx.Model(&types.Message{}).Where(
+ "id = ? AND session_id = ?", message.ID, message.SessionID,
+ ).Update("run_state", message.RunState).Error; err != nil {
+ return err
+ }
return writeMessageArtifacts(tx, message)
})
}
diff --git a/internal/application/service/agent_service.go b/internal/application/service/agent_service.go
index 7071761d8..6865ecc32 100644
--- a/internal/application/service/agent_service.go
+++ b/internal/application/service/agent_service.go
@@ -1229,6 +1229,12 @@ func (s *agentService) registerTools(
toolToRegister = tools.NewSequentialThinkingTool()
case tools.ToolTodoWrite:
toolToRegister = tools.NewTodoWriteTool()
+ case tools.ToolAskUser:
+ asker, ok := s.toolApprovalGate.(approval.UserAsker)
+ if !ok || asker == nil {
+ continue
+ }
+ toolToRegister = tools.NewAskUserTool(asker)
case tools.ToolSearchKnowledge:
toolToRegister = tools.NewSearchKnowledgeTool(
s.knowledgeBaseService,
diff --git a/internal/application/service/session_agent_qa.go b/internal/application/service/session_agent_qa.go
index 154e38e5a..d5bbb0631 100644
--- a/internal/application/service/session_agent_qa.go
+++ b/internal/application/service/session_agent_qa.go
@@ -268,6 +268,15 @@ func (s *sessionService) AgentQA(
engine.SetSteerSink(req.SteerSink)
}
+ engine.SetInteractive(req.Interactive)
+ if req.Suspendable && s.cfg != nil && s.cfg.Agent.PromptSuspend() {
+ if request, err := json.Marshal(resumableAgentRequest(ctx, req)); err != nil {
+ logger.Warnf(ctx, "Run cannot be suspended, encoding its request failed: %v", err)
+ } else {
+ engine.EnableSuspension(request)
+ }
+ }
+
// A compaction that ends on a stored turn is written back onto it, so the
// next turn loads the summary instead of summarizing the same history
// again. Without multi-turn there is no stored history to end on.
@@ -305,7 +314,13 @@ func (s *sessionService) AgentQA(
// Execute agent with streaming (asynchronously)
// Events will be emitted to EventBus and handled by the Handler layer
logger.Info(ctx, "Executing agent with streaming")
- if _, err := engine.Execute(ctx, sessionID, req.AssistantMessageID, agentQuery, llmContext, agentImageURLs); err != nil {
+ if req.Resume != nil {
+ _, err = engine.Resume(ctx, sessionID, req.AssistantMessageID, llmContext,
+ req.Resume.Snapshot, req.Resume.Prompt)
+ } else {
+ _, err = engine.Execute(ctx, sessionID, req.AssistantMessageID, agentQuery, llmContext, agentImageURLs)
+ }
+ if err != nil {
logger.Errorf(ctx, "Agent execution failed: %v", err)
// Emit error event to the EventBus used by this agent
eventBus.Emit(ctx, event.Event{
@@ -322,6 +337,30 @@ func (s *sessionService) AgentQA(
return nil
}
+// resumableAgentRequest keeps the durable part of req needed to rebuild the
+// run elsewhere. Session, attachments and images are reloaded from storage.
+func resumableAgentRequest(ctx context.Context, req *types.QARequest) types.ResumableAgentRequest {
+ r := types.ResumableAgentRequest{
+ Query: req.Query,
+ SummaryModelID: req.SummaryModelID,
+ ReasoningEffort: req.ReasoningEffort,
+ SharedAgentReadOnly: req.SharedAgentReadOnly,
+ KnowledgeBaseIDs: req.KnowledgeBaseIDs,
+ KnowledgeIDs: req.KnowledgeIDs,
+ TagScopes: req.TagScopes,
+ MCPServiceIDs: req.MCPServiceIDs,
+ SkillNames: req.SkillNames,
+ WebSearchEnabled: req.WebSearchEnabled,
+ QuestionOrigin: req.QuestionOrigin,
+ UserMessageID: req.UserMessageID,
+ Language: types.LanguageFromContextOrDefault(ctx),
+ }
+ if req.CustomAgent != nil {
+ r.AgentID, r.AgentTenantID = req.CustomAgent.ID, req.CustomAgent.TenantID
+ }
+ return r
+}
+
// buildAgentConfig creates a runtime AgentConfig from the QARequest's custom agent configuration,
// tenant info, and resolved knowledge bases / search targets.
func (s *sessionService) buildAgentConfig(
diff --git a/internal/application/service/session_rewind.go b/internal/application/service/session_rewind.go
index a9994d316..2eaab1df4 100644
--- a/internal/application/service/session_rewind.go
+++ b/internal/application/service/session_rewind.go
@@ -170,8 +170,13 @@ type SessionRewindService struct {
snapshots ForkSnapshotDeleter
liveRuns rewindLiveRunReader
busyGate *SessionBusyGate
+ // suspendedRuns closes runs suspended on prompts before the cut.
+ suspendedRuns *SuspendedRunService
}
+// SetSuspendedRuns lets rewind close the session's suspended runs.
+func (s *SessionRewindService) SetSuspendedRuns(runs *SuspendedRunService) { s.suspendedRuns = runs }
+
// NewSessionRewindService wires the service. A nil sandbox port skips the
// workspace reset with NO_SANDBOX, which is the correct behaviour for a
// deployment without sandboxes.
@@ -243,6 +248,13 @@ func (s *SessionRewindService) Rewind(
if userID == "" || source.UserID != userID {
return nil, ErrRewindSessionNotFound
}
+ // Rewinding moves on from a prompt still waiting for an answer; its run
+ // is completed first so it does not read as a turn in progress.
+ if s.suspendedRuns != nil {
+ if _, err := s.suspendedRuns.SupersedeSession(ctx, sessionID); err != nil {
+ return nil, fmt.Errorf("session rewind: supersede suspended runs: %w", err)
+ }
+ }
rewindPoint, err := s.messages.GetMessage(ctx, sessionID, messageID)
if err != nil {
diff --git a/internal/application/service/suspended_run.go b/internal/application/service/suspended_run.go
new file mode 100644
index 000000000..c0fdb6133
--- /dev/null
+++ b/internal/application/service/suspended_run.go
@@ -0,0 +1,94 @@
+package service
+
+import (
+ "context"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/agent"
+ "github.com/Tencent/WeKnora/internal/agent/hitl"
+ agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+)
+
+// SuspendedRunService keeps the assistant message of a suspended run in step
+// with its prompt when the system, not the run itself, moves the prompt on:
+// the reaper taking over, or the user moving on without answering.
+type SuspendedRunService struct {
+ broker *hitl.Broker
+ messages interfaces.MessageRepository
+}
+
+// NewSuspendedRunService builds the service.
+func NewSuspendedRunService(broker *hitl.Broker, messages interfaces.MessageRepository) *SuspendedRunService {
+ s := &SuspendedRunService{broker: broker, messages: messages}
+ broker.SetRunHooks(s.Hooks())
+ return s
+}
+
+// Hooks returns the message updates the broker runs as it takes prompts over.
+func (s *SuspendedRunService) Hooks() hitl.RunHooks {
+ return hitl.RunHooks{Suspended: s.MarkAwaitingInput, Closed: s.Close}
+}
+
+// Reap runs one reaper sweep.
+func (s *SuspendedRunService) Reap(ctx context.Context, now time.Time) (int, error) {
+ return s.broker.Reap(ctx, now, s.Hooks())
+}
+
+// SupersedeSession closes the session's suspended runs because the user moved
+// on. Call it before the session's history is read or cut.
+func (s *SuspendedRunService) SupersedeSession(ctx context.Context, sessionID string) (int, error) {
+ return s.broker.SupersedeSession(ctx, sessionID, s.Hooks())
+}
+
+// MarkAwaitingInput shows a run suspended on its owner's behalf the way a
+// self-suspended run looks: the saved steps, waiting on the prompt.
+func (s *SuspendedRunService) MarkAwaitingInput(
+ ctx context.Context, prompt *types.AgentPrompt, state *types.AgentRunSuspension,
+) error {
+ return s.update(ctx, prompt, state, func(msg *types.Message, snap *agent.RunSnapshot) {
+ msg.AgentSteps = agenttools.SanitizeAgentStepsForStorage(snap.DisplaySteps())
+ msg.RunState = types.MessageRunStateAwaitingInput
+ })
+}
+
+// Close completes a run that will never resume. The blocked call and the
+// calls after it are recorded as failed with reason.
+func (s *SuspendedRunService) Close(
+ ctx context.Context, prompt *types.AgentPrompt, state *types.AgentRunSuspension, reason string,
+) error {
+ return s.update(ctx, prompt, state, func(msg *types.Message, snap *agent.RunSnapshot) {
+ msg.AgentSteps = agenttools.SanitizeAgentStepsForStorage(snap.ClosedSteps(reason))
+ msg.KnowledgeReferences = mergeSnapshotReferences(msg.KnowledgeReferences, snap.KnowledgeRefs)
+ msg.RunState = ""
+ msg.IsCompleted = true
+ })
+}
+
+func (s *SuspendedRunService) update(
+ ctx context.Context, prompt *types.AgentPrompt, state *types.AgentRunSuspension,
+ apply func(*types.Message, *agent.RunSnapshot),
+) error {
+ snap, err := agent.DecodeRunSnapshot(state.Snapshot)
+ if err != nil {
+ return err
+ }
+ msg, err := s.messages.GetMessage(ctx, prompt.SessionID, prompt.AssistantMessageID)
+ if err != nil {
+ return err
+ }
+ if msg == nil || msg.IsCompleted {
+ return nil
+ }
+ apply(msg, snap)
+ msg.UpdatedAt = time.Now()
+ return s.messages.UpdateMessage(ctx, msg)
+}
+
+func mergeSnapshotReferences(existing types.References, refs []*types.SearchResult) types.References {
+ if len(existing) > 0 || len(refs) == 0 {
+ return existing
+ }
+ return types.References(refs)
+}
diff --git a/internal/application/service/suspended_run_test.go b/internal/application/service/suspended_run_test.go
new file mode 100644
index 000000000..88872daec
--- /dev/null
+++ b/internal/application/service/suspended_run_test.go
@@ -0,0 +1,118 @@
+package service
+
+import (
+ "context"
+ "encoding/json"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/agent"
+ "github.com/Tencent/WeKnora/internal/agent/hitl"
+ "github.com/Tencent/WeKnora/internal/application/repository"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+ "gorm.io/driver/sqlite"
+ "gorm.io/gorm"
+)
+
+func newSuspendedRunFixture(t *testing.T) (*SuspendedRunService, *hitl.Broker, *gorm.DB) {
+ t.Helper()
+ db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
+ require.NoError(t, err)
+ sqlDB, err := db.DB()
+ require.NoError(t, err)
+ sqlDB.SetMaxOpenConns(1)
+ t.Cleanup(func() { _ = sqlDB.Close() })
+ require.NoError(t, db.AutoMigrate(&types.Message{}, &types.MessageArtifactRecord{}))
+ broker := hitl.NewBroker(nil, nil)
+ return NewSuspendedRunService(broker, repository.NewMessageRepository(db)), broker, db
+}
+
+// seedSuspendedRun stores a run of sessionID suspended on promptID and
+// returns its assistant message ID.
+func seedSuspendedRun(
+ t *testing.T, broker *hitl.Broker, db *gorm.DB, sessionID, promptID string, expires *time.Time,
+) string {
+ t.Helper()
+ ctx := context.Background()
+ snap := agent.RunSnapshot{
+ Version: agent.RunSnapshotVersion,
+ Query: "q",
+ CompletedSteps: []types.AgentStep{{Iteration: 0, Thought: "earlier round"}},
+ PendingRound: agent.PendingRound{
+ Step: types.AgentStep{Iteration: 1, Thought: "checking", ToolCalls: []types.ToolCall{
+ {ID: "call-a", Name: "first", Result: &types.ToolResult{Success: true, Output: "ok"}},
+ }},
+ Calls: []agent.PendingCall{
+ {ID: "call-a", Name: "first", Arguments: `{}`},
+ {ID: "call-b", Name: "danger", Arguments: `{"x":1}`},
+ },
+ BlockedIndex: 1,
+ },
+ }
+ data, err := json.Marshal(snap)
+ require.NoError(t, err)
+ msg := &types.Message{
+ SessionID: sessionID, Role: "assistant",
+ RunState: types.MessageRunStateAwaitingInput, CreatedAt: time.Now(),
+ }
+ require.NoError(t, db.Create(msg).Error)
+ messageID := msg.ID
+ require.NoError(t, broker.Store().Create(ctx, &types.AgentPrompt{
+ ID: promptID, TenantID: 1, SessionID: sessionID, AssistantMessageID: messageID,
+ Kind: types.AgentPromptKindToolApproval, ToolCallID: "call-b",
+ Status: types.AgentPromptSuspended, Suspendable: true, ExpiresAt: expires,
+ }))
+ require.NoError(t, broker.Suspensions().Save(ctx, &types.AgentRunSuspension{
+ AssistantMessageID: messageID, TenantID: 1, SessionID: sessionID, PromptID: promptID,
+ SnapshotVersion: agent.RunSnapshotVersion, Snapshot: types.JSON(data),
+ }))
+ return messageID
+}
+
+func TestSuspendedRunSupersedeCompletesTheMessage(t *testing.T) {
+ ctx := context.Background()
+ runs, broker, db := newSuspendedRunFixture(t)
+ m1 := seedSuspendedRun(t, broker, db, "s1", "p1", nil)
+
+ n, err := runs.SupersedeSession(ctx, "s1")
+ require.NoError(t, err)
+ require.Equal(t, 1, n)
+
+ var msg types.Message
+ require.NoError(t, db.First(&msg, "id = ?", m1).Error)
+ require.True(t, msg.IsCompleted)
+ require.Empty(t, msg.RunState, "run_state is cleared, not left stale")
+ require.Len(t, msg.AgentSteps, 2)
+ calls := msg.AgentSteps[1].ToolCalls
+ require.Len(t, calls, 2, "every call the model issued keeps a result")
+ require.True(t, calls[0].Result.Success)
+ require.False(t, calls[1].Result.Success)
+ require.Equal(t, hitl.ReasonPromptSupersede, calls[1].Result.Error)
+
+ saved, err := broker.Suspensions().Get(ctx, m1)
+ require.NoError(t, err)
+ require.Nil(t, saved)
+}
+
+func TestSuspendedRunReapExpiresAndCloses(t *testing.T) {
+ ctx := context.Background()
+ runs, broker, db := newSuspendedRunFixture(t)
+ m1 := seedSuspendedRun(t, broker, db, "s1", "p1", nil)
+ past := time.Now().Add(-time.Minute)
+ m2 := seedSuspendedRun(t, broker, db, "s2", "p-old", &past)
+
+ n, err := runs.Reap(ctx, time.Now())
+ require.NoError(t, err)
+ require.Equal(t, 1, n)
+
+ var msg types.Message
+ require.NoError(t, db.First(&msg, "id = ?", m2).Error)
+ require.True(t, msg.IsCompleted)
+ require.Equal(t, hitl.ReasonPromptExpired, msg.AgentSteps[1].ToolCalls[1].Result.Error)
+
+ var open types.Message
+ require.NoError(t, db.First(&open, "id = ?", m1).Error)
+ require.False(t, open.IsCompleted)
+ require.Equal(t, types.MessageRunStateAwaitingInput, open.RunState)
+}
diff --git a/internal/application/service/tenant_skill_install_test.go b/internal/application/service/tenant_skill_install_test.go
index 5c3d38c52..f29239fee 100644
--- a/internal/application/service/tenant_skill_install_test.go
+++ b/internal/application/service/tenant_skill_install_test.go
@@ -224,8 +224,10 @@ func TestSkillTreeVerifyCommandQuotesPaths(t *testing.T) {
func TestVerifySkillTreeIssuesOneCommandRegardlessOfScriptCount(t *testing.T) {
fx := newInstallFixture(t)
files := map[string][]byte{"SKILL.md": []byte(validSkillMD)}
- rels := []string{"run.sh", "scripts/a.py", "scripts/b.py",
- "scripts/c.py", "scripts/d.py", "scripts/e.py"}
+ rels := []string{
+ "run.sh", "scripts/a.py", "scripts/b.py",
+ "scripts/c.py", "scripts/d.py", "scripts/e.py",
+ }
for _, rel := range rels {
files[rel] = []byte("pass\n")
}
@@ -3226,6 +3228,16 @@ func (e *installAgentEngine) SetMemoryPrompt(string)
func (e *installAgentEngine) SetSteerSink(sink types.SteerSink) { e.sink = sink }
func (e *installAgentEngine) SetContextCheckpointSink(types.ContextCheckpointSink) {}
+func (e *installAgentEngine) EnableSuspension(json.RawMessage) {}
+
+func (e *installAgentEngine) SetInteractive(bool) {}
+
+func (e *installAgentEngine) Resume(context.Context, string, string, []chat.Message,
+ []byte, *types.AgentPrompt,
+) (*types.AgentState, error) {
+ return nil, errors.New("not supported")
+}
+
type installSessionService struct {
fx *installFixture
}
@@ -3435,6 +3447,7 @@ func (s installFileService) SaveBytes(_ context.Context, data []byte, _ uint64,
}
return "file://bundle.zip", nil
}
+
func (s installFileService) GetFile(_ context.Context, ref string) (io.ReadCloser, error) {
if s.fx != nil {
s.fx.getFileCalls.Add(1)
diff --git a/internal/application/service/tenant_skill_transcript_test.go b/internal/application/service/tenant_skill_transcript_test.go
index 167897cc9..615b08cc1 100644
--- a/internal/application/service/tenant_skill_transcript_test.go
+++ b/internal/application/service/tenant_skill_transcript_test.go
@@ -73,6 +73,8 @@ func (s *transcriptStreams) ClearLiveRun(context.Context, string, string) error
return nil
}
+func (s *transcriptStreams) ResetEvents(context.Context, string, string) error { return nil }
+
func (s *transcriptStreams) types() []types.ResponseType {
out := make([]types.ResponseType, 0, len(s.events))
for _, evt := range s.events {
diff --git a/internal/config/config.go b/internal/config/config.go
index 16d293e8a..c3315cff1 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -50,6 +50,48 @@ type AgentConfig struct {
// ToolApprovalTimeoutSeconds is how long the agent waits for human approval on a flagged MCP tool.
// 0 means default 600 (10 minutes).
ToolApprovalTimeoutSeconds int `yaml:"tool_approval_timeout_seconds" json:"tool_approval_timeout_seconds"`
+ // PromptSuspendEnabled lets a run that waits on a suspendable prompt (tool
+ // approval) end after PromptHotWaitSeconds and persist its state instead of
+ // blocking up to ToolApprovalTimeoutSeconds. Unset means enabled.
+ PromptSuspendEnabled *bool `yaml:"prompt_suspend_enabled" json:"prompt_suspend_enabled"`
+ // PromptHotWaitSeconds is how long a suspendable prompt waits in memory
+ // before the run is suspended. 0 means default 120.
+ PromptHotWaitSeconds int `yaml:"prompt_hot_wait_seconds" json:"prompt_hot_wait_seconds"`
+ // PromptExpireSeconds is how long a suspended prompt stays answerable.
+ // 0 means default 604800 (7 days); a negative value never expires.
+ PromptExpireSeconds int `yaml:"prompt_expire_seconds" json:"prompt_expire_seconds"`
+}
+
+// Defaults for suspendable agent prompts.
+const (
+ DefaultPromptHotWait = 120 * time.Second
+ DefaultPromptExpire = 7 * 24 * time.Hour
+)
+
+// PromptSuspend reports whether suspendable prompts may suspend their run.
+func (c *AgentConfig) PromptSuspend() bool {
+ return c == nil || c.PromptSuspendEnabled == nil || *c.PromptSuspendEnabled
+}
+
+// PromptHotWait returns the in-memory wait before a run is suspended.
+func (c *AgentConfig) PromptHotWait() time.Duration {
+ if c == nil || c.PromptHotWaitSeconds <= 0 {
+ return DefaultPromptHotWait
+ }
+ return time.Duration(c.PromptHotWaitSeconds) * time.Second
+}
+
+// PromptExpiry returns how long a suspended prompt stays answerable; zero
+// means it never expires.
+func (c *AgentConfig) PromptExpiry() time.Duration {
+ switch {
+ case c == nil || c.PromptExpireSeconds == 0:
+ return DefaultPromptExpire
+ case c.PromptExpireSeconds < 0:
+ return 0
+ default:
+ return time.Duration(c.PromptExpireSeconds) * time.Second
+ }
}
// IMConfig configures the IM integration service.
@@ -821,6 +863,10 @@ func applyAgentEnvOverrides(cfg *Config) {
cfg.Agent.ToolApprovalTimeoutSeconds = int(d.Seconds())
}
}
+ if value := strings.TrimSpace(os.Getenv("WEKNORA_AGENT_PROMPT_SUSPEND")); value != "" {
+ enabled := strings.EqualFold(value, "true")
+ cfg.Agent.PromptSuspendEnabled = &enabled
+ }
}
// applyAuthAndTenantDefaults fills in defaults for the Auth and Tenant
diff --git a/internal/container/container.go b/internal/container/container.go
index f5a26ff95..78b1ca104 100644
--- a/internal/container/container.go
+++ b/internal/container/container.go
@@ -37,6 +37,7 @@ import (
"gorm.io/gorm"
"github.com/Tencent/WeKnora/internal/agent/approval"
+ "github.com/Tencent/WeKnora/internal/agent/hitl"
"github.com/Tencent/WeKnora/internal/application/repository"
dorisRepo "github.com/Tencent/WeKnora/internal/application/repository/retriever/doris"
elasticsearchRepoV7 "github.com/Tencent/WeKnora/internal/application/repository/retriever/elasticsearch/v7"
@@ -178,6 +179,8 @@ func BuildContainer(container *dig.Container) *dig.Container {
must(container.Provide(neo4jRepo.NewNeo4jRepository))
must(container.Provide(repository.NewMCPServiceRepository))
must(container.Provide(repository.NewMCPToolApprovalRepository))
+ must(container.Provide(repository.NewAgentPromptRepository))
+ must(container.Provide(repository.NewAgentRunSuspensionRepository))
must(container.Provide(repository.NewMCPOAuthRepository))
must(container.Provide(repository.NewTenantSandboxConfigRepository))
must(container.Provide(repository.NewTenantSkillRepository))
@@ -324,8 +327,24 @@ func BuildContainer(container *dig.Container) *dig.Container {
logger.Debugf(ctx, "[Container] Registering event bus and agent service...")
must(container.Provide(event.NewEventBus))
must(container.Provide(service.NewSessionSandboxPinner))
- must(container.Provide(func(cfg *config.Config, s interfaces.MCPToolApprovalService, rdb *redis.Client) *approval.Gate {
- return approval.NewGate(cfg, &approval.Adapter{Svc: s}, rdb)
+ must(container.Provide(func(
+ cfg *config.Config,
+ prompts interfaces.AgentPromptRepository,
+ suspensions interfaces.AgentRunSuspensionRepository,
+ rdb *redis.Client,
+ ) *hitl.Broker {
+ opts := []hitl.Option{hitl.WithSuspensionStore(suspensions)}
+ if cfg != nil && cfg.Agent != nil {
+ opts = append(opts, hitl.WithSuspendExpiry(cfg.Agent.PromptExpiry()))
+ }
+ return hitl.NewBroker(prompts, rdb, opts...)
+ }))
+ must(container.Provide(service.NewSuspendedRunService))
+ must(container.Invoke(startAgentPromptReaper))
+ must(container.Provide(func(
+ cfg *config.Config, s interfaces.MCPToolApprovalService, broker *hitl.Broker,
+ ) *approval.Gate {
+ return approval.NewGate(cfg, &approval.Adapter{Svc: s}, broker)
}))
// Expose Gate as MCPApproval interface so AgentService and others can depend on the abstraction.
must(container.Provide(func(g *approval.Gate) approval.MCPApproval { return g }))
@@ -564,6 +583,14 @@ func BuildContainer(container *dig.Container) *dig.Container {
) *handler.MCPServiceHandler {
return handler.NewMCPServiceHandler(mcpService, toolApprovals, gate, models, agents)
}))
+ must(container.Invoke(func(
+ sessions *session.Handler, mcp *handler.MCPServiceHandler,
+ broker *hitl.Broker, runs *service.SuspendedRunService, rewind *service.SessionRewindService,
+ ) {
+ rewind.SetSuspendedRuns(runs)
+ sessions.SetSuspendedRuns(broker, runs)
+ mcp.SetRunResumer(sessions)
+ }))
must(container.Provide(handler.NewMCPCredentialsHandler))
must(container.Provide(handler.NewMCPOAuthHandler))
must(container.Provide(handler.NewModelCredentialsHandler))
@@ -1974,6 +2001,31 @@ func startForkSnapshotReaper(reaper *service.ForkSnapshotReaper, cleaner interfa
})
}
+// startAgentPromptReaper takes over prompts whose owner stopped renewing its
+// lease and suspended prompts past their expiry, so a crash never leaves a
+// prompt or its run open forever.
+func startAgentPromptReaper(runs *service.SuspendedRunService, cleaner interfaces.ResourceCleaner) {
+ stop := make(chan struct{})
+ go func() {
+ ticker := time.NewTicker(time.Minute)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-ticker.C:
+ if _, err := runs.Reap(context.Background(), time.Now()); err != nil {
+ logger.Warnf(context.Background(), "[AgentPromptReaper] reap failed: %v", err)
+ }
+ case <-stop:
+ return
+ }
+ }
+ }()
+ cleaner.RegisterWithName("AgentPromptReaper", func() error {
+ close(stop)
+ return nil
+ })
+}
+
// startTemporaryDocumentCleanup removes expired session attachments and their
// extracted images. The durable expiry timestamp is the source of truth; the
// ticker only controls how quickly storage is reclaimed.
diff --git a/internal/database/migration_sqlite_agent_allowed_tools_test.go b/internal/database/migration_sqlite_agent_allowed_tools_test.go
index a32c99954..ea7ca70e7 100644
--- a/internal/database/migration_sqlite_agent_allowed_tools_test.go
+++ b/internal/database/migration_sqlite_agent_allowed_tools_test.go
@@ -38,8 +38,11 @@ func requireAgentToolListsUpgraded(t *testing.T, db *sql.DB, query string) {
require.NoError(t, json.Unmarshal([]byte(agentToolListRows[id]), &want), id)
require.JSONEq(t, string(want.AllowedTools), string(got.AllowedTools), "%s must be left as it is", id)
}
+ // Migration 35 freezes the defaults that existed when it was written.
+ // Later defaults must not silently grant tools to explicit lists.
+ legacyDefaults := []string{"search_knowledge", "read_document", "list_documents", "search_conversations"}
want := map[string][]string{
- "reasoning-empty": tools.DefaultAllowedTools(),
+ "reasoning-empty": legacyDefaults,
"reasoning-null": nil,
"reasoning-missing": nil,
"reasoning-picked": {"thinking"},
@@ -55,6 +58,9 @@ func requireAgentToolListsUpgraded(t *testing.T, db *sql.DB, query string) {
require.Equal(t, expected, config.AllowedTools, id)
// The default tools still apply to the agents that never set a list.
before := tools.EffectiveAllowedTools(decodeAllowedTools(t, agentToolListRows[id]))
+ if id == "reasoning-empty" {
+ before = legacyDefaults
+ }
require.ElementsMatch(t, before, tools.EffectiveAllowedTools(config.AllowedTools),
"%s must keep its effective tools", id)
}
diff --git a/internal/database/migration_sqlite_versioned_schema_test.go b/internal/database/migration_sqlite_versioned_schema_test.go
index 44a41b856..e18f53c4f 100644
--- a/internal/database/migration_sqlite_versioned_schema_test.go
+++ b/internal/database/migration_sqlite_versioned_schema_test.go
@@ -36,19 +36,22 @@ var versionedSQLiteTables = []string{
"tenant_skill_snapshots",
"tenant_skill_catalog",
"tenant_user_env_vars",
+ "agent_prompts",
+ "agent_run_suspensions",
}
// versionedSQLiteColumns maps each existing table to the columns that the
// versioned migrations add and the SQLite baseline was missing.
var versionedSQLiteColumns = map[string][]string{
- "model_catalog_configs": {"version", "overlay", "history", "updated_by", "updated_at"}, // 000031
- "memory_subjects": {"extraction_state"}, // 000094
- "memory_items": {"replaces_id"}, // 000094
- "tenants": {"api_principal_config"}, // 000064
- "users": {"is_system_admin"}, // 000053
- "knowledges": {"pending_subtasks_count", "profile"}, // 000056, 000101
- "knowledge_bases": {"profile_config", "generated_profile"}, // 000101
- "messages": {"attachments", "usage", "sandbox_checkpoint", "context_checkpoint"}, // 000034/085/097/105
+ "model_catalog_configs": {"version", "overlay", "history", "updated_by", "updated_at"}, // 000031
+ "memory_subjects": {"extraction_state"}, // 000094
+ "memory_items": {"replaces_id"}, // 000094
+ "tenants": {"api_principal_config"}, // 000064
+ "users": {"is_system_admin"}, // 000053
+ "knowledges": {"pending_subtasks_count", "profile"}, // 000056, 000101
+ "knowledge_bases": {"profile_config", "generated_profile"}, // 000101
+ // 000034/085/097/105/119
+ "messages": {"attachments", "usage", "sandbox_checkpoint", "context_checkpoint", "run_state"},
"sessions": {
"parent_session_id", "forked_from_message_id", "fork_bootstrap", // 000097
"sandbox_config_tenant_id", // 000027
@@ -71,7 +74,7 @@ var versionedSQLiteColumns = map[string][]string{
}, // 000028
}
-const expectedSQLiteMigrationVersion = 36
+const expectedSQLiteMigrationVersion = 37
func TestSQLiteMigrationsCreateVersionedSchema(t *testing.T) {
repoRoot := sqliteRepoRoot(t)
diff --git a/internal/event/event.go b/internal/event/event.go
index b9b556b57..66434760d 100644
--- a/internal/event/event.go
+++ b/internal/event/event.go
@@ -61,6 +61,11 @@ const (
EventToolApprovalRequired EventType = "tool_approval_required"
EventToolApprovalResolved EventType = "tool_approval_resolved"
+ // EventAgentPromptRequired requests user input (ask_user). The request and answer travel as the
+ // prompt kind's JSON, so a new kind needs no new event.
+ EventAgentPromptRequired EventType = "agent_prompt_required"
+ EventAgentPromptResolved EventType = "agent_prompt_resolved"
+
// MCP OAuth in-conversation authorization prompt: emitted when an
// OAuth-enabled MCP service is invoked but the current user has not
// authorized it yet. The agent pauses until the user authorizes (or the
diff --git a/internal/event/event_data.go b/internal/event/event_data.go
index 7546485f7..7f27505ca 100644
--- a/internal/event/event_data.go
+++ b/internal/event/event_data.go
@@ -1,6 +1,9 @@
package event
-import "time"
+import (
+ "encoding/json"
+ "time"
+)
// EventData contains common event data structures for different stages
@@ -147,6 +150,9 @@ type AgentCompleteData struct {
MessageID string `json:"message_id,omitempty"` // Assistant message ID
RequestID string `json:"request_id,omitempty"`
Extra map[string]interface{} `json:"extra,omitempty"`
+ // Suspended is set (*types.PromptSuspension) when the run ended waiting
+ // on a user prompt; the message is then not complete.
+ Suspended interface{} `json:"suspended,omitempty"`
}
// === Streaming Event Data Structures ===
@@ -271,9 +277,13 @@ type ToolApprovalRequiredData struct {
Args interface{} `json:"args,omitempty"`
ArgsJSON string `json:"args_json,omitempty"`
TimeoutSeconds int `json:"timeout_seconds"`
- RequestedAtUnix int64 `json:"requested_at"`
- ToolCallID string `json:"tool_call_id"`
- RequestID string `json:"request_id,omitempty"`
+ // HotWaitSeconds equals TimeoutSeconds; when Suspendable, the run is
+ // suspended rather than rejected once it elapses.
+ HotWaitSeconds int `json:"hot_wait_seconds"`
+ Suspendable bool `json:"suspendable"`
+ RequestedAtUnix int64 `json:"requested_at"`
+ ToolCallID string `json:"tool_call_id"`
+ RequestID string `json:"request_id,omitempty"`
}
// ToolApprovalResolvedData confirms the user decision (or timeout/cancel).
@@ -285,6 +295,34 @@ type ToolApprovalResolvedData struct {
Canceled bool `json:"canceled,omitempty"`
}
+// AgentPromptRequiredData asks the user a question of the given kind.
+// Request is the kind's request JSON, e.g. types.AskUserPromptRequest.
+type AgentPromptRequiredData struct {
+ PendingID string `json:"pending_id"`
+ Kind string `json:"kind"`
+ SessionID string `json:"session_id"`
+ AssistantMessageID string `json:"assistant_message_id"`
+ Request json.RawMessage `json:"request"`
+ TimeoutSeconds int `json:"timeout_seconds"`
+ HotWaitSeconds int `json:"hot_wait_seconds"`
+ Suspendable bool `json:"suspendable"`
+ RequestedAtUnix int64 `json:"requested_at"`
+ ToolCallID string `json:"tool_call_id"`
+ RequestID string `json:"request_id,omitempty"`
+}
+
+// AgentPromptResolvedData reports how a prompt ended. Response is the
+// answer JSON when Answered.
+type AgentPromptResolvedData struct {
+ PendingID string `json:"pending_id"`
+ Kind string `json:"kind"`
+ Answered bool `json:"answered"`
+ Response json.RawMessage `json:"response,omitempty"`
+ Reason string `json:"reason,omitempty"`
+ TimedOut bool `json:"timed_out,omitempty"`
+ Canceled bool `json:"canceled,omitempty"`
+}
+
// MCPOAuthRequiredData is emitted when an OAuth-enabled MCP service is invoked
// during a conversation but the current user has not authorized it yet. The
// UI surfaces an "Authorize" card; the agent pauses until the user authorizes.
diff --git a/internal/handler/agent_prompt_test.go b/internal/handler/agent_prompt_test.go
new file mode 100644
index 000000000..dbddbb309
--- /dev/null
+++ b/internal/handler/agent_prompt_test.go
@@ -0,0 +1,90 @@
+package handler
+
+import (
+ "context"
+ "net/http"
+ "net/http/httptest"
+ "strings"
+ "testing"
+ "time"
+
+ "github.com/gin-gonic/gin"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+
+ "github.com/Tencent/WeKnora/internal/agent/approval"
+ "github.com/Tencent/WeKnora/internal/config"
+ "github.com/Tencent/WeKnora/internal/errors"
+ "github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+type recordingResumer struct{ prompts []*types.AgentPrompt }
+
+func (r *recordingResumer) ResumeSuspendedRun(_ *gin.Context, p *types.AgentPrompt, _ bool, _ *time.Time) {
+ r.prompts = append(r.prompts, p)
+}
+
+func postAgentPrompt(
+ h *MCPServiceHandler, promptID, body string, principal types.Principal,
+) (*httptest.ResponseRecorder, *gin.Context) {
+ w := httptest.NewRecorder()
+ c, _ := gin.CreateTestContext(w)
+ req := httptest.NewRequest(http.MethodPost, "/agent/prompts/"+promptID, strings.NewReader(body))
+ req.Header.Set("Content-Type", "application/json")
+ c.Request = req.WithContext(types.WithPrincipal(req.Context(), principal))
+ c.Params = gin.Params{{Key: "prompt_id", Value: promptID}}
+ c.Set(types.TenantIDContextKey.String(), uint64(1))
+ h.ResolveAgentPrompt(c)
+ return w, c
+}
+
+func appErrorCode(t *testing.T, c *gin.Context) int {
+ t.Helper()
+ require.NotEmpty(t, c.Errors)
+ var appErr *errors.AppError
+ require.ErrorAs(t, c.Errors.Last().Err, &appErr)
+ return appErr.HTTPCode
+}
+
+func TestResolveAgentPrompt(t *testing.T) {
+ gin.SetMode(gin.TestMode)
+ gate := approval.NewGate(&config.Config{Agent: &config.AgentConfig{
+ ToolApprovalTimeoutSeconds: 60, PromptHotWaitSeconds: 1,
+ }}, nil, nil)
+ resumer := &recordingResumer{}
+ h := &MCPServiceHandler{toolApprovalGate: gate, runResumer: resumer}
+ owner := types.Principal{Type: "user", ID: "u1"}
+
+ ans, err := gate.AskUser(context.Background(), approval.AskRequest{
+ TenantID: 1, UserID: owner.StorageID(), SessionID: "s1", AssistantMessageID: "m1", ToolCallID: "tc1",
+ EventBus: event.NewEventBus(), Question: types.AskUserPromptRequest{Question: "color?"},
+ Snapshot: []byte(`{"version":1}`), SnapshotVersion: 1,
+ })
+ require.NoError(t, err)
+ require.NotNil(t, ans.Suspended)
+ id := ans.PromptID
+
+ _, c := postAgentPrompt(h, id, `{"kind":"tool_approval","response":{"approved":true}}`, owner)
+ assert.Equal(t, http.StatusNotFound, appErrorCode(t, c), "a mismatched kind hides the prompt")
+
+ _, c = postAgentPrompt(h, id, `{"kind":"mcp_oauth","response":{"authorized":true}}`, owner)
+ assert.Equal(t, http.StatusBadRequest, appErrorCode(t, c), "OAuth cannot be claimed by the user")
+
+ _, c = postAgentPrompt(h, id, `{"kind":"ask_user","response":{}}`, owner)
+ assert.Equal(t, http.StatusBadRequest, appErrorCode(t, c), "an empty answer is invalid")
+
+ _, c = postAgentPrompt(h, id, `{"kind":"ask_user","response":{"text":"red"}}`,
+ types.Principal{Type: "user", ID: "u2"})
+ assert.Equal(t, http.StatusBadRequest, appErrorCode(t, c), "only the prompt's user may answer")
+ assert.Empty(t, resumer.prompts)
+
+ w, c := postAgentPrompt(h, id, `{"kind":"ask_user","response":{"text":"red"}}`, owner)
+ require.Empty(t, c.Errors)
+ assert.JSONEq(t, `{"success":true,"resumed":true}`, w.Body.String())
+ require.Len(t, resumer.prompts, 1)
+ assert.Equal(t, id, resumer.prompts[0].ID)
+
+ _, c = postAgentPrompt(h, id, `{"kind":"ask_user","response":{"text":"blue"}}`, owner)
+ assert.Equal(t, http.StatusBadRequest, appErrorCode(t, c), "a prompt is answered once")
+}
diff --git a/internal/handler/embed_channel.go b/internal/handler/embed_channel.go
index a03fe26b7..410974c8b 100644
--- a/internal/handler/embed_channel.go
+++ b/internal/handler/embed_channel.go
@@ -548,6 +548,18 @@ func (h *EmbedChannelHandler) EmbedResolveToolApproval(c *gin.Context) {
h.mcpServiceHandler.ResolveToolApproval(c)
}
+// EmbedResolveAgentPrompt answers a prompt raised in the visitor's session.
+func (h *EmbedChannelHandler) EmbedResolveAgentPrompt(c *gin.Context) {
+ if err := h.ensureEmbedSession(c); err != nil {
+ return
+ }
+ if h.mcpServiceHandler == nil {
+ c.JSON(http.StatusInternalServerError, gin.H{"error": "agent prompt handler unavailable"})
+ return
+ }
+ h.mcpServiceHandler.ResolveAgentPrompt(c)
+}
+
type embedWebhookEventRequest struct {
Type string `json:"type"`
SessionID string `json:"session_id"`
diff --git a/internal/handler/mcp_oauth.go b/internal/handler/mcp_oauth.go
index 0d22aee5c..c15952117 100644
--- a/internal/handler/mcp_oauth.go
+++ b/internal/handler/mcp_oauth.go
@@ -424,7 +424,7 @@ func (h *MCPOAuthHandler) ResolveMCPOAuth(c *gin.Context) {
switch decision {
case "cancel", "reject", "skip":
- if err := h.gate.Resolve(tenantID, gateUserID, pendingID, approval.Decision{
+ if err := h.resolveOAuthPrompt(c, tenantID, gateUserID, pendingID, approval.Decision{
Approved: false,
Reason: "user canceled",
}); err != nil {
@@ -466,7 +466,7 @@ func (h *MCPOAuthHandler) ResolveMCPOAuth(c *gin.Context) {
return
}
- if err := h.gate.Resolve(tenantID, gateUserID, pendingID, approval.Decision{Approved: true}); err != nil {
+ if err := h.resolveOAuthPrompt(c, tenantID, gateUserID, pendingID, approval.Decision{Approved: true}); err != nil {
switch {
case stderrors.Is(err, approval.ErrPendingNotFound):
c.Error(errors.NewNotFoundError("pending authorization not found or already completed"))
@@ -514,7 +514,7 @@ func (h *MCPOAuthHandler) CancelMCPOAuth(c *gin.Context) {
return
}
- if err := h.gate.Resolve(tenantID, gateUserID, pendingID, approval.Decision{
+ if err := h.resolveOAuthPrompt(c, tenantID, gateUserID, pendingID, approval.Decision{
Approved: false,
Reason: "user canceled",
}); err != nil {
@@ -537,3 +537,18 @@ func (h *MCPOAuthHandler) CancelMCPOAuth(c *gin.Context) {
}
c.JSON(http.StatusOK, gin.H{"success": true})
}
+
+// resolveOAuthPrompt records a decision on an in-conversation OAuth prompt.
+// The embed routes carry session_id, which pins the prompt to that session.
+func (h *MCPOAuthHandler) resolveOAuthPrompt(
+ c *gin.Context, tenantID uint64, userID, pendingID string, d approval.Decision,
+) error {
+ return h.gate.Resolve(c.Request.Context(), approval.ResolveRequest{
+ TenantID: tenantID,
+ UserID: userID,
+ SessionID: c.Param("session_id"),
+ Kind: types.AgentPromptKindMCPOAuth,
+ PendingID: pendingID,
+ Decision: d,
+ })
+}
diff --git a/internal/handler/mcp_service.go b/internal/handler/mcp_service.go
index d742d0d76..9d455ed8e 100644
--- a/internal/handler/mcp_service.go
+++ b/internal/handler/mcp_service.go
@@ -6,9 +6,11 @@ import (
stderrors "errors"
"net/http"
"strings"
+ "time"
"unicode/utf8"
"github.com/Tencent/WeKnora/internal/agent/approval"
+ "github.com/Tencent/WeKnora/internal/agent/hitl"
"github.com/Tencent/WeKnora/internal/application/access"
"github.com/Tencent/WeKnora/internal/errors"
"github.com/Tencent/WeKnora/internal/handler/dto"
@@ -29,8 +31,20 @@ type MCPServiceHandler struct {
// agents resolves a shared agent so the @MCP picker can list the services
// that agent can actually reach, which live in ITS OWNER's workspace.
agents access.SharedAgentLookup
+ // runResumer continues a run suspended on an approval once it is
+ // answered. Nil leaves such answers to the reaper, which closes the run.
+ runResumer RunResumer
}
+// RunResumer continues an agent run that ended suspended on prompt, now
+// answered by the request c. It must not block on the run.
+type RunResumer interface {
+ ResumeSuspendedRun(c *gin.Context, prompt *types.AgentPrompt, ownerGone bool, ownerLeaseUntil *time.Time)
+}
+
+// SetRunResumer wires the resumer of suspended runs.
+func (h *MCPServiceHandler) SetRunResumer(r RunResumer) { h.runResumer = r }
+
// NewMCPServiceHandler creates a new MCP service handler
func NewMCPServiceHandler(
mcpServiceService interfaces.MCPServiceService,
@@ -784,21 +798,103 @@ func (h *MCPServiceHandler) ResolveToolApproval(c *gin.Context) {
c.Error(errors.NewUnauthorizedError("authenticated user required to resolve tool approval"))
return
}
- if err := h.toolApprovalGate.Resolve(tenantID, gateUserID, pendingID, dec); err != nil {
+ // The embed route carries session_id; binding it stops an embed visitor
+ // from resolving a prompt raised in another session.
+ res, err := h.toolApprovalGate.ResolveForResume(ctx, approval.ResolveRequest{
+ TenantID: tenantID,
+ UserID: gateUserID,
+ SessionID: c.Param("session_id"),
+ Kind: types.AgentPromptKindToolApproval,
+ PendingID: pendingID,
+ Decision: dec,
+ })
+ h.finishResolve(c, pendingID, res, err)
+}
+
+// finishResolve maps a resolve error to its HTTP status, or resumes the
+// run a suspended prompt belonged to and reports whether it did.
+func (h *MCPServiceHandler) finishResolve(c *gin.Context, pendingID string, res hitl.Resolution, err error) {
+ ctx := c.Request.Context()
+ if err != nil {
switch {
case stderrors.Is(err, approval.ErrPendingNotFound):
- c.Error(errors.NewNotFoundError("pending approval not found or already completed"))
+ _ = c.Error(errors.NewNotFoundError("pending prompt not found or already completed"))
case stderrors.Is(err, approval.ErrAlreadyResolved):
- c.Error(errors.NewBadRequestError("pending approval already resolved (timeout / cancel raced your action)"))
+ _ = c.Error(errors.NewBadRequestError(
+ "pending prompt already resolved (timeout / cancel raced your action)"))
case stderrors.Is(err, approval.ErrTenantMismatch):
- c.Error(errors.NewBadRequestError("workspace mismatch"))
+ _ = c.Error(errors.NewBadRequestError("workspace mismatch"))
case stderrors.Is(err, approval.ErrUserMismatch):
- c.Error(errors.NewBadRequestError("user mismatch: only the session owner may resolve this approval"))
+ _ = c.Error(errors.NewBadRequestError("user mismatch: only the session owner may answer this prompt"))
+ case stderrors.Is(err, approval.ErrInvalidDecision):
+ _ = c.Error(errors.NewBadRequestError(err.Error()))
default:
logger.ErrorWithFields(ctx, err, map[string]interface{}{"pending_id": pendingID})
- c.Error(errors.NewInternalServerError(err.Error()))
+ _ = c.Error(errors.NewInternalServerError(err.Error()))
}
return
}
- c.JSON(http.StatusOK, gin.H{"success": true})
+ // A suspended run has ended; this replica now continues it.
+ resumed := res.Resume && h.runResumer != nil
+ if resumed {
+ h.runResumer.ResumeSuspendedRun(c, res.Prompt, res.OwnerGone, res.OwnerLeaseUntil)
+ }
+ c.JSON(http.StatusOK, gin.H{"success": true, "resumed": resumed})
+}
+
+type resolveAgentPromptBody struct {
+ Kind string `json:"kind" binding:"required"`
+ Response json.RawMessage `json:"response" binding:"required"`
+}
+
+// ResolveAgentPrompt godoc
+// @Summary 回答 Agent 的交互请求
+// @Description 回答 Agent 运行中发起的交互(ask_user 提问或工具审批)。
+// @Description kind 须与交互一致,response 为该类型的回答 JSON(不接受未知字段):
+// @Description ask_user 为 {selected?, values?, text?, declined?};
+// @Description tool_approval 为 {approved: bool, modified_args?: object, reason?: string}。
+// @Description 返回 resumed=true 表示运行已挂起并在本次回答后恢复,客户端需重新接入该消息的事件流
+// @Tags Agent
+// @Accept json
+// @Produce json
+// @Param prompt_id path string true "交互 ID(事件中的 pending_id)"
+// @Param request body map[string]interface{} true "{kind: \"ask_user\"|\"tool_approval\", response: object}"
+// @Success 200 {object} map[string]interface{} "{success: true, resumed: bool}"
+// @Failure 400 {object} errors.AppError "回答不合法或交互已结束"
+// @Failure 404 {object} errors.AppError "交互不存在"
+// @Security Bearer
+// @Security ApiKeyAuth
+// @Router /agent/prompts/{prompt_id} [post]
+func (h *MCPServiceHandler) ResolveAgentPrompt(c *gin.Context) {
+ ctx := c.Request.Context()
+ promptID := c.Param("prompt_id")
+ tenantID := c.GetUint64(types.TenantIDContextKey.String())
+ if tenantID == 0 {
+ _ = c.Error(errors.NewBadRequestError("Workspace ID cannot be empty"))
+ return
+ }
+ if h.toolApprovalGate == nil {
+ _ = c.Error(errors.NewInternalServerError("Agent prompts are not configured"))
+ return
+ }
+ var body resolveAgentPromptBody
+ if err := c.ShouldBindJSON(&body); err != nil {
+ _ = c.Error(errors.NewBadRequestError(err.Error()))
+ return
+ }
+ principal, _ := types.PrincipalFromContext(ctx)
+ userID := principal.StorageID()
+ if strings.TrimSpace(userID) == "" {
+ _ = c.Error(errors.NewUnauthorizedError("authenticated user required to answer a prompt"))
+ return
+ }
+ res, err := h.toolApprovalGate.ResolveResponse(ctx, hitl.ResolveRequest{
+ TenantID: tenantID,
+ UserID: userID,
+ SessionID: c.Param("session_id"),
+ Kind: body.Kind,
+ PromptID: promptID,
+ Response: body.Response,
+ })
+ h.finishResolve(c, promptID, res, err)
}
diff --git a/internal/handler/message.go b/internal/handler/message.go
index 991bcbc5c..c6a405a24 100644
--- a/internal/handler/message.go
+++ b/internal/handler/message.go
@@ -1,6 +1,7 @@
package handler
import (
+ "context"
stderrors "errors"
"net/http"
"strconv"
@@ -28,6 +29,9 @@ type MessageHandler struct {
// handle mode is available.
FileService interfaces.FileService
StorageResolver interfaces.StorageBackendResolver
+ // Prompts supplies the pending prompt of messages awaiting input. May be
+ // nil, in which case such messages carry none.
+ Prompts interfaces.AgentPromptRepository
}
// NewMessageHandler creates a new message handler instance with the required service
@@ -41,11 +45,52 @@ func NewMessageHandler(
messageService interfaces.MessageService,
fileService interfaces.FileService,
storageResolver interfaces.StorageBackendResolver,
+ prompts interfaces.AgentPromptRepository,
) *MessageHandler {
return &MessageHandler{
MessageService: messageService,
FileService: fileService,
StorageResolver: storageResolver,
+ Prompts: prompts,
+ }
+}
+
+// attachPendingPrompts sets PendingPrompt on messages awaiting input. Only
+// prompts raised for the caller are shown; the messages themselves were
+// already scoped to the caller's session.
+func (h *MessageHandler) attachPendingPrompts(ctx context.Context, sessionID string, messages []*types.Message) {
+ if h.Prompts == nil {
+ return
+ }
+ awaiting := false
+ for _, m := range messages {
+ awaiting = awaiting || m.RunState == types.MessageRunStateAwaitingInput
+ }
+ if !awaiting {
+ return
+ }
+ rows, err := h.Prompts.ListBySession(ctx, sessionID, []string{types.AgentPromptSuspended})
+ if err != nil {
+ logger.Warnf(ctx, "list pending prompts of session %s: %v", sessionID, err)
+ return
+ }
+ principal, _ := types.PrincipalFromContext(ctx)
+ caller := principal.StorageID()
+ byMessage := make(map[string]*types.AgentPrompt, len(rows))
+ for _, p := range rows {
+ if p.UserID == "" || p.UserID == caller {
+ byMessage[p.AssistantMessageID] = p
+ }
+ }
+ for _, m := range messages {
+ p := byMessage[m.ID]
+ if p == nil || m.RunState != types.MessageRunStateAwaitingInput {
+ continue
+ }
+ m.PendingPrompt = &types.PendingPromptView{
+ ID: p.ID, Kind: p.Kind, ToolCallID: p.ToolCallID,
+ Request: p.Request, ExpiresAt: p.ExpiresAt, CreatedAt: p.CreatedAt,
+ }
}
}
@@ -131,6 +176,7 @@ func (h *MessageHandler) LoadMessages(c *gin.Context) {
"Successfully retrieved recent messages, session ID: %s, message count: %d",
sessionID, len(messages),
)
+ h.attachPendingPrompts(ctx, sessionID, messages)
c.JSON(http.StatusOK, gin.H{
"success": true,
"data": rewriter.RewriteMessagesResponse(ctx, messages),
@@ -171,6 +217,7 @@ func (h *MessageHandler) LoadMessages(c *gin.Context) {
"Successfully retrieved messages before time, session ID: %s, message count: %d",
sessionID, len(messages),
)
+ h.attachPendingPrompts(ctx, sessionID, messages)
c.JSON(http.StatusOK, gin.H{
"success": true,
"data": rewriter.RewriteMessagesResponse(ctx, messages),
diff --git a/internal/handler/message_pending_prompt_test.go b/internal/handler/message_pending_prompt_test.go
new file mode 100644
index 000000000..4dd44a6e7
--- /dev/null
+++ b/internal/handler/message_pending_prompt_test.go
@@ -0,0 +1,70 @@
+package handler
+
+import (
+ "context"
+ "testing"
+ "time"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+)
+
+type sessionPromptRepo struct {
+ interfaces.AgentPromptRepository
+ rows []*types.AgentPrompt
+ calls int
+}
+
+func (r *sessionPromptRepo) ListBySession(
+ _ context.Context, sessionID string, statuses []string,
+) ([]*types.AgentPrompt, error) {
+ r.calls++
+ var out []*types.AgentPrompt
+ for _, p := range r.rows {
+ for _, s := range statuses {
+ if p.SessionID == sessionID && p.Status == s {
+ out = append(out, p)
+ }
+ }
+ }
+ return out, nil
+}
+
+func TestAttachPendingPrompts(t *testing.T) {
+ expires := time.Now().Add(time.Hour)
+ caller := types.Principal{Type: "user", ID: "u1"}
+ repo := &sessionPromptRepo{rows: []*types.AgentPrompt{
+ {
+ ID: "p1", SessionID: "s1", AssistantMessageID: "m1", UserID: caller.StorageID(),
+ Kind: types.AgentPromptKindToolApproval, ToolCallID: "call-1", Status: types.AgentPromptSuspended,
+ Request: types.JSON(`{"service_name":"svc"}`), ExpiresAt: &expires,
+ },
+ {
+ ID: "p2", SessionID: "s1", AssistantMessageID: "m2", UserID: "user:someone-else",
+ Kind: types.AgentPromptKindToolApproval, Status: types.AgentPromptSuspended,
+ },
+ }}
+ h := &MessageHandler{Prompts: repo}
+ ctx := types.WithPrincipal(context.Background(), caller)
+
+ awaiting := func(id string) *types.Message {
+ return &types.Message{ID: id, RunState: types.MessageRunStateAwaitingInput}
+ }
+ m1, m2, done := awaiting("m1"), awaiting("m2"), &types.Message{ID: "m3"}
+ h.attachPendingPrompts(ctx, "s1", []*types.Message{m1, m2, done})
+
+ require.NotNil(t, m1.PendingPrompt)
+ assert.Equal(t, "p1", m1.PendingPrompt.ID)
+ assert.Equal(t, "call-1", m1.PendingPrompt.ToolCallID)
+ assert.JSONEq(t, `{"service_name":"svc"}`, string(m1.PendingPrompt.Request))
+ assert.Equal(t, &expires, m1.PendingPrompt.ExpiresAt)
+ assert.Nil(t, m2.PendingPrompt, "another user's prompt stays hidden")
+ assert.Nil(t, done.PendingPrompt)
+
+ repo.calls = 0
+ h.attachPendingPrompts(ctx, "s1", []*types.Message{{ID: "m3"}})
+ assert.Zero(t, repo.calls, "no lookup without an awaiting message")
+}
diff --git a/internal/handler/sandbox_skill_test.go b/internal/handler/sandbox_skill_test.go
index 465215d2f..26898655f 100644
--- a/internal/handler/sandbox_skill_test.go
+++ b/internal/handler/sandbox_skill_test.go
@@ -1037,6 +1037,8 @@ func (m *transcriptStreamManager) ClearLiveRun(context.Context, string, string)
return nil
}
+func (m *transcriptStreamManager) ResetEvents(context.Context, string, string) error { return nil }
+
func (m *transcriptStreamManager) readKey() string {
m.mu.Lock()
defer m.mu.Unlock()
diff --git a/internal/handler/session/agent_stream_handler.go b/internal/handler/session/agent_stream_handler.go
index 762c16746..08581c36a 100644
--- a/internal/handler/session/agent_stream_handler.go
+++ b/internal/handler/session/agent_stream_handler.go
@@ -43,6 +43,9 @@ type AgentStreamHandler struct {
assistantMessage *types.Message
streamManager interfaces.StreamManager
completionEvent *interfaces.StreamEvent // Published only after the final message is persisted.
+ // suspension is set when the run ended waiting on a user prompt. The
+ // message then stays incomplete and the run is resumed later.
+ suspension *types.PromptSuspension
eventBus *event.EventBus
@@ -155,6 +158,31 @@ func (h *AgentStreamHandler) Subscribe() {
h.eventBus.On(event.EventToolApprovalResolved, h.handleToolApprovalResolved)
h.eventBus.On(event.EventMCPOAuthRequired, h.handleMCPOAuthRequired)
h.eventBus.On(event.EventMCPOAuthResolved, h.handleMCPOAuthResolved)
+ h.eventBus.On(event.EventAgentPromptRequired, h.handleAgentPromptEvent)
+ h.eventBus.On(event.EventAgentPromptResolved, h.handleAgentPromptEvent)
+}
+
+// handleAgentPromptEvent forwards generic prompt events to the SSE stream.
+func (h *AgentStreamHandler) handleAgentPromptEvent(_ context.Context, evt event.Event) error {
+ var responseType types.ResponseType
+ switch evt.Data.(type) {
+ case event.AgentPromptRequiredData:
+ responseType = types.ResponseTypeAgentPromptRequired
+ case event.AgentPromptResolvedData:
+ responseType = types.ResponseTypeAgentPromptResolved
+ default:
+ return nil
+ }
+ if err := h.streamManager.AppendEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{
+ ID: evt.ID,
+ Type: responseType,
+ Done: true,
+ Timestamp: time.Now(),
+ Data: toolApprovalDataToMap(evt.Data),
+ }); err != nil {
+ logger.GetLogger(h.ctx).Error("Append agent prompt event failed", "error", err)
+ }
+ return nil
}
// handleThought handles agent thought events
@@ -719,10 +747,21 @@ func (h *AgentStreamHandler) handleComplete(ctx context.Context, evt event.Event
h.mu.Lock()
defer h.mu.Unlock()
+ suspended, _ := data.Suspended.(*types.PromptSuspension)
+ h.suspension = suspended
+ if suspended != nil && suspended.Detached {
+ return nil
+ }
+
// Update assistant message with final data
if data.MessageID == h.assistantMessageID {
// h.assistantMessage.Content = data.FinalAnswer
- h.assistantMessage.IsCompleted = true
+ if suspended != nil {
+ h.assistantMessage.RunState = types.MessageRunStateAwaitingInput
+ } else {
+ h.assistantMessage.RunState = ""
+ h.assistantMessage.IsCompleted = true
+ }
h.assistantMessage.AgentDurationMs = data.TotalDurationMs
// Update knowledge references if provided
@@ -776,12 +815,13 @@ func (h *AgentStreamHandler) handleComplete(ctx context.Context, evt event.Event
// persisted without artifacts. Collect is a no-op when either the
// collector wasn't wired in, no sandbox is bound, or no files were
// produced — those cases must not disturb the completion path.
+ // A suspended run collects when its resumed run completes.
//
// Layouts without a separate output tree must not be collected
// (scanning Root would upload the whole project). Remote backends keep
// skills.ArtifactOutputDir(), or layout.OutputDir when advertised.
var previous types.MessageArtifacts
- if h.artifactCollector != nil {
+ if h.artifactCollector != nil && suspended == nil {
collectCtx := context.WithoutCancel(h.ctx)
var artifacts types.MessageArtifacts
if collectDir, skip := h.artifactCollector.CollectTarget(collectCtx, h.sessionID); !skip {
@@ -851,7 +891,7 @@ func (h *AgentStreamHandler) handleComplete(ctx context.Context, evt event.Event
// Fallback: if no answer events were streamed but we have a final answer,
// emit it as answer events so the frontend can render it properly.
// This guards against edge cases where the LLM stops without calling final_answer.
- if h.finalAnswer == "" && data.FinalAnswer != "" {
+ if suspended == nil && h.finalAnswer == "" && data.FinalAnswer != "" {
logger.GetLogger(h.ctx).Warnf(
"No answer events were streamed, emitting fallback answer (len=%d). "+
"This typically happens when: (1) model stopped naturally and content was sent as thought events, "+
@@ -915,6 +955,9 @@ func (h *AgentStreamHandler) handleComplete(ctx context.Context, evt event.Event
if data.ModelID != "" {
completeData["model_id"] = data.ModelID
}
+ if suspended != nil {
+ completeData["suspended"] = suspended
+ }
h.completionEvent = &interfaces.StreamEvent{
ID: evt.ID,
Type: types.ResponseTypeComplete,
@@ -937,6 +980,20 @@ func (h *AgentStreamHandler) publishCompletion(ctx context.Context) error {
if h.completionEvent == nil {
return nil
}
+ if s := h.suspension; s != nil {
+ if err := h.streamManager.AppendEvent(ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{
+ ID: "suspended-" + s.PromptID,
+ Type: types.ResponseTypeRunSuspended,
+ Timestamp: time.Now(),
+ Data: map[string]interface{}{
+ "pending_id": s.PromptID,
+ "kind": s.Kind,
+ "expires_at": s.ExpiresAt,
+ },
+ }); err != nil {
+ return err
+ }
+ }
if err := h.streamManager.AppendEvent(ctx, h.sessionID, h.assistantMessageID, *h.completionEvent); err != nil {
return err
}
@@ -944,6 +1001,14 @@ func (h *AgentStreamHandler) publishCompletion(ctx context.Context) error {
return nil
}
+// Suspension reports the prompt the run ended waiting on, or nil when the
+// run finished.
+func (h *AgentStreamHandler) Suspension() *types.PromptSuspension {
+ h.mu.Lock()
+ defer h.mu.Unlock()
+ return h.suspension
+}
+
// emitArtifactsPending tells the live UI that sandbox files exist and are
// being uploaded. It must not take h.mu — Collect calls it while
// handleComplete already holds the lock.
diff --git a/internal/handler/session/continue_stream_resource_urls_test.go b/internal/handler/session/continue_stream_resource_urls_test.go
index f8424512f..83f986b93 100644
--- a/internal/handler/session/continue_stream_resource_urls_test.go
+++ b/internal/handler/session/continue_stream_resource_urls_test.go
@@ -98,6 +98,8 @@ func (s *stubStreamManager) ClearLiveRun(context.Context, string, string) error
return nil
}
+func (s *stubStreamManager) ResetEvents(context.Context, string, string) error { return nil }
+
// completedAnswerStream is one assistant turn whose answer embeds a knowledge-base
// image, with the resource handle straddling two deltas as it does in production
// when the model-context decoder flushes mid-reference.
diff --git a/internal/handler/session/handler.go b/internal/handler/session/handler.go
index 811816aa8..a0644ec30 100644
--- a/internal/handler/session/handler.go
+++ b/internal/handler/session/handler.go
@@ -4,6 +4,7 @@ import (
stderrors "errors"
"net/http"
+ "github.com/Tencent/WeKnora/internal/agent/hitl"
"github.com/Tencent/WeKnora/internal/application/service"
"github.com/Tencent/WeKnora/internal/browserskill"
"github.com/Tencent/WeKnora/internal/config"
@@ -72,6 +73,10 @@ type Handler struct {
// validate CreateSession's optional project_dir. Nil means none are
// approved, so a non-empty project_dir is rejected.
approvedProjectDirs HostProjectDirsLoader
+ // promptBroker and suspendedRuns resume and supersede runs suspended on
+ // agent prompts. Nil leaves suspended prompts to the reaper.
+ promptBroker *hitl.Broker
+ suspendedRuns *service.SuspendedRunService
}
// NewHandler creates a new instance of Handler with all necessary dependencies
diff --git a/internal/handler/session/qa.go b/internal/handler/session/qa.go
index f46bc4b99..64e80cb22 100644
--- a/internal/handler/session/qa.go
+++ b/internal/handler/session/qa.go
@@ -99,13 +99,24 @@ type qaRequestContext struct {
// turnLeaseHeld records that executeQA already took the send-side turn
// lease for this request, so the QA service does not take a second one.
turnLeaseHeld bool
+ // resume continues a suspended run on assistantMessage instead of
+ // starting a turn.
+ resume *types.AgentResume
}
// buildQARequest converts the qaRequestContext into a types.QARequest for service invocation.
// steerSink rides along when the caller set one, so agent runs drain mid-run
// message injections at round boundaries.
+// calledWithAPIKey reports an X-API-Key caller; the prompt endpoints are
+// closed to API keys, so such a caller cannot answer a question.
+func calledWithAPIKey(ctx context.Context) bool {
+ _, ok := types.TenantAPIKeyScopeFromContext(ctx)
+ return ok
+}
+
func (rc *qaRequestContext) buildQARequest() *types.QARequest {
imageURLs, imageDescription := extractImageURLsAndOCRText(rc.images)
+ interactive := !calledWithAPIKey(rc.ctx)
req := &types.QARequest{
Session: rc.session,
Query: rc.query,
@@ -127,6 +138,11 @@ func (rc *qaRequestContext) buildQARequest() *types.QARequest {
Attachments: rc.attachments,
QuestionOrigin: rc.questionOrigin,
TurnLeaseHeld: rc.turnLeaseHeld,
+ // Only a caller that can answer the prompt later may leave the run
+ // suspended; an API-key caller would get a turn with no answer.
+ Suspendable: interactive,
+ Interactive: interactive,
+ Resume: rc.resume,
}
if rc.steerSink != nil {
req.SteerSink = rc.steerSink
@@ -806,6 +822,9 @@ func (h *Handler) setupSSEStream(reqCtx *qaRequestContext, generateTitle bool, m
reqCtx.userCreatedAt,
reqCtx.assistantMessage,
)
+ if reqCtx.resume != nil {
+ h.writeRunResumedEvent(reqCtx.ctx, reqCtx.sessionID, reqCtx.assistantMessage.ID, reqCtx.resume.Prompt.ID)
+ }
// Setup stop event handler
h.setupStopEventHandler(eventBus, reqCtx.sessionID, reqCtx.session.TenantID, reqCtx.assistantMessage, cancel)
@@ -1237,7 +1256,9 @@ func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitle
// This is a pure UI memo (no behavioural effect) and runs in a goroutine
// to avoid adding a DB round-trip to TTFB. Use WithoutCancel so a fast
// client disconnect doesn't drop the write.
- go h.persistLastRequestState(ctx, reqCtx, mode)
+ if reqCtx.resume == nil {
+ go h.persistLastRequestState(ctx, reqCtx, mode)
+ }
if mode == qaModeAgent {
if err := h.rejectIfOtherAgentRunLive(ctx, reqCtx); err != nil {
@@ -1257,6 +1278,11 @@ func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitle
}
return
}
+ // A new message moves on from any prompt still waiting for an answer.
+ // Its run is closed first so the history this turn loads is well formed.
+ if reqCtx.resume == nil {
+ h.supersedeSuspendedRuns(ctx, sessionID)
+ }
releaseQATurn, held := h.holdQATurn(ctx, reqCtx)
if !held {
@@ -1406,6 +1432,11 @@ func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitle
if streamCtx.releaseTurn != nil {
streamCtx.releaseTurn()
}
+ if streamCtx.streamHandler != nil {
+ if suspension := streamCtx.streamHandler.Suspension(); suspension != nil && suspension.Detached {
+ return // The new owner controls persistence and the live-run marker.
+ }
+ }
// Use WithoutCancel so a user-triggered stop (which cancels
// asyncCtx) doesn't also cancel the GORM UPDATE that persists
// AgentSteps/Content. Without this, cancelled-ctx makes
@@ -2013,7 +2044,23 @@ func (h *Handler) sessionTenantInfoContext(ctx context.Context) (context.Context
func (h *Handler) completeStreamAssistantMessage(
ctx context.Context, streamCtx *sseStreamContext, query, userMessageID string,
) {
- if err := h.completeAssistantMessage(ctx, streamCtx.assistantMessage, query, userMessageID); err != nil {
+ if streamCtx.streamHandler != nil {
+ if suspension := streamCtx.streamHandler.Suspension(); suspension != nil && suspension.Detached {
+ return
+ }
+ }
+ persist := func() error {
+ return h.completeAssistantMessage(ctx, streamCtx.assistantMessage, query, userMessageID)
+ }
+ if streamCtx.streamHandler != nil && streamCtx.streamHandler.Suspension() != nil {
+ // The turn is not over: indexing, memory and follow-ups run when the
+ // resumed run completes.
+ persist = func() error {
+ streamCtx.assistantMessage.UpdatedAt = time.Now()
+ return h.messageService.UpdateMessage(ctx, streamCtx.assistantMessage)
+ }
+ }
+ if err := persist(); err != nil {
if streamCtx.streamHandler != nil {
_ = streamCtx.streamHandler.handleError(ctx, event.Event{
ID: uuid.New().String(), Type: event.EventError, SessionID: streamCtx.assistantMessage.SessionID,
diff --git a/internal/handler/session/resume.go b/internal/handler/session/resume.go
new file mode 100644
index 000000000..60888e9e1
--- /dev/null
+++ b/internal/handler/session/resume.go
@@ -0,0 +1,334 @@
+package session
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/agent"
+ "github.com/Tencent/WeKnora/internal/agent/hitl"
+ "github.com/Tencent/WeKnora/internal/application/service"
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+ "github.com/gin-gonic/gin"
+)
+
+// SetSuspendedRuns wires what resuming and superseding suspended runs need.
+// Without it answers to suspended prompts are recorded but never resumed, and
+// new messages leave suspended prompts to expire.
+func (h *Handler) SetSuspendedRuns(broker *hitl.Broker, runs *service.SuspendedRunService) {
+ h.promptBroker, h.suspendedRuns = broker, runs
+}
+
+func (h *Handler) supersedeSuspendedRuns(ctx context.Context, sessionID string) {
+ if h.suspendedRuns == nil {
+ return
+ }
+ if _, err := h.suspendedRuns.SupersedeSession(context.WithoutCancel(ctx), sessionID); err != nil {
+ logger.Warnf(ctx, "supersede suspended runs of session %s: %v", sessionID, err)
+ }
+}
+
+// How long resuming waits for the run that suspended to finish tearing down,
+// and how often it looks. A run suspends its prompt before it has persisted
+// the message and released the session, so an answer can arrive first.
+var (
+ resumeSettleTimeout = 15 * time.Second
+ resumeSettleInterval = 250 * time.Millisecond
+)
+
+// ResumeSuspendedRun continues the run suspended on prompt, which c has just
+// answered, on this replica. It returns once the run has started; the run
+// streams to the message's event stream, where clients attach as they do to
+// any live run. ownerGone is hitl.Resolution.OwnerGone.
+func (h *Handler) ResumeSuspendedRun(
+ c *gin.Context, prompt *types.AgentPrompt, ownerGone bool, ownerLeaseUntil *time.Time,
+) {
+ if h.promptBroker == nil || h.suspendedRuns == nil {
+ return
+ }
+ ctx := logger.CloneContext(context.WithoutCancel(c.Request.Context()))
+ stopLease := h.promptBroker.KeepLease(ctx, prompt.ID, prompt.OwnerInstance)
+ if err := h.awaitSuspendedRunSettled(ctx, prompt, ownerGone, ownerLeaseUntil); err != nil {
+ stopLease()
+ logger.Errorf(ctx, "resume run of prompt %s: %v", prompt.ID, err)
+ state, _ := h.promptBroker.Suspensions().Get(ctx, prompt.AssistantMessageID)
+ if state != nil && state.PromptID != prompt.ID {
+ state = nil
+ }
+ h.abandonResume(ctx, prompt, state)
+ return
+ }
+ reqCtx, state, err := h.buildResumeRequest(ctx, c, prompt)
+ if err != nil {
+ stopLease()
+ logger.Errorf(ctx, "resume run of prompt %s: %v", prompt.ID, err)
+ h.abandonResume(ctx, prompt, state)
+ return
+ }
+ go func() {
+ defer stopLease()
+ defer func() {
+ if r := recover(); r != nil {
+ logger.Errorf(ctx, "resumed run of prompt %s panicked: %v", prompt.ID, r)
+ }
+ h.finishResume(ctx, prompt, state)
+ }()
+ h.executeQA(reqCtx, qaModeAgent, false)
+ }()
+}
+
+// awaitSuspendedRunSettled waits until the run that suspended on prompt has
+// let go of its message: the message is persisted as awaiting input and the
+// session's live-run marker no longer names it. Resuming earlier would race
+// that run's teardown, which rewrites the message and clears the marker the
+// resumed run sets. A marker left by an owner that is gone is cleared here,
+// since nothing else will.
+func (h *Handler) awaitSuspendedRunSettled(
+ ctx context.Context, prompt *types.AgentPrompt, ownerGone bool, ownerLeaseUntil *time.Time,
+) error {
+ deadline := time.Now().Add(resumeSettleTimeout)
+ if ownerLeaseUntil != nil && ownerLeaseUntil.After(deadline) {
+ deadline = *ownerLeaseUntil
+ }
+ for {
+ msg, err := h.messageService.GetMessage(ctx, prompt.SessionID, prompt.AssistantMessageID)
+ if err != nil {
+ return fmt.Errorf("load assistant message: %w", err)
+ }
+ if msg == nil || msg.IsCompleted {
+ return fmt.Errorf("assistant message is no longer open")
+ }
+ if msg.RunState != types.MessageRunStateAwaitingInput &&
+ (ownerGone || (ownerLeaseUntil != nil && time.Now().After(deadline))) {
+ // The waiter may have died after suspending the prompt but before
+ // persisting its message. Rebuild it from the durable snapshot.
+ if h.promptBroker == nil || h.suspendedRuns == nil {
+ return fmt.Errorf("suspended run recovery is unavailable")
+ }
+ state, err := h.promptBroker.Suspensions().Get(ctx, prompt.AssistantMessageID)
+ if err != nil {
+ return fmt.Errorf("read suspended run state: %w", err)
+ }
+ if state == nil || state.PromptID != prompt.ID {
+ return fmt.Errorf("no run state saved for prompt %s", prompt.ID)
+ }
+ if err := h.suspendedRuns.MarkAwaitingInput(ctx, prompt, state); err != nil {
+ return fmt.Errorf("restore suspended message: %w", err)
+ }
+ msg.RunState = types.MessageRunStateAwaitingInput
+ }
+ if msg.RunState == types.MessageRunStateAwaitingInput {
+ liveID, _, err := h.streamManager.GetLiveRun(ctx, prompt.SessionID)
+ if err != nil {
+ return fmt.Errorf("look up live run: %w", err)
+ }
+ if liveID != msg.ID {
+ return nil
+ }
+ if ownerGone || time.Now().After(deadline) {
+ if err := h.streamManager.ClearLiveRun(ctx, prompt.SessionID, msg.ID); err != nil {
+ return fmt.Errorf("clear stale live run: %w", err)
+ }
+ return nil
+ }
+ }
+ if time.Now().After(deadline) {
+ return fmt.Errorf("the suspended run did not finish within %s", resumeSettleTimeout)
+ }
+ time.Sleep(resumeSettleInterval)
+ }
+}
+
+// buildResumeRequest rebuilds the request of the suspended run from what it
+// saved. The returned state is non-nil whenever the run state could be read.
+func (h *Handler) buildResumeRequest(
+ ctx context.Context, c *gin.Context, prompt *types.AgentPrompt,
+) (*qaRequestContext, *types.AgentRunSuspension, error) {
+ state, err := h.promptBroker.Suspensions().Get(ctx, prompt.AssistantMessageID)
+ if err != nil {
+ return nil, nil, fmt.Errorf("read run state: %w", err)
+ }
+ if state == nil || state.PromptID != prompt.ID {
+ return nil, nil, fmt.Errorf("no run state saved for this prompt")
+ }
+ state.Snapshot, err = h.restoreResumeUserMessages(ctx, prompt.SessionID, state.Snapshot)
+ if err != nil {
+ return nil, state, err
+ }
+ var req types.ResumableAgentRequest
+ if err := decodeResumableRequest(state.Snapshot, &req); err != nil {
+ return nil, state, err
+ }
+ if req.Language != "" {
+ ctx = context.WithValue(ctx, types.LanguageContextKey, req.Language)
+ }
+
+ session, err := h.sessionService.GetSession(ctx, prompt.SessionID)
+ if err != nil || session == nil {
+ return nil, state, fmt.Errorf("load session: %v", err)
+ }
+ msg, err := h.messageService.GetMessage(ctx, prompt.SessionID, prompt.AssistantMessageID)
+ if err != nil || msg == nil {
+ return nil, state, fmt.Errorf("load assistant message: %v", err)
+ }
+ if msg.IsCompleted || msg.RunState != types.MessageRunStateAwaitingInput {
+ return nil, state, fmt.Errorf("assistant message is not awaiting input")
+ }
+ customAgent, effectiveTenantID, shared := h.resolveAgent(ctx, c, req.AgentID, sharedSourceTenant(session, req))
+ if customAgent == nil {
+ return nil, state, fmt.Errorf("agent %s is no longer available", req.AgentID)
+ }
+
+ // Mark the message as generating again before the run publishes itself
+ // as live: an awaiting message is not treated as a live run.
+ msg.RunState = ""
+ msg.UpdatedAt = time.Now()
+ if err := h.messageService.UpdateMessage(ctx, msg); err != nil {
+ return nil, state, fmt.Errorf("reopen assistant message: %w", err)
+ }
+ if err := h.streamManager.ResetEvents(ctx, prompt.SessionID, msg.ID); err != nil {
+ logger.Warnf(ctx, "reset events of message %s: %v", msg.ID, err)
+ }
+
+ // Steering messages must stay in the original assistant's history turn.
+ requestID := msg.RequestID
+ if requestID == "" {
+ requestID = prompt.RequestID
+ }
+ return &qaRequestContext{
+ ctx: ctx,
+ query: req.Query,
+ userInput: req.Query,
+ // The run outlives this request, and gin recycles its context.
+ c: c.Copy(),
+ sessionID: prompt.SessionID,
+ requestID: requestID,
+ receivedAt: time.Now(),
+ session: session,
+ customAgent: customAgent,
+ assistantMessage: msg,
+ knowledgeBaseIDs: req.KnowledgeBaseIDs,
+ knowledgeIDs: req.KnowledgeIDs,
+ tagScopes: req.TagScopes,
+ mcpServiceIDs: req.MCPServiceIDs,
+ skillNames: req.SkillNames,
+ summaryModelID: req.SummaryModelID,
+ reasoningEffort: req.ReasoningEffort,
+ webSearchEnabled: req.WebSearchEnabled,
+ effectiveTenantID: effectiveTenantID,
+ sharedAgentReadOnly: shared && req.SharedAgentReadOnly,
+ userMessageID: req.UserMessageID,
+ channel: msg.Channel,
+ questionOrigin: req.QuestionOrigin,
+ skipSSE: true,
+ resume: &types.AgentResume{Snapshot: state.Snapshot, Prompt: prompt},
+ }, state, nil
+}
+
+// sharedSourceTenant is the workspace to resolve a shared agent from, or 0
+// for the session's own agents.
+func sharedSourceTenant(session *types.Session, req types.ResumableAgentRequest) uint64 {
+ if req.AgentTenantID == 0 || req.AgentTenantID == session.TenantID {
+ return 0
+ }
+ return req.AgentTenantID
+}
+
+// finishResume closes what the resumed run left open: a prompt it never got
+// to act on, and the run state it no longer needs. A run that suspended
+// again saved state for its new prompt, which is kept.
+func (h *Handler) finishResume(ctx context.Context, prompt *types.AgentPrompt, state *types.AgentRunSuspension) {
+ row, err := h.promptBroker.Store().Get(ctx, prompt.ID)
+ if err == nil && row != nil && row.Status == types.AgentPromptAnswered {
+ // The message now belongs to the prompt the run suspended on again;
+ // closing it from the old state would complete it under that prompt.
+ if cur, _ := h.promptBroker.Suspensions().Get(ctx, prompt.AssistantMessageID); cur != nil &&
+ cur.PromptID != prompt.ID {
+ h.promptBroker.Fail(ctx, prompt.ID, hitl.ReasonResumeStopped)
+ return
+ }
+ h.abandonResume(ctx, prompt, state)
+ return
+ }
+ if err := h.promptBroker.Suspensions().Delete(ctx, prompt.AssistantMessageID, prompt.ID); err != nil {
+ logger.Warnf(ctx, "drop run state of message %s: %v", prompt.AssistantMessageID, err)
+ }
+}
+
+// abandonResume fails a prompt whose run could not be resumed and completes
+// its message, so it neither waits for the reaper nor stays open.
+func (h *Handler) abandonResume(ctx context.Context, prompt *types.AgentPrompt, state *types.AgentRunSuspension) {
+ h.promptBroker.Fail(ctx, prompt.ID, hitl.ReasonResumeStopped)
+ if state != nil {
+ if err := h.suspendedRuns.Close(ctx, prompt, state, hitl.ReasonResumeStopped); err != nil {
+ logger.Warnf(ctx, "close run of message %s: %v", prompt.AssistantMessageID, err)
+ }
+ }
+ if err := h.promptBroker.Suspensions().Delete(ctx, prompt.AssistantMessageID, prompt.ID); err != nil {
+ logger.Warnf(ctx, "drop run state of message %s: %v", prompt.AssistantMessageID, err)
+ }
+}
+
+func decodeResumableRequest(snapshot []byte, req *types.ResumableAgentRequest) error {
+ snap, err := agent.DecodeRunSnapshot(snapshot)
+ if err != nil {
+ return err
+ }
+ if len(snap.Request) == 0 {
+ return fmt.Errorf("run state carries no request")
+ }
+ if err := json.Unmarshal(snap.Request, req); err != nil {
+ return fmt.Errorf("decode saved request: %w", err)
+ }
+ if req.Query == "" {
+ // Snapshots written before Query was included in the request.
+ req.Query = snap.Query
+ }
+ return nil
+}
+
+// Older snapshots retained steering boundaries but not their text. Resolve
+// those IDs from the same session before replaying, including the pending round.
+func (h *Handler) restoreResumeUserMessages(
+ ctx context.Context, sessionID string, snapshot []byte,
+) (types.JSON, error) {
+ snap, err := agent.DecodeRunSnapshot(snapshot)
+ if err != nil {
+ return nil, err
+ }
+ if snap.UserMessages == nil {
+ snap.UserMessages = make(map[string]string)
+ }
+ steps := append(append([]types.AgentStep(nil), snap.CompletedSteps...), snap.PendingRound.Step)
+ for _, step := range steps {
+ for _, id := range step.UserMessagesBefore {
+ if _, ok := snap.UserMessages[id]; ok {
+ continue
+ }
+ msg, err := h.messageService.GetMessage(ctx, sessionID, id)
+ if err != nil {
+ return nil, fmt.Errorf("load steered message %s: %w", id, err)
+ }
+ if msg == nil || msg.Role != "user" || msg.SessionID != sessionID {
+ return nil, fmt.Errorf("steered message %s is not a user message of this session", id)
+ }
+ snap.UserMessages[id] = msg.Content
+ }
+ }
+ data, err := json.Marshal(snap)
+ return types.JSON(data), err
+}
+
+func (h *Handler) writeRunResumedEvent(ctx context.Context, sessionID, messageID, promptID string) {
+ if err := h.streamManager.AppendEvent(ctx, sessionID, messageID, interfaces.StreamEvent{
+ ID: "resumed-" + promptID,
+ Type: types.ResponseTypeRunResumed,
+ Timestamp: time.Now(),
+ Data: map[string]interface{}{"pending_id": promptID},
+ }); err != nil {
+ logger.Warnf(ctx, "append run_resumed of message %s: %v", messageID, err)
+ }
+}
diff --git a/internal/handler/session/resume_context_test.go b/internal/handler/session/resume_context_test.go
new file mode 100644
index 000000000..b0b11ad47
--- /dev/null
+++ b/internal/handler/session/resume_context_test.go
@@ -0,0 +1,118 @@
+package session
+
+import (
+ "context"
+ "encoding/json"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/agent"
+ "github.com/Tencent/WeKnora/internal/agent/hitl"
+ "github.com/Tencent/WeKnora/internal/application/service"
+ "github.com/Tencent/WeKnora/internal/stream"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+ "github.com/stretchr/testify/require"
+)
+
+type resumeMessages struct {
+ interfaces.MessageService
+ rows map[string]*types.Message
+}
+
+func (m *resumeMessages) GetMessage(_ context.Context, sessionID, id string) (*types.Message, error) {
+ row := m.rows[id]
+ if row == nil || row.SessionID != sessionID {
+ return nil, nil
+ }
+ cloned := *row
+ return &cloned, nil
+}
+
+func (m *resumeMessages) UpdateMessage(_ context.Context, row *types.Message) error {
+ cloned := *row
+ m.rows[row.ID] = &cloned
+ return nil
+}
+
+type resumeMessageRepo struct {
+ interfaces.MessageRepository
+ messages *resumeMessages
+}
+
+type resumeSessionService struct{ interfaces.SessionService }
+
+func (*resumeSessionService) GetSession(_ context.Context, id string) (*types.Session, error) {
+ return &types.Session{ID: id, TenantID: 1}, nil
+}
+
+func (r *resumeMessageRepo) GetMessage(ctx context.Context, sessionID, id string) (*types.Message, error) {
+ return r.messages.GetMessage(ctx, sessionID, id)
+}
+
+func (r *resumeMessageRepo) UpdateMessage(ctx context.Context, m *types.Message) error {
+ return r.messages.UpdateMessage(ctx, m)
+}
+
+func TestBuildResumeRequestKeepsTurnAndRestoresLegacySteering(t *testing.T) {
+ c, ctx := newResolveAgentTestContext(1)
+ messages := &resumeMessages{rows: map[string]*types.Message{
+ "m": {ID: "m", SessionID: "sess-1", RequestID: "original-turn", RunState: types.MessageRunStateAwaitingInput},
+ "u": {ID: "u", SessionID: "sess-1", Role: "user", Content: "use staging"},
+ }}
+ b := hitl.NewBroker(nil, nil)
+ request, err := json.Marshal(types.ResumableAgentRequest{AgentID: "a", UserMessageID: "first"})
+ require.NoError(t, err)
+ snapshot, err := json.Marshal(agent.RunSnapshot{
+ Version: agent.RunSnapshotVersion, Query: "original question", Request: request,
+ PendingRound: agent.PendingRound{Step: types.AgentStep{UserMessagesBefore: []string{"u"}}},
+ })
+ require.NoError(t, err)
+ require.NoError(t, b.Suspensions().Save(ctx, &types.AgentRunSuspension{
+ AssistantMessageID: "m", PromptID: "p", Snapshot: types.JSON(snapshot),
+ }))
+ h := &Handler{
+ promptBroker: b, messageService: messages, streamManager: stream.NewMemoryStreamManager(),
+ sessionService: &resumeSessionService{},
+ customAgentService: &resolveOwnAgentStub{agent: &types.CustomAgent{ID: "a"}},
+ }
+ req, _, err := h.buildResumeRequest(ctx, c, &types.AgentPrompt{
+ ID: "p", SessionID: "sess-1", AssistantMessageID: "m", RequestID: "transport",
+ })
+ require.NoError(t, err)
+ require.Equal(t, "original question", req.query)
+ require.Equal(t, req.query, req.userInput)
+ require.Equal(t, "original-turn", req.requestID)
+ require.Equal(t, "original question", req.buildQARequest().Query)
+ snap, err := agent.DecodeRunSnapshot(req.resume.Snapshot)
+ require.NoError(t, err)
+ require.Equal(t, "use staging", snap.UserMessages["u"])
+}
+
+func TestResumeRecoversOwnerThatDiedBeforeSavingMessage(t *testing.T) {
+ for _, ownerGone := range []bool{true, false} {
+ t.Run(map[bool]string{true: "reaped", false: "self-suspended"}[ownerGone], func(t *testing.T) {
+ shortResumeSettle(t, 20*time.Millisecond)
+ ctx := t.Context()
+ messages := &resumeMessages{rows: map[string]*types.Message{"m": {ID: "m", SessionID: "s"}}}
+ b := hitl.NewBroker(nil, nil)
+ require.NoError(t, b.Suspensions().Save(ctx, &types.AgentRunSuspension{
+ AssistantMessageID: "m", PromptID: "p1",
+ Snapshot: types.JSON(`{"version":1,"completed_steps":[{"thought":"saved work"}]}`),
+ }))
+ mgr := stream.NewMemoryStreamManager()
+ require.NoError(t, mgr.SetLiveRun(ctx, "s", "m", "old"))
+ h := &Handler{
+ messageService: messages, promptBroker: b, streamManager: mgr,
+ suspendedRuns: service.NewSuspendedRunService(b, &resumeMessageRepo{messages: messages}),
+ }
+ past := time.Now().Add(-time.Second)
+ require.NoError(t, h.awaitSuspendedRunSettled(ctx, settlePrompt, ownerGone, &past))
+ require.Equal(t, types.MessageRunStateAwaitingInput, messages.rows["m"].RunState)
+ require.Equal(t, "saved work", messages.rows["m"].AgentSteps[0].Thought)
+ live, _, err := mgr.GetLiveRun(ctx, "s")
+ require.NoError(t, err)
+ require.Empty(t, live)
+ })
+ }
+}
diff --git a/internal/handler/session/resume_settle_test.go b/internal/handler/session/resume_settle_test.go
new file mode 100644
index 000000000..129b9d01f
--- /dev/null
+++ b/internal/handler/session/resume_settle_test.go
@@ -0,0 +1,86 @@
+package session
+
+import (
+ "context"
+ "sync"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/stream"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+ "github.com/stretchr/testify/require"
+)
+
+type settleMessages struct {
+ interfaces.MessageService
+ mu sync.Mutex
+ msg types.Message
+}
+
+func (s *settleMessages) GetMessage(context.Context, string, string) (*types.Message, error) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ m := s.msg
+ return &m, nil
+}
+
+func (s *settleMessages) set(f func(*types.Message)) {
+ s.mu.Lock()
+ defer s.mu.Unlock()
+ f(&s.msg)
+}
+
+func shortResumeSettle(t *testing.T, timeout time.Duration) {
+ prevTimeout, prevInterval := resumeSettleTimeout, resumeSettleInterval
+ resumeSettleTimeout, resumeSettleInterval = timeout, 10*time.Millisecond
+ t.Cleanup(func() { resumeSettleTimeout, resumeSettleInterval = prevTimeout, prevInterval })
+}
+
+var settlePrompt = &types.AgentPrompt{ID: "p1", SessionID: "s", AssistantMessageID: "m"}
+
+// An answer that lands while the suspending run is still tearing down waits
+// for it to persist the message and release the session.
+func TestResumeWaitsForSuspendingRunToFinish(t *testing.T) {
+ shortResumeSettle(t, 5*time.Second)
+ mgr := stream.NewMemoryStreamManager()
+ require.NoError(t, mgr.SetLiveRun(t.Context(), "s", "m", "req"))
+ messages := &settleMessages{msg: types.Message{ID: "m", SessionID: "s"}}
+ h := &Handler{messageService: messages, streamManager: mgr}
+
+ go func() {
+ time.Sleep(50 * time.Millisecond)
+ messages.set(func(m *types.Message) { m.RunState = types.MessageRunStateAwaitingInput })
+ time.Sleep(50 * time.Millisecond)
+ _ = mgr.ClearLiveRun(context.Background(), "s", "m")
+ }()
+
+ start := time.Now()
+ require.NoError(t, h.awaitSuspendedRunSettled(t.Context(), settlePrompt, false, nil))
+ require.GreaterOrEqual(t, time.Since(start), 100*time.Millisecond)
+}
+
+func TestResumeClearsMarkerLeftByVanishedOwner(t *testing.T) {
+ shortResumeSettle(t, 5*time.Second)
+ mgr := stream.NewMemoryStreamManager()
+ require.NoError(t, mgr.SetLiveRun(t.Context(), "s", "m", "req"))
+ messages := &settleMessages{msg: types.Message{
+ ID: "m", SessionID: "s", RunState: types.MessageRunStateAwaitingInput,
+ }}
+ h := &Handler{messageService: messages, streamManager: mgr}
+
+ require.NoError(t, h.awaitSuspendedRunSettled(t.Context(), settlePrompt, true, nil))
+ live, _, err := mgr.GetLiveRun(t.Context(), "s")
+ require.NoError(t, err)
+ require.Empty(t, live)
+}
+
+func TestResumeGivesUpOnMessageThatNeverSettles(t *testing.T) {
+ shortResumeSettle(t, 60*time.Millisecond)
+ messages := &settleMessages{msg: types.Message{ID: "m", SessionID: "s"}}
+ h := &Handler{messageService: messages, streamManager: stream.NewMemoryStreamManager()}
+ require.Error(t, h.awaitSuspendedRunSettled(t.Context(), settlePrompt, false, nil))
+
+ messages.set(func(m *types.Message) { m.IsCompleted = true })
+ require.Error(t, h.awaitSuspendedRunSettled(t.Context(), settlePrompt, true, nil))
+}
diff --git a/internal/handler/session/steer.go b/internal/handler/session/steer.go
index 3575be42d..e0a1be232 100644
--- a/internal/handler/session/steer.go
+++ b/internal/handler/session/steer.go
@@ -357,7 +357,7 @@ func (h *Handler) liveAgentRun(ctx context.Context, sessionID string) (string, e
if err != nil {
return "", err
}
- if msg == nil || msg.IsCompleted {
+ if msg == nil || msg.IsCompleted || msg.RunState == types.MessageRunStateAwaitingInput {
if err := h.streamManager.ClearLiveRun(ctx, sessionID, assistantID); err != nil {
logger.Warnf(ctx, "stale live run cleanup failed for session %s: %v", sessionID, err)
}
@@ -947,6 +947,8 @@ func (h *Handler) claimNextSteerFollowUp(
prevReqCtx.sessionID, len(backlog), len(injected))
followUp := *prevReqCtx
+ // A queued message starts a new turn, never another replay of this one.
+ followUp.resume = nil
followUp.ctx = ctx
followUp.query = first.Content
followUp.userInput = first.Content
diff --git a/internal/handler/session/steer_live_run_test.go b/internal/handler/session/steer_live_run_test.go
index 18b007cac..e65fb7e79 100644
--- a/internal/handler/session/steer_live_run_test.go
+++ b/internal/handler/session/steer_live_run_test.go
@@ -264,12 +264,14 @@ func TestSteerFollowUpHandoffKeepsSessionLiveAcrossPreviousClear(t *testing.T) {
prev := &qaRequestContext{
sessionID: "sess-1",
session: &types.Session{ID: "sess-1"},
+ resume: &types.AgentResume{Snapshot: []byte(`{"version":1}`)},
}
streamCtx := &sseStreamContext{assistantMessage: &types.Message{ID: "assist-A"}}
followUp, ok := h.claimNextSteerFollowUp(ctx, prev, streamCtx)
require.True(t, ok)
require.NotNil(t, followUp)
+ require.Nil(t, followUp.buildQARequest().Resume)
assert.Equal(t, "do this next", followUp.query)
assert.Equal(t, "do this next", msgs.byID[followUp.userMessageID].Content)
require.NotEmpty(t, followUp.assistantMessage.ID)
diff --git a/internal/handler/session/suspended_completion_test.go b/internal/handler/session/suspended_completion_test.go
new file mode 100644
index 000000000..480a66be3
--- /dev/null
+++ b/internal/handler/session/suspended_completion_test.go
@@ -0,0 +1,81 @@
+package session
+
+import (
+ "context"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+)
+
+func TestSuspendedRunIsSavedIncompleteAndAnnounced(t *testing.T) {
+ messages := &imageCompletionMessages{}
+ stream := &imageCompletionStream{}
+ h := &Handler{messageService: messages, streamManager: stream}
+ bus := event.NewEventBus()
+ message := &types.Message{ID: "m", SessionID: "s", Role: "assistant"}
+ ctx := types.WithExecutionTenant(context.Background(), 1)
+ streamHandler := h.setupStreamHandler(ctx, "s", "m", "req", 1, time.Now(), message, bus)
+
+ expires := time.Now().Add(time.Hour)
+ suspension := &types.PromptSuspension{
+ PromptID: "p1", Kind: types.AgentPromptKindToolApproval, ExpiresAt: &expires,
+ }
+ steps := []types.AgentStep{{Iteration: 0, Thought: "checking first", ToolCalls: []types.ToolCall{
+ {ID: "call-a", Name: "first_tool", Result: &types.ToolResult{Success: true, Output: "ok"}},
+ }}}
+ require.NoError(t, bus.Emit(ctx, event.Event{
+ ID: "complete-1",
+ Type: event.EventAgentComplete,
+ Data: event.AgentCompleteData{
+ MessageID: "m", FinalAnswer: "must not be shown", AgentSteps: steps, Suspended: suspension,
+ },
+ }))
+ require.Equal(t, suspension, streamHandler.Suspension())
+ require.Empty(t, stream.events, "nothing is announced before the message is saved")
+
+ h.completeStreamAssistantMessage(ctx, &sseStreamContext{
+ eventBus: bus, streamHandler: streamHandler, assistantMessage: message,
+ }, "the question", "u1")
+
+ require.NotNil(t, messages.saved)
+ require.False(t, messages.saved.IsCompleted)
+ require.Equal(t, types.MessageRunStateAwaitingInput, messages.saved.RunState)
+ require.Len(t, messages.saved.AgentSteps, 1)
+
+ require.Len(t, stream.events, 2, "no fallback answer for a suspended run")
+ announced := stream.events[0]
+ require.Equal(t, types.ResponseTypeRunSuspended, announced.Type)
+ require.Equal(t, "p1", announced.Data["pending_id"])
+ require.Equal(t, types.AgentPromptKindToolApproval, announced.Data["kind"])
+ require.Equal(t, &expires, announced.Data["expires_at"])
+
+ complete := stream.events[1]
+ require.Equal(t, types.ResponseTypeComplete, complete.Type)
+ require.True(t, complete.Done)
+ require.Equal(t, suspension, complete.Data["suspended"])
+}
+
+func TestDetachedRunDoesNotOverwriteOrAnnounceCompletion(t *testing.T) {
+ messages := &imageCompletionMessages{}
+ stream := &imageCompletionStream{}
+ h := &Handler{messageService: messages, streamManager: stream}
+ bus := event.NewEventBus()
+ message := &types.Message{ID: "m", SessionID: "s", Role: "assistant", Content: "original"}
+ ctx := types.WithExecutionTenant(t.Context(), 1)
+ handler := h.setupStreamHandler(ctx, "s", "m", "req", 1, time.Now(), message, bus)
+ suspension := &types.PromptSuspension{PromptID: "p", Detached: true}
+ require.NoError(t, bus.Emit(ctx, event.Event{
+ Type: event.EventAgentComplete,
+ Data: event.AgentCompleteData{MessageID: "m", FinalAnswer: "stale result", Suspended: suspension},
+ }))
+ h.completeStreamAssistantMessage(ctx, &sseStreamContext{
+ eventBus: bus, streamHandler: handler, assistantMessage: message,
+ }, "question", "u")
+ require.Equal(t, "original", message.Content)
+ require.False(t, message.IsCompleted)
+ require.Nil(t, messages.saved)
+ require.Empty(t, stream.events)
+}
diff --git a/internal/im/tool_display.go b/internal/im/tool_display.go
index ff33d989f..266021e2d 100644
--- a/internal/im/tool_display.go
+++ b/internal/im/tool_display.go
@@ -44,6 +44,7 @@ var imToolNameLabels = map[string]string{
"wiki_read_page": "Wiki 阅读",
"wiki_read_source_doc": "精读源文档",
"todo_write": "计划管理",
+ "ask_user": "向用户提问",
"knowledge_graph_extract": "知识图谱抽取",
"thinking": "思考",
"image_analysis": "查看图片内容",
diff --git a/internal/modelcontext/tool_policy.go b/internal/modelcontext/tool_policy.go
index 38c9699ed..0ef6b8a63 100644
--- a/internal/modelcontext/tool_policy.go
+++ b/internal/modelcontext/tool_policy.go
@@ -174,6 +174,7 @@ var toolHandlePolicies = map[string]toolHandlePolicy{
// never structured source rendering.
"thinking": {},
"todo_write": {},
+ "ask_user": {},
// Skill output is user-authored content of unknown shape. Compact known
// durable IDs, but do not mine it for source keys: a skill's JSON may use
// "url"/"knowledge_id" with unrelated semantics.
diff --git a/internal/router/routes_agent.go b/internal/router/routes_agent.go
index c495a47bd..425bf0131 100644
--- a/internal/router/routes_agent.go
+++ b/internal/router/routes_agent.go
@@ -256,6 +256,7 @@ func RegisterEmbedPublicRoutes(
embed.POST("/sessions/:session_id/mcp-services/:id/oauth/authorize-url", embedHandler.EmbedMCPOAuthAuthorizeURL)
embed.GET("/sessions/:session_id/mcp-services/:id/oauth/status", embedHandler.EmbedMCPOAuthStatus)
embed.POST("/sessions/:session_id/tool-approvals/:pending_id", embedHandler.EmbedResolveToolApproval)
+ embed.POST("/sessions/:session_id/prompts/:prompt_id", embedHandler.EmbedResolveAgentPrompt)
// Serve images embedded in bot replies (e.g. chart exports). EmbedAuth
// injects the channel's tenant, and the handler enforces that the
// requested path belongs to that tenant.
diff --git a/internal/router/routes_infra.go b/internal/router/routes_infra.go
index 898b41459..5e542f1dd 100644
--- a/internal/router/routes_infra.go
+++ b/internal/router/routes_infra.go
@@ -201,6 +201,8 @@ func RegisterMCPServiceRoutes(
// people who actually have context to approve, so the gate is
// kept at "anyone in the tenant" instead.
agentTool.POST("/tool-approvals/:pending_id", g.Viewer(), handler.ResolveToolApproval)
+ // Answer any user-answerable prompt (ask_user, tool approval); same gating.
+ agentTool.POST("/prompts/:prompt_id", g.Viewer(), handler.ResolveAgentPrompt)
// Resume an agent run paused on an in-conversation MCP OAuth prompt.
// Same tenant-member (Viewer+) gating rationale as tool-approvals.
agentTool.POST("/mcp-oauth-resolutions/:pending_id", g.Viewer(), oauthHandler.ResolveMCPOAuth)
diff --git a/internal/stream/memory_manager.go b/internal/stream/memory_manager.go
index 3f1be193d..0b51f129f 100644
--- a/internal/stream/memory_manager.go
+++ b/internal/stream/memory_manager.go
@@ -94,6 +94,19 @@ func (m *MemoryStreamManager) AppendEvent(
return nil
}
+// ResetEvents drops the message's events, keeping its steer events.
+func (m *MemoryStreamManager) ResetEvents(_ context.Context, sessionID, messageID string) error {
+ stream := m.getStream(sessionID, messageID)
+ if stream == nil {
+ return nil
+ }
+ stream.mu.Lock()
+ defer stream.mu.Unlock()
+ stream.events = make([]interfaces.StreamEvent, 0)
+ stream.lastUpdated = time.Now()
+ return nil
+}
+
// GetEvents gets events starting from offset
// Returns: events slice, next offset, error
func (m *MemoryStreamManager) GetEvents(
diff --git a/internal/stream/redis_live_run_test.go b/internal/stream/redis_live_run_test.go
index b5285b851..883762c82 100644
--- a/internal/stream/redis_live_run_test.go
+++ b/internal/stream/redis_live_run_test.go
@@ -222,3 +222,33 @@ func TestRedisDropMessageStreamsRemovesEventsSteerAndLiveRun(t *testing.T) {
require.NoError(t, err)
require.Empty(t, liveID)
}
+
+func TestResetEventsDropsEventsAndKeepsSteer(t *testing.T) {
+ redisManager, _ := newTestRedisStreamManager(t, time.Hour)
+ for name, manager := range map[string]interfaces.StreamManager{
+ "memory": NewMemoryStreamManager(), "redis": redisManager,
+ } {
+ t.Run(name, func(t *testing.T) {
+ ctx := context.Background()
+ require.NoError(t, manager.AppendEvent(ctx, "session", "run",
+ interfaces.StreamEvent{ID: "old", Content: "before"}))
+ require.NoError(t, manager.AppendSteerEvents(ctx, "session", "run",
+ []interfaces.StreamEvent{{ID: "steer-1", Content: "next"}}))
+
+ require.NoError(t, manager.ResetEvents(ctx, "session", "run"))
+ events, _, err := manager.GetEvents(ctx, "session", "run", 0)
+ require.NoError(t, err)
+ require.Empty(t, events)
+ steer, _, err := manager.GetSteerEvents(ctx, "session", "run", 0)
+ require.NoError(t, err)
+ require.Len(t, steer, 1)
+
+ require.NoError(t, manager.AppendEvent(ctx, "session", "run",
+ interfaces.StreamEvent{ID: "new", Content: "after"}))
+ events, _, err = manager.GetEvents(ctx, "session", "run", 0)
+ require.NoError(t, err)
+ require.Len(t, events, 1)
+ require.Equal(t, "new", events[0].ID)
+ })
+ }
+}
diff --git a/internal/stream/redis_manager.go b/internal/stream/redis_manager.go
index 4e0191ac4..4c6a48ebe 100644
--- a/internal/stream/redis_manager.go
+++ b/internal/stream/redis_manager.go
@@ -101,6 +101,14 @@ func (r *RedisStreamManager) AppendEvent(
return nil
}
+// ResetEvents deletes the message's event list.
+func (r *RedisStreamManager) ResetEvents(ctx context.Context, sessionID, messageID string) error {
+ if err := r.client.Del(ctx, r.buildKey(sessionID, messageID)).Err(); err != nil {
+ return fmt.Errorf("failed to reset stream events: %w", err)
+ }
+ return nil
+}
+
// GetEvents gets events starting from offset using Redis LRange
// Returns: events slice, next offset, error
func (r *RedisStreamManager) GetEvents(
diff --git a/internal/types/agent.go b/internal/types/agent.go
index cbbf07164..05b57c839 100644
--- a/internal/types/agent.go
+++ b/internal/types/agent.go
@@ -389,6 +389,9 @@ type ToolResult struct {
// model asked to read Images when it cannot view them. Live only.
ImageDetail string `json:"-"`
ImageFocus string `json:"-"`
+ // Suspend, when set, means the call did not run: it is waiting on a user
+ // prompt and the run must end so it can be resumed later. Live only.
+ Suspend *PromptSuspension `json:"-"`
}
// Image description detail levels requested by a file read.
@@ -503,6 +506,11 @@ type AgentState struct {
FinalAnswer string `json:"final_answer"` // The final answer to the query
KnowledgeRefs []*SearchResult `json:"knowledge_refs"` // Collected knowledge references
TurnUsage TokenUsage `json:"turn_usage"` // LLM usage accumulated across this turn
+ // Suspended is set when the run ended waiting on a user prompt.
+ // SuspendedStep is the interrupted round: its thought and the calls
+ // that finished before the blocked one, kept for display.
+ Suspended *PromptSuspension `json:"-"`
+ SuspendedStep *AgentStep `json:"-"`
}
// FunctionDefinition represents a function definition for LLM function calling
diff --git a/internal/types/agent_prompt.go b/internal/types/agent_prompt.go
new file mode 100644
index 000000000..4ee470540
--- /dev/null
+++ b/internal/types/agent_prompt.go
@@ -0,0 +1,194 @@
+package types
+
+import (
+ "encoding/json"
+ "time"
+
+ "github.com/google/uuid"
+ "gorm.io/gorm"
+)
+
+// Kinds of human-in-the-loop prompts an agent run can raise.
+const (
+ AgentPromptKindToolApproval = "tool_approval"
+ AgentPromptKindMCPOAuth = "mcp_oauth"
+ AgentPromptKindAskUser = "ask_user"
+)
+
+// Lifecycle states of an AgentPrompt. Transitions are compare-and-set on the
+// row, so every replica agrees on a single outcome.
+const (
+ // AgentPromptPending: an owner replica is blocked waiting in memory.
+ AgentPromptPending = "pending"
+ // AgentPromptSuspended: the run ended; an answer will resume it.
+ AgentPromptSuspended = "suspended"
+ // AgentPromptAnswered: the user responded; Response holds the answer.
+ AgentPromptAnswered = "answered"
+ // AgentPromptExecuting: the answer authorized a side effect that is
+ // running; it must not be replayed if the executor disappears.
+ AgentPromptExecuting = "executing"
+ AgentPromptDone = "done"
+ AgentPromptFailed = "failed"
+ AgentPromptCanceled = "canceled"
+ AgentPromptExpired = "expired"
+ // AgentPromptSuperseded: the user moved on (new message, rewind,
+ // deletion) while the prompt was suspended.
+ AgentPromptSuperseded = "superseded"
+)
+
+// AgentPrompt is one prompt raised by an agent run. Kind decides the shape of
+// Request and Response; the row is the source of truth for the answer and
+// process memory only holds a wake-up hook.
+type AgentPrompt struct {
+ ID string `json:"id" gorm:"type:varchar(36);primaryKey"`
+ TenantID uint64 `json:"tenant_id" gorm:"not null"`
+ UserID string `json:"user_id" gorm:"type:varchar(64);not null;default:''"`
+ SessionID string `json:"session_id" gorm:"type:varchar(36);not null"`
+ AssistantMessageID string `json:"assistant_message_id" gorm:"type:varchar(36);not null;default:''"`
+ RequestID string `json:"request_id" gorm:"type:varchar(128);not null;default:''"`
+ Kind string `json:"kind" gorm:"type:varchar(32);not null"`
+ ToolCallID string `json:"tool_call_id" gorm:"type:varchar(255);not null;default:''"`
+ // Suspendable prompts may outlive the run that raised them. Prompts raised
+ // while an external operation is in flight cannot.
+ Suspendable bool `json:"suspendable" gorm:"not null;default:false"`
+ Request JSON `json:"request,omitempty"`
+ Response JSON `json:"response,omitempty"`
+ Status string `json:"status" gorm:"type:varchar(32);not null"`
+ // CloseReason explains a system-side ending (timeout, cancel, supersede).
+ CloseReason string `json:"close_reason" gorm:"type:text;not null;default:''"`
+ ResolvedBy string `json:"resolved_by" gorm:"type:varchar(64);not null;default:''"`
+ ResolvedAt *time.Time `json:"resolved_at,omitempty"`
+ OwnerInstance string `json:"owner_instance" gorm:"type:varchar(64);not null;default:''"`
+ LeaseUntil *time.Time `json:"lease_until,omitempty"`
+ ExpiresAt *time.Time `json:"expires_at,omitempty"`
+ CreatedAt time.Time `json:"created_at"`
+ UpdatedAt time.Time `json:"updated_at"`
+}
+
+// TableName pins the table name.
+func (AgentPrompt) TableName() string { return "agent_prompts" }
+
+// BeforeCreate sets ID for AgentPrompt.
+func (p *AgentPrompt) BeforeCreate(_ *gorm.DB) error {
+ if p.ID == "" {
+ p.ID = uuid.New().String()
+ }
+ return nil
+}
+
+// IsOpen reports whether the prompt still waits for an answer.
+func (p *AgentPrompt) IsOpen() bool {
+ return p != nil && (p.Status == AgentPromptPending || p.Status == AgentPromptSuspended)
+}
+
+// AgentPromptTransition is a compare-and-set update applied only when the
+// row is in one of the From states. Nil / empty fields are left unchanged.
+type AgentPromptTransition struct {
+ From []string
+ To string
+ Response JSON
+ CloseReason *string
+ ResolvedBy *string
+ ResolvedAt *time.Time
+ ExpiresAt *time.Time
+ // Owner and LeaseUntil hand the row to a new owner replica.
+ Owner *string
+ LeaseUntil *time.Time
+ // UnexpiredAt additionally requires the row not to have expired at that
+ // time (expires_at empty or later).
+ UnexpiredAt *time.Time
+ // ExpectedOwner and LeaseBefore fence a stale reader against a takeover
+ // or renewal between reading the row and updating it.
+ ExpectedOwner *string
+ LeaseBefore *time.Time
+}
+
+// AgentRunSuspension is the persisted state of a run blocked on a prompt, so
+// any replica can resume it once the prompt is answered. Snapshot is opaque
+// outside the agent engine and versioned by SnapshotVersion.
+type AgentRunSuspension struct {
+ AssistantMessageID string `json:"assistant_message_id" gorm:"type:varchar(36);primaryKey"`
+ TenantID uint64 `json:"tenant_id" gorm:"not null"`
+ SessionID string `json:"session_id" gorm:"type:varchar(36);not null"`
+ PromptID string `json:"prompt_id" gorm:"type:varchar(36);not null"`
+ SnapshotVersion int `json:"snapshot_version" gorm:"not null"`
+ Snapshot JSON `json:"snapshot" gorm:"not null"`
+ CreatedAt time.Time `json:"created_at"`
+ UpdatedAt time.Time `json:"updated_at"`
+}
+
+// TableName pins the table name.
+func (AgentRunSuspension) TableName() string { return "agent_run_suspensions" }
+
+// PromptSuspension describes a run that ended waiting on a prompt.
+type PromptSuspension struct {
+ // Detached is runtime-only: another owner already controls the message.
+ Detached bool `json:"-"`
+ PromptID string `json:"pending_id"`
+ Kind string `json:"kind"`
+ ExpiresAt *time.Time `json:"expires_at,omitempty"`
+}
+
+// PendingPromptView is what a client needs to render and answer a suspended
+// prompt when it reloads the conversation.
+type PendingPromptView struct {
+ ID string `json:"id"`
+ Kind string `json:"kind"`
+ ToolCallID string `json:"tool_call_id"`
+ Request JSON `json:"request,omitempty"`
+ ExpiresAt *time.Time `json:"expires_at,omitempty"`
+ CreatedAt time.Time `json:"created_at"`
+}
+
+// ResumableAgentRequest is the part of a QARequest needed to rebuild the run
+// on another replica. It holds the original query and durable request settings.
+type ResumableAgentRequest struct {
+ AgentID string `json:"agent_id"`
+ Query string `json:"query,omitempty"`
+ // AgentTenantID is the agent owner's workspace; it differs from the
+ // session's when the agent is shared.
+ AgentTenantID uint64 `json:"agent_tenant_id,omitempty"`
+ SummaryModelID string `json:"summary_model_id,omitempty"`
+ ReasoningEffort string `json:"reasoning_effort,omitempty"`
+ SharedAgentReadOnly bool `json:"shared_agent_read_only,omitempty"`
+ KnowledgeBaseIDs []string `json:"knowledge_base_ids,omitempty"`
+ KnowledgeIDs []string `json:"knowledge_ids,omitempty"`
+ TagScopes []TagScope `json:"tag_scopes,omitempty"`
+ MCPServiceIDs []string `json:"mcp_service_ids,omitempty"`
+ SkillNames []string `json:"skill_names,omitempty"`
+ WebSearchEnabled bool `json:"web_search_enabled,omitempty"`
+ QuestionOrigin *QuestionOrigin `json:"question_origin,omitempty"`
+ UserMessageID string `json:"user_message_id,omitempty"`
+ Language string `json:"language,omitempty"`
+}
+
+// ToolApprovalPromptRequest is the Request of an AgentPromptKindToolApproval.
+type ToolApprovalPromptRequest struct {
+ ServiceID string `json:"service_id"`
+ ServiceName string `json:"service_name"`
+ MCPToolName string `json:"mcp_tool_name"`
+ RegisteredToolName string `json:"registered_tool_name"`
+ Description string `json:"description,omitempty"`
+ Args json.RawMessage `json:"args,omitempty"`
+}
+
+// ToolApprovalPromptResponse is the Response of an AgentPromptKindToolApproval.
+type ToolApprovalPromptResponse struct {
+ Approved bool `json:"approved"`
+ // ModifiedArgs, when set on approval, replaces the original arguments.
+ ModifiedArgs json.RawMessage `json:"modified_args,omitempty"`
+ Reason string `json:"reason,omitempty"`
+}
+
+// MCPOAuthPromptRequest is the Request of an AgentPromptKindMCPOAuth.
+type MCPOAuthPromptRequest struct {
+ ServiceID string `json:"service_id"`
+ ServiceName string `json:"service_name"`
+ MCPToolName string `json:"mcp_tool_name,omitempty"`
+}
+
+// MCPOAuthPromptResponse is the Response of an AgentPromptKindMCPOAuth.
+type MCPOAuthPromptResponse struct {
+ Authorized bool `json:"authorized"`
+ Reason string `json:"reason,omitempty"`
+}
diff --git a/internal/types/ask_user.go b/internal/types/ask_user.go
new file mode 100644
index 000000000..9e2ae66fe
--- /dev/null
+++ b/internal/types/ask_user.go
@@ -0,0 +1,284 @@
+package types
+
+import (
+ "encoding/json"
+ "errors"
+ "fmt"
+ "math"
+ "strings"
+ "unicode/utf8"
+)
+
+// Limits on an ask_user question. The model writes the question, so its size
+// is bounded to keep the card readable and the stored row small.
+const (
+ AskUserMaxQuestionLen = 2000
+ AskUserMaxOptions = 10
+ AskUserMaxOptionLen = 200
+ AskUserMaxFields = 8
+ AskUserMaxNameLen = 64
+ AskUserMaxTextLen = 4000
+)
+
+// Field types an ask_user form may contain.
+const (
+ AskUserFieldText = "text"
+ AskUserFieldNumber = "number"
+ AskUserFieldSelect = "select"
+ AskUserFieldMultiSelect = "multiselect"
+)
+
+// AskUserField is one input of an ask_user form.
+type AskUserField struct {
+ Name string `json:"name"`
+ Label string `json:"label,omitempty"`
+ Type string `json:"type"`
+ Required bool `json:"required,omitempty"`
+ Options []string `json:"options,omitempty"`
+}
+
+// AskUserPromptRequest is the Request of an AgentPromptKindAskUser: a
+// question with either choices, a small form, or neither (free text).
+type AskUserPromptRequest struct {
+ Question string `json:"question"`
+ Options []string `json:"options,omitempty"`
+ MultiSelect bool `json:"multi_select,omitempty"`
+ Fields []AskUserField `json:"fields,omitempty"`
+ AllowFreeText bool `json:"allow_free_text,omitempty"`
+}
+
+// AskUserPromptResponse is the Response of an AgentPromptKindAskUser.
+// Declined means the user chose not to answer.
+type AskUserPromptResponse struct {
+ Selected []string `json:"selected,omitempty"`
+ Values map[string]any `json:"values,omitempty"`
+ Text string `json:"text,omitempty"`
+ Declined bool `json:"declined,omitempty"`
+}
+
+// FreeTextOnly reports whether the question is answered by text alone.
+func (r *AskUserPromptRequest) FreeTextOnly() bool {
+ return len(r.Options) == 0 && len(r.Fields) == 0
+}
+
+// Validate checks a question against the ask_user limits.
+func (r *AskUserPromptRequest) Validate() error {
+ r.Question = strings.TrimSpace(r.Question)
+ if r.Question == "" {
+ return errors.New("question is required")
+ }
+ if utf8.RuneCountInString(r.Question) > AskUserMaxQuestionLen {
+ return fmt.Errorf("question exceeds %d characters", AskUserMaxQuestionLen)
+ }
+ if len(r.Options) > 0 && len(r.Fields) > 0 {
+ return errors.New("use either options or fields, not both")
+ }
+ if err := validateAskUserOptions(r.Options); err != nil {
+ return err
+ }
+ if len(r.Fields) > AskUserMaxFields {
+ return fmt.Errorf("at most %d fields", AskUserMaxFields)
+ }
+ names := make(map[string]bool, len(r.Fields))
+ for i := range r.Fields {
+ f := &r.Fields[i]
+ f.Name = strings.TrimSpace(f.Name)
+ if f.Name == "" || utf8.RuneCountInString(f.Name) > AskUserMaxNameLen {
+ return fmt.Errorf("field %d needs a name of at most %d characters", i, AskUserMaxNameLen)
+ }
+ if names[f.Name] {
+ return fmt.Errorf("duplicate field %q", f.Name)
+ }
+ names[f.Name] = true
+ if utf8.RuneCountInString(f.Label) > AskUserMaxOptionLen {
+ return fmt.Errorf("label of field %q exceeds %d characters", f.Name, AskUserMaxOptionLen)
+ }
+ switch f.Type {
+ case AskUserFieldText, AskUserFieldNumber:
+ if len(f.Options) > 0 {
+ return fmt.Errorf("field %q of type %s takes no options", f.Name, f.Type)
+ }
+ case AskUserFieldSelect, AskUserFieldMultiSelect:
+ if len(f.Options) == 0 {
+ return fmt.Errorf("field %q needs options", f.Name)
+ }
+ if err := validateAskUserOptions(f.Options); err != nil {
+ return fmt.Errorf("field %q: %w", f.Name, err)
+ }
+ default:
+ return fmt.Errorf("field %q has unsupported type %q", f.Name, f.Type)
+ }
+ }
+ return nil
+}
+
+func validateAskUserOptions(options []string) error {
+ if len(options) > AskUserMaxOptions {
+ return fmt.Errorf("at most %d options", AskUserMaxOptions)
+ }
+ seen := make(map[string]bool, len(options))
+ for _, o := range options {
+ // A model may put a serialized choice list inside a one-element array.
+ // Do not display that list as a single choice, even if its JSON is valid.
+ trimmed := strings.TrimSpace(o)
+ if strings.HasPrefix(trimmed, "[") {
+ inner := strings.TrimSpace(strings.TrimPrefix(trimmed, "["))
+ if strings.HasPrefix(inner, "\"") || inner == "]" {
+ return errors.New("options must contain one choice per string, not an encoded array; " +
+ `use "options": ["first choice", "second choice"]`)
+ }
+ }
+ if strings.TrimSpace(o) == "" || utf8.RuneCountInString(o) > AskUserMaxOptionLen {
+ return fmt.Errorf("options must be non-empty and at most %d characters", AskUserMaxOptionLen)
+ }
+ if seen[o] {
+ return fmt.Errorf("duplicate option %q", o)
+ }
+ seen[o] = true
+ }
+ return nil
+}
+
+// ValidateAnswer checks a response against the question it answers.
+func (r *AskUserPromptRequest) ValidateAnswer(a *AskUserPromptResponse) error {
+ if a.Declined {
+ if len(a.Selected) > 0 || len(a.Values) > 0 || a.Text != "" {
+ return errors.New("a declined answer carries no content")
+ }
+ return nil
+ }
+ if utf8.RuneCountInString(a.Text) > AskUserMaxTextLen {
+ return fmt.Errorf("text exceeds %d characters", AskUserMaxTextLen)
+ }
+ hasText := strings.TrimSpace(a.Text) != ""
+ if hasText && !r.AllowFreeText && !r.FreeTextOnly() {
+ return errors.New("this question does not accept free text")
+ }
+ if len(a.Selected) > 0 && len(r.Options) == 0 {
+ return errors.New("this question has no options")
+ }
+ if err := checkChoices(a.Selected, r.Options, r.MultiSelect); err != nil {
+ return err
+ }
+ if len(a.Values) > 0 && len(r.Fields) == 0 {
+ return errors.New("this question has no fields")
+ }
+ fields := make(map[string]AskUserField, len(r.Fields))
+ for _, f := range r.Fields {
+ fields[f.Name] = f
+ }
+ for name, v := range a.Values {
+ f, ok := fields[name]
+ if !ok {
+ return fmt.Errorf("unknown field %q", name)
+ }
+ if err := checkFieldValue(f, v); err != nil {
+ return err
+ }
+ }
+ for _, f := range r.Fields {
+ if v, ok := a.Values[f.Name]; f.Required && (!ok || isEmptyAnswer(v)) {
+ return fmt.Errorf("field %q is required", f.Name)
+ }
+ }
+ switch {
+ case r.FreeTextOnly():
+ if !hasText {
+ return errors.New("an answer is required")
+ }
+ case len(r.Options) > 0:
+ if len(a.Selected) == 0 && !hasText {
+ return errors.New("choose an option")
+ }
+ }
+ return nil
+}
+
+func checkChoices(selected, options []string, multi bool) error {
+ if !multi && len(selected) > 1 {
+ return errors.New("only one option may be chosen")
+ }
+ allowed := make(map[string]bool, len(options))
+ for _, o := range options {
+ allowed[o] = true
+ }
+ seen := make(map[string]bool, len(selected))
+ for _, s := range selected {
+ if !allowed[s] {
+ return fmt.Errorf("%q is not an option", s)
+ }
+ if seen[s] {
+ return fmt.Errorf("%q chosen twice", s)
+ }
+ seen[s] = true
+ }
+ return nil
+}
+
+func checkFieldValue(f AskUserField, v any) error {
+ switch f.Type {
+ case AskUserFieldText:
+ s, ok := v.(string)
+ if !ok {
+ return fmt.Errorf("field %q expects text", f.Name)
+ }
+ if utf8.RuneCountInString(s) > AskUserMaxTextLen {
+ return fmt.Errorf("field %q exceeds %d characters", f.Name, AskUserMaxTextLen)
+ }
+ case AskUserFieldNumber:
+ n, ok := v.(float64)
+ if !ok || math.IsNaN(n) || math.IsInf(n, 0) {
+ return fmt.Errorf("field %q expects a number", f.Name)
+ }
+ case AskUserFieldSelect:
+ s, ok := v.(string)
+ if !ok {
+ return fmt.Errorf("field %q expects one option", f.Name)
+ }
+ if s != "" {
+ return checkChoices([]string{s}, f.Options, false)
+ }
+ case AskUserFieldMultiSelect:
+ list, ok := v.([]any)
+ if !ok {
+ return fmt.Errorf("field %q expects a list of options", f.Name)
+ }
+ chosen := make([]string, 0, len(list))
+ for _, item := range list {
+ s, ok := item.(string)
+ if !ok {
+ return fmt.Errorf("field %q expects a list of options", f.Name)
+ }
+ chosen = append(chosen, s)
+ }
+ return checkChoices(chosen, f.Options, true)
+ }
+ return nil
+}
+
+func isEmptyAnswer(v any) bool {
+ switch x := v.(type) {
+ case nil:
+ return true
+ case string:
+ return strings.TrimSpace(x) == ""
+ case []any:
+ return len(x) == 0
+ }
+ return false
+}
+
+// ValidateAskUserResponse is the broker validator of AgentPromptKindAskUser.
+func ValidateAskUserResponse(request, response json.RawMessage) error {
+ var q AskUserPromptRequest
+ if err := json.Unmarshal(request, &q); err != nil {
+ return fmt.Errorf("unreadable question: %w", err)
+ }
+ var a AskUserPromptResponse
+ dec := json.NewDecoder(strings.NewReader(string(response)))
+ dec.DisallowUnknownFields()
+ if err := dec.Decode(&a); err != nil {
+ return err
+ }
+ return q.ValidateAnswer(&a)
+}
diff --git a/internal/types/ask_user_test.go b/internal/types/ask_user_test.go
new file mode 100644
index 000000000..84a92878d
--- /dev/null
+++ b/internal/types/ask_user_test.go
@@ -0,0 +1,105 @@
+package types
+
+import (
+ "encoding/json"
+ "strings"
+ "testing"
+
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+func TestAskUserRequestValidate(t *testing.T) {
+ many := make([]string, AskUserMaxOptions+1)
+ for i := range many {
+ many[i] = strings.Repeat("o", i+1)
+ }
+ for name, tc := range map[string]struct {
+ req AskUserPromptRequest
+ err string
+ }{
+ "free text": {req: AskUserPromptRequest{Question: " which? "}},
+ "options": {req: AskUserPromptRequest{Question: "q", Options: []string{"a", "b"}}},
+ "empty question": {req: AskUserPromptRequest{Question: " "}, err: "question is required"},
+ "long question": {
+ req: AskUserPromptRequest{Question: strings.Repeat("问", AskUserMaxQuestionLen+1)}, err: "exceeds",
+ },
+ "too many options": {req: AskUserPromptRequest{Question: "q", Options: many}, err: "at most"},
+ "duplicate option": {req: AskUserPromptRequest{Question: "q", Options: []string{"a", "a"}}, err: "duplicate"},
+ "options and fields": {req: AskUserPromptRequest{
+ Question: "q", Options: []string{"a"}, Fields: []AskUserField{{Name: "n", Type: AskUserFieldText}},
+ }, err: "either"},
+ "unknown field type": {req: AskUserPromptRequest{
+ Question: "q", Fields: []AskUserField{{Name: "n", Type: "date"}},
+ }, err: "unsupported"},
+ "select without options": {req: AskUserPromptRequest{
+ Question: "q", Fields: []AskUserField{{Name: "n", Type: AskUserFieldSelect}},
+ }, err: "needs options"},
+ "duplicate field": {req: AskUserPromptRequest{
+ Question: "q", Fields: []AskUserField{
+ {Name: "n", Type: AskUserFieldText}, {Name: "n", Type: AskUserFieldNumber},
+ },
+ }, err: "duplicate field"},
+ } {
+ t.Run(name, func(t *testing.T) {
+ err := tc.req.Validate()
+ if tc.err == "" {
+ require.NoError(t, err)
+ return
+ }
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), tc.err)
+ })
+ }
+}
+
+func TestValidateAskUserResponse(t *testing.T) {
+ form := `{"question":"q","fields":[
+ {"name":"env","type":"select","options":["dev","prod"],"required":true},
+ {"name":"replicas","type":"number"},
+ {"name":"tags","type":"multiselect","options":["a","b"]},
+ {"name":"note","type":"text"}]}`
+ choice := `{"question":"q","options":["a","b"]}`
+ for name, tc := range map[string]struct {
+ request, response string
+ err string
+ }{
+ "free text answer": {request: `{"question":"q"}`, response: `{"text":"blue"}`},
+ "free text missing": {request: `{"question":"q"}`, response: `{}`, err: "required"},
+ "declined": {request: choice, response: `{"declined":true}`},
+ "declined with answer": {request: choice, response: `{"declined":true,"selected":["a"]}`, err: "no content"},
+ "choice": {request: choice, response: `{"selected":["b"]}`},
+ "not an option": {request: choice, response: `{"selected":["c"]}`, err: "not an option"},
+ "two of single choice": {request: choice, response: `{"selected":["a","b"]}`, err: "only one"},
+ "no choice": {request: choice, response: `{}`, err: "choose"},
+ "text not allowed": {request: choice, response: `{"text":"x"}`, err: "free text"},
+ "text allowed": {
+ request: `{"question":"q","options":["a"],"allow_free_text":true}`,
+ response: `{"text":"other"}`,
+ },
+ "form": {
+ request: form,
+ response: `{"values":{"env":"prod","replicas":3,"tags":["a"],"note":"ok"}}`,
+ },
+ "form missing required": {request: form, response: `{"values":{"replicas":3}}`, err: `"env" is required`},
+ "form wrong type": {request: form, response: `{"values":{"env":"prod","replicas":"3"}}`, err: "number"},
+ "form unknown field": {request: form, response: `{"values":{"env":"prod","x":1}}`, err: "unknown field"},
+ "form bad option": {request: form, response: `{"values":{"env":"staging"}}`, err: "not an option"},
+ "unknown key": {request: choice, response: `{"selected":["a"],"extra":1}`, err: "unknown field"},
+ "long text": {
+ request: `{"question":"q"}`,
+ response: `{"text":"` + strings.Repeat("x", AskUserMaxTextLen+1) + `"}`,
+ err: "exceeds",
+ },
+ } {
+ t.Run(name, func(t *testing.T) {
+ err := ValidateAskUserResponse(json.RawMessage(tc.request), json.RawMessage(tc.response))
+ if tc.err == "" {
+ require.NoError(t, err)
+ return
+ }
+ require.Error(t, err)
+ assert.Contains(t, err.Error(), tc.err)
+ })
+ }
+}
diff --git a/internal/types/chat.go b/internal/types/chat.go
index 16785c7d4..b16298616 100644
--- a/internal/types/chat.go
+++ b/internal/types/chat.go
@@ -261,10 +261,22 @@ const (
// The UI shows a toolbar placeholder until ResponseTypeComplete carries
// the file list.
ResponseTypeArtifactsPending ResponseType = "artifacts_pending"
+ // ResponseTypeRunSuspended precedes complete when the run ended waiting
+ // on a user prompt; the message stays incomplete until it is answered.
+ ResponseTypeRunSuspended ResponseType = "run_suspended"
+ // ResponseTypeRunResumed opens the stream of a suspended run resumed
+ // after its prompt was answered. Steps saved before the suspension are
+ // not replayed; the client keeps the ones it already shows.
+ ResponseTypeRunResumed ResponseType = "run_resumed"
// ToolApprovalRequired: MCP tool marked dangerous — UI must collect user approval before execution continues
ResponseTypeToolApprovalRequired ResponseType = "tool_approval_required"
// ToolApprovalResolved: user approved/rejected (or timeout); informational for UI replay
ResponseTypeToolApprovalResolved ResponseType = "tool_approval_resolved"
+ // ResponseTypeAgentPromptRequired indicates that the agent asks the user something (ask_user);
+ // data carries the prompt kind and its request JSON.
+ ResponseTypeAgentPromptRequired ResponseType = "agent_prompt_required"
+ // ResponseTypeAgentPromptResolved indicates an answered, declined, timed out or canceled prompt.
+ ResponseTypeAgentPromptResolved ResponseType = "agent_prompt_resolved"
// MCPOAuthRequired: an OAuth-enabled MCP service was invoked but the user
// has not authorized it — UI must surface an "Authorize" prompt and the
// agent pauses until authorization completes (or the wait times out).
diff --git a/internal/types/interfaces/agent.go b/internal/types/interfaces/agent.go
index f0c3a2ea8..5f682536c 100644
--- a/internal/types/interfaces/agent.go
+++ b/internal/types/interfaces/agent.go
@@ -2,6 +2,7 @@ package interfaces
import (
"context"
+ "encoding/json"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/models/chat"
@@ -43,6 +44,21 @@ type AgentEngine interface {
// end on a stored turn, so later turns start from them. Nil (default)
// keeps compaction local to the turn. Must be called before Execute.
SetContextCheckpointSink(sink types.ContextCheckpointSink)
+
+ // EnableSuspension lets a user prompt end the run so it can be resumed
+ // later instead of blocking. request is the caller's
+ // types.ResumableAgentRequest. Must be called before Execute.
+ EnableSuspension(request json.RawMessage)
+
+ // SetInteractive marks the client as able to render and answer prompts
+ // (ask_user). Must be called before Execute or Resume.
+ SetInteractive(interactive bool)
+
+ // Resume continues a suspended run from its saved snapshot, delivering
+ // the answered prompt to the call it was blocked on. Use instead of
+ // Execute; EnableSuspension still applies.
+ Resume(ctx context.Context, sessionID, messageID string, llmContext []chat.Message,
+ snapshot []byte, answered *types.AgentPrompt) (*types.AgentState, error)
}
// AgentService defines the interface for agent-related operations
diff --git a/internal/types/interfaces/agent_prompt.go b/internal/types/interfaces/agent_prompt.go
new file mode 100644
index 000000000..34613f17e
--- /dev/null
+++ b/internal/types/interfaces/agent_prompt.go
@@ -0,0 +1,41 @@
+package interfaces
+
+import (
+ "context"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// AgentPromptRepository persists human-in-the-loop prompts raised by agent
+// runs. State changes are compare-and-set so replicas never disagree.
+type AgentPromptRepository interface {
+ Create(ctx context.Context, row *types.AgentPrompt) error
+ // Get returns nil, nil when the row does not exist.
+ Get(ctx context.Context, id string) (*types.AgentPrompt, error)
+ // Transition applies t only when the row is in one of t.From and reports
+ // whether this call won.
+ Transition(ctx context.Context, id string, t types.AgentPromptTransition) (bool, error)
+ // RenewLease extends the lease of a row that is pending, answered or
+ // executing, while owner still holds it.
+ RenewLease(ctx context.Context, id, owner string, until time.Time) (bool, error)
+ // ListStaleLeases returns up to limit rows in one of statuses whose lease
+ // ended before t: their owner replica is gone.
+ ListStaleLeases(ctx context.Context, statuses []string, before time.Time, limit int) ([]*types.AgentPrompt, error)
+ // ListExpired returns up to limit suspended rows that expired before t.
+ ListExpired(ctx context.Context, before time.Time, limit int) ([]*types.AgentPrompt, error)
+ // ListBySession returns the session's rows in one of statuses.
+ ListBySession(ctx context.Context, sessionID string, statuses []string) ([]*types.AgentPrompt, error)
+}
+
+// AgentRunSuspensionRepository persists the state of runs blocked on a
+// prompt, one row per assistant message.
+type AgentRunSuspensionRepository interface {
+ // Save inserts or replaces the row for row.AssistantMessageID.
+ Save(ctx context.Context, row *types.AgentRunSuspension) error
+ // Get returns nil, nil when the message has no saved state.
+ Get(ctx context.Context, assistantMessageID string) (*types.AgentRunSuspension, error)
+ // Delete removes the row only while it still belongs to promptID, so a
+ // newer prompt's state is never dropped by a stale caller.
+ Delete(ctx context.Context, assistantMessageID, promptID string) error
+}
diff --git a/internal/types/interfaces/stream_manager.go b/internal/types/interfaces/stream_manager.go
index aa5f69512..7bd8b9701 100644
--- a/internal/types/interfaces/stream_manager.go
+++ b/internal/types/interfaces/stream_manager.go
@@ -31,6 +31,10 @@ type StreamManager interface {
// Returns: events slice, next offset for subsequent reads, error
GetEvents(ctx context.Context, sessionID, messageID string, fromOffset int) ([]StreamEvent, int, error)
+ // ResetEvents drops a message's stream events so a run resumed into the
+ // same message starts a fresh stream. Steer events are kept.
+ ResetEvents(ctx context.Context, sessionID, messageID string) error
+
// AppendSteerEvents appends control events (steer instructions) to a
// dedicated per-run sub-list that is never surfaced on the SSE stream.
// Producers are incoming "append a message to the running turn" HTTP
diff --git a/internal/types/message.go b/internal/types/message.go
index 4170146ca..a5aa584a9 100644
--- a/internal/types/message.go
+++ b/internal/types/message.go
@@ -502,8 +502,15 @@ type Message struct {
// repository loads it with every message it returns and writes it whenever it
// is non-nil on create or update. A nil slice leaves the stored rows alone.
Artifacts MessageArtifacts `json:"artifacts,omitempty" gorm:"-"`
+ // PendingPrompt is the prompt an awaiting_input message waits on. The
+ // message list fills it in for the prompt's owner; it is never stored.
+ PendingPrompt *PendingPromptView `json:"pending_prompt,omitempty" gorm:"-"`
// Whether message generation is complete
IsCompleted bool `json:"is_completed"`
+ // RunState refines an incomplete message: MessageRunStateAwaitingInput
+ // means the run ended suspended on a prompt instead of still generating.
+ // Empty means IsCompleted alone describes the message.
+ RunState string `json:"run_state,omitempty" gorm:"type:varchar(32);not null;default:''"`
// Whether this response is a fallback (no knowledge base match found)
IsFallback bool `json:"is_fallback,omitempty"`
// Agent total execution duration in milliseconds (from query start to answer start)
@@ -663,6 +670,10 @@ func (m *Message) BeforeCreate(tx *gorm.DB) (err error) {
return nil
}
+// MessageRunStateAwaitingInput marks an assistant message whose run ended
+// suspended on an agent prompt and will resume once the user answers.
+const MessageRunStateAwaitingInput = "awaiting_input"
+
// MessageSearchMode represents the search mode for message search
type MessageSearchMode string
diff --git a/internal/types/qa_request.go b/internal/types/qa_request.go
index ac1aa927d..08178d444 100644
--- a/internal/types/qa_request.go
+++ b/internal/types/qa_request.go
@@ -94,4 +94,23 @@ type QARequest struct {
// IM/MCP, which call the QA services directly, do not and leave this
// false so the service takes the lease itself.
TurnLeaseHeld bool
+ // Suspendable lets the run end while it waits on a user prompt and be
+ // resumed later. Set by callers whose client can render a suspended
+ // message and answer it afterwards (web, embed, API); IM and MCP callers
+ // wait synchronously.
+ Suspendable bool
+ // Interactive marks a caller that can show and answer a prompt the agent
+ // raises on its own, such as an ask_user question. API-key callers cannot
+ // answer prompts, so their runs are not interactive.
+ Interactive bool
+ // Resume, when set, continues a suspended run instead of starting one.
+ Resume *AgentResume
+}
+
+// AgentResume is what a resumed run continues from.
+type AgentResume struct {
+ // Snapshot is the run state saved when the run suspended.
+ Snapshot []byte
+ // Prompt is the answered prompt the run was suspended on.
+ Prompt *AgentPrompt
}
diff --git a/migrations/sqlite/000037_agent_prompts.down.sql b/migrations/sqlite/000037_agent_prompts.down.sql
new file mode 100644
index 000000000..cc029f9bc
--- /dev/null
+++ b/migrations/sqlite/000037_agent_prompts.down.sql
@@ -0,0 +1,10 @@
+ALTER TABLE messages DROP COLUMN run_state;
+
+DROP INDEX IF EXISTS idx_agent_run_suspensions_session;
+DROP TABLE IF EXISTS agent_run_suspensions;
+
+DROP INDEX IF EXISTS idx_agent_prompts_message;
+DROP INDEX IF EXISTS idx_agent_prompts_status_expires;
+DROP INDEX IF EXISTS idx_agent_prompts_status_lease;
+DROP INDEX IF EXISTS idx_agent_prompts_session_status;
+DROP TABLE IF EXISTS agent_prompts;
diff --git a/migrations/sqlite/000037_agent_prompts.up.sql b/migrations/sqlite/000037_agent_prompts.up.sql
new file mode 100644
index 000000000..7dfddcd80
--- /dev/null
+++ b/migrations/sqlite/000037_agent_prompts.up.sql
@@ -0,0 +1,50 @@
+-- Mirrors versioned migration 000119_agent_prompts:
+-- persisted human-in-the-loop prompts and suspended agent run state.
+
+CREATE TABLE IF NOT EXISTS agent_prompts (
+ id TEXT PRIMARY KEY,
+ tenant_id INTEGER NOT NULL,
+ user_id TEXT NOT NULL DEFAULT '',
+ session_id TEXT NOT NULL,
+ assistant_message_id TEXT NOT NULL DEFAULT '',
+ request_id TEXT NOT NULL DEFAULT '',
+ kind TEXT NOT NULL,
+ tool_call_id TEXT NOT NULL DEFAULT '',
+ suspendable BOOLEAN NOT NULL DEFAULT 0,
+ request TEXT,
+ response TEXT,
+ status TEXT NOT NULL,
+ close_reason TEXT NOT NULL DEFAULT '',
+ resolved_by TEXT NOT NULL DEFAULT '',
+ resolved_at DATETIME,
+ owner_instance TEXT NOT NULL DEFAULT '',
+ lease_until DATETIME,
+ expires_at DATETIME,
+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_prompts_session_status
+ ON agent_prompts (session_id, status);
+CREATE INDEX IF NOT EXISTS idx_agent_prompts_status_lease
+ ON agent_prompts (status, lease_until);
+CREATE INDEX IF NOT EXISTS idx_agent_prompts_status_expires
+ ON agent_prompts (status, expires_at);
+CREATE INDEX IF NOT EXISTS idx_agent_prompts_message
+ ON agent_prompts (assistant_message_id);
+
+CREATE TABLE IF NOT EXISTS agent_run_suspensions (
+ assistant_message_id TEXT PRIMARY KEY,
+ tenant_id INTEGER NOT NULL,
+ session_id TEXT NOT NULL,
+ prompt_id TEXT NOT NULL,
+ snapshot_version INTEGER NOT NULL,
+ snapshot TEXT NOT NULL,
+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_run_suspensions_session
+ ON agent_run_suspensions (session_id);
+
+ALTER TABLE messages ADD COLUMN run_state TEXT NOT NULL DEFAULT '';
diff --git a/migrations/versioned/000119_agent_prompts.down.sql b/migrations/versioned/000119_agent_prompts.down.sql
new file mode 100644
index 000000000..7f428a999
--- /dev/null
+++ b/migrations/versioned/000119_agent_prompts.down.sql
@@ -0,0 +1,10 @@
+ALTER TABLE messages DROP COLUMN IF EXISTS run_state;
+
+DROP INDEX IF EXISTS idx_agent_run_suspensions_session;
+DROP TABLE IF EXISTS agent_run_suspensions;
+
+DROP INDEX IF EXISTS idx_agent_prompts_message;
+DROP INDEX IF EXISTS idx_agent_prompts_status_expires;
+DROP INDEX IF EXISTS idx_agent_prompts_status_lease;
+DROP INDEX IF EXISTS idx_agent_prompts_session_status;
+DROP TABLE IF EXISTS agent_prompts;
diff --git a/migrations/versioned/000119_agent_prompts.up.sql b/migrations/versioned/000119_agent_prompts.up.sql
new file mode 100644
index 000000000..af6fbcd1b
--- /dev/null
+++ b/migrations/versioned/000119_agent_prompts.up.sql
@@ -0,0 +1,57 @@
+DO $$ BEGIN RAISE NOTICE '[Migration 000119] Creating agent_prompts and agent_run_suspensions...'; END $$;
+
+-- One row per human-in-the-loop prompt raised by an agent run: a tool
+-- approval, an in-conversation OAuth authorization, a question for the user.
+-- The row, not process memory, is the source of truth for the answer so any
+-- replica can record it. Kind-specific content lives in request / response.
+CREATE TABLE IF NOT EXISTS agent_prompts (
+ id VARCHAR(36) PRIMARY KEY,
+ tenant_id BIGINT NOT NULL,
+ user_id VARCHAR(64) NOT NULL DEFAULT '',
+ session_id VARCHAR(36) NOT NULL,
+ assistant_message_id VARCHAR(36) NOT NULL DEFAULT '',
+ request_id VARCHAR(128) NOT NULL DEFAULT '',
+ kind VARCHAR(32) NOT NULL,
+ tool_call_id VARCHAR(255) NOT NULL DEFAULT '',
+ suspendable BOOLEAN NOT NULL DEFAULT false,
+ request JSONB,
+ response JSONB,
+ status VARCHAR(32) NOT NULL,
+ close_reason TEXT NOT NULL DEFAULT '',
+ resolved_by VARCHAR(64) NOT NULL DEFAULT '',
+ resolved_at TIMESTAMPTZ,
+ owner_instance VARCHAR(64) NOT NULL DEFAULT '',
+ lease_until TIMESTAMPTZ,
+ expires_at TIMESTAMPTZ,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_prompts_session_status
+ ON agent_prompts (session_id, status);
+CREATE INDEX IF NOT EXISTS idx_agent_prompts_status_lease
+ ON agent_prompts (status, lease_until);
+CREATE INDEX IF NOT EXISTS idx_agent_prompts_status_expires
+ ON agent_prompts (status, expires_at);
+CREATE INDEX IF NOT EXISTS idx_agent_prompts_message
+ ON agent_prompts (assistant_message_id);
+
+-- Run state persisted when an agent run blocks on a prompt, so the run can be
+-- suspended and later resumed by any replica.
+CREATE TABLE IF NOT EXISTS agent_run_suspensions (
+ assistant_message_id VARCHAR(36) PRIMARY KEY,
+ tenant_id BIGINT NOT NULL,
+ session_id VARCHAR(36) NOT NULL,
+ prompt_id VARCHAR(36) NOT NULL,
+ snapshot_version INTEGER NOT NULL,
+ snapshot JSONB NOT NULL,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
+);
+
+CREATE INDEX IF NOT EXISTS idx_agent_run_suspensions_session
+ ON agent_run_suspensions (session_id);
+
+ALTER TABLE messages ADD COLUMN IF NOT EXISTS run_state VARCHAR(32) NOT NULL DEFAULT '';
+
+DO $$ BEGIN RAISE NOTICE '[Migration 000119] agent_prompts ready'; END $$;