From 383d26535adcd7c4c4d383d5c81889028bc46237 Mon Sep 17 00:00:00 2001 From: lyingbug Date: Wed, 14 Oct 2026 20:37:28 +0800 Subject: [PATCH] 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 --- client/mcp_service.go | 33 + config/builtin_agents.yaml | 2 + docs/design/agent-hitl-suspend-resume.md | 467 +++++++++ frontend/src/api/embed/index.ts | 23 +- frontend/src/api/mcp-service.ts | 18 +- .../useChatStreamHandler.suspend.test.ts | 201 ++++ .../src/composables/useChatStreamHandler.ts | 183 +++- .../src/composables/useEmbedChatSession.ts | 45 +- .../src/composables/usePromptCountdown.ts | 65 ++ .../src/composables/usePromptDock.test.mjs | 178 ++++ frontend/src/composables/usePromptDock.ts | 87 ++ frontend/src/i18n/locales/en-US.ts | 37 +- frontend/src/i18n/locales/ja-JP.ts | 37 +- frontend/src/i18n/locales/ko-KR.ts | 37 +- frontend/src/i18n/locales/ru-RU.ts | 37 +- frontend/src/i18n/locales/zh-CN.ts | 37 +- frontend/src/i18n/locales/zh-TW.ts | 37 +- frontend/src/utils/askUser.test.ts | 41 + frontend/src/utils/askUser.ts | 67 ++ frontend/src/utils/promptKeys.ts | 29 + frontend/src/utils/suspendedRun.ts | 7 + frontend/src/utils/tool-capabilities.ts | 1 + frontend/src/views/agent/AgentEditorModal.vue | 3 +- .../AgentStreamDisplay.style.test.mjs | 9 +- .../chat/components/AgentStreamDisplay.vue | 71 +- .../src/views/chat/components/AskUserCard.vue | 286 ++++++ .../views/chat/components/McpOAuthCard.vue | 68 +- .../chat/components/PendingPromptDock.vue | 287 ++++++ .../chat/components/ToolApprovalCard.vue | 171 ++-- .../components/agent-interaction-card.less | 223 +++++ frontend/src/views/chat/index.vue | 53 +- frontend/src/views/embed/EmbedChatCore.vue | 17 + internal/agent/act.go | 61 +- internal/agent/approval/ask_user.go | 200 ++++ internal/agent/approval/ask_user_test.go | 114 +++ .../agent/approval/consume_failure_test.go | 100 ++ internal/agent/approval/gate.go | 902 ++++++++---------- internal/agent/approval/gate_test.go | 246 ++++- internal/agent/engine.go | 24 +- internal/agent/finalize.go | 6 + internal/agent/hitl/broker.go | 727 ++++++++++++++ internal/agent/hitl/broker_test.go | 366 +++++++ internal/agent/hitl/reaper.go | 208 ++++ internal/agent/hitl/resume_test.go | 175 ++++ internal/agent/hitl/store.go | 210 ++++ internal/agent/hitl/suspend_test.go | 270 ++++++ internal/agent/resume.go | 170 ++++ internal/agent/resume_mcp_test.go | 83 ++ internal/agent/resume_test.go | 195 ++++ internal/agent/steer.go | 1 + internal/agent/suspend.go | 272 ++++++ internal/agent/suspend_test.go | 168 ++++ internal/agent/tools/ask_user.go | 183 ++++ internal/agent/tools/ask_user_test.go | 172 ++++ internal/agent/tools/capabilities.go | 1 + internal/agent/tools/definitions.go | 7 + internal/agent/tools/exec_context.go | 12 + .../tools/mcp_catalog_integration_test.go | 6 + internal/agent/tools/mcp_catalog_test.go | 7 + internal/agent/tools/mcp_oauth.go | 4 +- internal/agent/tools/mcp_oauth_test.go | 84 ++ internal/agent/tools/mcp_tool.go | 64 +- internal/agent/tools/mcp_tool_enabled_test.go | 7 + internal/agent/tools/param_cast.go | 5 + .../repository/agent_prompt_repository.go | 219 +++++ .../agent_prompt_repository_test.go | 224 +++++ internal/application/repository/message.go | 7 + internal/application/service/agent_service.go | 6 + .../application/service/session_agent_qa.go | 41 +- .../application/service/session_rewind.go | 12 + internal/application/service/suspended_run.go | 94 ++ .../application/service/suspended_run_test.go | 118 +++ .../service/tenant_skill_install_test.go | 17 +- .../service/tenant_skill_transcript_test.go | 2 + internal/config/config.go | 46 + internal/container/container.go | 56 +- ...gration_sqlite_agent_allowed_tools_test.go | 8 +- .../migration_sqlite_versioned_schema_test.go | 21 +- internal/event/event.go | 5 + internal/event/event_data.go | 46 +- internal/handler/agent_prompt_test.go | 90 ++ internal/handler/embed_channel.go | 12 + internal/handler/mcp_oauth.go | 21 +- internal/handler/mcp_service.go | 110 ++- internal/handler/message.go | 47 + .../handler/message_pending_prompt_test.go | 70 ++ internal/handler/sandbox_skill_test.go | 2 + .../handler/session/agent_stream_handler.go | 71 +- .../continue_stream_resource_urls_test.go | 2 + internal/handler/session/handler.go | 5 + internal/handler/session/qa.go | 51 +- internal/handler/session/resume.go | 334 +++++++ .../handler/session/resume_context_test.go | 118 +++ .../handler/session/resume_settle_test.go | 86 ++ internal/handler/session/steer.go | 4 +- .../handler/session/steer_live_run_test.go | 2 + .../session/suspended_completion_test.go | 81 ++ internal/im/tool_display.go | 1 + internal/modelcontext/tool_policy.go | 1 + internal/router/routes_agent.go | 1 + internal/router/routes_infra.go | 2 + internal/stream/memory_manager.go | 13 + internal/stream/redis_live_run_test.go | 30 + internal/stream/redis_manager.go | 8 + internal/types/agent.go | 8 + internal/types/agent_prompt.go | 194 ++++ internal/types/ask_user.go | 284 ++++++ internal/types/ask_user_test.go | 105 ++ internal/types/chat.go | 12 + internal/types/interfaces/agent.go | 16 + internal/types/interfaces/agent_prompt.go | 41 + internal/types/interfaces/stream_manager.go | 4 + internal/types/message.go | 11 + internal/types/qa_request.go | 19 + .../sqlite/000037_agent_prompts.down.sql | 10 + migrations/sqlite/000037_agent_prompts.up.sql | 50 + .../versioned/000119_agent_prompts.down.sql | 10 + .../versioned/000119_agent_prompts.up.sql | 57 ++ 118 files changed, 10104 insertions(+), 708 deletions(-) create mode 100644 docs/design/agent-hitl-suspend-resume.md create mode 100644 frontend/src/composables/useChatStreamHandler.suspend.test.ts create mode 100644 frontend/src/composables/usePromptCountdown.ts create mode 100644 frontend/src/composables/usePromptDock.test.mjs create mode 100644 frontend/src/composables/usePromptDock.ts create mode 100644 frontend/src/utils/askUser.test.ts create mode 100644 frontend/src/utils/askUser.ts create mode 100644 frontend/src/utils/promptKeys.ts create mode 100644 frontend/src/utils/suspendedRun.ts create mode 100644 frontend/src/views/chat/components/AskUserCard.vue create mode 100644 frontend/src/views/chat/components/PendingPromptDock.vue create mode 100644 internal/agent/approval/ask_user.go create mode 100644 internal/agent/approval/ask_user_test.go create mode 100644 internal/agent/approval/consume_failure_test.go create mode 100644 internal/agent/hitl/broker.go create mode 100644 internal/agent/hitl/broker_test.go create mode 100644 internal/agent/hitl/reaper.go create mode 100644 internal/agent/hitl/resume_test.go create mode 100644 internal/agent/hitl/store.go create mode 100644 internal/agent/hitl/suspend_test.go create mode 100644 internal/agent/resume.go create mode 100644 internal/agent/resume_mcp_test.go create mode 100644 internal/agent/resume_test.go create mode 100644 internal/agent/suspend.go create mode 100644 internal/agent/suspend_test.go create mode 100644 internal/agent/tools/ask_user.go create mode 100644 internal/agent/tools/ask_user_test.go create mode 100644 internal/application/repository/agent_prompt_repository.go create mode 100644 internal/application/repository/agent_prompt_repository_test.go create mode 100644 internal/application/service/suspended_run.go create mode 100644 internal/application/service/suspended_run_test.go create mode 100644 internal/handler/agent_prompt_test.go create mode 100644 internal/handler/message_pending_prompt_test.go create mode 100644 internal/handler/session/resume.go create mode 100644 internal/handler/session/resume_context_test.go create mode 100644 internal/handler/session/resume_settle_test.go create mode 100644 internal/handler/session/suspended_completion_test.go create mode 100644 internal/types/agent_prompt.go create mode 100644 internal/types/ask_user.go create mode 100644 internal/types/ask_user_test.go create mode 100644 internal/types/interfaces/agent_prompt.go create mode 100644 migrations/sqlite/000037_agent_prompts.down.sql create mode 100644 migrations/sqlite/000037_agent_prompts.up.sql create mode 100644 migrations/versioned/000119_agent_prompts.down.sql create mode 100644 migrations/versioned/000119_agent_prompts.up.sql diff --git a/client/mcp_service.go b/client/mcp_service.go index 269dd667..5ff543af 100644 --- a/client/mcp_service.go +++ b/client/mcp_service.go @@ -298,3 +298,36 @@ func (c *Client) ResolveToolApproval(ctx context.Context, pendingID string, req } return parseResponse(resp, &response) } + +// ResolveAgentPromptRequest answers a prompt an agent run is waiting on. Kind +// must match the prompt ("ask_user" or "tool_approval"); Response is the +// kind's answer, e.g. {"text": "..."} or {"selected": ["..."]} for ask_user, +// {"approved": true} or {"approved": false, "reason": "..."} for +// tool_approval (approval may add "modified_args": {...}). Unknown fields are +// rejected. +type ResolveAgentPromptRequest struct { + Kind string `json:"kind"` + Response json.RawMessage `json:"response"` +} + +// ResolveAgentPrompt answers a pending agent prompt by id. Resumed reports +// that the run had been suspended and now continues in the background; its +// output lands in the same assistant message. +// Server route: POST /api/v1/agent/prompts/{prompt_id}. +func (c *Client) ResolveAgentPrompt( + ctx context.Context, promptID string, req *ResolveAgentPromptRequest, +) (resumed bool, err error) { + path := fmt.Sprintf("/api/v1/agent/prompts/%s", promptID) + resp, err := c.doRequest(ctx, http.MethodPost, path, req, nil) + if err != nil { + return false, err + } + var response struct { + Success bool `json:"success"` + Resumed bool `json:"resumed"` + } + if err := parseResponse(resp, &response); err != nil { + return false, err + } + return response.Resumed, nil +} diff --git a/config/builtin_agents.yaml b/config/builtin_agents.yaml index fcea1242..93ee8f76 100644 --- a/config/builtin_agents.yaml +++ b/config/builtin_agents.yaml @@ -79,6 +79,7 @@ builtin_agents: - "read_document" - "list_documents" - "query_knowledge_graph" + - "ask_user" web_search_enabled: true web_search_max_results: 5 reflection_enabled: false @@ -126,6 +127,7 @@ builtin_agents: allowed_tools: - "data_schema" - "data_analysis" + - "ask_user" web_search_enabled: false web_search_max_results: 0 reflection_enabled: true diff --git a/docs/design/agent-hitl-suspend-resume.md b/docs/design/agent-hitl-suspend-resume.md new file mode 100644 index 00000000..e4db100a --- /dev/null +++ b/docs/design/agent-hitl-suspend-resume.md @@ -0,0 +1,467 @@ +# Agent 人工交互(HITL):两段式挂起与恢复 + +状态:草案(P1 已实现) 关联:issue #1173(MCP 工具人工审批) + +## 0. 范围:通用人工交互,而不只是工具审批 + +“Agent 停下来等人”有多种形态,本设计把它们统一成一个模型:**交互请求(prompt)**。一条交互请求有类型(`kind`)、请求载荷(`request`)和用户回答(`response`),由通用核心 `internal/agent/hitl.Broker` 负责持久化、等待、跨副本投递和挂起恢复;各类型只提供载荷结构、回答校验和前端卡片。 + +| kind | 场景 | 回答 | 可挂起(`suspendable`) | +|---|---|---|---| +| `tool_approval` | MCP 工具执行前审批 | 批准/拒绝、修改后的参数、理由 | 是 | +| `mcp_oauth` | MCP 服务需要用户先完成 OAuth 授权 | 已授权/放弃 | 是 | +| `ask_user`(规划) | Agent 主动向用户提问,弹窗或表单收集答案 | 按问题的 schema 填写 | 是 | +| MCP elicitation(规划) | MCP 服务端在工具调用**进行中**向用户索取输入 | 按 elicitation schema | **否** | +| 浏览器人工接手(规划) | 登录、验证码等需要人在浏览器里操作 | 完成/放弃 | **否** | + +**可挂起的边界**:交互发生在外部调用**之前**(审批、OAuth、提问),运行可以安全地落库结束,之后从快照恢复;交互发生在外部调用**进行中**(elicitation 期间 MCP 会话和工具调用都开着;浏览器接手依赖副本上的连接),运行状态无法序列化,只能在内存里短等待,超时即按失败处理。记录上的 `suspendable` 标记由发起方填写,Broker 据此决定短等待到期后是挂起还是关闭。 + +下文以工具审批为主线描述流程,其他可挂起的类型走完全相同的路径,只是“恢复时如何把回答交给被阻塞的调用”不同(见 6.1 的 `PreDecided`)。 + +## 1. 背景与目标 + +当前 `approval.Gate.RequestAndWait` 是同步阻塞式审批:Agent 运行的 goroutine 原地等待,进程内存里保存着完整的 ReAct 状态,等待上限默认 10 分钟(`tool_approval_timeout_seconds`)。这带来四个限制: + +1. 超时只是防止 goroutine 泄漏的保险丝,无法支持“第二天再审批”。 +2. waiter 只在进程内存里,发版、OOM、Pod 调度后待审批状态全部丢失。 +3. `AgentSteps` 只在轮次结束时由 `handleComplete` 写库,等待期间进程崩溃会丢掉整轮已完成的步骤。 +4. 等待期间会话一直处于“运行中”。 + +目标: + +- 用户就在旁边时体验不变:短时间内仍在内存里等待,零额外延迟。 +- 超过短等待阈值后,把运行状态持久化并结束本次运行,释放 goroutine 和会话占用。 +- 用户任意时间(在过期时间内)批准或拒绝后,由任意副本发起一次新的运行,接着执行被打断的那一轮,然后继续 ReAct 循环,输出写入**同一条**助手消息。 +- 多副本部署下正确:状态以数据库为准,Redis 只用于唤醒和事件流。 + +不在本期范围: + +- 非阻塞的延迟审批模式(工具立即返回“待审批”)。它依赖本设计的基础设施,以后作为个别工具的可选模式单独设计。 +- 内置工具的审批(审批仍只接入 MCP 工具)。 +- MCP elicitation 与浏览器人工接手的具体接入(只保证模型能承载它们,见第 0 节)。 + +## 2. 现状要点(设计依据) + +| 事实 | 位置 | 对设计的影响 | +|---|---|---| +| 引擎跨轮无状态,`Execute` 总是追加一条新 user 消息并从第 0 轮开始 | `internal/agent/engine.go:326` | 需要新增恢复入口,不能复用 `Execute` | +| 本轮 user 内容经 `RenderUserTurnContent` 渲染(含 runtime context),不落库;渲染结果含本次请求 Registry 的 cN/dN 句柄 | `internal/agent/observe.go:1032` | 快照保存原始 query 与图片 URL,恢复时用新 Registry 重新渲染 | +| step 在一轮工具全部结束后才 append;此前只在局部变量里 | `engine.go:1056` | 需要引擎显式跟踪“进行中的一轮” | +| MCP 工具不在 `CanRunConcurrently` 白名单,是并行执行中的屏障 | `act.go:306-316` | 同一时刻一次运行最多只有一个待审批调用 | +| `response.ToolCalls` 的参数含 cN/dN/res:// 等临时句柄,在 `runToolCall` 里才解码 | `act.go:418` 起、`internal/modelcontext/registry.go` | 未执行调用的参数必须在挂起时用当前 Registry 解码后再持久化 | +| `LoadAgentHistory` 只回放 `IsCompleted=true` 的轮次 | `agent_history.go:237` | 挂起的轮次不会进入后续轮次的历史,恢复时由快照提供 | +| `Message` 没有状态字段;仓储 `Updates(struct)` 跳过零值 | `internal/types/message.go`、`repository/message.go:263` | 新增 `run_state` 列和列级更新方法 | +| 引用由 handler 在 `EventAgentReferences` 上累积;complete 时仅非空才覆盖 | `agent_stream_handler.go:712` 起 | 恢复时 handler 要以已持久化的引用为初值 | +| live-run 标记在 StreamManager,`SetLiveRun` 是 SetNX,`ClearLiveRun` 是 CAS | `internal/stream/redis_manager.go:358-496` | 直接复用为会话级互斥 | +| 事件流 key 为 `{prefix}:{session}:{message}`,TTL 1h;没有清空接口 | `interfaces/stream_manager.go` | 需要新增 `ResetEvents` | +| asynq 仅在 `REDIS_ADDR` 非空时启用;否则为进程内 `SyncTaskExecutor`(不做 TaskID 去重) | `internal/container/container.go:442-473` | 去重不能只靠 TaskID,必须叠加数据库 CAS | +| 沙箱绑定在 Redis,客户端为远程接口;每条退出路径都会给 `/workspace` 打检查点 | `internal/sandbox/session_binding_redis.go`、`agent_stream_handler.go:754` | 挂起路径同样打检查点,恢复时沙箱已回收则从检查点还原 | +| 前端刷新后从 `agent_steps` 重建时间线,不会还原审批卡片;`is_completed=false` 会立即调用 `continue-stream` | `useChatStreamHandler.ts:324-472`、`chat/index.vue:949-984` | 前端需要识别新状态,并从持久化数据渲染卡片 | + +## 3. 总体方案 + +一次交互经历两个阶段: + +- **短等待阶段(hot)**:与现在一致,运行 goroutine 在内存里等待,默认最长 120 秒。用户在此期间回答,结果直接投递给 waiter,运行原地继续。 +- **挂起阶段(suspended)**:超过短等待阈值后,可挂起的交互把运行状态落库,运行以 `awaiting_input` 结束。用户回答后,由恢复任务在任意副本上重建引擎,继续执行。不可挂起的交互在短等待到期后直接关闭为 `expired`。 + +进入交互的那一刻(而不是超时时)就把完整快照写库。因此短等待阶段的进程崩溃也能被回收任务转成挂起状态,不丢步骤。 + +```mermaid +stateDiagram-v2 + [*] --> pending: 进入交互,写快照,持有租约 + pending --> answered: 用户回答(任意副本 CAS) + pending --> suspended: 短等待超时且可挂起(持有者 CAS)\n或租约过期(回收任务 CAS) + pending --> expired: 短等待超时且不可挂起 + pending --> canceled: 用户停止运行 + suspended --> answered: 用户回答 + suspended --> superseded: 用户发新消息 / 回溯 / 删除会话 + suspended --> expired: 超过过期时间(回收任务) + answered --> executing: 回答需要触发外部副作用(如批准的工具调用) + answered --> done: 回答已交给模型(拒绝、OAuth、提问) + executing --> done: 工具结果已持久化 + executing --> failed: 执行中断,结果未知 + done --> [*] + failed --> [*] + canceled --> [*] + superseded --> [*] + expired --> [*] +``` + +`answered` 只表示“用户已回答”,回答内容(批准还是拒绝、填了什么)在 `response` 里,与“由谁继续执行”无关:如果持有者 waiter 还活着,就由它在内存中继续;否则由恢复任务继续。系统侧关闭(超时、取消、取代)的原因写在 `close_reason`,与用户回答分开存放。 + +## 4. 数据模型 + +### 4.1 新表 `agent_prompts` + +一条记录对应一次交互请求(主键即现有前端字段 `pending_id`)。与类型相关的内容全部放在 `request` / `response` 两个 JSON 列里,新增类型不需要改表。 + +| 列 | 类型 | 说明 | +|---|---|---| +| `id` | varchar(36) PK | 即 `pending_id` | +| `tenant_id` | bigint | 发起运行的租户(执行租户) | +| `user_id` | varchar | 会话所有者,Resolve 授权用;记录上有值时调用方必须是同一用户(调用方为空视为不匹配),记录上为空时只校验租户(与原审批行为一致) | +| `session_id` | varchar(36) | Resolve 时与路由中的会话比对 | +| `assistant_message_id` | varchar(36) | | +| `request_id` | varchar | 发起运行的 request id,用于追踪 | +| `kind` | varchar(32) | `tool_approval`、`mcp_oauth`,后续 `ask_user` 等;Resolve 时与接口声明的类型比对 | +| `tool_call_id` | varchar | 被阻塞的工具调用 | +| `suspendable` | boolean | 见第 0 节 | +| `request` | jsonb / text | 类型相关的请求载荷,例如审批的服务、工具名和**已解码**参数(不含临时句柄) | +| `response` | jsonb / text | 用户回答,例如 `{approved, modified_args, reason}` | +| `status` | varchar(32) | 见第 3 节状态机 | +| `close_reason` | text | 系统侧关闭的原因(超时、取消、取代) | +| `resolved_by` | varchar | 作答的用户 | +| `resolved_at` | timestamptz | | +| `owner_instance` | varchar | 当前等待或恢复运行的唯一所有权令牌(同一副本接管时也更换) | +| `lease_until` | timestamptz | 持有者租约,持有者每 10s 续约 | +| `expires_at` | timestamptz | 挂起后的过期时间;为空表示不过期 | +| `created_at` / `updated_at` | timestamptz | | + +索引: + +- `(session_id, status)`:新消息到来时查找待处理的交互。 +- `(status, lease_until)`、`(status, expires_at)`:回收任务扫描。 +- `(assistant_message_id)`。 + +各类型的载荷结构定义在 `internal/types/agent_prompt.go`(如 `ToolApprovalPromptRequest` / `ToolApprovalPromptResponse`),回答校验函数通过 `Broker.RegisterKind` 注册;未注册的类型一律拒绝回答。 + +### 4.2 新表 `agent_run_suspensions` + +一条记录对应一条处于挂起或执行中的助手消息,保存恢复所需的全部运行状态。与交互表分开,原因是交互表承载“回答”,这张表承载“运行状态”,生命周期不同:恢复完成后快照即可删除,交互记录作为审计保留。 + +| 列 | 类型 | 说明 | +|---|---|---| +| `assistant_message_id` | varchar(36) PK | | +| `tenant_id` / `session_id` | | | +| `prompt_id` | varchar(36) | 当前阻塞它的交互 | +| `snapshot_version` | int | 快照格式版本,当前为 1 | +| `snapshot` | jsonb / text | 见 4.4 | +| `created_at` / `updated_at` | timestamptz | | + +### 4.3 `messages` 表新增列 + +| 列 | 类型 | 说明 | +|---|---|---| +| `run_state` | varchar(32),默认 `''` | `''` 表示沿用 `is_completed` 语义;`awaiting_input` 表示已挂起,等待用户回答 | + +挂起的消息:`is_completed=false`、`run_state='awaiting_input'`、`agent_steps` 为挂起前已完成的步骤(供展示)。 + +新增仓储列级方法,避免 `Updates(struct)` 跳过零值: + +- `MarkMessageAwaitingInput(ctx, sessionID, messageID, steps, refs, usage, sandboxCheckpoint)` +- `ClearMessageRunState(ctx, sessionID, messageID)` + +`SessionHasIncompleteAssistant`(回溯时判断会话是否忙碌)改为排除 `run_state='awaiting_input'`,由回溯流程先取代挂起再继续(见 8.3)。 + +### 4.4 快照格式(版本 1) + +定义在 `internal/agent/suspend.go`: + +```go +type RunSnapshot struct { + Version int `json:"version"` + // 调用方的 types.ResumableAgentRequest(只存持久标识) + Request json.RawMessage `json:"request,omitempty"` + // 原始 query 与图片 URL;恢复时用新 Registry 重新渲染本轮 user 消息 + Query string `json:"query"` + ImageURLs []string `json:"image_urls,omitempty"` + + // 已完成的轮次,与将来写入 Message.AgentSteps 的内容一致 + CompletedSteps []types.AgentStep `json:"completed_steps"` + KnowledgeRefs []*types.SearchResult `json:"knowledge_refs,omitempty"` + CurrentRound int `json:"current_round"` + TurnUsage types.TokenUsage `json:"turn_usage"` + + // 被打断的那一轮 + PendingRound PendingRound `json:"pending_round"` +} + +type PendingRound struct { + // 本轮的 thought / reasoning;ToolCalls 只含阻塞调用之前已完成的调用 + Step types.AgentStep `json:"step"` + // 模型在这一轮发出的全部调用,参数均为已解码的持久形式 + Calls []PendingCall `json:"calls"` + // 被交互阻塞的调用下标,之后的调用尚未执行 + BlockedIndex int `json:"blocked_index"` +} + +type PendingCall struct { + ID string `json:"id"` // 已规范化 + Name string `json:"name"` + Arguments string `json:"arguments"` // 已解码 + UnresolvedHandles []string `json:"unresolved_handles,omitempty"` + ProviderMetadata types.ToolCallMetadata `json:"provider_metadata,omitempty"` +} +``` + +`types.ResumableAgentRequest` 保存原始 Query、AgentID、SummaryModelID、ReasoningEffort、SharedAgentReadOnly、KnowledgeBaseIDs、KnowledgeIDs、TagScopes、MCPServiceIDs、SkillNames、WebSearchEnabled、QuestionOrigin、UserMessageID、Language。会话、附件和图片在恢复时从存储重新读取;本机浏览器连接绑定在某个副本的 WebSocket 上,恢复时一律视为不可用。`AgentTenantID`(P3 新增)记录智能体所属工作区,用来在恢复时解析共享智能体。快照中的 `UserMessages` 保存 `UserMessagesBefore` 引用的补充消息正文,恢复时按原轮次边界插入;旧快照缺少正文时,从同一会话的消息记录补齐。已消费事件仍由 steer 列表中的 consumed 标记去重。 + +**临时句柄的处理(关键)**:模型输出里的 cN/dN/res:// 句柄只在本次运行的 `modelcontext.Registry` 中有效,恢复后 Registry 是新建的,编号可能不同。本轮 user 消息和工具结果在发给模型前都被编码过,所以快照里不存渲染后的消息,只存原始 query 和已解码的步骤。`think.go` 在拿到模型响应时已经对 `response.ToolCalls` 执行 `DecodeToolCalls`,`Function.Arguments` 即解码后的参数(`ModelArguments` 不落库),快照直接保存它和 `UnresolvedHandles`。恢复时跳过解码步骤;`UnresolvedHandles` 非空的调用照旧在执行前失败。 + +已完成步骤里的 thought、工具参数和结果本来就以解码后的形式存储(`modelcontext` 的约定是“模型输出在被工具、存储、UI 消费前先解码”)。恢复后每次调用 LLM 前 `EncodeMessages` 会重新编码,编号一致性由新 Registry 自己保证。 + +恢复 MCP 工具注册表时,同时读取已完成历史和挂起轮次中已发出的调用,确保首次调用的延迟加载工具也能重建。 + +## 5. 后端流程 + +### 5.1 进入交互(持有者,短等待阶段) + +分两层:通用核心 `hitl.Broker.Await(ctx, Spec)` 负责持久化与等待;各类型的适配层负责构造载荷、发出类型专属事件、解释回答。工具审批的适配层是 `approval.Gate`,`MCPTool.Execute` 判断需要审批后调用 `Gate.RequestAndWait`,后者构造 `ToolApprovalPromptRequest` 再调用 `Broker.Await`。`Broker.Await` 的步骤: + +1. 调用方通过 `ToolExecContext.Snapshot` 取得当前运行快照(见 6.1),放进 `Spec.Suspend`。取快照失败时不挂起,退回内存等待。 +2. 有快照时先写 `agent_run_suspensions`,再写 `agent_prompts`(`status=pending`、`suspendable=true`、`owner_instance`、`lease_until=now+30s`)。两步不在同一事务里:快照先落库,回收任务看到交互记录时快照一定已存在;交互记录写失败时快照随后被删除。交互没有以挂起结束(回答、超时、取消、写库失败)时,`Await` 退出前按 `(assistant_message_id, prompt_id)` 条件删除快照,不会误删同一消息上更新的快照。 +3. 本地登记 waiter,调用适配层的 `Emit` 发出事件(工具审批仍是 `tool_approval_required`,新增字段 `hot_wait_seconds`;`timeout_seconds` 保留为同一值,兼容旧前端)。 +4. 等待以下任一事件: + - Pub/Sub 唤醒(频道 `weknora:agent_prompt:wake`):从数据库读取回答,以数据库为准。 + - 每 3 秒轮询一次数据库状态,兜底 Pub/Sub 丢消息。 + - 短等待计时器到期:可挂起时执行 `pending → suspended` 的 CAS,同时写入 `expires_at`;不可挂起时执行 `pending → expired`。CAS 失败说明用户刚好回答,转为读取回答。 + - ctx 取消(用户停止):执行 `pending → canceled` 的 CAS。失败同样转为读取回答。 +5. 后台每 10 秒续约 `lease_until`,续约 CAS 同时校验可续约状态和本次运行的 `owner_instance` 令牌。 +6. 拿到回答后由适配层 `Consume`,CAS 必须匹配本次运行的所有权令牌且成功后才能继续。失去所有权的等待者退出,不再落库或发布完成事件。存储出错不算失去所有权:先重试,必要时重新读取记录确认同一所有者的目标状态已落库。仍为 answered 或读取失败时返回存储错误,不执行工具;按所有权令牌尽力关闭交互,并走普通失败收尾、发布失败事件,避免错误地 detach 后遗留未完成消息: + - 需要外部副作用(批准的工具调用):CAS `answered → executing`,执行工具,再 CAS `executing → done`(`MarkExecuted`),删除快照。 + - 其他(拒绝、OAuth、提问):CAS `answered → done`,把回答交给调用方,删除快照。 + - 挂起:返回带 `Suspend` 标记的结果(见 6.2),引擎停止本轮并结束运行。 + +关闭挂起功能时(`prompt_suspend_enabled=false`),第 4 步的短等待计时器使用原有的 `tool_approval_timeout_seconds`,到期后按现在的逻辑记为超时。数据库记录照样写,便于审计和跨实例 Resolve。 + +P1 已实现第 2 至 6 步中除快照与挂起以外的部分:超时一律关闭为 `expired`。P2 补上了快照与挂起:只有 HTTP 流式入口(Web、嵌入页、API)的请求设置 `QARequest.Suspendable`,并且开关打开时,引擎才提供 `Snapshot`;IM 与 MCP server 入口不设置,仍按原有超时阻塞。持有者在短等待中发现记录已被回收任务改为 `suspended`(自己的租约已过期),同样按挂起返回。 + +### 5.2 用户回答(任意副本) + +现有接口 `POST /agent/tool-approvals/{pending_id}` 与 MCP OAuth 回调保留,内部都走 `Broker.Resolve`。通用接口 `POST /agent/prompts/{prompt_id}`(嵌入页为 `POST /embed/.../sessions/{session_id}/prompts/{prompt_id}`)的请求体为 `{kind, response}`,`response` 是该类型的回答(P4.5 已实现)。它接受 `ask_user` 与 `tool_approval`;`mcp_oauth` 只能经 OAuth 回调完成,按 400 拒绝。旧接口作为兼容层保留。`Broker.Resolve` 的步骤: + +1. 按 id 读取记录。`kind` 与接口声明的类型不符、`session_id` 与路由中的会话不符时,一律返回 `not_found`,不暴露记录存在与否。再校验 `tenant_id` 和 `user_id`(调用方 userID 为空视为不匹配)。嵌入页接口额外校验 channel 与 session 的归属。 +2. 调用该类型注册的校验函数。两类回答都拒绝未知字段。工具审批:回答为 `{approved, modified_args?, reason?}`,`approved` 必填;`modified_args` 只在批准时生效,必须是 JSON 对象;P2 起再按工具的 InputSchema 校验,工具定义取自 MCP 元数据快照,取不到就拒绝请求。提问:按问题的 schema 校验。校验失败返回 400。 +3. 记录仍为 `pending` 但持有者租约已过期(持有者已退出、回收任务尚未扫到)时,先按回收任务的规则把它转为 `suspended`(清空 `owner_instance`,并把消息改为等待输入),再走下面的 CAS,使这次回答直接恢复运行,而不是记给一个已经不存在的 waiter。 +4. 依次尝试两个 CAS,以区分之前的状态,同时兼容不支持 `RETURNING` 的场景: + - `UPDATE … SET status='answered', response=?, resolved_* WHERE id=? AND status='suspended' AND (expires_at IS NULL OR expires_at > now)`,同时生成新的 `owner_instance` 令牌并设置 `lease_until`,交给回答所在的副本。成功则由该副本恢复运行(5.4)。(P3 已实现) + - `UPDATE … WHERE id=? AND status='pending'`。成功则通过 Pub/Sub 唤醒持有者,不等待 ack,因为持有者会轮询数据库兜底。(P1 已实现) + - 两者都失败:重新读取记录,返回 `already_resolved`、`expired` 或 `not_found`。 +5. 响应体新增 `resumed: bool`。为 `true` 时,前端需要从偏移 0 重新接入该消息的事件流(旧事件已被清空)。(P3 已实现于 `POST /agent/tool-approvals/{id}`;MCP OAuth 回调不会挂起,忽略恢复结果。) + +原先基于 Pub/Sub ack 的跨实例投递已在 P1 移除,Pub/Sub 只保留唤醒职责。 + +### 5.3 挂起并结束运行(持有者) + +引擎收到 `Suspend` 信号后(6.2)停止当前轮,跳过“合成最终答案”的路径,发出 `EventAgentComplete`,其中新增 `Suspended`(`*types.PromptSuspension`,含 `pending_id`、`kind`、`expires_at`)。 + +`AgentStreamHandler.handleComplete` 在 `Suspended` 时: + +- 不设置 `IsCompleted`,改为设置 `RunState=awaiting_input`;已完成步骤、引用、用量照常写入。 +- 照常打沙箱检查点。 +- **不**收集产物(artifacts),不补发兜底答案,留到恢复后真正完成时再处理。 +- 消息落库成功后,向事件流发布 `run_suspended` 事件(带 `pending_id`、`kind`、`expires_at`),再发布 `complete`(`data.suspended` 同样带挂起信息),让当前 SSE 正常结束。 + +外层 defer: + +- 落库只调用 `UpdateMessage`(`Updates` 会写入非空的 `run_state`),**不**写入聊天历史知识库、不生成追问建议、不记录长期记忆,这些留到恢复后完成时再做。 +- 处理 steer 队列:未消费的 `after` 类消息照常触发 `kickNextRunFromSteerBacklog`。新一轮启动时会按 8.1 取代这次审批,语义与“用户发了新消息”一致。未消费的 `inject` 类消息按 `after` 处理。下一轮清空 `Resume`,不重放上一轮快照。 +- `ClearLiveRun`。`liveAgentRun` 把 `awaiting_input` 的消息视为没有运行中的任务,残留的 live-run 标记会被清掉。 + +### 5.4 恢复运行(回答所在的副本) + +最初计划用 asynq 任务 `agent:resume_run` 投递恢复。实现时改为由回答请求所在的副本在进程内直接恢复,用交互记录的租约代替任务去重:`Resolve` 的 CAS 成功时该副本就持有了租约,恢复期间持续续约;副本中途崩溃时租约过期,由回收任务收尾(5.6 第 2 条)。这样不依赖 Redis 队列,单机和多机行为一致。 + +入口为 `session.Handler.ResumeSuspendedRun`,由 `MCPServiceHandler` 在 `resumed=true` 时调用,立即返回,运行在后台进行: + +1. `Broker.KeepLease` 按新的所有权令牌续约,直到运行结束或交互离开 answered / executing。先等待旧运行落库并释放 live-run 标记;旧持有者失联或其租约到期后,从持久快照恢复尚未落库的等待消息,再清理残留标记。 +2. 读取快照,确认属于该交互;从快照的 `Request` 解出 `ResumableAgentRequest`,恢复语言设置。 +3. 用回答请求的身份(已在 `Resolve` 中校验为会话所有者)读取会话和助手消息,消息必须仍是 `awaiting_input` 且未完成;用 `AgentID` 和 `AgentTenantID` 重新解析智能体(共享智能体按原工作区解析)。 +4. 把消息的 `run_state` 清空后再发布 live run:`liveAgentRun` 把 `awaiting_input` 视为空闲,不先清空的话恢复中的运行会被当成残留标记清掉。 +5. `StreamManager.ResetEvents` 清空该消息的事件列表(steer 列表保留)。恢复请求沿用原始 Query 和 RequestID,确保记忆、追问和历史分组保留本轮语义。 +6. 以 `skipSSE=true` 走 `executeQA`,和 steer 接力的服务端发起运行同一路径:会话互斥、沙箱 turn lease、`setupSSEStream`、完成落库都复用。`setupSSEStream` 在 `agent_query` 之后追加 `run_resumed`。`AgentQA` 看到 `QARequest.Resume` 时调用 `engine.Resume` 而不是 `Execute`。 +7. 运行结束后检查交互:仍是 `answered` 说明运行在执行工具之前就失败了(会话被占用、智能体加载失败等),此时把交互标记为 `failed`,并按 5.6 的方式收尾消息;否则按 `(assistant_message_id, prompt_id)` 条件删除快照。再次挂起时新快照属于新的交互,不会被删除。 +8. 第 2、3 步失败(快照缺失、智能体已删除、消息状态不符)时同样标记 `failed` 并收尾消息。 + +`run_resumed` 只包含 `pending_id`。挂起前的步骤不重放,前端保留已经显示的部分,再追加恢复后的事件;完成事件里的 `agent_steps` 是完整列表。 + +### 5.5 工具至多执行一次 + +- 被阻塞的调用拿到回答时 CAS `answered → executing`(批准)或 `answered → done`(拒绝),工具执行结束后 `executing → done`。 +- 恢复运行的副本在 `executing` 期间失联:回收任务把交互标记为 `failed`,消息收尾时该调用写为“结果未知”,**不重放**工具。 +- 恢复失败(智能体不可用等,发生在执行工具之前):当场标记为 `failed` 并收尾,不重试。 + +### 5.6 回收任务 + +复用 housekeeping 的 cron 方式,每分钟执行一次。租约过期后的状态更新同时校验扫描时的所有权令牌和当前租约仍已过期,避免误回收扫描后续约或接管的运行: + +1. `status='pending' AND lease_until < now`:持有者已失联。可挂起且快照属于该交互时,CAS 为 `suspended`(写入 `expires_at`),用快照的 `DisplaySteps()` 覆盖消息的 `agent_steps` 并标记为 `awaiting_input`;否则 CAS 为 `expired`。快照在进入审批时已经写入,此处直接可用。(P2 已实现,由容器里每分钟一次的 `AgentPromptReaper` 执行;开关关闭时同样运行,用来关闭崩溃遗留的 pending 记录。) +2. `status IN ('answered','executing') AND lease_until < now` 且快照仍属于该交互:恢复运行的副本已失联。CAS 为 `failed`,消息收尾为已完成,被阻塞的调用及之后的调用写为失败(`executing` 时说明结果未知),删除快照。短等待中回答的交互快照已被持有者删除,不受影响。 +3. `status='suspended' AND expires_at < now`:CAS 为 `expired`,消息收尾为已完成(不调用 LLM),被阻塞的调用及之后的调用写为“已过期”,删除快照。 + +收尾由 `service.SuspendedRunService` 统一完成(回收任务、8.1 取代、恢复失败共用):步骤取 `RunSnapshot.ClosedSteps(reason)`,保证每个 tool_call 都有结果;`IsCompleted=true`、`run_state` 清空。`UpdateMessage` 单独写 `run_state` 列,因为 GORM 的 `Updates` 会跳过空字符串。正文不追加说明文字,原因写在失败的工具结果里。(P3 已实现第 2、3 条。) + +租约和过期时间由应用侧时钟写入和比较(Postgres 与 SQLite 的时间表达式不通用)。部署要求各副本通过 NTP 校时;30 秒租约配合 10 秒续约,足以容忍常见的秒级时钟偏差。 + +## 6. 引擎改动 + +### 6.1 跟踪进行中的一轮 + +`AgentEngine` 新增 `roundProgress`,用互斥锁保护: + +- 在 `executeToolCalls` 之前登记本轮的 thought、reasoning 和完整的 `response.ToolCalls`。 +- 顺序路径和并行路径在每个调用完成时写入结果。并行路径中 MCP 调用是屏障,执行到它时,之前的调用都已经完成(`g.Wait()`),所以快照是确定的。 +- `snapshot(blockedIndex)` 生成 `RunSnapshot`;阻塞调用之前有未完成的调用时报错(此时不挂起)。参数本来就是解码后的形式(4.4)。 + +`ToolExecContext` 新增两个字段: + +- `Snapshot func() ([]byte, int, error)`:返回编码后的快照和格式版本;运行不可挂起时为 nil。(P2) +- `Answered *types.AgentPrompt`:恢复时传给被阻塞的那个调用(按 `tool_call_id` 匹配),即已回答的交互记录。发起交互的工具见到它就跳过等待,由各自的适配层把 `response` 解释为结果:`MCPTool.Execute` 仍执行开头的 `IsEnabled` 校验(管理员在此期间禁用了工具时以禁用为准),然后通过 `Gate.ResumeDecision` 得到审批决定并发出 `tool_approval_resolved`。即使工具此后不再需要审批,也按用户的决定执行,因为用户可能修改了参数。`ask_user` 直接把答案作为工具结果返回。(P3 已实现 MCP 部分。) + +能发起可挂起交互的工具都必须是并行执行中的屏障(MCP 工具已经是,`ask_user` 不进 `CanRunConcurrently` 白名单),这样一次运行同一时刻最多只有一个阻塞中的交互,快照才是确定的。 + +### 6.2 挂起信号 + +`types.ToolResult` 新增 `Suspend *types.PromptSuspension`(`json:"-"`)。 + +- 顺序路径:调用返回 `Suspend` 后,后面的调用不再执行,被阻塞的调用不 append、不发 tool_result 事件,`executeToolCalls` 返回该挂起信息。 +- 并行路径:在屏障调用返回后检查标记,先按原顺序 append 并发出之前已完成的调用,再停止。 +- `runReActIteration` 收到后不把本轮 step 并入 `RoundSteps`、不再调用 LLM,记入 `state.Suspended` 与 `state.SuspendedStep` 后退出循环;`executeLoop` 跳过 `handleMaxIterations`。 +- `emitCompletionEvent` 在挂起时带 `RoundSteps` 加上被打断那一轮已完成的部分(`SuspendedStep`),供消息展示。 + +### 6.3 恢复入口 + +```go +func (e *AgentEngine) Resume( + ctx context.Context, + sessionID, messageID string, + llmContext []chat.Message, + snapshot []byte, + answered *types.AgentPrompt, +) (*types.AgentState, error) +``` + +快照以字节传入并在引擎内解码,`interfaces.AgentEngine` 因此不需要引用 `agent` 包。`answered.ToolCallID` 必须与快照中被阻塞的调用一致,否则拒绝恢复。 + +1. 消息列表:system(重新计算)+ `llmContext` + `snap.UserTurn` + 由 `snap.CompletedSteps` 经 `appendToolResults` 展开的消息。 +2. 在完整消息列表上调用 `RememberMCPHistory`,恢复本轮已经 describe 或调用过的 MCP 工具,再 `RefreshMCPTools`。 +3. `state` 初始化:`RoundSteps = snap.CompletedSteps`、`CurrentRound = snap.CurrentRound`、`TurnUsage = snap.TurnUsage`。 +4. 完成被打断的那一轮: + - 已有结果的调用直接沿用。 + - 被阻塞的调用以 `PreAnswered=answered` 执行。 + - 之后的调用使用解码后的参数按原顺序**顺序**执行(剩余调用通常很少,顺序执行天然满足屏障规则)。其中的调用可能再次发起交互乃至再次挂起:此时直接发出带 `Suspended` 的完成事件并返回,按 5.3 处理。 + - 发出与正常执行相同的 tool_call / tool_result 事件,然后 append step。 +5. 进入正常的 `executeLoop`,从下一轮开始。 + +`executeLoop` 本身就接受初始状态和消息列表,`Resume` 直接调用它。 + +## 7. 事件与接口变更 + +| 变更 | 说明 | +|---|---| +| 新事件 `agent_prompt_required` / `agent_prompt_resolved` | 通用交互事件,`{pending_id, kind, request, tool_call_id, timeout_seconds, hot_wait_seconds, suspendable, requested_at}` / `{pending_id, kind, answered, response, reason, timed_out, canceled}`。目前只有 `ask_user` 使用;工具审批与 OAuth 仍只发各自的旧事件(P4.5 已实现) | +| `tool_approval_required` 新增 `hot_wait_seconds`、`suspendable` | 前端倒计时归零时显示“已转入后台等待”,而不是“已超时” | +| 新事件 `run_suspended` | `{pending_id, kind, expires_at}`,紧接着发 `complete` | +| 新事件 `run_resumed` | `{pending_id}`,紧跟在恢复运行的 `agent_query` 之后(P3 已实现) | +| `tool_approval_resolved` 新增 `superseded`、`expired` | | +| 新接口 `POST /agent/prompts/{prompt_id}`(含嵌入页版本) | 请求体 `{kind, response}`,响应含 `resumed`;SDK 方法 `Client.ResolveAgentPrompt`(P4.5 已实现) | +| `POST /agent/tool-approvals/{id}` 响应新增 `resumed` | 保留为兼容层;嵌入页接口同步 | +| 消息列表接口:消息新增 `run_state`、`pending_prompt` | `pending_prompt` 只对会话所有者返回,包含卡片所需字段和 `expires_at` | +| 新增 `StreamManager.ResetEvents` | Redis 实现为 `DEL` 事件列表;memory 实现为清空事件切片。两者都保留 steer 列表(P3 已实现) | + +API 文档、Swagger、`client/` SDK 同步更新(按 `weknora-api-docs-sync` 流程处理)。 + +## 8. 会话级语义 + +### 8.1 挂起期间用户发新消息 + +`executeQA` 在 `rejectIfOtherAgentRunLive` 和回溯检查之后、`holdQATurn` 之前(恢复运行本身跳过这一步;steer 接力的新一轮同样会取代): + +1. 查找本会话 `status='suspended'` 的交互,CAS 为 `superseded`。 +2. 把对应消息收尾为已完成:被阻塞的调用及之后的调用结果写为“用户未回答就继续了对话”,补成一个完整的 step,正文不变,然后删除快照。(P3 已实现,见 `SuspendedRunService.SupersedeSession`。) +3. 这样新一轮的 `LoadAgentHistory` 能看到完整、合规的上一轮(每个 tool_call 都有对应的 tool 结果)。 + +前端提示语明确说明“发送新消息会放弃待处理的操作”。`ask_user` 例外:卡片上可直接作答;如果用户选择在输入框回复,按普通新消息处理(取代该提问),模型在新一轮的历史里能看到问题和新消息。 + +### 8.2 用户停止 + +- 短等待阶段:与现在一致,按 `canceled` 处理。 +- 挂起阶段:没有运行中的任务,界面不显示停止按钮;用户可直接点拒绝。 + +### 8.3 回溯、分叉、删除 + +- 回溯:`SessionRewindService.Rewind` 在校验会话归属之后、读取回溯点之前按 8.1 取代挂起,再执行原有逻辑。(P3 已实现) +- 分叉:不取代。分叉只复制回溯点之前的消息,未完成的回溯点照旧被拒绝,源会话的挂起不受影响。 +- 删除消息或会话:不做专门处理。交互仍会在过期时被回收任务关闭;收尾时消息已不存在,只删除快照。 + +## 9. 前端改动 + +1. `handleMsgList`:消息 `run_state==='awaiting_input'` 时: + - 从 `agent_steps` 重建时间线,并在末尾追加由 `pending_prompt` 构造的交互卡片(按 `kind` 渲染); + - **不**调用 `continue-stream`,`isReplying=false`,输入框可用; + - 时间线不显示“进行中”的占位动画。 +2. 交互卡片按 `kind` 注册渲染组件(工具审批、OAuth 复用现有卡片,`ask_user` 为问题表单): + - 短等待阶段的倒计时归零后,文案改为“已转入后台等待,可稍后处理”,按钮仍然可用; + - 挂起阶段显示过期时间。 +3. 作答后,如果响应 `resumed=true`:设置 `isReplying=true`,对该消息调用 `continue-stream`。恢复任务的投递有延迟,404 时按 500ms 间隔重试,最多重试 10 次。从 `run_resumed` 事件开始追加到现有时间线,不替换已重建的步骤。 +4. `run_suspended`:结束当前流,卡片切换为挂起样式,`isReplying=false`。 +5. 挂起状态下发送新消息:先弹出确认提示,发送成功后刷新消息列表,旧卡片显示“已放弃”。 +6. 侧栏会话列表:可选显示“待处理”角标(第二期)。 +7. i18n:新增文案,按 `i18n-locale-align` 流程同步到全部语言。 + +## 10. 配置 + +| 配置项 | 默认值 | 说明 | +|---|---|---| +| `agent.prompt_suspend_enabled` | 未配置时为 `true`(P4 起) | 设为 `false` 恢复为纯阻塞式(仍写数据库记录);对所有可挂起类型生效。环境变量 `WEKNORA_AGENT_PROMPT_SUSPEND=true/false` 可覆盖 | +| `agent.prompt_hot_wait_seconds` | `120` | 短等待时长;`0` 取默认值 | +| `agent.prompt_expire_seconds` | `604800`(7 天) | 挂起后的过期时间;`0` 取默认值,负数表示不过期 | +| `agent.tool_approval_timeout_seconds` | `600` | 保留;仅在关闭挂起时作为阻塞上限 | + +部署检查:进程无法自行判断是否有多个副本,因此只在启动时对 `STREAM_MANAGER_TYPE=memory` 且 `REDIS_ADDR` 非空的组合打警告。配了 Redis 通常意味着多副本部署,而这种组合下副本之间的事件流和 live-run 标记不共享。 + +## 11. 安全 + +- Resolve 按资源鉴权:路由中的会话与接口声明的类型必须与记录一致(不一致按不存在处理,防止跨会话或跨类型作答),租户、会话所有者都必须匹配;嵌入页额外校验 channel 与 session。 +- 回答必须通过该类型注册的校验函数,未注册的类型一律拒绝。 +- `pending_prompt` 与请求载荷只返回给会话所有者,与现有 SSE 可见范围一致。 +- `modified_args` 按 InputSchema 校验,校验通过后完整替换原参数,不保留旧键(与现有逻辑一致)。 +- `ask_user` 的答案是用户输入,交给模型时按不可信数据包裹(与工具结果同等对待),不拼进系统提示。 +- 恢复时重新校验:工具是否启用、是否仍需审批、智能体是否仍可访问、会话是否仍属于该用户。任何一项不满足都不执行工具。 +- 快照只存持久 ID 和已解码参数,不存凭据;MCP 凭据在执行时按现有方式解析。 +- 过期、取代、停止都会留下交互记录,满足审计需要。 + +## 12. 内置提问工具 `ask_user` + +Agent 需要用户补充信息或做选择时调用,作为 P4 之后的单独一期。 + +- 参数中的 options 必须是逐项列出的字符串数组。合法的数组字符串仍可兼容解析;以 `[` 开头却无法解析的字符串不再包装成单个选项,选项数组内嵌的序列化列表同样被拒绝,并返回工具参数错误供模型重试。 +- 参数:`question`(必填),可选 `options`(单选或多选)、`fields`(简单表单,限定为文本、数字、单选、多选几种类型),以及 `allow_free_text`。参数 schema 严格限定,字段数与选项数设上限,防止模型生成超大表单。 +- 执行:构造 `kind='ask_user'` 的交互,走 `Gate.AskUser` → `Broker.Await`;有快照时短等待后挂起,否则阻塞到超时。回答校验按本次的 `fields` / `options` 检查必填项、类型与取值范围,未知字段一律拒绝。用户也可以选择“不回答”(`{"declined": true}`)。 +- 结果:答案按“The user answered. / Selected / Fields / Text”格式作为工具结果返回给模型;用户拒绝、超时或被取代时,返回明确的“用户未回答(原因)”,由模型决定下一步。工具结果的 `data` 同时保存问题与答案,历史重建时据此把这次调用渲染成已作答的卡片,而不是一行工具调用。 +- 挂起与恢复:与工具审批相同,恢复时通过 `ToolExecContext.Answered` 直接返回答案。 +- 非交互渠道:只有 Web 与嵌入页的 HTTP 流式问答标记为可交互(`QARequest.Interactive` → `engine.SetInteractive`)。API Key 调用方无法访问作答接口,因此即使能挂起审批也不算可交互。IM、API Key 等渠道调用时,工具不发卡片,直接告诉模型“在本轮回复里直接提问并结束本轮”;用户的下一条消息就是答案。 +- 开关:加入 `DefaultAllowedTools` 与内置智能体(智能推理、数据分析师)的工具列表;智能体配置中可取消勾选。显式配置了 `allowed_tools` 的自定义智能体需手动加入。 +- 前端:`AskUserCard` 按选项(单选/多选)、表单字段、自由文本渲染;与审批卡片共用倒计时与“已转入后台等待”逻辑(`usePromptCountdown`)。等待输入的消息不折叠步骤,卡片始终可见。 + +## 13. 分期实施 + +| 期 | 内容 | 对外行为变化 | +|---|---|---| +| P1 | 两张新表与 `messages.run_state` 迁移(Postgres 000119、SQLite 000037);通用核心 `hitl.Broker`(持久化、租约、轮询兜底、Pub/Sub 唤醒、按 kind 校验回答);工具审批与 OAuth 改为其上的适配层;Resolve 绑定 session 与 kind | 无,仍是阻塞式 | +| P2(已实现) | 引擎 `roundProgress`、快照、`Suspend` 信号;handler 挂起收尾;`run_suspended` 事件;回收任务第 1 条 | 超过短等待后挂起,但暂时无法恢复(功能开关默认关闭) | +| P3(已实现) | `engine.Resume`、进程内恢复与租约、`ResetEvents`、`run_resumed`;8.1 新消息与回溯取代;回收任务第 2、3 条;`SuspendedRunService` 统一收尾 | 后端功能完整(功能开关默认关闭,前端未适配) | +| P4(已实现) | 功能开关默认打开;消息列表为 `awaiting_input` 消息附带 `pending_prompt`(只对发起人可见,含卡片字段与 `expires_at`);前端处理 `run_suspended` / `run_resumed`,挂起卡片显示“已转入后台等待”与截止时间,回答返回 `resumed: true` 后 Web 端经 continue-stream 重新接上同一条消息(短暂重试等待恢复流出现),嵌入页无 continue-stream,改为轮询消息列表、结束后重新加载;发送新消息时挂起卡片显示“已放弃”;i18n | 工具审批可长时间挂起并在任意副本恢复 | +| P4.5(部分实现) | 已实现:`ask_user` 内置工具(第 12 节)及其表单卡片;通用接口 `POST /agent/prompts/{prompt_id}`(含嵌入页)与 SDK 方法。未实现:MCP OAuth 接入挂起(OAuth 仍只做阻塞等待) | Agent 可以向用户提问 | +| P5 | 文档、Swagger 产物重新生成(当前主干的 Swagger 产物已落后较多,单独提交) | | + +## 14. 测试要点 + +- 通用核心(P1 已覆盖):跨副本作答经数据库送达持有者;会话、类型、租户、用户绑定;未注册类型被拒;回答校验失败;回答与超时同时发生时回答胜出;超时与取消留下记录;`executing → done`。 +- 状态机:每条 CAS 转换的成功与失败分支,包括并发 Resolve、Resolve 与短等待超时同时发生、Resolve 与用户停止同时发生。 +- 快照:顺序路径和并行路径下,阻塞调用位于一轮的开头、中间、末尾;未执行调用含临时句柄时,恢复后参数正确。 +- 恢复:恢复后发给 LLM 的消息序列与未挂起时逐条一致(以 golden 测试固定);恢复中再次挂起;恢复时工具已被禁用;恢复时智能体已被删除。 +- 至多执行一次:在 `executing` 阶段模拟崩溃,重试时不重放。 +- 多副本:两个 Gate 实例共用一个数据库和 Redis,Resolve 打到非持有者;持有者在短等待阶段消失后,由回收任务转为挂起,再恢复。 +- 会话语义:挂起时发新消息、回溯、删除会话;历史重建结果合规。 +- 前端:刷新后卡片正确显示;批准后接入事件流;`run_suspended` / `run_resumed` 的渲染。 + +## 15. 已确认的决定 + +1. 短等待默认 120 秒,挂起后默认 7 天过期。 +2. 过期后不调用 LLM,直接收尾并附一行说明。 +3. 本期只对 Web、嵌入页、API 渠道开放挂起;IM 渠道(`Channel` 为 IM 类)保持阻塞式,不进入挂起分支(`ask_user` 在 IM 渠道的降级见第 12 节)。 +4. 挂起时 steer 队列里的消息按“新消息取代待处理的交互”处理。 +5. P1 直接做成通用的人工交互模型(`agent_prompts` + `hitl.Broker`),工具审批与 OAuth 是其上的适配层。 +6. `ask_user` 放进本次范围,作为前端一期之后的单独一期。 diff --git a/frontend/src/api/embed/index.ts b/frontend/src/api/embed/index.ts index d0f9c038..5afd9e7d 100644 --- a/frontend/src/api/embed/index.ts +++ b/frontend/src/api/embed/index.ts @@ -407,12 +407,31 @@ export async function resolveEmbedToolApproval( visitorId: string, pendingId: string, body: { decision: 'approve' | 'reject'; modified_args?: Record; reason?: string }, -): Promise { - 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, +): Promise<{ resumed: boolean }> { + const res: any = await post( + `/api/v1/embed/${channelId}/sessions/${encodeURIComponent(sessionId)}/prompts/${encodeURIComponent(promptId)}`, + { kind, response }, + { headers: embedSessionHeaders(token, sessionSig, visitorId) }, + ) + return { resumed: Boolean(res?.resumed) } } export async function getEmbedMessageList( diff --git a/frontend/src/api/mcp-service.ts b/frontend/src/api/mcp-service.ts index 2dd75841..7383c543 100644 --- a/frontend/src/api/mcp-service.ts +++ b/frontend/src/api/mcp-service.ts @@ -292,8 +292,22 @@ export async function revokeMCPOAuthToken(serviceId: string): Promise { export async function resolveToolApproval( pendingId: string, body: { decision: 'approve' | 'reject'; modified_args?: Record; reason?: string } -): Promise { - 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, +): Promise<{ resumed: boolean }> { + const res: any = await post(`/api/v1/agent/prompts/${encodeURIComponent(promptId)}`, { kind, response }) + return { resumed: Boolean(res?.resumed) } } // Resume an agent run that paused on an in-conversation MCP OAuth prompt. diff --git a/frontend/src/composables/useChatStreamHandler.suspend.test.ts b/frontend/src/composables/useChatStreamHandler.suspend.test.ts new file mode 100644 index 00000000..c5ee57f8 --- /dev/null +++ b/frontend/src/composables/useChatStreamHandler.suspend.test.ts @@ -0,0 +1,201 @@ +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import test from 'node:test' +import vm from 'node:vm' +import ts from 'typescript' +import * as vue from 'vue' +import * as finalContent from '../utils/finalArtifactContent.ts' +import * as history from '../utils/rag-pipeline-history.ts' +import * as timestamps from '../utils/messageTimestamp.ts' +import * as steering from '../utils/steerStreamFork.ts' +import type { useChatStreamHandler as StreamHandler } from './useChatStreamHandler.ts' + +const source = readFileSync(new URL('./useChatStreamHandler.ts', import.meta.url), 'utf8') +const compiled = ts.transpileModule(source, { + compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 }, +}).outputText +const modules: Record = { + 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[]>([]) + 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) => + (m.agentEventStream as Record[]).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[] + 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[]).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[]).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[]).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) => + (m.agentEventStream as Record[]).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[]).some( + (e) => e.type === 'tool_call' && e.tool_call_id === 'call-0', + )) + assert.equal(pending.pending_id, 'q2') + assert.equal(pending.suspended, true) + assert.equal(pending.request.question, 'Second?') + handler.prepareForNewOutgoingMessage() + assert.equal(prompts(m)[1].abandoned, true) +}) + +test('a prompt without display steps remains answerable after orphan recovery', async () => { + const { handler, messagesList } = setup() + const row = awaitingRow() + row.agent_steps = [] + await handler.handleMsgList([row]) + const message = messagesList[0] + assert.equal(message.isAgentMode, true) + assert.equal(message.is_completed, true) + assert.equal(cards(message).length, 1) + assert.equal(cards(message)[0].pending_id, 'p1') +}) diff --git a/frontend/src/composables/useChatStreamHandler.ts b/frontend/src/composables/useChatStreamHandler.ts index d5c6e184..46fe7ecd 100644 --- a/frontend/src/composables/useChatStreamHandler.ts +++ b/frontend/src/composables/useChatStreamHandler.ts @@ -50,6 +50,74 @@ function mergeToolCallArguments(previous: unknown, incoming: unknown): Record | undefined + if (!p?.id) return [] + const request = (p.request || {}) as Record + const createdAt = Date.parse(String(p.created_at || '')) + const requestedAt = Number.isNaN(createdAt) ? undefined : Math.floor(createdAt / 1000) + if (p.kind === 'ask_user') { + return [{ + type: 'agent_prompt_required', + pending_id: p.id, + kind: p.kind, + request, + tool_call_id: p.tool_call_id, + requested_at: requestedAt, + suspendable: true, + suspended: true, + expires_at: p.expires_at, + resolved: false, + }] + } + if (p.kind !== 'tool_approval') return [] + return [{ + type: 'tool_approval_required', + pending_id: p.id, + service_name: request.service_name, + mcp_tool_name: request.mcp_tool_name, + description: request.description, + args_json: request.args === undefined ? '' : JSON.stringify(request.args), + tool_call_id: p.tool_call_id, + requested_at: requestedAt, + suspendable: true, + suspended: true, + expires_at: p.expires_at, + resolved: false, + }] +} + +/** The card of an ask_user call that finished, from the stored tool result. */ +function askUserHistoryCard(toolCallId: string, data: ChatMessage): ChatMessage { + return { + type: 'agent_prompt_required', + pending_id: `history-${toolCallId}`, + kind: 'ask_user', + request: data.question, + tool_call_id: toolCallId, + resolved: true, + answered: Boolean(data.answered), + response: data.answer, + resolve_reason: data.reason, + timed_out: Boolean(data.timed_out), + canceled: Boolean(data.canceled), + } +} + export function useChatStreamHandler(options: UseChatStreamHandlerOptions) { const { t } = useI18n() const { @@ -130,11 +198,21 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) { if (msg.role === 'assistant' && !msg.is_completed) { markAssistantStopped(msg) } + if (msg.role === 'assistant' && isAwaitingInput(msg)) abandonPendingPrompts(msg) } fullContent.value = '' currentAssistantMessageId.value = '' } + /** A new message supersedes the prompt a suspended run waits on. */ + const abandonPendingPrompts = (msg: ChatMessage) => { + const stream = (msg.agentEventStream as ChatMessage[] | undefined) || [] + msg.agentEventStream = stream.map((e) => + isPromptCard(e) && !e.resolved ? { ...e, resolved: true, abandoned: true } : e, + ) + msg.run_state = '' + } + /** Mark the assistant row being stopped without clearing its id (stop API still needs it). */ const markInFlightAssistantStopped = (messageId?: string) => { let target: ChatMessage | undefined @@ -376,6 +454,10 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) { const result = toolCall.result as ChatMessage | undefined const resultData = result?.data as ChatMessage | undefined const target = toolCall.target as ChatMessage | undefined + if (resultData?.display_type === 'ask_user') { + events.push(askUserHistoryCard(String(toolCall.id || ''), resultData)) + return + } events.push({ type: 'tool_call', tool_call_id: toolCall.id, @@ -428,6 +510,26 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) { return events } + /** + * Readies a suspended message to stream again after its prompt was answered + * and the server resumed the run. The resumed stream carries only new events, + * so the timeline built from history stays and the blocked tool call is + * dropped: the resumed run reports it afresh. + */ + const prepareResumedMessage = (message: ChatMessage, pendingId: string) => { + const stream = (message.agentEventStream as ChatMessage[] | undefined) || [] + const card = stream.find((e) => isPromptCard(e) && e.pending_id === pendingId) + const blockedCall = card?.tool_call_id + message.agentEventStream = stream.filter((e) => { + if (e.type === 'agent_complete' || e.type === 'stop') return false + return !(blockedCall && e.type === 'tool_call' && e.tool_call_id === blockedCall) + }) + message._eventMap = new Map() + message._pendingToolCalls = new Map() + message.run_state = '' + message.is_completed = false + } + const handleMsgList = async ( data: ChatMessage[], isScrollType = false, @@ -443,6 +545,9 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) { if (item.id) existingIds.add(item.id) item.isAgentMode = false + // A run awaiting input has ended for now: nothing streams until its + // prompt is answered, so it renders as settled. + const awaiting = isAwaitingInput(item) const willContinueStream = preserveIncompleteStreamReactive && !item.is_completed if (willContinueStream) { item.agentEventStream = item.agentEventStream || [] @@ -471,6 +576,16 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) { if (agentStepsAreTruncated(item.agent_steps as unknown[])) item.truncated = true } + if (awaiting) { + item.isAgentMode = true + item.hideContent = true + item.agentEventStream = markRaw( + (item.agentEventStream as ChatMessage[]) + .filter((e) => e.type !== 'agent_complete') + .concat(pendingPromptEvents(item.pending_prompt)), + ) + item.is_completed = true + } restoreQuickAnswerFlags(item) if (item.content) { @@ -601,7 +716,8 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) { (data.response_type === 'thinking' || data.response_type === 'answer' || data.response_type === 'tool_call' || - data.response_type === 'tool_approval_required') + data.response_type === 'tool_approval_required' || + data.response_type === 'agent_prompt_required') ) { log('[Agent Chunk] Closing loading for continued stream') loading.value = false @@ -689,12 +805,64 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) { description: d.description, args_json: d.args_json, timeout_seconds: d.timeout_seconds, + hot_wait_seconds: d.hot_wait_seconds, + suspendable: d.suspendable, requested_at: d.requested_at, tool_call_id: d.tool_call_id, resolved: false, }) break } + case 'agent_prompt_required': { + if (!message.agentEventStream) message.agentEventStream = [] + const d = dataPayload || {} + ;(message.agentEventStream as ChatMessage[]).push({ + type: 'agent_prompt_required', + pending_id: d.pending_id, + kind: d.kind, + request: d.request, + timeout_seconds: d.timeout_seconds, + hot_wait_seconds: d.hot_wait_seconds, + suspendable: d.suspendable, + requested_at: d.requested_at, + tool_call_id: d.tool_call_id, + resolved: false, + }) + break + } + case 'agent_prompt_resolved': { + const d = dataPayload || {} + const ev = (message.agentEventStream as ChatMessage[] | undefined)?.find( + (e) => e.type === 'agent_prompt_required' && e.pending_id === d.pending_id, + ) + if (ev) { + ev.resolved = true + ev.answered = d.answered + ev.response = d.response + ev.resolve_reason = d.reason + ev.timed_out = d.timed_out + ev.canceled = d.canceled + } + break + } + case 'run_suspended': { + // The run ended waiting on this prompt; answering it resumes the run. + const d = dataPayload || {} + const card = (message.agentEventStream as ChatMessage[] | undefined)?.find( + (e) => isPromptCard(e) && e.pending_id === d.pending_id, + ) + if (card) { + card.suspended = true + card.expires_at = d.expires_at + } + message.run_state = AWAITING_INPUT + break + } + case 'run_resumed': { + message.run_state = '' + message.is_completed = false + break + } case 'tool_approval_resolved': { const d = dataPayload || {} const pid = d.pending_id @@ -1046,7 +1214,7 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) { if (usage) { message.usage = usage } - if (message.agentEventStream) { + if (message.agentEventStream && !isAwaitingInput(message)) { ;(message.agentEventStream as ChatMessage[]).push({ type: 'agent_complete', total_duration_ms: dataPayload?.total_duration_ms || 0, @@ -1138,7 +1306,9 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) { let existingMessage = replay || findLastMessage( (item) => item.role === 'assistant' && - (item.id === data.id || item.request_id === data.id), + (item.id === data.id || + item.request_id === data.id || + (!!data.assistant_message_id && item.id === data.assistant_message_id)), ) const created = !existingMessage if (!existingMessage) { @@ -1187,7 +1357,11 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) { data.response_type === 'reflection' || data.response_type === 'artifacts_pending' || data.response_type === 'context_compacted' || - data.response_type === 'user_message_injected' + data.response_type === 'user_message_injected' || + data.response_type === 'run_suspended' || + data.response_type === 'run_resumed' || + data.response_type === 'agent_prompt_required' || + data.response_type === 'agent_prompt_resolved' const activeAssistant = getTrailingIncompleteAssistant() const isCurrentlyAgentMode = activeAssistant?.isAgentMode === true @@ -1334,6 +1508,7 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) { handleMsgList, processStreamChunk, prepareForNewOutgoingMessage, + prepareResumedMessage, markInFlightAssistantStopped, } } diff --git a/frontend/src/composables/useEmbedChatSession.ts b/frontend/src/composables/useEmbedChatSession.ts index 552991de..5876cbff 100644 --- a/frontend/src/composables/useEmbedChatSession.ts +++ b/frontend/src/composables/useEmbedChatSession.ts @@ -5,6 +5,7 @@ import { nextTick, onMounted, onUnmounted, + provide, type Ref, } from 'vue' import { useStream } from '@/api/chat/streame' @@ -19,7 +20,8 @@ import { embedToast } from '@/utils/embedToast' import { buildQueryWithHostContext } from '@/utils/embedContext' import { fileToDataURI } from '@/utils/embedFile' import { useI18n } from 'vue-i18n' -import { useChatStreamHandler } from '@/composables/useChatStreamHandler' +import { useChatStreamHandler, isPromptCard } from '@/composables/useChatStreamHandler' +import { resumeSuspendedRunKey } from '@/utils/suspendedRun' import { useStickyBottomOnResize } from '@/composables/useStickyBottomOnResize' export function useEmbedChatSession(options: { @@ -123,6 +125,7 @@ export function useEmbedChatSession(options: { handleMsgList, processStreamChunk, prepareForNewOutgoingMessage, + prepareResumedMessage, markInFlightAssistantStopped, } = useChatStreamHandler({ messagesList, @@ -328,6 +331,44 @@ export function useEmbedChatSession(options: { }) } + // Embed has no stream to re-attach to, so a resumed run is followed by + // polling history until its message settles, then reloading it. + let resumePoll: ReturnType | 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[] | 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[] | undefined)?.find((m) => m.id === messageId) + if (!latest || latest.is_completed || latest.run_state === 'awaiting_input' || Date.now() > deadline) { + resetAndLoad(sid) + return + } + } catch (err) { + console.error('Failed to poll resumed run:', err) + } + resumePoll = setTimeout(poll, 2000) + } + resumePoll = setTimeout(poll, 1000) + } + provide(resumeSuspendedRunKey, followResumedRun) + watch(error, (newError) => { if (newError) { embedToast(newError) @@ -349,6 +390,7 @@ export function useEmbedChatSession(options: { }) const resetAndLoad = (sid: string) => { + stopResumePoll() messagesList.splice(0) historyLoading.value = true historyLoadingMore.value = false @@ -379,6 +421,7 @@ export function useEmbedChatSession(options: { }) onUnmounted(() => { + stopResumePoll() stopStream() fullContent.value = '' }) diff --git a/frontend/src/composables/usePromptCountdown.ts b/frontend/src/composables/usePromptCountdown.ts new file mode 100644 index 00000000..589e38fa --- /dev/null +++ b/frontend/src/composables/usePromptCountdown.ts @@ -0,0 +1,65 @@ +import { computed, onBeforeUnmount, onMounted, ref } from 'vue' +import { useI18n } from 'vue-i18n' + +export interface PromptTiming { + requestedAt?: number + timeoutSeconds?: number + hotWaitSeconds?: number + suspendable?: boolean + suspended?: boolean + expiresAt?: string + resolved?: boolean +} + +/** + * Countdown of a prompt card. A suspendable prompt counts down its hot wait; + * past it (or once suspended) it is parked: the run no longer waits in + * memory, and answering later resumes it until expiresAt. + */ +export function usePromptCountdown(props: PromptTiming) { + const { t, locale } = useI18n() + const now = ref(Date.now()) + let timer: ReturnType | null = null + onMounted(() => { + timer = setInterval(() => { now.value = Date.now() }, 1000) + }) + onBeforeUnmount(() => { + if (timer) clearInterval(timer) + }) + + const deadline = computed(() => { + const base = (props.requestedAt || 0) * 1000 + const wait = props.suspendable ? props.hotWaitSeconds || props.timeoutSeconds : props.timeoutSeconds + return base + (wait || 600) * 1000 + }) + + const parked = computed(() => Boolean(props.suspended || (props.suspendable && now.value >= deadline.value))) + + const secondsLeft = computed(() => { + if (props.resolved) return -1 + return Math.max(0, Math.floor((deadline.value - now.value) / 1000)) + }) + + const timerClass = computed(() => { + if (secondsLeft.value <= 30) return 'timer-critical' + if (secondsLeft.value <= 120) return 'timer-warning' + return '' + }) + + const countdownText = computed(() => { + const s = secondsLeft.value + if (s < 60) return t('agentStream.toolApproval.countdownShort', { seconds: s }) + return `${Math.floor(s / 60)}:${(s % 60).toString().padStart(2, '0')}` + }) + + const parkedText = computed(() => { + const expires = props.expiresAt ? new Date(props.expiresAt) : null + if (!expires || Number.isNaN(expires.getTime())) return t('agentStream.toolApproval.parked') + const time = expires.toLocaleString(locale.value, { + month: 'numeric', day: 'numeric', hour: '2-digit', minute: '2-digit', + }) + return t('agentStream.toolApproval.parkedUntil', { time }) + }) + + return { parked, secondsLeft, timerClass, countdownText, parkedText } +} diff --git a/frontend/src/composables/usePromptDock.test.mjs b/frontend/src/composables/usePromptDock.test.mjs new file mode 100644 index 00000000..0d1da193 --- /dev/null +++ b/frontend/src/composables/usePromptDock.test.mjs @@ -0,0 +1,178 @@ +import assert from 'node:assert/strict' +import { readFileSync } from 'node:fs' +import test from 'node:test' +import vm from 'node:vm' +import ts from 'typescript' +import * as vue from 'vue' +import { isSubmitKey, optionIndexForKey, optionKey } from '../utils/promptKeys.ts' + +const source = readFileSync(new URL('./usePromptDock.ts', import.meta.url), 'utf8') +const compiled = ts.transpileModule(source, { + compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 }, +}).outputText +const modules = { + vue, + '@/composables/useChatStreamHandler': { + isAwaitingInput: (m) => m?.run_state === 'awaiting_input', + }, +} +const exports = {} +vm.runInNewContext(compiled, { + exports, Date, + require: (id) => { + assert.ok(id in modules, `unexpected import ${id}`) + return modules[id] + }, +}) +const { pendingPrompts, markPromptSubmitted, promptSubmission } = exports + +// pendingPrompts runs in the vm realm; its arrays are rebuilt here to compare. +const ids = (list) => Array.from(list, (p) => p.pending_id) + +const approval = (id, extra = {}) => + ({ type: 'tool_approval_required', pending_id: id, resolved: false, ...extra }) + +test('docks the open prompts of streaming and suspended runs, oldest first', () => { + const prompts = pendingPrompts([ + { role: 'user', agentEventStream: [approval('user-row')] }, + { role: 'assistant', is_completed: true, run_state: 'awaiting_input', agentEventStream: [approval('a')] }, + { + role: 'assistant', is_completed: false, agentEventStream: [ + { type: 'tool_call', pending_id: 'x' }, + { type: 'agent_prompt_required', kind: 'ask_user', pending_id: 'b', resolved: false }, + { type: 'mcp_oauth_required', pending_id: 'c', resolved: false }, + ], + }, + ]) + assert.deepEqual(ids(prompts), ['a', 'b', 'c']) +}) + +test('leaves settled runs, resolved prompts and unknown kinds in the timeline', () => { + const prompts = pendingPrompts([ + { role: 'assistant', is_completed: true, agentEventStream: [approval('settled')] }, + { + role: 'assistant', is_completed: false, agentEventStream: [ + approval('resolved', { resolved: true }), + { type: 'agent_prompt_required', kind: 'something_else', pending_id: 'other', resolved: false }, + approval(''), + ], + }, + ]) + assert.deepEqual(ids(prompts), []) +}) + +test('drops a suspended prompt once it expired', () => { + const past = new Date(Date.now() - 60_000).toISOString() + const future = new Date(Date.now() + 60_000).toISOString() + const prompts = pendingPrompts([{ + role: 'assistant', is_completed: true, run_state: 'awaiting_input', agentEventStream: [ + approval('expired', { suspended: true, expires_at: past }), + approval('live', { suspended: true, expires_at: future }), + ], + }]) + assert.deepEqual(ids(prompts), ['live']) +}) + +test('a prompt answered on this page leaves the dock before the stream confirms it', () => { + const messages = vue.reactive([ + { role: 'assistant', is_completed: false, agentEventStream: [approval('answered-here'), approval('next')] }, + ]) + const docked = vue.computed(() => ids(pendingPrompts(messages))) + assert.deepEqual(docked.value, ['answered-here', 'next']) + + markPromptSubmitted('answered-here', { approved: true }) + assert.deepEqual(docked.value, ['next']) + assert.deepEqual(promptSubmission('answered-here'), { approved: true }) +}) + +test('both chat views mount the dock above their composer and feed it their messages', () => { + const read = (path) => readFileSync(new URL(path, import.meta.url), 'utf8') + const chat = read('../views/chat/index.vue') + assert.match(chat, /providePromptDock\(messagesList\)/) + assert.match(chat, /]*\/>\s*\s* { + assert.equal(optionKey(0), 'A') + assert.equal(optionKey(25), 'Z') + assert.equal(optionKey(26), '') + assert.equal(optionIndexForKey('b'), 1) + assert.equal(optionIndexForKey('C'), 2) + assert.equal(optionIndexForKey('1'), -1) + assert.equal(optionIndexForKey('Enter'), -1) +}) + +test('Enter submits unless it inserts a line break or confirms an IME candidate', () => { + const key = (init) => ({ key: 'Enter', shiftKey: false, isComposing: false, keyCode: 13, ...init }) + assert.equal(isSubmitKey(key({})), true) + assert.equal(isSubmitKey(key({ shiftKey: true })), false) + assert.equal(isSubmitKey(key({ isComposing: true })), false) + assert.equal(isSubmitKey(key({ keyCode: 229 })), false) + assert.equal(isSubmitKey(key({ key: 'a' })), false) +}) + +test('Enter on a focused control keeps its native action instead of submitting the prompt', () => { + for (const control of ['reject', 'skip', 'args-toggle', 'dock-next']) { + const key = { + key: 'Enter', shiftKey: false, isComposing: false, keyCode: 13, + target: { closest: (selector) => selector.includes('button') ? { control, getAttribute: () => null } : null }, + } + assert.equal(isSubmitKey(key), false, control) + } +}) + +test('Enter on the option just picked submits it rather than toggling it off', () => { + const option = { getAttribute: (name) => ({ role: 'option', 'aria-selected': 'true' })[name] } + const key = { + key: 'Enter', shiftKey: false, isComposing: false, keyCode: 13, + target: { closest: (selector) => (selector.includes('button') ? option : null) }, + } + assert.equal(isSubmitKey(key), true) +}) + +test('the approval handler does not approve when Enter targets Reject', () => { + const card = readFileSync(new URL('../views/chat/components/ToolApprovalCard.vue', import.meta.url), 'utf8') + const handler = card.slice(card.indexOf('const handleKey ='), card.indexOf('defineExpose')) + const decisions = [] + const compiled = ts.transpileModule(handler, { compilerOptions: { target: ts.ScriptTarget.ES2022 } }).outputText + const handleKey = vm.runInNewContext(compiled + '\nhandleKey', { + interactive: { value: true }, isJsonValid: { value: true }, isSubmitKey, + submit: (decision) => decisions.push(decision), + }) + const key = { key: 'Enter', shiftKey: false, isComposing: false, keyCode: 13, + target: { tagName: 'BUTTON', closest: () => ({ textContent: 'Reject' }) } } + assert.equal(handleKey(key), false) + assert.deepEqual(decisions, []) + assert.equal(handleKey({ ...key, target: { tagName: 'SECTION', closest: () => null } }), true) + assert.deepEqual(decisions, ['approve']) +}) + + +test('Enter on an unselected option selects it instead of submitting the previous answer', () => { + const card = readFileSync(new URL('../views/chat/components/AskUserCard.vue', import.meta.url), 'utf8') + const source = card.slice(card.indexOf('const handleKey ='), card.indexOf('defineExpose')) + const compiled = ts.transpileModule(source, { compilerOptions: { target: ts.ScriptTarget.ES2022 } }).outputText + for (const initial of [[], ['A']]) { + let selected = [...initial] + const submitted = [] + const handleKey = vm.runInNewContext(compiled + '\nhandleKey', { + interactive: { value: true }, isSubmitKey, isTextEntry: () => false, + optionIndexForKey, options: { value: ['A', 'B'] }, + submit: () => submitted.push([...selected]), toggleOption: (value) => { selected = [value] }, + }) + const control = { getAttribute: (name) => ({ role: 'option', 'aria-selected': String(selected.includes('B')) })[name] } + const key = { key: 'Enter', shiftKey: false, isComposing: false, keyCode: 13, + target: { closest: (selector) => selector.includes('button') ? control : null } } + // Returning false preserves the native button click; the dock must not + // preventDefault or submit A while the user's focus is on B. + assert.equal(handleKey(key), false) + assert.deepEqual(submitted, []) + selected = ['B'] // The button's native click selects B. + assert.equal(handleKey(key), true) + assert.deepEqual(submitted, [['B']]) + } +}) diff --git a/frontend/src/composables/usePromptDock.ts b/frontend/src/composables/usePromptDock.ts new file mode 100644 index 00000000..a6044e8b --- /dev/null +++ b/frontend/src/composables/usePromptDock.ts @@ -0,0 +1,87 @@ +import { computed, inject, provide, reactive, ref, type ComputedRef, type InjectionKey, type Ref } from 'vue' +import { isAwaitingInput } from '@/composables/useChatStreamHandler' + +type PromptEvent = Record +type ChatRow = Record + +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>()) + +export function markPromptSubmitted(pendingId: string, answer: Record = {}) { + submissions.set(pendingId, answer) +} + +export function promptSubmission(pendingId: string): Record | 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 + activeId: Ref + collapsed: Ref + /** Bumped when something asks the dock to take focus. */ + focusRequest: Ref + isDocked: (pendingId: string) => boolean + focus: (pendingId: string) => void +} + +const promptDockKey: InjectionKey = Symbol('promptDock') + +/** Called by a chat view; its timeline cards and its dock share the result. */ +export function providePromptDock(messages: ChatRow[]): PromptDock { + const prompts = computed(() => pendingPrompts(messages)) + const activeId = ref('') + const collapsed = ref(false) + const focusRequest = ref(0) + const dock: PromptDock = { + prompts, + activeId, + collapsed, + focusRequest, + isDocked: (pendingId) => prompts.value.some((e) => e.pending_id === pendingId), + focus: (pendingId) => { + activeId.value = pendingId + collapsed.value = false + focusRequest.value++ + }, + } + provide(promptDockKey, dock) + return dock +} + +export function usePromptDock(): PromptDock | null { + return inject(promptDockKey, null) +} diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts index bafb398c..e70ee24b 100755 --- a/frontend/src/i18n/locales/en-US.ts +++ b/frontend/src/i18n/locales/en-US.ts @@ -6148,7 +6148,8 @@ export default { getDocumentInfo: 'Get Document Info', queryKnowledgeGraph: 'Query Knowledge Graph', think: 'Deep Thinking', - todoWrite: 'Make Plan' + todoWrite: 'Make Plan', + askUser: 'Ask User' }, vectorStoreBadge: { systemDefault: 'System default', @@ -6246,10 +6247,37 @@ export default { } }, agentStream: { + askUser: { + title: 'Question for you', + selectPlaceholder: 'Select', + textPlaceholder: 'Type your answer', + otherPlaceholder: 'Other (optional)', + decline: 'Skip', + submit: 'Submit', + declinedTag: 'Declined to answer', + submitted: 'Submitted', + answeredTag: 'Answered', + timedOutTag: 'No answer in time', + canceledTag: 'Canceled', + unansweredTag: 'Not answered', + submitFailed: 'Failed to submit', + }, + promptDock: { + approvalTitle: 'Needs your review', + oauthTitle: 'Needs your authorization', + waiting: 'Waiting for you', + handle: 'Respond', + pager: '{current} / {total}', + previous: 'Previous', + next: 'Next', + collapse: 'Collapse', + expand: 'Expand' + }, toolApproval: { waiting: 'Awaiting review · {target}', waitingStatus: 'Awaiting review', targetWithTool: '{service} › {tool}', + dockQuestion: 'Allow {target} to run?', titleWithTarget: 'Review · {service} › {tool}', argsLabel: 'Arguments', argsModified: 'Modified', @@ -6258,6 +6286,9 @@ export default { reject: 'Reject', approvedTag: 'Approved', rejectedTag: 'Rejected', + parked: 'Waiting in the background — answer any time', + parkedUntil: 'Waiting in the background — answer before {time}', + abandonedTag: 'Abandoned', invalidJson: 'Arguments must be valid JSON', submitted: 'Submitted', submitFailed: 'Submit failed', @@ -6267,6 +6298,7 @@ export default { waiting: 'Awaiting authorization · {target}', waitingStatus: 'Awaiting authorization', targetWithTool: '{service} › {tool}', + dockQuestion: 'Authorize {target} to continue', titleWithService: 'OAuth · {service}', titleWithTool: 'OAuth · {service} › {tool}', desc: 'Authorizing opens a new window to sign in. The tool call resumes automatically once authorization succeeds.', @@ -6294,6 +6326,7 @@ export default { readDocument: 'Read document', listDocuments: 'List documents', todoWrite: 'Plan Management', + askUser: 'Ask User', knowledgeGraphExtract: 'Knowledge Graph Extraction', thinking: 'Thinking', attachmentParsing: 'Parsing Attachment', @@ -6587,6 +6620,8 @@ export default { thinkingDesc: 'Dynamic and reflective problem-solving thinking tool', todoWrite: 'Plan', todoWriteDesc: 'Create structured research plans', + askUser: 'Ask User', + askUserDesc: 'Ask the user for missing information and wait for the answer before continuing', searchKnowledge: 'Search knowledge', searchKnowledgeDesc: 'Semantic, keyword or hybrid search over knowledge-base chunks', readDocument: 'Read document', diff --git a/frontend/src/i18n/locales/ja-JP.ts b/frontend/src/i18n/locales/ja-JP.ts index f269ff18..9d6a2a34 100644 --- a/frontend/src/i18n/locales/ja-JP.ts +++ b/frontend/src/i18n/locales/ja-JP.ts @@ -6148,7 +6148,8 @@ export default { getDocumentInfo: 'ドキュメント情報の取得', queryKnowledgeGraph: 'ナレッジグラフの照会', think: '深い思考', - todoWrite: '計画の作成' + todoWrite: '計画の作成', + askUser: 'ユーザーに質問' }, vectorStoreBadge: { systemDefault: 'システムデフォルト', @@ -6246,10 +6247,37 @@ export default { } }, agentStream: { + askUser: { + title: 'あなたへの質問', + selectPlaceholder: '選択してください', + textPlaceholder: '回答を入力', + otherPlaceholder: 'その他(任意)', + decline: '回答しない', + submit: '送信', + declinedTag: '回答を辞退しました', + submitted: '送信済み', + answeredTag: '回答済み', + timedOutTag: '時間内に回答なし', + canceledTag: 'キャンセル済み', + unansweredTag: '未回答', + submitFailed: '送信に失敗しました', + }, + promptDock: { + approvalTitle: '承認が必要です', + oauthTitle: '認可が必要です', + waiting: 'あなたの対応待ち', + handle: '対応する', + pager: '{current} / {total}', + previous: '前へ', + next: '次へ', + collapse: '折りたたむ', + expand: '展開' + }, toolApproval: { waiting: '承認待ち · {target}', waitingStatus: '承認待ち', targetWithTool: '{service} › {tool}', + dockQuestion: '{target} の実行を許可しますか?', titleWithTarget: '承認 · {service} › {tool}', argsLabel: '引数', argsModified: '変更あり', @@ -6258,6 +6286,9 @@ export default { reject: '拒否', approvedTag: '承認済み', rejectedTag: '拒否済み', + parked: 'バックグラウンドで待機中。後で対応できます', + parkedUntil: 'バックグラウンドで待機中。{time} までに対応してください', + abandonedTag: '破棄済み', invalidJson: '引数は有効なJSONである必要があります', submitted: '送信しました', submitFailed: '送信に失敗しました', @@ -6267,6 +6298,7 @@ export default { waiting: '認可待ち · {target}', waitingStatus: '認可待ち', targetWithTool: '{service} › {tool}', + dockQuestion: '続行するには {target} を認可してください', titleWithService: 'OAuth · {service}', titleWithTool: 'OAuth · {service} › {tool}', desc: '認可すると、サインイン用の新しいウィンドウが開きます。認可が成功すると、ツール呼び出しは自動的に再開されます。', @@ -6294,6 +6326,7 @@ export default { readDocument: 'ドキュメントを読む', listDocuments: 'ドキュメント一覧', todoWrite: '計画管理', + askUser: 'ユーザーに質問', knowledgeGraphExtract: 'ナレッジグラフ抽出', thinking: '思考', attachmentParsing: '添付ファイルを解析', @@ -6587,6 +6620,8 @@ export default { thinkingDesc: '動的かつ内省的に問題を解決する思考ツール', todoWrite: '計画', todoWriteDesc: '構造化された調査計画を作成します', + askUser: 'ユーザーに質問', + askUserDesc: '必要な情報が不足しているときにユーザーへ質問し、回答を待ってから続行します', searchKnowledge: 'ナレッジベースを検索', searchKnowledgeDesc: 'セマンティック・キーワード・ハイブリッド検索でナレッジベースのチャンクを検索します', readDocument: 'ドキュメントを読む', diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.ts index 6ca61b06..abb6ac76 100755 --- a/frontend/src/i18n/locales/ko-KR.ts +++ b/frontend/src/i18n/locales/ko-KR.ts @@ -1497,6 +1497,8 @@ export default { thinkingDesc: '동적이고 반성적인 문제 해결 사고 도구', todoWrite: '계획 수립', todoWriteDesc: '구조화된 연구 계획 생성', + askUser: '사용자에게 질문', + askUserDesc: '필요한 정보가 부족할 때 사용자에게 질문하고 답변을 기다린 후 계속합니다', searchKnowledge: '지식베이스 검색', searchKnowledgeDesc: '의미, 키워드 또는 하이브리드 방식으로 지식베이스 청크 검색', readDocument: '문서 읽기', @@ -1809,6 +1811,7 @@ export default { readDocument: '문서 읽기', listDocuments: '문서 목록 보기', todoWrite: '계획 관리', + askUser: '사용자에게 질문', knowledgeGraphExtract: '지식 그래프 추출', thinking: '사고', attachmentParsing: '첨부 파일 파싱', @@ -1871,6 +1874,7 @@ export default { waiting: '인증 대기 · {target}', waitingStatus: '인증 대기', targetWithTool: '{service} › {tool}', + dockQuestion: '계속하려면 {target} 인증이 필요합니다', titleWithService: 'OAuth · {service}', titleWithTool: 'OAuth · {service} › {tool}', desc: '인증을 누르면 새 창에서 로그인합니다. 인증이 완료되면 이 도구 호출이 자동으로 계속됩니다.', @@ -1885,10 +1889,37 @@ export default { resumeFailed: '실행 재개 실패, 다시 시도하세요', skipFailed: '건너뛰기 실패, 다시 시도하세요' }, + askUser: { + title: '질문이 있습니다', + selectPlaceholder: '선택하세요', + textPlaceholder: '답변을 입력하세요', + otherPlaceholder: '기타(선택)', + decline: '답변 안 함', + submit: '제출', + declinedTag: '답변 거절함', + submitted: '제출됨', + answeredTag: '답변함', + timedOutTag: '시간 내 답변 없음', + canceledTag: '취소됨', + unansweredTag: '답변 없음', + submitFailed: '제출 실패', + }, + promptDock: { + approvalTitle: '검토가 필요합니다', + oauthTitle: '인증이 필요합니다', + waiting: '응답 대기 중', + handle: '응답하기', + pager: '{current} / {total}', + previous: '이전', + next: '다음', + collapse: '접기', + expand: '펼치기' + }, toolApproval: { waiting: '승인 대기 · {target}', waitingStatus: '승인 대기', targetWithTool: '{service} › {tool}', + dockQuestion: '{target} 실행을 허용할까요?', titleWithTarget: '검토 · {service} › {tool}', argsLabel: '인수', argsModified: '수정됨', @@ -1897,6 +1928,9 @@ export default { reject: '거부', approvedTag: '승인됨', rejectedTag: '거부됨', + parked: '백그라운드에서 대기 중 — 나중에 처리할 수 있습니다', + parkedUntil: '백그라운드에서 대기 중 — {time} 전에 처리하세요', + abandonedTag: '포기됨', invalidJson: '유효한 JSON이 아닙니다', submitted: '제출됨', submitFailed: '제출 실패', @@ -2011,7 +2045,8 @@ export default { getDocumentInfo: '문서 정보 조회', queryKnowledgeGraph: '지식 그래프 쿼리', think: '깊이 생각하기', - todoWrite: '계획 수립' + todoWrite: '계획 수립', + askUser: '사용자에게 질문' }, commandPalette: { placeholder: '지식베이스, 파일, 대화 검색…', diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts index 43ff93d5..591a063a 100755 --- a/frontend/src/i18n/locales/ru-RU.ts +++ b/frontend/src/i18n/locales/ru-RU.ts @@ -1497,6 +1497,8 @@ export default { thinkingDesc: 'Динамический инструмент рефлексивного решения проблем', todoWrite: 'Планирование', todoWriteDesc: 'Создание структурированных исследовательских планов', + askUser: 'Вопрос пользователю', + askUserDesc: 'Задаёт пользователю вопрос, когда не хватает данных, и ждёт ответа', searchKnowledge: 'Поиск по базе знаний', searchKnowledgeDesc: 'Семантический, ключевой или гибридный поиск по фрагментам базы знаний', readDocument: 'Чтение документа', @@ -1809,6 +1811,7 @@ export default { readDocument: 'Чтение документа', listDocuments: 'Список документов', todoWrite: 'Управление планами', + askUser: 'Вопрос пользователю', knowledgeGraphExtract: 'Извлечение графа знаний', thinking: 'Размышление', attachmentParsing: 'Разбор вложения', @@ -1871,6 +1874,7 @@ export default { waiting: 'Ожидание авторизации · {target}', waitingStatus: 'Ожидание авторизации', targetWithTool: '{service} › {tool}', + dockQuestion: 'Авторизуйте {target}, чтобы продолжить', titleWithService: 'OAuth · {service}', titleWithTool: 'OAuth · {service} › {tool}', desc: 'Авторизация откроет новое окно для входа. После успешной авторизации вызов инструмента продолжится автоматически.', @@ -1885,10 +1889,37 @@ export default { resumeFailed: 'Не удалось возобновить выполнение, повторите попытку', skipFailed: 'Не удалось пропустить, повторите попытку' }, + askUser: { + title: 'Вопрос к вам', + selectPlaceholder: 'Выберите', + textPlaceholder: 'Введите ответ', + otherPlaceholder: 'Другое (необязательно)', + decline: 'Не отвечать', + submit: 'Отправить', + declinedTag: 'Отказ от ответа', + submitted: 'Отправлено', + answeredTag: 'Ответ дан', + timedOutTag: 'Нет ответа вовремя', + canceledTag: 'Отменено', + unansweredTag: 'Без ответа', + submitFailed: 'Не удалось отправить', + }, + promptDock: { + approvalTitle: 'Требуется ваша проверка', + oauthTitle: 'Требуется авторизация', + waiting: 'Ожидает вашего ответа', + handle: 'Ответить', + pager: '{current} / {total}', + previous: 'Назад', + next: 'Далее', + collapse: 'Свернуть', + expand: 'Развернуть' + }, toolApproval: { waiting: 'Ожидание проверки · {target}', waitingStatus: 'Ожидание проверки', targetWithTool: '{service} › {tool}', + dockQuestion: 'Разрешить вызов {target}?', titleWithTarget: 'Проверка · {service} › {tool}', argsLabel: 'Аргументы', argsModified: 'Изменено', @@ -1897,6 +1928,9 @@ export default { reject: 'Отклонить', approvedTag: 'Подтверждено', rejectedTag: 'Отклонено', + parked: 'Ожидает в фоне — можно ответить позже', + parkedUntil: 'Ожидает в фоне — ответьте до {time}', + abandonedTag: 'Отменено', invalidJson: 'Некорректный JSON', submitted: 'Отправлено', submitFailed: 'Ошибка отправки', @@ -2011,7 +2045,8 @@ export default { getDocumentInfo: 'Получить информацию о документе', queryKnowledgeGraph: 'Запрос к графу знаний', think: 'Глубокое размышление', - todoWrite: 'Составить план' + todoWrite: 'Составить план', + askUser: 'Вопрос пользователю' }, commandPalette: { placeholder: 'Поиск по базам знаний, файлам, диалогам…', diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts index ff894cf2..79e7bbe7 100755 --- a/frontend/src/i18n/locales/zh-CN.ts +++ b/frontend/src/i18n/locales/zh-CN.ts @@ -1499,6 +1499,8 @@ export default { thinkingDesc: '动态和反思性的问题解决思考工具', todoWrite: '制定计划', todoWriteDesc: '创建结构化的研究计划', + askUser: '向用户提问', + askUserDesc: '在缺少关键信息时向用户提问,并等待回答后继续', searchKnowledge: '检索知识库', searchKnowledgeDesc: '语义、关键词或混合检索知识库分块', readDocument: '阅读文档', @@ -1811,6 +1813,7 @@ export default { readDocument: '阅读文档', listDocuments: '浏览文档列表', todoWrite: '计划管理', + askUser: '向用户提问', knowledgeGraphExtract: '知识图谱抽取', thinking: '思考', attachmentParsing: '解析附件', @@ -1873,6 +1876,7 @@ export default { waiting: '等待授权 · {target}', waitingStatus: '等待授权', targetWithTool: '{service} › {tool}', + dockQuestion: '需要授权 {target} 才能继续', titleWithService: 'OAuth 授权 · {service}', titleWithTool: 'OAuth 授权 · {service} › {tool}', desc: '点击授权将打开新窗口完成登录,授权成功后会自动继续本次工具调用。', @@ -1887,10 +1891,37 @@ export default { resumeFailed: '恢复执行失败,请重试', skipFailed: '跳过失败,请重试' }, + askUser: { + title: '向你提问', + selectPlaceholder: '请选择', + textPlaceholder: '输入你的回答', + otherPlaceholder: '其他(可选)', + decline: '不回答', + submit: '提交', + declinedTag: '已拒绝回答', + submitted: '已提交', + answeredTag: '已回答', + timedOutTag: '超时未回答', + canceledTag: '已取消', + unansweredTag: '未回答', + submitFailed: '提交失败', + }, + promptDock: { + approvalTitle: '需要你审核', + oauthTitle: '需要你授权', + waiting: '等待你处理', + handle: '去处理', + pager: '{current} / {total}', + previous: '上一个', + next: '下一个', + collapse: '收起', + expand: '展开' + }, toolApproval: { waiting: '等待审核 · {target}', waitingStatus: '等待审核', targetWithTool: '{service} › {tool}', + dockQuestion: '允许调用 {target}?', titleWithTarget: '人工审核 · {service} › {tool}', argsLabel: '调用参数', argsModified: '已修改', @@ -1899,6 +1930,9 @@ export default { reject: '拒绝', approvedTag: '已通过', rejectedTag: '已拒绝', + parked: '已转入后台等待,可稍后处理', + parkedUntil: '已转入后台等待,{time} 前可处理', + abandonedTag: '已放弃', invalidJson: '参数不是合法 JSON', submitted: '已提交', submitFailed: '提交失败', @@ -2013,7 +2047,8 @@ export default { getDocumentInfo: '获取文档信息', queryKnowledgeGraph: '查询知识图谱', think: '深度思考', - todoWrite: '制定计划' + todoWrite: '制定计划', + askUser: '向用户提问' }, commandPalette: { placeholder: '搜索知识库、文件、对话…', diff --git a/frontend/src/i18n/locales/zh-TW.ts b/frontend/src/i18n/locales/zh-TW.ts index 7f31ffae..ca069c27 100644 --- a/frontend/src/i18n/locales/zh-TW.ts +++ b/frontend/src/i18n/locales/zh-TW.ts @@ -1499,6 +1499,8 @@ export default { thinkingDesc: '動態和反思性的問題解決思考工具', todoWrite: '制定計劃', todoWriteDesc: '建立結構化的研究計劃', + askUser: '向使用者提問', + askUserDesc: '在缺少關鍵資訊時向使用者提問,並等待回答後繼續', searchKnowledge: '檢索知識庫', searchKnowledgeDesc: '語義、關鍵字或混合檢索知識庫切塊', readDocument: '閱讀文件', @@ -1811,6 +1813,7 @@ export default { readDocument: '閱讀文件', listDocuments: '瀏覽文件清單', todoWrite: '計劃管理', + askUser: '向使用者提問', knowledgeGraphExtract: '知識圖譜抽取', thinking: '思考', attachmentParsing: '解析附件', @@ -1873,6 +1876,7 @@ export default { waiting: '等待授權 · {target}', waitingStatus: '等待授權', targetWithTool: '{service} › {tool}', + dockQuestion: '需要授權 {target} 才能繼續', titleWithService: 'OAuth 授權 · {service}', titleWithTool: 'OAuth 授權 · {service} › {tool}', desc: '點擊授權將打開新視窗完成登入,授權成功後會自動繼續本次工具呼叫。', @@ -1887,10 +1891,37 @@ export default { resumeFailed: '復原執行失敗,請重試', skipFailed: '跳過失敗,請重試' }, + askUser: { + title: '向你提問', + selectPlaceholder: '請選擇', + textPlaceholder: '輸入你的回答', + otherPlaceholder: '其他(選填)', + decline: '不回答', + submit: '提交', + declinedTag: '已拒絕回答', + submitted: '已提交', + answeredTag: '已回答', + timedOutTag: '逾時未回答', + canceledTag: '已取消', + unansweredTag: '未回答', + submitFailed: '提交失敗', + }, + promptDock: { + approvalTitle: '需要你審核', + oauthTitle: '需要你授權', + waiting: '等待你處理', + handle: '去處理', + pager: '{current} / {total}', + previous: '上一個', + next: '下一個', + collapse: '收起', + expand: '展開' + }, toolApproval: { waiting: '等待審核 · {target}', waitingStatus: '等待審核', targetWithTool: '{service} › {tool}', + dockQuestion: '允許呼叫 {target}?', titleWithTarget: '人工審核 · {service} › {tool}', argsLabel: '呼叫參數', argsModified: '已修改', @@ -1899,6 +1930,9 @@ export default { reject: '拒絕', approvedTag: '已透過', rejectedTag: '已拒絕', + parked: '已轉入背景等待,可稍後處理', + parkedUntil: '已轉入背景等待,{time} 前可處理', + abandonedTag: '已放棄', invalidJson: '參數不是合法 JSON', submitted: '已提交', submitFailed: '提交失敗', @@ -2013,7 +2047,8 @@ export default { getDocumentInfo: '獲取文件資訊', queryKnowledgeGraph: '查詢知識圖譜', think: '深度思考', - todoWrite: '制定計劃' + todoWrite: '制定計劃', + askUser: '向使用者提問' }, commandPalette: { placeholder: '搜尋知識庫、檔案、對話…', diff --git a/frontend/src/utils/askUser.test.ts b/frontend/src/utils/askUser.test.ts new file mode 100644 index 00000000..10183644 --- /dev/null +++ b/frontend/src/utils/askUser.test.ts @@ -0,0 +1,41 @@ +import assert from 'node:assert/strict' +import test from 'node:test' +import { buildAskUserResponse, canSubmitAskUser, summarizeAskUserAnswer, type AskUserQuestion } from './askUser.ts' + +const form: AskUserQuestion = { + question: 'Trip?', + fields: [ + { name: 'city', label: 'City', type: 'text', required: true }, + { name: 'days', type: 'number' }, + { name: 'tags', type: 'multiselect', options: ['a', 'b'] }, + ], +} + +test('a form answer keeps filled fields only', () => { + const r = buildAskUserResponse(form, { selected: [], values: { city: ' Paris ', days: 3, tags: [] }, text: 'ignored' }) + assert.deepEqual(r, { values: { city: 'Paris', days: 3 } }) + assert.equal(canSubmitAskUser(form, r), true) + assert.equal(summarizeAskUserAnswer(form, r), 'City: Paris\ndays: 3') +}) + +test('a form waits for its required fields', () => { + const r = buildAskUserResponse(form, { selected: [], values: { days: 2 }, text: '' }) + assert.equal(canSubmitAskUser(form, r), false) +}) + +test('options accept a choice or, when allowed, typed text', () => { + const q: AskUserQuestion = { question: 'Pick', options: ['x', 'y'], allow_free_text: true } + assert.equal(canSubmitAskUser(q, buildAskUserResponse(q, { selected: [], values: {}, text: '' })), false) + assert.deepEqual(buildAskUserResponse(q, { selected: ['y'], values: {}, text: '' }), { selected: ['y'] }) + const typed = buildAskUserResponse(q, { selected: [], values: {}, text: 'z' }) + assert.deepEqual(typed, { text: 'z' }) + assert.equal(canSubmitAskUser(q, typed), true) + const strict: AskUserQuestion = { question: 'Pick', options: ['x'] } + assert.deepEqual(buildAskUserResponse(strict, { selected: [], values: {}, text: 'z' }), {}) +}) + +test('a free-text question needs text', () => { + const q: AskUserQuestion = { question: 'Why?' } + assert.equal(canSubmitAskUser(q, buildAskUserResponse(q, { selected: [], values: {}, text: ' ' })), false) + assert.deepEqual(buildAskUserResponse(q, { selected: [], values: {}, text: ' because ' }), { text: 'because' }) +}) diff --git a/frontend/src/utils/askUser.ts b/frontend/src/utils/askUser.ts new file mode 100644 index 00000000..f9c53954 --- /dev/null +++ b/frontend/src/utils/askUser.ts @@ -0,0 +1,67 @@ +export interface AskUserField { + name: string + label?: string + type: 'text' | 'number' | 'select' | 'multiselect' + required?: boolean + options?: string[] +} + +/** Request of an ask_user prompt; mirrors types.AskUserPromptRequest. */ +export interface AskUserQuestion { + question: string + options?: string[] + multi_select?: boolean + fields?: AskUserField[] + allow_free_text?: boolean +} + +export interface AskUserDraft { + selected: string[] + values: Record + 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 { + const response: Record = {} + if (q.options?.length && draft.selected.length) response.selected = [...draft.selected] + if (q.fields?.length) { + const values: Record = {} + 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): boolean { + const values = (response.values || {}) as Record + 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 { + const lines: string[] = [] + const selected = answer.selected as string[] | undefined + if (selected?.length) lines.push(selected.join(', ')) + const values = (answer.values || {}) as Record + for (const f of q.fields || []) { + const v = values[f.name] + if (isEmpty(v)) continue + lines.push(`${f.label || f.name}: ${Array.isArray(v) ? v.join(', ') : String(v)}`) + } + if (typeof answer.text === 'string' && answer.text.trim()) lines.push(answer.text.trim()) + return lines.join('\n') +} diff --git a/frontend/src/utils/promptKeys.ts b/frontend/src/utils/promptKeys.ts new file mode 100644 index 00000000..9ac92944 --- /dev/null +++ b/frontend/src/utils/promptKeys.ts @@ -0,0 +1,29 @@ +/** Letter shown beside the i-th option of a docked prompt: A, B, C… */ +export function optionKey(index: number): string { + return index >= 0 && index < 26 ? String.fromCharCode(65 + index) : '' +} + +/** Index of the option a key press picks, or -1. */ +export function optionIndexForKey(key: string): number { + if (key.length !== 1) return -1 + const code = key.toUpperCase().charCodeAt(0) + return code >= 65 && code <= 90 ? code - 65 : -1 +} + +/** Whether key presses on el are typing rather than shortcuts. */ +export function isTextEntry(el: EventTarget | null): boolean { + if (!(el instanceof HTMLElement)) return false + return el.isContentEditable || el.tagName === 'INPUT' || el.tagName === 'TEXTAREA' || el.tagName === 'SELECT' +} + +/** Enter that submits: not composing an IME candidate, not a soft line break. */ +export function isSubmitKey(e: KeyboardEvent): boolean { + // Let focused controls perform their own action (especially Reject/Skip). + // The dock receives bubbled keydowns from both its cards and its header. + // A picked option keeps focus after the click, and Enter then submits it. + const target = e.target as Element | null + const control = target?.closest?.('button, a, [role="button"]') + if (control && (control.getAttribute?.('role') !== 'option' + || control.getAttribute?.('aria-selected') !== 'true')) return false + return e.key === 'Enter' && !e.shiftKey && !e.isComposing && e.keyCode !== 229 +} diff --git a/frontend/src/utils/suspendedRun.ts b/frontend/src/utils/suspendedRun.ts new file mode 100644 index 00000000..7ecd0796 --- /dev/null +++ b/frontend/src/utils/suspendedRun.ts @@ -0,0 +1,7 @@ +import type { InjectionKey } from 'vue' + +/** + * Provided by a chat view: re-attaches to a suspended run after its prompt was + * answered and the server resumed it. Takes the prompt's pending id. + */ +export const resumeSuspendedRunKey: InjectionKey<(pendingId: string) => void> = Symbol('resumeSuspendedRun') diff --git a/frontend/src/utils/tool-capabilities.ts b/frontend/src/utils/tool-capabilities.ts index 68d98e84..bb3e1af2 100644 --- a/frontend/src/utils/tool-capabilities.ts +++ b/frontend/src/utils/tool-capabilities.ts @@ -53,6 +53,7 @@ export const TOOL_CAPABILITY_REQUIREMENTS: Record = { // ---- base / reasoning (no KB dependency) ---- thinking: {}, todo_write: {}, + ask_user: {}, // ---- RAG / chunk retrieval (need at least one chunk-indexed KB) ---- // We use vector|keyword as the canonical "has RAG chunks" signal. FAQ KBs diff --git a/frontend/src/views/agent/AgentEditorModal.vue b/frontend/src/views/agent/AgentEditorModal.vue index 50dccda1..15ff71af 100644 --- a/frontend/src/views/agent/AgentEditorModal.vue +++ b/frontend/src/views/agent/AgentEditorModal.vue @@ -2494,6 +2494,7 @@ const keepAllowedToolsUnset = ref(false); const toolTexts = computed>(() => ({ thinking: { label: t('agentEditor.tools.thinking'), description: t('agentEditor.tools.thinkingDesc') }, todo_write: { label: t('agentEditor.tools.todoWrite'), description: t('agentEditor.tools.todoWriteDesc') }, + ask_user: { label: t('agentEditor.tools.askUser'), description: t('agentEditor.tools.askUserDesc') }, search_conversations: { label: t('agentEditor.tools.searchConversations'), description: t('agentEditor.tools.searchConversationsDesc') }, search_knowledge: { label: t('agentEditor.tools.searchKnowledge'), description: t('agentEditor.tools.searchKnowledgeDesc') }, read_document: { label: t('agentEditor.tools.readDocument'), description: t('agentEditor.tools.readDocumentDesc') }, @@ -3922,7 +3923,7 @@ watch(agentMode, (val, _oldVal) => { // 用户主动切换模式后列表即为显式选择,不再保持未设置。 if (!isInitializing.value) keepAllowedToolsUnset.value = false; if (!isInitializing.value && formData.value.config.allowed_tools.length === 0) { - const tools: string[] = []; + const tools: string[] = ['ask_user']; if (hasRagKnowledgeBase.value) { tools.push(...knowledgeBaseTools); } diff --git a/frontend/src/views/chat/components/AgentStreamDisplay.style.test.mjs b/frontend/src/views/chat/components/AgentStreamDisplay.style.test.mjs index 70385d90..61fc2576 100644 --- a/frontend/src/views/chat/components/AgentStreamDisplay.style.test.mjs +++ b/frontend/src/views/chat/components/AgentStreamDisplay.style.test.mjs @@ -20,6 +20,7 @@ test('steer seals animation while keeping the preceding timeline open without co const props = reactive({ ragMode: false, session: { steerForked: true, is_completed: true } }) const state = vm.runInNewContext(`${stateBlock}\n${collapseBlock}\n({ isConversationDone, isSegmentDone, shouldShowCollapsedSteps })`, { props, computed, isAssistantTurnComplete, intermediateStepsCount: { value: 2 }, + isAwaitingInput: (m) => m?.run_state === 'awaiting_input', }) assert.equal(state.isSegmentDone.value, true) assert.equal(state.isConversationDone.value, false) @@ -27,6 +28,9 @@ test('steer seals animation while keeping the preceding timeline open without co props.session.steerForked = false assert.equal(state.isConversationDone.value, true) assert.equal(state.shouldShowCollapsedSteps.value, true) + props.session.run_state = 'awaiting_input' + assert.equal(state.isConversationDone.value, false) + assert.equal(state.shouldShowCollapsedSteps.value, false) }) test('agent steps use compact muted timeline styling', () => { @@ -145,7 +149,10 @@ test('agent mode shows a native placeholder before answer whenever nothing is pe assert.match(source, /return !hasPendingStreamingActivity\.value/) assert.match(source, /const hasPendingStreamingActivity = computed/) assert.match(source, /event\.thinking === true \|\| isThinkingActive\(event\.event_id\)/) - assert.match(source, /event\.type === 'tool_approval_required' \|\| event\.type === 'mcp_oauth_required'/) + assert.match( + source, + /event\.type === 'tool_approval_required' \|\|\s*event\.type === 'mcp_oauth_required' \|\|\s*event\.type === 'agent_prompt_required'/, + ) assert.match(source, /class="action-card action-pending"/) assert.match(source, /t\('chat\.thinkingAlt'\)/) assert.match(source, /chat-timeline-loading\.less/) diff --git a/frontend/src/views/chat/components/AgentStreamDisplay.vue b/frontend/src/views/chat/components/AgentStreamDisplay.vue index f8593071..5a3a2d65 100644 --- a/frontend/src/views/chat/components/AgentStreamDisplay.vue +++ b/frontend/src/views/chat/components/AgentStreamDisplay.vue @@ -117,7 +117,19 @@ :mcp-tool-name="event.mcp_tool_name || ''" :description="event.description" :args-json="event.args_json" :timeout-seconds="event.timeout_seconds" :requested-at="event.requested_at" :resolved="event.resolved" :approved="event.approved" - :resolve-reason="event.resolve_reason" v-bind="embedAuthProps" /> + :resolve-reason="event.resolve_reason" :suspendable="event.suspendable" + :hot-wait-seconds="event.hot_wait_seconds" :suspended="event.suspended" + :expires-at="event.expires_at" :abandoned="event.abandoned" v-bind="embedAuthProps" /> + + + +
+
@@ -341,7 +353,19 @@ + :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" /> + + + +
+
@@ -634,6 +658,7 @@ + + diff --git a/frontend/src/views/chat/components/McpOAuthCard.vue b/frontend/src/views/chat/components/McpOAuthCard.vue index 20bda2fa..c91b6341 100644 --- a/frontend/src/views/chat/components/McpOAuthCard.vue +++ b/frontend/src/views/chat/components/McpOAuthCard.vue @@ -1,5 +1,24 @@