@deepseek-ai/dsh-tool-ask-user 0.1.7-rc.2 → 0.2.0-rc.2

package/README.i18n.yaml

@@ -9,32 +9,32 @@
   en: 2a561a70c4a900d7
   zh: 3d12372992cf2634
 /deepseek-ai-dsh-tool-ask-user/summary:
-  en: 45bb29d463d1e8d2
-  zh: a462610ab6e8e61b
+  en: 1a9a38698a6cb1f3
+  zh: 35540765df5648e7
 /deepseek-ai-dsh-tool-ask-user/table-of-contents:
   en: d152484eb41ac6b4
   zh: 09388d293f9be9cb
 /deepseek-ai-dsh-tool-ask-user/use-this-package:
-  en: ed8ec46772509d66
-  zh: b06aad135f7a4fa3
+  en: 547a3ea61708bc3e
+  zh: 5e251ea392940c1a
 /deepseek-ai-dsh-tool-ask-user/use-this-package/when-to-call-the-tool:
-  en: 5a142d88def1a4fd
-  zh: 2ae5573abf23d76a
+  en: 7c70d43d4cd9aa19
+  zh: 7597e972067ec5fe
 /deepseek-ai-dsh-tool-ask-user/use-this-package/what-the-model-gets-back:
-  en: d0047cb9dda88606
-  zh: d3432561db23f65a
+  en: c30ba8cefa64a287
+  zh: cc8bc285ff859983
 /deepseek-ai-dsh-tool-ask-user/use-this-package/when-the-call-fails:
-  en: dd379ed6282761b6
-  zh: fa7da19a52091403
+  en: c4ac3c584f900230
+  zh: bd8d227f0637b8f1
 /deepseek-ai-dsh-tool-ask-user/understand-the-implementation:
   en: e9b9d46be0b45ca2
   zh: c02403486473cd80
 /deepseek-ai-dsh-tool-ask-user/understand-the-implementation/source-map:
-  en: 8ce163d8203be215
-  zh: 6fd9db8f061b8198
+  en: 95a6f15bb08e239b
+  zh: 9def25d23f0e131d
 /deepseek-ai-dsh-tool-ask-user/understand-the-implementation/consumer-role:
-  en: 30c2b751e1b04fe4
-  zh: 862c1087ad9c8f66
+  en: 7de88d25287b969f
+  zh: be36dc5a39aeac3b
 /deepseek-ai-dsh-tool-ask-user/understand-the-implementation/result-rendering:
   en: 686176b2703dfa08
   zh: 4ea4dab0da7f79f9
@@ -48,8 +48,8 @@
   en: e4c7376d4f29dbd5
   zh: 6b7a9eaf69c9ea53
 /deepseek-ai-dsh-tool-ask-user/model-experience/tool-schema/what-the-model-sees:
-  en: e043611dc8d99927
-  zh: 2e4b0e6548f2d64c
+  en: 577c8609a8bb915d
+  zh: 8607e0d39be0e492
 /deepseek-ai-dsh-tool-ask-user/model-experience/tool-schema/token-effect:
   en: 97cce067584eadff
   zh: c376cab39ea9df68
@@ -60,8 +60,8 @@
   en: 9717b983b6a857e3
   zh: 611a2dadf7c0c706
 /deepseek-ai-dsh-tool-ask-user/model-experience/tool-call-history-and-result/what-the-model-sees:
-  en: d5ba86e2dbdb5b4b
-  zh: f5a2d6de0d985eed
+  en: c2ceed515656e10b
+  zh: 4e9b6768e4914718
 /deepseek-ai-dsh-tool-ask-user/model-experience/tool-call-history-and-result/token-effect:
   en: 3092d4afd4ba8678
   zh: cb7a7bbefdbc3a1e
@@ -69,8 +69,8 @@
   en: f5d5f97a153f7c70
   zh: 4db81881ebdcfcc4
 /deepseek-ai-dsh-tool-ask-user/known-limitations-and-deferred-work:
