@yandy0725/pi-ask-user 0.2.1 → 0.4.0

package/README.md

@@ -11,7 +11,7 @@ A Pi package that adds an interactive `ask_user` tool for collecting user decisi
 - User-toggleable extra context on structured selections
 - Context display support
 - Configurable display mode: `overlay` (modal, default) or `inline` (rendered directly in the flow)
-- Runtime overlay toggle: press the configured overlay-toggle key (`alt+o` by default, configurable per call or via env var) while the prompt is open to temporarily hide/show the popup so you can read prior agent output, then press it again to bring it back
+- Runtime overlay toggle: press the configured overlay-toggle key (`alt+o` by default, configurable via env var or `ask-user.json`) while the prompt is open to temporarily hide/show the popup so you can read prior agent output, then press it again to bring it back
 - Pi-TUI-aligned keybinding and editor behavior
 - Custom TUI rendering for tool calls and results
 - System prompt integration via `promptSnippet` and `promptGuidelines`
@@ -58,12 +58,11 @@ The registered tool name is:
 | `options` | `(string \| {title, description?})[]?` | `[]` | Multiple-choice options |
 | `allowMultiple` | `boolean?` | `false` | Enable multi-select mode |
 | `allowFreeform` | `boolean?` | `true` | Add a "Type something" freeform option |
-| `allowComment` | `boolean?` | `false` | Expose a user-toggleable extra-context option in the custom UI (`ctrl+g` or the toggle row) and collect an optional comment in fallback dialogs |
-| `displayMode` | `"overlay" \| "inline"?` | env var or `"overlay"` | Controls custom UI rendering: `overlay` shows the centered modal (current behavior), `inline` renders without overlay framing |
-| `overlayToggleKey` | `string?` | env var or `"alt+o"` | Shortcut for hiding/showing the overlay popup (overlay mode only). Pi-TUI key spec, e.g. `"alt+o"`, `"ctrl+shift+h"`. Pass `"off"` to disable. |
-| `commentToggleKey` | `string?` | env var or `"ctrl+g"` | Shortcut for toggling the optional comment/extra-context row when `allowComment: true`. Pass `"off"` to disable. |
+| `allowComment` | `boolean?` | `true` | Expose a user-toggleable extra-context option in the custom UI (`ctrl+g` or the toggle row) and collect an optional comment in fallback dialogs |
 | `timeout` | `number?` | — | Auto-dismiss after N ms and return `null` if the prompt times out |
 
