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

package/packages/utility/src/attach/index.ts

@@ -0,0 +1,205 @@
+/**
+ * @pi-unipi/utility — image & file attachments
+ *
+ * After a paste, drag-and-drop or Ctrl+V, any image/document path that lands
+ * in the editor is swapped for a token — [Image #1], [File #2] — and listed
+ * in a chip row above the editor (with small inline previews in Kitty,
+ * Ghostty, iTerm2 and WezTerm). On submit, images are sent as real image
+ * content and file tokens expand to their paths. Deleting a token drops the
+ * attachment. After the message is sent, a user-only transcript line shows
+ * what was attached (the model never sees it).
+ */
+
+import { readFileSync } from "node:fs";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getCapabilities, Image, Key, matchesKey, truncateToWidth, type Component } from "@earendil-works/pi-tui";
+import { readUtilSettings } from "../settings.js";
+import { expandForSubmit, formatBytes, stillReferenced, tokenFor, tokenize, type Attachment } from "@pi-unipi/core";
+
+export const ATTACHMENTS_ENTRY = "unipi:attachments";
+const WIDGET = "unipi-attachments";
+const SCAN_AFTER_PASTE_MS = [80, 400, 1200];
+const PREVIEW_ROWS = 5;
+const PREVIEW_MAX = 3;
+
+type Theme = { fg: (color: string, text: string) => string; bold?: (t: string) => string };
+
+function isPaste(data: string): boolean {
+  return data.includes("\x1b[200~") || matchesKey(data, Key.ctrl("v")) || matchesKey(data, Key.alt("v"));
+}
+
+function canPreview(): boolean {
+  try {
+    return Boolean(getCapabilities().images);
+  } catch {
+    return false;
+  }
+}
+
+function chip(theme: Theme, a: Pick<Attachment, "kind" | "id" | "name" | "bytes">): string {
+  return `${theme.fg("accent", tokenFor(a))} ${a.name}${a.bytes ? theme.fg("muted", ` · ${formatBytes(a.bytes)}`) : ""}`;
+}
+
+/** Chip line + optional inline previews, shared by the widget and the transcript line. */
+function attachmentView(items: ReadonlyArray<Pick<Attachment, "kind" | "id" | "name" | "bytes" | "path" | "mimeType">>, theme: Theme, preview: boolean, hint: string): Component {
+  const images: Image[] = [];
+  if (preview && canPreview()) {
+    for (const a of items.filter((i) => i.kind === "image").slice(0, PREVIEW_MAX)) {
+      try {
+        images.push(new Image(readFileSync(a.path).toString("base64"), a.mimeType ?? "image/png", { fallbackColor: (s) => theme.fg("muted", s) }, { maxHeightCells: PREVIEW_ROWS, maxWidthCells: 32, filename: a.name }));
+      } catch {
+        // file gone — chip only
+      }
+    }
+  }
+  return {
+    invalidate() {
+      for (const i of images) i.invalidate();
+    },
+    render(width: number): string[] {
+      const bar = theme.fg("accent", "▌ ");
+      const chips = items.map((a) => chip(theme, a)).join(theme.fg("muted", "  ·  "));
+      const lines = [truncateToWidth(`${bar}${chips}${hint ? theme.fg("muted", `   ${hint}`) : ""}`, width, "…")];
+      for (const img of images) lines.push(...img.render(Math.min(width, 34)));
+      return lines;
+    },
+  };
+}
+
+export function registerAttachments(pi: ExtensionAPI): void {
+  let attachments: Attachment[] = [];
+  let sent: Attachment[] = [];
+  let ui: ExtensionContext["ui"] | null = null;
+  let unsub: (() => void) | undefined;
+  const timers = new Set<ReturnType<typeof setTimeout>>();
+
+  const refreshWidget = () => {
+    if (!ui) return;
+    const settings = readUtilSettings().attachments;
+    if (attachments.length === 0) {
+      ui.setWidget(WIDGET, undefined);
+      return;
+    }
+    const items = [...attachments];
+    ui.setWidget(WIDGET, (_tui, theme) => attachmentView(items, theme as unknown as Theme, settings.preview, "attached to your next message"), { placement: "aboveEditor" });
+  };
+
+  const scan = () => {
+    if (!ui) return;
+    try {
+      const text = ui.getEditorText();
+      const { text: next, added } = tokenize(text, attachments);
+      if (next !== text) ui.setEditorText(next);
+      if (added.length > 0) {
+        attachments = [...attachments, ...added];
+        refreshWidget();
+      }
+    } catch {
+      // editor unavailable — leave the text alone
+    }
+  };
+
+  const sync = () => {
+    if (!ui || attachments.length === 0) return;
+    try {
+      const kept = stillReferenced(ui.getEditorText(), attachments);
+      if (kept.length !== attachments.length) {
+        attachments = kept;
+        refreshWidget();
+      }
+    } catch {
+      // ignore
+    }
+  };
+
+  const later = (fn: () => void, ms: number) => {
+    const t = setTimeout(() => {
+      timers.delete(t);
+      fn();
+    }, ms);
+    t.unref?.();
+    timers.add(t);
+  };
+
+  try {
+    pi.registerEntryRenderer<{ items: Attachment[] }>(ATTACHMENTS_ENTRY, (entry, _opts, theme) => {
+      const items = entry.data?.items;
+      if (!Array.isArray(items) || items.length === 0) return undefined;
+      return attachmentView(items, theme as unknown as Theme, readUtilSettings().attachments.preview, "");
+    });
+  } catch {
+    // UI-dependent
+  }
+
+  pi.on("session_start", (_e, ctx) => {
+    unsub?.();
+    unsub = undefined;
+    attachments = [];
+    sent = [];
+    ui = ctx.hasUI ? ctx.ui : null;
+    if (!ui || !readUtilSettings(ctx.cwd).attachments.enabled) return;
+    ui.setWidget(WIDGET, undefined);
+    unsub = ui.onTerminalInput((data) => {
+      if (data === "\x7f" || data === "\b") {
+        // Token-aware backspace: if the cursor is at the end of a token
+        // (the common case right after a paste), delete the whole [Image #N]
+        // / [File #N] atomically instead of just the closing bracket. The
+        // editor API exposes no cursor position, so we only fire when the
+        // text ends with a token — mid-text edits fall through untouched.
+        const ed = ui;
+        if (ed) {
+          try {
+            const text = ed.getEditorText();
+            const m = /\[(?:Image|File) #\d+\] ?$/.exec(text);
+            if (m) {
+              ed.setEditorText(text.slice(0, text.length - m[0].length));
+              later(sync, 0);
+              return { consume: true };
+            }
+          } catch {
+            // editor unavailable — fall through
+          }
+        }
+      }
+      if (isPaste(data)) for (const ms of SCAN_AFTER_PASTE_MS) later(scan, ms);
+      else if (attachments.length > 0) later(sync, 60);
+      return undefined;
+    });
+  });
+
+  pi.on("input", (event) => {
+    try {
+      if (event.source === "extension" || attachments.length === 0) return undefined;
+      const text = event.text ?? "";
+      const used = stillReferenced(text, attachments);
+      if (used.length === 0 || text.trimStart().startsWith("/")) return undefined;
+      const out = expandForSubmit(text, used);
+      sent = used;
+      attachments = [];
+      refreshWidget();
+      return { action: "transform" as const, text: out.text, images: [...(event.images ?? []), ...out.images] };
+    } catch {
+      return undefined;
+    }
+  });
+
+  // The user message is in the session by now: show what went with it.
+  pi.on("agent_start", () => {
+    if (sent.length === 0) return;
+    const items = sent.map(({ id, kind, name, path, bytes, mimeType }) => ({ id, kind, name, path, bytes, mimeType }));
+    sent = [];
+    try {
+      pi.appendEntry(ATTACHMENTS_ENTRY, { items });
+    } catch {
+      // ignore
+    }
+  });
+
+  pi.on("session_shutdown", () => {
+    unsub?.();
+    unsub = undefined;
+    for (const t of timers) clearTimeout(t);
+    timers.clear();
+    ui = null;
+  });
+}

package/packages/utility/src/commands.ts

@@ -1,27 +1,15 @@
 /**
- * @pi-unipi/utility — Command registration
+ * @pi-unipi/utility — Commands
  *
- * Registers all utility commands:
- * - /unipi:continue — existing, preserved
- * - /unipi:reload — reload all extensions
- * - /unipi:status — show module status
- * - /unipi:cleanup — clean stale files
- * - /unipi:env — show environment
- * - /unipi:doctor — run diagnostics
+ *   /unipi:continue (/unipi:retry) — take another turn without adding user text
+ *   /unipi:cleanup [--dry-run|--yes] — allowlisted stale files, preview + confirm
+ *   /unipi:doctor                     — runtime diagnostics
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import {
-  UNIPI_PREFIX,
-  UTILITY_COMMANDS,
-  UNIPI_EVENTS,
-  emitEvent,
-} from "@pi-unipi/core";
-import { cleanupStale, formatCleanupReport } from "./lifecycle/cleanup.js";
+import { harnessMetadata, UNIPI_PREFIX, UTILITY_COMMANDS } from "@pi-unipi/core";
+import { findCleanupItems, formatBytes, formatCleanupPreview, removeCleanupItems } from "./lifecycle/cleanup.js";
 import { runDiagnostics, formatDiagnosticsReport } from "./diagnostics/engine.js";
-import { getEnvironmentInfo, formatEnvironmentInfo } from "./tools/env.js";
-import type { NameBadgeState } from "./tui/name-badge-state.js";
-import { isSkillDiscoveryEnabled } from "./skill-discovery.js";
 
 /** Send a markdown response via pi.sendMessage */
 function sendResponse(pi: ExtensionAPI, markdown: string): void {
@@ -30,151 +18,59 @@ function sendResponse(pi: ExtensionAPI, markdown: string): void {
       customType: "unipi-response",
       content: markdown,
       display: true,
+      details: { unipiHarness: harnessMetadata({ source: "Utility", title: "Response", synopsis: "Command response" }, "followUp") },
     },
     { deliverAs: "followUp" },
   );
 }
 
