pi-spark 0.7.0 → 0.9.0

package/README.md

@@ -6,10 +6,10 @@ A small, opinionated collection of [pi](https://pi.dev/) extensions.
 
 ## Extensions
 
-- **Codex usage:** shows your OpenAI Codex (ChatGPT) rate-limit usage as a footer status when a Codex model is active.
 - **Editor:** replaces the default editor with a compact working indicator (inspired by [Amp](https://ampcode.com/)) and current model info.
 - **Footer:** shows session information, extension statuses, cost, and context usage on one line.
 - **Fullscreen:** clears the screen and scrollback on session start, pins the editor and footer to the bottom for a full-screen session, and clears again on exit.
+- **Models:** exposes a `model` tool so the agent can list the models the user can use currently and inspect the provider, model, and thinking level in use.
 - **Name:** exposes a `name` tool so the agent can give the current session a concise, recognizable name in the session selector.
 - **Presets:** switches named model presets with `/preset`, `--preset`, and quick cycle shortcuts.
 - **Recap:** generates a short idle-session recap and exposes a `/recap` command for manual generation, inspired by [Claude Code's session recap](https://code.claude.com/docs/en/interactive-mode#session-recap).
@@ -46,29 +46,25 @@ Example:
   "footer": false,
   "presets": {
     "claude-opus": {
-      "model": "claude-opus-4-8",
       "provider": "anthropic",
+      "model": "claude-opus-4-8",
       "thinkingLevel": "high"
     },
     "gpt": {
-      "model": "gpt-5.5",
       "provider": "openai-codex",
+      "model": "gpt-5.5",
       "thinkingLevel": "medium"
     }
   },
   "recap": {
-    "idle": 180000,
-    "model": "gpt-5.4-mini",
+    "idle": "5m",
     "provider": "openai-codex",
+    "model": "gpt-5.4-mini",
     "thinkingLevel": "off"
   }
 }
 ```
 
-### Codex usage
-
-- pi-spark queries the ChatGPT backend and shows your Codex 5-hour (`5h`) and 7-day (`7d`) rate-limit usage as a footer status, refreshing on session start, model change, and after billable turns. The status appears only while a Codex (`openai-codex`) model is active and uses its stored OAuth credential.
-
 ### Editor
 
 - `editor.spinner` controls the working indicator style and can be `dots`, `lights`, `tildes`, or `pulse`.
@@ -81,6 +77,12 @@ Example:
 
 - pi-spark clears the screen and scrollback at session start and exit, pins the editor and footer to the bottom, and enables pi's `clearOnShrink` behavior programmatically so pinned UI stays aligned after taller components close.
 
+### Models
+
+- The agent can call the `model` tool with two actions:
+  - `list`: gets all currently usable models with their metadata, with optional `provider` and `model` substring filters and `offset`/`limit` paging.
+  - `current`: gets the active provider, model, and thinking level.
+
 ### Name
 
 - The agent can set or refresh the current session's name and optionally give a reason.
@@ -98,7 +100,8 @@ Use presets in these ways:
 ### Recap
 
 - pi-spark can generate a short recap after the session has been idle or when you run `/recap` manually.
-- The `recap.idle` value is in milliseconds and must be at least `5000`. The recap model can be customized with `provider`, `model`, and `thinkingLevel`.
+- The `recap.idle` value sets how long the session must stay idle before a recap is generated. It accepts either a millisecond number or a human-readable duration string parsed by [vercel/ms](https://github.com/vercel/ms) (e.g., `"3m"`, `"30s"`, `"2 minutes"`), and must resolve to at least 5000ms.
+- The recap model can be customized with `provider`, `model`, and `thinkingLevel`.
 
 ## Recommended pi settings
 
@@ -111,3 +114,7 @@ Use presets in these ways:
 ```
 
 Project trust is an [input-loading guard](https://pi.dev/docs/latest/security#project-trust), so use `"always"` only if you trust the projects you open.
+
+## Other pi packages
+
+- [pi-credits](https://github.com/zlliang/pi-credits): shows the active provider's credit balance or rate-limit usage as a footer status.

package/extensions/models/config.ts

@@ -0,0 +1,3 @@
+import * as z from "zod";
+
+export const modelsConfigSchema = z.object({});

package/extensions/models/index.ts

@@ -0,0 +1,188 @@
+import { clampThinkingLevel, getSupportedThinkingLevels, StringEnum } from "@earendil-works/pi-ai";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, truncateHead } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+import { loadConfig } from "../shared/config";
+import { formatModel } from "../shared/format";
+
+import type { Api, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, TruncationResult } from "@earendil-works/pi-coding-agent";
+
+/** Pi's built-in default thinking level, clamped per model. Not exported by pi's public API. */
+const DEFAULT_THINKING_LEVEL: ModelThinkingLevel = "medium";
+
+type ModelMetadata = Omit<Model<Api>, "headers" | "compat"> & {
+  thinkingLevels: ModelThinkingLevel[];
+  defaultThinkingLevel: ModelThinkingLevel;
+};
+
+type ModelToolDetails =
+  | { action: "current"; current: { model: ModelMetadata; thinkingLevel: ModelThinkingLevel } }
+  | { action: "list"; models: ModelMetadata[]; total: number; truncation?: TruncationResult }
+
+function toMetadata(model: Model<Api>): ModelMetadata {
+  const { headers: _headers, compat: _compat, ...metadata } = model;
+
+  return {
+    ...metadata,
+    thinkingLevels: getSupportedThinkingLevels(model),
+    defaultThinkingLevel: clampThinkingLevel(model, DEFAULT_THINKING_LEVEL),
+  };
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", (_event, ctx) => {
+    const config = loadConfig(ctx, "models");
+    if (!config) return;
+
+    pi.registerTool({
+      name: "model",
+      label: "model",
+      description:
+        "Inspect pi's model state. The \"current\" action returns the active model with metadata " +
+        "and thinking level. The \"list\" action returns all models the user can use " +
+        "currently (auth configured), including metadata such as provider, id, name, API type, " +
+        "reasoning support, input modalities, cost, context window, and max output tokens. " +
+        "Lists can be filtered with provider/model queries and paged with offset/limit. " +
+        `List output is one JSON object per line, truncated to ${DEFAULT_MAX_LINES} models or ` +
+        `${DEFAULT_MAX_BYTES / 1024}KB (whichever is hit first).`,
+      promptSnippet: "List available models or show the current model in use",
+      promptGuidelines: [
+        "Use model when the user asks which models are available in pi or which model and thinking level are currently in use.",
+      ],
+      parameters: Type.Object({
+        action: StringEnum(["list", "current"] as const, {
+          description:
+            "\"list\" returns all currently usable models with metadata; " +
+            "\"current\" returns the active model with metadata and thinking level.",
+        }),
+        provider: Type.Optional(Type.String({
+          description: "For list: filter by provider, case-insensitive substring (e.g., \"vercel\", \"moonshot\")",
+        })),
+        model: Type.Optional(Type.String({
+          description: "For list: filter by model id or display name, case-insensitive substring (e.g., \"claude\", \"deepseek\")",
+        })),
+        offset: Type.Optional(Type.Number({
+          description: "For list: model number to start from (1-indexed)"
+        })),
+        limit: Type.Optional(Type.Number({
+          description: "For list: maximum number of models to return"
+        })),
+      }),
+      renderCall(args, theme) {
+        let text = `${theme.bold(theme.fg("toolTitle", "model"))} ${theme.fg("accent", args.action)}`;
+
+        if (args.provider) text += theme.fg("muted", ` provider:${args.provider}`);
+        if (args.model) text += theme.fg("muted", ` model:${args.model}`);
+        if (args.offset !== undefined || args.limit !== undefined) text += theme.fg("warning", ` from:${args.offset ?? 1}`);
+        if (args.limit !== undefined) text += theme.fg("warning", ` to:${(args.offset ?? 1) + args.limit - 1}`);
+
+        return new Text(text, 0, 0);
+      },
+      renderResult(result, { expanded }, theme, context) {
+        const details = result.details as ModelToolDetails | undefined;
+
+        const container = new Container();
+        container.addChild(new Spacer(1));
+
+        if (context.isError || !details) {
+          const output = result.content
+            .filter((content) => content.type === "text")
+            .map((content) => content.text)
+            .join("\n");
+          container.addChild(new Text(theme.fg("error", output), 0, 0));
+
+          return container;
+        }
+
+        if (details.action === "current") {
+          const { model, thinkingLevel } = details.current;
+          container.addChild(new Text(theme.fg("muted", formatModel(model.provider, model.id, thinkingLevel)), 0, 0));
+
+          return container;
+        }
+
+        const filtered = context.args.provider !== undefined || context.args.model !== undefined;
+        const models = details.models ?? [];
+        const total = details.total ?? models.length;
+
+        if (expanded) {
+          models.forEach((model) => {
+            container.addChild(new Text(theme.fg("muted", formatModel(model.provider, model.id)), 0, 0));
+          });
+
+          container.addChild(new Spacer(1));
+        }
+
+        const summary = `${models.length !== total ? `${models.length} of ` : ""}${total} ${filtered ? "matched" : "available"} model${total === 1 ? "" : "s"} listed`;
+        container.addChild(new Text(theme.fg("muted", summary) + (details.truncation?.truncated ? theme.fg("warning", " (truncated)") : ""), 0, 0));
+
+        return container;
+      },
+      async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        if (params.action === "current") {
+          const model = ctx.model;
+          if (!model) throw new Error("No model is currently selected.");
+
+          const thinkingLevel = pi.getThinkingLevel();
+          const current = { model: toMetadata(model), thinkingLevel };
+
+          return {
+            content: [{ type: "text", text: JSON.stringify(current) }],
+            details: { action: "current", current } satisfies ModelToolDetails,
+          };
+        }
+
+        const providerQuery = params.provider?.trim().toLowerCase();
+        const modelQuery = params.model?.trim().toLowerCase();
+        const filtered = providerQuery !== undefined || modelQuery !== undefined;
+
+        const matched = ctx.modelRegistry.getAvailable().filter((model) => {
+          if (providerQuery && !model.provider.toLowerCase().includes(providerQuery)) return false;
+          if (modelQuery && !model.id.toLowerCase().includes(modelQuery) && !model.name.toLowerCase().includes(modelQuery)) return false;
+          return true;
+        }).map(toMetadata);
+        const total = matched.length;
+
+        if (total === 0) {
+          return {
+            content: [{ type: "text", text: `0 models ${filtered ? "matched" : "available"}.` }],
+            details: { action: "list", models: [], total } satisfies ModelToolDetails,
+          };
+        }
+
+        // Convert from 1-indexed offset to 0-indexed array access.
+        const startIndex = params.offset ? Math.max(0, params.offset - 1) : 0;
+        if (startIndex >= total) {
+          throw new Error(`Offset ${params.offset} is beyond end of list (${total} models total).`);
+        }
+
+        const endIndex = params.limit !== undefined ? Math.min(startIndex + params.limit, total) : total;
+        const selected = matched.slice(startIndex, endIndex);
+
+        // JSONL: one compact object per line, so truncation cuts at record boundaries.
+        const truncation = truncateHead(selected.map((model) => JSON.stringify(model)).join("\n"), {
+          maxLines: DEFAULT_MAX_LINES,
+          maxBytes: DEFAULT_MAX_BYTES,
+        });
+
+        const delivered = truncation.truncated ? selected.slice(0, truncation.outputLines) : selected;
+        const endDisplay = startIndex + delivered.length;
+        const nextOffset = endDisplay + 1;
+
+        let text = truncation.content;
+        if (truncation.truncated) {
+          text += `\n\n[Truncated: showing models ${startIndex + 1}-${endDisplay} of ${total}; use offset=${nextOffset} to continue]`;
+        } else if (endDisplay < total) {
+          text += `\n\n[${total - endDisplay} more models in list; use offset=${nextOffset} to continue]`;
+        }
+
+        return {
+          content: [{ type: "text", text }],
+          details: { action: "list", models: delivered, total, truncation } satisfies ModelToolDetails,
+        };
+      },
+    });
+  });
+}

package/extensions/recap/idle.ts

@@ -1,6 +1,32 @@
+import { ms } from "ms";
 import * as z from "zod";
 
-export const idleTimeoutSchema = z.number().min(5000);
+import type { StringValue } from "ms";
+
+const MIN_IDLE_MS = 5_000;
+
+/** Accept a millisecond number or a human-readable duration (e.g., "3m"), normalized to milliseconds. */
+export const idleTimeoutSchema = z
+  .union([z.number(), z.string()])
+  .transform((value, ctx) => {
+    if (typeof value === "number") return value;
+
+    let parsed: number;
+    try {
+      parsed = ms(value as StringValue);
+    } catch (error) {
+      ctx.addIssue({ code: "custom", message: error instanceof Error ? error.message : String(error) });
+      return z.NEVER;
+    }
+
+    if (Number.isNaN(parsed)) {
+      ctx.addIssue({ code: "custom", message: `Value is not a valid duration. value=${JSON.stringify(value)}` });
+      return z.NEVER;
+    }
+
+    return parsed;
+  })
+  .pipe(z.number().min(MIN_IDLE_MS));
 
 type IdleTimeout = z.infer<typeof idleTimeoutSchema>;
 type IdleHash = string | number | boolean;

package/extensions/shared/config/schema.ts

@@ -1,18 +1,18 @@
 import * as z from "zod";
 
-import { codexUsageConfigSchema } from "../../codex-usage/config";
 import { editorConfigSchema } from "../../editor/config";
 import { footerConfigSchema } from "../../footer/config";
 import { fullscreenConfigSchema } from "../../fullscreen/config";
+import { modelsConfigSchema } from "../../models/config";
 import { nameConfigSchema } from "../../name/config";
 import { presetsConfigSchema } from "../../presets/config";
 import { recapConfigSchema } from "../../recap/config";
 
 export const configSchemas = {
-  codexUsage: codexUsageConfigSchema,
   editor: editorConfigSchema,
   footer: footerConfigSchema,
   fullscreen: fullscreenConfigSchema,
+  models: modelsConfigSchema,
   name: nameConfigSchema,
   presets: presetsConfigSchema,
   recap: recapConfigSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-spark",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "A small, opinionated collection of pi extensions",
   "keywords": [
     "pi-coding-agent",
@@ -28,6 +28,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "ms": "4.0.0-nightly.202508271359",
     "zod": "^4.4.3"
   },
   "peerDependencies": {

package/extensions/codex-usage/client.ts

@@ -1,69 +0,0 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
-export const CODEX_PROVIDER = "openai-codex";
-const USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
-const REQUEST_TIMEOUT_MS = 30_000;
-
-/** Normalized Codex usage with rate-limit windows reduced to used percentages. */
-export interface CodexUsage {
-  unlimited: boolean;
-  /** Used percentage of the 5-hour window, clamped to 0-100. */
-  primaryPercent: number | undefined;
-  /** Used percentage of the 7-day window, clamped to 0-100. */
-  secondaryPercent: number | undefined;
-}
-
-interface CodexUsageResponse {
-  rate_limit?: {
-    primary_window?: CodexRateWindow | null;
-    secondary_window?: CodexRateWindow | null;
-  } | null;
-  credits?: {
-    unlimited?: boolean;
-  } | null;
-}
-
-interface CodexRateWindow {
-  used_percent?: number | string;
-}
-
-/** Read the ChatGPT account id from the stored Codex OAuth credential, if present. */
-export function readAccountId(ctx: ExtensionContext): string | undefined {
-  const credential = ctx.modelRegistry.authStorage.get(CODEX_PROVIDER) as { accountId?: string } | undefined;
-  const accountId = credential?.accountId;
-
-  return typeof accountId === "string" && accountId.trim() ? accountId.trim() : undefined;
-}
-
-/** Fetch and normalize Codex usage, aborting on timeout or when the parent signal aborts. */
-export async function fetchCodexUsage(token: string, accountId?: string, parentSignal?: AbortSignal): Promise<CodexUsage> {
-  const signals = [AbortSignal.timeout(REQUEST_TIMEOUT_MS)];
-  if (parentSignal) signals.push(parentSignal);
-
-  const headers: Record<string, string> = {
-    Accept: "application/json",
-    Authorization: `Bearer ${token}`,
-  };
-  if (accountId) headers["ChatGPT-Account-Id"] = accountId;
-
-  const response = await fetch(USAGE_URL, { method: "GET", headers, signal: AbortSignal.any(signals) });
-  if (!response.ok) throw new Error("request failed");
-
-  return normalizeUsage((await response.json()) as CodexUsageResponse);
-}
-
-function normalizeUsage(payload: CodexUsageResponse): CodexUsage {
-  return {
-    unlimited: payload.credits?.unlimited === true,
-    primaryPercent: parseUsedPercent(payload.rate_limit?.primary_window),
-    secondaryPercent: parseUsedPercent(payload.rate_limit?.secondary_window),
-  };
-}
-
-function parseUsedPercent(window: CodexRateWindow | null | undefined): number | undefined {
-  const raw = window?.used_percent;
-  if (raw === undefined || raw === null) return undefined;
-
-  const value = typeof raw === "number" ? raw : Number(raw);
-  return Number.isFinite(value) ? Math.min(100, Math.max(0, value)) : undefined;
-}

package/extensions/codex-usage/config.ts

@@ -1,5 +0,0 @@
-import * as z from "zod";
-
-export const codexUsageConfigSchema = z.object({});
-
-export type CodexUsageConfig = z.infer<typeof codexUsageConfigSchema>;

package/extensions/codex-usage/index.ts

@@ -1,51 +0,0 @@
-import { CodexUsageManager } from "./manager";
-import { loadConfig } from "../shared/config";
-import { isUsage } from "../shared/usage";
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import type { AgentMessage } from "@earendil-works/pi-agent-core";
-
-function hasCost(message: AgentMessage): boolean {
-  const usage = (message as { usage?: unknown }).usage;
-  if (!isUsage(usage)) return false;
-
-  return usage.cost.total > 0 || usage.input > 0 || usage.output > 0;
-}
-
-export default function (pi: ExtensionAPI) {
-  let codexUsageManager: CodexUsageManager | undefined = undefined;
-
-  pi.on("session_start", (_event, ctx) => {
-    if (!ctx.hasUI) return;
-
-    const config = loadConfig(ctx, "codexUsage");
-    if (!config) return;
-
-    codexUsageManager = new CodexUsageManager();
-    codexUsageManager.refresh(ctx);
-  });
-
-  pi.on("model_select", (_event, ctx) => {
-    codexUsageManager?.refresh(ctx);
-  });
-
-  pi.on("turn_end", (event, ctx) => {
-    if (!hasCost(event.message)) return;
-
-    codexUsageManager?.refresh(ctx);
-  });
-
-  pi.on("session_compact", (_event, ctx) => {
-    codexUsageManager?.refresh(ctx);
-  });
-
-  pi.on("session_tree", (event, ctx) => {
-    if (!event.summaryEntry) return;
-
-    codexUsageManager?.refresh(ctx);
-  });
-
-  pi.on("session_shutdown", () => {
-    codexUsageManager = undefined;
-  });
-}

package/extensions/codex-usage/manager.ts

@@ -1,47 +0,0 @@
-import { CODEX_PROVIDER, fetchCodexUsage, readAccountId } from "./client";
-import { renderError, renderUsage } from "./status";
-
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
-const STATUS_KEY = "codex-usage";
-
-export class CodexUsageManager {
-  private inflight: Promise<void> | undefined = undefined;
-
-  async refresh(ctx: ExtensionContext): Promise<void> {
-    if (!this.isCodexContext(ctx)) {
-      ctx.ui.setStatus(STATUS_KEY, undefined);
-      return;
-    }
-
-    if (this.inflight) return this.inflight;
-
-    this.inflight = this.fetch(ctx).finally(() => {
-      this.inflight = undefined;
-    });
-
-    return this.inflight;
-  }
-
-  private async fetch(ctx: ExtensionContext): Promise<void> {
-    try {
-      const token = await ctx.modelRegistry.getApiKeyForProvider(CODEX_PROVIDER);
-      if (!token) {
-        ctx.ui.setStatus(STATUS_KEY, undefined);
-        return;
-      }
-
-      const usage = await fetchCodexUsage(token, readAccountId(ctx), ctx.signal);
-      if (!this.isCodexContext(ctx)) return;
-
-      ctx.ui.setStatus(STATUS_KEY, renderUsage(ctx.ui.theme, usage));
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      ctx.ui.setStatus(STATUS_KEY, renderError(ctx.ui.theme, message));
-    }
-  }
-
-  private isCodexContext(ctx: ExtensionContext): boolean {
-    return ctx.model?.provider === CODEX_PROVIDER;
-  }
-}

package/extensions/codex-usage/status.ts

@@ -1,31 +0,0 @@
-import type { Theme } from "@earendil-works/pi-coding-agent";
-
-import type { CodexUsage } from "./client";
-
-const LABEL = "Codex";
-
-/** Render a footer status string for normalized Codex usage. */
-export function renderUsage(theme: Theme, usage: CodexUsage): string {
-  const label = theme.fg("dim", LABEL);
-
-  if (usage.unlimited || (usage.primaryPercent === undefined && usage.secondaryPercent === undefined)) {
-    return `${label} ${theme.fg("success", "unlimited")}`;
-  }
-
-  const fiveHour = renderLane(theme, "5h", usage.primaryPercent);
-  const sevenDay = renderLane(theme, "7d", usage.secondaryPercent);
-  return `${label} ${fiveHour} ${sevenDay}`;
-}
-
-/** Render a footer status string for a usage fetch error. */
-export function renderError(theme: Theme, message: string): string {
-  return theme.fg("error", `${LABEL} usage unavailable: ${message}`);
-}
-
-function renderLane(theme: Theme, label: string, percent?: number): string {
-  const text = `${label} ${percent === undefined ? "?" : percent.toFixed(0)}%`;
-
-  if (percent && percent > 90) return theme.fg("error", text);
-  if (percent && percent > 70) return theme.fg("warning", text);
-  return theme.fg("dim", text);
-}