@rol1n/pi-kit 0.1.0 → 0.1.1

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+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
 
@@ -8,92 +8,67 @@ Pi extensions and prompt templates, published together as **`@rol1n/pi-kit`** or
 pi install npm:@rol1n/pi-kit
 ```
 
-Install from GitHub or a local checkout during development:
+Install from GitHub or a local checkout:
 
 ```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 with `pi update npm:@rol1n/pi-kit` or `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
-```
-
-UI, transport, parsing, and storage helpers live beside the entrypoint as needed. Small extensions can remain a single cohesive `index.ts`.
+| 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 currently exposes 13 extension entrypoints and the seven templates in [prompts](prompts/). Personal skills, provider credentials, MCP servers, and keybindings remain normal Pi configuration.
-
-Use `pi config` or narrow package resources in personal/project settings:
+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": ["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.
-
 ## Build and publish
 
-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:
+[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
-npm pack --dry-run --ignore-scripts
-npm publish --access public
-```
 
-Prepare an independent release from the same source:
+# Stage any extension into dist/<id>
+npm run prepare:extension -- subagent
 
-```sh
-npm run prepare:extension -- memory-log
-cd dist/extensions/memory-log
-npm pack --dry-run --ignore-scripts
-npm publish --access public
+# 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
 ```
 
-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.
-
-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
-
-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).
+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/{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),
+  };
+}

package/continue-signal/README.md

@@ -0,0 +1,20 @@
+# continue-signal
+
+Resume an idle Pi agent with a visible continuation signal.
+
+## Install
+
+```sh
+pi install npm:@rol1n/continue-signal
+```
+
+Also included in `@rol1n/pi-kit`.
+
+## Commands and shortcuts
+
+| Action | Trigger |
+|---|---|
+| Resume unfinished work | `/continue` or `Alt+C` |
+| Resume with custom instruction | `/continue Review the remaining test failures` |
+
+An explicit command argument takes priority; otherwise the current editor draft is consumed, falling back to a default resume prompt.

package/{extensions/continue-signal → continue-signal}/index.ts

@@ -3,13 +3,31 @@
  * Uses the editor draft when no prompt is supplied.
  */
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Key } from "@earendil-works/pi-tui";
-import { renderContinueSignal } from "./renderer.ts";
+import type { ExtensionAPI, ExtensionContext, MessageRenderer } from "@earendil-works/pi-coding-agent";
+import { Box, Key, Text } from "@earendil-works/pi-tui";
 
 const DEFAULT_PROMPT = "Review the conversation context and resume any unfinished work from where it stopped.";
 const CUSTOM_TYPE = "continue-signal";
 
+const renderContinueSignal: MessageRenderer<{ timestamp?: number }> = (
+  message,
+  { expanded, outputPad },
+  theme,
+) => {
+  const time = new Date(message.details?.timestamp ?? Date.now()).toLocaleTimeString();
+  const title = `${theme.bold(theme.fg("accent", "⚡ LOOP RESUME SIGNAL"))} ${theme.fg("muted", `[${time}]` )}`;
+
+  const box = new Box(outputPad, 1, (text) => theme.bg("customMessageBg", text));
+  box.addChild(new Text(title, 0, 0));
+  box.addChild(new Text(theme.fg("text", "Re-linking conversation context & resuming agent loop..."), 0, 0));
+
+  if (expanded && message.content) {
+    box.addChild(new Text(theme.fg("dim", `Prompt: ${message.content}`), 0, 0));
+  }
+
+  return box;
+};
+
 export default function (pi: ExtensionAPI) {
   pi.registerMessageRenderer(CUSTOM_TYPE, renderContinueSignal);
 

package/custom-providers/README.md

@@ -0,0 +1,20 @@
+# custom-providers
+
+Registers additional model providers through Pi's native model registry and `/login` interface.
+
+## Install
+
+```sh
+pi install npm:@rol1n/custom-providers
+```
+
+Also included in `@rol1n/pi-kit`.
+
+## Providers
+
+| Provider | Configuration |
+|---|---|
+| Magpie | `MAGPIE_BASE_URL` (default `http://127.0.0.1:3425/v1`); authenticate via `MAGPIE_GATEWAY_KEY` or `/login magpie` |
+| SHUAI API | Authenticate via `/login shuaiapi` |
+| BigModel | Authenticate via `/login bigmodel` |
+| DashScope | Authenticate via `/login dashscope`; `DASHSCOPE_IMAGE_URL` overrides the image API base URL |

package/{extensions/custom-providers → custom-providers}/index.ts

@@ -10,9 +10,19 @@ import { imageProviders } from "./image/index.ts";
 import { classifierProviders } from "./classifier/index.ts";
 import { asrProviders } from "./asr/index.ts";
 
-export { asrProviders, ALL_ASR_MODELS } from "./asr/index.ts";
+export { asrProviders, ALL_ASR_MODELS, createAsrProvider, type AsrModelDefinition, type StreamingAsrProvider } from "./asr/index.ts";
+export { imageProviders, fetchAllAvailableImageModels, generateImage, resolveImageModel, type ImageModelDefinition } from "./image/index.ts";
+
+const BATCH_LOCK_KEY = "__piCustomProvidersBatchLock";
+
+export function ensureCustomProviders(pi: ExtensionAPI): void {
+  const g = globalThis as Record<string, unknown>;
+  if (g[BATCH_LOCK_KEY]) return;
+  g[BATCH_LOCK_KEY] = true;
+  setTimeout(() => {
+    g[BATCH_LOCK_KEY] = false;
+  }, 0).unref?.();
 
-export default function customProviders(pi: ExtensionAPI): void {
   const providerIds = new Set<string>([
     ...Object.keys(chatProviders),
     ...Object.keys(imageProviders),
@@ -48,3 +58,7 @@ export default function customProviders(pi: ExtensionAPI): void {
     pi.registerProvider(id, config);
   }
 }
+
+export default function customProviders(pi: ExtensionAPI): void {
+  ensureCustomProviders(pi);
+}

package/image-generate/README.md

@@ -0,0 +1,25 @@
+# image-generate
+
+Generate images through OpenRouter or DashScope and save them to `.pi/generated-images/` in the current project. Registers the `image_generate` tool and `/image-generate` model selector.
+
+## Install
+
+```sh
+pi install npm:@rol1n/image-generate
+```
+
+Also included in `@rol1n/pi-kit`. Installing this package automatically installs `@rol1n/custom-providers`.
+
+## Use
+
+Run `/image-generate model` to open the interactive model picker, or `/image-generate model qwen-image-3.0-pro` to switch directly.
+
+```json
+{
+  "prompt": "A clean technical diagram of a terminal workflow",
+  "aspectRatio": "16:9",
+  "model": "google/gemini-3.1-flash-image"
+}
+```
+
+Authenticate via `/login openrouter` or `/login dashscope` (or `OPENROUTER_API_KEY` / `DASHSCOPE_API_KEY`).

package/{extensions/image-generate → image-generate}/index.ts

@@ -12,13 +12,32 @@ import { Text, type AutocompleteItem } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 import {
+  ensureCustomProviders,
   fetchAllAvailableImageModels,
   generateImage,
   resolveImageModel,
   type ImageModelDefinition,
-} from "../custom-providers/image/index.ts";
+} from "../custom-providers/index.ts";
 import { saveImageAtomically } from "./files.ts";
-import { DEFAULT_MODEL, registryImageModels, resolveProviderId } from "./models.ts";
+/** Image catalog lookup and provider selection. */
+
+export const DEFAULT_MODEL = "google/gemini-3.1-flash-image";
+
+/** Image models known to Pi: OpenRouter's built-in catalog plus our DashScope registration. */
+export function registryImageModels(ctx: { modelRegistry: { getModelsOfType(type: string): readonly any[] } }) {
+  return ctx.modelRegistry.getModelsOfType("image") as readonly { id: string; name?: string; provider: string }[];
+}
+
+/** Resolve which provider owns a model id, preferring the Pi registry over heuristics. */
+export function resolveProviderId(
+  ctx: { modelRegistry: { getModelsOfType(type: string): readonly any[] } },
+  modelId: string,
+): string {
+  const lower = modelId.toLowerCase();
+  const known = registryImageModels(ctx).find((m) => m.id.toLowerCase() === lower);
+  if (known) return known.provider;
+  return lower.startsWith("qwen-image") ? "dashscope" : "openrouter";
+}
 import { SearchableImageModelSelectorComponent } from "./model-selector.ts";
 
 const DEFAULT_TIMEOUT_MS = 120_000;
@@ -28,6 +47,7 @@ let currentModel = DEFAULT_MODEL;
 // ============================ Extension Entrypoint ============================
 
 export default function imageGenerate(pi: ExtensionAPI): void {
+  ensureCustomProviders(pi);
   // 1. Slash command: /image-generate model [name]
   pi.registerCommand("image-generate", {
     description: "Switch default image generation model (/image-generate model [name])",

package/{extensions/image-generate → image-generate}/model-selector.ts

@@ -1,5 +1,5 @@
 import { Container, Input, Spacer, Text, fuzzyFilter, getKeybindings } from "@earendil-works/pi-tui";
-import type { ImageModelDefinition } from "../custom-providers/image/index.ts";
+import type { ImageModelDefinition } from "../custom-providers/index.ts";
 
 export class SearchableImageModelSelectorComponent extends Container {
   private searchInput: Input;

package/model-vision/README.md

@@ -0,0 +1,22 @@
+# model-vision
+
+Analyze a local image or public HTTP(S) image URL with a vision model. Registers the `model_vision` tool for OCR, UI inspection, and visual Q&A.
+
+## Install
+
+```sh
+pi install npm:@rol1n/model-vision
+```
+
+Available as a standalone package (not enabled in `@rol1n/pi-kit` by default).
+
+## Use
+
+```json
+{
+  "image": "./screenshots/error.png",
+  "prompt": "Read the error message and describe the relevant UI."
+}
+```
+
+Supports PNG, JPEG, WebP, GIF, and BMP up to 10 MiB. Private/local network URLs are blocked. Default model fallback chain is configured in `DEFAULT_VISION_MODELS` in `index.ts`.