dsh-plugin-guide 0.3.41 → 0.4.0

package/references/official-docs/docs/subsystems/user-questions.i18n.yaml

@@ -1,28 +0,0 @@
-# Bilingual-pair consistency record for user-questions.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/subsystems/user-questions.md
-/user-interaction:
-  en: bc5bf42af08a66aa
-  zh: a90222f49abd2d0c
-/user-interaction/question-options:
-  en: 88cceb3cf383248e
-  zh: 8e1d2627823b1ffc
-/user-interaction/presentation-intent:
-  en: aca3811ea3f0c2ef
-  zh: 6cf2aea40c7dece8
-/user-interaction/question-item:
-  en: 1ad4373e6fdfe4c7
-  zh: efb8d41ebe7224f8
-/user-interaction/ask-request:
-  en: e10cf6c8c9c20962
-  zh: 0b347b40c12b6b25
-/user-interaction/answer:
-  en: efd2dbb95a885d0e
-  zh: 7a20c75c4ea6a9e0
-/user-interaction/timed-questions-and-late-replies:
-  en: 74fa698d4a115e80
-  zh: 4e9b03b5eab2ae5e
-/user-interaction/errors:
-  en: 5762b1498a426ab6
-  zh: bb9987ec82103620

package/references/official-docs/docs/subsystems/user-questions.md