+Appearance options (`displayMode`, `overlayToggleKey`, `commentToggleKey`) are **not** model-visible parameters. They are user preferences resolved from env vars and `ask-user.json` — see [Display mode](#display-mode) and [Shortcuts](#shortcuts). They remain accepted by the internal `AskParams` type for SDK/direct callers, but an LLM tool call cannot set them.
+
 ## Example usage shape
 
 ```json
@@ -76,8 +75,7 @@ The registered tool name is:
   ],
   "allowMultiple": false,
   "allowFreeform": true,
-  "allowComment": true,
-  "displayMode": "inline"
+  "allowComment": true
 }
 ```
 
@@ -95,11 +93,12 @@ export PI_ASK_USER_COMMENT_TOGGLE_KEY=alt+c
 
 Effective order:
 
-1. Per-call `displayMode` parameter (if provided)
-2. `PI_ASK_USER_DISPLAY_MODE` (if set to `"overlay"` or `"inline"`)
-3. Project config file `.pi/ask-user.json` `displayMode` field (if exists)
-4. User config file `~/.pi/agent/ask-user.json` `displayMode` field (if exists)
-5. Fallback default: `"overlay"`
+1. `PI_ASK_USER_DISPLAY_MODE` (if set to `"overlay"` or `"inline"`)
+2. Project config file `.pi/ask-user.json` `displayMode` field (if exists)
+3. User config file `~/.pi/agent/ask-user.json` `displayMode` field (if exists)
+4. Fallback default: `"overlay"`
+
+(A per-call `displayMode` still wins over all of the above for SDK/direct callers, but the field is no longer part of the model-visible tool schema.)
 
 Unrecognised values are silently ignored and fall back to `"overlay"`.
 
@@ -111,7 +110,7 @@ In addition to environment variables, you can use JSON config files:
 - User-level (global): `~/.pi/agent/ask-user.json`
 - Project-level: `.pi/ask-user.json`
 
-Fields in the project-level file override same-named fields in the user-level file. Priority: call param > env var > project config > user config > default.
+Fields in the project-level file override same-named fields in the user-level file. Priority: env var > project config > user config > default.
 
 **Example `~/.pi/agent/ask-user.json`:**
 
@@ -129,11 +128,12 @@ All fields are optional. Missing files or malformed JSON are silently ignored, e
 
 Effective order for both `overlayToggleKey` and `commentToggleKey`:
 
-1. Per-call parameter (if provided)
-2. Matching env var (`PI_ASK_USER_OVERLAY_TOGGLE_KEY` / `PI_ASK_USER_COMMENT_TOGGLE_KEY`)
-3. Project config file `.pi/ask-user.json` (if exists)
-4. User config file `~/.pi/agent/ask-user.json` (if exists)
-5. Built-in defaults: `alt+o` and `ctrl+g`
+1. Matching env var (`PI_ASK_USER_OVERLAY_TOGGLE_KEY` / `PI_ASK_USER_COMMENT_TOGGLE_KEY`)
+2. Project config file `.pi/ask-user.json` (if exists)
+3. User config file `~/.pi/agent/ask-user.json` (if exists)
+4. Built-in defaults: `alt+o` and `ctrl+g`
+
+(A per-call parameter still wins for SDK/direct callers, but these fields are no longer part of the model-visible tool schema.)
 
 Pass `"off"`, `"none"`, or `"disabled"` (at any level) to disable the shortcut entirely. Invalid specs are silently dropped and the next source is used. Specs follow the Pi-TUI [`KeyId`](https://github.com/earendil-works/pi-mono/blob/main/packages/tui/src/keys.ts) format: `[mod+]...key` where modifiers are `ctrl`, `shift`, `alt`, `super`, in any order, joined by `+` (e.g. `ctrl+g`, `alt+shift+x`, `escape`, `tab`).
 
@@ -149,7 +149,7 @@ While an `ask_user` prompt is open:
 | `esc` | Clear the search filter, exit freeform/comment mode, or cancel the prompt. |
 | `↑` / `↓`, `ctrl+k` / `ctrl+j` | Navigate options. `ctrl+k` / `ctrl+j` (vim-style) work while typing in searchable prompts without disturbing the filter. |
 
-If you prefer never to see the overlay, set `displayMode: "inline"` per call or `PI_ASK_USER_DISPLAY_MODE=inline` globally.
+If you prefer never to see the overlay, set `PI_ASK_USER_DISPLAY_MODE=inline` globally or `"displayMode": "inline"` in `ask-user.json`.
 
 ## Result details
 

package/README.zh.md

@@ -11,7 +11,7 @@
 - 选择后可切换添加额外上下文（可选注释）
 - 上下文展示支持
 - 可配置的显示模式：`overlay`（模态，默认）或 `inline`（直接内联渲染）
-- 运行时浮层切换：当提示窗口打开时，按下配置的叠加层切换键（默认 `alt+o`，可每次调用配置或通过环境变量设置）临时隐藏/显示弹窗，以便阅读之前的 Agent 输出
+- 运行时浮层切换：当提示窗口打开时，按下配置的叠加层切换键（默认 `alt+o`，可通过环境变量或 `ask-user.json` 配置）临时隐藏/显示弹窗，以便阅读之前的 Agent 输出
 - Pi-TUI 对齐的按键绑定和编辑器行为
 - 工具调用和结果的自定义 TUI 渲染
 - 通过 `promptSnippet` 和 `promptGuidelines` 集成系统提示词
@@ -58,12 +58,11 @@ pi install npm:@yandy0725/pi-ask-user
 | `options` | `(string \| {title, description?})[]?` | `[]` | 多选选项 |
 | `allowMultiple` | `boolean?` | `false` | 启用多选模式 |
 | `allowFreeform` | `boolean?` | `true` | 添加"自定义输入"自由文本选项 |
-| `allowComment` | `boolean?` | `false` | 在自定义 UI 中提供可切换的额外上下文选项（`ctrl+g` 或切换行），并在回退对话框中收集可选注释 |
-| `displayMode` | `"overlay" \| "inline"?` | 环境变量或 `"overlay"` | 控制自定义 UI 渲染：`overlay` 显示居中模态框（当前行为），`inline` 不显示叠加框架渲染 |
-| `overlayToggleKey` | `string?` | 环境变量或 `"alt+o"` | 隐藏/显示叠加弹窗的快捷键（仅 overlay 模式）。Pi-TUI 键位格式，例如 `"alt+o"`、`"ctrl+shift+h"`。传入 `"off"` 禁用。 |
-| `commentToggleKey` | `string?` | 环境变量或 `"ctrl+g"` | 当 `allowComment: true` 时切换可选注释/额外上下文行的快捷键。传入 `"off"` 禁用。 |
+| `allowComment` | `boolean?` | `true` | 在自定义 UI 中提供可切换的额外上下文选项（`ctrl+g` 或切换行），并在回退对话框中收集可选注释 |
 | `timeout` | `number?` | — | N 毫秒后自动关闭，超时返回 `null` |
 
+外观类选项（`displayMode`、`overlayToggleKey`、`commentToggleKey`）**不是**模型可见参数：它们是用户偏好，由环境变量与 `ask-user.json` 解析（见[显示模式](#显示模式)与[快捷键](#快捷键)）。内部 `AskParams` 类型仍接受它们（供 SDK/直接调用），但 LLM 的工具调用无法设置。
+
 ## 通过环境变量设置个人偏好
 
 在你的 shell 配置（`~/.zshrc`、`~/.bash_profile` 等）中设置以下变量来全局配置默认值：
@@ -78,11 +77,12 @@ export PI_ASK_USER_COMMENT_TOGGLE_KEY=alt+c
 
 生效优先级：
 
-1. 每次调用时的 `displayMode` 参数（如提供）
-2. `PI_ASK_USER_DISPLAY_MODE`（如设置为 `"overlay"` 或 `"inline"`）
-3. 项目配置文件 `.pi/ask-user.json`（如存在）中的 `displayMode`
-4. 用户配置文件 `~/.pi/agent/ask-user.json`（如存在）中的 `displayMode`
-5. 回退默认值：`"overlay"`
+1. `PI_ASK_USER_DISPLAY_MODE`（如设置为 `"overlay"` 或 `"inline"`）
+2. 项目配置文件 `.pi/ask-user.json`（如存在）中的 `displayMode`
+3. 用户配置文件 `~/.pi/agent/ask-user.json`（如存在）中的 `displayMode`
+4. 回退默认值：`"overlay"`
+
+（SDK/直接调用传入的 `displayMode` 仍会覆盖以上所有层级，但该字段已不在模型可见的 tool schema 里。）
 
 无法识别的值会被静默忽略并回退到 `"overlay"`。
 
@@ -94,7 +94,7 @@ export PI_ASK_USER_COMMENT_TOGGLE_KEY=alt+c
 - 用户级（全局）：`~/.pi/agent/ask-user.json`
 - 项目级：`.pi/ask-user.json`
 
-项目级文件中的字段会覆盖用户级文件中同名字段。配置优先级：调用参数 > 环境变量 > 项目配置 > 用户配置 > 默认值。
+项目级文件中的字段会覆盖用户级文件中同名字段。配置优先级：环境变量 > 项目配置 > 用户配置 > 默认值。
 
 **示例 `~/.pi/agent/ask-user.json`：**
 
@@ -112,10 +112,9 @@ export PI_ASK_USER_COMMENT_TOGGLE_KEY=alt+c
 
 `overlayToggleKey` 和 `commentToggleKey` 的生效优先级：
 
-1. 每次调用时的参数（如提供）
-2. 对应的环境变量（`PI_ASK_USER_OVERLAY_TOGGLE_KEY` / `PI_ASK_USER_COMMENT_TOGGLE_KEY`）
-3. 项目配置文件 `.pi/ask-user.json`（如存在）
-4. 用户配置文件 `~/.pi/agent/ask-user.json`（如存在）
+1. 对应的环境变量（`PI_ASK_USER_OVERLAY_TOGGLE_KEY` / `PI_ASK_USER_COMMENT_TOGGLE_KEY`）
+2. 项目配置文件 `.pi/ask-user.json`（如存在）
+3. 用户配置文件 `~/.pi/agent/ask-user.json`（如存在）
 5. 内置默认值：`alt+o` 和 `ctrl+g`
 
 传入 `"off"`、`"none"` 或 `"disabled"`（任意级别）可以完全禁用快捷键。无效的键位格式会被静默丢弃，使用下一个来源。键位格式遵循 Pi-TUI 的 [`KeyId`](https://github.com/earendil-works/pi-mono/blob/main/packages/tui/src/keys.ts) 格式：`[mod+]...key`，修饰键为 `ctrl`、`shift`、`alt`、`super`，可任意顺序用 `+` 连接（如 `ctrl+g`、`alt+shift+x`、`escape`、`tab`）。
@@ -132,7 +131,7 @@ export PI_ASK_USER_COMMENT_TOGGLE_KEY=alt+c
 | `esc` | 清除搜索过滤、退出自由文本/注释模式、或取消提示。 |
 | `↑` / `↓`、`ctrl+k` / `ctrl+j` | 导航选项。`ctrl+k` / `ctrl+j`（vim 风格）可在可搜索提示中打字时不干扰过滤输入。 |
 
-如果你始终不希望看到叠加层，请每次调用时设置 `displayMode: "inline"`，或全局设置 `PI_ASK_USER_DISPLAY_MODE=inline`。
+如果你始终不希望看到叠加层，请全局设置 `PI_ASK_USER_DISPLAY_MODE=inline`，或在 `ask-user.json` 中设置 `"displayMode": "inline"`。
 
 ## 结果详情
 

package/index.ts

@@ -32,30 +32,12 @@ import {
 	truncateToWidth,
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
-import { type TUnsafe, Type } from "typebox";
+import { Type } from "typebox";
 import { type QuestionOption, renderSingleSelectRows } from "./src/single-select-layout.js";
 
 const _require = createRequire(import.meta.url);
 const ASK_USER_VERSION: string = (_require("./package.json") as { version: string }).version;
 
-/**
- * Emit a flat `{ type: "string", enum: [...] }` JSON Schema instead of the
- * `anyOf`/`oneOf` shape that `Type.Union([Type.Literal()])` produces. Google's
- * function-calling API rejects the union form. Local copy of pi-ai's StringEnum
- * to avoid a peer dependency for one helper.
- */
-function StringEnum<const T extends readonly string[]>(
-	values: T,
-	options?: { description?: string; default?: T[number] },
-): TUnsafe<T[number]> {
-	return Type.Unsafe<T[number]>({
-		type: "string",
-		enum: [...values],
-		...(options?.description ? { description: options.description } : {}),
-		...(options?.default !== undefined ? { default: options.default } : {}),
-	});
-}
-
 /**
  * `getMarkdownTheme()` returns a bag of closures that read through a Proxy
  * over the host's theme singleton. The Proxy only throws on property access,
@@ -1534,15 +1516,12 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "ask_user",
 		label: "Ask User",
-		description:
-			"Ask the user a question with optional multiple-choice answers. Use this to gather information interactively. Ask exactly one focused question per call. Before calling, gather context with tools (read/web/ref) and pass a short summary via the context field.",
-		promptSnippet:
-			"Ask the user one focused question with optional multiple-choice answers to gather information interactively",
+		description: "Ask the user one focused question with optional multiple-choice answers.",
+		promptSnippet: "Ask the user one focused question with optional multiple-choice answers",
 		promptGuidelines: [
-			"Before calling ask_user, gather context with tools (read/web/ref) and pass a short summary via the context field.",
+			"Before calling ask_user, gather context with your read/search/web tools and pass a short summary via the context field.",
 			"Use ask_user when the user's intent is ambiguous, when a decision requires explicit user input, or when multiple valid options exist.",
-			"Ask exactly one focused question per ask_user call.",
-			"Do not combine multiple numbered, multipart, or unrelated questions into one ask_user prompt.",
+			"Ask exactly one focused question per ask_user call — never combine multiple, numbered, or unrelated questions in one prompt.",
 		],
 		// Block other tool calls in the same assistant turn until the user answers,
 		// so the model can't batch ask_user with bash/edit/write and let those run
@@ -1570,28 +1549,14 @@ export default function (pi: ExtensionAPI) {
 			allowMultiple: Type.Optional(Type.Boolean({ description: "Allow selecting multiple options. Default: false" })),
 			allowFreeform: Type.Optional(Type.Boolean({ description: "Add a freeform text option. Default: true" })),
 			allowComment: Type.Optional(
-				Type.Boolean({ description: "Collect an optional comment after selecting one or more options. Default: false" }),
-			),
-			displayMode: Type.Optional(
-				StringEnum(["overlay", "inline"] as const, {
-					description:
-						"UI rendering mode. 'overlay' shows a centered modal, 'inline' renders in-place. Default: PI_ASK_USER_DISPLAY_MODE env var if set, otherwise 'overlay'. Omit to respect the user's configured preference.",
-				}),
-			),
-			overlayToggleKey: Type.Optional(
-				Type.String({
-					description:
-						"Shortcut for hiding/showing the overlay popup (overlay mode only), e.g. 'alt+o' or 'ctrl+shift+h'. Pass 'off' to disable. Default: PI_ASK_USER_OVERLAY_TOGGLE_KEY env var if set, otherwise 'alt+o'.",
-				}),
-			),
-			commentToggleKey: Type.Optional(
-				Type.String({
-					description:
-						"Shortcut for toggling the optional comment/extra-context row when allowComment is true, e.g. 'ctrl+g'. Pass 'off' to disable. Default: PI_ASK_USER_COMMENT_TOGGLE_KEY env var if set, otherwise 'ctrl+g'.",
-				}),
+				Type.Boolean({ description: "Collect an optional comment after selecting one or more options. Default: true" }),
 			),
+			// 外观类选项（displayMode / overlayToggleKey / commentToggleKey）不再暴露给模型：
+			// 它们是**用户偏好**，优先级为 模型参数 > env > ask-user.json > 默认值，模型能直接
+			// 盖掉用户的设置，且占了 782 字符的 schema。取值改由 env（PI_ASK_USER_DISPLAY_MODE 等）
+			// 与 ask-user.json 提供，内部解析链与 `AskParams` 类型保留（SDK/内部调用仍可传）。
 			timeout: Type.Optional(
-				Type.Number({ description: "Auto-dismiss after N milliseconds. Returns null (cancelled) when expired." }),
+				Type.Number({ description: "Auto-dismiss after N ms; returns null when expired." }),
 			),
 		}),
 
@@ -1609,7 +1574,7 @@ export default function (pi: ExtensionAPI) {
 				options: rawOptions = [],
 				allowMultiple = false,
 				allowFreeform = true,
-				allowComment = false,
+				allowComment = true,
 				displayMode,
 				overlayToggleKey,
 				commentToggleKey,

package/package.json

@@ -3,7 +3,7 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"version": "0.2.1",
+	"version": "0.4.0",
 	"description": "Interactive ask_user tool for pi-coding-agent with searchable split-pane selection UI, multi-select, and freeform input",
 	"license": "MIT",
 	"repository": {
@@ -41,10 +41,10 @@
 		"typebox": "*"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.14",
-		"@types/node": "^26.6.2",
-		"typebox": "^1.3.34",
+		"@biomejs/biome": "^2.6.2",
+		"@types/node": "^26.6.5",
+		"typebox": "^1.4.3",
 		"typescript": "~7.0.2",
-		"vitest": "^5.0.1"
+		"vitest": "^5.0.5"
 	}
 }