-/**
- * Register all utility commands.
- */
+function busy(ctx: ExtensionContext): boolean {
+  if (ctx.isIdle()) return false;
+  if (ctx.hasUI) ctx.ui.notify("Agent is busy. Press ESC to interrupt, then try again.", "warning");
+  return true;
+}
+
 export function registerUtilityCommands(pi: ExtensionAPI): void {
-  // ─── /unipi:continue — preserved ─────────────────────────────────────────
+  const continueHandler = async (_args: string, ctx: ExtensionContext) => {
+    if (busy(ctx)) return;
+    pi.sendMessage({ customType: "unipi-continue", content: "", display: false }, { triggerTurn: true });
+  };
   pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.CONTINUE}`, {
-    description: "Continue the agent from where it left off without adding user context",
-    handler: async (_args: string, ctx: ExtensionContext) => {
-      if (!ctx.isIdle()) {
-        if (ctx.hasUI) {
-          ctx.ui.notify(
-            "Agent is busy. Press ESC to interrupt, then try again.",
-            "warning",
-          );
-        }
-        return;
-      }
-
-      pi.sendMessage(
-        {
-          customType: "unipi-continue",
-          content: "",
-          display: false,
-        },
-        { triggerTurn: true },
-      );
-    },
+    description: "Continue the agent from where it left off, without adding text (/unipi:retry)",
+    handler: continueHandler,
   });
-
-  // ─── /unipi:reload ───────────────────────────────────────────────────────
-  pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.RELOAD}`, {
-    description: "Reload all Pi extensions without restarting",
-    handler: async (_args: string, ctx: ExtensionContext) => {
-      if (!ctx.isIdle()) {
-        if (ctx.hasUI) {
-          ctx.ui.notify("Agent is busy. Press ESC to interrupt first.", "warning");
-        }
-        return;
-      }
-
-      sendResponse(
-        pi,
-        "## 🔄 Reload Extensions\n\n" +
-          "To reload all extensions:\n" +
-          "1. Press **Ctrl+C** to exit Pi\n" +
-          "2. Run `pi` again to restart with fresh extensions\n\n" +
-          "*Note: Pi does not support hot-reloading of extensions.*",
-      );
-    },
-  });
-
-  // ─── /unipi:status ───────────────────────────────────────────────────────
-  pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.STATUS}`, {
-    description: "Show all unipi modules status",
-    handler: async (_args: string, ctx: ExtensionContext) => {
-      if (!ctx.isIdle()) {
-        if (ctx.hasUI) {
-          ctx.ui.notify("Agent is busy. Press ESC to interrupt first.", "warning");
-        }
-        return;
-      }
-
-      sendResponse(
-        pi,
-        "## 📊 Module Status\n\n" +
-          "Use `/unipi:info` for the live module and tool dashboard.\n" +
-          "Use `/unipi:doctor` to run configuration and runtime diagnostics.",
-      );
-    },
+  pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.RETRY}`, {
+    description: "Retry the last turn — alias of /unipi:continue",
+    handler: continueHandler,
   });
 
