@rol1n/pi-kit 0.0.0-stage → 0.1.0

package/extensions/custom-providers/image/handlers/openrouter.ts

@@ -0,0 +1,185 @@
+/**
+ * OpenRouter image generation over OpenRouter's dedicated Images API (`POST /api/v1/images`).
+ *
+ * This deliberately does NOT reuse Pi's built-in `openrouter-images` api: Pi implements that
+ * on top of chat completions with `modalities: ["image"]`, which carries neither `aspect_ratio`
+ * nor `input_references`. Both are supported here, so `image-generate.ts` calls this handler
+ * directly instead of `ctx.modelRegistry.generateImages()`.
+ * The model list still comes from Pi's registry (`getModelsOfType("image")`) and auth from
+ * `getApiKeyForProvider("openrouter")` -- the same credential Pi's built-in provider uses.
+ */
+import { open } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+import type { GenerateImageContext, GeneratedImageOutput, ImageModelDefinition } from "../types.ts";
+
+const OPENROUTER_IMAGE_ENDPOINT = "https://openrouter.ai/api/v1/images";
+const OPENROUTER_MODELS_ENDPOINT = "https://openrouter.ai/api/v1/images/models";
+const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
+const MAX_REDIRECTS = 5;
+
+const MIME_BY_EXTENSION: Record<string, string | undefined> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".bmp": "image/bmp",
+};
+
+async function fetchRemoteImageBuffer(
+  url: string,
+  signal?: AbortSignal,
+): Promise<{ buffer: Buffer; mimeType: string }> {
+  let currentUrl = url;
+  for (let redirect = 0; redirect <= MAX_REDIRECTS; redirect++) {
+    const parsed = new URL(currentUrl);
+    if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+      throw new Error(`Unsupported URL protocol: ${parsed.protocol}`);
+    }
+
+    const response = await fetch(currentUrl, {
+      redirect: "manual",
+      headers: { Accept: "image/png,image/jpeg,image/webp,image/gif,image/bmp,*/*" },
+      signal,
+    });
+
+    if ([301, 302, 303, 307, 308].includes(response.status)) {
+      const loc = response.headers.get("location");
+      if (!loc) throw new Error(`Redirect missing location header (HTTP ${response.status})`);
+      if (redirect === MAX_REDIRECTS) throw new Error("Too many redirects downloading image");
+      currentUrl = new URL(loc, currentUrl).href;
+      continue;
+    }
+
+    if (!response.ok) {
+      throw new Error(`Failed to download image (HTTP ${response.status})`);
+    }
+
+    const rawMime = response.headers.get("content-type")?.split(";")[0]?.trim().toLowerCase() || "image/png";
+    const arrayBuf = await response.arrayBuffer();
+    if (arrayBuf.byteLength > MAX_IMAGE_BYTES) {
+      throw new Error("Image exceeds maximum allowed size (25 MB)");
+    }
+
+    return { buffer: Buffer.from(arrayBuf), mimeType: rawMime };
+  }
+  throw new Error("Failed to download image: too many redirects");
+}
+
+export async function generateOpenrouterImage(
+  ctx: GenerateImageContext,
+  options: { apiKey: string; signal?: AbortSignal; cwd?: string },
+): Promise<GeneratedImageOutput> {
+  const payload: Record<string, unknown> = {
+    model: ctx.model,
+    prompt: ctx.prompt,
+  };
+
+  if (ctx.aspectRatio) {
+    payload.aspect_ratio = ctx.aspectRatio;
+  }
+
+  if (ctx.image) {
+    const imgRef = ctx.image.trim();
+    if (imgRef.startsWith("http://") || imgRef.startsWith("https://")) {
+      payload.input_references = [{ type: "image_url", image_url: { url: imgRef } }];
+    } else {
+      const localImgPath = resolve(options.cwd || process.cwd(), imgRef);
+      let buf: Buffer;
+      try {
+        const fileHandle = await open(localImgPath, "r");
+        buf = await fileHandle.readFile();
+        await fileHandle.close();
+      } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Reference image not readable at ${localImgPath}: ${reason}`);
+      }
+      const ext = extname(localImgPath).toLowerCase();
+      const mime = MIME_BY_EXTENSION[ext];
+      if (!mime) {
+        throw new Error(`Unsupported reference image type: ${ext || localImgPath}`);
+      }
+      payload.input_references = [
+        {
+          type: "image_url",
+          image_url: { url: `data:${mime};base64,${buf.toString("base64")}` },
+        },
+      ];
+    }
+  }
+
+  const response = await fetch(OPENROUTER_IMAGE_ENDPOINT, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${options.apiKey}`,
+      "Content-Type": "application/json",
+      "HTTP-Referer": "https://pi.dev",
+      "X-Title": "Pi Image Generate Extension",
+    },
+    body: JSON.stringify(payload),
+    signal: options.signal,
+  });
+
+  if (!response.ok) {
+    const errText = await response.text();
+    throw new Error(`OpenRouter image request failed (HTTP ${response.status}): ${errText.slice(0, 400)}`);
+  }
+
+  const data = (await response.json()) as {
+    data?: Array<{ b64_json?: string; url?: string; revised_prompt?: string }>;
+  };
+
+  const item = data.data?.[0];
+  if (!item) {
+    throw new Error("OpenRouter returned an empty image list.");
+  }
+
+  let imgBuffer: Buffer;
+  let mimeType = "image/png";
+
+  if (item.b64_json) {
+    imgBuffer = Buffer.from(item.b64_json, "base64");
+  } else if (item.url) {
+    const downloaded = await fetchRemoteImageBuffer(item.url, options.signal);
+    imgBuffer = downloaded.buffer;
+    mimeType = downloaded.mimeType;
+  } else {
+    throw new Error("OpenRouter response did not contain image data or URL.");
+  }
+
+  return {
+    buffer: imgBuffer,
+    mimeType,
+    model: ctx.model,
+    provider: "openrouter",
+    revisedPrompt: item.revised_prompt,
+  };
+}
+
+export async function fetchOpenrouterCatalog(signal?: AbortSignal): Promise<ImageModelDefinition[]> {
+  const list: ImageModelDefinition[] = [];
+  try {
+    const timeoutSig = AbortSignal.any([AbortSignal.timeout(4000), ...(signal ? [signal] : [])]);
+    const resp = await fetch(OPENROUTER_MODELS_ENDPOINT, {
+      signal: timeoutSig,
+      headers: { Accept: "application/json" },
+    });
+    if (resp.ok) {
+      const data = (await resp.json()) as { data?: Array<{ id?: string; name?: string; description?: string }> };
+      if (Array.isArray(data?.data)) {
+        for (const item of data.data) {
+          if (!item?.id || typeof item.id !== "string") continue;
+          const id = item.id.trim();
+          const name = typeof item.name === "string" ? item.name.trim() : id;
+          const desc =
+            typeof item.description === "string" && item.description.trim()
+              ? item.description.trim().replace(/\s+/g, " ").slice(0, 60) + "..."
+              : "OpenRouter Image Model";
+
+          list.push({ id, name, provider: "openrouter", description: desc });
+        }
+      }
+    }
+  } catch {}
+  return list;
+}

