pi-spark 0.3.1 → 0.5.0

package/README.md

@@ -6,11 +6,13 @@ 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.
 - **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).
+- **Set session name:** exposes a `set_session_name` tool so the agent can give the current session a concise, recognizable name in the session selector.
 
 ![Screenshot](./assets/screenshot.png)
 
@@ -32,6 +34,8 @@ pi install git:github.com/zlliang/pi-spark
 
 Spark reads config from `~/.pi/agent/spark.json` and from the current project’s `.pi/spark.json`. Project config overrides matching global fields.
 
+All extensions are enabled by default. Set a specific extension to `false` to disable it, for example, `"footer": false` disables the footer extension.
+
 Example:
 
 ```json
@@ -41,32 +45,57 @@ Example:
   },
   "footer": false,
   "presets": {
-    "gpt": {
-      "provider": "openai-codex",
-      "model": "gpt-5.5",
-      "thinkingLevel": "medium"
-    },
     "claude-opus": {
-      "provider": "anthropic",
       "model": "claude-opus-4-8",
+      "provider": "anthropic",
       "thinkingLevel": "high"
+    },
+    "gpt": {
+      "model": "gpt-5.5",
+      "provider": "openai-codex",
+      "thinkingLevel": "medium"
     }
   },
   "recap": {
     "idle": 180000,
-    "provider": "openai-codex",
     "model": "gpt-5.4-mini",
+    "provider": "openai-codex",
     "thinkingLevel": "off"
   }
 }
 ```
 
-Notes:
+### 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`, or `tildes`.
+
+### Footer
+
+- pi-spark replaces the footer with a compact one-line view of session metadata, extension statuses, cost, and context usage.
+
+### Fullscreen
+
+- 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.
+
+### Presets
+
+- Each key under `presets` defines a named model preset with `provider`, `model`, and optional `thinkingLevel` fields.
+
+Use presets in these ways:
+
+- Select interactively with `/preset` or `/preset <key>`
+- Start pi with a preset using `pi --preset <key>`
+- Cycle presets with `ctrl+super+p` and `ctrl+shift+super+p` (`super` is `command` on macOS)
+
+### 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`.
+
+### Set session name
 
-- Set an extension key to `false` to disable it.
-- The `editor.spinner` value can be `dots`, `lights`, or `tildes`.
-- Fullscreen enables Pi's `clearOnShrink` behavior programmatically so the pinned editor and footer stay aligned after taller UI components close.
-- Presets can be selected with `/preset` or `/preset <key>`.
-- Start pi with a preset using `pi --preset <key>`.
-- Cycle presets with `ctrl+super+p` and `ctrl+shift+super+p` (`super` is `command` on macOS).
-- The `recap.idle` value is in milliseconds and must be at least `5000`.
+- The agent can set or refresh the current session's display name and optionally give a reason.

package/extensions/codex-usage/client.ts

@@ -0,0 +1,69 @@
+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(`HTTP ${response.status}`);
+
+  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

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

package/extensions/codex-usage/index.ts

