@qilin-agent/client-ui-user-questions 0.0.0-stage → 3.1.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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,52 @@
+# Bilingual-pair consistency record for README.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 packages/client/ui-user-questions/README.md
+/:
+  en: 13e42622514cbe43
+  zh: 0220a98a1eac72f4
+/qilin-client-ui-user-questions:
+  en: be4a03eeb9e18e85
+  zh: 34deda5d4cb2034d
+/qilin-client-ui-user-questions/summary:
+  en: 7e81c6a53759ff37
+  zh: b83f666c4ef4cbd3
+/qilin-client-ui-user-questions/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-client-ui-user-questions/use-this-package:
+  en: 4aa048dcb7282f12
+  zh: d2731da0870aa6a0
+/qilin-client-ui-user-questions/use-this-package/answering:
+  en: 8b6f37bfb11a2c3a
+  zh: 59d8951211f9b21b
+/qilin-client-ui-user-questions/use-this-package/the-plan-review-card:
+  en: 956f8d409e63d6ef
+  zh: a50fcd2f30c473c7
+/qilin-client-ui-user-questions/use-this-package/failure-and-recovery:
+  en: da530ef485c07417
+  zh: b07525cfcd5034f0
+/qilin-client-ui-user-questions/understand-the-implementation:
+  en: 77e1b2585acdf67b
+  zh: d433ec185c6b8f57
+/qilin-client-ui-user-questions/understand-the-implementation/intent-surface-election:
+  en: 7f3e0e2460317462
+  zh: cb6b9410410e2f29
+/qilin-client-ui-user-questions/understand-the-implementation/copy-and-locale:
+  en: a1c3107133be67e1
+  zh: 7360dcc78fdc9de1
+/qilin-client-ui-user-questions/further-exploration:
+  en: 386261a510da12be
+  zh: e980853275da8aad
+/qilin-client-ui-user-questions/model-experience:
+  en: 2c410f527afb6e88
+  zh: d5e5a751d044170a
+/qilin-client-ui-user-questions/model-experience/kv-cache-effect:
+  en: fa1c388ea39d02b0
+  zh: 70152186ca395643
+/qilin-client-ui-user-questions/known-limitations-and-deferred-work:
+  en: beb6dc6d1496e799
+  zh: d92150a88a797c21
+/qilin-client-ui-user-questions/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: 3bb0c20c93f16f98

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+---
+description: "Web ask_user_question feature for the qilin web client: the composer-takeover question UI and the plan-review approval card."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/client-ui-user-questions
+
+English | [中文](README.zh.md)
+
+## Summary
+
+When an agent asks a question in the Web client, this package replaces the chat composer with an interactive question surface. Users can move through questions, choose one or multiple options, enter custom answers, skip items, and submit one structured answer batch. Single-choice selections advance immediately, while drafts survive Session navigation for the lifetime of the page. A single question with a supported presentation intent can use a dedicated surface, including the plan-review card with `Request changes` and `Approve` actions.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+When the agent asks a question, the composer becomes the question surface: answer each question, navigate with the pager, or skip it. Single-select choices advance immediately; Enter continues the flow and submits once every question is answered or skipped, while Shift+Enter breaks a line instead (during IME composition Enter only confirms the input candidate without advancing).
+
+### Answering
+
+A multi-select draft keeps its selected labels while the user opens or edits the custom answer, so its submitted item may carry both `selected` and `custom`; a single-select custom answer remains exclusive. Question detail reuses the assistant-output `MarkdownText` primitive, including its GFM rendering and untrusted-content policy. The capped card keeps its title, navigation, and submission actions fixed while long detail and choices share an internal scroll region. "Skip" retains other drafts and emits the existing blank `{ selected: [] }` result for that item, while close rejects the whole wait as `ASK_CANCELLED`.
+
+### The plan-review card
+
+A `plan-review` intent — set by `qilin-plan-mode` on the `exit_plan_mode` review — renders a compact approval card: a `Plan review` strip with a `View full plan` link, the plan title and a two-line plain-text summary, and `Request changes` / `Approve` actions. The complete plan opens in the sidebar through the link or its permanent Chat card. Approve answers with the asker's approval label; `Request changes` rejects the wait as `ASK_CANCELLED`, returning the composer for the user's feedback without submitting an approval. The card has no separate refusal button.
+
+### Failure and recovery
+
+The generic question flow keeps its current page, selected labels, custom text, and explicit skips in a non-persisted Slot store scoped to the owning Session generation and keyed by the pending request's local render identity. Switching from Session A to B retires A when no other reference owns it, so returning to A starts an empty question draft; another reference that keeps A's generation alive also keeps that draft. A different request identity reads an empty draft and replaces the previous value on its first edit; a successful answer or cancellation clears the matching value. The host remains authoritative for whether the request is pending.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The package is one ownership rule: rendering a question is a host UI capability, having the tool is an agent capability, so the `tool-ask-user` row belongs to the presets that want it (and to the TUI composition, which has no presets).
+
+### Intent surface election
+
+The card accepts one question declaring the intent, carrying the plan as `detail`, and offering the named approve label, with at most one alternative and no multi-select. Its secondary action returns to the composer for change requests. Larger choices and multi-select questions remain in the generic flow.
+
+### Copy and locale
+
+Composer chrome copy (pager, buttons, placeholders, validation feedback) is bilingual: the plugin registers zh/en dictionaries under the `question` namespace of `qilin-client-locale` and hands the entry its bound translator plus the locale snapshot source through the inject face, so a locale switch re-renders a mounted composer. Question and option text arrives from the model and renders verbatim; carrier failure messages also display untranslated.
+
+A plan review exposes `conversation.plan-review.actions` with its request key, full text, and optional invocation identity. The plan plugin opens logged plans from history and unlogged reviews as temporary sidebar previews. Opening a document does not answer or dismiss the review.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+These pages cover the composer host, the tool seam, and the plan-mode consumer.
+
+- [ui-conversation](../ui-conversation/README.md) — the chat surface owning the `conversation.composer` chain.
+- [tool-ask-user](../../interaction/tool-ask-user/README.md) — the model-facing tool whose schema and answers this UI renders.
+- [ui-plan](../ui-plan/README.md) — the plan-mode surface that sets the `plan-review` intent.
+- [user-questions](../../interaction/user-questions/README.md) — the Host-side question seam and its answerer waterfall.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+Indirectly, through `qilin-tool-ask-user`, whose model-visible schema and answer rendering this package presents in the Web client.
+
+#### KV Cache effect
+
+No direct invalidation; `qilin-tool-ask-user` owns the model-visible tool call and result.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define draft durability and composer ownership; they are current package constraints.
+
+- **Unsubmitted drafts have page-and-Session lifetime** — Session navigation preserves them while that Session scope remains in the page, but a full page reload, Session pruning, or a newly delivered pending-request identity starts with an empty draft. The store never writes them to the Host, `localStorage`, or disk.
+- **One request owns the composer at a time** — later pending requests remain in the session snapshot and become visible after the earlier request resolves.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,105 @@
+---
+description: "qilin Web 客户端的 ask_user_question 功能：接管编辑器的提问 UI 与 plan-review 审批卡片。"
+kind: "package-reference"
+---
+
+# @qilin-agent/client-ui-user-questions
+
+[English](README.md) | 中文
+
+## 概述
+
+当 agent（智能体）在 Web 客户端中提问时，本包会用交互式提问界面接管聊天编辑器。用户可以在问题之间导航、选择一个或多个选项、输入自定义答案、跳过问题，并提交一批结构化答案。选择单选项后会立即前进，而草稿会在当前页面的生命周期内跨会话导航保留。若唯一的问题声明了受支持的呈现意图，则可使用专用界面，包括带 `Request changes` 和 `Approve` 操作的 plan-review 卡片。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当 agent 提问时，编辑器变成提问界面：回答每个问题、用翻页器导航，或跳过它。选择单选选项后会立即前进；Enter 继续流程，并在所有问题均已回答或跳过后提交，而 Shift+Enter 改为换行（IME 组合输入期间按 Enter 只会确认输入候选，不会前进）。
+
+### 作答
+
+用户打开或编辑自定义答案时，多选题草稿会保留已选中的标签，因此提交项可以同时携带 `selected` 与 `custom`；单选题的自定义答案仍保持互斥。问题详情复用助手输出的 `MarkdownText` 原语，包括其 GFM 渲染与不受信任内容策略。限高卡片保持标题、导航与提交动作固定，超长的详情与选项共享内部滚动区。「跳过」会保留其他草稿，并为该项发出既有的空 `{ selected: [] }` 结果；关闭则以 `ASK_CANCELLED` 拒绝整个等待。
+
+### plan-review 卡片
+
+`plan-review` 意图——由 `qilin-plan-mode` 在 `exit_plan_mode` 审阅上设置——渲染紧凑审批卡片：顶部为带“查看全文”链接的“计划待审”条带，正文显示计划标题和两行纯文本摘要，底部提供“要求修改”和“同意执行”。通过链接或聊天历史中的常驻卡片可在侧边栏阅读完整计划。“同意执行”用提问方的批准标签回答；“要求修改”以 `ASK_CANCELLED` 拒绝等待，让编辑器归位供用户输入反馈，不会提交批准。卡片不再单列拒绝按钮。
+
+### 失败与恢复
+
+通用提问流程把当前题号、已选标签、自定义文本和显式跳过状态保存在非持久化 slot 存储中；该存储归属对应 Session generation，并以待处理请求的本地渲染标识为键。从 Session A 切换到 B 时，如果没有其他引用持有 A，A 就会结束，因此返回 A 时会得到空的问题草稿；如果另一个引用继续持有 A 的 generation，该草稿也会保留。不同的请求标识读取空草稿，并在首次编辑时替换旧值；成功回答或取消会清除相符的值。请求是否仍在等待由主机保持权威。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本包是一条归属规则：渲染提问是宿主的 UI 能力，拥有该工具则是 agent 的能力，因此 `tool-ask-user` 行属于需要它的各个 preset（以及没有 preset 的 TUI 组装）。
+
+### 意图界面选择
+
+卡片接管声明了意图、以 `detail` 携带计划、提供了被指名的批准标签的单个问题，要求除批准外最多一个选项，且非多选。次要操作返回编辑器供用户提出修改要求。更多选项或多选问题仍由通用流程处理。
+
+### 文案与 locale
+
+编辑器外框文案（翻页器、按钮、占位符、校验提示）是双语的：插件在 `qilin-client-locale` 的 `question` 命名空间下注册 zh/en 词典，并通过 inject face 把绑定的翻译函数和 locale 快照源交给该条目，因此切换语言会重新渲染已挂载的编辑器。问题与选项文本来自模型并原样渲染；载体失败消息也不经翻译直接显示。
+
+计划审批通过 `conversation.plan-review.actions` 插槽提供请求键、完整正文和可选的调用标识。计划插件从历史中打开已记录计划，并把没有调用标识的审批作为临时侧边栏预览打开。打开文档不会回答或关闭审批。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+以下页面覆盖编辑器宿主、工具 seam 与 plan-mode 消费方。
+
+- [ui-conversation](../ui-conversation/README.zh.md)——拥有 `conversation.composer` 链的聊天界面。
+- [tool-ask-user](../../interaction/tool-ask-user/README.zh.md)——面向模型的工具；本 UI 会渲染其 schema 与答案。
+- [ui-plan](../ui-plan/README.zh.md)——设置 `plan-review` 意图的 plan-mode 界面。
+- [user-questions](../../interaction/user-questions/README.zh.md)——Host 侧提问 seam 及其应答方 waterfall（瀑布式事件）。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+间接影响模型体验：本包在 Web 客户端呈现 `qilin-tool-ask-user` 所拥有的模型可见 schema 与答案渲染。
+
+#### KV Cache 影响
+
+不会直接失效；模型可见的工具调用与结果由 `qilin-tool-ask-user` 拥有。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制定义草稿持久性与编辑器归属；它们是当前包约束。
+
+- **未提交草稿的生命周期限于当前页面与会话**：只要该会话作用域仍留在页面内，会话导航就会保留草稿；完整刷新页面、会话被裁剪，或待处理请求以新的本地标识重新交付时，则从空草稿开始。存储从不把草稿写入主机、`localStorage` 或磁盘。
+- **每次只有一个请求拥有编辑器**：后续待处理请求仍留在会话快照中，并在较早请求落定后显示。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+无。
+
+</details>