pi-spark 0.12.0 → 0.13.1

package/README.md

@@ -2,46 +2,68 @@
 
 # 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
+![Overview](./assets/screenshot-overview.png)
 
-- **Credits:** shows the active provider's credit balance or rate-limit usage in the status line.
-- **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).
+## Features
 
-![Screenshot](./assets/screenshot.png)
+### Compact TUI: editor, footer, and fullscreen
 
-## Install
+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 from npm:
+- 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.
 
-```bash
-pi install npm:pi-spark
-```
+![Compact TUI](./assets/screenshot-tui.png)
+
+### Credits
 
-For local development from this repo:
+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.
 
-```bash
-pi install /path/to/pi-spark
-```
+- 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)).
+
+![Credits](./assets/screenshot-credits.png)
+
+### 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.
+
+![Presets](./assets/screenshot-presets.png)
+
+### 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
+![Recap](./assets/screenshot-recap.png)
 
-Spark reads config from `~/.pi/agent/spark.json` and from the current project’s `.pi/spark.json`. Project config overrides matching global fields.
+### Agent tools: `name` and `model`
 
-All extensions are enabled by default. Set a specific extension to `false` to disable it, for example, `"footer": false` disables the footer extension.
+pi-spark provides the pi coding agent with tools to inspect and manipulate itself. Currently, `name` and `model` tools are included.
 
