@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/image/skills/image/SKILL.md

@@ -1,76 +0,0 @@
----
-name: image
-description: Generate images from text prompts and analyze images with vision models
----
-
-# Image Tools
-
-Two agent tools: `image_generate` creates images from a text prompt, and
-`image_recognize` analyzes an existing image.
-
-## image_generate
-
-```
-image_generate(prompt: "A cutaway diagram of a submarine, technical illustration, muted blues")
-image_generate(prompt: "...", model: "flux.2-pro")
-```
-
-- `prompt` (required) — describe subject, style, composition and lighting.
-  Detail materially improves the result.
-- `model` (optional) — fuzzy-matched against the image catalog
-  (`flux`, `gemini-3-pro-image`, `recraft-v4`, …). Omit to use the model
-  configured in `/unipi:settings`.
-
-The image is returned inline and, when `saveToDisk` is on (the default),
-written to the output directory (default `~/.unipi/images`). The saved path is
-reported in the result.
-
-**Image generation costs money per call.** Never regenerate an image
-speculatively — only when the user asks for a change.
-
-Models are served through OpenRouter, so an OpenRouter key is required:
-https://openrouter.ai/keys
-
-## image_recognize
-
-```
-image_recognize(image: "./screenshot.png")
-image_recognize(image: "./error.png", prompt: "What does the stack trace say?")
-image_recognize(image: "...", model: "claude-sonnet", systemPrompt: "Reply only with the visible text.")
-```
-
-- `image` (required) — a local file path, a `data:` URL, or raw base64.
-  **Prefer a file path**: inlining base64 into the conversation is far more
-  expensive. Remote URLs are not fetched — download first.
-- `prompt` (optional) — the question to ask. Defaults to a general
-  description. A specific question gives a far more useful answer.
-- `model` (optional) — must accept image input. Omit to use the configured
-  model, falling back to the session's current model.
-- `systemPrompt` (optional) — override the configured system prompt for one
-  call.
-
-Supported types: PNG, JPEG, GIF, WebP. The type is detected from the file's
-magic numbers, so a misnamed extension still works.
-
-### When to use it
-
-- Reading a screenshot of an error, a stack trace, or failing UI
-- Understanding a design mockup or wireframe before implementing it
-- Extracting content from an architecture diagram or flowchart
-- Checking what a rendered page or chart actually looks like
-
-## Configuration
-
-`/unipi:settings` configures both tools:
-
-- Generation model (picker over the built-in catalog plus image models from
-  any provider registered by another extension)
-- Recognition model (picker over vision-capable models only)
-- Either picker accepts a **custom** `provider/model-id` — press `c` — for a
-  model the catalog does not list
-- Enable/disable either tool
-- Output directory and whether to save to disk
-- The recognition system prompt
-
-Config lives at `~/.unipi/config/image/config.json`. Toggling a tool on or off
-takes effect on the next session, since tools are registered at startup.

package/packages/image/src/generate.ts

