@rol1n/pi-kit 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RoL1n_SrP
+
+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.md

@@ -1,99 +1,136 @@
 # pi-kit
 
-Pi extensions and prompt templates, published together as **`@rol1n/pi-kit`** or as individual extension packages. Each extension's README describes its commands, settings, platform support, and dependencies.
+> Modular extensions and prompt templates for the [Pi Coding Agent](https://pi.dev), published as the **`@rol1n/pi-kit`** bundle and as standalone **`@rol1n/<extension>`** packages.
+
+<p align="left">
+  <b>English</b> •
+  <a href="README_zh.md"><b>中文说明</b></a>
+</p>
+
+[![npm version](https://img.shields.io/npm/v/@rol1n/pi-kit?style=flat-square&logo=npm)](https://www.npmjs.com/package/@rol1n/pi-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+
+---
 
 ## Install
 
+Install the default bundle:
+
 ```sh
 pi install npm:@rol1n/pi-kit
 ```
 
+Or install any standalone extension individually:
+
+```sh
+pi install npm:@rol1n/memory-log
+pi install npm:@rol1n/subagent
+pi install npm:@rol1n/multi-harness
+```
+
 Install from GitHub or a local checkout during development:
 
 ```sh
-pi install git:git@github.com:RolinShmily/pi-kit.git
+pi install https://github.com/RolinShmily/pi-kit
 pi install /absolute/path/to/pi-kit
 ```
 
-Update an installed package with `pi update npm:@rol1n/pi-kit`, or update all Pi packages with `pi update --extensions`.
+Update installed packages:
+
+```sh
+pi update npm:@rol1n/pi-kit
+pi update --extensions
+```
+
+---
 
 ## Extensions
 
-| Package and documentation | Purpose | Included in the kit |
-|---|---|---|
-| [ask-u-questions](extensions/ask-u-questions/README.md) | Interactive questions | Yes |
-| [continue-signal](extensions/continue-signal/README.md) | Resume an idle agent | Yes |
-| [custom-providers](extensions/custom-providers/README.md) | Additional model providers and gateway configuration | Yes |
-| [image-generate](extensions/image-generate/README.md) | Image generation and model selection | Yes |
-| [memory-log](extensions/memory-log/README.md) | Background observational memory | Yes |
-| [model-vision](extensions/model-vision/README.md) | Image understanding and OCR | No |
-| [multi-harness](extensions/multi-harness/README.md) | Delegate to Pi, Codex, Claude, and OpenCode | Yes |
-| [oai-subquota](extensions/oai-subquota/README.md) | Codex subscription quota | Yes |
-| [prompt-snipaste](extensions/prompt-snipaste/README.md) | Select snippets for the next user message | Yes |
-| [screenshot](extensions/screenshot/README.md) | Reference the latest Windows/WSL screenshot | No |
-| [srp-theme](extensions/srp-theme/README.md) | Footer, prompt preview, and throughput display | Yes |
-| [subagent](extensions/subagent/README.md) | Delegate to asynchronous Pi workers | Yes |
-| [tui-asr](extensions/tui-asr/README.md) | Streaming voice dictation | Yes |
-| [web-reach](extensions/web-reach/README.md) | Web search and page extraction | Yes |
-| [windows-wheel-fix](extensions/windows-wheel-fix/README.md) | Windows ConPTY/Zellij mouse reporting | Yes, active only on Windows |
-
-Independent package names use the `@rol1n/<name>` scope, such as `@rol1n/memory-log` or `@rol1n/multi-harness`. Each package has its own release version and README; the implementation is shared with the kit.
-
-Every extension uses the same directory layout:
-
-```text
-extensions/<name>/
-├── index.ts          # Pi entrypoint and registration
-├── README.md         # Package documentation
-└── ...               # Modules grouped by responsibility
-```
+Each top-level directory is a self-contained extension (`<name>/index.ts` + `README.md`). Detailed commands, parameters, and settings are documented in each extension's README:
+
+| Extension | Description | In `@rol1n/pi-kit` | Standalone Package |
+| :--- | :--- | :---: | :--- |
+| [ask-u-questions](ask-u-questions/README.md) | Interactive single-choice, multi-choice, and text dialogs | Yes | `@rol1n/ask-u-questions` |
+| [continue-signal](continue-signal/README.md) | Resume an idle agent via `/continue` or `Alt+C` | Yes | `@rol1n/continue-signal` |
+| [custom-providers](custom-providers/README.md) | Additional model providers and gateway registration | Yes | `@rol1n/custom-providers` |
+| [image-generate](image-generate/README.md) | Image generation tool and `/image-generate` model selector | Yes | `@rol1n/image-generate` |
+| [memory-log](memory-log/README.md) | Tiered asynchronous observational memory and instant compaction | Yes | `@rol1n/memory-log` |
+| [model-vision](model-vision/README.md) | Image understanding and OCR tool (`model_vision`) | No | `@rol1n/model-vision` |
+| [multi-harness](multi-harness/README.md) | Delegate tasks across `pi`, `codex`, `claude`, and `opencode` | Yes | `@rol1n/multi-harness` |
+| [oai-subquota](oai-subquota/README.md) | OpenAI Codex subscription quota monitor and statusline | Yes | `@rol1n/oai-subquota` |
+| [prompt-snipaste](prompt-snipaste/README.md) | Prompt snippet selector (`/snipaste`, `Alt+S`) with 7 built-in prompts | Yes | `@rol1n/prompt-snipaste` |
+| [screenshot](screenshot/README.md) | Insert the latest Windows/WSL screenshot path (`/screenshot`) | No | `@rol1n/screenshot` |
+| [srp-theme](srp-theme/README.md) | Last-prompt preview widget and real-time streaming TPS meter | Yes | `@rol1n/srp-theme` |
+| [subagent](subagent/README.md) | Delegate tasks to parallel Pi workers in tmux/Zellij or background processes | Yes | `@rol1n/subagent` |
+| [tui-asr](tui-asr/README.md) | Streaming voice dictation via Aliyun DashScope ASR (`/asr`, `Alt+M`) | Yes | `@rol1n/tui-asr` |
+| [web-reach](web-reach/README.md) | Keyless Exa MCP web search and multi-tier page extraction | No | `@rol1n/web-reach` |
+| [windows-wheel-fix](windows-wheel-fix/README.md) | Windows ConPTY / Zellij mouse-wheel reporting fix | Yes (Windows) | `@rol1n/windows-wheel-fix` |
 
-UI, transport, parsing, and storage helpers live beside the entrypoint as needed. Small extensions can remain a single cohesive `index.ts`.
+> Standalone packages with cross-extension dependencies (`tui-asr` / `image-generate` -> `@rol1n/custom-providers`, `multi-harness` -> `@rol1n/subagent`) declare standard npm `dependencies` and resolve them automatically on install.
 
-## Resource selection
+---
 
-The kit currently exposes 13 extension entrypoints and the seven templates in [prompts](prompts/). Personal skills, provider credentials, MCP servers, and keybindings remain normal Pi configuration.
+## Resource Selection
 
-Use `pi config` or narrow package resources in personal/project settings:
+`@rol1n/pi-kit` exposes 12 extension entrypoints and the 7 prompt templates bundled in [prompt-snipaste/prompts](prompt-snipaste/prompts/). Use `pi config` or filter loaded resources in `settings.json`:
 
 ```json
 {
   "packages": [
     {
       "source": "npm:@rol1n/pi-kit",
-      "extensions": ["extensions/**", "!extensions/tui-asr/**"],
-      "prompts": ["prompts/diagnose-report.md"]
+      "extensions": ["**/*.ts", "!tui-asr/**"],
+      "prompts": ["prompt-snipaste/prompts/diagnose-report.md"]
     }
   ]
 }
 ```
 
-Omit a resource field to load the package defaults; use `[]` to disable that resource type. Filters select resources already exposed by the package. When also installing an independent extension package, exclude its entry from the kit to avoid loading the same feature twice.
+---
+
+## Development & Publishing
 
-## Build and publish
+[kit.config.json](kit.config.json) controls bundle selection (`bundle`), inter-extension dependencies (`deps`), and release versions. The top-level `version` belongs to `@rol1n/pi-kit`; each extension can set its own `version`, otherwise it inherits the top-level version. Set explicit extension versions to release the kit and standalone packages independently.
 
-From a source checkout, edit [kit.config.json](https://github.com/RolinShmily/pi-kit/blob/main/kit.config.json) to choose each extension's `bundle` flag, package name, version, entrypoint, runtime files, and README. Then synchronize and inspect the aggregate release:
+### Automated releases
+
+1. Update the code and bump the relevant version(s) in `kit.config.json`.
+2. Push to `main` with changes to `kit.config.json` or `package.json`, or manually run **Publish to npm** in GitHub Actions. Changes to the packaging script or workflow also trigger a release run.
+3. CI runs the same pipeline for both triggers:
 
 ```sh
 npm run manifest
 npm run check
-npm pack --dry-run --ignore-scripts
-npm publish --access public
+npm run publish:ci -- all
 ```
 
-Prepare an independent release from the same source:
+The workflow in [`.github/workflows/publish.yml`](.github/workflows/publish.yml) generates `package.json`, validates the layout, then publishes all standalone extensions in dependency order, followed by the kit. Already-published versions are skipped; versions are never bumped automatically. `bundle: false` excludes an extension from the kit, not from standalone publishing. Publishing runs do not overlap, and a new run does not cancel an active release. Code-only pushes do not trigger publishing.
+
+You do not need to run `manifest` or publish locally for an npm release. CI generates the manifest only in its checkout and does not commit it back. For local or Git installs, run `npm run manifest` and commit the generated `package.json` when changing bundle selection or versions so the repository manifest stays in sync.
+
+### Local development and manual publishing
 
 ```sh
+# Sync the local manifest and validate all extensions
+npm run manifest
+npm run check
+
+# Stage a standalone package into dist/<id>
 npm run prepare:extension -- memory-log
-cd dist/extensions/memory-log
-npm pack --dry-run --ignore-scripts
-npm publish --access public
+
+# Optional local release; also accepts extensions, kit, or a single extension ID
+npm run publish:ci -- all
 ```
 
-The preparation command copies that extension's README to the package root and includes shared implementation files where needed. Add new runtime assets to its `files` list. Names and versions are configured independently; use an available npm name and a new version for each publication. Preparation does not install dependencies or publish anything.
+---
+
+## Acknowledgements
+
+- [elpapi42/pi-observational-memory](https://github.com/elpapi42/pi-observational-memory) — Observational memory architecture and inspiration for [`memory-log`](memory-log/README.md).
+- [earendil-works/pi](https://github.com/earendil-works/pi) — The Pi coding agent harness and SDK.
 
-All packages link to [RolinShmily/pi-kit](https://github.com/RolinShmily/pi-kit). The `pi-package` keyword makes each published package eligible for the Pi gallery; indexing can take time. Pi supplies the host libraries declared as peer dependencies.
+---
 
-## Attribution
+## License
 
-Existing author and copyright notices remain with their source files. Upstream issue references and integration details are linked from the individual extension READMEs, including the [Windows terminal workaround](extensions/windows-wheel-fix/README.md).
+[MIT](LICENSE) © RoL1n_SrP

package/README_zh.md

@@ -0,0 +1,136 @@
+# pi-kit
+
+> 面向 [Pi Coding Agent](https://pi.dev) 的模块化扩展与提示词模板套件，支持作为 **`@rol1n/pi-kit`** 聚合包或 **`@rol1n/<extension>`** 独立包安装。
+
+<p align="left">
+  <a href="README.md"><b>English</b></a> •
+  <b>中文说明</b>
+</p>
+
+[![npm version](https://img.shields.io/npm/v/@rol1n/pi-kit?style=flat-square&logo=npm)](https://www.npmjs.com/package/@rol1n/pi-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+
+---
+
+## 安装
+
+安装默认聚合包：
+
+```sh
+pi install npm:@rol1n/pi-kit
+```
+
+或按需安装任意独立扩展包：
+
+```sh
+pi install npm:@rol1n/memory-log
+pi install npm:@rol1n/subagent
+pi install npm:@rol1n/multi-harness
+```
+
+开发期间也可直接从 GitHub 或本地目录安装：
+
+```sh
+pi install https://github.com/RolinShmily/pi-kit
+pi install /absolute/path/to/pi-kit
+```
+
+更新已安装的包：
+
+```sh
+pi update npm:@rol1n/pi-kit
+pi update --extensions
+```
+
+---
+
+## 扩展列表
+
+仓库根目录下每个文件夹均为自包含扩展（`<name>/index.ts` + `README.md`）。各扩展的详细命令、参数与配置说明请参阅对应目录的 README：
+
+| 扩展目录 | 功能简介 | 默认纳入 `pi-kit` | 独立 npm 包名 |
+| :--- | :--- | :---: | :--- |
+| [ask-u-questions](ask-u-questions/README.md) | 交互式单选、多选与自由文本提问弹窗（共享 UI 锁） | Yes | `@rol1n/ask-u-questions` |
+| [continue-signal](continue-signal/README.md) | 通过 `/continue` 或 `Alt+C` 唤醒空闲智能体继续未完成任务 | Yes | `@rol1n/continue-signal` |
+| [custom-providers](custom-providers/README.md) | 自定义模型服务商与网关（Magpie、智谱、阿里百炼等）注册 | Yes | `@rol1n/custom-providers` |
+| [image-generate](image-generate/README.md) | OpenRouter / 百炼文生图与参考图生图工具及 `/image-generate` 模型选择器 | Yes | `@rol1n/image-generate` |
+| [memory-log](memory-log/README.md) | 分层异步观察记忆系统与零模型阻塞的确定性秒级压缩 | Yes | `@rol1n/memory-log` |
+| [model-vision](model-vision/README.md) | 本地与远程图片视觉理解、OCR 与 UI 诊断工具（`model_vision`） | No | `@rol1n/model-vision` |
+| [multi-harness](multi-harness/README.md) | 跨 `pi`、`codex`、`claude`、`opencode` 的多 CLI 协同委派运行时 | Yes | `@rol1n/multi-harness` |
+| [oai-subquota](oai-subquota/README.md) | OpenAI Codex 订阅额度（5h / 7d 窗口与重置时间）状态栏监控 | Yes | `@rol1n/oai-subquota` |
+| [prompt-snipaste](prompt-snipaste/README.md) | 提示词片段选择器（`/snipaste`、`Alt+S`），内置 7 个常用提示词模板 | Yes | `@rol1n/prompt-snipaste` |
+| [screenshot](screenshot/README.md) | 一键将最新 Windows / WSL 系统截图路径插入编辑器（`/screenshot`） | No | `@rol1n/screenshot` |
+| [srp-theme](srp-theme/README.md) | 编辑器下方最近提问预览组件与实时流式 TPS 速率仪表 | Yes | `@rol1n/srp-theme` |
+| [subagent](subagent/README.md) | 基于 tmux / Zellij 分屏或后台进程的并发 Pi 子智能体工具 | Yes | `@rol1n/subagent` |
+| [tui-asr](tui-asr/README.md) | 基于阿里百炼 Paraformer 的终端实时流式语音听写（`/asr`、`Alt+M`） | Yes | `@rol1n/tui-asr` |
+| [web-reach](web-reach/README.md) | 免 Key Exa MCP 网页搜索与多级网页正文提取（RSC / HTML / PDF / Jina） | No | `@rol1n/web-reach` |
+| [windows-wheel-fix](windows-wheel-fix/README.md) | 修复 Windows ConPTY / Zellij 下鼠标滚轮被误转为上下方向键的问题 | Yes (仅 Windows) | `@rol1n/windows-wheel-fix` |
+
+> 带有跨扩展依赖的独立包（`tui-asr` / `image-generate` 依赖 `@rol1n/custom-providers`，`multi-harness` 依赖 `@rol1n/subagent`）已声明标准 npm `dependencies`，单独安装时会自动拉取补全并激活所需依赖。
+
+---
+
+## 资源按需筛选
+
+`@rol1n/pi-kit` 默认导出 12 个扩展入口与 [prompt-snipaste/prompts](prompt-snipaste/prompts/) 下的 7 个提示词模板。可通过 `pi config` 或在 `settings.json` 中按需过滤：
+
+```json
+{
+  "packages": [
+    {
+      "source": "npm:@rol1n/pi-kit",
+      "extensions": ["**/*.ts", "!tui-asr/**"],
+      "prompts": ["prompt-snipaste/prompts/diagnose-report.md"]
+    }
+  ]
+}
+```
+
+---
+
+## 构建与发布
+
+[kit.config.json](kit.config.json) 统一管理聚合包选择（`bundle`）、扩展间的依赖关系（`deps`）与发布版本。顶层 `version` 属于 `@rol1n/pi-kit`；各扩展可以单独设置 `version`，未设置时继承顶层版本。为每个扩展显式设置版本即可让聚合包与独立包分别升级。
+
+### 自动发布
+
+1. 修改代码，并在 `kit.config.json` 中提升需要发布的包的版本。
+2. 将包含 `kit.config.json` 或 `package.json` 变更的提交推送到 `main`，或在 GitHub Actions 手动运行 **Publish to npm**。修改打包脚本或工作流本身也会触发发布流程。
+3. 自动和手动触发均执行同一条流水线：
+
+```sh
+npm run manifest
+npm run check
+npm run publish:ci -- all
+```
+
+[`.github/workflows/publish.yml`](.github/workflows/publish.yml) 会生成 `package.json`、校验扩展布局，再按依赖顺序发布所有独立扩展，最后发布聚合包。已存在的版本自动跳过，不会自动提升版本号。`bundle: false` 只表示不纳入聚合包，不影响独立发布。发布流程不会并行执行，新触发的流程也不会取消正在进行的发布。仅修改扩展代码不会触发发布。
+
+发布 npm 包无需本地运行 `manifest` 或 `publish`。CI 只在运行目录中生成清单，不会自动提交回仓库。若使用本地或 Git 安装，调整聚合包选择或版本后仍应运行 `npm run manifest` 并提交生成的 `package.json`，保持仓库清单同步。
+
+### 本地开发与手动发布
+
+```sh
+# 同步本地清单并校验所有扩展
+npm run manifest
+npm run check
+
+# 将单个扩展构建到 dist/<id>
+npm run prepare:extension -- memory-log
+
+# 可选的本地发布，也支持 extensions、kit 或单个扩展 ID
+npm run publish:ci -- all
+```
+
+---
+
+## 致谢
+
+- [elpapi42/pi-observational-memory](https://github.com/elpapi42/pi-observational-memory) — [`memory-log`](memory-log/README.md) 的观察记忆架构灵感与上游基础。
+- [earendil-works/pi](https://github.com/earendil-works/pi) — Pi Coding Agent 运行时与 SDK。
+
+---
+
+## 许可证
+
+[MIT](LICENSE) © RoL1n_SrP

package/ask-u-questions/README.md

@@ -0,0 +1,26 @@
+# ask-u-questions
+
+Interactive single-choice, multiple-choice, and free-text questions for Pi. Registers the `ask_user_question` tool and serializes dialogs through a shared UI lock.
+
+## Install
+
+```sh
+pi install npm:@rol1n/ask-u-questions
+```
+
+Also included in `@rol1n/pi-kit`.
+
+## Use
+
+```json
+{
+  "question": "Which output format should I use?",
+  "options": [
+    { "label": "Markdown (Recommended)", "value": "markdown" },
+    { "label": "JSON", "value": "json" }
+  ],
+  "multiSelect": false
+}
+```
+
+Omit `options` or pass `[]` for free-text input. Set `multiSelect: true` only when multiple choices are expected. `details` adds supporting context, and an `Other` option is provided automatically for choice questions.

package/{extensions/ask-u-questions → ask-u-questions}/dialog-ui.ts

@@ -55,3 +55,26 @@ export function addWrapped(
   }
 }
 
+const SHARED_UI_LOCK_KEY = "__piSharedUiLock";
+function getSharedUiLock(): { withLock<T>(fn: () => T | Promise<T>): Promise<T> } {
+  const g = globalThis as any;
+  if (!g[SHARED_UI_LOCK_KEY]) {
+    let chain: Promise<void> = Promise.resolve();
+    g[SHARED_UI_LOCK_KEY] = {
+      withLock<T>(fn: () => T | Promise<T>): Promise<T> {
+        const prev = chain;
+        let release: () => void;
+        chain = new Promise<void>((r) => {
+          release = r;
+        });
+        return prev.then(fn).finally(() => release!());
+      },
+    };
+  }
+  return g[SHARED_UI_LOCK_KEY];
+}
+const sharedUiLock = getSharedUiLock();
+
+export function withUILock<T>(fn: () => Promise<T>): Promise<T> {
+  return sharedUiLock.withLock(fn);
+}

package/{extensions/ask-u-questions → ask-u-questions}/index.ts

@@ -1,12 +1,16 @@
 /** Interactive questions, serialized through the shared dialog lock. */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { AskUserQuestionMode } from "./types.ts";
-import { AskUserQuestionParams } from "./schema.ts";
-import { normalizeOptions } from "./answers.ts";
-import { buildResult, cancelledResult, unavailableResult } from "./results.ts";
+import {
+  AskUserQuestionParams,
+  buildResult,
+  cancelledResult,
+  normalizeOptions,
+  unavailableResult,
+  type AskUserQuestionMode,
+} from "./types.ts";
+import { withUILock } from "./dialog-ui.ts";
 import { askSingleChoice } from "./single-choice.ts";
 import { askMultiChoice } from "./multi-choice.ts";
-import { withUILock } from "./ui-lock.ts";
 import { questionRenderers } from "./tool-renderers.ts";
 
 export type { AskOption, TextAnswer, OptionAnswer, OtherAnswer, AskAnswer, AskUserQuestionStatus, AskUserQuestionMode, AskUserQuestionResultDetails } from "./types.ts";

package/{extensions/ask-u-questions → ask-u-questions}/multi-choice.ts

@@ -1,7 +1,6 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Editor, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import type { AskAnswer, AskOption, DisplayOption } from "./types.ts";
-import { getOtherLabel, isChineseContext, sortAnswers } from "./answers.ts";
+import { getOtherLabel, isChineseContext, sortAnswers, type AskAnswer, type AskOption, type DisplayOption } from "./types.ts";
 import { addWrapped, createEditorTheme } from "./dialog-ui.ts";
 
 export async function askMultiChoice(
@@ -257,4 +256,3 @@ export async function askMultiChoice(
     },
   );
 }
-

package/{extensions/ask-u-questions → ask-u-questions}/single-choice.ts

@@ -1,7 +1,6 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Editor, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
-import type { AskAnswer, AskOption, DisplayOption } from "./types.ts";
-import { getOtherLabel, isChineseContext } from "./answers.ts";
+import { getOtherLabel, isChineseContext, type AskAnswer, type AskOption, type DisplayOption } from "./types.ts";
 import { addWrapped, createEditorTheme } from "./dialog-ui.ts";
 
 export async function askSingleChoice(
@@ -179,4 +178,3 @@ export async function askSingleChoice(
     },
   );
 }
-

package/{extensions/ask-u-questions → ask-u-questions}/tool-renderers.ts

@@ -1,8 +1,6 @@
 import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
-import type { AskUserQuestionParams } from "./schema.ts";
-import type { AskUserQuestionResultDetails } from "./types.ts";
-import { getOtherLabel, isChineseContext, normalizeOptions } from "./answers.ts";
+import { AskUserQuestionParams, getOtherLabel, isChineseContext, normalizeOptions, type AskUserQuestionResultDetails } from "./types.ts";
 
 export const questionRenderers: Pick<ToolDefinition<typeof AskUserQuestionParams, AskUserQuestionResultDetails>, "renderCall" | "renderResult"> = {
   renderCall(args, theme, context) {

package/ask-u-questions/types.ts

@@ -0,0 +1,192 @@
+import { Type } from "typebox";
+
+const OptionSchema = Type.Object({
+  label: Type.String({ description: 'Option label. Put a recommended option first and append "(Recommended)".' }),
+  value: Type.Optional(Type.String({ description: "Machine-readable value; defaults to the label." })),
+  description: Type.Optional(Type.String({ description: "Additional context shown below the option." })),
+});
+
+export const AskUserQuestionParams = Type.Object({
+  question: Type.String({ description: "The question to ask. Ask only one question per call." }),
+  details: Type.Optional(Type.String({ description: "Background or instructions shown below the question." })),
+  options: Type.Optional(Type.Array(OptionSchema, {
+    description: "Choices for selection. Omit or pass an empty array for free-text input. An Other choice is always available.",
+  })),
+  multiSelect: Type.Optional(Type.Boolean({ description: "Allow selecting multiple options when true." })),
+});
+
+export interface AskOption {
+  label: string;
+  value: string;
+  description?: string;
+}
+
+export interface DisplayOption extends AskOption {
+  id: string;
+  index?: number;
+  isOther?: boolean;
+  isSubmit?: boolean;
+}
+
+export interface TextAnswer {
+  type: "text";
+  label: string;
+  value: string;
+}
+
+export interface OptionAnswer {
+  type: "option";
+  label: string;
+  value: string;
+  index: number;
+}
+
+export interface OtherAnswer {
+  type: "other";
+  label: string;
+  value: string;
+}
+
+export type AskAnswer = TextAnswer | OptionAnswer | OtherAnswer;
+export type AskUserQuestionStatus = "answered" | "cancelled" | "unavailable";
+export type AskUserQuestionMode = "text" | "single-select" | "multi-select";
+
+export interface AskUserQuestionResultDetails {
+  status: AskUserQuestionStatus;
+  question: string;
+  context?: string;
+  mode: AskUserQuestionMode;
+  answers: AskAnswer[];
+  message?: string;
+}
+
+export function normalizeOptions(
+  options: Array<{ label: string; value?: string; description?: string }> | undefined,
+): AskOption[] {
+  return (options || [])
+    .map((option) => ({
+      label: option.label.trim(),
+      value: option.value?.trim() || option.label.trim(),
+      description: option.description?.trim() || undefined,
+    }))
+    .filter((option) => option.label.length > 0);
+}
+
+export function isChineseContext(
+  question: string,
+  options?: Array<{ label?: string; description?: string }>,
+  context?: string,
+): boolean {
+  if (/[\u4e00-\u9fa5]/.test(question)) return true;
+  if (context && /[\u4e00-\u9fa5]/.test(context)) return true;
+  if (options && options.some((o) => (o.label && /[\u4e00-\u9fa5]/.test(o.label)) || (o.description && /[\u4e00-\u9fa5]/.test(o.description)))) {
+    return true;
+  }
+  return false;
+}
+
+export function getOtherLabel(options: AskOption[], isZh = false): string {
+  if (isZh) {
+    return options.some((option) => option.label === "其他（自定义输入）")
+      ? "自定义输入"
+      : "其他（自定义输入）";
+  }
+  return options.some((option) => option.label === "Other (custom input)")
+    ? "Custom input"
+    : "Other (custom input)";
+}
+
+function answerSortRank(answer: AskAnswer): number {
+  switch (answer.type) {
+    case "option":
+      return answer.index;
+    case "other":
+      return Number.MAX_SAFE_INTEGER - 1;
+    case "text":
+      return Number.MAX_SAFE_INTEGER;
+  }
+}
+
+export function sortAnswers(answers: AskAnswer[]): AskAnswer[] {
+  return [...answers].sort((a, b) => answerSortRank(a) - answerSortRank(b));
+}
+
+function formatAnswerForModel(answer: AskAnswer): string {
+  switch (answer.type) {
+    case "text":
+      return answer.label;
+    case "other":
+      return `Other: ${answer.label}`;
+    case "option":
+      return `${answer.index}. ${answer.label}`;
+  }
+}
+
+function buildStructuredResult(
+  status: AskUserQuestionStatus,
+  question: string,
+  mode: AskUserQuestionMode,
+  answers: AskAnswer[],
+  context?: string,
+  message?: string,
+): AskUserQuestionResultDetails {
+  return {
+    status,
+    question,
+    context,
+    mode,
+    answers,
+    message,
+  };
+}
+
+export function cancelledResult(question: string, mode: AskUserQuestionMode, context?: string) {
+  const isZh = isChineseContext(question, undefined, context);
+  const message = isZh ? "用户取消了本次提问" : "User cancelled the question.";
+  return {
+    content: [{ type: "text" as const, text: message }],
+    details: buildStructuredResult("cancelled", question, mode, [], context, message),
+  };
+}
+
+export function unavailableResult(question: string, mode: AskUserQuestionMode, message: string, context?: string) {
+  return {
+    content: [{ type: "text" as const, text: message }],
+    details: buildStructuredResult("unavailable", question, mode, [], context, message),
+  };
+}
+
+export function buildResult(
+  question: string,
+  context: string | undefined,
+  mode: AskUserQuestionMode,
+  answers: AskAnswer[],
+) {
+  const isZh = isChineseContext(question, answers, context);
+  let text: string;
+  if (mode === "text") {
+    const answer = answers[0];
+    if (isZh) {
+      text = answer.label.trim().length > 0
+        ? `用户输入回答: ${answer.label}`
+        : "用户提交了空回答";
+    } else {
+      text = answer.label.trim().length > 0
+        ? `User answered: ${answer.label}`
+        : "User submitted an empty answer";
+    }
+  } else if (mode === "single-select") {
+    text = isZh
+      ? `用户选择项: ${formatAnswerForModel(answers[0])}`
+      : `User selected: ${formatAnswerForModel(answers[0])}`;
+  } else {
+    text = isZh
+      ? `用户选择多项:\n${answers.map((answer) => `- ${formatAnswerForModel(answer)}`).join("\n")}`
+      : `User selected multiple:\n${answers.map((answer) => `- ${formatAnswerForModel(answer)}`).join("\n")}`;
+  }
+
+  return {
+    content: [{ type: "text" as const, text }],
+    details: buildStructuredResult("answered", question, mode, answers, context),
+  };
+}