@trim21/personal-pi-extensions 0.0.186 → 0.0.188

package/README.md

@@ -11,6 +11,8 @@
 | [opencode-edit](#opencode-edit)               | 替换内置 edit 工具，使用 opencode 的 schema 和匹配引擎 |
 | [bash-default-timeout](#bash-default-timeout) | 为 bash 工具设置默认超时（180 秒）                     |
 | [vision-agent](#vision-agent)                 | 视觉代理：主模型不支持视觉时，spawn 子 agent 识别图片  |
+| [todowrite](#todowrite)                       | opencode 风格的任务列表工具，完整列表替换语义          |
+| [question](#question)                         | opencode 风格的提问工具，阻塞式询问用户选择            |
 
 ---
 
@@ -169,6 +171,48 @@ pi -e ./src/vision-agent.ts
 
 ---
 
+## todowrite
+
+opencode 风格的任务列表工具，参数与语义和 opencode 的 [`todowrite`](https://github.com/anomalyco/opencode) 工具一致。取代原 `todo-pendant.ts` 的 widget 输出方式，改用 `details.pendant.markdown` 渲染（与 vision-agent 相同的 pendant 约定）。
+
+- **完整列表替换语义**：模型每次调用都传完整的 todo 列表，工具整体替换当前列表
+- **参数**：`todos: Array<{ content, status, priority }>`
+  - `status`：`pending` | `in_progress` | `completed` | `cancelled`
+  - `priority`：`high` | `medium` | `low`
+- **持久化**：列表存进工具结果 `details.todos`，跟随会话分支自动恢复
+- **渲染**：每次调用用完整 markdown 列表输出对应的任务（pendant 面板自动展开）
+
+与 pi 内置 `todo` 工具（`create`/`update`/`list`/… 单条动作）不同，本工具没有单条增删改动作，模型必须每次都传完整列表。
+
+### 使用
+
+```bash
+pi -e ./src/todowrite.ts
+```
+
+---
+
+## question
+
+opencode 风格的提问工具，参数与语义和 opencode 的 [`question`](https://github.com/anomalyco/opencode) 工具一致。阻塞式执行：工具调用挂起，等用户作答后才把答案返回给模型。
+
+- **参数**：`questions: Array<{ question, header, options, multiple? }>`
+  - `options` 每项为 `{ label, description }`
+  - `multiple` 缺省为单选，`true` 时循环用 `ui.select` 逐个勾选直到「✓ Done」
+- **自定义答案**：每个问题自动追加 `Type your own answer.` 选项，选中后走 `ui.input` 自由输入
+- **返回值**：每个问题一个 label 数组（`Answer = string[]`），跳过的为空数组
+- **输出**：与 opencode 一致 —— `User has answered your questions: "q"="a", "q2"="Unanswered"...`
+
+交互全部走 pi 内置的 `ctx.ui.select` / `ctx.ui.input`，不写自定义 TUI 渲染；`option.description` 不显示在对话框里，仅保留在 `details` 中。
+
+### 使用
+
+```bash
+pi -e ./src/question.ts
+```
+
+---
+
 ## 安装
 
 ### 通过 npm/git 包

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trim21/personal-pi-extensions",
-  "version": "0.0.186",
+  "version": "0.0.188",
   "type": "module",
   "description": "Custom pi coding-agent extensions: bwrap sandbox, workspace guard, opencode edit, and more",
   "keywords": [
@@ -64,7 +64,8 @@
       "src/bash-default-timeout.ts",
       "src/gh-readonly.ts",
       "src/spawn-agent.ts",
-      "src/todo-pendant.ts"
+      "src/todowrite.ts",
+      "src/question.ts"
     ]
   },
   "lint-staged": {

package/src/question.ts

@@ -0,0 +1,167 @@
+/**
+ * question —— opencode 风格的提问工具
+ *
+ * 参数与语义和 opencode 的 `question` 工具一致：
+ *   questions 数组，每项含 question / header / options / multiple：
+ *   - options 每项为 label / description
+ *   - 单选（默认）：用户在选项里选一个，也可选「Type your own answer.」自由输入
+ *   - 多选（multiple: true）：循环用 ui.select 逐个勾选，直到「✓ Done」
+ *   - 每个问题返回一个 label 数组（Answer = string[]），跳过的为空数组
+ *   - 输出与 opencode 一致：
+ *     User has answered your questions: "q"="a", "q2"="Unanswered"...
+ *
+ * 交互全部走 pi 内置的 ctx.ui.select / ctx.ui.input，不写自定义 TUI 渲染。
+ * 注意：ui.select 只接受 string 标签，option.description 不显示在对话框里，
+ * 仅保留在 details 中（schema 仍与 opencode 对齐）。
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+// ── constants ────────────────────────────────────────────────────────────────
+
+export const TOOL_NAME = "question";
+/** opencode 会自动追加的自定义答案选项；用户选中后走 ctx.ui.input */
+export const CUSTOM_LABEL = "Type your own answer.";
+/** 多选模式下结束勾选的哨兵选项 */
+export const DONE_LABEL = "✓ Done";
+
+/** 与 opencode question.txt 语义一致的描述 */
+export const QUESTION_DESCRIPTION = [
+  "Use this tool when you need to ask the user questions during execution. This allows you to:",
+  "1. Gather user preferences or requirements",
+  "2. Clarify ambiguous instructions",
+  "3. Get decisions on implementation choices as you work",
+  "4. Offer choices to the user about what direction to take.",
+  "",
+  "Usage notes:",
+  '- A "Type your own answer" option is added automatically; don\'t include "Other" or catch-all options',
+  "- Answers are returned as arrays of labels; set multiple to true to allow selecting more than one",
+  '- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label',
+].join("\n");
+
+// ── types ────────────────────────────────────────────────────────────────────
+
+export interface QuestionOption {
+  label: string;
+  description: string;
+}
+
+/** 与 schema 对齐的输入形状（multiple 可选） */
+export interface QuestionInput {
+  question: string;
+  header: string;
+  options: QuestionOption[];
+  multiple?: boolean;
+}
+
+/** 规整后的问题（multiple 已默认化为 boolean） */
+export interface Question extends Omit<QuestionInput, "multiple"> {
+  multiple: boolean;
+}
+
+/** 每个问题的答案：选中的 label 数组（自定义输入就是单元素的 [text]） */
+export type Answer = string[];
+
+export interface QuestionDetails {
+  questions: Question[];
+  answers: Answer[];
+}
+
+// ── schema（与 opencode 的 Question.Prompt 一致）──────────────────────────────
+
+const optionSchema = Type.Object({
+  label: Type.String({ description: "Display text (concise, 1-5 words)" }),
+  description: Type.String({ description: "Explanation of what this choice means" }),
+});
+
+const questionSchema = Type.Object({
+  question: Type.String({ description: "The complete question to ask" }),
+  header: Type.String({ description: "Very short label (max 30 chars)" }),
+  options: Type.Array(optionSchema, { description: "Available choices" }),
+  multiple: Type.Optional(Type.Boolean({ description: "Allow selecting multiple choices" })),
+});
+
+export const questionParamsSchema = Type.Object({
+  questions: Type.Array(questionSchema, { description: "Questions to ask" }),
+});
+
+// ── 纯函数（可测试）──────────────────────────────────────────────────────────
+
+/** trim 各字段并把可选的 multiple 默认化为 false */
+export function normalizeQuestions(questions: readonly QuestionInput[]): Question[] {
+  return questions.map((q) => ({
+    question: q.question.trim(),
+    header: q.header.trim(),
+    options: q.options.map((o) => ({ label: o.label.trim(), description: o.description.trim() })),
+    multiple: q.multiple === true,
+  }));
+}
+
+/** 与 opencode 一致的输出：每个问题 "q"="a, b"，空答案显示 Unanswered */
+export function formatAnswers(questions: readonly Question[], answers: readonly Answer[]): string {
+  const formatted = questions
+    .map((q, i) => `"${q.question}"="${answers[i]?.length ? answers[i].join(", ") : "Unanswered"}"`)
+    .join(", ");
+  return `User has answered your questions: ${formatted}. You can now continue with the user's answers in mind.`;
+}
+
+function dialogTitle(q: Question): string {
+  return q.header ? `${q.header}: ${q.question}` : q.question;
+}
+
+async function askSingle(q: Question, ctx: ExtensionContext): Promise<Answer> {
+  const title = dialogTitle(q);
+  const options = [...q.options.map((o) => o.label), CUSTOM_LABEL];
+  const choice = await ctx.ui.select(title, options);
+  if (choice === undefined) return [];
+  if (choice === CUSTOM_LABEL) {
+    const typed = await ctx.ui.input(title, "Type your answer…");
+    return typed?.trim() ? [typed.trim()] : [];
+  }
+  return [choice];
+}
+
+async function askMultiple(q: Question, ctx: ExtensionContext): Promise<Answer> {
+  const title = dialogTitle(q);
+  const selected: string[] = [];
+  const remaining = new Set(q.options.map((o) => o.label));
+  while (remaining.size > 0) {
+    const choice = await ctx.ui.select(title, [...remaining, DONE_LABEL]);
+    if (choice === undefined || choice === DONE_LABEL) break;
+    if (!remaining.has(choice)) continue;
+    selected.push(choice);
+    remaining.delete(choice);
+  }
+  return selected;
+}
+
+// ── extension ────────────────────────────────────────────────────────────────
+
+export default function question(pi: ExtensionAPI) {
+  pi.registerTool<typeof questionParamsSchema, QuestionDetails>({
+    name: TOOL_NAME,
+    label: "Question",
+    description: QUESTION_DESCRIPTION,
+    parameters: questionParamsSchema,
+    // 交互式提问不能与其他工具并行弹出，逐个串行执行
+    executionMode: "sequential",
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      if (!ctx.hasUI) {
+        throw new Error("Cannot ask questions: interactive UI is not available in this mode");
+      }
+      const questions = normalizeQuestions(params.questions);
+
+      const answers: Answer[] = [];
+      for (const q of questions) {
+        answers.push(q.multiple ? await askMultiple(q, ctx) : await askSingle(q, ctx));
+      }
+
+      return {
+        content: [{ type: "text", text: formatAnswers(questions, answers) }],
+        details: { questions, answers },
+      };
+    },
+  });
+}

package/src/todowrite.ts

@@ -0,0 +1,164 @@
+/**
+ * todowrite —— opencode 风格的任务列表工具
+ *
+ * 完整列表替换语义（与 opencode 的 todowrite 工具一致）：
+ *   每次调用用给定的 todos 数组整体替换当前任务列表。
+ *   todos 数组，每项含 content / status / priority 三个字段：
+ *   status:   pending | in_progress | completed | cancelled
+ *   priority: high | medium | low
+ *
+ * 状态存在工具结果 details 里（跟随会话分支），同时把任务列表渲染成
+ * pendant.markdown（与 vision-agent 相同的 pendant 约定），每次调用都用
+ * 完整的 markdown 列表输出对应的任务 —— 取代原 todo-pendant.ts 里
+ * setWidget 的 widget 输出方式。
+ *
+ * 与 pi 内置 todo 工具（create/update/list/... 动作）不同，本工具没有
+ * 单条增删改动作 —— 模型每次都要传完整的 todo 列表，语义与 opencode 对齐。
+ */
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+// ── constants ────────────────────────────────────────────────────────────────
+
+export const TOOL_NAME = "todowrite";
+
+export const TODO_STATUSES = ["pending", "in_progress", "completed", "cancelled"] as const;
+export const TODO_PRIORITIES = ["high", "medium", "low"] as const;
+
+export type TodoStatus = (typeof TODO_STATUSES)[number];
+export type TodoPriority = (typeof TODO_PRIORITIES)[number];
+
+/** opencode 的 todowrite 描述（语义等价），补上「整体替换」这一关键规则 */
+export const TODOWRITE_DESCRIPTION = [
+  "Create and maintain a structured task list for the current coding session. Tracks progress, organizes multi-step work, and surfaces status to the user.",
+  "",
+  "This tool REPLACES the entire todo list: pass the full updated list of todos on every call.",
+  "",
+  "## When to use",
+  "Use proactively when:",
+  "- The task requires 3+ distinct steps or actions (not just 3 tool calls for a single conceptual step)",
+  "- The work is non-trivial and benefits from planning",
+  "- The user provides multiple tasks (numbered or comma-separated) or explicitly asks for a todo list",
+  "- New instructions arrive - capture them as todos",
+  "- You start a task - mark it `in_progress` (only one at a time) before working",
+  "- You finish a task - mark it `completed` and add any follow-ups discovered during the work",
+  "",
+  "## When NOT to use",
+  "Skip when:",
+  "- The work is a single, straightforward task (or <3 trivial steps)",
+  "- The request is purely informational or conversational",
+  "- Tracking adds no organizational value",
+  "",
+  "## States",
+  "- `pending` - not started",
+  "- `in_progress` - actively working (exactly ONE at a time)",
+  "- `completed` - finished successfully",
+  "- `cancelled` - no longer needed",
+  "",
+  "## Rules",
+  "- Update status in real time; don't batch completions",
+  "- Mark `completed` only after the required work is actually done, including any required verification. Never based on intent.",
+  "- Keep exactly one `in_progress` while work remains",
+  "- If blocked or partial, keep it `in_progress` and add a follow-up todo describing the blocker",
+  "- Preserve user-provided commands verbatim (flags, args, order)",
+  "- Items should be specific and actionable; break large work into smaller steps",
+].join("\n");
+
+// ── types ────────────────────────────────────────────────────────────────────
+
+export interface TodoInfo {
+  content: string;
+  status: TodoStatus;
+  priority: TodoPriority;
+}
+
+export interface TodoDetails {
+  todos: TodoInfo[];
+  pendant: { markdown: string; expanded: boolean };
+}
+
+// ── schema（与 opencode 的 Parameters 一致）──────────────────────────────────
+
+const todoInfoSchema = Type.Object({
+  content: Type.String({ description: "Brief description of the task" }),
+  status: StringEnum(TODO_STATUSES, {
+    description: "Current status of the task: pending, in_progress, completed, cancelled",
+  }),
+  priority: StringEnum(TODO_PRIORITIES, {
+    description: "Priority level of the task: high, medium, low",
+  }),
+});
+
+export const todowriteSchema = Type.Object({
+  todos: Type.Array(todoInfoSchema, { description: "The updated todo list" }),
+});
+
+// ── 纯函数（可测试）──────────────────────────────────────────────────────────
+
+/** trim content 并返回干净副本；字段类型已由 typebox schema 推断，无需运行时校验 */
+export function normalizeTodos(todos: readonly TodoInfo[]): TodoInfo[] {
+  return todos.map((t) => ({ ...t, content: t.content.trim() }));
+}
+
+/** opencode 返回标题里的计数：未完成（status !== completed）的任务数 */
+export function countOpen(todos: readonly TodoInfo[]): number {
+  return todos.filter((t) => t.status !== "completed").length;
+}
+
+/** 与 opencode 一致的输出：格式化的 JSON 字符串 */
+export function serializeTodos(todos: readonly TodoInfo[]): string {
+  return JSON.stringify(todos, null, 2);
+}
+
+const STATUS_MARK: Record<TodoStatus, string> = {
+  pending: " ",
+  in_progress: ">",
+  completed: "x",
+  cancelled: "-",
+};
+
+/**
+ * 把任务列表整理成 pendant 渲染用的 markdown。
+ * 每个任务一行，与 vision-agent 的 pendant.markdown 约定一致。
+ */
+export function buildTodoMarkdown(todos: readonly TodoInfo[]): string {
+  const lines = ["## Tasks", "", `**${countOpen(todos)} open · ${todos.length} total**`];
+  if (todos.length === 0) {
+    lines.push("", "_No todos_");
+    return lines.join("\n");
+  }
+  lines.push("");
+  for (const t of todos) {
+    lines.push(`- [${STATUS_MARK[t.status]}] ${t.content} \`${t.priority}\``);
+  }
+  return lines.join("\n");
+}
+
+// ── extension ────────────────────────────────────────────────────────────────
+
+export default function todowrite(pi: ExtensionAPI) {
+  pi.registerTool<typeof todowriteSchema, TodoDetails>({
+    name: TOOL_NAME,
+    label: "Todo Write",
+    description: TODOWRITE_DESCRIPTION,
+    parameters: todowriteSchema,
+
+    execute(_toolCallId, params) {
+      // 整体替换（opencode 语义）。
+      // 纯同步逻辑，用 Promise.resolve 满足 execute 的 Promise 返回类型。
+      const todos = normalizeTodos(params.todos);
+      return Promise.resolve({
+        content: [{ type: "text", text: serializeTodos(todos) }],
+        details: {
+          todos,
+          pendant: {
+            markdown: buildTodoMarkdown(todos),
+            expanded: true,
+          },
+        },
+      });
+    },
+  });
+}

package/src/todo-pendant.ts

@@ -1,89 +0,0 @@
-/**
- * Todo Pendant Extension
- *
- * Intercepts `todo` tool results and renders the task list as a widget
- * above the editor in Pendant's UI. Compatible with pi's built-in todo
- * tool's four-status task model (pending / in_progress / completed / deleted).
- *
- * Usage:
- *   pi -e src/todo-pendant.ts
- */
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-// ---------------------------------------------------------------------------
-// Types matching pi's built-in todo tool TaskDetails
-// ---------------------------------------------------------------------------
-
-type TaskStatus = "pending" | "in_progress" | "completed" | "deleted";
-
-interface Task {
-  id: number;
-  subject: string;
-  description?: string;
-  activeForm?: string;
-  status: TaskStatus;
-  blockedBy?: number[];
-  owner?: string;
-  metadata?: Record<string, unknown>;
-}
-
-interface TaskDetails {
-  action: string;
-  params: Record<string, unknown>;
-  tasks: Task[];
-  nextId: number;
-  error?: string;
-}
-
-function isTaskDetails(d: unknown): d is TaskDetails {
-  return typeof d === "object" && d !== null && "tasks" in d && Array.isArray(d.tasks);
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-const STATUS_MARK = {
-  pending: " ",
-  in_progress: " ",
-  deleted: " ",
-  completed: "x",
-} as const;
-
-function formatTaskLine(t: Task): string {
-  const mark = STATUS_MARK[t.status];
-  const form = t.status === "in_progress" && t.activeForm ? ` (${t.activeForm})` : "";
-  let line = `- [${mark}] #${t.id} ${t.subject}${form}`;
-  if (t.blockedBy?.length) {
-    line += ` ⛓ ${t.blockedBy.map((id) => `#${id}`).join(", ")}`;
-  }
-  return line;
-}
-
-// ---------------------------------------------------------------------------
-// Extension
-// ---------------------------------------------------------------------------
-
-export default function todoPendant(pi: ExtensionAPI) {
-  pi.on("tool_result", (event, ctx) => {
-    if (event.toolName !== "todo") return;
-
-    const details = event.details;
-    if (!isTaskDetails(details) || details.tasks.length === 0) {
-      ctx.ui.setWidget("todo-pendant", undefined);
-      return;
-    }
-
-    const visible = details.tasks.filter((t) => t.status !== "deleted");
-    if (visible.length === 0) {
-      ctx.ui.setWidget("todo-pendant", undefined);
-      return;
-    }
-
-    ctx.ui.setWidget(
-      "todo-pendant",
-      visible.map((t) => formatTaskLine(t)),
-    );
-  });
-}