@@ -1,307 +0,0 @@
-# User Interaction
-
-English | [中文](user-questions.zh.md)
-
-The user-questions seam of [dsh-user-questions](../../packages/interaction/user-questions). It is the provider-neutral vocabulary a tool or permission plugin uses when it needs the human to answer before the agent can continue. Agent-scoped waterfall listeners compose the available UI surfaces, including listeners relayed to a connected client.
-
-Source: [`packages/interaction/user-questions/src/index.ts`](../../packages/interaction/user-questions/src/index.ts)
-
-## Question options
-
-`AskUserQuestionOption` contains one selectable choice. `label` is the user-facing option text and also the model-facing selected value; `description` is optional UI help text.
-
-```ts type-equiv
-/** One selectable answer offered to the user. */
-interface AskUserQuestionOption {
-  /** User-facing label. */
-  label: string
-  /** Optional extra context rendered by capable UIs. */
-  description?: string
-}
-```
-
-## Presentation intent
-
-`AskUserQuestionIntent` optionally declares a known decision kind. It is tagged on `kind` so intents can be added; a UI that does not recognise a tag renders the generic option list. An intent changes presentation only — a UI honouring it answers with the same option labels a generic UI would send, so the caller reads the same answer fields either way. `approve` names the affirmative option instead of relying on option order. `ask()` rejects the two assertions no type can carry: an `approve` naming none of its own question's options, and an intent on a question with no `detail`.
-
-```ts type-equiv
-/**
- * A caller-declared presentation intent: the question IS this kind of
- * decision, so a UI that recognises the tag may present it as such instead of as a
- * generic option list. Tagged so further intents can be added; a UI that does
- * not know a tag renders the generic flow, and the answer encoding is identical
- * either way — an intent changes presentation only, never the protocol.
- */
-type AskUserQuestionIntent = {
-  /** A plan submitted for review: `detail` is the plan markdown `ask()` requires, and the decision approves or declines it. */
-  kind: 'plan-review'
-  /**
-   * The option label that approves the plan; every other option declines it.
-   * Named rather than positional so no UI infers the verdict from option order.
-   * An `approve` naming no option of its own question is rejected at `ask()`.
-   */
-  approve: string
-  /** Logged tool invocation whose arguments contain the reviewed plan. */
-  callId?: ToolCallId
-}
-```
-
-## Question item
-
-`AskUserQuestionItem` is one question in a request. The caller supplies a stable `id`, which is echoed back with the answer so batched questions remain routable. Optional `detail` carries supporting text that providers render with the question but keep out of selectable option labels.
-
-```ts type-equiv
-/** One question in a user-questions request. */
-interface AskUserQuestionItem {
-  /** Stable caller-provided question id, echoed in the answer. */
-  id: string
-  /** The question to display. */
-  question: string
-  /** Optional supporting detail rendered with the question but kept out of option labels. */
-  detail?: string
-  /** Optional short heading/group label. */
-  header?: string
-  /** Optional choices the UI can render as a menu. */
-  options?: AskUserQuestionOption[]
-  /** Whether more than one option may be selected. Defaults to single-select. */
-  multiSelect?: boolean
-  /** Optional presentation intent for capable UIs; absent asks for the generic option list. */
-  intent?: AskUserQuestionIntent
-}
-```
-
-## Ask request
-
-`AskUserQuestionRequest` is the cross-package request. `questions` is an array so a UI can present related prompts in one flow while preserving a stable id per answer. When present, `agent` is the exact live caller; the interaction seam admits it only while the live registry identifies that instance as a runtime root.
-
-```ts type-equiv
-/** Request for a human answer. */
-interface AskUserQuestionRequest extends AskUserQuestionRequestEvent {}
-```
-
-## Answer
-
-Providers return one answer item per question id. `selected` contains selected option labels, and `custom` carries a free-form "Other" answer when the user typed one. For a single-select question, `custom` overrides the selected choice and `selected` is empty. For a multi-select question, `custom` may supplement the labels in `selected`. A UI may also use an item with empty `selected` and no `custom` to preserve a skipped question in an otherwise completed batch.
-
-```ts type-equiv
-/** Answer to one question. */
-interface AskUserQuestionAnswerItem {
-  /** The answered question id. */
-  id: string
-  /** Selected option labels. May accompany custom text for a multi-select question. */
-  selected: string[]
-  /** Optional free-text "Other" answer. */
-  custom?: string
-}
-```
-
-```ts type-equiv
-/** The human's answer. */
-interface AskUserQuestionAnswer {
-  /** Structured answers keyed by question id. */
-  answers: AskUserQuestionAnswerItem[]
-}
-```
-
-Timed answerers receive `wait: { callId, timed: true }`. The call id identifies the card and the foreground wait. The Client calls `attachWait` to claim the wait and obtain its remaining duration; transport forwards the original event without inspecting or rewriting these fields. A `wait` without `timed` identifies an indefinite card-keyed request. An absent `wait` identifies a blocking request without a card key.
-
-```ts type-equiv
-/** Client-safe payload declared for the user-question answerer waterfall. */
-interface AskUserQuestionRequestEvent {
-  /** Questions to display. */
-  questions: AskUserQuestionItem[]
-  /** Agent identity projected to the corresponding Client Context in transit. */
-  agent?: Agent
-  /** Cancellation lifetime of the pending request. */
-  signal?: AbortSignal
-  /**
-   * Tool call the Client card is keyed by. Timed answerers attach to the
-   * business wait stream before starting their local countdown.
-   */
-  wait?: {
-    /** Tool call the Client card is keyed by. */
-    callId: ToolCallId
-    /** True for a foreground wait that requires a Client claim; absent for indefinite waits. */
-    timed?: boolean
-  }
-}
-```
-
-## Timed questions and late replies
-
-A timed question waits for a bounded foreground window and then lets the agent continue independent work. If the user answers inside the window, the tool returns the answer batch; otherwise `TimedUserQuestionResult` is `{ pending: true, callId }`. Pending means the question is still answerable; it is not an empty answer, a refusal, a confirmation, or permission.
-
-```ts type-equiv
-/** Timed ask result returned when the foreground answer window closes. */
-type TimedUserQuestionResult = AskUserQuestionAnswer | { pending: true; callId: ToolCallId }
-```
-
-A Client claim is a business Remote stream, not a Gateway delivery. `TimedQuestionWait` holds the original Host deadline and runs its timer only while no claim exists. Its `attachWait` stream yields the current remaining duration, and the Client counts down with its own clock. Focus, editing, and Take time stay local. Stream cancellation releases that claim; after the last claim leaves, the Host resumes the original deadline. An unattended timeout aborts the foreground waterfall's private signal and returns pending without cancelling the Turn. Gateway and `api-remotes` contain no question-specific timing policy.
-
-The `userQuestions` Session projection folds existing events into the answerable question set and the settled one; no wait state, focus state, or deadline is logged. Each `request/header` records the exact tool schemas the model saw. Native calls are tracked only when that header declares the timed `ask_user_question` schema with a `timeout` parameter; the blocking legacy tool never declares it. A native `tool/call` opens a question. A `tool/result` marks it `continued` only when it carries the pending payload or is the synthetic `TOOL_OUTCOME_UNKNOWN` result Session resume repair appends; an answer batch moves it into `settled` with that batch, and any failure drops it. A `run_code` PTC sub-call enters the projection when its `tool/ptc-dispatch` result is pending, even though the request header exposes only `run_code`. A late reply moves a continued question into `settled` when its message is admitted as `user/message`, together with the answer batch read out of that message: the timed call's own result recorded the timeout, so a transcript row has nowhere else to read what the user finally chose. A queued reply can be canceled before admission and leaves the question answerable. A reply whose text carries no readable batch settles the call with no answers; one naming a call that is not active changes nothing.
-
-```ts type-equiv
-/** `open` while the tool call may still return the answer; `continued` once the answer can only arrive as a new turn. */
-type UserQuestionState = 'open' | 'continued'
-```
-
-```ts type-equiv
-/** One unanswered timed `ask_user_question` call reconstructed from the Session log. */
-interface PendingUserQuestion {
-  readonly callId: ToolCallId
-  readonly questions: readonly AskUserQuestionItem[]
-  readonly state: UserQuestionState
-}
-```
-
-```ts type-equiv
-/**
- * One timed `ask_user_question` call and the answers it settled with: the
- * batch its own result carried when the user answered inside the window,
- * otherwise the batch its late reply carried, because that call's own result
- * recorded the timeout. A transcript row reads what the user finally answered
- * from here, and only a call listed here was a timed one.
- */
-interface SettledUserQuestion {
-  /** The settled call. */
-  readonly callId: ToolCallId
-  /** The recorded batch, one entry per question; empty when the late reply carried none. */
-  readonly answers: readonly AskUserQuestionAnswerItem[]
-}
-```
-
-```ts type-equiv
-/**
- * Both halves of one Session's timed `ask_user_question` state, as every
- * Client reads them. A call made while the blocking legacy tool was in
- * effect appears in neither half.
- */
-interface UserQuestionProjectionView {
-  /** Calls that can still take an answer, in ask order. */
-  readonly active: readonly PendingUserQuestion[]
-  /** Calls an answer settled, in settlement order. */
-  readonly settled: readonly SettledUserQuestion[]
-}
-```
-
-An open question accepts answers only through the waterfall. Once it is `continued`, the `answer` Remote method queues a user message for the owning agent and wakes it if idle. The message has source `user-question-reply`, outcome `answered`, and an `answer_to_pending_question` payload. The method returns `false` for an open or unknown call, rejects a second queued reply with `REPLY_QUEUED` even after a Host restart, and rejects incomplete or duplicate answer batches with `BAD_ANSWER`.
-
-Closing the Client panel sends nothing. A foreground timeout ends only the tool wait. Continued questions have no deadline; they stay answerable until a reply is admitted.
-
-After a Host restart, the Remote layer resumes the root agent when the Session reopens. A late reply then enters a new turn.
-
-## Errors
-
-`UserQuestionError` extends `HarnessError`, so `ctx.tools.execute()` preserves `{ name, code }` for model-facing tool failures such as `EMPTY_QUESTIONS`, `BAD_INTENT`, `NO_PROVIDER`, `ASK_ABORTED`, or UI-side cancellation.
-
-```ts type-equiv
-/** Stable error taxonomy for user-questions failures. */
-class UserQuestionError extends HarnessError {
-  constructor(message: string, code: string, options?: ErrorOptions) {
-    super(message, code, options)
-    this.name = 'UserQuestionError'
-  }
-}
-```
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxuserquestions--userquestionservice"></a>
-
-### `ctx.userQuestions` — `UserQuestionService`
-
-`ctx.userQuestions`: validation plus the scoped answerer waterfall.
-
-```ts cordis-catalog
-/**
- * Answer a continued question. The reply is steered into the agent as a
- * user message whose source names the call; that message is also the
- * record that closes the question in the projection.
- * @param agent - Live root agent for the owning Session.
- * @param callId - Continued question identity.
- * @param answer - Complete structured answer batch, one item per question of the call.
- * @returns Whether the question is still continued; an accepted reply stays
- *   queued until the agent admits its user message.
- * @throws {UserQuestionError} `BAD_ANSWER` when the batch does not name each
- *   question of the call exactly once, or `REPLY_QUEUED` when a reply is
- *   already waiting for admission.
- */
-@Remote answer(agent: Agent, callId: ToolCallId, answer: AskUserQuestionAnswer): boolean
-
-/**
- * Let one answer UI hold a live timed wait. Closing the stream releases its claim.
- * @param agent - Live root agent owning the question.
- * @param callId - Foreground tool call to attach to.
- * @param signal - Remote stream cancellation, including Client disconnect.
- * @returns One Host-computed remaining duration, or no frames once the wait ended.
- */
-@Remote({ mode: 'stream' }) async *attachWait(agent: Agent, callId: ToolCallId, signal: AbortSignal): AsyncIterable<{ remainingMs: number }>
-
-/**
- * Foreground wait whose first settlement the Client decides: the Client
- * rejects with `ASK_TIMED_OUT` when its countdown ends, and this method maps
- * that code to the pending result.
- * @param request - Questions, live owner agent, and abort signal.
- * @param callId - Tool call identity the Client card is keyed by.
- * @param timeoutMs - Positive foreground wait in milliseconds.
- * @returns The answer when it arrives inside the window, otherwise a pending
- *   result, also when no connected Client claimed the request by the deadline.
- * @throws {UserQuestionError} `BAD_TIMEOUT` for a non-integer, non-positive,
- *   or oversized wait.
- */
-async askTimed( request: AskUserQuestionRequest & { agent: Agent }, callId: ToolCallId, timeoutMs: number, ): Promise<TimedUserQuestionResult>
-
-/**
- * Ask the scoped answerer waterfall and wait for the user's answer.
- *
- * When a caller supplies an agent, human interaction is valid only for the
- * exact live runtime root. Runtime ownership, not durable session lineage,
- * decides this boundary: an owned child has no human answerer and would
- * block forever, while a lineage-bearing session resumed as a new runtime
- * root may ask normally.
- *
- * @param request Questions, owner agent, and abort signal.
- * @returns The answer chosen or typed by the human.
- * @throws {UserQuestionError} code `ASK_ABORTED` when the supplied signal
- *   is already or becomes aborted, `CALLER_NOT_LIVE` when a supplied agent
- *   is not the registry's exact live instance, or `DELEGATED_CALLER` when
- *   that live agent is owned by another agent.
- */
-async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
-```
-
-Types: [Agent](core.md) · [ToolCallId](core.md)
-
-Source: [`packages/interaction/user-questions/src/index.ts`](../../packages/interaction/user-questions/src/index.ts)
-
-<a id="user-questions-events"></a>
-
-### `user-questions/*` events
-
-<a id="user-questionsrequest--waterfall"></a>
-
-#### `user-questions/request` — waterfall
-
-Ask composed answerers for structured user input. Return an answer to claim the request or call `next()` to delegate. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
-
-```ts cordis-catalog
-/**
- * Ask composed answerers for structured user input. Return an answer to
- * claim the request or call `next()` to delegate. Scope-filtered dispatch
- * (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @param request - pending user-question request.
- * @mode waterfall
- */
-'user-questions/request'( this: Scoped<Agent>, request: AskUserQuestionRequestEvent, next: () => Promise<AskUserQuestionAnswer>, ): Promise<AskUserQuestionAnswer>
-```
-
-Types: [Agent](core.md) · [Scoped](scope.md)
-
-Source: [`packages/interaction/user-questions/src/types.ts`](../../packages/interaction/user-questions/src/types.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/user-questions.zh.md

@@ -1,307 +0,0 @@
-# 用户交互
-
-[English](user-questions.md) | 中文
-
-[dsh-user-questions](../../packages/interaction/user-questions) 的用户交互 seam。它是工具或权限插件需要人类回答后 agent（智能体）才能继续时所使用的、提供方无关的词汇。Agent-scoped waterfall listener 组合可用的 UI 界面，其中包括转发到已连接 client 的 listener。
-
-源码：[`packages/interaction/user-questions/src/index.ts`](../../packages/interaction/user-questions/src/index.ts)
-
-## 问题选项
-
-`AskUserQuestionOption` 包含一个可供选择的选项。`label` 是面向用户的选项文字，同时也是面向模型的选中值；`description` 是可选的 UI 帮助文本。
-
-```ts type-equiv
-/** One selectable answer offered to the user. */
-interface AskUserQuestionOption {
-  /** User-facing label. */
-  label: string
-  /** Optional extra context rendered by capable UIs. */
-  description?: string
-}
-```
-
-## 呈现意图
-
-`AskUserQuestionIntent` 可选地声明一种已知的决策类型。它以 `kind` 作为标记，以便后续加入更多意图；不认识某个标记的 UI 会渲染通用选项列表。意图只改变呈现——遵循它的 UI 回答的选项标签与通用 UI 相同，因此调用方读到的答案字段一致。`approve` 指明表示同意的选项，而不依赖选项顺序。`ask()` 拒绝两种类型无法表达的断言：`approve` 未命名该问题自己的任何选项，以及没有 `detail` 的问题声明了意图。
-
-```ts type-equiv
-/**
- * A caller-declared presentation intent: the question IS this kind of
- * decision, so a UI that recognises the tag may present it as such instead of as a
- * generic option list. Tagged so further intents can be added; a UI that does
- * not know a tag renders the generic flow, and the answer encoding is identical
- * either way — an intent changes presentation only, never the protocol.
- */
-type AskUserQuestionIntent = {
-  /** A plan submitted for review: `detail` is the plan markdown `ask()` requires, and the decision approves or declines it. */
-  kind: 'plan-review'
-  /**
-   * The option label that approves the plan; every other option declines it.
-   * Named rather than positional so no UI infers the verdict from option order.
-   * An `approve` naming no option of its own question is rejected at `ask()`.
-   */
-  approve: string
-  /** Logged tool invocation whose arguments contain the reviewed plan. */
-  callId?: ToolCallId
-}
-```
-
-## 问题条目
-
-`AskUserQuestionItem` 是请求中的一个问题。调用方提供稳定的 `id`，它会随答案原样返回，使批量问题仍可路由。可选的 `detail` 携带辅助文本；提供方会将其随问题渲染，但不会放入可选选项标签。
-
-```ts type-equiv
-/** One question in a user-questions request. */
-interface AskUserQuestionItem {
-  /** Stable caller-provided question id, echoed in the answer. */
-  id: string
-  /** The question to display. */
-  question: string
-  /** Optional supporting detail rendered with the question but kept out of option labels. */
-  detail?: string
-  /** Optional short heading/group label. */
-  header?: string
-  /** Optional choices the UI can render as a menu. */
-  options?: AskUserQuestionOption[]
-  /** Whether more than one option may be selected. Defaults to single-select. */
-  multiSelect?: boolean
-  /** Optional presentation intent for capable UIs; absent asks for the generic option list. */
-  intent?: AskUserQuestionIntent
-}
-```
-
-## 提问请求
-
-`AskUserQuestionRequest` 是跨包请求。`questions` 是数组，这样 UI 可以在一个流程中呈现相关提示，同时保持每个回答有稳定的 id。如提供 `agent`，它必须与存活调用方是同一实例；只有当当前注册表将该实例识别为运行时根时，交互 seam 才会接纳该 agent。
-
-```ts type-equiv
-/** Request for a human answer. */
-interface AskUserQuestionRequest extends AskUserQuestionRequestEvent {}
-```
-
-## 回答
-
-提供方为每个问题 id 返回一个回答项。`selected` 包含选中的选项标签，`custom` 在用户输入自由文本时携带「其他」回答。对于单选题，`custom` 会覆盖选中的选项，且 `selected` 为空。对于多选题，`custom` 可以补充 `selected` 中的标签。UI 也可以使用 `selected` 为空且不含 `custom` 的回答项，在其余问题均已完成的批次中保留被跳过的问题。
-
-```ts type-equiv
-/** Answer to one question. */
-interface AskUserQuestionAnswerItem {
-  /** The answered question id. */
-  id: string
-  /** Selected option labels. May accompany custom text for a multi-select question. */
-  selected: string[]
-  /** Optional free-text "Other" answer. */
-  custom?: string
-}
-```
-
-```ts type-equiv
-/** The human's answer. */
-interface AskUserQuestionAnswer {
-  /** Structured answers keyed by question id. */
-  answers: AskUserQuestionAnswerItem[]
-}
-```
-
-计时回答器收到 `wait: { callId, timed: true }`。调用 id 标识卡片及前台等待。Client 调用 `attachWait` 接手等待并取得剩余时长；传输层转发原事件，不检查或改写这些字段。不带 `timed` 的 `wait` 表示无限期等待的具名卡片请求；没有 `wait` 则表示不带卡片 key 的阻塞请求。
-
-```ts type-equiv
-/** Client-safe payload declared for the user-question answerer waterfall. */
-interface AskUserQuestionRequestEvent {
-  /** Questions to display. */
-  questions: AskUserQuestionItem[]
-  /** Agent identity projected to the corresponding Client Context in transit. */
-  agent?: Agent
-  /** Cancellation lifetime of the pending request. */
-  signal?: AbortSignal
-  /**
-   * Tool call the Client card is keyed by. Timed answerers attach to the
-   * business wait stream before starting their local countdown.
-   */
-  wait?: {
-    /** Tool call the Client card is keyed by. */
-    callId: ToolCallId
-    /** True for a foreground wait that requires a Client claim; absent for indefinite waits. */
-    timed?: boolean
-  }
-}
-```
-
-## 计时问题与迟到回复
-
-计时问题在有界的前台窗口内等待，然后让 agent 继续独立工作。用户在窗口内回答，工具返回整批答案；否则 `TimedUserQuestionResult` 为 `{ pending: true, callId }`。pending 表示问题仍可回答，不是空答案、拒绝、确认或授权。
-
-```ts type-equiv
-/** Timed ask result returned when the foreground answer window closes. */
-type TimedUserQuestionResult = AskUserQuestionAnswer | { pending: true; callId: ToolCallId }
-```
-
-Client 接手通过业务 Remote stream 表达，不等同于 Gateway 投递。`TimedQuestionWait` 保存原 Host deadline，仅在没有接手记录时运行计时器。`attachWait` stream 发出当前剩余时长，Client 用本地时钟倒计时。聚焦、编辑和「慢慢回答」状态仍归本地所有。stream 取消释放相应接手记录；最后一个接手方离开后，Host 恢复原 deadline。无人接手时超时中止前台 waterfall 专属的 signal 并返回 pending，不取消 Turn。Gateway 与 `api-remotes` 不包含问答专属计时策略。
-
-`userQuestions` Session 投影把现有事件折叠成可回答的问题集合与已结算的集合；不记录任何等待状态、聚焦状态或 deadline。每个 `request/header` 都记录了模型看到的确切工具 schema。只有请求头声明了带 `timeout` 参数的 timed `ask_user_question` schema，投影才跟踪原生调用；阻塞式 legacy 工具从不声明它。原生 `tool/call` 打开一个问题。`tool/result` 只在两种情况下把它标为 `continued`：带 pending 载荷，或是 Session resume 修复补写的 `TOOL_OUTCOME_UNKNOWN` 合成结果；回答批次把它连同该批次移入 `settled`，其他结果或失败都丢弃它。`run_code` 的 PTC 子调用若在 `tool/ptc-dispatch` 结果中返回 pending，也会进入投影，尽管请求头只列出 `run_code`。迟到回复在消息获准成为 `user/message` 时，才把已继续的问题连同消息中的回答批次移入 `settled`：计时调用自己的结果记录的是超时，transcript 行无处可读用户最终的选择。排队的回复可在准入前取消，此时问题仍可回答。回复正文不含可读批次时，该调用以零答案结算；回复指向的调用已不在可回答集合中时不改变任何内容。
-
-```ts type-equiv
-/** `open` while the tool call may still return the answer; `continued` once the answer can only arrive as a new turn. */
-type UserQuestionState = 'open' | 'continued'
-```
-
-```ts type-equiv
-/** One unanswered timed `ask_user_question` call reconstructed from the Session log. */
-interface PendingUserQuestion {
-  readonly callId: ToolCallId
-  readonly questions: readonly AskUserQuestionItem[]
-  readonly state: UserQuestionState
-}
-```
-
-```ts type-equiv
-/**
- * One timed `ask_user_question` call and the answers it settled with: the
- * batch its own result carried when the user answered inside the window,
- * otherwise the batch its late reply carried, because that call's own result
- * recorded the timeout. A transcript row reads what the user finally answered
- * from here, and only a call listed here was a timed one.
- */
-interface SettledUserQuestion {
-  /** The settled call. */
-  readonly callId: ToolCallId
-  /** The recorded batch, one entry per question; empty when the late reply carried none. */
-  readonly answers: readonly AskUserQuestionAnswerItem[]
-}
-```
-
-```ts type-equiv
-/**
- * Both halves of one Session's timed `ask_user_question` state, as every
- * Client reads them. A call made while the blocking legacy tool was in
- * effect appears in neither half.
- */
-interface UserQuestionProjectionView {
-  /** Calls that can still take an answer, in ask order. */
-  readonly active: readonly PendingUserQuestion[]
-  /** Calls an answer settled, in settlement order. */
-  readonly settled: readonly SettledUserQuestion[]
-}
-```
-
-开放中的问题只能通过 waterfall 回答。问题变为 `continued` 后，`answer` Remote 方法向所属 agent 排入一条用户消息，并在其空闲时唤醒它。消息的 source 为 `user-question-reply`，outcome 为 `answered`，正文是 `answer_to_pending_question` 载荷。开放或未知调用返回 `false`；回复仍在排队时的第二次提交以 `REPLY_QUEUED` 拒绝，Host 重启后也一样；遗漏或重复问题的回答批次以 `BAD_ANSWER` 拒绝。
-
-收起 Client 面板不会发送内容。前台超时只结束工具等待。已继续的问题没有期限；在回复进入会话前，问题仍可回答。
-
-Host 重启后，Session 重开时 Remote 层会恢复根 agent。之后的迟到回复会作为新一轮进入。
-
-## 错误
-
-`UserQuestionError` 继承 `HarnessError`，因此 `ctx.tools.execute()` 会保留 `{ name, code }`，用于面向模型的工具失败，如 `EMPTY_QUESTIONS`、`BAD_INTENT`、`NO_PROVIDER`、`ASK_ABORTED` 或 UI 侧取消。
-
-```ts type-equiv
-/** Stable error taxonomy for user-questions failures. */
-class UserQuestionError extends HarnessError {
-  constructor(message: string, code: string, options?: ErrorOptions) {
-    super(message, code, options)
-    this.name = 'UserQuestionError'
-  }
-}
-```
-
-<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
-
-<a id="cordis-surface"></a>
-
-## Cordis API
-
-Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — the language sides differ only in locale-specific paired document paths. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.zh.md#dispatch-modes), and the framework-inherited `ctx` API lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
-
-<a id="ctxuserquestions--userquestionservice"></a>
-
-### `ctx.userQuestions` — `UserQuestionService`
-
-`ctx.userQuestions`: validation plus the scoped answerer waterfall.
-
-```ts cordis-catalog
-/**
- * Answer a continued question. The reply is steered into the agent as a
- * user message whose source names the call; that message is also the
- * record that closes the question in the projection.
- * @param agent - Live root agent for the owning Session.
- * @param callId - Continued question identity.
- * @param answer - Complete structured answer batch, one item per question of the call.
- * @returns Whether the question is still continued; an accepted reply stays
- *   queued until the agent admits its user message.
- * @throws {UserQuestionError} `BAD_ANSWER` when the batch does not name each
- *   question of the call exactly once, or `REPLY_QUEUED` when a reply is
- *   already waiting for admission.
- */
-@Remote answer(agent: Agent, callId: ToolCallId, answer: AskUserQuestionAnswer): boolean
-
-/**
- * Let one answer UI hold a live timed wait. Closing the stream releases its claim.
- * @param agent - Live root agent owning the question.
- * @param callId - Foreground tool call to attach to.
- * @param signal - Remote stream cancellation, including Client disconnect.
- * @returns One Host-computed remaining duration, or no frames once the wait ended.
- */
-@Remote({ mode: 'stream' }) async *attachWait(agent: Agent, callId: ToolCallId, signal: AbortSignal): AsyncIterable<{ remainingMs: number }>
-
-/**
- * Foreground wait whose first settlement the Client decides: the Client
- * rejects with `ASK_TIMED_OUT` when its countdown ends, and this method maps
- * that code to the pending result.
- * @param request - Questions, live owner agent, and abort signal.
- * @param callId - Tool call identity the Client card is keyed by.
- * @param timeoutMs - Positive foreground wait in milliseconds.
- * @returns The answer when it arrives inside the window, otherwise a pending
- *   result, also when no connected Client claimed the request by the deadline.
- * @throws {UserQuestionError} `BAD_TIMEOUT` for a non-integer, non-positive,
- *   or oversized wait.
- */
-async askTimed( request: AskUserQuestionRequest & { agent: Agent }, callId: ToolCallId, timeoutMs: number, ): Promise<TimedUserQuestionResult>
-
-/**
- * Ask the scoped answerer waterfall and wait for the user's answer.
- *
- * When a caller supplies an agent, human interaction is valid only for the
- * exact live runtime root. Runtime ownership, not durable session lineage,
- * decides this boundary: an owned child has no human answerer and would
- * block forever, while a lineage-bearing session resumed as a new runtime
- * root may ask normally.
- *
- * @param request Questions, owner agent, and abort signal.
- * @returns The answer chosen or typed by the human.
- * @throws {UserQuestionError} code `ASK_ABORTED` when the supplied signal
- *   is already or becomes aborted, `CALLER_NOT_LIVE` when a supplied agent
- *   is not the registry's exact live instance, or `DELEGATED_CALLER` when
- *   that live agent is owned by another agent.
- */
-async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
-```
-
-Types: [Agent](core.zh.md) · [ToolCallId](core.zh.md)
-
-Source: [`packages/interaction/user-questions/src/index.ts`](../../packages/interaction/user-questions/src/index.ts)
-
-<a id="user-questions-events"></a>
-
-### `user-questions/*` events
-
-<a id="user-questionsrequest--waterfall"></a>
-
-#### `user-questions/request` — waterfall
-
-Ask composed answerers for structured user input. Return an answer to claim the request or call `next()` to delegate. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
-
-```ts cordis-catalog
-/**
- * Ask composed answerers for structured user input. Return an answer to
- * claim the request or call `next()` to delegate. Scope-filtered dispatch
- * (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
- * @param request - pending user-question request.
- * @mode waterfall
- */
-'user-questions/request'( this: Scoped<Agent>, request: AskUserQuestionRequestEvent, next: () => Promise<AskUserQuestionAnswer>, ): Promise<AskUserQuestionAnswer>
-```
-
-Types: [Agent](core.zh.md) · [Scoped](scope.zh.md)
-
-Source: [`packages/interaction/user-questions/src/types.ts`](../../packages/interaction/user-questions/src/types.ts)
-<!-- END GENERATED cordis-surface -->

package/references/official-docs/docs/subsystems/voice-input.i18n.yaml

@@ -1,19 +0,0 @@
-# Bilingual-pair consistency record for voice-input.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write docs/subsystems/voice-input.md
-/voice-input:
-  en: b21f58d0dcb90287
-  zh: be60807d02623a87
-/voice-input/provider-selection:
-  en: 3a5ec4718b839349
-  zh: a8448bd6064d4c81
-/voice-input/browser-and-host-ownership:
-  en: 404d67d8276522db
-  zh: f653397888d2e616
-/voice-input/preparation-and-settings:
-  en: 9350b2e58813262e
-  zh: c3b5e5cb100408af
-/voice-input/design-rationale:
-  en: 604b86d95ac007b3
-  zh: 472db5ba5905eddc