@hasna-internal/kai-tool-ask-user 0.1.1-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/interaction/tool-ask-user/README.md
+README.md: bf2ba369fca36c462c6155ed2354ab3d0e930dd0
+README.zh.md: 067235d84d70d2f3278fd39f5c01f130373d3ac2

package/README.md

@@ -0,0 +1,58 @@
+# @hasna-internal/kai-tool-ask-user
+
+English | [中文](README.zh.md)
+
+Model-facing `ask_user_question` tool over `ctx.userQuestions`. It lets the model ask the human a concise question when it needs confirmation, a choice, or missing information before continuing.
+
+## Tool
+
+`ask_user_question` accepts:
+
+- `questions` — required non-empty array of question objects.
+- `id` — required stable id on each question, echoed in the answer.
+- `question` — required question text for each question.
+- `header` — optional short heading.
+- `options` — optional choices with `label` and `description`. If recommending a choice, put it first and append `(Recommended)` to that label.
+- `multi_select` — whether that question may return more than one selected option.
+
+The tool calls `ctx.userQuestions.ask()` and returns canonical `{ answers: [{ id, selected, custom? }] }`. `selected` contains option labels; `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 `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`.
+
+## Role
+
+This is the Consumer package for the user-questions seam. It does not render UI and does not know how input is collected; it only translates model arguments into `AskUserQuestionRequest` and returns the human answer to the agent loop.
+
+## Model Experience
+
+### Tool schema
+
+#### 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.
+
+#### Token effect
+
+Fixed schema cost on every request where the tool is visible.
+
+#### KV Cache effect
+
+Prefix-stable while the definition and visibility are unchanged. Plugin lifecycle or scoped restrictions may invalidate reuse from this schema.
+
+### Tool-call history and result
+
+#### 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.
+
+#### Token effect
+
+Arguments and answer JSON are data-dependent retained tokens; there is no token cost while waiting for the human.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **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.
+- **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.

package/README.zh.md

@@ -0,0 +1,58 @@
+# @hasna-internal/kai-tool-ask-user
+
+[English](README.md) | 中文
+
+模型侧 `ask_user_question` 工具，基于 `ctx.userQuestions` 实现。当模型需要确认、选择结果或缺失的信息才能继续时，它可以借此向用户提出简明问题。
+
+## 工具
+
+`ask_user_question` 接受以下参数：
+
+- `questions`：必填的非空问题对象数组。
+- `id`：每个问题必填的稳定 id，会原样包含在回答中。
+- `question`：每个问题必填的问题文本。
+- `header`：可选的简短标题。
+- `options`：可选选项，包含 `label` 和 `description`。如需推荐某个选项，请将其置于首位，并在该标签末尾追加 `(Recommended)`。
+- `multi_select`：该问题是否可以返回多个选中的选项。
+
+工具调用 `ctx.userQuestions.ask()`，并返回规范的 `{ answers: [{ id, selected, custom? }] }`。`selected` 包含选项标签；`custom` 携带自由填写的回答，对于多选题会补充 `selected`，对于单选题则会覆盖它。Native 渲染器会保留紧凑的 JSON 文本形式 `{ "answers": [{ "id": "...", "selected": ["..."], "custom": "..." }] }`。
+
+## 职责
+
+此包是用户交互 seam 的Consumer 包。它不渲染 UI，也不了解输入的收集方式；它只将模型参数转换为 `AskUserQuestionRequest`，并把用户回答返回给 agent loop（智能体循环）。
+
+## 模型体验
+
+### 工具 schema
+
+#### 模型看到的内容
+
+模型会看到生成的 [`ask_user_question` schema](../../../docs/tool-catalog.zh.md#deepseek-aidsh-tool-ask-user)，其中包含问题 id、提示语、标题、选项和多选标志。
+
+#### Token 影响
+
+工具可见时，每个请求都会产生固定的 schema token 开销。
+
+#### KV Cache 影响
+
+只要定义和可见性保持不变，前缀即可稳定复用。插件生命周期变化或作用域限制可能会使从此 schema 起的缓存复用失效。
+
+### 工具调用历史与结果
+
+#### 模型看到的内容
+
+模型提出的完整问题保留在 assistant 工具调用参数中。用户回答后，下一步会看到精确采用 `{"answers":[{"id":"<id>","selected":["<label>"],"custom":"<text>"}]}` 形式的紧凑 JSON；不使用 `custom` 时会省略该字段，`selected` 可以包含零个、一个或多个标签。调用等待期间的 UI 交互不属于模型上下文。
+
+#### Token 影响
+
+参数和回答 JSON 是依数据而定的保留 token；等待用户时不会产生 token 开销。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **待处理问题会阻塞工具调用，直至用户作答**：该工具未声明 `timeout-policy` 预算；取消仅沿用当前轮次的 `exec.signal`。
+- **运行时中归属于其他 agent 的 subagent 不能向用户提问**：`ask_user_question` 会以 `DELEGATED_CALLER` 拒绝归属于另一个 agent 的存活子级；该子级必须在最终结果中包含尚未解决的问题或决策。持久谱系不能决定这一边界，因此带有谱系的会话恢复为运行时根后可以正常提问。
+- **Native 回答渲染为 JSON 文本**：规范值仍为结构化数据，但模型侧结果使用紧凑 JSON，而非更丰富的内容块词汇。

package/lib/index.js

@@ -0,0 +1,116 @@
+import { defineTool } from "@hasna-internal/kai-tools";
+import "@hasna-internal/kai-user-questions";
+//#region lib/types/index.js
+/**
+* Model-facing Consumer of the `ctx.userQuestions` capability seam.
+* The tool pauses until a UI provider returns a human answer, then feeds that
+* answer back into the agent loop as an ordinary tool result.
+*
+* @module @hasna-internal/kai-tool-ask-user
+*/
+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. Send one or more questions, each with a stable id that will be echoed in the answer.";
+function apply(ctx) {
+	ctx.tools.register(defineTool({
+		name: "ask_user_question",
+		description,
+		parameters: { questions: {
+			type: "array",
+			required: true,
+			description: "Questions to ask the user before continuing.",
+			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."
+					}
+				}
+			}
+		} },
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: { answers: {
+					type: "array",
+					required: true,
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							id: {
+								type: "string",
+								required: true
+							},
+							selected: {
+								type: "array",
+								required: true,
+								items: { type: "string" }
+							},
+							custom: { type: "string" }
+						}
+					}
+				} }
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: JSON.stringify(value)
+			}]
+		},
+		async execute(args, exec) {
+			return { answers: (await ctx.userQuestions.ask({
+				questions: args.questions.map((question) => ({
+					id: question.id,
+					question: question.question,
+					...question.header !== void 0 ? { header: question.header } : {},
+					...question.options !== void 0 ? { options: question.options } : {},
+					...question.multi_select !== void 0 ? { multiSelect: question.multi_select } : {}
+				})),
+				...exec.agent !== void 0 ? { agent: exec.agent } : {},
+				signal: exec.signal
+			})).answers.map((answer) => ({
+				id: answer.id,
+				selected: [...answer.selected],
+				...answer.custom !== void 0 ? { custom: answer.custom } : {}
+			})) };
+		}
+	}));
+}
+//#endregion
+export { apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hasna-internal/kai-tool-ask-user`.
+* @module @hasna-internal/kai-tool-ask-user/invariant
+*/
+const PACKAGE_NAME = "@hasna-internal/kai-tool-ask-user";
+/** Cordis companion plugin name. */
+const name = "tool-ask-user-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this model-facing adapter has no independent lifecycle stream; execution
+* relations are owned by the capability seam it calls.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Model-facing Consumer of the `ctx.userQuestions` capability seam.
+ * The tool pauses until a UI provider returns a human answer, then feeds that
+ * answer back into the agent loop as an ordinary tool result.
+ *
+ * @module @hasna-internal/kai-tool-ask-user
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import '@hasna-internal/kai-user-questions';
+export declare const name = "tool-ask-user";
+export declare const inject: string[];
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-tool-ask-user`.
+ * @module @hasna-internal/kai-tool-ask-user/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-ask-user-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@hasna-internal/kai-tool-ask-user",
+  "description": "Model-facing ask_user_question tool over the ctx.userQuestions seam",
+  "version": "0.1.1-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/interaction/tool-ask-user"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hasna-internal/kai-agent": "^0.1.1-rc.2",
+    "@hasna-internal/kai-tools": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@hasna-internal/kai-user-questions": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@hasna-internal/kai-system-prompt": "^0.1.1-rc.2",
+    "@hasna-internal/kai-llm": "^0.1.1-rc.2",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-user-questions": "^0.1.1-rc.2",
+    "@hasna-internal/kai-tools": "^0.1.1-rc.2",
+    "@hasna-internal/kai-agent": "^0.1.1-rc.2"
+  }
+}