@@ -1,256 +0,0 @@
-/**
- * @pi-unipi/image — Image generation
- *
- * Wraps pi-ai's image API. `generateImages` never rejects — failures come back
- * as `stopReason: "error"` — so every call site must inspect the result rather
- * than relying on try/catch.
- */
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-import { getImagesModels, type ImageGenModel, type ImagesModelsLike } from "./models.js";
-
-export interface GeneratedImage {
-  /** Base64 image data. */
-  data: string;
-  mimeType: string;
-  /** Absolute path, when saved to disk. */
-  path?: string;
-}
-
-export interface GenerateResult {
-  images: GeneratedImage[];
-  /** Any accompanying commentary from the model. */
-  text: string;
-  model: string;
-  provider: string;
-}
-
-/** Structural view of pi-ai's AssistantImages. */
-interface AssistantImagesLike {
-  output?: Array<{ type?: string; text?: string; data?: string; mimeType?: string }>;
-  stopReason?: string;
-  errorMessage?: string;
-  usage?: unknown;
-}
-
-/** Injectable generation function, for tests. */
-export type GenerateImagesFn = (
-  model: unknown,
-  context: { input: Array<{ type: string; text?: string }> },
-  options: { apiKey?: string; signal?: AbortSignal },
-) => Promise<AssistantImagesLike>;
-
-/** Extension for a media type, for naming saved files. */
-function extensionFor(mimeType: string): string {
-  switch (mimeType) {
-    case "image/png":
-      return ".png";
-    case "image/jpeg":
-      return ".jpg";
-    case "image/webp":
-      return ".webp";
-    case "image/gif":
-      return ".gif";
-    case "image/svg+xml":
-      return ".svg";
-    default:
-      return ".img";
-  }
-}
-
-/** Filesystem-safe slug from a prompt, for a recognizable filename. */
-export function slugify(prompt: string, maxLength = 40): string {
-  const slug = prompt
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, maxLength)
-    .replace(/-+$/g, "");
-  return slug || "image";
-}
-
-/** Build a collision-free filename. */
-export function buildFileName(
-  prompt: string,
-  mimeType: string,
-  index: number,
-  now: Date = new Date(),
-): string {
-  const stamp = now.toISOString().replace(/[:.]/g, "-").replace("T", "_").slice(0, 19);
-  const suffix = index > 0 ? `-${index + 1}` : "";
-  return `${stamp}-${slugify(prompt)}${suffix}${extensionFor(mimeType)}`;
-}
-
-/**
- * Write an image to disk.
- * @returns the absolute path, or undefined if the write failed (never throws —
- * a failed save must not discard a successfully generated image).
- */
-export function saveImage(
-  outputDir: string,
-  fileName: string,
-  base64: string,
-): string | undefined {
-  try {
-    fs.mkdirSync(outputDir, { recursive: true });
-    const target = path.join(outputDir, fileName);
-    fs.writeFileSync(target, Buffer.from(base64, "base64"));
-    return target;
-  } catch {
-    return undefined;
-  }
-}
-
-/** Providers pi-ai's images collection can actually generate with. */
-function supportedProviders(imagesApi: ImagesModelsLike): string[] {
-  try {
-    return [...new Set(imagesApi.getModels().map((m) => m.provider))];
-  } catch {
-    return [];
-  }
-}
-
-/**
- * Whether generation can route to a provider. Unknown/empty catalogs are
- * treated as capable so a stubbed or future pi-ai is never blocked by this
- * check — the real call still reports its own error.
- */
-function providerCanGenerate(imagesApi: ImagesModelsLike, provider: string): boolean {
-  const providers = supportedProviders(imagesApi);
-  if (providers.length === 0) return true;
-  return providers.includes(provider);
-}
-
-export interface GenerateOptions {
-  prompt: string;
-  model: ImageGenModel;
-  /** Fallback key, used only when pi-ai's own auth resolution comes up empty. */
-  apiKey?: string;
-  signal?: AbortSignal;
-  /** Absolute directory for saved images; omit to skip saving. */
-  outputDir?: string;
-  /** Source image; when set the request is an edit rather than a generation. */
-  inputImage?: { data: string; mimeType: string };
-  now?: Date;
-  /** Injected images collection, for tests. */
-  images?: ImagesModelsLike;
-}
-
-/**
- * Generate images and optionally save them.
- * @throws {Error} with an actionable message when generation fails.
- */
-export async function generateImage(options: GenerateOptions): Promise<GenerateResult> {
-  const { prompt, model, signal, outputDir, now, inputImage } = options;
-
-  if (!prompt.trim()) {
-    throw new Error("A non-empty prompt is required.");
-  }
-
-  const imagesApi = options.images ?? (await getImagesModels());
-  if (!imagesApi) {
-    throw new Error(
-      "Image generation is unavailable — this version of pi-ai does not expose an image API.",
-    );
-  }
-
-  // pi-ai's images collection has its own provider set, separate from pi's
-  // chat registry. `registerRegistryImageProviders()` bridges pi's providers
-  // in, but a model may still name a provider with no image route at all —
-  // pi-ai would answer with a bare "Unknown provider: x", so say something
-  // useful instead.
-  if (!providerCanGenerate(imagesApi, model.provider)) {
-    const supported = supportedProviders(imagesApi);
-    throw new Error(
-      `Provider "${model.provider}" has no image-generation route.\n` +
-        `→ Available: ${supported.join(", ") || "openrouter"}.\n` +
-        "→ Providers are bridged from pi automatically; one without a baseUrl " +
-        "or an API key cannot be used.\n" +
-        "→ Pick another with /unipi:settings.",
-    );
-  }
-
-  // Prefer pi-ai's own credential store, then the caller-supplied fallback so
-  // a bare OPENROUTER_API_KEY still works.
-  let apiKey: string | undefined;
-  try {
-    // pi-ai resolves to an `AuthResult`, i.e. `{ auth: { apiKey } }`. Older
-    // shapes put the key at the top level, so accept both — reading only one
-    // fails silently and looks like a missing credential.
-    const resolvedAuth = (await imagesApi.getAuth(model)) as
-      | { apiKey?: string; auth?: { apiKey?: string } }
-      | undefined;
-    apiKey = resolvedAuth?.auth?.apiKey ?? resolvedAuth?.apiKey;
-  } catch {
-    // Reported as a missing key below.
-  }
-  apiKey ||= options.apiKey;
-
-  if (!apiKey) {
-    throw new Error(
-      `No API key for provider "${model.provider}".\n` +
-        "→ Sign in with /login, or set the provider's API key environment variable.\n" +
-        `→ Expected environment variable: ` +
-        `${model.provider.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`,
-    );
-  }
-
-  const input: Array<{ type: string; text?: string; data?: string; mimeType?: string }> =
-    [{ type: "text", text: prompt }];
-  if (inputImage) {
-    input.push({
-      type: "image",
-      data: inputImage.data,
-      mimeType: inputImage.mimeType,
-    });
-  }
-
-  const result = (await imagesApi.generateImages(
-    model,
-    { input } as { input: Array<{ type: string; text?: string }> },
-    { apiKey, ...(signal ? { signal } : {}) },
-  )) as AssistantImagesLike;
-
-  // pi-ai reports failures in-band rather than rejecting.
-  if (result.stopReason === "error") {
-    throw new Error(result.errorMessage || "Image generation failed.");
-  }
-  if (result.stopReason === "aborted") {
-    throw new Error("Image generation was cancelled.");
-  }
-
-  const images: GeneratedImage[] = [];
-  const textParts: string[] = [];
-
-  for (const part of result.output ?? []) {
-    if (part?.type === "image" && typeof part.data === "string" && part.data.length > 0) {
-      images.push({ data: part.data, mimeType: part.mimeType || "image/png" });
-    } else if (part?.type === "text" && typeof part.text === "string" && part.text.trim()) {
-      textParts.push(part.text.trim());
-    }
-  }
-
-  if (images.length === 0) {
-    throw new Error(
-      textParts.length > 0
-        ? `The model returned no image. It said: ${textParts.join(" ")}`
-        : "The model returned no image.",
-    );
-  }
-
-  if (outputDir) {
-    images.forEach((image, index) => {
-      const fileName = buildFileName(prompt, image.mimeType, index, now);
-      image.path = saveImage(outputDir, fileName, image.data);
-    });
-  }
-
-  return {
-    images,
-    text: textParts.join("\n"),
-    model: model.id,
-    provider: model.provider,
-  };
-}

