pi-spark 0.24.0 → 0.26.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.26.0](https://github.com/zlliang/pi-spark/compare/v0.25.0...v0.26.0) (2026-09-20)
+
+
+### ⚠ BREAKING CHANGES
+
+* Require Pi 0.86.0 or later.
+
+### Features
+
+* adopt Pi 0.86 model and usage APIs ([5d5868d](https://github.com/zlliang/pi-spark/commit/5d5868defdad303a0b8a9761b013886a198c268d))
+
+## [0.25.0](https://github.com/zlliang/pi-spark/compare/v0.24.0...v0.25.0) (2026-09-14)
+
+
+### Bug Fixes
+
+* refine recap lifecycle and feature event handling ([4bb7474](https://github.com/zlliang/pi-spark/commit/4bb7474b3d04a6d92179b1873afdd6155e5e0368))
+
 ## [0.24.0](https://github.com/zlliang/pi-spark/compare/v0.23.1...v0.24.0) (2026-09-14)
 
 

package/docs/background-model-calls-and-openai-codex-sessions.md

@@ -73,3 +73,5 @@ The independent-session design preserves the main thread's WebSocket reuse, `pre
 Cache admission remains provider-controlled and noisy. In repeated GPT-5.6 Luna title A/B probes, isolated background calls caused no continuation errors and showed no negative main-thread cache trend. Main second-turn latency remained around the normal control range instead of paying the reconnect penalty seen when the shared main socket was closed.
 
 Use the [`measuring-model-cache`](../.agents/skills/measuring-model-cache/SKILL.md) skill to repeat the comparison after changes to Pi, providers, session handling, title, recap, or other background model features.
+
+**Update Sep 19, 2026:** Background calls now use Pi 0.86's `ctx.modelRegistry.streamSimple(...).result()` to support extension-registered providers and resolve authentication automatically. Independent Codex UUIDv7 sessions and cleanup in `finally` remain unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-spark",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Pi package that polishes your daily experience",
   "keywords": [
     "pi-coding-agent",
@@ -44,17 +44,17 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.85.0",
-    "@earendil-works/pi-ai": ">=0.85.0",
-    "@earendil-works/pi-coding-agent": ">=0.85.0",
-    "@earendil-works/pi-tui": ">=0.85.0",
+    "@earendil-works/pi-agent-core": ">=0.86.0",
+    "@earendil-works/pi-ai": ">=0.86.0",
+    "@earendil-works/pi-coding-agent": ">=0.86.0",
+    "@earendil-works/pi-tui": ">=0.86.0",
     "typebox": "*"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": ">=0.85.0",
-    "@earendil-works/pi-ai": ">=0.85.0",
-    "@earendil-works/pi-coding-agent": ">=0.85.0",
-    "@earendil-works/pi-tui": ">=0.85.0",
+    "@earendil-works/pi-agent-core": ">=0.86.0",
+    "@earendil-works/pi-ai": ">=0.86.0",
+    "@earendil-works/pi-coding-agent": ">=0.86.0",
+    "@earendil-works/pi-tui": ">=0.86.0",
     "@types/node": "*",
     "typebox": "*",
     "typescript": "^7.0.2"

package/src/features/editor/index.ts

@@ -168,11 +168,6 @@ export function registerEditor(pi: ExtensionAPI, events: EventCollector): void {
     editor?.setWorkingMessage("Running tools");
   });
 
-  pi.on("tool_call", (event) => {
-    runningToolCallIds.add(event.toolCallId);
-    editor?.setWorkingMessage("Running tools");
-  });
-
   pi.on("tool_execution_end", (event) => {
     runningToolCallIds.delete(event.toolCallId);
     editor?.setWorkingMessage(runningToolCallIds.size > 0 ? "Running tools" : undefined);

package/src/features/recap/idle.ts

@@ -1,5 +1,8 @@
 import parseDuration from "parse-duration";
 import * as z from "zod";
+import { convertToLlm, sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 const MIN_IDLE_MS = 5_000;
 
@@ -17,105 +20,79 @@ export const idleTimeoutSchema = z
   })
   .pipe(z.number().min(MIN_IDLE_MS));
 
-type IdleTimeout = z.infer<typeof idleTimeoutSchema>;
-type IdleHash = string | number | boolean;
-
 const DEFAULT_IDLE_MS = 5 * 60 * 1000;
 const POLL_MS = 1_000;
 
-export class IdleListener<T> {
-  private state: "active" | "watching" | "idle" = "active";
-  private computeStateHash: (ctx: T) => IdleHash;
-  private lastStateHash: IdleHash | undefined;
-
+export class IdleListener {
+  private entered = false;
+  private lastEditorText: string | undefined;
+  private stableSince = 0;
   private idleMs: number;
-  private pollMs: number;
-  private idleTimer: ReturnType<typeof setTimeout> | undefined;
   private pollTimer: ReturnType<typeof setInterval> | undefined;
 
-  private enterCallbacks: Set<(ctx: T) => void> = new Set();
-  private wakeCallbacks: Set<(ctx: T) => void> = new Set();
+  private enterCallbacks: Set<(ctx: ExtensionContext) => void> = new Set();
+  private resetCallbacks: Set<(ctx: ExtensionContext) => void> = new Set();
 
-  constructor(computeStateHash: (ctx: T) => IdleHash, idleMs: IdleTimeout = DEFAULT_IDLE_MS, pollMs: number = POLL_MS) {
-    this.computeStateHash = computeStateHash;
+  constructor(idleMs: number = DEFAULT_IDLE_MS) {
     this.idleMs = idleMs;
-    this.pollMs = pollMs;
   }
 
-  on(event: "enter" | "wake", callback: (ctx: T) => void): () => void {
-    const callbackSet = event === "enter" ? this.enterCallbacks : this.wakeCallbacks;
-    callbackSet.add(callback);
+  on(event: "enter" | "reset", callback: (ctx: ExtensionContext) => void): () => void {
+    const callbacks = event === "enter" ? this.enterCallbacks : this.resetCallbacks;
+    callbacks.add(callback);
 
-    return () => callbackSet.delete(callback);
+    return () => callbacks.delete(callback);
   }
 
-  watch(ctx: T): void {
-    if (this.state === "idle") return;
-
-    this.stop();
-    this.state = "watching";
-
-    this.lastStateHash = this.computeStateHash(ctx);
-    this.reset(ctx);
-
-    this.pollTimer = setInterval(() => {
-      const current = this.computeStateHash(ctx);
-      if (current === this.lastStateHash) return;
+  /** Clears any recap and starts a fresh idle period, keeping observation active while Pi is busy. */
+  reset(ctx: ExtensionContext): void {
+    this.entered = false;
+    this.lastEditorText = undefined;
+    this.resetCallbacks.forEach((callback) => callback(ctx));
 
-      this.lastStateHash = current;
-      this.reset(ctx);
-    }, this.pollMs);
-  }
-
-  enter(ctx: T): void {
-    if (this.state === "idle") return;
-
-    this.stop();
-    this.state = "idle";
-
-    this.enterCallbacks.forEach((callback) => callback(ctx));
-  }
-
-  /** Emits on every wake signal, even when the listener is already active. */
-  wake(ctx: T): void {
-    this.stop();
-    this.state = "active";
-
-    this.wakeCallbacks.forEach((callback) => callback(ctx));
+    this.check(ctx);
+    if (!this.pollTimer) {
+      this.pollTimer = setInterval(() => this.check(ctx), POLL_MS);
+    }
   }
 
   dispose(): void {
-    this.stop();
-    this.state = "active";
+    if (this.pollTimer) {
+      clearInterval(this.pollTimer);
+      this.pollTimer = undefined;
+    }
 
+    this.entered = false;
+    this.lastEditorText = undefined;
     this.enterCallbacks.clear();
-    this.wakeCallbacks.clear();
-  }
-
-  private reset(ctx: T): void {
-    this.clearIdleTimer();
-    this.idleTimer = setTimeout(() => {
-      this.idleTimer = undefined;
-      this.enter(ctx);
-    }, this.idleMs);
-  }
-
-  private stop(): void {
-    this.clearIdleTimer();
-    this.clearPollTimer();
+    this.resetCallbacks.clear();
   }
 
-  private clearIdleTimer(): void {
-    if (!this.idleTimer) return;
-
-    clearTimeout(this.idleTimer);
-    this.idleTimer = undefined;
-  }
-
-  private clearPollTimer(): void {
-    if (!this.pollTimer) return;
-
-    clearInterval(this.pollTimer);
-    this.pollTimer = undefined;
+  private check(ctx: ExtensionContext): void {
+    const canEnter = ctx.isIdle() && ctx.sessionManager.buildContextEntries().some((entry) => convertToLlm(sessionEntryToContextMessages(entry)).length > 0);
+    if (!canEnter) {
+      this.lastEditorText = undefined;
+      if (this.entered) {
+        this.entered = false;
+        this.resetCallbacks.forEach((callback) => callback(ctx));
+      }
+      return;
+    }
+
+    // Keep the recap while the user edits; only a reset or Pi becoming busy clears it.
+    if (this.entered) return;
+
+    const editorText = ctx.ui.getEditorText();
+    const now = Date.now();
+    if (editorText !== this.lastEditorText) {
+      this.lastEditorText = editorText;
+      this.stableSince = now;
+      return;
+    }
+
+    if (now - this.stableSince >= this.idleMs) {
+      this.entered = true;
+      this.enterCallbacks.forEach((callback) => callback(ctx));
+    }
   }
 }

package/src/features/recap/index.ts

@@ -2,13 +2,13 @@ import { IdleListener } from "./idle";
 import { RecapManager } from "./manager";
 import { loadConfig } from "../../config";
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 export function registerRecap(pi: ExtensionAPI): void {
-  let idleListener: IdleListener<ExtensionContext> | undefined = undefined;
+  let idleListener: IdleListener | undefined = undefined;
   let recapManager: RecapManager | undefined = undefined;
 
-  pi.on("session_start", (event, ctx) => {
+  pi.on("session_start", (_event, ctx) => {
     const config = loadConfig(ctx).recap;
     if (ctx.mode !== "tui" || !config) return;
 
@@ -16,52 +16,34 @@ export function registerRecap(pi: ExtensionAPI): void {
 
     pi.registerCommand("recap", {
       description: "Generate a short recap of the current session",
-      handler: async () => await recapManager?.run(ctx, { force: true }),
+      handler: async (_args, ctx) => await recapManager?.run(ctx, { force: true }),
     });
 
-    idleListener = new IdleListener((c) => `idle:${c.isIdle()};editor:${c.ui.getEditorText()}`, config.idle);
-    idleListener.on("enter", (c) => recapManager?.run(c));
-    idleListener.on("wake", (c) => recapManager?.clear(c));
+    idleListener = new IdleListener(config.idle);
+    idleListener.on("enter", (ctx) => recapManager?.run(ctx));
+    idleListener.on("reset", (ctx) => recapManager?.clear(ctx));
 
-    if (event.reason === "resume" || event.reason === "fork") {
-      idleListener.watch(ctx);
-    }
+    idleListener.reset(ctx);
   });
 
   pi.on("input", (_event, ctx) => {
-    idleListener?.wake(ctx);
+    idleListener?.reset(ctx);
   });
 
   pi.on("user_bash", (_event, ctx) => {
-    idleListener?.wake(ctx);
+    idleListener?.reset(ctx);
   });
 
   pi.on("agent_start", (_event, ctx) => {
-    idleListener?.wake(ctx);
+    idleListener?.reset(ctx);
   });
 
   pi.on("session_before_compact", (_event, ctx) => {
-    idleListener?.wake(ctx);
+    idleListener?.reset(ctx);
   });
 
   pi.on("session_before_tree", (_event, ctx) => {
-    idleListener?.wake(ctx);
-  });
-
-  pi.on("agent_settled", (_event, ctx) => {
-    idleListener?.watch(ctx);
-  });
-
-  pi.on("session_compact", (_event, ctx) => {
-    idleListener?.watch(ctx);
-  });
-
-  pi.on("session_compact_failed", (_event, ctx) => {
-    idleListener?.watch(ctx);
-  });
-
-  pi.on("session_tree", (_event, ctx) => {
-    idleListener?.watch(ctx);
+    idleListener?.reset(ctx);
   });
 
   pi.on("session_shutdown", (_event, ctx) => {

package/src/features/recap/manager.ts

@@ -1,10 +1,10 @@
-import { convertToLlm, serializeConversation } from "@earendil-works/pi-coding-agent";
+import { convertToLlm, serializeConversation, sessionEntryToContextMessages } from "@earendil-works/pi-coding-agent";
 
 import { clearRecapWidget, setRecapLoadingWidget, setRecapTextWidget } from "./widget";
 import { sanitizeText } from "../../utils/format";
 import { completeBackground, resolveModelSettings } from "../../utils/model";
 
-import type { Api, Model, ModelThinkingLevel, SimpleStreamOptions, Usage } from "@earendil-works/pi-ai";
+import type { Api, Model, ModelThinkingLevel, Usage } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { RecapConfig } from "./config";
 
@@ -32,7 +32,7 @@ export class RecapManager {
   }
 
   async run(ctx: ExtensionContext, options: { force?: boolean } = {}): Promise<void> {
-    if (this.active && !options.force) return;
+    if (!options.force && (this.active || this.inflight || !ctx.isIdle())) return;
 
     this.cancelInflight();
     const controller = new AbortController();
@@ -41,6 +41,7 @@ export class RecapManager {
     try {
       const modelSettings = await resolveModelSettings(ctx, this.config, "recap");
       if (controller.signal.aborted || this.inflight !== controller || !modelSettings) return;
+      if (!options.force && !ctx.isIdle()) return;
 
       const { model, thinkingLevel, warning } = modelSettings;
 
@@ -81,23 +82,18 @@ export class RecapManager {
   }
 
   private async generate(ctx: ExtensionContext, model: Model<Api>, thinkingLevel: ModelThinkingLevel, signal: AbortSignal): Promise<{ content: string; usage: Usage }> {
-    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-    if (!auth.ok) throw new Error(auth.error);
-
-    const options: SimpleStreamOptions = { maxTokens: MAX_TOKENS, signal };
-    if (auth.apiKey) options.apiKey = auth.apiKey;
-    if (auth.headers) options.headers = auth.headers;
-    if (auth.env) options.env = auth.env;
-    if (thinkingLevel !== "off") options.reasoning = thinkingLevel;
-
-    const response = await completeBackground(model, {
+    const response = await completeBackground(ctx, model, {
       systemPrompt: SYSTEM_PROMPT,
       messages: [{
         role: "user",
         content: [{ type: "text", text: this.buildPrompt(ctx) }],
         timestamp: Date.now(),
       }],
-    }, options);
+    }, {
+      maxTokens: MAX_TOKENS,
+      signal,
+      reasoning: thinkingLevel === "off" ? undefined : thinkingLevel,
+    });
 
     if (response.stopReason === "error") {
       throw new Error(response.errorMessage ?? "Recap generation failed");
@@ -113,7 +109,7 @@ export class RecapManager {
   }
 
   private buildPrompt(ctx: ExtensionContext): string {
-    const messages = ctx.sessionManager.getBranch().filter((entry) => entry.type === "message").map((entry) => entry.message);
+    const messages = ctx.sessionManager.buildContextEntries().flatMap(sessionEntryToContextMessages);
     const text = serializeConversation(convertToLlm(messages));
     const conversation = text.length > MAX_CONVERSATION_CHARS ? text.slice(-MAX_CONVERSATION_CHARS) : text;
 

package/src/features/title/index.ts

@@ -16,12 +16,12 @@ export function registerTitle(pi: ExtensionAPI): void {
   // Generate the title after the first completed turn, without waiting for the full agent run.
   // The manager skips sessions that already have a name and prevents concurrent attempts.
   pi.on("turn_end", (_event, ctx) => {
-    void titleManager?.run(ctx);
+    titleManager?.run(ctx);
   });
 
   // Fall back to settlement if the run ends without a completed turn or an early attempt fails.
   pi.on("agent_settled", (_event, ctx) => {
-    void titleManager?.run(ctx);
+    titleManager?.run(ctx);
   });
 
   pi.on("session_shutdown", () => {

package/src/features/title/manager.ts

@@ -3,7 +3,7 @@ import { convertToLlm, serializeConversation } from "@earendil-works/pi-coding-a
 import { sanitizeText } from "../../utils/format";
 import { completeBackground, resolveModelSettings } from "../../utils/model";
 
-import type { Api, Model, ModelThinkingLevel, SimpleStreamOptions, Usage } from "@earendil-works/pi-ai";
+import type { Api, Model, ModelThinkingLevel, Usage } from "@earendil-works/pi-ai";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { TitleConfig } from "./config";
 
@@ -64,23 +64,18 @@ export class TitleManager {
   }
 
   private async generate(ctx: ExtensionContext, model: Model<Api>, thinkingLevel: ModelThinkingLevel, signal: AbortSignal): Promise<{ content: string; usage: Usage }> {
-    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
-    if (!auth.ok) throw new Error(auth.error);
-
-    const options: SimpleStreamOptions = { maxTokens: MAX_TOKENS, signal };
-    if (auth.apiKey) options.apiKey = auth.apiKey;
-    if (auth.headers) options.headers = auth.headers;
-    if (auth.env) options.env = auth.env;
-    if (thinkingLevel !== "off") options.reasoning = thinkingLevel;
-
-    const response = await completeBackground(model, {
+    const response = await completeBackground(ctx, model, {
       systemPrompt: SYSTEM_PROMPT,
       messages: [{
         role: "user",
         content: [{ type: "text", text: this.buildPrompt(ctx) }],
         timestamp: Date.now(),
       }],
-    }, options);
+    }, {
+      maxTokens: MAX_TOKENS,
+      signal,
+      reasoning: thinkingLevel === "off" ? undefined : thinkingLevel,
+    });
 
     if (response.stopReason === "error") {
       throw new Error(response.errorMessage ?? "Title generation failed");

package/src/utils/model.ts

@@ -1,10 +1,9 @@
 import { uuidv7 } from "@earendil-works/pi-agent-core";
 import { clampThinkingLevel, cleanupSessionResources } from "@earendil-works/pi-ai";
-import { completeSimple } from "@earendil-works/pi-ai/compat";
 
 import { formatModel } from "./format";
 
-import type { Api, Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import type { Api, AssistantMessage, Context, Model, ModelsSimpleStreamOptions, ModelThinkingLevel } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { OptionalModelConfig } from "../config/model";
 
@@ -30,17 +29,17 @@ type ThinkingLevelSelection = {
  * Completes a one-shot background request, using an isolated session for OpenAI Codex models.
  * See [the investigation](../../docs/background-model-calls-and-openai-codex-sessions.md).
  */
-export const completeBackground: typeof completeSimple = async (model, context, options) => {
-  if (model.api !== "openai-codex-responses") return completeSimple(model, context, options);
+export async function completeBackground(ctx: ExtensionContext, model: Model<Api>, context: Context, options?: ModelsSimpleStreamOptions): Promise<AssistantMessage> {
+  if (model.api !== "openai-codex-responses") return ctx.modelRegistry.streamSimple(model, context, options).result();
 
   const sessionId = uuidv7();
 
   try {
-    return await completeSimple(model, context, { ...options, sessionId });
+    return await ctx.modelRegistry.streamSimple(model, context, { ...options, sessionId }).result();
   } finally {
     cleanupSessionResources(sessionId);
   }
-};
+}
 
 /**
  * Resolves the model and thinking level for a background feature (recap, title, ...).

package/src/utils/usage.ts

@@ -33,7 +33,7 @@ export function isUsage(value: unknown): value is Usage {
  * - `message` carries them on `message`.
  * - `custom` on `data`.
  * - `custom_message` on `details`.
- * - `compaction` and `branch_summary` directly on the entry.
+ * - `usage`, `compaction`, and `branch_summary` directly on the entry.
  *
  * Other entry types carry no usage. Returns `undefined` when the resolved field has no `usage`.
  */
@@ -42,8 +42,7 @@ export function getEntryUsage(entry: SessionEntry): Usage | undefined {
   if (entry.type === "message") source = entry.message;
   else if (entry.type === "custom") source = entry.data;
   else if (entry.type === "custom_message") source = entry.details;
-  else if (entry.type === "compaction" || entry.type === "branch_summary") source = entry;
-  else return;
+  else source = entry;
 
   if (typeof source !== "object" || source === null) return;
   const data = source as { usage?: unknown };