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

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

Tool approvals and MCP OAuth prompts are now rows in agent_prompts,
awaited through hitl.Broker (lease, DB polling, Redis wake-up, per-kind
answer validation). Resolve is bound to session and kind. This is P1 of
the suspend/resume design; runs still block as before.

* feat(agent): suspend runs whose prompt outlives a short in-memory wait

Behind agent.prompt_suspend_enabled (off by default). A run raised from the
HTTP stream saves its state when a tool approval is raised; after the hot
wait the prompt moves to suspended and the assistant message is saved as
awaiting_input instead of blocking. A reaper takes over prompts whose
waiting replica stopped renewing its lease. Resume comes in a later change.

* feat(agent): resume suspended runs once their prompt is answered

The replica that records the answer resumes the run in process under the
prompt's lease. Superseded, expired and abandoned runs are closed with a
result for every tool call, and approved tools are never replayed.

* feat(agent): let users answer suspended tool approvals and follow the resumed run

* feat(agent): ask_user tool and generic prompt answer endpoint

- ask_user built-in tool: options, short forms or free text; validated
  answers, decline, suspend/resume like tool approval; non-interactive
  callers (IM, API keys) are told to ask in the reply instead
- POST /agent/prompts/{prompt_id} (and embed variant) answers ask_user
  and tool_approval prompts, returns resumed; SDK ResolveAgentPrompt
- agent_prompt_required/resolved events; AskUserCard sharing the
  countdown with ToolApprovalCard; answered questions rebuilt as cards
  from history
- awaiting-input messages keep their steps expanded so the pending card
  stays visible; prompt cards keyed by their own id
- i18n for all locales; design doc updated

* fix(agent): keep prompt answers that race a suspending or vanished owner

- Resolve suspends a pending prompt whose owner's lease lapsed, as the
  reaper would, so the answer resumes the run instead of waking nobody.
- Resuming waits for the suspending run to persist its message and clear
  its live-run marker; a marker left by a vanished owner is cleared.
- A resumed run that suspends again on a new prompt no longer has its
  message closed from the old state.
- tool_approval answers are decoded strictly and require "approved";
  fix the SDK doc that showed {"decision": "approve"}.
- API-key runs block instead of suspending, since they cannot answer.
- A run state that cannot be saved falls back to an in-memory wait, and
  NUL escapes are stripped from snapshots for jsonb.

* style(chat): align the ask_user card with the other interaction cards

Question and answer use the timeline's step text styles instead of
primary-colored and monospace text; options and form controls use the
compact step size, the number input spans the row, and the free-text
character counter is hidden.

* feat(chat): dock pending agent prompts above the composer

Tool approvals, ask_user questions and MCP OAuth prompts were answered
inline in the agent timeline, where a long answer or scrolling back
pushes them out of view. Open prompts of a streaming or suspended run
now gather in a dock above the composer (main chat and embed), one at a
time with a pager, lettered options and Enter to submit. The timeline
keeps a one-line record with a link back to the dock and the outcome
once answered. Views without a dock still answer inline.

* fix(agent): fence prompt ownership and preserve resumed turn context

* fix(agent): keep runs through consume errors and file prompts under the caller

Consume reported a store error as a lost claim, so an answer consumed
during a database hiccup detached its run: the message was never
persisted, the live-run marker stayed, and the reaper skipped the row
because the waiter had already dropped the snapshot. Consume now retries,
then decides from the row, and gives a run up only when the prompt is
known to have moved on.

Tool approvals and OAuth prompts of a shared agent were filed under the
agent's workspace, so the user's answer failed the tenant check and the
prompt timed out. Like ask_user, they now use the caller's workspace;
policy and token lookups stay in the agent's.

Enter on a picked option submits it instead of toggling it off, and
resume errors no longer report a nil cause.

* fix(agent): validate prompt choices and require durable approval claims

Reject malformed serialized option lists so the model can retry with valid arguments. Distinguish prompt consumption failures from lost ownership without authorizing side effects, and preserve native Enter selection for unselected choices.

* fix(agent): resolve prompt workflow lint errors
main
lyingbug 2026-10-14 20:37:28 +08:00 committed by GitHub
parent 6c3730a6ad
commit 383d26535a
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
118 changed files with 10104 additions and 708 deletions

View File

@ -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
}

View File

@ -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

View File

@ -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` 放进本次范围,作为前端一期之后的单独一期。

View File

@ -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(

View File

@ -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.

View File

@ -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')
})

View File

@ -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,
}
}

View File

@ -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 = ''
})

View File

@ -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 }
}

View File

@ -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']])
}
})

View File

@ -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)
}

View File

@ -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',

View File

@ -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: 'ドキュメントを読む',

View File

@ -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: '지식베이스, 파일, 대화 검색…',

View File

@ -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: 'Поиск по базам знаний, файлам, диалогам…',

View File

@ -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: '搜索知识库、文件、对话…',

View File

@ -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: '搜尋知識庫、檔案、對話…',

View File

@ -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' })
})

View File

@ -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')
}

View File

@ -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
}

View File

@ -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')

View File

@ -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

View File

@ -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);
}

View File

@ -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/)

View File

@ -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'}`;
};

View File

@ -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>

View File

@ -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">

View File

@ -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>

View File

@ -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">

View File

@ -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;
}

View File

@ -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

View File

@ -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;

View File

@ -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

View File

@ -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
}

View File

@ -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)
}

View File

@ -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)
}

File diff suppressed because it is too large Load Diff

View File

@ -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)
}
})
}
}
}

View File

@ -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)

View File

@ -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,

View File

@ -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)
}
}

View File

@ -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)
})
}
}

View File

@ -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
}

View File

@ -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)
}

View File

@ -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
}

View File

@ -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")
}

View File

@ -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
}

View File

@ -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")
})
}
}

View File

@ -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)
}

View File

@ -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,

View File

@ -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
}

View File

@ -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))
}

View File

@ -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")
}

View File

@ -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)
}

View File

@ -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},

View File

@ -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

View File

@ -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.

View File

@ -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)

View File

@ -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"})

View File

@ -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,

View File

@ -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)
}

View File

@ -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 {

View File

@ -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) {

View File

@ -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
}

View File

@ -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
}

View File

@ -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)
}

View File

@ -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)
})
}

View File

@ -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,

View File

@ -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(

View File

@ -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 {

View File

@ -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)
}

View File

@ -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)
}

View File

@ -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)

View File

@ -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 {

View File

@ -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

View File

@ -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.

View File

@ -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)
}

View File

@ -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)

View File

@ -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

View File

@ -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.

View File

@ -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")
}

View File

@ -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"`

View File

@ -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,
})
}

View File

@ -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)
}

View File

@ -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),

View File

@ -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")
}

View File

@ -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()

View File

@ -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.

View File

@ -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.

View File

@ -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

View File

@ -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,

View File

@ -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)
}
}

View File

@ -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)
})
}
}

View File

@ -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))
}

View File

@ -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

View File

@ -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)

View File

@ -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)
}

View File

@ -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": "查看图片内容",

View File

@ -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.

View File

@ -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.

Some files were not shown because too many files have changed in this diff Show More