@zhushanwen/pi-ask-user 7.1.3 → 7.2.1

package/ARCHITECTURE.md

@@ -1,8 +1,10 @@
 # ask-user — Architecture
 
+> 功能分级：P0（依据见 [docs/FEATURE-PRIORITIES.md](../../../docs/FEATURE-PRIORITIES.md) §6 边界判例 #3——agent↔用户交互闭环的唯一通道，2026-09-12 用户裁决升 P0）。
+
 Internals reference for maintainers. For the usage contract (what the tool does, when an agent should call it), see [README.md](./README.md). This document covers how the code is structured, the state machine, the defensive execute flow, and where each design invariant is enforced — so a change does not silently break an invariant.
 
-Source: 10 files in `src/`, ~1970 lines total.
+Source: 10 files in `src/`, ~2085 lines total.
 
 ## File dependency graph
 
@@ -55,13 +57,23 @@ Source: 10 files in `src/`, ~1970 lines total.
 
 `AnswerValue` (`types.ts`) is the single structured answer model — `{ selected: string[]; other: string | null }`. The old internal/proto double model is gone: proto `AskUserOption.value` equaled `label` (both were the same string), so the proto layer consumes the same single model (`Result.answers: Record<string, AnswerValue>`, key = question text).
 
-Serialization happens **once, at the protocol boundary**: `encodeAnswer(value, { key, multiSelect })` in `answer-codec.ts` converts an `AnswerValue` into proto answers entries, byte-aligned with `@xyz-agent/extension-protocol` helpers' decode contract (`getAskUserAnswer` / `getAskUserOther`):
+Serialization happens **once, at the protocol boundary**: `encodeAnswer(value, { key, multiSelect })` in `answer-codec.ts` converts an `AnswerValue` into proto answers entries, byte-aligned with `@taiji/extension-protocol` helpers' decode contract (`getAskUserAnswer` / `getAskUserOther`):
 
 - 单选：`answers[key] = selected[0]`
 - 多选：`answers[key] = JSON.stringify(selected)`
 - Other：`answers[`${key}__other`] = other`（仅在 other 非空时写入）
 
-Encoding is **one-way** — the old `parseAnswerParts` text reverse-parsing was deleted with the double model; there is no decode counterpart inside the extension. `channel-handler.ts` reads `AnswerValue` directly and calls `encodeAnswer` when forwarding to subagents.
+Encoding is **one-way** — the old `parseAnswerParts` text reverse-parsing was deleted with the double model; there is no decode counterpart inside the extension. `channel-handler.ts` reads `AnswerValue` directly and calls `encodeAnswer` when forwarding to subagents. (`encodeAnswer` is the only encode implementation **inside this extension**; the renderer frontend components cannot import extension packages and implement the encoding independently, aligned to the same decode contract.)
+
+## Channel registry handshake (subagent passthrough)
+
+`channel-handler.ts` + `channel-registry-register.ts` implement the subagent passthrough: the host-process ask-user extension registers an `"ask_user"` channel handler through a versioned `globalThis[Symbol.for]` slot handshake (`CHANNEL_HANDSHAKE_KEY`). The skeleton (versioned slot + pending/flush; this side never creates the registry instance) is deliberate and must not be simplified away — the M4 incident (a simplified self-made registry hijacking the canonical slot) is the anchor, see the header comment of `channel-registry-register.ts`. A second consumer of the same handshake *pattern* exists: `extensions/universal/permission/src/footer-provider.ts` (own slot key `FOOTER_HANDSHAKE_KEY`, same versioned-slot shape).
+
+Registry outreach facts (ext-simplify-11, D4):
+
+- **Single registrant on this slot.** The `CHANNEL_HANDSHAKE_KEY` slot currently has exactly one registrant: ask-user (`"ask_user"`). The permission footer-provider handshake above uses its own separate slot — same pattern, different slot, not a registrant here.
+- **`"gui_widget"` route reserved but vacant.** The engine-sdk ui-channels parsing (`parseChannel`, re-exported via `packages/subagent-core/src/execution/ui-channels.ts`) reserves a `"gui_widget"` channel name, but no package registers a handler for it; the core-side `ui-request-handler-factory` special-cases the unregistered `"gui_widget"` request to `{ack:true}` without forwarding. A future registrant needs no ask-user change — registration is keyed by channel name and orthogonal per extension.
+- **Known gap, accepted (version-mismatch slot overwrite).** On `slot.version !== 1`, `readSlot` discards the slot and `registerAskUserChannelHandler` rebuilds it via `ensureSlot` — if a hypothetical v2 registry ever held the slot, this would drop its reference. Ruled not-worth-fixing (ext-simplify-11 finding 6): both sides pin `HANDSHAKE_VERSION = 1`, so the mismatch path is unreachable today; fixing it would be defensive code for an imagined v2. Re-review trigger: any PR that bumps either side's handshake version.
 
 ## `execute` defensive flow (6 steps)
 