@@ -0,0 +1,43 @@
+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 hasCostedUsage(messages: AgentMessage[]): boolean {
+  return messages.some((message) => {
+    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("agent_end", (event, ctx) => {
+    if (!hasCostedUsage(event.messages)) return;
+
+    codexUsageManager?.refresh(ctx);
+  });
+
+  pi.on("session_shutdown", () => {
+    codexUsageManager = undefined;
+  });
+}

package/extensions/codex-usage/manager.ts

@@ -0,0 +1,47 @@
+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

@@ -0,0 +1,31 @@
+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("dim", LABEL)} ${theme.fg("warning", `usage unavailable: ${message}`)}`;
+}
+
+function renderLane(theme: Theme, label: string, percent: number | undefined): string {
+  const text = `${label} ${percent === undefined ? "?" : percent.toFixed(1)}%`;
+
+  if (percent && percent > 90) return theme.fg("error", text);
+  if (percent && percent > 70) return theme.fg("warning", text);
+  return theme.fg("dim", text);
+}

package/extensions/footer/index.ts

@@ -35,15 +35,11 @@ class FooterComponent implements Component {
   private getLeft(): string {
     const cwd = this.ctx.sessionManager.getCwd();
     const url = pathToFileURL(resolve(cwd));
-    let text = linkText(formatCwd(cwd, homedir()), url.href);
-
+    const cwdText = linkText(formatCwd(cwd, homedir()), url.href);
     const branch = this.footerData.getGitBranch();
-    if (branch) text = `${text} [${branch}]`;
-
     const sessionName = this.ctx.sessionManager.getSessionName();
-    if (sessionName) text = `${text} • ${sessionName}`;
 
-    return this.theme.fg("dim", text);
+    return this.theme.fg("dim", [cwdText, branch, sessionName].filter(Boolean).join(" • "));
   }
 
   private getRight(): string {

package/extensions/set-session-name/config.ts

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

package/extensions/set-session-name/index.ts

@@ -0,0 +1,95 @@
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+import { loadConfig } from "../shared/config";
+import { sanitizeText } from "../shared/format";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", (_event, ctx) => {
+    if (!ctx.hasUI) return;
+
+    const config = loadConfig(ctx, "setSessionName");
+    if (!config) return;
+
+    pi.registerTool({
+      name: "set_session_name",
+      label: "set session name",
+      description:
+        "Set or refresh the current session's display name, shown in the session selector " +
+        "instead of the first-message preview. Use this when a concise name would make the " +
+        "session easier to recognize later, such as after a long opening prompt or a substantial " +
+        "topic shift.",
+      promptSnippet: "Set or refresh the current session's concise display name",
+      promptGuidelines: [
+        "Use set_session_name when the session would benefit from a concise, recognizable name, especially after a long, vague, or pasted opening prompt.",
+        "Use set_session_name to refresh the name only after a substantial shift in the conversation's focus; do not rename for minor follow-ups.",
+        "Include a concise set_session_name reason when it would help explain why the name identifies the session.",
+      ],
+      parameters: Type.Object({
+        name: Type.String({
+          minLength: 1,
+          maxLength: 120,
+          description:
+            "Concise session display name. Use a short, recognizable phrase in sentence case, " +
+            "ideally <= 72 characters. Do not use surrounding quotes, trailing punctuation, or " +
+            "generic prefixes like \"Chat about\". Examples: \"Refactor auth module\", " +
+            "\"Debug flaky CI pipeline\", \"Draft Q3 planning doc\".",
+        }),
+        reason: Type.Optional(Type.String({
+          minLength: 1,
+          maxLength: 240,
+          description:
+            "Optional concise reason for naming or renaming the current session. Explain what " +
+            "made the name useful, such as a long pasted prompt, ambiguous first message, task " +
+            "handoff, or substantial topic shift. Write a complete sentence, and keep it brief " +
+            "and user-facing. Examples: \"The long pasted prompt needed a stable label.\", " +
+            "\"The focus shifted from debugging to README updates.\", " +
+            "\"The task migrated from a previous session.\"",
+        })),
+      }),
+      renderCall(args, theme) {
+        const name = sanitizeText(args.name);
+        const reason = sanitizeText(args.reason ?? "");
+
+        const container = new Container();
+        container.addChild(new Text(`${theme.bold(theme.fg("toolTitle", "set_session_name"))} ${theme.fg("accent", `"${name}"`)}`, 0, 0));
+
+        if (reason) {
+          container.addChild(new Spacer(1));
+          container.addChild(new Text(theme.fg("muted", reason), 0, 0));
+        }
+
+        return container;
+      },
+      renderResult(result, _options, theme, context) {
+        const output = result.content
+          .filter((content) => content.type === "text")
+          .map((content) => content.text)
+          .join("\n");
+
+        return new Text(context.isError ? theme.fg("error", "\n" + output) : "", 0, 0);
+      },
+      async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+        const name = sanitizeText(params.name);
+        if (!name) throw new Error("Session name was empty after normalization. Provide a short, non-empty phrase.");
+
+        const previous = pi.getSessionName() ?? null;
+        if (previous === name) {
+          return {
+            content: [{ type: "text", text: `Session is already named "${name}". No change.` }],
+            details: { changed: false, previous },
+          };
+        }
+
+        pi.setSessionName(name);
+
+        return {
+          content: [{ type: "text", text: `${previous ? `Renamed session from "${previous}" to "${name}".` : `Named session "${name}".`}` }],
+          details: { changed: true, previous },
+        };
+      },
+    });
+  });
+}

package/extensions/shared/config/schema.ts

@@ -1,17 +1,21 @@
 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 { recapConfigSchema } from "../../recap/config";
 import { presetsConfigSchema } from "../../presets/config";
+import { recapConfigSchema } from "../../recap/config";
+import { setSessionNameConfigSchema } from "../../set-session-name/config";
 
 export const configSchemas = {
+  codexUsage: codexUsageConfigSchema,
   editor: editorConfigSchema,
   footer: footerConfigSchema,
   fullscreen: fullscreenConfigSchema,
-  recap: recapConfigSchema,
   presets: presetsConfigSchema,
+  recap: recapConfigSchema,
+  setSessionName: setSessionNameConfigSchema,
 };
 
 export type ConfigField = keyof typeof configSchemas;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-spark",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "A small, opinionated collection of pi extensions",
   "keywords": [
     "pi-coding-agent",