package/packages/image/src/index.ts

@@ -1,135 +0,0 @@
-/**
- * @pi-unipi/image — Extension entry
- *
- * Provides the `image_generate` and `image_recognize` agent tools plus the
- * Settings are managed in the unified /unipi:settings hub.
- */
-
-import { dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import {
-  IMAGE_TOOLS,
-  MODULES,
-  UNIPI_EVENTS,
-  emitEvent,
-  getPackageVersion,
-} from "@pi-unipi/core";
-
-import { registerImageTools } from "./tools.js";
-import {
-  applyRecognizeGating,
-  isVisionModel,
-  listImageGenModels,
-  listVisionModels,
-  type ChatModelRegistry,
-} from "./models.js";
-import { registerRegistryImageProviders } from "./register-providers.js";
-import { loadConfig } from "./settings.js";
-
-const VERSION = getPackageVersion(dirname(fileURLToPath(import.meta.url)));
-
-/** Info-screen registry, read off the global to avoid load-order coupling. */
-function getInfoRegistry() {
-  return (
-    globalThis as {
-      __unipi_info_registry?: {
-        registerGroup(group: unknown): void;
-      };
-    }
-  ).__unipi_info_registry;
-}
-
-/**
- * Hide image_recognize when the session model can natively see images, and
- * restore it when a text-only model takes over. Returns whether the tool is
- * provided after gating.
- */
-function applyVisionGating(pi: ExtensionAPI, model: unknown): boolean {
-  const active = pi.getActiveTools();
-  const next = applyRecognizeGating(active, model, IMAGE_TOOLS.RECOGNIZE);
-  if (next !== active) pi.setActiveTools(next);
-  return next.includes(IMAGE_TOOLS.RECOGNIZE);
-}
-
-export default function (pi: ExtensionAPI) {
-  registerImageTools(pi);
-
-  pi.on("model_select", (event) => {
-    if (!loadConfig().recognize.enabled) return;
-    applyVisionGating(pi, event.model);
-  });
-
-  pi.on("session_start", async (_event, ctx) => {
-    const config = loadConfig();
-
-    // Bridge pi's configured providers into pi-ai's images collection up front,
-    // so the settings picker and the info screen see them without a prior
-    // image_generate call. Best-effort: never block session start.
-    void registerRegistryImageProviders(
-      (ctx as unknown as { modelRegistry?: ChatModelRegistry }).modelRegistry,
-    ).catch(() => undefined);
-
-    // A vision-capable session model reads images itself, so image_recognize
-    // would only duplicate that ability. Drop it from the active tool set;
-    // the model_select handler above restores it when a text-only model is
-    // chosen later in the same session.
-    const recognizeProvided =
-      config.recognize.enabled && applyVisionGating(pi, ctx.model);
-
-    const tools: string[] = [];
-    if (config.generate.enabled) tools.push(IMAGE_TOOLS.GENERATE);
-    if (recognizeProvided) tools.push(IMAGE_TOOLS.RECOGNIZE);
-
-    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
-      name: MODULES.IMAGE,
-      version: VERSION,
-      commands: [],
-      tools,
-    });
-
-    const registry = getInfoRegistry();
-    if (!registry) return;
-
-    registry.registerGroup({
-      id: "image",
-      name: "Image",
-      icon: "🎨",
-      priority: 55,
-      config: {
-        showByDefault: true,
-        stats: [
-          { id: "generate", label: "Generate", show: true },
-          { id: "recognize", label: "Recognize", show: true },
-          { id: "visionModels", label: "Vision Models", show: true },
-        ],
-      },
-      dataProvider: async () => {
-        const current = loadConfig();
-
-        const genModels = await listImageGenModels();
-        const generate = current.generate.enabled
-          ? genModels.length > 0
-            ? current.generate.model
-            : "No image models available"
-          : "Disabled";
-
-        const chatRegistry = (ctx as unknown as { modelRegistry?: ChatModelRegistry })
-          .modelRegistry;
-        const vision = chatRegistry ? listVisionModels(chatRegistry) : [];
-
-        const recognize = !current.recognize.enabled
-          ? "Disabled"
-          : isVisionModel(ctx.model)
-            ? "Hidden (model has vision)"
-            : current.recognize.model || "Session model";
-
-        return {
-          generate: { value: generate },
-          recognize: { value: recognize },
-          visionModels: { value: String(vision.length) },
-        };
-      },
-    });
-  });
-}