@@ -164,7 +176,7 @@ Constants: `SPLIT_PANE_MIN_WIDTH = 84`, `SPLIT_PANE_LEFT_MIN = 32`, `SPLIT_PANE_
 
 ## Spec cross-reference
 
-The original spec files (`.xyz-harness/2026-06-15-ask-user/`) are no longer in the repo — this table is self-contained (FR = functional requirement from the original spec). Implementation anchors:
+The original spec files (`.taiji-harness/2026-06-15-ask-user/`) are no longer in the repo — this table is self-contained (FR = functional requirement from the original spec). Implementation anchors:
 
 | Spec | Implemented in |
 |------|----------------|

package/README.md

@@ -10,7 +10,7 @@ The tool's primary caller is the LLM. This README covers both **how an agent sho
 pi install npm:@zhushanwen/pi-ask-user
 ```
 
-> **Dev-only symlink**: during local development you may symlink this package into `~/.pi/agent/extensions/` for debugging, but **never use the symlinked copy for daily work**. Local directory discovery has an `index.ts` fallback that masks a missing `pi` manifest field — npm-installed copies then silently fail to load. See the repo root CLAUDE.md "扩展安装红线".
+> **Dev-only symlink**: during local development you may symlink this package into `~/.pi/agent/extensions/` for debugging, but **never use the symlinked copy for daily work**. Local directory discovery has an `index.ts` fallback that masks a missing `pi` manifest field — npm-installed copies then silently fail to load. See `docs/extensions/extension-conventions.md` "扩展安装红线".
 
 ## When to use
 
@@ -138,7 +138,7 @@ All three are consistent and point the same direction. If you tune behavior, edi
 
 ## Spec reference
 
-The original design spec (requirements, functional requirements FR-x, acceptance criteria AC-x, E2E test cases) predates this repository — the original spec files are no longer in the repo. The FR cross-reference table in ARCHITECTURE.md is self-contained: each entry names the behavior and where it is implemented in this codebase.
+Design spec files are not kept in this repo. The FR cross-reference table in ARCHITECTURE.md is self-contained: each entry names the behavior and where it is implemented in this codebase.
 
 ## License
 

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zhushanwen/pi-ask-user",
-  "version": "7.1.3",
+  "version": "7.2.1",
   "description": "Inline adaptive ask_user tool for Pi — single/multi-question structured input with split-pane preview and an inline free-text editor.",
   "type": "module",
   "main": "index.ts",
