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

package/packages/utility/src/image/transports.ts

@@ -0,0 +1,186 @@
+/**
+ * @pi-unipi/utility — image generation transports
+ *
+ * Three wire formats, one result shape. Every function THROWS on failure with
+ * a message worth showing the agent (pi only marks a tool result as failed
+ * when execute() throws).
+ *
+ *   openrouter    POST {base}/chat/completions, `modalities`, images come back
+ *                 as data URLs in choices[0].message.images
+ *   fal           POST https://fal.run/<model>, `sync_mode` → data URIs;
+ *                 edits send `image_urls`
+ *   openai-images POST {base}/images/generations; edits send an `image` array
+ *                 (the shape OpenAI, OmniRoute and most gateways accept)
+ */
+
+import type { ImageApi } from "./settings.js";
+
+export interface ImagePayload {
+  data: string;
+  mimeType: string;
+}
+
+export interface GenerateRequest {
+  api: ImageApi;
+  /** Endpoint base (ignored for fal, which has one host). */
+  baseUrl: string;
+  apiKey: string;
+  modelId: string;
+  prompt: string;
+  /** Source images → edit. */
+  images?: ImagePayload[];
+  /** Output modalities for OpenRouter (image-only models reject "text"). */
+  output?: string[];
+  signal?: AbortSignal;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}
+
+export interface GenerateResponse {
+  images: ImagePayload[];
+  text: string;
+}
+
+export const OPENROUTER_BASE = "https://openrouter.ai/api/v1";
+export const FAL_BASE = "https://fal.run";
+const DEFAULT_TIMEOUT_MS = 240_000;
+
+const dataUrl = (img: ImagePayload) => `data:${img.mimeType};base64,${img.data}`;
+
+/** `data:image/png;base64,....` → payload; undefined for anything else. */
+export function parseDataUrl(url: string): ImagePayload | undefined {
+  const m = /^data:([^;,]+)(?:;[^,]*)*,(.*)$/s.exec(url);
+  return m && m[2] ? { mimeType: m[1] || "image/png", data: m[2] } : undefined;
+}
+
+async function readError(res: Response): Promise<string> {
+  const body = await res.text().catch(() => "");
+  let detail = body.slice(0, 400);
+  try {
+    const parsed = JSON.parse(body) as { error?: { message?: string } | string; detail?: unknown; message?: string };
+    if (typeof parsed.error === "string") detail = parsed.error;
+    else if (parsed.error?.message) detail = parsed.error.message;
+    else if (typeof parsed.message === "string") detail = parsed.message;
+    else if (parsed.detail) detail = typeof parsed.detail === "string" ? parsed.detail : JSON.stringify(parsed.detail).slice(0, 400);
+  } catch {
+    // not JSON
+  }
+  return `${res.status} ${res.statusText}${detail ? `: ${detail}` : ""}`;
+}
+
+/** Fetch a remote image (fal without sync_mode, gateways returning URLs). */
+async function download(url: string, fetchImpl: typeof fetch, signal: AbortSignal): Promise<ImagePayload> {
+  const inline = parseDataUrl(url);
+  if (inline) return inline;
+  const res = await fetchImpl(url, { signal });
+  if (!res.ok) throw new Error(`Could not download the generated image: ${res.status}`);
+  const mimeType = res.headers.get("content-type")?.split(";")[0] || "image/png";
+  return { data: Buffer.from(await res.arrayBuffer()).toString("base64"), mimeType };
+}
+
+function join(base: string, suffix: string): string {
+  return `${base.replace(/\/+$/, "")}/${suffix.replace(/^\/+/, "")}`;
+}
+
+async function withTimeout<T>(req: GenerateRequest, run: (signal: AbortSignal, f: typeof fetch) => Promise<T>): Promise<T> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), req.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+  const onAbort = () => controller.abort();
+  req.signal?.addEventListener("abort", onAbort, { once: true });
+  try {
+    return await run(controller.signal, req.fetchImpl ?? fetch);
+  } catch (error) {
+    if (req.signal?.aborted) throw new Error("Image request was cancelled.");
+    if (controller.signal.aborted) throw new Error("Image request timed out.");
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    req.signal?.removeEventListener("abort", onAbort);
+  }
+}
+
+async function viaOpenRouter(req: GenerateRequest): Promise<GenerateResponse> {
+  return withTimeout(req, async (signal, f) => {
+    const content: unknown[] = [{ type: "text", text: req.prompt }];
+    for (const img of req.images ?? []) content.push({ type: "image_url", image_url: { url: dataUrl(img) } });
+    const output = req.output?.includes("image") ? req.output : ["image"];
+    const res = await f(join(req.baseUrl || OPENROUTER_BASE, "chat/completions"), {
+      method: "POST",
+      headers: { Authorization: `Bearer ${req.apiKey}`, "Content-Type": "application/json" },
+      body: JSON.stringify({ model: req.modelId, messages: [{ role: "user", content }], modalities: output }),
+      signal,
+    });
+    if (!res.ok) throw new Error(await readError(res));
+    const json = (await res.json()) as {
+      error?: { message?: string };
+      choices?: Array<{ message?: { content?: unknown; images?: Array<{ image_url?: { url?: string } }> } }>;
+    };
+    if (json.error?.message) throw new Error(json.error.message);
+    const message = json.choices?.[0]?.message;
+    const images: ImagePayload[] = [];
+    for (const item of message?.images ?? []) {
+      const url = item.image_url?.url;
+      if (url) images.push(await download(url, f, signal));
+    }
+    const text = typeof message?.content === "string" ? message.content.trim() : "";
+    return { images, text };
+  });
+}
+
+async function viaFal(req: GenerateRequest): Promise<GenerateResponse> {
+  return withTimeout(req, async (signal, f) => {
+    const body: Record<string, unknown> = { prompt: req.prompt, sync_mode: true, num_images: 1 };
+    if (req.images?.length) body.image_urls = req.images.map(dataUrl);
+    const res = await f(join(req.baseUrl || FAL_BASE, req.modelId), {
+      method: "POST",
+      headers: { Authorization: `Key ${req.apiKey}`, "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal,
+    });
+    if (!res.ok) throw new Error(await readError(res));
+    const json = (await res.json()) as { images?: Array<{ url?: string }>; image?: { url?: string }; description?: string };
+    const images: ImagePayload[] = [];
+    for (const item of json.images ?? (json.image ? [json.image] : [])) {
+      if (item.url) images.push(await download(item.url, f, signal));
+    }
+    return { images, text: typeof json.description === "string" ? json.description : "" };
+  });
+}
+
+async function viaOpenAIImages(req: GenerateRequest): Promise<GenerateResponse> {
+  if (!req.baseUrl) throw new Error(`No endpoint for ${req.modelId}: set a custom endpoint in /unipi:settings → Image.`);
+  return withTimeout(req, async (signal, f) => {
+    const body: Record<string, unknown> = { model: req.modelId, prompt: req.prompt };
+    if (req.images?.length) body.image = req.images.map(dataUrl);
+    const res = await f(join(req.baseUrl, "images/generations"), {
+      method: "POST",
+      headers: { Authorization: `Bearer ${req.apiKey}`, "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal,
+    });
+    if (!res.ok) throw new Error(await readError(res));
+    const json = (await res.json()) as { error?: { message?: string }; data?: Array<{ b64_json?: string; url?: string; media_type?: string; mime_type?: string; revised_prompt?: string }> };
+    if (json.error?.message) throw new Error(json.error.message);
+    const images: ImagePayload[] = [];
+    const notes: string[] = [];
+    for (const item of json.data ?? []) {
+      const declared = item.media_type ?? item.mime_type;
+      if (item.b64_json) images.push({ data: item.b64_json, mimeType: declared ?? "image/png" });
+      else if (item.url) images.push(await download(item.url, f, signal));
+      if (item.revised_prompt && item.revised_prompt !== req.prompt) notes.push(`Revised prompt: ${item.revised_prompt}`);
+    }
+    return { images, text: notes.join("\n") };
+  });
+}
+
+/** Run one generation/edit; throws unless at least one image came back. */
+export async function generate(req: GenerateRequest): Promise<GenerateResponse> {
+  if (!req.prompt.trim()) throw new Error("A non-empty prompt is required.");
+  if (!req.apiKey) throw new Error("No API key for this image model.");
+  const run = req.api === "fal" ? viaFal : req.api === "openrouter" ? viaOpenRouter : viaOpenAIImages;
+  const out = await run(req);
+  if (out.images.length === 0) {
+    throw new Error(out.text ? `The model returned no image. It said: ${out.text.slice(0, 300)}` : "The model returned no image.");
+  }
+  return out;
+}

package/packages/utility/src/index.ts

@@ -1,423 +1,102 @@
 /**
  * @pi-unipi/utility — Extension entry
  *
- * Comprehensive utilities suite for Pi coding agent:
- * - Commands: continue, reload, status, cleanup, env, doctor, badge
- * - Tools: ctx_env, set_session_name
- * - Lifecycle: process management, stale cleanup
- * - Analytics: lightweight event collection
- * - Diagnostics: cross-module health checks
- * - Prefix-cache observability: privacy-safe provider cache stats
- * - TUI: util settings, name badge (incl. Herdr pane title sync)
+ * - /unipi:settings — the unified settings hub
+ * - /unipi:continue (/unipi:retry), /unipi:cleanup, /unipi:doctor, /unipi:answer
+ * - Automatic session naming (jev gate + isolated one-tool session) + Herdr sync
+ * - Pasted images/files → [Image #N] / [File #N] attachments
+ * - Image tools: image_generate, image_edit, image_recognize
+ * - Response formatting: simple | regular | advanced tool rendering
+ * - The shared model cache (~/.unipi/config/models-cache.json)
  */
 
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { ExtensionAPI, ExtensionCommandContext, InputEvent, AgentEndEvent } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
   UNIPI_EVENTS,
   MODULES,
   UTILITY_COMMANDS,
-  UTILITY_TOOLS,
   emitEvent,
   getPackageVersion,
-  runCommandByName,
-  registerCommandRunner,
-  SettingsHub,
-  HUB_OVERLAY_OPTIONS,
-  type UnipiBadgeGenerateRequestEvent,
+  installHints,
+  openSettingsHub,
+  chatModelsToCache,
+  writeModelCache,
 } from "@pi-unipi/core";
 import { registerUtilityCommands } from "./commands.js";
-import { registerSkillJudging } from "./skill-discovery.js";
-import { NameBadgeState } from "./tui/name-badge-state.js";
-import { readBadgeSettings, readUtilSettings } from "./settings.js";
-import { getLifecycle } from "./lifecycle/process.js";
-import { getAnalyticsCollector } from "./analytics/collector.js";
-import { registerInfoScreen } from "./info-screen.js";
-import { PrefixCacheTracker, formatPrefixCacheStats } from "./prefix-cache.js";
+import { registerAutoRename } from "./rename/index.js";
+import { registerAnswerCommand } from "./answer/index.js";
+import { registerAttachments } from "./attach/index.js";
+import { imageCatalogEntries, loadImageConfig, refreshImageModelCache, registerImage } from "./image/index.js";
+import { registerToolRenderers } from "./render/tools.js";
+import { installTranscriptSpacing } from "./render/spacing.js";
+import { installHarnessRenderers, installHarnessUserRendering, withHarnessToolAnnotations } from "./render/harness.js";
+import { installHarnessProvenance } from "@pi-unipi/core";
+import { readUtilSettings } from "./settings.js";
+
+export { readUtilSettings } from "./settings.js";
+export { simpleWrapTool, simpleWrapped, installSimpleGroupEvents } from "./render/simple.js";
+export { withHarnessToolAnnotations } from "./render/harness.js";
 
-/** Re-export readBadgeSettings for cross-package use */
-export { readBadgeSettings } from "./settings.js";
-
-/** Package version */
 const VERSION = getPackageVersion(dirname(fileURLToPath(import.meta.url)));
 
-/** Whether we've seen the first user message (for auto badge generation) */
-let firstMessageSeen = false;
-
-/** Stored user text from first input, used to build conversation summary after agent responds */
-let firstUserText = "";
-
-/** Stored UI context from first input, used to show badge overlay after agent responds */
-let firstInputCtx: import("@earendil-works/pi-coding-agent").ExtensionContext | null = null;
-
-/** All commands registered by this module */
 const ALL_COMMANDS = [
   UTILITY_COMMANDS.CONTINUE,
-  UTILITY_COMMANDS.RELOAD,
-  UTILITY_COMMANDS.STATUS,
+  UTILITY_COMMANDS.RETRY,
   UTILITY_COMMANDS.CLEANUP,
-  UTILITY_COMMANDS.ENV,
   UTILITY_COMMANDS.DOCTOR,
-  UTILITY_COMMANDS.PREFIX_CACHE,
+  UTILITY_COMMANDS.ANSWER,
+  "settings",
 ].map((cmd) => `unipi:${cmd}`);
 
-/** All tools registered by this module */
-const ALL_TOOLS = [UTILITY_TOOLS.BATCH, UTILITY_TOOLS.ENV, UTILITY_TOOLS.SET_SESSION_NAME];
-
 export default function (pi: ExtensionAPI) {
-  // Initialize lifecycle manager
-  const lifecycle = getLifecycle();
-
-  // Initialize analytics collector
-  const analytics = getAnalyticsCollector();
-
-  // Session-local provider prefix observability. The random HMAC key and all
-  // payload-derived fingerprints remain in memory and are discarded on reload.
-  const prefixCache = new PrefixCacheTracker();
-  pi.registerCommand(`unipi:${UTILITY_COMMANDS.PREFIX_CACHE}`, {
-    description: "Show privacy-safe provider prefix-cache diagnostics",
-    handler: async (_args, ctx) => {
-      const report = formatPrefixCacheStats(prefixCache.getSnapshot());
-      if (ctx.hasUI) {
-        ctx.ui.notify(report, "info");
-      } else {
-        pi.sendMessage({ customType: "unipi-response", content: report, display: true }, { deliverAs: "followUp" });
-      }
-    },
-  });
-
-  // Badge actions — "Set session name…" / "Generate session name" rows in
-  // /unipi:settings (Utility group). The old badge slash commands are
-  // gone; the hub field is the same persisted setting.
-  registerCommandRunner("unipi:badge-set-name", async (rawCtx: unknown) => {
-    const ctx = rawCtx as ExtensionCommandContext;
-    if (!ctx.hasUI) {
-      ctx.ui.notify("Setting the session name requires an interactive UI.", "warning");
-      return;
-    }
-    const current = nameBadgeState.isVisible() ? undefined : "";
-    const name = await ctx.ui.input("Session name", current ?? "");
-    if (!name || !name.trim()) return;
-    nameBadgeState.setSessionName(pi, name.trim());
-    ctx.ui.notify(`Session name set to "${name.trim()}"`, "info");
-  });
-  registerCommandRunner("unipi:badge-generate", async (rawCtx: unknown) => {
-    const ctx = rawCtx as ExtensionCommandContext;
-    if (!ctx.hasUI) {
-      ctx.ui.notify("Badge generation requires an interactive UI.", "warning");
-      return;
-    }
-    await nameBadgeState.generate(pi, ctx);
-    ctx.ui.notify("Generating session name...", "info");
-  });
-
-  // The unified settings hub — every registered module in one panel.
+  // Standalone installs need provenance before any command can send.
+  try {
+    installHarnessProvenance(pi);
+  } catch {
+    // cosmetic
+  }
   pi.registerCommand("unipi:settings", {
-    description: "Configure all unipi modules in one panel (global + project scopes)",
-    handler: async (_args, ctx) => {
-      if (!ctx.hasUI) throw new Error("/unipi:settings needs the interactive TUI");
-      await ctx.ui.custom<void>(
-        (tui, _theme, _keybindings, done) => {
-          const hub = new SettingsHub({
-            cwd: ctx.cwd ?? process.cwd(),
-            onChanged: (namespace) => {
-              // Preserve the old overlay's live side-effect: the badge reacts
-              // immediately when "Show name badge" is toggled in the hub.
-              if (namespace !== "utility" || !ctx.hasUI) return;
-              try {
-                if (readUtilSettings().badge.badgeEnabled) void nameBadgeState.show(pi, ctx);
-                else nameBadgeState.hide();
-              } catch {
-                // Best effort — settings UI must never crash the panel.
-              }
-            },
-            runAction: async (command) => {
-              const ran = await runCommandByName(command, ctx);
-              if (!ran) ctx.ui.notify(`no handler registered for ${command}`, "warning");
-            },
-          });
-          hub.onClose = () => done();
-          return {
-            focused: true,
-            invalidate: () => hub.invalidate(),
-            render: (width: number) => hub.render(width),
-            handleInput: (data: string) => {
-              hub.handleInput(data);
-              tui.requestRender();
-            },
-            dispose: () => {},
-          };
-        },
-        HUB_OVERLAY_OPTIONS,
-      ).catch(() => {
-        // Overlay errors are non-blocking.
-      });
-    },
-  });
-
-  pi.on("session_start", () => {
-    // A replacement/reloaded session has a distinct provider prefix lineage.
-    // The extension factory is normally recreated, but reset explicitly so
-    // custom hosts that reuse one factory cannot leak counts across sessions.
-    prefixCache.reset();
+    description: "Configure all unipi modules in one panel (global + project scopes); /unipi:settings <search> opens it filtered",
+    handler: async (args, ctx) => openSettingsHub(ctx, { filter: args.trim() }),
   });
 
-  pi.on("before_provider_request", (event, ctx) => {
-    prefixCache.observeRequest(event.payload, ctx.model);
-    // Observe only: never replace or mutate provider payloads.
-  });
-
-  pi.on("agent_end", (event) => {
-    prefixCache.observeMessages(event.messages);
-  });
-
-  pi.on("model_select", (event) => {
-    if (event.previousModel && (
-      event.previousModel.provider !== event.model.provider ||
-      event.previousModel.id !== event.model.id ||
-      event.previousModel.api !== event.model.api
-    )) {
-      prefixCache.markBoundary("envelope_changed");
-    }
-  });
-  pi.on("thinking_level_select", (event) => {
-    if (event.previousLevel !== event.level) prefixCache.markBoundary("envelope_changed");
-  });
-  pi.on("session_compact", () => prefixCache.markBoundary("history_rewritten"));
-  pi.on("session_tree", () => prefixCache.markBoundary("history_rewritten"));
-
-  // Register cleanup on shutdown
-  lifecycle.registerCleanup(async () => {
-    analytics.disable();
-  });
-
-  // Initialize name badge state
-  const nameBadgeState = new NameBadgeState();
-
-  // Capture session context for cross-event use (not needed if BADGE_GENERATE_REQUEST removed)
-
-  // Skill startup discovery gate — when disabled (unipi.skills.discovery: false),
-  // Unipi's bundled skills are removed from the <available_skills> catalog so
-  // they never populate agent context; the user's own skills (global, project,
-  // settings-mounted, third-party packages) stay cataloged. /skill:name
-  // invocation is unaffected either way: pi expands those commands by reading
-  // SKILL.md directly. Applied consistently per turn, so the provider prefix
-  // cache stays intact.
-  // Skill exposure pipeline: bundled strip → jev freeze → recheck reveals.
-  registerSkillJudging(pi);
-
-  // Register commands
   registerUtilityCommands(pi);
+  registerAutoRename(pi);
+  registerAnswerCommand(pi);
+  registerAttachments(pi);
+  registerImage(pi);
+  registerToolRenderers(pi, readUtilSettings().render.style);
+  // Normalize blank runs between transcript blocks (all render styles).
+  installTranscriptSpacing(pi);
+  // Harness provenance: known custom-type panels + native USER card patch.
+  installHarnessRenderers(pi);
+  installHarnessUserRendering(pi);
+  // Unicrab hints: one line above the editor on startup + matching events.
+  installHints(pi);
 
-  // Register tools
-  registerUtilityTools(pi, nameBadgeState);
-
-  // Register info-screen group
-  registerInfoScreen(pi);
-
-  // Session lifecycle — announce module + restore badge
   pi.on("session_start", async (_event, ctx) => {
-    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
-      name: MODULES.UTILITY,
-      version: VERSION,
-      commands: ALL_COMMANDS,
-      tools: ALL_TOOLS,
-    });
-
-    analytics.recordModuleLoad(MODULES.UTILITY, VERSION);
-
-    // Restore name badge if it was visible in previous session
-    await nameBadgeState.restore(pi, ctx);
-
-    // Auto-show badge on session start if enabled in settings and UI is available.
-    // The badge shows "Set a name" placeholder until a name is generated.
-    // Previously the badge only showed after the first agent_end, which meant it
-    // was absent on restart until the user sent a message.
-    if (ctx?.hasUI && !nameBadgeState.isVisible()) {
-      const badgeSettings = readBadgeSettings();
-      if (badgeSettings.badgeEnabled) {
-        await nameBadgeState.show(pi, ctx);
-      }
-    }
-
-    // Write model cache for TUI components
-    if ((ctx as any).modelRegistry) {
-      const { writeModelCache } = await import("@pi-unipi/core");
-      const registry = (ctx as any).modelRegistry;
-      const models = (registry.getAvailable?.() ?? registry.getAll())
-        .map((m: any) => ({ provider: m.provider, id: m.id, name: m.name }));
-      writeModelCache(models);
-    }
-  });
-
-  // First-message hook: capture user text for deferred badge generation
-  pi.on("input", async (_event, ctx) => {
-    // Only trigger on first user message
-    if (firstMessageSeen) return;
-    firstMessageSeen = true;
-
-    // Check if auto generation is enabled
-    const settings = readBadgeSettings();
-    if (!settings.autoGen) return;
-
-    // Skip if badge already has a name
-    const sessionName = pi.getSessionName?.();
-    if (sessionName) return;
-
-    // Store first message text for later use in agent_end
-    // Note: InputEvent.text is the documented property; content may exist at runtime
-    const content = (_event as unknown as Record<string, unknown>).content;
-    firstUserText = typeof content === "string"
-      ? content
-      : Array.isArray(content)
-        ? (content as Array<Record<string, unknown>>)
-            .filter((c) => c.type === "text")
-            .map((c) => String(c.text))
-            .join(" ")
-        : "";
-
-    // Store ctx for badge overlay show after agent responds
-    firstInputCtx = ctx;
-  });
-
-  // After agent completes first response, generate badge name with full conversation context
-  pi.on("agent_end", async (event, _ctx) => {
-    // Only act if we captured a first input and are waiting for badge generation
-    if (!firstInputCtx) return;
-    const ctx = firstInputCtx;
-    firstInputCtx = null; // consume — only trigger once
-
-    // Check if a name was already set (e.g. manually) in the meantime
-    const sessionName = pi.getSessionName?.();
-    if (sessionName) return;
-
-    // Show badge overlay if UI available
-    if (ctx?.hasUI && !nameBadgeState.isVisible()) {
-      await nameBadgeState.show(pi, ctx);
-    }
-
-    // Build conversation summary from full message history (user + assistant)
-    const messages = event.messages;
-    const summaryParts: string[] = [];
-
-    // Include the user's first message
-    if (firstUserText) {
-      summaryParts.push(`User: ${firstUserText}`);
-    }
-
-    // Include assistant's response text
-    const assistantMsgs = messages.filter((m) => m.role === "assistant");
-    for (const msg of assistantMsgs) {
-      const content = msg.content;
-      if (Array.isArray(content)) {
-        const textParts = content
-          .filter((c): c is { type: "text"; text: string } => "text" in c && c.type === "text")
-          .map((c) => c.text)
-          .join(" ");
-        if (textParts) summaryParts.push(`Assistant: ${textParts}`);
-      } else if (typeof content === "string" && content) {
-        summaryParts.push(`Assistant: ${content}`);
-      }
-    }
-
-    // Truncate to reasonable size
-    const conversationSummary = summaryParts.join("\n").slice(0, 800);
-
-    // Emit event for subagents to spawn background agent
-    emitEvent(pi, UNIPI_EVENTS.BADGE_GENERATE_REQUEST, {
-      source: "input-hook",
-      conversationSummary,
-    });
-  });
-
-  // Track command usage
-  pi.on("tool_call", async (event) => {
-    if (event.toolName.startsWith("unipi:")) {
-      analytics.recordCommand(event.toolName, MODULES.UTILITY, 0, true);
+    try {
+      emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
+        name: MODULES.UTILITY,
+        version: VERSION,
+        commands: ALL_COMMANDS,
+        tools: [],
+      });
+      // Refresh the shared model cache: image models first (their real
+      // modalities win over the chat registry's text-only view), then pi's
+      // live chat registry (models with credentials, else the full registry).
+      const registry = ctx.modelRegistry as unknown as { getAvailable?: () => unknown[]; getAll?: () => unknown[] } | undefined;
+      const available = registry?.getAvailable?.() ?? [];
+      const chat = chatModelsToCache(available.length > 0 ? available : registry?.getAll?.() ?? []);
+      const write = () => writeModelCache([...imageCatalogEntries(loadImageConfig(ctx.cwd)), ...chat]);
+      if (chat.length > 0) write();
+      void refreshImageModelCache().then((changed) => {
+        if (changed && chat.length > 0) write();
+      });
+    } catch {
+      // Best effort — never block session start.
     }
   });