-  // ─── /unipi:cleanup ──────────────────────────────────────────────────────
   pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.CLEANUP}`, {
-    description: "Clean temp files, stale DBs, old sessions",
+    description: "Remove stale UniPi temp files and leftovers (preview first)",
     handler: async (args: string, ctx: ExtensionContext) => {
-      if (!ctx.isIdle()) {
-        if (ctx.hasUI) {
-          ctx.ui.notify("Agent is busy. Press ESC to interrupt first.", "warning");
-        }
+      if (busy(ctx)) return;
+      const items = findCleanupItems();
+      const preview = formatCleanupPreview(items);
+      if (items.length === 0 || args.includes("--dry-run")) {
+        sendResponse(pi, `## Cleanup${args.includes("--dry-run") ? " (dry run)" : ""}\n\n\`\`\`\n${preview}\n\`\`\``);
         return;
       }
-
-      const dryRun = args.includes("--dry-run");
-      const report = cleanupStale({ dryRun });
-
-      emitEvent(pi, UNIPI_EVENTS.UTILITY_CLEANUP_DONE, {
-        dryRun,
-        categories: ["db", "temp", "session", "cache"],
-        results: report.results.map((r) => ({
-          category: r.category,
-          removed: r.removed,
-          bytesFreed: r.bytesFreed,
-        })),
-      });
-
-      sendResponse(pi, formatCleanupReport(report));
-    },
-  });
-
-  // ─── /unipi:env ──────────────────────────────────────────────────────────
-  pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.ENV}`, {
-    description: "Show environment info (versions, paths)",
-    handler: async (_args: string, ctx: ExtensionContext) => {
-      if (!ctx.isIdle()) {
-        if (ctx.hasUI) {
-          ctx.ui.notify("Agent is busy. Press ESC to interrupt first.", "warning");
-        }
+      const confirmed = args.includes("--yes")
+        || (ctx.hasUI && await ctx.ui.confirm("Remove these files?", preview));
+      if (!confirmed) {
+        sendResponse(pi, `## Cleanup cancelled\n\n\`\`\`\n${preview}\n\`\`\`${ctx.hasUI ? "" : "\n\nRun `/unipi:cleanup --yes` to remove them."}`);
         return;
       }