-  "xyz-agent": {
+  "taiji": {
     "role": "universal"
   },
   "pi": {
@@ -29,7 +29,8 @@
     "ARCHITECTURE.md"
   ],
   "dependencies": {
-    "@xyz-agent/extension-protocol": "0.9.0",
+    "@taiji/extension-protocol": "0.11.0",
+    "@zhushanwen/pi-ext-guards": "0.4.0",
     "@zhushanwen/pi-extension-logger": "0.6.0"
   },
   "devDependencies": {

package/src/__tests__/answer-codec.test.ts

@@ -1,9 +1,9 @@
 // src/__tests__/answer-codec.test.ts
 // encodeAnswer 单向序列化 round-trip 测试（TC-09）。
-// 反向验证用 @xyz-agent/extension-protocol 的解码 helper（getAskUserAnswer / getAskUserOther）
+// 反向验证用 @taiji/extension-protocol 的解码 helper（getAskUserAnswer / getAskUserOther）
 // ——该 helper 是 proto answers 格式的唯一解码 SSOT，encode 输出必须与其字节级对齐。
 // m1 增量（TC-01）：property-based describe 作为 5 个确定性用例的随机化超集补充。
-import { getAskUserAnswer, getAskUserOther } from "@xyz-agent/extension-protocol";
+import { getAskUserAnswer, getAskUserOther } from "@taiji/extension-protocol";
 import fc from "fast-check";
 import { describe, expect, it } from "vitest";
 

package/src/__tests__/channel-handler.test.ts

@@ -10,7 +10,7 @@
 //     （single/multi/Other 三种答案形态，经 encodeAnswer 序列化）。
 //   - 取消（askUserInteract/custom 返回 null 或 cancelled）→ {cancelled: true}
 //   - 输入校验（channelPayload 缺失/无 questions）→ {cancelled: true}
-import type { AskUserQuestion } from "@xyz-agent/extension-protocol";
+import type { AskUserQuestion } from "@taiji/extension-protocol";
 import { describe, expect, it } from "vitest";
 
 import { createAskUserChannelHandler } from "../channel-handler";

package/src/__tests__/index.test.ts

@@ -522,7 +522,7 @@ describe("execute — inline render (FR-3)", () => {
 	});
 });
 
-// ── RPC 模式（xyz-agent GUI 富交互协议）──────────────────
+// ── RPC 模式（taiji GUI 富交互协议）──────────────────
 // hasUI=false + ui.select 存在 → 走 askUserInteract（select 通道 + ASK_USER_MARKER）。
 // select 的返回值是前端 JSON.stringify 的 AskUserAnswers，index.ts 做格式转换。
 describe("execute — RPC mode (askUserInteract via select channel)", () => {

package/src/__tests__/validate.test.ts

@@ -166,6 +166,33 @@ describe("validateInput", () => {
 		expect(result).toContain("Correct:");
 		expect(result).toContain('"header"');
 	});
+
+	// V-20/M23: label 恰为保留字 "Other" → 拦截。Other 自由输入行由 extension 自动追加，
+	// LLM 自带会渲染出同名双行；文案含 reserved 与改名指引（rename + e.g. 示例）。
+	it("rejects option label 'Other' as reserved with rename guidance", () => {
+		const result = validateInput([
+			q({ options: [{ label: "Postgres" }, { label: "Other" }] }),
+		]);
+		expect(result).not.toBeNull();
+		expect(result).toContain("reserved");
+		expect(result).toContain("rename");
+	});
+
+	// V-21/D2: 空白变体 " Other " 与合成 Other 行视觉不可分辨（仅差不可见空白），同样拦截
+	it("rejects whitespace variants of the reserved label (' Other ')", () => {
+		const result = validateInput([
+			q({ options: [{ label: "Postgres" }, { label: " Other " }] }),
+		]);
+		expect(result).toContain("reserved");
+	});
+
+	// V-22/D2: 含 Other 子串的合法标签不被拦截（精确匹配不误杀）——catch-all 语义可经命名传达
+	it("allows labels containing 'Other' as a substring (e.g. 'Other database')", () => {
+		const result = validateInput([
+			q({ options: [{ label: "Postgres" }, { label: "Other database" }] }),
+		]);
+		expect(result).toBeNull();
+	});
 });
 
 // ── options 字符串「下沉」机制集成证明 ──────────────────

package/src/answer-codec.ts

@@ -1,6 +1,6 @@
 // src/answer-codec.ts
 // AnswerValue → proto answers 条目的单向序列化（协议边界 SSOT）。
-// 与 @xyz-agent/extension-protocol helpers.ts 的解码契约字节级对齐：
+// 与 @taiji/extension-protocol helpers.ts 的解码契约字节级对齐：
 //   - 单选：answers[key] = selected[0]
 //   - 多选：answers[key] = JSON.stringify(selected)
 //   - Other：answers[`${key}__other`] = other