-
-  // Session shutdown cleanup
-  pi.on("session_shutdown", async () => {
-    nameBadgeState.hide();
-    firstMessageSeen = false;
-    firstUserText = "";
-    firstInputCtx = null;
-    await lifecycle.shutdown("session_shutdown");
-  });
-}
-
-/**
- * Register utility tools.
- */
-function registerUtilityTools(pi: ExtensionAPI, nameBadgeState: NameBadgeState): void {
-  // ctx_env — environment info
-  pi.registerTool({
-    name: UTILITY_TOOLS.ENV,
-    label: "Environment Info",
-    description: "Show environment information: Node version, Pi version, OS, unipi modules, config paths.",
-    promptSnippet: "Get environment details for debugging.",
-    parameters: {
-      type: "object",
-      properties: {},
-    },
-    async execute() {
-      const { getEnvironmentInfo, formatEnvironmentInfo } = await import("./tools/env.js");
-      const info = getEnvironmentInfo();
-      return {
-        content: [{ type: "text", text: formatEnvironmentInfo(info) }],
-        details: info,
-      };
-    },
-  });
-
-  // set_session_name — set the session name for badge display
-  const badgeSettings = readBadgeSettings();
-  if (badgeSettings.agentTool) {
-    pi.registerTool({
-      name: UTILITY_TOOLS.SET_SESSION_NAME,
-      label: "Set Session Name",
-      description:
-        "Set the session name that appears in the badge overlay and session selector. " +
-        "Use this to give the current session a descriptive title. " +
-        "Name should be concise (max 5 words recommended).",
-      promptSnippet: "Set a name/title for the current session.",
-      parameters: {
-        type: "object",
-        properties: {
-          name: {
-            type: "string",
-            description: "The session name to set (max 5 words recommended).",
-          },
-        },
-        required: ["name"],
-      },
-      async execute(_toolCallId, params) {
-        const { name } = params as { name: string };
-        if (!name || typeof name !== "string") {
-          return {
-            content: [{ type: "text", text: "Error: name parameter is required and must be a string." }],
-            details: undefined,
-          };
-        }
-
-        const trimmed = name.trim();
-        if (trimmed.length === 0) {
-          return {
-            content: [{ type: "text", text: "Error: name cannot be empty." }],
-            details: undefined,
-          };
-        }
-
-        // Set the session name
-        nameBadgeState.setSessionName(pi, trimmed);
-
-        return {
-          content: [{ type: "text", text: `Session name set to: "${trimmed}"` }],
-          details: { name: trimmed },
-        };
-      },
-    });
-  }
 }