@gonrocca/zero-pi 0.1.10 → 0.1.11

package/README.md

@@ -181,26 +181,103 @@ the most recent recommendation.
 `skill-loop.md` gives the agent a closed learning loop so solutions are reused
 instead of re-derived.
 
+### ZERO terminal theme (`themes/zero-sdd.json`)
+
+`zero-pi` ships a Pi theme named `zero-sdd`: a dark, high-contrast terminal
+palette with cyan, amber, mint, rose, and violet accents tuned for SDD work.
+Select it from `/settings`, or set `"theme": "zero-sdd"` in Pi settings.
+
 ### Startup banner (`extensions/startup-banner.ts`)
 
-Renders the `ZERO` wordmark in ANSI Shadow figlet style with a purple → amber
-shimmer sweep the moment a pi session starts, then settles into a static
-gradient glow. Pure ANSI 24-bit colour, no runtime dependencies.
+Renders the `ZERO` wordmark as ASCII-safe Tetris cells. In the default animated
+mode, the cells assemble from the bottom up when a pi session starts, then
+settle into the completed ZERO banner. Pure ANSI 24-bit colour, no runtime
+dependencies.
 
 The render runs synchronously before pi draws its UI, so the animation never
 fights pi's renderer.
 
+### Working-phrase ticker (`extensions/working-phrases.ts`)
+
+Pi shows a single static `Working...` line while the agent is busy. This
+extension replaces it with a context-aware, rotating phrase:
+
+- **While a tool runs** — a tool-specific line: `Leyendo archivos…`,
+  `Ejecutando comandos…`, `Buscando en el código…`. MCP tools are named by
+  server (`Consultando un MCP…`).
+- **While a zero sub-agent runs** — the SDD phase it owns:
+  `Explorando el código…`, `Planeando la solución…`,
+  `Construyendo la implementación…`, `Revisando el veredicto…`.
+- **While the model thinks** — a rotation of playful verbs (`Maquinando…`,
+  `Rumiando…`, `Cocinando…`). Once a `/forge` run is detected the rotation
+  biases toward SDD vocabulary.
+
+It also installs a theme-tinted braille spinner that gently breathes through
+the palette's `dim`/`muted`/`accent` colours. The extension uses only pi's
+public extension API, and every handler is defensive — the indicator can never
+break a session.
+
 Control it with the `ZERO_BANNER` environment variable:
 
 | `ZERO_BANNER` | Effect |
 | ------------- | ------ |
-| _(unset)_ / `shimmer` | Animated shimmer sweep, then settle (default) |
-| `static` | Settled gradient only, no animation |
+| _(unset)_ / `shimmer` | Animated Tetris assembly, then settle (default) |
+| `static` | Completed Tetris banner only, no animation |
 | `off` | Render nothing |
 
 Colour is skipped automatically when `NO_COLOR` is set or the output is not a
 TTY.
 
