@rol1n/pi-kit 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# pi-kit
 
-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.
+Pi extensions and prompt templates distributed together as **`@rol1n/pi-kit`** and individually as **`@rol1n/<extension>`**. Each extension directory contains its own `index.ts` and `README.md`.
+
+## Install
+
+```sh
+pi install npm:@rol1n/pi-kit
+```
+
+Install from GitHub or a local checkout:
+
+```sh
+pi install https://github.com/RolinShmily/pi-kit
+pi install /absolute/path/to/pi-kit
+```
+
+Update with `pi update npm:@rol1n/pi-kit` or `pi update --extensions`.
+
+## Extensions
+
+| Extension | Purpose | Default in kit | Standalone npm |
+|---|---|---|---|
+| [ask-u-questions](ask-u-questions/README.md) | Interactive single/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` selector | Yes | `@rol1n/image-generate` |
+| [memory-log](memory-log/README.md) | Background observational memory and compaction | Yes | `@rol1n/memory-log` |
+| [model-vision](model-vision/README.md) | Image understanding and OCR tool | No | `@rol1n/model-vision` |
+| [multi-harness](multi-harness/README.md) | Delegate to Pi, Codex, Claude, and OpenCode | Yes | `@rol1n/multi-harness` |
+| [oai-subquota](oai-subquota/README.md) | OpenAI Codex subscription quota monitor | Yes | `@rol1n/oai-subquota` |
+| [prompt-snipaste](prompt-snipaste/README.md) | Select prompt snippets for the next user message (bundles 7 built-in prompts) | Yes | `@rol1n/prompt-snipaste` |
+| [screenshot](screenshot/README.md) | Insert the latest Windows/WSL screenshot path | No | `@rol1n/screenshot` |
+| [srp-theme](srp-theme/README.md) | Prompt preview footer and streaming TPS meter | Yes | `@rol1n/srp-theme` |
+| [subagent](subagent/README.md) | Delegate to asynchronous Pi workers | Yes | `@rol1n/subagent` |
+| [tui-asr](tui-asr/README.md) | Streaming voice dictation via DashScope ASR | Yes | `@rol1n/tui-asr` |
+| [web-reach](web-reach/README.md) | Keyless Exa web search and multi-tier page extraction | Yes | `@rol1n/web-reach` |
+| [windows-wheel-fix](windows-wheel-fix/README.md) | Windows ConPTY/Zellij mouse-wheel reporting fix | Yes (Windows only) | `@rol1n/windows-wheel-fix` |
+
+## Resource selection
+
+The kit exposes 13 extension entrypoints and the 7 prompt templates bundled in [prompt-snipaste/prompts](prompt-snipaste/prompts/). Narrow loaded resources with `pi config` or in `settings.json`:
+
+```json
+{
+  "packages": [
+    {
+      "source": "npm:@rol1n/pi-kit",
+      "extensions": ["**/*.ts", "!tui-asr/**"],
+      "prompts": ["prompt-snipaste/prompts/diagnose-report.md"]
+    }
+  ]
+}
+```
+
+## Build and publish
+
+[kit.config.json](kit.config.json) controls which extensions are bundled into `@rol1n/pi-kit` (`bundle: true`) and inter-extension npm dependencies (`deps`).
+
+```sh
+# Sync package.json from kit.config.json and validate
+npm run manifest
+npm run check
+
+# Stage any extension into dist/<id>
+npm run prepare:extension -- subagent
+
+# Publish all standalone extensions, or the kit, or one extension
+npm run publish:ci -- extensions
+npm run publish:ci -- kit
+npm run publish:ci -- tui-asr
+```
+
+GitHub Actions OIDC Trusted Publishing is configured in [`.github/workflows/publish.yml`](.github/workflows/publish.yml).

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/ask-u-questions/dialog-ui.ts

@@ -0,0 +1,80 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { type EditorTheme, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+export function createEditorTheme(theme: Theme): EditorTheme {
+  return {
+    borderColor: (s) => theme.fg("accent", s),
+    selectList: {
+      selectedPrefix: (t) => theme.fg("accent", t),
+      selectedText: (t) => theme.fg("accent", t),
+      description: (t) => theme.fg("muted", t),
+      scrollInfo: (t) => theme.fg("dim", t),
+      noMatch: (t) => theme.fg("warning", t),
+    },
+  };
+}
+
+export function addWrapped(
+  lines: string[],
+  text: string,
+  width: number,
+  firstIndent = " ",
+  restIndent = firstIndent,
+  styleFn?: (line: string) => string,
+): void {
+  if (!text) return;
+  const paragraphs = text.split(/\r?\n/);
+  for (let pIdx = 0; pIdx < paragraphs.length; pIdx++) {
+    const paragraph = paragraphs[pIdx];
+    if (paragraph.length === 0) {
+      lines.push("");
+      continue;
+    }
+    const isFirstParagraph = pIdx === 0;
+    const currentFirstIndent = isFirstParagraph ? firstIndent : restIndent;
+    const firstWidth = Math.max(1, width - visibleWidth(currentFirstIndent));
+    const restWidth = Math.max(1, width - visibleWidth(restIndent));
+
+    if (firstWidth === restWidth) {
+      const wrapped = wrapTextWithAnsi(paragraph, firstWidth);
+      for (let i = 0; i < wrapped.length; i++) {
+        const indent = isFirstParagraph && i === 0 ? firstIndent : restIndent;
+        const rawLine = wrapped[i];
+        const styled = styleFn ? styleFn(rawLine) : rawLine;
+        lines.push(truncateToWidth(`${indent}${styled}`, width));
+      }
+    } else {
+      const wrapped = wrapTextWithAnsi(paragraph, Math.min(firstWidth, restWidth));
+      for (let i = 0; i < wrapped.length; i++) {
+        const indent = isFirstParagraph && i === 0 ? firstIndent : restIndent;
+        const rawLine = wrapped[i];
+        const styled = styleFn ? styleFn(rawLine) : rawLine;
+        lines.push(truncateToWidth(`${indent}${styled}`, width));
+      }
+    }
+  }
+}
+
+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/ask-u-questions/index.ts

@@ -0,0 +1,92 @@
+/** Interactive questions, serialized through the shared dialog lock. */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+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 { questionRenderers } from "./tool-renderers.ts";
+
+export type { AskOption, TextAnswer, OptionAnswer, OtherAnswer, AskAnswer, AskUserQuestionStatus, AskUserQuestionMode, AskUserQuestionResultDetails } from "./types.ts";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "ask_user_question",
+    label: "Ask User Question",
+    description:
+      "Ask the user a clear question and pause execution until they select an option or provide input. Useful when requirements are ambiguous, user preferences or architectural decisions are needed, or critical operations require explicit user confirmation. Always phrase the question and options in the same language as the conversation context. Ask exactly one focused question per call.",
+    promptSnippet:
+      "Ask the user a question to clarify requirements or gather decisions instead of making assumptions.",
+    promptGuidelines: [
+      "Always phrase the question and options in the same language as the conversation context (e.g. ask in Chinese if conversing in Chinese, ask in English if conversing in English).",
+      "Ask exactly one specific question per tool call.",
+      "If you need input across multiple distinct dimensions, make separate tool calls instead of combining them into one.",
+      "When options are provided, an 'Other (custom input)' choice is automatically available in the user interface.",
+      "Set multiSelect: true only when the user is expected to select multiple choices.",
+      'Put the recommended option first in the list and append "(Recommended)" to its label.',
+      "Prefer using this tool whenever multiple valid implementation paths exist that depend on user preference.",
+    ],
+    parameters: AskUserQuestionParams,
+
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const options = normalizeOptions(params.options);
+      const context = params.details?.trim() || undefined;
+      const mode: AskUserQuestionMode =
+        options.length === 0
+          ? "text"
+          : params.multiSelect
+            ? "multi-select"
+            : "single-select";
+
+      if (signal?.aborted) {
+        return cancelledResult(params.question, mode, context);
+      }
+
+      if (!ctx.hasUI) {
+        return unavailableResult(
+          params.question,
+          mode,
+          "ask_user_question requires an interactive TUI environment",
+          context,
+        );
+      }
+
+      return withUILock(async () => {
+        if (mode === "text") {
+          const editorTitle = context
+            ? `${params.question}\n\n${context}`
+            : params.question;
+          const answer = await ctx.ui.editor(editorTitle);
+          if (answer === undefined) {
+            return cancelledResult(params.question, mode, context);
+          }
+          return buildResult(params.question, context, mode, [
+            { type: "text", label: answer.trim(), value: answer.trim() },
+          ]);
+        }
+
+        if (mode === "single-select") {
+          const answer = await askSingleChoice(ctx, params.question, context, options);
+          if (!answer) {
+            return cancelledResult(params.question, mode, context);
+          }
+          return buildResult(params.question, context, mode, [answer]);
+        }
+
+        const answers = await askMultiChoice(ctx, params.question, context, options);
+        if (!answers) {
+          return cancelledResult(params.question, mode, context);
+        }
+        return buildResult(params.question, context, mode, answers);
+      });
+    },
+
+    ...questionRenderers,
+  });
+}

package/ask-u-questions/multi-choice.ts

@@ -0,0 +1,258 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Editor, Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { getOtherLabel, isChineseContext, sortAnswers, type AskAnswer, type AskOption, type DisplayOption } from "./types.ts";
+import { addWrapped, createEditorTheme } from "./dialog-ui.ts";
+
+export async function askMultiChoice(
+  ctx: ExtensionContext,
+  question: string,
+  context: string | undefined,
+  options: AskOption[],
+): Promise<AskAnswer[] | null> {
+  const isZh = isChineseContext(question, options, context);
+  const otherLabel = getOtherLabel(options, isZh);
+  const choiceItems: DisplayOption[] = options.map((option, index) => ({
+    ...option,
+    id: `option:${index}`,
+    index: index + 1,
+  }));
+  const submitItem: DisplayOption = {
+    id: "submit",
+    label: isZh ? "提交确认" : "Confirm & Submit",
+    value: "__submit__",
+    isSubmit: true,
+  };
+  const allItems: DisplayOption[] = [
+    ...choiceItems,
+    { id: "other", label: otherLabel, value: "__other__", isOther: true },
+    submitItem,
+  ];
+
+  return ctx.ui.custom<AskAnswer[] | null>(
+    (tui, theme, _kb, done: (result: AskAnswer[] | null) => void) => {
+      let optionIndex = 0;
+      let editMode = false;
+      let cachedLines: string[] | undefined;
+      let cachedWidth = -1;
+      let componentFocused = false;
+      const selected = new Map<string, AskAnswer>();
+      const editor = new Editor(tui, createEditorTheme(theme));
+
+      editor.onSubmit = (value) => {
+        const trimmed = value.trim();
+        if (!trimmed) return;
+        selected.set("other", { type: "other", label: trimmed, value: trimmed });
+        editMode = false;
+        editor.focused = false;
+        refresh();
+      };
+
+      function refresh() {
+        cachedLines = undefined;
+        tui.requestRender();
+      }
+
+      function toggleOption(item: DisplayOption) {
+        if (selected.has(item.id)) {
+          selected.delete(item.id);
+        } else {
+          selected.set(item.id, {
+            type: "option",
+            label: item.label,
+            value: item.value,
+            index: item.index!,
+          });
+        }
+        refresh();
+      }
+
+      function handleInput(data: string) {
+        if (editMode) {
+          if (matchesKey(data, Key.escape)) {
+            editMode = false;
+            editor.focused = false;
+            editor.setText(selected.get("other")?.label || "");
+            refresh();
+            return;
+          }
+          editor.handleInput(data);
+          refresh();
+          return;
+        }
+
+        if (matchesKey(data, Key.up)) {
+          optionIndex = Math.max(0, optionIndex - 1);
+          refresh();
+          return;
+        }
+        if (matchesKey(data, Key.down)) {
+          optionIndex = Math.min(allItems.length - 1, optionIndex + 1);
+          refresh();
+          return;
+        }
+
+        const current = allItems[optionIndex];
+        if (matchesKey(data, Key.space)) {
+          if (current.isSubmit) return;
+          if (current.isOther) {
+            if (selected.has("other")) {
+              selected.delete("other");
+              refresh();
+            } else {
+              editMode = true;
+              editor.focused = componentFocused;
+              editor.setText("");
+              refresh();
+            }
+            return;
+          }
+          toggleOption(current);
+          return;
+        }
+
+        if (matchesKey(data, Key.enter)) {
+          if (current.isSubmit) {
+            if (selected.size > 0) {
+              done(sortAnswers(Array.from(selected.values())));
+            }
+            return;
+          }
+          if (current.isOther) {
+            editMode = true;
+            editor.focused = componentFocused;
+            editor.setText(selected.get("other")?.label || "");
+            refresh();
+            return;
+          }
+          toggleOption(current);
+          return;
+        }
+
+        if (matchesKey(data, Key.escape)) {
+          done(null);
+        }
+      }
+
+      function render(width: number): string[] {
+        if (cachedLines && cachedWidth === width) return cachedLines;
+
+        const lines: string[] = [];
+        const add = (text: string) => lines.push(truncateToWidth(text, width));
+
+        add(theme.fg("accent", "─".repeat(width)));
+
+        if (editMode) {
+          addWrapped(lines, question, width, " ", " ", (l) => theme.fg("text", theme.bold(l)));
+          if (context) {
+            addWrapped(lines, context, width, " ", " ", (l) => theme.fg("muted", l));
+          }
+          lines.push("");
+          const header = allItems[optionIndex]?.label || otherLabel;
+          add(theme.fg("accent", ` > ${header}:`));
+          for (const line of editor.render(Math.max(1, width - 4))) {
+            add(`   ${line}`);
+          }
+          lines.push("");
+          const editHint = isZh
+            ? " Enter 保存 • Esc 返回多选"
+            : " Enter to save • Esc to return";
+          add(theme.fg("dim", editHint));
+          add(theme.fg("accent", "─".repeat(width)));
+          cachedLines = lines;
+          cachedWidth = width;
+          return lines;
+        }
+
+        addWrapped(lines, question, width, " ", " ", (l) => theme.fg("text", theme.bold(l)));
+        if (context) {
+          addWrapped(lines, context, width, " ", " ", (l) => theme.fg("muted", l));
+        }
+        lines.push("");
+
+        for (let i = 0; i < allItems.length; i++) {
+          const item = allItems[i];
+          const isFocused = i === optionIndex;
+          const prefix = isFocused ? theme.fg("accent", " > ") : "   ";
+
+          if (item.isSubmit) {
+            const hasSelected = selected.size > 0;
+            const countText = isZh
+              ? `(已选 ${selected.size} 项)`
+              : `(${selected.size} selected)`;
+            const label = hasSelected
+              ? `✓ ${item.label} ${countText}`
+              : `○ ${item.label}`;
+            const styled = isFocused
+              ? theme.bold(theme.fg("accent", label))
+              : theme.fg(hasSelected ? "success" : "dim", label);
+            lines.push(truncateToWidth(`${prefix}${styled}`, width));
+            continue;
+          }
+
+          if (item.isOther) {
+            const other = selected.get("other");
+            const marker = other ? "[x]" : "[ ]";
+            const suffix = other ? ` — ${other.label}` : "";
+            const label = `${marker} ${item.label}${suffix}`;
+            const styled = isFocused
+              ? theme.bold(theme.fg("accent", label))
+              : theme.fg(other ? "success" : "text", label);
+            lines.push(truncateToWidth(`${prefix}${styled}`, width));
+            continue;
+          }
+
+          const checked = selected.has(item.id);
+          const marker = checked ? "[x] " : "[ ] ";
+          const numPrefix = `${item.index}. `;
+          const firstIndent = `${prefix}${checked ? theme.fg("success", marker) : marker}${numPrefix}`;
+          const restIndent = " ".repeat(visibleWidth(firstIndent));
+          const styleLabel = (l: string) => {
+            if (isFocused) return theme.bold(theme.fg("accent", l));
+            if (checked) return theme.fg("success", l);
+            return theme.fg("text", l);
+          };
+
+          addWrapped(lines, item.label, width, firstIndent, restIndent, styleLabel);
+
+          if (item.description) {
+            const descIndent = " ".repeat(visibleWidth(firstIndent));
+            const descStyle = (l: string) => theme.fg("muted", l);
+            addWrapped(lines, item.description, width, descIndent, descIndent, descStyle);
+          }
+        }
+
+        lines.push("");
+        if (selected.size === 0) {
+          const warnText = isZh
+            ? " 请至少选择一项回答后再提交。"
+            : " Please select at least one option before submitting.";
+          add(theme.fg("warning", warnText));
+        }
+        const navHint = isZh
+          ? " ↑↓ 切换 • 空格 勾选 • Enter 编辑/提交 • Esc 取消"
+          : " ↑↓ to navigate • Space to select • Enter to edit/submit • Esc to cancel";
+        add(theme.fg("dim", navHint));
+        add(theme.fg("accent", "─".repeat(width)));
+
+        cachedLines = lines;
+        cachedWidth = width;
+        return lines;
+      }
+
+      return {
+        render,
+        invalidate: () => {
+          cachedLines = undefined;
+        },
+        handleInput,
+        get focused(): boolean {
+          return componentFocused;
+        },
+        set focused(value: boolean) {
+          componentFocused = value;
+          editor.focused = editMode && componentFocused;
+        },
+      };
+    },
+  );
+}