-
-      const info = getEnvironmentInfo();
-      sendResponse(pi, formatEnvironmentInfo(info));
+      const result = removeCleanupItems(items);
+      const failed = result.failed.length ? `\n\nCould not remove:\n${result.failed.map((p) => `- \`${p}\``).join("\n")}` : "";
+      sendResponse(pi, `## Cleanup\n\nRemoved ${result.removed} item(s), ${formatBytes(result.bytes)}.${failed}`);
     },
   });
 
-  // ─── /unipi:doctor ───────────────────────────────────────────────────────
   pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.DOCTOR}`, {
-    description: "Run diagnostics across all unipi modules",
+    description: "Check UniPi's runtime: folders, config, model cache, Decision Model, skills",
     handler: async (_args: string, ctx: ExtensionContext) => {
-      if (!ctx.isIdle()) {
-        if (ctx.hasUI) {
-          ctx.ui.notify("Agent is busy. Press ESC to interrupt first.", "warning");
-        }
-        return;
-      }
-
-      emitEvent(pi, UNIPI_EVENTS.UTILITY_DIAGNOSTICS_START, {
-        overall: "unknown",
-        checkCount: 0,
-      });
-
-      const report = await runDiagnostics();
-
-      emitEvent(pi, UNIPI_EVENTS.UTILITY_DIAGNOSTICS_DONE, {
-        overall: report.overall,
-        checkCount: report.checks.length,
-        report,
-      });
-
-      sendResponse(pi, formatDiagnosticsReport(report));
+      if (busy(ctx)) return;
+      sendResponse(pi, formatDiagnosticsReport(await runDiagnostics()));
     },
   });
 }

package/packages/utility/src/diagnostics/engine.ts

@@ -51,9 +51,7 @@ const coreDirectoriesPlugin: DiagnosticPlugin = {
   async run(): Promise<DiagnosticCheck[]> {
     const dirs = [
       { path: "~/.unipi", required: true },
-      { path: "~/.unipi/memory", required: false },
-      { path: "~/.unipi/cache", required: false },
-      { path: "~/.unipi/analytics", required: false },
+      { path: "~/.unipi/config", required: false },
     ];
 
     const checks: DiagnosticCheck[] = [];
@@ -196,6 +194,52 @@ const nodeEnvironmentPlugin: DiagnosticPlugin = {
   },
 };
 
+/** Model cache, Decision Model key and skill exposure — what other modules depend on. */
+const unipiRuntimePlugin: DiagnosticPlugin = {
+  name: "unipi_runtime",
+  module: "@pi-unipi/utility",
+  async run(): Promise<DiagnosticCheck[]> {
+    const { readModelCache, resolveDecisionModel, jevApiKey, getSettings } = await import("@pi-unipi/core");
+    const checks: DiagnosticCheck[] = [];
+    const models = readModelCache();
+    const images = models.filter((m) => m.output?.includes("image")).length;
+    checks.push({
+      name: "model_cache",
+      module: "@pi-unipi/core",
+      status: models.length > 0 ? "healthy" : "warning",
+      message: models.length > 0
+        ? `Model cache: ${models.length} models (${images} image generators)`
+        : "Model cache is empty — pickers fall back to ~/.pi/agent/models.json",
+      suggestion: models.length > 0 ? undefined : "Start a pi session once; utility refreshes the cache on session start",
+      durationMs: 0,
+    });
+    const dm = resolveDecisionModel(process.cwd(), "utility");
+    const hasKey = Boolean(jevApiKey(dm, process.env));
+    checks.push({
+      name: "decision_model",
+      module: "@pi-unipi/core",
+      status: hasKey ? "healthy" : "warning",
+      message: hasKey
+        ? `Decision Model: ${dm.provider}/${dm.model}`
+        : `Decision Model ${dm.provider}/${dm.model} has no API key — auto-rename and skill judging fall back`,
+      suggestion: hasKey ? undefined : "Set a key in /unipi:settings → Decision Model, or export OPENROUTER_API_KEY",
+      durationMs: 0,
+    });
+    const mode = (getSettings("skills", process.cwd()) as { exposure?: { mode?: string } }).exposure?.mode ?? "judged";
+    checks.push({
+      name: "skill_exposure",
+      module: "@pi-unipi/skill-registry",
+      status: mode === "off" ? "warning" : "healthy",
+      message: mode === "off"
+        ? "Skill exposure is off: UniPi's bundled skills are hidden from the model in this project"
+        : `Skill exposure: ${mode}`,
+      suggestion: mode === "off" ? "Switch Skills → Exposure → Skill exposure to judged or all in /unipi:settings" : undefined,
+      durationMs: 0,
+    });
+    return checks;
+  },
+};
+
 // ─── Diagnostics Engine ──────────────────────────────────────────────────────
 
 /** Registry of diagnostic plugins */
@@ -203,6 +247,7 @@ const plugins: DiagnosticPlugin[] = [
   coreDirectoriesPlugin,
   configFilesPlugin,
   nodeEnvironmentPlugin,
+  unipiRuntimePlugin,
 ];
 
 /** Register a custom diagnostic plugin */
@@ -259,7 +304,7 @@ export async function runDiagnostics(): Promise<DiagnosticsReport> {
 /** Format a diagnostics report as markdown */
 export function formatDiagnosticsReport(report: DiagnosticsReport): string {
   const lines = [
-    "## 🔍 Diagnostics Report",
+    "## Diagnostics",
     "",
     `**Overall:** ${report.overall.toUpperCase()}`,
     `**Checks:** ${report.summary.healthy} healthy, ${report.summary.warning} warning, ${report.summary.error} error, ${report.summary.unknown} unknown`,
@@ -282,7 +327,7 @@ export function formatDiagnosticsReport(report: DiagnosticsReport): string {
       lines.push(`- **${check.name}** (${check.module})`);
       lines.push(`  ${check.message}`);
       if (check.suggestion) {
-        lines.push(`  💡 ${check.suggestion}`);
+        lines.push(`  → ${check.suggestion}`);
       }
       lines.push("");
     }

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

@@ -0,0 +1,33 @@
+/**
+ * @pi-unipi/utility — image: tools + recognize gating
+ *
+ * image_recognize is hidden while the session model can see images itself
+ * (pi's read tool already hands it the pixels) and comes back for text-only
+ * models.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { IMAGE_TOOLS } from "@pi-unipi/core";
+import { applyRecognizeGating } from "./models.js";
+import { loadConfig } from "./settings.js";
+import { registerImageTools } from "./tools.js";
+
+export { imageCatalogEntries, refreshImageModelCache } from "./models.js";
+export { loadConfig as loadImageConfig } from "./settings.js";
+
+export function registerImage(pi: ExtensionAPI): void {
+  registerImageTools(pi);
+
+  const gate = (model: unknown) => {
+    try {
+      if (!loadConfig().recognize.enabled) return;
+      const active = pi.getActiveTools();
+      const next = applyRecognizeGating(active, model, IMAGE_TOOLS.RECOGNIZE);
+      if (next !== active) pi.setActiveTools(next);
+    } catch {
+      // tools not ready — next event retries
+    }
+  };
+  pi.on("session_start", (_e, ctx) => gate(ctx.model));
+  pi.on("model_select", (event) => gate(event.model));
+}