+### Provider guard (`extensions/provider-guard.ts`)
+
+zero-pi watches model switches and steps in when you move to a metered
+provider. When you switch to a model on the `anthropic` provider — which bills
+per token and draws down your metered extra-usage pool — the guard offers to
+redirect you to the equivalent model on `pi-claude-cli`, the provider backed by
+your subscription's limits.
+
+The redirect is offered through a confirmation dialog, and that dialog is your
+escape hatch: say "yes" and the guard switches you to the subscription-backed
+equivalent; say "no" (or cancel) and you stay on the metered `anthropic`
+provider with no further nagging. When there is no equivalent model on
+`pi-claude-cli`, and when a model is restored on session start rather than
+switched deliberately, the guard skips the modal and just shows a one-line
+warning. Switching to a subscription provider is a complete no-op — no dialog,
+no notification, no noise.
+
+### Conversation resume (`extensions/conversation-resume.ts`)
+
+When pi exits normally, zero-pi writes a local handoff note:
+
+```
+.pi/zero-resume.md
+```
+
+The note includes the exact restore command for the persisted pi session:
+
+```bash
+pi --session '<session-file>'
+```
+
+When a session id is available it also writes the shorter form:
+
+```bash
+pi --session <session-id>
+```
+
+`pi --resume` is listed too for the interactive session picker. The file also
+keeps a concise conversation tail, enough to remember the last user intent and
+assistant progress without replacing pi's real session history.
+
+Generate it manually at any time:
+
+```text
+/zero-resume
+```
+
+The resume lives under `.pi/`, and zero-pi creates `.pi/.gitignore` so local
+conversation context is not accidentally committed.
+
 ## Relationship to `zero`
 
 `zero-pi` is the pi-specific layer of the **[zero](https://github.com/gonzalonicolasr/zero)**

package/extensions/conversation-resume.ts

@@ -0,0 +1,399 @@
+// zero-pi - conversation resume on shutdown.
+//
+// Pi already persists the full session in ~/.pi/agent/sessions. This extension
+// leaves a small project-local handoff note when the user quits pi, with the
+// exact command needed to restore that session plus a concise conversation tail.
+//
+// It intentionally avoids model calls during shutdown: quitting should stay
+// fast and reliable, even offline or without an API key.
+
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const RESUME_DIR = ".pi";
+const RESUME_FILE = "zero-resume.md";
+const DEFAULT_MAX_ITEMS = 12;
+const DEFAULT_MAX_CHARS = 1200;
+
+type NotifyType = "info" | "warning" | "error";
+
+interface ContentBlock {
+  type?: string;
+  text?: string;
+  thinking?: string;
+  name?: string;
+  arguments?: unknown;
+  mimeType?: string;
+}
+
+interface MessageLike {
+  role?: string;
+  content?: unknown;
+  command?: string;
+  output?: string;
+  summary?: string;
+  timestamp?: number;
+  customType?: string;
+}
+
+export interface SessionEntryLike {
+  type?: string;
+  id?: string;
+  timestamp?: string;
+  message?: MessageLike;
+  summary?: string;
+  tokensBefore?: number;
+}
+
+export interface ResumeMetadata {
+  cwd?: string;
+  generatedAt?: Date;
+  maxChars?: number;
+  maxItems?: number;
+  reason?: string;
+  sessionFile?: string;
+  sessionId?: string;
+}
+
+export interface ResumeItem {
+  label: string;
+  text: string;
+  timestamp?: string;
+}
+
+interface PiUI {
+  notify?(message: string, type?: NotifyType): void;
+}
+
+interface PiSessionManager {
+  getBranch?(): SessionEntryLike[];
+  getSessionFile?(): string | undefined;
+  getSessionId?(): string | undefined;
+}
+
+interface PiContext {
+  cwd?: string;
+  hasUI?: boolean;
+  ui?: PiUI;
+  sessionManager?: PiSessionManager;
+}
+
+interface PiCommandContext extends PiContext {}
+
+interface PiAPI {
+  on?(event: string, handler: (event: unknown, ctx: PiContext) => Promise<void> | void): void;
+  registerCommand?(
+    name: string,
+    options: {
+      description?: string;
+      handler: (args: string, ctx: PiCommandContext) => Promise<void> | void;
+    },
+  ): void;
+}
+
+/** Convert a shell argument into a single-quoted literal for PowerShell/sh. */
+export function quoteShellArg(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+/** The project-local resume path. */
+export function resumePath(cwd: string): string {
+  return join(cwd, RESUME_DIR, RESUME_FILE);
+}
+
+/** Extract readable text from pi message content blocks. */
+export function contentToText(content: unknown): string {
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+
+  const parts: string[] = [];
+  for (const raw of content) {
+    if (!raw || typeof raw !== "object") continue;
+    const block = raw as ContentBlock;
+    if (block.type === "text" && typeof block.text === "string") {
+      parts.push(block.text);
+      continue;
+    }
+    if (block.type === "toolCall" && typeof block.name === "string") {
+      parts.push(`[tool call: ${block.name}]`);
+      continue;
+    }
+    if (block.type === "image") {
+      parts.push(`[image${block.mimeType ? `: ${block.mimeType}` : ""}]`);
+    }
+  }
+  return parts.join("\n").trim();
+}
+
+function collapseWhitespace(text: string): string {
+  return text.replace(/\r\n/g, "\n").replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+function truncateText(text: string, maxChars: number): string {
+  const clean = collapseWhitespace(text);
+  if (clean.length <= maxChars) return clean;
+  return `${clean.slice(0, Math.max(0, maxChars - 15)).trimEnd()}\n...[truncated]`;
+}
+
+function timestampFromMessage(entry: SessionEntryLike): string | undefined {
+  if (entry.timestamp) return entry.timestamp;
+  const ts = entry.message?.timestamp;
+  return typeof ts === "number" ? new Date(ts).toISOString() : undefined;
+}
+
+function entryToResumeItem(entry: SessionEntryLike, maxChars: number): ResumeItem | null {
+  if (entry.type === "compaction" && typeof entry.summary === "string") {
+    return {
+      label: "Compaction",
+      text: truncateText(entry.summary, maxChars),
+      timestamp: entry.timestamp,
+    };
+  }
+
+  if (entry.type === "branch_summary" && typeof entry.summary === "string") {
+    return {
+      label: "Branch summary",
+      text: truncateText(entry.summary, maxChars),
+      timestamp: entry.timestamp,
+    };
+  }
+
+  if (entry.type !== "message" || !entry.message) return null;
+  const message = entry.message;
+  const role = message.role ?? "message";
+
+  if (role === "toolResult") return null;
+
+  if (role === "bashExecution") {
+    const command = typeof message.command === "string" ? message.command : "";
+    const output = typeof message.output === "string" ? message.output : "";
+    const text = [`$ ${command}`, output].filter(Boolean).join("\n");
+    return text
+      ? { label: "Shell", text: truncateText(text, maxChars), timestamp: timestampFromMessage(entry) }
+      : null;
+  }
+
+  if (role === "compactionSummary" && typeof message.summary === "string") {
+    return {
+      label: "Compaction",
+      text: truncateText(message.summary, maxChars),
+      timestamp: timestampFromMessage(entry),
+    };
+  }
+
+  const text = contentToText(message.content);
+  if (!text) return null;
+
+  const label =
+    role === "user"
+      ? "User"
+      : role === "assistant"
+        ? "Assistant"
+        : role === "custom"
+          ? `Custom${message.customType ? ` (${message.customType})` : ""}`
+          : role;
+
+  return { label, text: truncateText(text, maxChars), timestamp: timestampFromMessage(entry) };
+}
+
+/** Convert branch entries into the concise items shown in the resume note. */
+export function conversationItems(
+  entries: SessionEntryLike[],
+  maxChars = DEFAULT_MAX_CHARS,
+): ResumeItem[] {
+  return entries
+    .map((entry) => entryToResumeItem(entry, maxChars))
+    .filter((item): item is ResumeItem => item !== null);
+}
+
+function restoreCommands(sessionFile?: string, sessionId?: string): string[] {
+  const commands: string[] = [];
+  if (sessionFile) commands.push(`pi --session ${quoteShellArg(sessionFile)}`);
+  if (sessionId) commands.push(`pi --session ${sessionId}`);
+  commands.push("pi --resume");
+  return commands;
+}
+
+/** Render the project-local markdown resume. */
+export function buildConversationResume(
+  entries: SessionEntryLike[],
+  metadata: ResumeMetadata = {},
+): string {
+  const generatedAt = metadata.generatedAt ?? new Date();
+  const maxItems = metadata.maxItems ?? DEFAULT_MAX_ITEMS;
+  const maxChars = metadata.maxChars ?? DEFAULT_MAX_CHARS;
+  const items = conversationItems(entries, maxChars).slice(-maxItems);
+  const commands = restoreCommands(metadata.sessionFile, metadata.sessionId);
+
+  const lines: string[] = [
+    "# ZERO Pi Resume",
+    "",
+    "> Local handoff note. It may contain conversation context; keep `.pi/` out of commits.",
+    "",
+    "## Restore",
+    "",
+    "Exact command:",
+    "",
+    "```powershell",
+    commands[0],
+    "```",
+    "",
+  ];
+
+  if (metadata.sessionId) {
+    lines.push("Same session by id:", "", "```powershell", `pi --session ${metadata.sessionId}`, "```", "");
+  }
+
+  lines.push(
+    "Open the interactive picker:",
+    "",
+    "```powershell",
+    "pi --resume",
+    "```",
+    "",
+    "## Session",
+    "",
+    `- Updated: ${generatedAt.toISOString()}`,
+  );
+
+  if (metadata.reason) lines.push(`- Shutdown reason: ${metadata.reason}`);
+  if (metadata.cwd) lines.push(`- CWD: ${metadata.cwd}`);
+  if (metadata.sessionFile) lines.push(`- Session file: ${metadata.sessionFile}`);
+  if (metadata.sessionId) lines.push(`- Session id: ${metadata.sessionId}`);
+
+  lines.push("", "## Conversation Tail", "");
+
+  if (items.length === 0) {
+    lines.push("_No conversation messages were available yet._", "");
+  } else {
+    for (const item of items) {
+      const suffix = item.timestamp ? ` - ${item.timestamp}` : "";
+      lines.push(`### ${item.label}${suffix}`, "", item.text, "");
+    }
+  }
+
+  lines.push(
+    "## Continue Prompt",
+    "",
+    "Continue from this ZERO Pi resume. If you need the full context, run the restore command above first.",
+    "",
+  );
+
+  return `${lines.join("\n").replace(/\n{3,}/g, "\n\n")}\n`;
+}
+
+function ensureResumeDir(cwd: string): string {
+  const dir = join(cwd, RESUME_DIR);
+  mkdirSync(dir, { recursive: true });
+
+  const ignorePath = join(dir, ".gitignore");
+  if (!existsSync(ignorePath)) {
+    writeFileSync(ignorePath, "*\n!.gitignore\n", "utf8");
+  }
+
+  return dir;
+}
+
+/** Write the resume atomically and return the path written. */
+export function writeConversationResume(
+  cwd: string,
+  entries: SessionEntryLike[],
+  metadata: ResumeMetadata = {},
+): string {
+  const dir = ensureResumeDir(cwd);
+  const target = join(dir, RESUME_FILE);
+  const tmp = join(dir, `${RESUME_FILE}.tmp`);
+  const text = buildConversationResume(entries, metadata);
+  writeFileSync(tmp, text, "utf8");
+  renameSync(tmp, target);
+  return target;
+}
+
+function notify(ctx: PiContext, message: string, type: NotifyType): void {
+  try {
+    ctx.ui?.notify?.(message, type);
+  } catch {
+    // UI notifications are best-effort only.
+  }
+}
+
+function readBranch(ctx: PiContext): SessionEntryLike[] {
+  try {
+    return ctx.sessionManager?.getBranch?.() ?? [];
+  } catch {
+    return [];
+  }
+}
+
+function sessionFile(ctx: PiContext): string | undefined {
+  try {
+    return ctx.sessionManager?.getSessionFile?.();
+  } catch {
+    return undefined;
+  }
+}
+
+function sessionId(ctx: PiContext): string | undefined {
+  try {
+    return ctx.sessionManager?.getSessionId?.();
+  } catch {
+    return undefined;
+  }
+}
+
+function writeFromContext(ctx: PiContext, reason: string): string | null {
+  const cwd = ctx.cwd;
+  if (!cwd) return null;
+
+  const branch = readBranch(ctx);
+  if (branch.length === 0 && !sessionFile(ctx) && !sessionId(ctx)) return null;
+
+  return writeConversationResume(cwd, branch, {
+    cwd,
+    reason,
+    sessionFile: sessionFile(ctx),
+    sessionId: sessionId(ctx),
+  });
+}
+
+export default function register(pi?: PiAPI): void {
+  if (!pi) return;
+
+  if (typeof pi.on === "function") {
+    pi.on("session_shutdown", async (event, ctx) => {
+      const reason = (event as { reason?: string } | undefined)?.reason ?? "unknown";
+      if (reason !== "quit") return;
+      if (process.env.ZERO_RESUME === "off" || process.env.ZERO_RESUME === "0") return;
+
+      try {
+        const path = writeFromContext(ctx, reason);
+        if (path) notify(ctx, `zero resume written: ${path}`, "info");
+      } catch (err) {
+        notify(ctx, `zero resume failed: ${err instanceof Error ? err.message : String(err)}`, "warning");
+      }
+    });
+  }
+
+  if (typeof pi.registerCommand === "function") {
+    pi.registerCommand("zero-resume", {
+      description: "Write .pi/zero-resume.md with restore command and conversation tail",
+      handler: async (_args, ctx) => {
+        try {
+          const path = writeFromContext(ctx, "manual");
+          if (!path) {
+            notify(ctx, "zero-resume: no persisted session context found", "warning");
+            return;
+          }
+          const command = sessionFile(ctx)
+            ? `pi --session ${quoteShellArg(sessionFile(ctx)!)}`
+            : sessionId(ctx)
+              ? `pi --session ${sessionId(ctx)}`
+              : "pi --resume";
+          notify(ctx, `zero-resume: wrote ${path}\nrestore: ${command}`, "info");
+        } catch (err) {
+          notify(ctx, `zero-resume: ${err instanceof Error ? err.message : String(err)}`, "error");
+        }
+      },
+    });
+  }
+}

package/extensions/provider-guard-extension.ts

@@ -0,0 +1,195 @@
+// zero-pi — metered-provider guard, pi wiring.
+//
+// A thin pi extension that wires the pure decision logic in `provider-guard.ts`
+// to the `model_select` hook. Whenever pi reports a model switch, this handler
+// classifies it (in the pure module) and executes the resulting `GuardAction`:
+// a silent no-op for subscription providers, a non-blocking `warning` for a
+// metered provider with no equivalent (or a session `restore`), or — for a
+// deliberate switch to a metered provider that has an equivalent — a `confirm`
+// dialog offering to redirect to the subscription provider.
+//
+// All decisions live in `provider-guard.ts`; this file only declares the
+// minimal pi-API surface it uses, hooks `model_select`, and performs the I/O
+// (`confirm`/`notify`/`setModel`). Both `register` and the handler are wrapped
+// in a swallowing `try/catch` — exactly like `autotune-extension.ts`, a failure
+// must never break a pi session. The package stays dependency-free: only
+// `provider-guard.ts` is imported (no `node:*` is needed here, no third party).
+
+import {
+  classifyModelSwitch,
+  redirectFailedMessage,
+  type ModelLike,
+} from "./provider-guard.ts";
+
+// ---------------------------------------------------------------------------
+// Minimal local pi-API interfaces
+// ---------------------------------------------------------------------------
+//
+// `provider-guard-extension.ts` declares only the slice of pi's API it uses,
+// exactly like `autotune-extension.ts` and `zero-models.ts`. The guard never
+// depends on pi's full type surface — just the shapes below.
+
+/** The minimum a `Model` of pi must expose for the guard. Mirrors `ModelLike`
+ *  of the pure module — `setModel`/the registry both speak this shape. */
+interface PiModel {
+  provider: string;
+  id: string;
+}
+
+/** The model registry slice the guard uses: a `find` that resolves a model by
+ *  `(provider, id)` or returns `undefined` when no such model exists. */
+interface PiModelRegistry {
+  find(provider: string, modelId: string): PiModel | undefined;
+}
+
+/** The slice of pi's UI surface the guard uses. `confirm` may be sync or async
+ *  (pi versions differ); both are handled uniformly with `await`. */
+interface PiUI {
+  confirm(title: string, message: string): Promise<boolean> | boolean;
+  notify(message: string, type?: "info" | "warning" | "error"): void;
+}
+
+/** The context pi passes to a `model_select` handler. `modelRegistry` is
+ *  optional — if absent the guard degrades to warn-only (it can no longer
+ *  resolve equivalents) rather than breaking. */
+interface PiModelSelectContext {
+  ui: PiUI;
+  modelRegistry?: PiModelRegistry;
+}
+
+/** The `model_select` event pi emits on a model change. The guard only reads
+ *  `model` and `source`; `source` is `set`/`cycle`/`restore` or, defensively,
+ *  any other string a future pi version might report. */
+interface PiModelSelectEvent {
+  type: "model_select";
+  model?: PiModel;
+  source?: "set" | "cycle" | "restore" | string;
+}
+
+/** The slice of pi's extension API the guard uses: `on` to hook events and
+ *  `setModel` to apply a redirection. */
+interface PiExtensionAPI {
+  on(
+    event: string,
+    handler: (event: PiModelSelectEvent, ctx: PiModelSelectContext) => void | Promise<void>,
+  ): void;
+  setModel(model: PiModel): Promise<boolean>;
+}
+
+// ---------------------------------------------------------------------------
+// Handler
+// ---------------------------------------------------------------------------
+
+/**
+ * The `model_select` guard handler.
+ *
+ * Runs entirely inside `register`'s swallowing `try/catch`, but is also wrapped
+ * again here so no failure of `find`/`confirm`/`notify`/`setModel` can ever
+ * propagate out of a pi session. The flow:
+ *
+ *   1. Validate `event`/`event.model` — a malformed event returns cleanly.
+ *   2. Build the injected `lookup` over `ctx.modelRegistry.find`, wrapped in a
+ *      `try/catch` that returns `undefined`. If `modelRegistry` is absent,
+ *      degrade to an always-`undefined` lookup (warn-only).
+ *   3. `classifyModelSwitch(model, source, lookup)` → a `GuardAction`.
+ *   4. Execute the action: `ignore` → no-op; `warn` → `notify(..., "warning")`;
+ *      `offer-redirect` → `confirm`, and on a truthy answer `setModel` +
+ *      `notify(..., "info")` (or the failure notice if `setModel` returns
+ *      `false`). A falsy `confirm` leaves the user on the metered provider.
+ */
+async function handleModelSelect(
+  event: PiModelSelectEvent,
+  ctx: PiModelSelectContext,
+  pi: PiExtensionAPI,
+): Promise<void> {
+  try {
+    // 1. Malformed event — no event, no model, or no UI to talk to: bail out.
+    if (!event || !event.model || !ctx || !ctx.ui || typeof ctx.ui.notify !== "function") {
+      return;
+    }
+
+    // 2. Build the injected lookup. `classifyModelSwitch` assumes a total
+    //    lookup, so `find` is wrapped in a `try/catch` returning `undefined`.
+    //    If `modelRegistry` is absent the guard cannot resolve equivalents —
+    //    degrade to an always-`undefined` lookup so a metered provider still
+    //    produces a warning rather than breaking.
+    const registry = ctx.modelRegistry;
+    const lookup = (provider: string, id: string): ModelLike | undefined => {
+      if (!registry || typeof registry.find !== "function") return undefined;
+      try {
+        return registry.find(provider, id);
+      } catch {
+        // A registry lookup failure degrades to "no equivalent", never throws.
+        return undefined;
+      }
+    };
+
+    // 3. Classify the switch in the pure module.
+    const action = classifyModelSwitch(event.model, event.source, lookup);
+
+    // 4. Execute the action.
+    if (action.kind === "ignore") {
+      // Non-metered provider or malformed event — nothing to do.
+      return;
+    }
+
+    if (action.kind === "warn") {
+      // Metered provider with no equivalent, or a session `restore` — a single
+      // non-blocking warning, no modal, no `setModel`.
+      ctx.ui.notify(action.message, "warning");
+      return;
+    }
+
+    // action.kind === "offer-redirect" — deliberate switch to a metered
+    // provider that has a subscription equivalent. Offer the redirect; the
+    // `confirm` dialog itself is the user's escape (AC 1.5).
+    const accepted = await ctx.ui.confirm(action.confirmTitle, action.confirmMessage);
+    if (!accepted) {
+      // User declined or cancelled — leave them on the metered provider, no
+      // second warning, no `setModel`.
+      return;
+    }
+
+    const applied = await pi.setModel(action.safeModel);
+    if (applied) {
+      // Redirection took effect — confirm it with an `info` notification.
+      ctx.ui.notify(action.redirectMessage, "info");
+    } else {
+      // `setModel` returned `false`: the switch did not apply. Do not claim
+      // "redirected" — emit the optional failure notice instead.
+      ctx.ui.notify(
+        redirectFailedMessage(action.safeModel.id, action.safeModel.provider),
+        "warning",
+      );
+    }
+  } catch {
+    // Any failure of the guard must never break a pi session.
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+/**
+ * The pi extension entry point.
+ *
+ * pi calls this once when the extension loads. It wires the guard handler to
+ * the `model_select` event. The whole body is wrapped in a swallowing
+ * `try/catch`, and the handler is wrapped again, so neither registration nor a
+ * later failure can ever break a pi session. Called with no or an invalid
+ * `pi` (missing, or no `.on` function), it no-ops cleanly.
+ */
+export default function register(pi?: unknown): void {
+  try {
+    if (!pi || typeof (pi as PiExtensionAPI).on !== "function") {
+      return;
+    }
+    const api = pi as PiExtensionAPI;
+    api.on("model_select", (event: PiModelSelectEvent, ctx: PiModelSelectContext): Promise<void> => {
+      return handleModelSelect(event, ctx, api);
+    });
+  } catch {
+    // Registration itself must never break a pi session.
+  }
+}