-  en: a0f0f15f51d5affb
-  zh: 41f11351e852968c
+  en: c8df1368c2959465
+  zh: b14fb07a60e75ebf
 /deepseek-ai-dsh-tool-ask-user/known-limitations-and-deferred-work/dev-note:
-  en: e67f633dc6fe7773
-  zh: 3bb0c20c93f16f98
+  en: 0b06d843322610c1
+  zh: a1e7cadd4f03c384

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`ask_user_question` lets a model pause work and ask the human for confirmation, a choice, or missing information. It accepts one or more questions and returns their answers as compact JSON. The call waits until an answer is accepted or the turn is cancelled; if no answer handler accepts it, the model receives an error. A live child agent owned by another agent cannot call this tool and must report unresolved questions in its final result. The package does not render or collect input, so callers must provide a compatible user interaction surface.
+`ask_user_question` asks the user for confirmation, a choice, or missing information. It waits for an answer by default. With `mode: timed`, a deadline can release the model to continue independent work while the question stays answerable; `timeout: -1` waits indefinitely. A live child agent cannot call the tool. Callers provide the answer UI.
 
 ## Table of Contents
 
@@ -25,11 +25,23 @@ English | [中文](README.zh.md)
 <a id="use-this-package"></a>
 ## Use this package
 
-Compose this plugin wherever the model should be able to pause for a human decision: it provides the `ask_user_question` tool and needs the `ctx.userQuestions` seam with an answerer that accepts the scoped request. Without one, the tool call fails with an error instead of degrading.
+Compose this plugin with `ctx.userQuestions` when the model needs a user decision. Without an answerer, blocking calls fail; finite timed calls return pending at their deadline.
+
+Shipped presets use blocking mode. To enable timed mode, set `mode: timed` on the `tool-ask-user` row in the active preset's `config.plugins` list:
+
+```yaml
+- id: tool-ask-user
+  name: '@deepseek-ai/dsh-tool-ask-user'
+  config:
+    mode: timed
+    timeout: 120
+```
+
+This is a plugin row, not a top-level `--patch` entry. In the Web profile, change the `preset-standard` plugin list or use the Agent Preset editor. `mode: legacy` or omitted config keeps the blocking schema. The row's `timeout` applies to each timed call by default; `-1` waits indefinitely unless the model supplies a positive timeout. A model-supplied `-1` applies only to that call, including all its questions.
 
 ### When to call the tool
 
-The model calls `ask_user_question` when it needs confirmation, a choice, or missing information before proceeding. Send one or more questions, each with a stable `id` that is echoed in the answer; a recommended option goes first with `(Recommended)` appended to its label.
+Send one or more questions with ids unique within the call; the answer echoes those ids. Put a recommended option first and append `(Recommended)` to its label. The optional per-call `timeout` is in seconds; use `-1` when work cannot safely continue without an answer. A timeout is never approval. In the Web card, editing or choosing Take time also holds that Client's wait until submission or cancellation.
 
 ```json
 {
@@ -49,7 +61,9 @@ The model calls `ask_user_question` when it needs confirmation, a choice, or mis
 
 ### What the model gets back
 
-The tool returns one answer object per question: `selected` holds the chosen option labels, and `custom` carries a free-form answer — supplementing `selected` for a multi-select question and overriding it for a single-select question. The Native renderer preserves the compact JSON text shape.
+An answer returns one item per question. `selected` holds option labels; `custom` supplements a multi-select answer or replaces a single-select choice. A skipped item has empty `selected` and no `custom`.
+
+For a finite timed call, `{ "pending": true, "callId": "…" }` means the foreground wait ended without an answer. The question remains answerable, and the model may continue independent work. A later answer arrives as a user message identified by `kind`, `tool`, and `callId`. Web chat pairs its questions and answers; other consumers receive compact JSON text.
 
 ```json
 { "answers": [{ "id": "cleanup", "selected": ["Yes, delete them (Recommended)"] }] }
@@ -57,7 +71,7 @@ The tool returns one answer object per question: `selected` holds the chosen opt
 
 ### When the call fails
 