package/src/channel-handler.ts

@@ -2,7 +2,7 @@
 //
 // ask_user channel handler：把 subagent 子进程的 ask_user 请求透传到主进程 UI 渲染。
 //
-// 设计（关键决策）：askUserInteract（@xyz-agent/extension-protocol）只在 RPC 模式可用
+// 设计（关键决策）：askUserInteract（@taiji/extension-protocol）只在 RPC 模式可用
 // （内部 isGuiCapable 检查 mode==='rpc'，TUI 下抛错）。所以 handler 按 ctx.mode 分流：
 //   - RPC：转发器——调 askUserInteract(guiCtx, protoQuestions)，复用 select 通道 +
 //     ASK_USER_MARKER 契约，主进程 ctx.ui.select 经 GUI sidecar 渲染（不进 parseSpawnLine，
@@ -13,7 +13,7 @@
 //     （key=header/question，单选=string，多选=JSON 数组，Other→__other），让子进程 decode 一致。
 //
 // handler 收到的 req.channelPayload = {questions: AskUserQuestion[], allowCancel}（proto 格式，
-// 由子进程 askUserInteract 编码、packages/subagent-core 的 parseChannel（execution/ui-channels.ts）
+// 由子进程 askUserInteract 编码、packages/subagent-core 的 parseChannel（execution/ui/ui-channels.ts）
 // 解析 options[0] JSON 得到）。
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -21,7 +21,7 @@ import {
 	type AskUserAnswers,
 	askUserInteract,
 	type AskUserQuestion,
-} from "@xyz-agent/extension-protocol";
+} from "@taiji/extension-protocol";
 
 import { AskUserComponent } from "./component";
 import { encodeAnswer } from "./answer-codec";
