pi-spark 0.14.4 → 0.14.6

package/README.md

@@ -6,6 +6,20 @@
 
 ![Overview](./assets/screenshot-overview.png)
 
+## Install
+
+Install from npm:
+
+```bash
+pi install npm:pi-spark
+```
+
+Install from git:
+
+```bash
+pi install git:github.com/zlliang/pi-spark
+```
+
 ## Features
 
 ### Compact TUI: editor, footer, and fullscreen
@@ -131,18 +145,22 @@ Each preset must set all three fields.
 | --- | --- | --- |
 | `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. |
+| `thinkingLevel` | `ModelThinkingLevel` | Thinking level for the preset. |
 
 #### `RecapConfig`
 
-All fields are optional, including `thinkingLevel`.
+All fields are optional, including `thinkingLevel`. If the recap model configuration is incomplete, pi-spark falls back to the session's main model.
 
 | 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. |
+| `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., `"5m"`); minimum 5000 ms, defaults to 5 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. |
+| `thinkingLevel` | `ModelThinkingLevel` | Thinking level for the recap model. |
+
+#### `ModelThinkingLevel`
+
+Valid values: `off`, `minimal`, `low`, `medium`, `high`, `xhigh`.
 
 ### Turn off the features you don't like
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-spark",
-  "version": "0.14.4",
+  "version": "0.14.6",
   "description": "Pi package that polishes your daily experience and keeps you at the frontier of agentic workflows.",
   "keywords": [
     "pi-coding-agent",

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

@@ -1,11 +1,8 @@
 import { fileURLToPath } from "node:url";
 
-import { credentials, loadPackageDefinition, Metadata } from "@grpc/grpc-js";
-import { loadSync } from "@grpc/proto-loader";
-
 import { toNumber } from "../../../utils/format";
 
-import type { ClientUnaryCall, ServiceClientConstructor, ServiceError } from "@grpc/grpc-js";
+import type { ClientUnaryCall, Metadata, ServiceClientConstructor, ServiceError } from "@grpc/grpc-js";
 import type { Credits, CreditsProvider } from "../types";
 
 type GatewayClient = InstanceType<ServiceClientConstructor>;
@@ -43,9 +40,16 @@ let client: GatewayClient | undefined;
 /** The API key maps to a fixed account, so cache the resolved resource name. */
 const accountByKey = new Map<string, string>();
 
-function getClient(): GatewayClient {
+async function getClient(): Promise<GatewayClient> {
   if (client) return client;
 
+  // @grpc/* is heavy to import (~45 ms cold); load it lazily so startup never pays for it unless
+  // Fireworks credits are actually fetched.
+  const [{ credentials, loadPackageDefinition }, { loadSync }] = await Promise.all([
+    import("@grpc/grpc-js"),
+    import("@grpc/proto-loader"),
+  ]);
+
   const protoPath = fileURLToPath(new URL("./fireworks.proto", import.meta.url));
   const definition = loadSync(protoPath, { keepCase: true, longs: String, defaults: true });
   const proto = loadPackageDefinition(definition) as unknown as { gateway: { Gateway: ServiceClientConstructor } };
@@ -55,12 +59,14 @@ function getClient(): GatewayClient {
 }
 
 async function unary<T>(method: string, request: object, apiKey: string, signal: AbortSignal): Promise<T> {
+  const grpc = await import("@grpc/grpc-js");
+  const gateway = await getClient();
+
   return new Promise<T>((resolve, reject) => {
-    const metadata = new Metadata();
+    const metadata = new grpc.Metadata();
     metadata.set("x-api-key", apiKey);
 
     const deadline = new Date(Date.now() + DEADLINE_MS);
-    const gateway = getClient();
     const invoke = gateway[method] as (
       request: object,
       metadata: Metadata,

package/src/features/pi/actions/name.ts

@@ -22,23 +22,13 @@ export const nameAction = defineAction({
         "(e.g., \"Refactor auth module\", \"Debug flaky CI pipeline\"). Do not use " +
         "surrounding quotes, trailing punctuation, or generic prefixes like \"Chat about\".",
     }),
-    reason: Type.Optional(Type.String({
-      maxLength: 240,
-      description:
-        "For \"name\": Explain briefly why the session was named or renamed, such as a long pasted " +
-        "prompt, an ambiguous first message, or a topic shift. Write one user-facing " +
-        "sentence (e.g., \"The focus shifted from debugging to README updates.\").",
-    })),
   },
   required: ["name"],
   promptGuidelines: [
     "Use the pi tool's \"name\" action to give the current session a concise, recognizable name, especially after a long, vague, or pasted opening prompt, or after a substantial shift in the conversation's focus.",
   ],
   renderParams(args, theme) {
-    const name = theme.fg("muted", sanitizeText(args.name ?? ""));
-    const reason = sanitizeText(args.reason ?? "");
-
-    return [reason ? name + theme.fg("muted", "\n\n" + reason) : name];
+    return [theme.fg("muted", sanitizeText(args.name ?? ""))];
   },
   renderResult() {
     // "name" has no success UI; errors are rendered by the registry's fallback.

package/src/features/pi/actions/whoami.ts

@@ -31,14 +31,16 @@ export const whoamiAction = defineAction({
       return container;
     }
 
+    const formatLine = (label: string, value: string) => `${label.padEnd(7)}  ${value}`;
+
     if (details.sessionName) {
-      container.addChild(new Text(theme.fg("muted", `session  ${details.sessionName}`), 0, 0));
+      container.addChild(new Text(theme.fg("muted", formatLine("session", details.sessionName)), 0, 0));
     }
 
     if (details.model) {
       const row = toModelRow(details.model, details.thinkingLevel);
       const cells = [row.label, row.cost, row.context].join("  ");
-      container.addChild(new Text(theme.fg("muted", `model    ${cells}`), 0, 0));
+      container.addChild(new Text(theme.fg("muted", formatLine("model", cells)), 0, 0));
     }
 
     return container;

package/src/features/presets/index.ts

@@ -14,9 +14,9 @@ export function registerPresets(pi: ExtensionAPI): void {
     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 presetFlag = event.reason === "startup" ? pi.getFlag("preset") : undefined;
 
     if (!config || Object.keys(config).length === 0) {
       if (presetFlag) ctx.ui.notify("No presets defined in spark.json", "warning");

package/src/features/presets/selector.ts

@@ -1,5 +1,5 @@
-import { DynamicBorder } from "@earendil-works/pi-coding-agent";
-import { Container, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
+import { keyText, DynamicBorder } from "@earendil-works/pi-coding-agent";
+import { Box, Container, SelectList, Spacer, Text } from "@earendil-works/pi-tui";
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { PresetManager } from "./manager";
@@ -20,12 +20,11 @@ export async function showPresetSelector(ctx: ExtensionContext, presetManager: P
       }));
 
     const container = new Container();
-
     container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
-    container.addChild(new Spacer(1));
-    container.addChild(new Text(theme.bold("Select preset"), 0, 0));
-    container.addChild(new Text(theme.fg("dim", "↑↓ navigate · enter select · esc cancel"), 0, 0));
-    container.addChild(new Spacer(1));
+
+    const box = new Box(1, 1);
+    box.addChild(new Text(theme.bold(theme.fg("accent", "Select preset")), 0, 0));
+    box.addChild(new Spacer(1));
 
     const selectList = new SelectList(items, 10, {
       selectedPrefix: (text) => theme.fg("accent", text),
@@ -36,9 +35,17 @@ export async function showPresetSelector(ctx: ExtensionContext, presetManager: P
     });
     selectList.onSelect = (item) => done(item.value);
     selectList.onCancel = () => done(null);
-    container.addChild(selectList);
+    box.addChild(selectList);
+    box.addChild(new Spacer(1));
+
+    const keyHints = [
+      ["↑↓", "navigate"],
+      [keyText("tui.select.confirm"), "select"],
+      [keyText("tui.select.cancel"), "cancel"],
+    ] as const;
+    box.addChild(new Text(keyHints.map((item) => `${theme.fg("dim", item[0])} ${theme.fg("muted", item[1])}`).join("  "), 0, 0));
 
-    container.addChild(new Spacer(1));
+    container.addChild(box);
     container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
 
     return {

package/src/features/recap/idle.ts

@@ -31,7 +31,7 @@ export const idleTimeoutSchema = z
 type IdleTimeout = z.infer<typeof idleTimeoutSchema>;
 type IdleHash = string | number | boolean;
 
-const DEFAULT_IDLE_MS = 3 * 60 * 1000;
+const DEFAULT_IDLE_MS = 5 * 60 * 1000;
 const POLL_MS = 1_000;
 
 export class IdleListener<T> {

package/src/features/web/client.ts

@@ -1,6 +1,4 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-
+import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { TextContent } from "@earendil-works/pi-ai";
 
 /** Exa's hosted MCP endpoint (Streamable HTTP). No API key required for the free tier. */
@@ -56,6 +54,13 @@ export class ExaClient {
 
     if (!this.connecting) {
       this.connecting = (async () => {
+        // The MCP SDK is heavy to import (~40 ms cold); load it lazily so startup never pays for
+        // it unless a web action actually runs.
+        const [{ Client }, { StreamableHTTPClientTransport }] = await Promise.all([
+          import("@modelcontextprotocol/sdk/client/index.js"),
+          import("@modelcontextprotocol/sdk/client/streamableHttp.js"),
+        ]);
+
         const next = new Client({ name: "pi-spark", version: "0" });
         const transport = new StreamableHTTPClientTransport(new URL(EXA_MCP_URL));
         await next.connect(transport as Parameters<Client["connect"]>[0]);

package/src/utils/tool.ts

@@ -4,7 +4,7 @@ import { Type } from "typebox";
 
 import { formatDuration, joinTextContent } from "./format";
 
-import type { AgentToolResult, ExtensionAPI, ExtensionContext, Theme, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, AgentToolUpdateCallback, ExtensionAPI, ExtensionContext, Theme, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { Component } from "@earendil-works/pi-tui";
 import type { Static, TObject, TProperties, TSchema } from "typebox";
 
@@ -28,8 +28,9 @@ export interface Action<C, F extends TProperties = TProperties, D extends Action
   showTiming?: boolean;
   /** Styled segments shown after the `<tool> <action>` prefix. */
   renderParams?: (args: Static<TObject<F>>, theme: Theme) => string[];
+  /** Only handles successful output; error output is handled centrally. */
   renderResult?: NonNullable<ToolDefinition<TObject<F>, D>["renderResult"]>;
-  execute(args: Static<TObject<F>>, context: C, signal: AbortSignal | undefined): Promise<AgentToolResult<D>>;
+  execute(args: Static<TObject<F>>, context: C, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<D> | undefined): Promise<AgentToolResult<D>>;
 }
 
 /** Identity helper bound to context `C`, so actions infer their field/details types while sharing one context shape. */
@@ -75,7 +76,6 @@ export function registerComposedTool<C>(pi: ExtensionAPI, config: ComposedToolCo
 
   const activeTiming = new ActiveTiming();
   const noTiming = new NoTiming();
-  // Resolve per-action timing from the stable call args, so error results (no details) still settle.
   const timingFor = (action: string | undefined): Timing => (byName.get(action ?? "")?.showTiming ? activeTiming : noTiming);
 
   const renderActionResult: NonNullable<ToolDefinition["renderResult"]> = (result, options, theme, context) => {
@@ -111,7 +111,7 @@ export function registerComposedTool<C>(pi: ExtensionAPI, config: ComposedToolCo
 
       return timingFor(context.args.action).renderResult(inner, options, theme, context);
     },
-    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const action = byName.get(params.action);
       if (!action) throw new Error(`Unknown ${config.name} action "${params.action}"`);
 
@@ -121,7 +121,7 @@ export function registerComposedTool<C>(pi: ExtensionAPI, config: ComposedToolCo
         }
       }
 
-      return action.execute(params as never, config.createContext(ctx), signal);
+      return action.execute(params as any, config.createContext(ctx), signal, onUpdate);
     },
   });
 }
@@ -147,55 +147,67 @@ interface TimingState {
   startedAt?: number;
   endedAt?: number;
   interval?: ReturnType<typeof setInterval>;
+  hasResult?: boolean;
 }
 
 class ActiveTiming implements Timing {
+  // No result yet: `renderCall` owns the live "Elapsed" ticker.
   renderCall(inner: Component, ...[theme, context]: RenderCallTail): Component {
     const state = context.state as TimingState;
+
     if (context.executionStarted && state.startedAt === undefined) {
       state.startedAt = Date.now();
       delete state.endedAt;
+      delete state.hasResult;
     }
 
-    // Result is in: renderResult owns the timing line, so just settle here.
-    if (!context.isPartial) {
-      this.settle(state);
-      return inner;
-    }
-
-    // Still running, no result yet: show a live "Elapsed" line, ticking once a second.
-    if (state.startedAt === undefined) return inner;
+    // Not started, or final (`renderResult` owns the "Took" line): render nothing here.
+    if (state.startedAt === undefined || !context.isPartial) return inner;
 
     state.interval ??= setInterval(() => context.invalidate(), 1000);
-    return this.withTimingLine(inner, "Elapsed", Date.now() - state.startedAt, theme);
+
+    // `renderResult` runs later in the same render pass, so decide visibility at render time:
+    // hide once any result has arrived.
+    return this.withTimingLine(inner, "Elapsed", Date.now() - state.startedAt, theme, () => !state.hasResult);
   }
 
+  // A result exists: `renderResult` owns the line — "Elapsed" while streaming, "Took" once final.
   renderResult(inner: Component, ...[options, theme, context]: RenderResultTail): Component {
     const state = context.state as TimingState;
-    if (!options.isPartial || context.isError) this.settle(state);
+    state.hasResult = true;
+
+    const isRunning = options.isPartial && !context.isError;
+    if (!isRunning) this.settle(state);
     if (state.startedAt === undefined) return inner;
 
-    const label = options.isPartial ? "Elapsed" : "Took";
     const endTime = state.endedAt ?? Date.now();
-    return this.withTimingLine(inner, label, endTime - state.startedAt, theme);
+    return this.withTimingLine(inner, isRunning ? "Elapsed" : "Took", endTime - state.startedAt, theme);
   }
 
   private settle(state: TimingState): void {
-    if (state.startedAt !== undefined) state.endedAt ??= Date.now();
+    if (state.startedAt !== undefined) {
+      state.endedAt ??= Date.now();
+    }
+
     if (state.interval) {
       clearInterval(state.interval);
       delete state.interval;
     }
   }
 
-  private withTimingLine(content: Component, label: string, ms: number, theme: Theme): Container {
+  private withTimingLine(content: Component, label: string, ms: number, theme: Theme, visible?: () => boolean): Component {
     const container = new Container();
     container.addChild(content);
 
     container.addChild(new Spacer(1));
-    container.addChild(new Text(`${theme.fg("muted", `${label} ${formatDuration(ms)}`)}`, 0, 0));
+    container.addChild(new Text(theme.fg("muted", `${label} ${formatDuration(ms)}`), 0, 0));
+
+    if (!visible) return container;
 
-    return container;
+    return {
+      invalidate: () => container.invalidate(),
+      render: (width) => (visible() ? container.render(width) : content.render(width)),
+    };
   }
 }