-The tool call blocks until the human answers and cancels only through the turn's signal. No accepting answerer, an aborted call, or a caller that is not the exact live runtime root each settles as an error the model sees in the tool result — most notably, a live child agent owned by another agent is rejected (`DELEGATED_CALLER`) and must include the unresolved question or decision in its final result.
+Legacy and `timeout: -1` calls wait for an answer or cancellation; without an accepting answerer, they return an error. A finite timed call without an answerer returns pending at its deadline. Cancellation and a caller that is not the exact live runtime root also return errors. A live child agent is rejected with `DELEGATED_CALLER` and must include the unresolved decision in its final result.
 
 -----
 
@@ -73,12 +87,13 @@ The observable behavior is covered in [Use this package](#use-this-package); thi
 
 | File | Role |
 |---|---|
-| [`src/index.ts`](src/index.ts) | Tool registration: `ask_user_question` schema, execute path, result render |
+| [`src/index.ts`](src/index.ts) | Default blocking tool definition and mode selection |
+| [`src/timed.ts`](src/timed.ts) | Opt-in timed tool definition and result rendering |
 | — | No runtime invariant companion is published; this model-facing adapter has no independent lifecycle stream; execution relations are owned by the capability seam it calls. |
 
 ### Consumer role
 
-The plugin registers one `defineTool` entry on `ctx.tools` with injects `['tools', 'userQuestions']`. `execute` maps model arguments into an `AskUserQuestionRequest`, forwards the exact calling agent and the turn's signal, and maps the accepted answer back into the canonical `answers` array. The seam owns identity checks, intent validation, waterfall dispatch, and the error taxonomy; this package only translates.
+The plugin registers one tool definition. Legacy mode calls `ask()`; timed mode calls `askTimed()` for positive timeouts and `ask()` for `-1`. Both forward the calling agent and turn signal to `ctx.userQuestions`. Timed requests include the tool call id in `wait`, so a Client can reopen their card. The projection identifies timed native calls from the `timeout` field in the recorded tool schema, even when a call omits that argument.
 
 ### Result rendering
 
@@ -107,7 +122,7 @@ Read these pages when the package-level contract is not enough. They move from t
 
 #### What the model sees
 
-The model sees the generated [`ask_user_question` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ask-user), including question ids, prompts, headings, options, and multi-select flags.
+The shipped presets expose the original blocking [`ask_user_question` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ask-user). A custom Cordis row with `mode: timed` switches to the alternate schema, including question ids, prompts, headings, options, multi-select flags, `timeout`, and the pending result; the model sees only the selected definition.
 
 #### Token effect
 
@@ -121,7 +136,7 @@ Prefix-stable while the definition and visibility are unchanged. Plugin lifecycl
 
 #### What the model sees
 
-The model's full questions remain in the assistant tool-call arguments. After the human answers, the next step sees compact JSON in the exact shape `{"answers":[{"id":"<id>","selected":["<label>"],"custom":"<text>"}]}`; `custom` is omitted when unused and `selected` can contain zero, one, or several labels. UI interaction while the call is pending is not model context.
+The assistant tool call retains the questions. An answer during the wait appears in the next step as compact `{"answers":[{"id":"<id>","selected":["<label>"],"custom":"<text>"}]}` JSON; unused `custom` is omitted. A timed-out call returns `{"pending":true,"callId":"<pending-call-id>","message":"<instruction>"}`. A later answer arrives as a user message with `kind: "answer_to_pending_question"`, `tool: "ask_user_question"`, the call id, the original questions, and the answers. UI activity before submission is not model context.
 
 #### Token effect
 
@@ -138,7 +153,8 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 These limits define when the tool is a poor fit. They are current package constraints, not a UI backlog.
 
-- **A pending question blocks the tool call until the human answers** — the tool declares no `timeout-policy` budget; cancellation rides the turn's `exec.signal` only.
+- **The legacy tool never reports pending** — it returns an answer or an error. Native legacy calls do not enter the `userQuestions` projection, and interrupted calls cannot take late answers.
+- **An interrupted PTC wait may lose its question** — if the `run_code` process ends before an `ask_user_question` sub-call records its `tool/ptc-dispatch` result, the projection cannot reconstruct that sub-call for a late answer.
 - **Runtime-owned subagents cannot ask the user** — `ask_user_question` rejects a live child owned by another agent with `DELEGATED_CALLER`; the child must include the unresolved question or decision in its final result. Durable lineage does not decide this boundary, so a lineage-bearing session resumed as a runtime root may ask normally.
 - **Native answers render as JSON text** — the canonical value remains structured, but the model-facing result uses compact JSON rather than a richer content-block vocabulary.
 
@@ -148,6 +164,6 @@ These limits define when the tool is a poor fit. They are current package constr
 <details>
 <summary>Working context for maintainers — click to expand</summary>
 
-None.
+The [`userQuestions` projection](../user-questions/src/projection.ts) reads each recorded tool schema rather than the call arguments: timed calls may omit `timeout`, and timed `-1` calls still use the timed schema. Changes to the projection fold require a `stateVersion` bump so stored caches refold from the log.
 
 </details>

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`ask_user_question` 让模型暂停工作，向用户请求确认、选择或缺失的信息。它接受一个或多个问题，并以紧凑 JSON 返回回答。调用会等待回答被接受或当前轮次被取消；如果没有回答处理器接受请求，模型会收到错误。归属于运行时其他 agent 的子级不能调用此工具，必须在最终结果中报告尚未解决的问题。本包不渲染界面或收集输入，因此调用方必须提供兼容的用户交互表面。
+`ask_user_question` 向用户请求确认、选择或缺失的信息。默认情况下，它会等待回答。设置 `mode: timed` 后，期限到达时模型可以继续独立工作，而问题仍可回答；`timeout: -1` 则无限期等待。存活的子 agent 不能调用此工具。调用方需提供回答界面。
 
 ## 目录
 
@@ -25,11 +25,23 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-凡模型应当能够暂停等待人类决定的场景，都可组合此插件：它提供 `ask_user_question` 工具，并且需要带有接受作用域请求的 answerer 的 `ctx.userQuestions` seam。没有 answerer 接受时，工具调用会以错误失败，而不是降级。
+当模型需要用户决定时，将此插件与 `ctx.userQuestions` 组合。没有 answerer 时，阻塞式调用返回错误；有限时长的 timed 调用到期后返回 pending。
+
+随附 preset 使用阻塞模式。要启用 timed 模式，请在当前 preset 的 `config.plugins` 列表中，将 `tool-ask-user` 条目设为 `mode: timed`：
+
+```yaml
+- id: tool-ask-user
+  name: '@deepseek-ai/dsh-tool-ask-user'
+  config:
+    mode: timed
+    timeout: 120
+```
+
+以上片段是插件条目，不是顶层 `--patch` 条目。在 Web profile 中，请修改 `preset-standard` 的插件列表，或使用 Agent Preset 编辑器。`mode: legacy` 或省略配置会保留阻塞式 schema。条目中的 `timeout` 默认适用于每次 timed 调用；设为 `-1` 时会无限期等待，除非模型传入正数期限。模型传入的 `-1` 只适用于该次调用，包括其中的所有问题。
 
 ### 何时调用该工具
 
-当模型需要确认、选择结果或缺失的信息才能继续时，调用 `ask_user_question`。发送一个或多个问题，每个问题携带稳定的 `id`（回答中会原样包含）；推荐选项放在首位，并在标签末尾追加 `(Recommended)`。
+发送一个或多个问题，每个问题的 `id` 在本次调用内必须唯一；回答会带回这些 id。推荐选项放在首位，并在标签末尾追加 `(Recommended)`。可选的单次调用 `timeout` 以秒为单位；如果没有回答就无法安全继续，请使用 `-1`。超时绝不表示批准。在 Web 卡片中，开始编辑或选择“慢慢回答”也会让该 Client 的等待持续到提交或取消。
 
 ```json
 {
@@ -49,7 +61,9 @@ kind: "package-reference"
 
 ### 模型得到什么
 
-工具为每个问题返回一个回答对象：`selected` 保存选中的选项标签，`custom` 携带自由填写的回答——对多选题补充 `selected`，对单选题覆盖它。Native 渲染器保留紧凑的 JSON 文本形式。
+收到回答时，工具为每个问题返回一项。`selected` 保存选项标签；`custom` 可以补充多选答案，或替代单选选项。跳过的回答项具有空 `selected`，且没有 `custom`。
+
+对于有限时长的 timed 调用，`{ "pending": true, "callId": "…" }` 表示前台等待结束时仍没有回答。问题仍可回答，模型可以继续独立工作。之后的回答以用户消息送达，由 `kind`、`tool` 和 `callId` 标识。Web 对话会配对展示问题与回答；其他消费方收到紧凑 JSON 文本。
 
 ```json
 { "answers": [{ "id": "cleanup", "selected": ["Yes, delete them (Recommended)"] }] }
@@ -57,7 +71,7 @@ kind: "package-reference"
 
 ### 调用何时失败
 
-工具调用会阻塞到用户作答，并且只能通过当前轮次的信号取消。没有 answerer 接受、调用被中止、或调用方不是确切的存活运行时根，都会以模型在工具结果中看到的错误结算——最值得注意的是，归属于另一个 agent 的存活子级会被拒绝（`DELEGATED_CALLER`），必须在最终结果中包含尚未解决的问题或决定。
+Legacy 调用和 `timeout: -1` 调用会等待回答或取消；没有 answerer 接受时返回错误。有限时长的 timed 调用若没有 answerer，则在到期后返回 pending。取消调用，或调用方不是确切的存活运行时根时，也会返回错误。存活的子 agent 会以 `DELEGATED_CALLER` 被拒绝，必须在最终结果中包含尚未解决的决定。
 
 -----
 
@@ -73,12 +87,13 @@ kind: "package-reference"
 
 | 文件 | 职责 |
 |---|---|
-| [`src/index.ts`](src/index.ts) | 工具注册：`ask_user_question` schema、执行路径、结果渲染 |
+| [`src/index.ts`](src/index.ts) | 默认阻塞式工具定义与模式选择 |
+| [`src/timed.ts`](src/timed.ts) | 显式启用的计时工具定义与结果渲染 |
 | — | 不发布运行时不变式伴生入口；此模型侧适配器没有独立的生命周期流；执行关系由其调用的能力 seam 负责。 |
 
 ### 消费方角色
 
-该插件以 `['tools', 'userQuestions']` 注入，在 `ctx.tools` 上注册一个 `defineTool` 条目。`execute` 把模型参数映射为 `AskUserQuestionRequest`，转发确切的调用 agent 与当前轮次的信号，并把接受的回答映射回规范的 `answers` 数组。身份检查、意图校验、waterfall（瀑布式事件）分派与错误分类由 seam 拥有；本包只做转换。
+插件只注册一个工具定义。Legacy 模式调用 `ask()`；timed 模式对正数期限调用 `askTimed()`，对 `-1` 调用 `ask()`。两者都向 `ctx.userQuestions` 传递调用方 agent 和轮次信号。Timed 请求在 `wait` 中包含工具调用 id，Client 因此可以重新打开对应卡片。投影从记录的工具 schema 的 `timeout` 字段识别 timed 原生调用，即使某次调用省略该参数也一样。
 
 ### 结果渲染
 
@@ -107,7 +122,7 @@ kind: "package-reference"
 
 #### 模型看到的内容
 
-模型会看到生成的 [`ask_user_question` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-ask-user)，其中包含问题 id、提示语、标题、选项与多选标志。
+随附 preset 会公开原有的阻塞式 [`ask_user_question` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-ask-user)。自定义 Cordis 行设置 `mode: timed` 后，会切换到包含问题 id、提示语、标题、选项、多选标志、`timeout` 与待处理结果的异步 schema；模型只会看到被选中的定义。
 
 #### Token 影响
 
@@ -121,7 +136,7 @@ kind: "package-reference"
 
 #### 模型看到的内容
 
-模型提出的完整问题保留在 assistant 工具调用参数中。用户回答后，下一步会看到精确采用 `{"answers":[{"id":"<id>","selected":["<label>"],"custom":"<text>"}]}` 形式的紧凑 JSON；不使用 `custom` 时会省略该字段，`selected` 可以包含零个、一个或多个标签。调用等待期间的 UI 交互不属于模型上下文。
+assistant 工具调用保留问题。等待期间收到的回答会在下一步显示为紧凑的 `{"answers":[{"id":"<id>","selected":["<label>"],"custom":"<text>"}]}` JSON；未使用的 `custom` 会省略。计时到期的调用返回 `{"pending":true,"callId":"<pending-call-id>","message":"<instruction>"}`。之后的回答以用户消息送达，包含 `kind: "answer_to_pending_question"`、`tool: "ask_user_question"`、调用 id、原问题和答案。提交之前的 UI 活动不属于模型上下文。
 
 #### Token 影响
 
@@ -138,7 +153,8 @@ kind: "package-reference"
 
 这些限制说明该工具何时不合适。它们是当前包约束，不是 UI 积压事项。
 
-- **待处理问题会阻塞工具调用，直至用户作答**：该工具未声明 `timeout-policy` 预算；取消仅沿用当前轮次的 `exec.signal`。
+- **Legacy 工具不会报告 pending**：它只返回回答或错误。原生 legacy 调用不进入 `userQuestions` 投影；中断的调用不能接受迟到回答。
+- **中断的 PTC 等待可能丢失问题**：若 `run_code` 进程在 `ask_user_question` 子调用记录 `tool/ptc-dispatch` 结果前结束，投影无法重建该子调用以接受迟到回答。
 - **运行时中归属于其他 agent 的 subagent 不能向用户提问**：`ask_user_question` 会以 `DELEGATED_CALLER` 拒绝归属于另一个 agent 的存活子级；该子级必须在最终结果中包含尚未解决的问题或决定。持久谱系不能决定这一边界，因此带有谱系的会话恢复为运行时根后可以正常提问。
 - **Native 回答渲染为 JSON 文本**：规范值仍为结构化数据，但模型侧结果使用紧凑 JSON，而非更丰富的内容块词汇。
 
@@ -148,6 +164,6 @@ kind: "package-reference"
 <details>
 <summary>维护者的工作上下文——点击展开</summary>
 
-无。
+[`userQuestions` 投影](../user-questions/src/projection.ts)读取记录的工具 schema，而不是调用参数：timed 调用可以省略 `timeout`，timed `-1` 调用也仍使用 timed schema。改变投影折叠语义时必须提高 `stateVersion`，让持久化缓存从日志重新折叠。
 
 </details>

package/lib/index.js

@@ -1,5 +1,205 @@
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import "@deepseek-ai/dsh-user-questions";
+import z from "@deepseek-ai/schemastery";
+import { TIMED_WAIT_PARAMETER } from "@deepseek-ai/dsh-user-questions";
+//#region lib/types/timed.js
+/**
+* Opt-in timed `ask_user_question` tool definition.
+*/
+function validateTimeout(timeout) {
+	if (timeout !== -1 && (!Number.isInteger(timeout) || timeout < 1 || timeout > 2147483)) throw new Error("timeout must be -1 or a positive integer up to 2147483 seconds");
+	return timeout;
+}
+function validateQuestionIds(questions) {
+	const ids = /* @__PURE__ */ new Set();
+	for (const question of questions) {
+		if (ids.has(question.id)) throw new Error(`question id ${JSON.stringify(question.id)} must be unique within this call`);
+		ids.add(question.id);
+	}
+}
+const description$1 = "Ask brief, direct, self-contained questions about missing information, preferences, or decisions. Use user-facing terms; assume no knowledge of background work or internal names. Use distinct stable question IDs. A submitted skipped question is an answer item with empty selected and no custom; pending instead means no answer batch arrived before the timeout and the user can still answer.";
+/**
+* Instruction the pending result carries in its `message` field. It is a field
+* of the result value rather than prose beside it because the recorded result
+* text is read back as one JSON object: the `userQuestions` projection decides
+* from it that the call stays answerable, and the Client question row decides
+* from it that the recorded result is the timeout, not an answer batch.
+*/
+const pendingNotice = "No answer batch arrived before the timeout. This is pending, not a skipped answer. Continue useful independent work. The user can still answer; their reply will be a user message identified as answer_to_pending_question with this callId and the original questions. Do not treat this as permission.";
+/**
+* Translate the model schema into the service request without changing ownership.
+* @param questions - Model-supplied questions in tool-schema form.
+* @param exec - Execution context that owns the agent and cancellation signal.
+* @returns The corresponding user-question service request.
+*/
+function questionRequest(questions, exec) {
+	return {
+		questions: questions.map((question) => ({
+			id: question.id,
+			question: question.question,
+			...question.header !== void 0 ? { header: question.header } : {},
+			...question.options !== void 0 ? { options: question.options.map((option) => ({ ...option })) } : {},
+			...question.multi_select !== void 0 ? { multiSelect: question.multi_select } : {}
+		})),
+		...exec.agent !== void 0 ? { agent: exec.agent } : {},
+		signal: exec.signal
+	};
+}
+/**
+* Copy service-owned answer arrays into the model-facing result.
+* @param result - Answer returned by the user-question service.
+* @returns A detached model-facing answer payload.
+*/
+function answerResult(result) {
+	return { answers: result.answers.map((answer) => ({
+		id: answer.id,
+		selected: [...answer.selected],
+		...answer.custom !== void 0 ? { custom: answer.custom } : {}
+	})) };
+}
+/**
+* Register the opt-in timed tool definition.
+* @param ctx - Agent-scoped context receiving the tool.
+* @param timeout - Default foreground wait in seconds.
+*/
+function registerTimedAskUser(ctx, timeout = 120) {
+	const defaultTimeout = validateTimeout(timeout);
+	ctx.tools.register(defineTool({
+		name: "ask_user_question",
+		description: description$1,
+		parameters: {
+			questions: {
+				type: "array",
+				required: true,
+				description: "Questions to ask the user.",
+				items: {
+					type: "object",
+					additionalProperties: true,
+					properties: {
+						id: {
+							type: "string",
+							required: true,
+							description: "Stable id for this question; echoed in the answer."
+						},
+						question: {
+							type: "string",
+							required: true,
+							description: "The specific question to ask the user."
+						},
+						header: {
+							type: "string",
+							description: "Optional short heading for the question, such as \"Confirm\" or \"Choose Mode\"."
+						},
+						options: {
+							type: "array",
+							description: "Optional choices to show the user. If you recommend one, put it first and append \"(Recommended)\" to that label.",
+							items: {
+								type: "object",
+								additionalProperties: true,
+								properties: {
+									label: {
+										type: "string",
+										required: true,
+										description: "Short user-facing option label."
+									},
+									description: {
+										type: "string",
+										description: "One sentence explaining the tradeoff or impact."
+									}
+								}
+							}
+						},
+						multi_select: {
+							type: "boolean",
+							description: "Whether the user may select more than one option. Defaults to false."
+						}
+					}
+				}
+			},
+			[TIMED_WAIT_PARAMETER]: {
+				type: "integer",
+				description: `Wait seconds for the entire batch (default ${defaultTimeout}); omit unless the user specifies a duration. Use -1 only when an answer is required before proceeding.`
+			}
+		},
+		output: {
+			schema: { oneOf: [{
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					pending: {
+						type: "boolean",
+						enum: [true],
+						required: true,
+						description: "True when the foreground wait expired before the user submitted an answer batch. The questions remain answerable; this is not a skipped answer."
+					},
+					callId: {
+						type: "string",
+						required: true,
+						description: "Tool call whose unanswered questions remain pending."
+					},
+					message: {
+						type: "string",
+						required: true,
+						description: "How to continue while the questions stay answerable."
+					}
+				}
+			}, {
+				type: "object",
+				additionalProperties: false,
+				properties: { answers: {
+					type: "array",
+					required: true,
+					description: "Submitted answer batch with one item per question. A skipped question has empty selected and no custom; unlike pending, the user has completed the batch.",
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							id: {
+								type: "string",
+								required: true,
+								description: "Stable question id echoed from the request."
+							},
+							selected: {
+								type: "array",
+								required: true,
+								items: { type: "string" },
+								description: "Selected option labels. Empty with no custom means the user explicitly skipped this question."
+							},
+							custom: {
+								type: "string",
+								description: "Optional free-form answer; omitted for a skipped question."
+							}
+						}
+					}
+				} }
+			}] },
+			render: (_args, value) => [{
+				type: "text",
+				text: JSON.stringify(value)
+			}]
+		},
+		async execute(args, exec) {
+			const timeout = validateTimeout(args.timeout ?? defaultTimeout);
+			validateQuestionIds(args.questions);
+			const request = questionRequest(args.questions, exec);
+			if (timeout !== -1) {
+				if (exec.agent === void 0) throw new Error("timed questions require a live agent");
+				const result = await ctx.userQuestions.askTimed({
+					...request,
+					agent: exec.agent
+				}, exec.callId, timeout * 1e3);
+				return "pending" in result ? {
+					...result,
+					message: pendingNotice
+				} : answerResult(result);
+			}
+			return answerResult(await ctx.userQuestions.ask({
+				...request,
+				wait: { callId: exec.callId }
+			}));
+		}
+	}));
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * Model-facing Consumer of the `ctx.userQuestions` capability seam.
@@ -8,10 +208,18 @@ import "@deepseek-ai/dsh-user-questions";
 *
 * @module @deepseek-ai/dsh-tool-ask-user
 */