@@ -29,13 +29,13 @@ import { type AnswerValue, type Option, type Question, type Result, type ThemeLi
 
 /**
  * channel handler 签名——与 packages/subagent-core 的 UiChannelRegistry.ChannelHandler 一致
- *（execution/ui-channels.ts 定义，(req: unknown) => Promise<unknown>）。本文件不静态 import
+ *（execution/ui/ui-channels.ts 定义，(req: unknown) => Promise<unknown>）。本文件不静态 import
  * packages/subagent-core（host 侧包，非本包依赖——两侧扩展经 globalThis slot 握手协作，
  * 见 index.ts 工厂注释）；handler 签名用本地等价类型，运行时结构兼容。
  */
 export type ChannelHandler = (req: unknown) => Promise<unknown>;
 
-/** handler 返回给 packages/subagent-core 的 UiResponse 形状（execution/dialog-queue.ts 定义）。
+/** handler 返回给 packages/subagent-core 的 UiResponse 形状（execution/ui/dialog-queue.ts 定义）。
  *  - {value}: select 的回传值（子进程 JSON.parse(value) 得 answers）
  *  - {cancelled}: 用户取消 / 子进程 close / handler 抛错 */
 type ChannelResponse = { value: string } | { cancelled: true };
@@ -71,13 +71,14 @@ function protoToInternalQuestions(protoQuestions: AskUserQuestion[]): Question[]
  * 内部 Result.answers：key = question 全文，value = 结构化 AnswerValue
  * （selected = option label 数组，other = Other 自由文本）。
  *
- * proto AskUserAnswers 契约（@xyz-agent/extension-protocol）：
+ * proto AskUserAnswers 契约（@taiji/extension-protocol）：
  *   - key = question.header ?? question 全文
  *   - 单选：value = 选中项 label string
  *   - 多选：value = JSON.stringify(选中项 label 数组)
  *   - Other 自由文本：单独 key `${header}__other`
  *
- * 序列化走 encodeAnswer（answer-codec.ts 是唯一 encode 实现，与协议包解码 helper 对齐）。
+ * 序列化走 encodeAnswer（answer-codec.ts 是本扩展内的唯一 encode 实现，与协议包解码
+ * helper 对齐；renderer 前端组件无法 import extension 包，独立实现对齐同一解码契约）。
  */
 function encodeTuiResultToProto(
 	protoQuestions: AskUserQuestion[],

package/src/channel-registry-register.ts

@@ -4,7 +4,7 @@
 //
 // 设计动机（PR #85 #M4 修复）：原实现 ask-user 先 session_start 时会自建简化 Map-based
 // registry 占据 canonical 槽位，劫持后续 getOrCreateChannelRegistry 拿到的实例
-// （packages/subagent-core 的 createUiChannelRegistry（execution/ui-channels.ts）才是
+// （packages/subagent-core 的 createUiChannelRegistry（execution/ui/ui-channels.ts）才是
 // canonical——它带排队、dialog 队列等完整能力）。修复后的握手协议改为「带 version 的 slot」：
 //   - 承载 subagent-core 的 subagent-workflow 扩展 session_start 时往 slot 写
 //     {version, registry, pending:[]}（registry 由 subagent-core 创建）
@@ -23,7 +23,7 @@ const logger = getLogger("ask-user");
 /**
  * 进程级 channel registry 握手的 globalThis key（Symbol.for 跨模块共享）。
  *
- * ⚠️ 必须与 packages/subagent-core/src/execution/channel-registry-access.ts 的字面量
+ * ⚠️ 必须与 packages/subagent-core/src/execution/assembly/channel-registry-access.ts 的字面量
  * 完全一致——两边用同一字符串确保拿到同一 slot 实例。改名必须两侧同步。
  */
 export const CHANNEL_HANDSHAKE_KEY = Symbol.for(
@@ -38,7 +38,7 @@ const ASK_USER_CHANNEL = "ask_user";
 
 /**
  * channel registry 的本地等价接口（与 packages/subagent-core 的 UiChannelRegistry 形状一致，
- * execution/ui-channels.ts 定义）。本模块不静态 import packages/subagent-core（host 侧包，
+ * execution/ui/ui-channels.ts 定义）。本模块不静态 import packages/subagent-core（host 侧包，
  * 非本包依赖——两侧经 globalThis slot 握手协作）；运行时结构兼容即可。
  */
 interface ChannelRegistry {

package/src/index.ts

@@ -8,7 +8,8 @@ import {
 	type AskUserQuestion,
 	getAskUserAnswer,
 	getAskUserOther,
-} from "@xyz-agent/extension-protocol";
+} from "@taiji/extension-protocol";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 import { createAskUserChannelHandler } from "./channel-handler";
 import { registerAskUserChannelHandler } from "./channel-registry-register";
@@ -175,7 +176,7 @@ function protoAnswersToResult(
 }
 
 /**
- * RPC 模式（xyz-agent GUI）交互入口。
+ * RPC 模式（taiji GUI）交互入口。
  *
  * 走 askUserInteract（select 通道 + ASK_USER_MARKER），前端 AskUserOverlay 渲染富交互 UI。
  * 返回 Result（正常/取消），或抛错（select 异常 / 非 RPC 模式调用了此函数）。
@@ -211,7 +212,7 @@ export default function (pi: ExtensionAPI): void {
 	// 注册 ask_user channel handler：把 subagent 子进程的 ask_user 请求透传到主进程 UI。
 	//
 	// 跨扩展握手协议（PR #85 #M4）：通过 globalThis Symbol.for 约定 slot 形状
-	//（CHANNEL_HANDSHAKE_KEY，与 packages/subagent-core/src/execution/channel-registry-access.ts
+	//（CHANNEL_HANDSHAKE_KEY，与 packages/subagent-core/src/execution/assembly/channel-registry-access.ts
 	// 用同一字符串 key），不依赖 dynamic import npm 包名（两个扩展都通过
 	// ~/.pi/agent/extensions/ symlink 加载，互相之间无法用 npm 包名 import）。
 	//
@@ -220,7 +221,7 @@ export default function (pi: ExtensionAPI): void {
 	//   2. slot.registry 就绪（承载 packages/subagent-core 的 subagent-workflow 扩展先到）→ 直接调 registry.register
 	//   3. slot.registry 未就绪 → handler 入 pending，等 subagent-core flush
 	// ask-user 永不创建 registry 实例——canonical registry 仅 packages/subagent-core 创建
-	//（execution/ui-channels.ts 的 createUiChannelRegistry）。
+	//（execution/ui/ui-channels.ts 的 createUiChannelRegistry）。
 	pi.on("session_start", (_event, ctx) => {
 		registerAskUserChannelHandler(createAskUserChannelHandler(ctx));
 	});
@@ -294,7 +295,7 @@ Don't:
 				);
 			}
 
-			// 4. 交互执行：TUI 走 ctx.ui.custom，RPC（xyz-agent GUI）走 askUserInteract。
+			// 4. 交互执行：TUI 走 ctx.ui.custom，RPC（taiji GUI）走 askUserInteract。
 			// 注意：hasUI 在 TUI 和 RPC 模式都为 true（dialog-capable），不能用于区分——
 			// 用 ctx.mode === 'rpc' 判定 GUI 渲染通道。
 			const useRpc = ctx.mode === "rpc";
@@ -307,7 +308,7 @@ Don't:
 				// RPC 通道不可用（真 headless / select 缺失）→ 禁用工具（spec FR-8）。
 				// TUI 分支不禁用——custom 抛错通常是组件临时故障，允许 LLM 重试。
 				// 禁用收尾先行，再 throw（W4）：pi catch 后文案原样成为 toolResult content。
-				const message = err instanceof Error ? err.message : String(err);
+				const message = toErrorMessage(err);
 				if (useRpc) disableAskUser(pi);
 				throw new Error(
 					useRpc

package/src/validate.ts

@@ -1,5 +1,5 @@
 // src/validate.ts
-import { HEADER_MAX_CHARS, type InputQuestion, QUESTION_MAX_CHARS } from "./types";
+import { HEADER_MAX_CHARS, type InputQuestion, OTHER_LABEL, QUESTION_MAX_CHARS } from "./types";
 
 /** 控制字符（含 \n \r \t 等）：question 文本禁止包含，避免 answers key 含不可见字符（spec FR-2） */
 const CONTROL_CHAR_RE = /[\x00-\x1f\x7f]/;
@@ -18,6 +18,8 @@ const ERROR_PREVIEW_CHARS = 20;
  * - options 元素必须是 {label, description} 对象，不能是 string（弱模型高频误用）
  * - question 文本长度上限与无控制字符（保证 answers key 有界、可预测）
  * - question 文本在数组内唯一
+ * - option label 不得为保留字 Other（trim 后精确匹配）——Other 自由输入行由 extension
+ *   自动追加，LLM 自带会在渲染层产生同名双行（M23）
  * - 同问题内 option label 唯一
  * - 多问题（questions.length > 1）时每个 question 必须有非空 header
  *
@@ -77,6 +79,12 @@ function checkOptionLabels(qt: string, options: InputQuestion["options"]): strin
 		if (opt.label.trim() === "") {
 			return `Option label must not be empty in question "${qt}". Give every option a distinct, descriptive label.`;
 		}
+		// 保留字 Other（trim 口径：带空白变体与合成 Other 行视觉不可分辨，同样要拦）——
+		// 两条渲染路径都会无条件追加合成 Other 自由输入行，LLM 自带的 "Other" 选项会与它
+		// 同名并存：一行是普通选项、一行是自由输入，UI 自相矛盾且答案通道歧义（M23）。
+		if (opt.label.trim() === OTHER_LABEL) {
+			return `Option label "${OTHER_LABEL}" is reserved in question "${qt}" — the Other free-text option is added automatically. Remove it; to offer a catch-all choice, rely on the built-in Other, or rename the option (e.g. "Other database").`;
+		}
 		if (seenLabels.has(opt.label)) {
 			return `Duplicate option label "${opt.label}" in question "${qt}". Options must be mutually exclusive — reword one so each label maps to a distinct choice.`;
 		}