-Example:
+- `name` sets or updates the current session's name.
+- `model` shows the active model or lists pi models.
+
+![Agent tools](./assets/screenshot-tools.png)
+
+## 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
 {
-  "credits": false,
   "editor": {
     "spinner": "dots"
   },
@@ -67,58 +89,61 @@ Example:
 }
 ```
 
-### Credits
-
-- pi-spark shows the active provider's credit balance or rate-limit usage in the status line.
-- Supported providers: DeepSeek, Fireworks, Moonshot, OpenAI Codex, OpenRouter, and Vercel AI Gateway.
-- Most provider-specific fetching approaches reference [CodexBar](https://github.com/steipete/codexbar). Fireworks is an exception: its balance lives behind an internal gRPC API, so the approach was reverse-engineered from the `firectl` binary — see [docs/fireworks.md](./docs/fireworks.md).
-
-### Editor
-
-- `editor.spinner` controls the working indicator style and can be `dots`, `lights`, `tildes`, or `pulse`.
+### References
 
-### Footer
+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 replaces the footer with a compact one-line view of session metadata, extension statuses, cost, and context usage.
+| 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. |
 
-### Fullscreen
+#### `EditorConfig`
 
-- 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.
+The `spinner` field is optional and defaults to `tildes`.
 
-### Models
+| Field | Value | Description |
+| --- | --- | --- |
+| `spinner` | `dots` | `⠋, ⠙, ⠹, ⠸, ⠼, ⠴, ⠦, ⠧, ⠇, ⠏` |
+|  | `lights` | `○, ●` |
+|  | `tildes` (default) | `∼, ≈, ≋, ≈, ∼` |
+|  | `pulse` | `·, •, ●, •, ·` |
 
-- 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.
+#### `Preset`
 
-### Name
+Each preset must set all three fields.
 
-- The agent can set or refresh the current session's name and optionally give a reason.
+| 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. |
 
-### Presets
+#### `RecapConfig`
 
-- Each key under `presets` defines a named model preset with `provider`, `model`, and optional `thinkingLevel` fields.
+All fields are optional, including `thinkingLevel`.
 
-Use presets in these ways:
+| 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. |
 
-- 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)
+### Turn off the features you don't like
 
-### Recap
+All features are enabled by default. Set a specific feature to `false` in `spark.json` to disable it.
 
-- 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`.
-
-## Recommended pi settings
-
-[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.

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,7 +1,7 @@
 {
   "name": "pi-spark",
-  "version": "0.12.0",
-  "description": "Pi extensions that polish the daily experience.",
+  "version": "0.13.1",
+  "description": "Pi package that polishes your daily experience and keeps you at the frontier of agentic workflows.",
   "keywords": [
     "pi-coding-agent",
     "pi-package"
@@ -13,14 +13,15 @@
   "license": "MIT",
   "type": "module",
   "files": [
-    "extensions",
+    "index.ts",
+    "src",
     "assets",
     "README.md",
     "LICENSE"
   ],
   "pi": {
     "extensions": [
-      "./extensions"
+      "./index.ts"
     ],
     "image": "https://raw.githubusercontent.com/zlliang/pi-spark/main/assets/cover.png"
   },

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/{extensions → src/features}/credits/index.ts

@@ -1,6 +1,6 @@
 import { CreditsManager } from "./manager";
-import { isUsage } from "./utils";
-import { loadConfig } from "../shared/config";
+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";
@@ -12,14 +12,12 @@ function hasCost(message: AgentMessage): boolean {
   return usage.cost.total > 0 || usage.input > 0 || usage.output > 0;
 }
 
-export default function (pi: ExtensionAPI) {
+export function registerCredits(pi: ExtensionAPI): void {
   let creditsManager: CreditsManager | undefined = undefined;
 
   pi.on("session_start", (_event, ctx) => {
-    if (!ctx.hasUI) return;
-
-    const config = loadConfig(ctx, "credits");
-    if (!config) return;
+    const config = loadConfig(ctx).credits;
+    if (!ctx.hasUI || !config) return;
 
     creditsManager = new CreditsManager();
     creditsManager.refresh(ctx);

package/{extensions → src/features}/credits/providers/deepseek.ts

@@ -1,4 +1,4 @@
-import { convertToUSD, toNumber } from "../utils";
+import { convertToUSD, toNumber } from "../../../utils/format";
 
 import type { Credits, CreditsProvider } from "../types";
 

package/{extensions → src/features}/credits/providers/fireworks.ts

@@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url";
 import { credentials, loadPackageDefinition, Metadata } from "@grpc/grpc-js";
 import { loadSync } from "@grpc/proto-loader";
 
-import { toNumber } from "../utils";
+import { toNumber } from "../../../utils/format";
 
 import type { ClientUnaryCall, ServiceClientConstructor, ServiceError } from "@grpc/grpc-js";
 import type { Credits, CreditsProvider } from "../types";

package/{extensions → src/features}/credits/providers/moonshot.ts

@@ -1,4 +1,4 @@
-import { convertToUSD, toNumber } from "../utils";
+import { convertToUSD, toNumber } from "../../../utils/format";
 
 import type { Credits, CreditsProvider } from "../types";
 

package/{extensions → src/features}/credits/providers/openai-codex.ts

@@ -1,4 +1,4 @@
-import { toNumber } from "../utils";
+import { toNumber } from "../../../utils/format";
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { Credits, CreditsProvider } from "../types";

package/{extensions → src/features}/credits/providers/openrouter.ts

@@ -1,4 +1,4 @@
-import { toNumber } from "../utils";
+import { toNumber } from "../../../utils/format";
 
 import type { Credits, CreditsProvider } from "../types";
 

package/{extensions → src/features}/credits/providers/vercel-ai-gateway.ts

@@ -1,4 +1,4 @@
-import { toNumber } from "../utils";
+import { toNumber } from "../../../utils/format";
 
 import type { Credits, CreditsProvider } from "../types";
 

package/{extensions → src/features}/editor/index.ts

@@ -1,13 +1,14 @@
 import { CustomEditor } from "@earendil-works/pi-coding-agent";
 
 import { Spinner } from "./spinner";
-import { SplitLine } from "../shared/components/split-line";
-import { loadConfig } from "../shared/config";
-import { autoCollectEvents, PRESET_CHANGE, parsePresetChange } from "../shared/events";
-import { formatModel } from "../shared/format";
+import { SplitLine } from "../../components/split-line";
+import { loadConfig } from "../../config";
+import { PRESET_CHANGE, parsePresetChange } from "../../events";
+import { formatModel } from "../../utils/format";
 
 import type { ExtensionAPI, ExtensionContext, KeybindingsManager } from "@earendil-works/pi-coding-agent";
 import type { TUI, EditorTheme } from "@earendil-works/pi-tui";
+import type { EventCollector } from "../../events";
 
 class Editor extends CustomEditor {
   private pi: ExtensionAPI;
@@ -81,18 +82,14 @@ class Editor extends CustomEditor {
   }
 }
 
-export default function (pi: ExtensionAPI) {
-  const events = autoCollectEvents(pi);
-
+export function registerEditor(pi: ExtensionAPI, events: EventCollector): void {
   let editor: Editor | undefined = undefined;
   let spinner: Spinner | undefined = undefined;
   let runningToolCallIds = new Set<string>();
 
   pi.on("session_start", (_event, ctx) => {
-    if (!ctx.hasUI) return;
-
-    const config = loadConfig(ctx, "editor");
-    if (!config) return;
+    const config = loadConfig(ctx).editor;
+    if (!ctx.hasUI || !config) return;
 
     spinner = new Spinner(config.spinner);
 

package/{extensions → src/features}/footer/index.ts

@@ -2,10 +2,10 @@ import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { SplitLine } from "../shared/components/split-line";
-import { loadConfig } from "../shared/config";
-import { formatContextUsage, formatCost, formatCwd, linkText, sanitizeText } from "../shared/format";
-import { getEntryUsage } from "../shared/usage";
+import { SplitLine } from "../../components/split-line";
+import { loadConfig } from "../../config";
+import { formatContextUsage, formatCost, formatCwd, linkText, sanitizeText } from "../../utils/format";
+import { getEntryUsage } from "../../utils/usage";
 
 import type { ExtensionContext, ExtensionAPI, ReadonlyFooterDataProvider, Theme } from "@earendil-works/pi-coding-agent";
 import type { Component } from "@earendil-works/pi-tui";
@@ -80,12 +80,10 @@ class FooterComponent implements Component {
   }
 }
 
-export default function (pi: ExtensionAPI) {
+export function registerFooter(pi: ExtensionAPI): void {
   pi.on("session_start", (_event, ctx) => {
-    if (!ctx.hasUI) return;
-
-    const config = loadConfig(ctx, "footer");
-    if (!config) return;
+    const config = loadConfig(ctx).footer;
+    if (!ctx.hasUI || !config) return;
 
     ctx.ui.setFooter((_tui, theme, footerData) => new FooterComponent(ctx, theme, footerData));
   });

package/{extensions → src/features}/fullscreen/index.ts

@@ -1,12 +1,11 @@
 import { VERSION } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth } from "@earendil-works/pi-tui";
 
 import { BottomFiller } from "./filler";
-import { loadConfig } from "../shared/config";
-import { sanitizeText } from "../shared/format";
+import { loadConfig } from "../../config";
+import { sanitizeText } from "../../utils/format";
 
 import type { ExtensionAPI, ExtensionContext, Theme } from "@earendil-works/pi-coding-agent";
-import { truncateToWidth } from "@earendil-works/pi-tui";
-
 import type { TUI } from "@earendil-works/pi-tui";
 import type { UserMessage } from "@earendil-works/pi-ai";
 
@@ -33,16 +32,14 @@ function extractText(message: UserMessage): string {
   return content.filter((block) => block.type === "text").map((block) => block.text).join(" ");
 }
 
-export default function (pi: ExtensionAPI) {
+export function registerFullscreen(pi: ExtensionAPI): void {
   let tui: TUI | undefined;
   let enabled = false;
   let pendingClear = false;
 
   pi.on("session_start", (_event, ctx) => {
-    if (!ctx.hasUI) return;
-
-    const config = loadConfig(ctx, "fullscreen");
-    if (!config) return;
+    const config = loadConfig(ctx).fullscreen;
+    if (!ctx.hasUI || !config) return;
 
     enabled = true;
     pendingClear = true;

package/src/features/model/config.ts

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

package/{extensions/models → src/features/model}/index.ts

@@ -4,8 +4,8 @@ import { Container, Spacer, Text } from "@earendil-works/pi-tui";
 import { filter, parse } from "liqe";
 import { Type } from "typebox";
 
-import { loadConfig } from "../shared/config";
-import { formatModel, formatTokens } from "../shared/format";
+import { loadConfig } from "../../config";
+import { formatModel, formatTokens } from "../../utils/format";
 
 import type { Api, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, TruncationResult } from "@earendil-works/pi-coding-agent";
@@ -72,9 +72,9 @@ function formatListNotice(truncated: boolean, startIndex: number, endDisplay: nu
   return undefined;
 }
 
-export default function (pi: ExtensionAPI) {
+export function registerModel(pi: ExtensionAPI): void {
   pi.on("session_start", (_event, ctx) => {
-    const config = loadConfig(ctx, "models");
+    const config = loadConfig(ctx).model;
     if (!config) return;
 
     pi.registerTool({
@@ -89,7 +89,7 @@ export default function (pi: ExtensionAPI) {
       promptSnippet: "Show the active model or list pi models",
       promptGuidelines: [
         "Use the model tool when you need pi model metadata, the active model, or the thinking level, rather than guessing.",
-        "When listing models with the model tool, include available:true in the query unless unavailable models are explicitly needed.",
+        "Use the model tool with `available:true` in the query unless unavailable models are explicitly needed.",
       ],
       parameters: Type.Object({
         action: StringEnum(["active", "list"] as const, {

package/{extensions → src/features}/name/index.ts

@@ -1,25 +1,23 @@
 import { Container, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
-import { loadConfig } from "../shared/config";
-import { sanitizeText } from "../shared/format";
+import { loadConfig } from "../../config";
+import { sanitizeText } from "../../utils/format";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-export default function (pi: ExtensionAPI) {
+export function registerName(pi: ExtensionAPI): void {
   pi.on("session_start", (_event, ctx) => {
-    if (!ctx.hasUI) return;
-
-    const config = loadConfig(ctx, "name");
+    const config = loadConfig(ctx).name;
     if (!config) return;
 
     pi.registerTool({
       name: "name",
       label: "name",
       description:
-        "Name or rename the current session. The name is a concise label shown in the session " +
+        "Set or update the current session's name. The name is a concise label shown in the session " +
         "selector instead of the first-message preview.",
-      promptSnippet: "Name or rename the current session",
+      promptSnippet: "Set or update the current session's name",
       promptGuidelines: [
         "Use the name tool when the session needs a concise, recognizable label, especially after a long, vague, or pasted opening prompt.",
         "Use the name tool to rename the session only after a substantial shift in the conversation's focus, not for minor follow-ups.",

package/{extensions → src/features}/presets/config.ts

@@ -1,6 +1,6 @@
 import * as z from "zod";
 
-import { modelSchema } from "../shared/config/model";
+import { modelSchema } from "../../config/model";
 
 export const presetsConfigSchema = z.record(z.string().min(1), modelSchema);
 

package/{extensions → src/features}/presets/index.ts

@@ -2,11 +2,11 @@ import { Key } from "@earendil-works/pi-tui";
 
 import { PresetManager } from "./manager";
 import { showPresetSelector } from "./selector";
-import { loadConfig } from "../shared/config";
+import { loadConfig } from "../../config";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-export default function (pi: ExtensionAPI) {
+export function registerPresets(pi: ExtensionAPI): void {
   let presetManager: PresetManager | undefined = undefined;
 
   pi.registerFlag("preset", {
@@ -14,10 +14,10 @@ export default function (pi: ExtensionAPI) {
     type: "string",
   });
 
-  pi.on("session_start", async (event, ctx) => {
+  pi.on("session_start", async (_event, ctx) => {
+    const config = loadConfig(ctx).presets;
     const presetFlag = pi.getFlag("preset");
 
-    const config = loadConfig(ctx, "presets");
     if (!config || Object.keys(config).length === 0) {
       if (presetFlag) ctx.ui.notify("No presets defined in spark.json", "warning");
       return;

package/{extensions → src/features}/presets/manager.ts

@@ -1,5 +1,5 @@
-import { PRESET_CHANGE } from "../shared/events";
-import { formatModel } from "../shared/format";
+import { PRESET_CHANGE } from "../../events";
+import { formatModel } from "../../utils/format";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { PresetsConfig, PresetConfig } from "./config";

package/{extensions → src/features}/recap/config.ts

@@ -1,7 +1,7 @@
 import * as z from "zod";
 
 import { idleTimeoutSchema } from "./idle";
-import { optionalModelSchema } from "../shared/config/model";
+import { optionalModelSchema } from "../../config/model";
 
 export const recapConfigSchema = optionalModelSchema.extend({
   idle: idleTimeoutSchema.optional(),

package/{extensions → src/features}/recap/index.ts

@@ -1,18 +1,16 @@
 import { IdleListener } from "./idle";
 import { RecapManager } from "./manager";
-import { loadConfig } from "../shared/config";
+import { loadConfig } from "../../config";
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
-export default function (pi: ExtensionAPI) {
+export function registerRecap(pi: ExtensionAPI): void {
   let idleListener: IdleListener<ExtensionContext> | undefined = undefined;
   let recapManager: RecapManager | undefined = undefined;
 
   pi.on("session_start", (event, ctx) => {
-    if (!ctx.hasUI) return;
-
-    const config = loadConfig(ctx, "recap");
-    if (!config) return;
+    const config = loadConfig(ctx).recap;
+    if (!ctx.hasUI || !config) return;
 
     recapManager = new RecapManager(pi, config);
 

package/{extensions → src/features}/recap/manager.ts

@@ -3,22 +3,22 @@ import { convertToLlm, serializeConversation } from "@earendil-works/pi-coding-a
 
 import { resolveRecapModelSettings } from "./model";
 import { clearRecapWidget, setRecapLoadingWidget, setRecapTextWidget } from "./widget";
-import { sanitizeText } from "../shared/format";
+import { sanitizeText } from "../../utils/format";
 
 import type { Api, Model, ModelThinkingLevel, SimpleStreamOptions, Usage } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { RecapConfig } from "./config";
 
 const SYSTEM_PROMPT = [
-  "You write concise idle-session recaps for a terminal coding agent.",
+  "You write concise idle session recaps for a terminal coding agent.",
   "Use only transcript-supported facts; do not invent progress, intent, files, or next steps.",
   "Prefer the latest active task if the session changed direction.",
   "Summarize the user's goal, what was done, current state, and any clearly supported next step.",
-  "Respond in the conversation's primary language.",
-  "Output 1-2 plain-text sentences under 80 words. No heading, markdown, bullets, or quotes.",
+  "Respond in the conversation's primary language. Address the user in the second person.",
+  "Output 1-2 plain-text sentences under 40 words. No heading, markdown, bullets, or quotes.",
 ].join("\n");
 
-const MAX_TOKENS = 100;
+const MAX_TOKENS = 80;
 const MAX_CONVERSATION_CHARS = 8_000;
 
 export class RecapManager {

package/{extensions → src/features}/recap/model.ts

@@ -1,10 +1,10 @@
 import { clampThinkingLevel } from "@earendil-works/pi-ai";
 
-import { formatModel } from "../shared/format";
+import { formatModel } from "../../utils/format";
 
 import type { Api, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { OptionalModelConfig } from "../shared/config/model";
+import type { OptionalModelConfig } from "../../config/model";
 
 const DEFAULT_THINKING_LEVEL: ModelThinkingLevel = "off";
 

package/{extensions/shared/format/index.ts → src/utils/format.ts}

@@ -61,3 +61,32 @@ export function sanitizeText(text: string): string {
     .replace(/ +/g, " ")
     .trim();
 }
+
+/** Coerce a possibly-stringified numeric value to a finite number, or `undefined`. */
+export function toNumber(value?: string | number | null): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  const parsed = typeof value === "number" ? value : Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+const FRANKFURTER_API = "https://api.frankfurter.dev/v2/rate";
+
+interface FrankfurterRateResponse {
+  rate?: string | number;
+}
+
+/** Convert an amount in the given currency to USD via the Frankfurter API. */
+export async function convertToUSD(amount: number | undefined, currency: string | undefined, signal: AbortSignal): Promise<number | undefined> {
+  if (amount === undefined) return undefined;
+  if (!currency || currency === "USD") return amount;
+
+  const url = `${FRANKFURTER_API}/${encodeURIComponent(currency)}/USD`;
+  const response = await fetch(url, { headers: { Accept: "application/json" }, signal });
+  if (!response.ok) throw new Error("currency conversion failed");
+
+  const payload = (await response.json()) as FrankfurterRateResponse;
+  const rate = toNumber(payload.rate);
+  if (rate === undefined) throw new Error("currency conversion failed");
+
+  return amount * rate;
+}

package/{extensions/shared/usage/index.ts → src/utils/usage.ts}

@@ -25,24 +25,6 @@ export function isUsage(value: unknown): value is Usage {
   );
 }
 
-/** Sum two `Usage` values into a new one. */
-export function addUsage(a: Usage, b: Usage): Usage {
-  return {
-    input: a.input + b.input,
-    output: a.output + b.output,
-    cacheRead: a.cacheRead + b.cacheRead,
-    cacheWrite: a.cacheWrite + b.cacheWrite,
-    totalTokens: a.totalTokens + b.totalTokens,
-    cost: {
-      input: a.cost.input + b.cost.input,
-      output: a.cost.output + b.cost.output,
-      cacheRead: a.cost.cacheRead + b.cost.cacheRead,
-      cacheWrite: a.cost.cacheWrite + b.cost.cacheWrite,
-      total: a.cost.total + b.cost.total,
-    },
-  };
-}
-
 /**
  * Extract usage from a session entry.
  *

package/extensions/credits/utils.ts

@@ -1,52 +0,0 @@
-import type { Usage } from "@earendil-works/pi-ai";
-
-/** Structural type guard for the pi `Usage` shape. */
-export function isUsage(value: unknown): value is Usage {
-  if (typeof value !== "object" || value === null) return false;
-
-  const usage = value as Record<string, unknown>;
-  const hasTokenFields =
-    typeof usage.input === "number" &&
-    typeof usage.output === "number" &&
-    typeof usage.cacheRead === "number" &&
-    typeof usage.cacheWrite === "number" &&
-    typeof usage.totalTokens === "number";
-  if (!hasTokenFields) return false;
-
-  if (typeof usage.cost !== "object" || usage.cost === null) return false;
-  const cost = usage.cost as Record<string, unknown>;
-  return (
-    typeof cost.input === "number" &&
-    typeof cost.output === "number" &&
-    typeof cost.cacheRead === "number" &&
-    typeof cost.cacheWrite === "number" &&
-    typeof cost.total === "number"
-  );
-}
-
-export function toNumber(value?: string | number | null): number | undefined {
-  if (value === undefined || value === null) return undefined;
-  const parsed = typeof value === "number" ? value : Number(value);
-  return Number.isFinite(parsed) ? parsed : undefined;
-}
-
-const FRANKFURTER_API = "https://api.frankfurter.dev/v2/rate";
-
-interface FrankfurterRateResponse {
-  rate?: string | number;
-}
-
-export async function convertToUSD(amount: number | undefined, currency: string | undefined, signal: AbortSignal): Promise<number | undefined> {
-  if (amount === undefined) return undefined;
-  if (!currency || currency === "USD") return amount;
-
-  const url = `${FRANKFURTER_API}/${encodeURIComponent(currency)}/USD`;
-  const response = await fetch(url, { headers: { Accept: "application/json" }, signal });
-  if (!response.ok) throw new Error("currency conversion failed");
-
-  const payload = (await response.json()) as FrankfurterRateResponse;
-  const rate = toNumber(payload.rate);
-  if (rate === undefined) throw new Error("currency conversion failed");
-
-  return amount * rate;
-}

package/extensions/models/config.ts

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

package/extensions/shared/config/schema.ts

@@ -1,24 +0,0 @@
-import * as z from "zod";
-
-import { creditsConfigSchema } from "../../credits/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 = {
-  credits: creditsConfigSchema,
-  editor: editorConfigSchema,
-  footer: footerConfigSchema,
-  fullscreen: fullscreenConfigSchema,
-  models: modelsConfigSchema,
-  name: nameConfigSchema,
-  presets: presetsConfigSchema,
-  recap: recapConfigSchema,
-};
-
-export type ConfigField = keyof typeof configSchemas;
-export type ConfigValue<Field extends ConfigField> = z.infer<(typeof configSchemas)[Field]>;

package/extensions/shared/events/index.ts

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