package/extensions/custom-providers/image/index.ts

@@ -0,0 +1,96 @@
+import type { ModalityProvidersRecord } from "../types.ts";
+import {
+  DASHSCOPE_IMAGE_URL,
+  DASHSCOPE_IMAGE_MODELS,
+  resolveImageModel,
+  toImageModelDefinition,
+} from "./models.ts";
+import { generateDashscopeImages, generateDashscopeImage } from "./handlers/dashscope.ts";
+import { generateOpenrouterImage, fetchOpenrouterCatalog } from "./handlers/openrouter.ts";
+import type { GenerateImageContext, GeneratedImageOutput, ImageModelDefinition } from "./types.ts";
+
+export * from "./types.ts";
+export * from "./models.ts";
+export * from "./handlers/dashscope.ts";
+export * from "./handlers/openrouter.ts";
+
+/** Minimal shape of a Pi registry image model. */
+export type RegistryImageModel = { id: string; name?: string; provider: string };
+
+/**
+ * Only DashScope is registered here.
+ *
+ * `openrouter` must NOT be registered: `pi.registerProvider()` with a `models` list
+ * replaces that provider's entire built-in catalog (chat included). Pi already ships
+ * the OpenRouter image models natively under the same provider + credential.
+ */
+export const imageProviders: ModalityProvidersRecord = {
+  dashscope: {
+    name: "Aliyun DashScope",
+    models: DASHSCOPE_IMAGE_MODELS.map((m) => ({
+      type: "image",
+      id: m.id,
+      name: m.name,
+      api: "dashscope-images",
+      baseUrl: DASHSCOPE_IMAGE_URL,
+      input: ["text", "image"],
+      output: ["image"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    })),
+    images: {
+      "dashscope-images": {
+        generateImages: generateDashscopeImages as any,
+      },
+    },
+  },
+};
+
+/**
+ * Build the catalog shown by the model selector.
+ *
+ * Sources, in priority order: the provider registry (`ctx.modelRegistry.getModelsOfType("image")`,
+ * which already covers both OpenRouter's built-in catalog and the DashScope registration above),
+ * followed by the live OpenRouter catalog for models newer than the bundled snapshot.
+ */
+export async function fetchAllAvailableImageModels(
+  registryModels: readonly RegistryImageModel[] = [],
+  signal?: AbortSignal,
+): Promise<ImageModelDefinition[]> {
+  const map = new Map<string, ImageModelDefinition>();
+  const add = (model: ImageModelDefinition) => {
+    const key = model.id.toLowerCase();
+    if (!map.has(key)) map.set(key, model);
+  };
+
+  for (const model of DASHSCOPE_IMAGE_MODELS) add(model);
+  for (const model of registryModels) add(toImageModelDefinition(model));
+  for (const model of await fetchOpenrouterCatalog(signal)) add(model);
+
+  return Array.from(map.values());
+}
+
+export async function generateImage(
+  ctx: GenerateImageContext,
+  options: {
+    apiKey: string;
+    provider?: string;
+    baseUrl?: string;
+    signal?: AbortSignal;
+    cwd?: string;
+  },
+): Promise<GeneratedImageOutput> {
+  const model = resolveImageModel(ctx.model);
+  const provider = options.provider ?? (model.startsWith("qwen-image") ? "dashscope" : "openrouter");
+
+  if (provider === "dashscope") {
+    return generateDashscopeImage(
+      { prompt: ctx.prompt, model, aspectRatio: ctx.aspectRatio, image: ctx.image },
+      { apiKey: options.apiKey, baseUrl: options.baseUrl || DASHSCOPE_IMAGE_URL, cwd: options.cwd, signal: options.signal },
+    );
+  }
+
+  return generateOpenrouterImage(
+    { ...ctx, model },
+    { apiKey: options.apiKey, signal: options.signal, cwd: options.cwd },
+  );
+}

package/extensions/custom-providers/image/models.ts

@@ -0,0 +1,71 @@
+import type { ImageModelDefinition } from "./types.ts";
+
+export const DASHSCOPE_IMAGE_URL =
+  process.env.DASHSCOPE_IMAGE_URL?.trim().replace(/\/+$/, "") ||
+  "https://dashscope.aliyuncs.com/api/v1";
+
+/**
+ * DashScope is not a Pi built-in image provider, so its catalog is declared here
+ * and registered through `imageProviders`.
+ *
+ * OpenRouter is deliberately absent: Pi already ships its image catalog (61 models)
+ * under its built-in `openrouter` provider, using the same `/login openrouter` credential.
+ */
+export const DASHSCOPE_IMAGE_MODELS: ImageModelDefinition[] = [
+  {
+    id: "qwen-image-3.0-pro",
+    name: "Qwen Image 3.0 Pro",
+    provider: "dashscope",
+    description: "Aliyun DashScope flagship image generation model with strong typography and rendering capabilities",
+  },
+];
+
+/** Project a Pi registry image model into the selector's view model. */
+export function toImageModelDefinition(model: {
+  id: string;
+  name?: string;
+  provider: string;
+}): ImageModelDefinition {
+  return {
+    id: model.id,
+    name: model.name?.trim() || model.id,
+    provider: model.provider,
+    description: `${model.provider} image model`,
+  };
+}
+
+/**
+ * Resolve a user-supplied model argument against the provider registry.
+ *
+ * The registry is the single source of truth, so no hand-written alias table is kept:
+ * OpenRouter's catalog belongs to Pi and changes without notice, and a stale alias would
+ * silently return a model id that no longer exists.
+ *
+ * Order: exact id -> exact display name -> substring (shortest match wins, so `gpt-image-1`
+ * prefers `openai/gpt-image-1` over `openai/gpt-image-1-mini`). Anything unresolved is
+ * returned verbatim so the provider reports the real error.
+ */
+export function resolveImageModel(
+  model?: string,
+  availableModels?: readonly ImageModelDefinition[],
+  defaultModel = "google/gemini-3.1-flash-image",
+): string {
+  const trimmed = model?.trim() ?? "";
+  if (!trimmed) return defaultModel;
+  if (!availableModels?.length) return trimmed;
+
+  const lower = trimmed.toLowerCase();
+
+  const exact = availableModels.find((m) => m.id.toLowerCase() === lower);
+  if (exact) return exact.id;
+
+  const byName = availableModels.find((m) => m.name.toLowerCase() === lower);
+  if (byName) return byName.id;
+
+  const partial = availableModels
+    .filter((m) => m.id.toLowerCase().includes(lower))
+    .sort((a, b) => a.id.length - b.id.length);
+  if (partial.length) return partial[0].id;
+
+  return trimmed;
+}

package/extensions/custom-providers/image/types.ts

@@ -0,0 +1,22 @@
+export interface ImageModelDefinition {
+  id: string;
+  name: string;
+  provider: "openrouter" | "dashscope" | string;
+  description: string;
+}
+
+export interface GenerateImageContext {
+  prompt: string;
+  model: string;
+  aspectRatio?: string;
+  image?: string; // local file path or remote image url
+  cwd?: string;
+}
+
+export interface GeneratedImageOutput {
+  buffer: Buffer;
+  mimeType: string;
+  model: string;
+  provider: string;
+  revisedPrompt?: string;
+}

package/extensions/custom-providers/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Register custom providers through Pi's native model and /login APIs.
+ * Organizes models and providers by Pi's core model types: chat, image, classifier, and asr.
+ * Credentials belong in Pi's auth.json, not here.
+ */
+
+import type { ExtensionAPI, ProviderConfig } from "@earendil-works/pi-coding-agent";
+import { chatProviders } from "./chat/index.ts";
+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 default function customProviders(pi: ExtensionAPI): void {
+  const providerIds = new Set<string>([
+    ...Object.keys(chatProviders),
+    ...Object.keys(imageProviders),
+    ...Object.keys(classifierProviders),
+    ...Object.keys(asrProviders),
+  ]);
+
+  for (const id of providerIds) {
+    const chat = chatProviders[id];
+    const image = imageProviders[id];
+    const classifier = classifierProviders[id];
+    const asr = asrProviders[id];
+
+    const config: ProviderConfig = {
+      name: chat?.name ?? image?.name ?? classifier?.name ?? asr?.name ?? id,
+      baseUrl: chat?.baseUrl ?? image?.baseUrl ?? classifier?.baseUrl,
+      api: (chat?.api ?? "openai-completions") as any,
+      ...(chat?.apiKey ? { apiKey: chat.apiKey } : {}),
+      ...(chat?.refreshModels ? { refreshModels: chat.refreshModels } : {}),
+      models: [
+        ...(chat?.models ?? []),
+        ...(image?.models ?? []),
+        ...(classifier?.models ?? []),
+      ],
+      ...(image?.images || chat?.images || classifier?.images
+        ? { images: { ...chat?.images, ...image?.images, ...classifier?.images } }
+        : {}),
+      ...(classifier?.classifiers || chat?.classifiers || image?.classifiers
+        ? { classifiers: { ...chat?.classifiers, ...image?.classifiers, ...classifier?.classifiers } }
+        : {}),
+    };
+
+    pi.registerProvider(id, config);
+  }
+}

package/extensions/custom-providers/types.ts

@@ -0,0 +1,17 @@
+import type { ProviderConfig } from "@earendil-works/pi-coding-agent";
+import type { AsrModelDefinition } from "./asr/models.ts";
+
+export interface ModalityProviderConfig {
+  name?: string;
+  baseUrl?: string;
+  api?: string;
+  apiKey?: ProviderConfig["apiKey"];
+  headers?: Record<string, string>;
+  models?: Record<string, unknown>[];
+  refreshModels?: ProviderConfig["refreshModels"];
+  images?: ProviderConfig["images"];
+  classifiers?: ProviderConfig["classifiers"];
+  asr?: AsrModelDefinition[];
+}
+
+export type ModalityProvidersRecord = Record<string, ModalityProviderConfig>;

package/extensions/image-generate/README.md

@@ -0,0 +1,29 @@
+# image-generate
+
+Generate images through OpenRouter or DashScope and save them to the current project. Registers `image_generate` and the `/image-generate` model selector.
+
+## Install
+
+```sh
+pi install npm:@rol1n/image-generate
+```
+
+Also included in `@rol1n/pi-kit`. The extension entrypoint is `extensions/image-generate/index.ts`; model lookup, the selector UI, and image persistence live in `models.ts`, `model-selector.ts`, and `files.ts` beside it.
+
+## Use
+
+`/image-generate model` opens the searchable selector; `/image-generate model qwen-image-3.0-pro` selects a named model for the current session.
+
+```json
+{
+  "prompt": "A clear technical illustration of a terminal workflow",
+  "aspectRatio": "16:9",
+  "model": "google/gemini-3.1-flash-image"
+}
+```
+
+The `image_generate` tool also accepts `image` as a local path or remote reference URL where the selected provider supports reference images. The default model is `google/gemini-3.1-flash-image`. Outputs are saved under `.pi/generated-images/` relative to the working directory and the tool returns the saved path.
+
+## Authentication and providers
+
+Use `/login openrouter` or `/login dashscope`, or the corresponding `OPENROUTER_API_KEY` / `DASHSCOPE_API_KEY` environment variable. DashScope registry entries are supplied by [custom-providers](https://github.com/RolinShmily/pi-kit/tree/main/extensions/custom-providers). Helper adapters ship with this package, but copying helpers does not register that extension. Generation requests use the selected provider's account and pricing.

package/extensions/image-generate/files.ts

@@ -0,0 +1,49 @@
+import { existsSync } from "node:fs";
+import { mkdir, open, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+
+const DEFAULT_OUTPUT_DIR = ".pi/generated-images";
+
+function detectExtension(mimeType: string): string {
+  switch (mimeType) {
+    case "image/jpeg":
+    case "image/jpg":
+      return ".jpg";
+    case "image/webp":
+      return ".webp";
+    case "image/gif":
+      return ".gif";
+    case "image/bmp":
+      return ".bmp";
+    default:
+      return ".png";
+  }
+}
+
+export async function saveImageAtomically(cwd: string, buffer: Buffer, mimeType: string): Promise<string> {
+  const outputDir = resolve(cwd, DEFAULT_OUTPUT_DIR);
+  if (!existsSync(outputDir)) {
+    await mkdir(outputDir, { recursive: true });
+  }
+
+  const date = new Date().toISOString().replace(/T/, "-").replace(/:/g, "").slice(0, 15);
+  const ext = detectExtension(mimeType);
+
+  for (let i = 1; i <= 999; i++) {
+    const filename = `${date}-${String(i).padStart(3, "0")}${ext}`;
+    const targetPath = join(outputDir, filename);
+    try {
+      const handle = await open(targetPath, "wx");
+      await handle.writeFile(buffer);
+      await handle.close();
+      return targetPath;
+    } catch (err: any) {
+      if (err?.code === "EEXIST") continue;
+      throw err;
+    }
+  }
+
+  const fallback = join(outputDir, `${date}-${Date.now()}${ext}`);
+  await writeFile(fallback, buffer);
+  return fallback;
+}