pi-spark 0.11.2 → 0.13.0

package/README.md

@@ -1,40 +1,54 @@
+![Cover](./assets/cover.png)
+
 # pi-spark
 
-[Pi](https://pi.dev/) extensions that polish the daily experience.
+[Pi](https://pi.dev/) package that polishes your daily experience and keeps you at the frontier of agentic workflows.
 
-## Extensions
+## Features
 
-- **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).
+### Compact TUI: editor, footer, and fullscreen
 
-![Screenshot](./assets/screenshot.png)
+pi-spark ships with custom editor, footer, and fullscreen rendering, replacing the default ones. The compact TUI gives you a calm, immersive experience without distraction.
 
-## Install
+- The editor shows a working indicator inspired by [Amp](https://ampcode.com/) and the current model on the top border. If you use [presets](#presets), the active preset appears there too.
+- The footer shows session information, extension statuses, cost, and context usage on one line.
+- The fullscreen rendering clears the terminal screen and scrollback on session start and exit, and pins the editor and footer to the bottom.
 
-Install from npm:
+### Credits
 
-```bash
-pi install npm:pi-spark
-```
+pi-spark shows the active provider's credit balance or rate-limit usage in the status line, so you can keep an eye on what's left without leaving the terminal.
 
-For local development from this monorepo:
+- Supported providers: DeepSeek, Fireworks, Moonshot, OpenAI Codex, OpenRouter, and Vercel AI Gateway.
+- Most provider fetching follows [CodexBar](https://github.com/steipete/codexbar). Fireworks is the exception: its balance sits behind an internal gRPC API, reverse-engineered from the `firectl` binary (see [docs/fireworks.md](./docs/fireworks.md)).
 
-```bash
-pi install /path/to/pi-packages/packages/pi-spark
-```
+### Presets
+
+pi-spark lets you define named model presets in `spark.json` (see [Configuration](#configuration)), so you can switch between models and thinking levels without retyping provider details. The active preset is shown on the editor's top border.
+
+- Switch interactively with `/preset`, or jump straight to one with `/preset <name>`.
+- Start pi on a given preset with `pi --preset <name>`.
+- Cycle presets with `ctrl+super+p` (forward) and `ctrl+shift+super+p` (backward); `super` is `command` on macOS and needs a terminal that forwards it.
+
+### Recap
+
+pi-spark generates a short recap of the current session after it goes idle, or on demand, inspired by [Claude Code's session recap](https://code.claude.com/docs/en/interactive-mode#session-recap).
+
+- A recap is generated automatically once the session stays idle past `recap.idle` in `spark.json`.
+- Run `/recap` to generate one manually at any time.
+- The recap can use its own model, configured separately from your working model.
 
-## Configure
+### Agent tools: `name` and `model`
 
-Spark reads config from `~/.pi/agent/spark.json` and from the current project’s `.pi/spark.json`. Project config overrides matching global fields.
+pi-spark provides the pi coding agent with tools to inspect and manipulate itself. Currently, `name` and `model` tools are included.
 
-All extensions are enabled by default. Set a specific extension to `false` to disable it, for example, `"footer": false` disables the footer extension.
+- `name` sets or updates the current session's name.
+- `model` shows the active model or lists pi models.
 
-Example:
+## Configuration
+
+pi-spark reads config from `~/.pi/agent/spark.json` and from the current project's `.pi/spark.json`. Project config overrides matching global fields.
+
+For example:
 
 ```json
 {
@@ -63,56 +77,61 @@ Example:
 }
 ```
 
-### Editor
-
-- `editor.spinner` controls the working indicator style and can be `dots`, `lights`, `tildes`, or `pulse`.
-
-### Footer
-
-- pi-spark replaces the footer with a compact one-line view of session metadata, extension statuses, cost, and context usage.
+### References
 
-### Fullscreen
+All fields are optional. Each top-level feature runs with the defaults below unless you [turn it off](#turn-off-the-features-you-dont-like).
 
-- 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.
+| Field | Value (or `false`) | Description |
+| --- | --- | --- |
+| `credits` | `{}` | Shows the active provider's credit balance or rate-limit usage in the status line. |
+| `editor` | `EditorConfig` | Shows a working indicator and the current model on the editor's top border. |
+| `footer` | `{}` | Shows session info, extension statuses, cost, and context usage on one line. |
+| `fullscreen` | `{}` | Clears the screen and scrollback on start and exit, and pins the editor and footer to the bottom. |
+| `model` | `{}` | Exposes the `model` agent tool. |
+| `name` | `{}` | Exposes the `name` agent tool. |
+| `presets` | `{ [name]: Preset }` | Defines named model presets, keyed by name. |
+| `recap` | `RecapConfig` | Generates a session recap when idle or on demand. |
 
-### Models
+#### `EditorConfig`
 
-- The agent can call the `model` tool with two actions:
-  - `active`: gets the active provider, model, and thinking level.
-  - `list`: lists models with their metadata, with an optional [Liqe](https://github.com/gajus/liqe) (Lucene-like) `query` over model fields and `offset`/`limit` paging.
+The `spinner` field is optional and defaults to `tildes`.
 
-### Name
+| Field | Value | Description |
+| --- | --- | --- |
+| `spinner` | `dots` | `⠋, ⠙, ⠹, ⠸, ⠼, ⠴, ⠦, ⠧, ⠇, ⠏` |
+|  | `lights` | `○, ●` |
+|  | `tildes` (default) | `∼, ≈, ≋, ≈, ∼` |
+|  | `pulse` | `·, •, ●, •, ·` |
 
-- The agent can set or refresh the current session's name and optionally give a reason.
+#### `Preset`
 
-### Presets
+Each preset must set all three fields.
 
-- Each key under `presets` defines a named model preset with `provider`, `model`, and optional `thinkingLevel` fields.
+| Field | Value | Description |
+| --- | --- | --- |
+| `provider` | string | Provider id, e.g. `anthropic`. |
+| `model` | string | Model id, e.g. `claude-opus-4-8`. |
+| `thinkingLevel` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` | Thinking level for the preset. |
 
-Use presets in these ways:
+#### `RecapConfig`
 
-- 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)
+All fields are optional, including `thinkingLevel`.
 
-### Recap
+| Field | Value | Description |
+| --- | --- | --- |
+| `idle` | number (ms) or duration string | How long the session must stay idle before a recap is generated. Accepts a millisecond number or a [vercel/ms](https://github.com/vercel/ms) string (e.g. `"3m"`); minimum 5000 ms, defaults to 3 minutes. |
+| `provider` | string | Provider id for the recap model. |
+| `model` | string | Model id for the recap model. |
+| `thinkingLevel` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` | Thinking level for the recap model. |
 
-- pi-spark can generate a short recap after the session has been idle or when you run `/recap` manually.
-- 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`.
+### Turn off the features you don't like
 
-## Recommended pi settings
+All features are enabled by default. Set a specific feature to `false` in `spark.json` to disable it.
 
-[Pi 0.79.0](https://pi.dev/news/releases/0.79.0) added a project trust dialog that asks before loading project-local resources ([earendil-works/pi#5514](https://github.com/earendil-works/pi/issues/5514)), and [pi 0.79.1](https://pi.dev/news/releases/0.79.1) made the default behavior configurable via `defaultProjectTrust`. To keep startup minimal, set it to `"always"` in `~/.pi/agent/settings.json` (or change it with `/settings`):
+For example, to disable the customized footer:
 
 ```json
 {
-  "defaultProjectTrust": "always"
+  "footer": false
 }
 ```
-
-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
-
-See my [pi-packages](https://github.com/zlliang/pi-packages) repo for the full list.

package/index.ts

@@ -0,0 +1,31 @@
+import { autoCollectEvents } from "./src/events";
+import { registerCredits } from "./src/features/credits";
+import { registerEditor } from "./src/features/editor";
+import { registerFooter } from "./src/features/footer";
+import { registerFullscreen } from "./src/features/fullscreen";
+import { registerModel } from "./src/features/model";
+import { registerName } from "./src/features/name";
+import { registerPresets } from "./src/features/presets";
+import { registerRecap } from "./src/features/recap";
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+/**
+ * pi-spark is a single extension that bundles several features. Each feature registers itself
+ * like a standalone extension and reads its config via the shared, cached `loadConfig`. This file
+ * is just the registry that wires them together.
+ */
+export default function (pi: ExtensionAPI) {
+  // Own the event-bus subscription lifecycle here so features never manage cleanup themselves;
+  // the collector disposes every subscription on session_shutdown.
+  const events = autoCollectEvents(pi);
+
+  registerCredits(pi);
+  registerEditor(pi, events);
+  registerFooter(pi);
+  registerFullscreen(pi);
+  registerModel(pi);
+  registerName(pi);
+  registerPresets(pi);
+  registerRecap(pi);
+}

package/package.json

@@ -1,30 +1,36 @@
 {
   "name": "pi-spark",
-  "version": "0.11.2",
-  "description": "Pi extensions that polish the daily experience.",
+  "version": "0.13.0",
+  "description": "Pi package that polishes your daily experience and keeps you at the frontier of agentic workflows.",
   "keywords": [
     "pi-coding-agent",
     "pi-package"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/zlliang/pi-packages.git",
-    "directory": "packages/pi-spark"
+    "url": "git+https://github.com/zlliang/pi-spark.git"
   },
   "license": "MIT",
   "type": "module",
   "files": [
-    "extensions",
+    "index.ts",
+    "src",
     "assets",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "pi": {
     "extensions": [
-      "./extensions"
+      "./index.ts"
     ],
-    "image": "https://raw.githubusercontent.com/zlliang/pi-packages/main/assets/cover.png"
+    "image": "https://raw.githubusercontent.com/zlliang/pi-spark/main/assets/cover.png"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
+    "@grpc/grpc-js": "^1.14.4",
+    "@grpc/proto-loader": "^0.8.1",
     "liqe": "^3.8.7",
     "ms": "4.0.0-nightly.202508271359",
     "zod": "^4.4.3"
@@ -35,5 +41,14 @@
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "@types/node": "*",
+    "typebox": "*",
+    "typescript": "^6.0.3"
   }
-}
+}

package/{extensions/shared → src}/components/inline-text.ts

@@ -1,6 +1,6 @@
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
-import { sanitizeText } from "../format";
+import { sanitizeText } from "../utils/format";
 
 import type { Component } from "@earendil-works/pi-tui";
 

package/{extensions/shared → src}/config/index.ts

@@ -2,26 +2,51 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
-import { configSchemas } from "./schema";
+import { sparkConfigSchema } from "./schema";
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { ConfigField, ConfigValue } from "./schema";
+import type { SparkConfig } from "./schema";
 
 type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
 type JsonObject = { [key: string]: JsonValue };
 
-export function loadConfig<Field extends ConfigField>(ctx: ExtensionContext, field: Field, fileName: string = "spark.json"): ConfigValue<Field> | undefined {
-  const rawConfig = loadMergedJson(getConfigPaths(ctx.cwd, fileName));
-  const rawValue = rawConfig?.[field];
-  if (rawValue === false) return undefined;
-
-  const result = configSchemas[field].safeParse(rawValue === true || rawValue === undefined ? {} : rawValue);
-  if (result.success) return result.data as ConfigValue<Field>;
+/** All features disabled; used as the fallback when `spark.json` fails validation. */
+const DISABLED_CONFIG: SparkConfig = Object.freeze({
+  credits: false,
+  editor: false,
+  footer: false,
+  fullscreen: false,
+  model: false,
+  name: false,
+  presets: false,
+  recap: false,
+});
+
+const cache = new Map<string, SparkConfig>();
+
+/** Load and validate spark.json once per session lifecycle; later calls return the cached result. */
+export function loadConfig(ctx: ExtensionContext, fileName: string = "spark.json"): SparkConfig {
+  const key = `${ctx.cwd}\u0000${fileName}`;
+  const cached = cache.get(key);
+  if (cached) return cached;
+
+  const rawConfig = loadMergedJson(getConfigPaths(ctx.cwd, fileName)) ?? {};
+  const result = sparkConfigSchema.safeParse(rawConfig);
+
+  if (!result.success) {
+    const message = result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ");
+    ctx.ui.notify(`Invalid spark config: ${message}`, "error");
+
+    const config = DISABLED_CONFIG;
+    cache.set(key, config);
+
+    return config;
+  }
 
-  const message = result.error.issues.map((issue) => `${[field, ...issue.path].join(".")}: ${issue.message}`).join("; ");
-  ctx.ui.notify(`Invalid spark config: ${message}`, "error");
+  const config = result.data;
+  cache.set(key, config);
 
-  return undefined;
+  return config;
 }
 
 function getConfigPaths(cwd: string, fileName: string): [globalPath: string, projectPath: string] {

package/src/config/schema.ts

@@ -0,0 +1,30 @@
+import * as z from "zod";
+
+import { creditsConfigSchema } from "../features/credits/config";
+import { editorConfigSchema } from "../features/editor/config";
+import { footerConfigSchema } from "../features/footer/config";
+import { fullscreenConfigSchema } from "../features/fullscreen/config";
+import { modelConfigSchema } from "../features/model/config";
+import { nameConfigSchema } from "../features/name/config";
+import { presetsConfigSchema } from "../features/presets/config";
+import { recapConfigSchema } from "../features/recap/config";
+
+const disabled = z.literal(false);
+
+/**
+ * Each feature field is `{ ... } | false`: `false` disables the feature, an object configures
+ * it, and an omitted field falls back to defaults (`{}`, enabled).
+ */
+export const sparkConfigSchema = z.object({
+  credits: creditsConfigSchema.or(disabled).default({}),
+  editor: editorConfigSchema.or(disabled).default({}),
+  footer: footerConfigSchema.or(disabled).default({}),
+  fullscreen: fullscreenConfigSchema.or(disabled).default({}),
+  model: modelConfigSchema.or(disabled).default({}),
+  name: nameConfigSchema.or(disabled).default({}),
+  presets: presetsConfigSchema.or(disabled).default({}),
+  recap: recapConfigSchema.or(disabled).default({}),
+});
+
+/** Resolved config for every feature; `false` means the feature is disabled. */
+export type SparkConfig = z.infer<typeof sparkConfigSchema>;

package/{extensions/shared → src}/events/auto-collect-events.ts

@@ -1,6 +1,6 @@
 import type { ExtensionAPI, EventBus } from "@earendil-works/pi-coding-agent";
 
-class EventCollector {
+export class EventCollector {
   private pi: ExtensionAPI;
   private collected: Set<() => void> = new Set();
 

package/src/events/index.ts

@@ -0,0 +1,3 @@
+export { autoCollectEvents, EventCollector } from "./auto-collect-events";
+
+export * from "./preset";

package/src/features/credits/config.ts

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

package/src/features/credits/index.ts

@@ -0,0 +1,49 @@
+import { CreditsManager } from "./manager";
+import { loadConfig } from "../../config";
+import { isUsage } from "../../utils/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 function registerCredits(pi: ExtensionAPI): void {
+  let creditsManager: CreditsManager | undefined = undefined;
+
+  pi.on("session_start", (_event, ctx) => {
+    const config = loadConfig(ctx).credits;
+    if (!ctx.hasUI || !config) return;
+
+    creditsManager = new CreditsManager();
+    creditsManager.refresh(ctx);
+  });
+
+  pi.on("model_select", (_event, ctx) => {
+    creditsManager?.refresh(ctx);
+  });
+
+  pi.on("turn_end", (event, ctx) => {
+    if (!hasCost(event.message)) return;
+
+    creditsManager?.refresh(ctx);
+  });
+
+  pi.on("session_compact", (_event, ctx) => {
+    creditsManager?.refresh(ctx);
+  });
+
+  pi.on("session_tree", (event, ctx) => {
+    if (!event.summaryEntry) return;
+
+    creditsManager?.refresh(ctx);
+  });
+
+  pi.on("session_shutdown", () => {
+    creditsManager = undefined;
+  });
+}

package/src/features/credits/manager.ts

@@ -0,0 +1,64 @@
+import { findProvider } from "./providers";
+import { renderCredits, renderError } from "./status";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { CreditsProvider } from "./types";
+
+const STATUS_KEY = "credits";
+const REQUEST_TIMEOUT_MS = 30_000;
+
+export class CreditsManager {
+  private inflight: AbortController | undefined = undefined;
+  private currentProvider: string | undefined = undefined;
+
+  async refresh(ctx: ExtensionContext): Promise<void> {
+    this.inflight?.abort();
+
+    const provider = findProvider(ctx.model?.provider);
+    if (!provider) {
+      this.inflight = undefined;
+      this.currentProvider = undefined;
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+      return;
+    }
+
+    // Clear stale credits from another provider while the new fetch is in flight.
+    if (this.currentProvider !== provider.id) {
+      this.currentProvider = provider.id;
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+    }
+
+    const controller = new AbortController();
+    this.inflight = controller;
+
+    await this.fetch(ctx, provider, controller.signal).finally(() => {
+      if (this.inflight === controller) this.inflight = undefined;
+    });
+  }
+
+  private async fetch(ctx: ExtensionContext, provider: CreditsProvider, signal: AbortSignal): Promise<void> {
+    try {
+      const apiKey = await ctx.modelRegistry.getApiKeyForProvider(provider.id);
+      if (!apiKey) {
+        ctx.ui.setStatus(STATUS_KEY, undefined);
+        return;
+      }
+
+      const signals = [AbortSignal.timeout(REQUEST_TIMEOUT_MS), signal];
+      if (ctx.signal) signals.push(ctx.signal);
+
+      const credits = await provider.fetch(ctx, apiKey, AbortSignal.any(signals));
+
+      // The active model may have changed while the request was in flight.
+      if (ctx.model?.provider !== provider.id) return;
+
+      ctx.ui.setStatus(STATUS_KEY, renderCredits(ctx.ui.theme, provider.label, credits));
+    } catch (error) {
+      if (signal.aborted || ctx.signal?.aborted) return;
+      if (ctx.model?.provider !== provider.id) return;
+
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.setStatus(STATUS_KEY, renderError(ctx.ui.theme, provider.label, message));
+    }
+  }
+}

package/src/features/credits/providers/deepseek.ts

@@ -0,0 +1,36 @@
+import { convertToUSD, toNumber } from "../../../utils/format";
+
+import type { Credits, CreditsProvider } from "../types";
+
+const PROVIDER = "deepseek";
+const URL = "https://api.deepseek.com/user/balance";
+
+interface DeepSeekBalanceResponse {
+  balance_infos?: DeepSeekBalanceInfo[] | null;
+}
+
+interface DeepSeekBalanceInfo {
+  currency?: string;
+  total_balance?: string | number;
+}
+
+export const deepseekProvider: CreditsProvider = {
+  id: PROVIDER,
+  label: "DeepSeek",
+
+  async fetch(_ctx, apiKey, signal): Promise<Credits> {
+    const headers: Record<string, string> = {
+      Accept: "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    };
+
+    const response = await fetch(URL, { headers, signal });
+    if (!response.ok) throw new Error("request failed");
+
+    const payload = (await response.json()) as DeepSeekBalanceResponse;
+    const balance = payload.balance_infos?.find((entry) => entry.currency === "USD") ?? payload.balance_infos?.[0];
+    const remaining = await convertToUSD(toNumber(balance?.total_balance), balance?.currency, signal);
+
+    return { type: "balance", remaining };
+  },
+};

package/src/features/credits/providers/fireworks.proto

@@ -0,0 +1,42 @@
+syntax = "proto3";
+
+// Minimal slice of the Fireworks control-plane gateway API (`gateway.Gateway`), reconstructed from
+// the `firectl` binary. Only the messages and RPCs needed to read an account's credit balance are
+// declared here.
+package gateway;
+
+// Mirrors google.type.Money.
+message Money {
+  string currency_code = 1;
+  int64 units = 2;
+  int32 nanos = 3;
+}
+
+message Balance {
+  Money money = 1;
+}
+
+message GetBalanceRequest {
+  string name = 1; // resource name, e.g., "accounts/<account_id>"
+}
+
+message Account {
+  string name = 1; // resource name, e.g., "accounts/<account_id>"
+  string display_name = 2;
+}
+
+message ListAccountsRequest {
+  int32 page_size = 1;
+  string page_token = 2;
+}
+
+message ListAccountsResponse {
+  repeated Account accounts = 1;
+  string next_page_token = 2;
+  int32 total_size = 3;
+}
+
+service Gateway {
+  rpc ListAccounts(ListAccountsRequest) returns (ListAccountsResponse);
+  rpc GetBalance(GetBalanceRequest) returns (Balance);
+}