+const Config = z.object({
+	mode: z.union(["legacy", "timed"]).default("legacy"),
+	timeout: z.union([-1, z.number().step(1).min(1).max(2147483)]).default(120)
+});
 const name = "tool-ask-user";
 const inject = ["tools", "userQuestions"];
 const description = "Ask the user a concise question when you need confirmation, a choice, or missing information before proceeding.";
-function apply(ctx) {
+function apply(ctx, config = {}) {
+	if (config.mode === "timed") {
+		registerTimedAskUser(ctx, config.timeout);
+		return;
+	}
 	ctx.tools.register(defineTool({
 		name: "ask_user_question",
 		description,
@@ -113,4 +321,4 @@ function apply(ctx) {
 	}));
 }
 //#endregion
-export { apply, inject, name };
+export { Config, apply, inject, name };

package/lib/types/index.d.ts

@@ -6,8 +6,17 @@
  * @module @deepseek-ai/dsh-tool-ask-user
  */
 import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
 import '@deepseek-ai/dsh-user-questions';
+/** Cordis row selecting the tool schema and its default foreground wait. */
+export interface Config {
+    /** Tool definition selected by this Cordis row. Defaults to the blocking legacy tool. */
+    mode?: 'legacy' | 'timed';
+    /** Foreground wait before automatic continuation. Defaults to 120 seconds. */
+    timeout?: number;
+}
+export declare const Config: z<Config>;
 export declare const name = "tool-ask-user";
 export declare const inject: string[];
-export declare function apply(ctx: Context): void;
+export declare function apply(ctx: Context, config?: Config): void;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/timed.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Opt-in timed `ask_user_question` tool definition.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/**
+ * Register the opt-in timed tool definition.
+ * @param ctx - Agent-scoped context receiving the tool.
+ * @param timeout - Default foreground wait in seconds.
+ */
+export declare function registerTimedAskUser(ctx: Context, timeout?: number): void;
+//# sourceMappingURL=timed.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-tool-ask-user",
   "description": "Model-facing ask_user_question tool over the ctx.userQuestions seam",
-  "version": "0.1.7-rc.2",
+  "version": "0.2.0-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,17 +27,20 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-user-questions": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-user-questions": "0.2.0-rc.2",
     "@deepseek-ai/cordis": "~4.0.4"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-llm": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-agent": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-system-prompt": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
-    "@deepseek-ai/dsh-user-questions": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-agent": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-llm": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
+    "@deepseek-ai/dsh-user-questions": "0.2.0-rc.2",
     "@deepseek-ai/cordis": "~4.0.4"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "~3.18.4"
   }
 }