@hyperspaceng/neural-coding-agent 0.63.0 → 0.64.1

package/docs/extensions.md

@@ -293,10 +293,11 @@ Fired by the `pi` CLI during startup session resolution, before the initial sess
 This event is:
 - CLI-only. It is not emitted in SDK mode.
 - Startup-only. It is not emitted for later interactive `/new` or `/resume` actions.
-- Bypassed when `--session-dir` is provided.
+- Lower priority than `--session-dir` and `sessionDir` in `settings.json`.
 - Special-cased to receive no `ctx` argument.
 
 If multiple extensions return `sessionDir`, the last one wins.
+Combined precedence is: `--session-dir` CLI flag, then `sessionDir` in settings, then extension `session_directory` hooks.
 
 ```typescript
 pi.on("session_directory", async (event) => {
@@ -564,17 +565,27 @@ Before `tool_call` runs, pi waits for previously emitted Agent events to finish
 
 In the default parallel tool execution mode, sibling tool calls from the same assistant message are preflighted sequentially, then executed concurrently. `tool_call` is not guaranteed to see sibling tool results from that same assistant message in `ctx.sessionManager`.
 
+`event.input` is mutable. Mutate it in place to patch tool arguments before execution.
+
+Behavior guarantees:
+- Mutations to `event.input` affect the actual tool execution
+- Later `tool_call` handlers see mutations made by earlier handlers
+- No re-validation is performed after your mutation
+- Return values from `tool_call` only control blocking via `{ block: true, reason?: string }`
+
 ```typescript
 import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
 
 pi.on("tool_call", async (event, ctx) => {
   // event.toolName - "bash", "read", "write", "edit", etc.
   // event.toolCallId
-  // event.input - tool parameters
+  // event.input - tool parameters (mutable)
 
   // Built-in tools: no type params needed
   if (isToolCallEventType("bash", event)) {
     // event.input is { command: string; timeout?: number }
+    event.input.command = `source ~/.profile\n${event.input.command}`;
+
     if (event.input.command.includes("rm -rf")) {
       return { block: true, reason: "Dangerous command" };
     }
@@ -618,6 +629,8 @@ Fired after tool execution finishes and before `tool_execution_end` plus the fin
 - Each handler sees the latest result after previous handler changes
 - Handlers can return partial patches (`content`, `details`, or `isError`); omitted fields keep their current values
 
+Use `ctx.signal` for nested async work inside the handler. This lets Esc cancel model calls, `fetch()`, and other abort-aware operations started by the extension.
+
 ```typescript
 import { isBashToolResult } from "@mariozechner/pi-coding-agent";
 
@@ -629,6 +642,12 @@ pi.on("tool_result", async (event, ctx) => {
     // event.details is typed as BashToolDetails
   }
 
+  const response = await fetch("https://example.com/summarize", {
+    method: "POST",
+    body: JSON.stringify({ content: event.content }),
+    signal: ctx.signal,
+  });
+
   // Modify result:
   return { content: [...], details: {...}, isError: false };
 });
@@ -748,6 +767,31 @@ ctx.sessionManager.getLeafId()        // Current leaf entry ID
 
 Access to models and API keys.
 
+### ctx.signal
+
+The current agent abort signal, or `undefined` when no agent turn is active.
+
+Use this for abort-aware nested work started by extension handlers, for example:
+- `fetch(..., { signal: ctx.signal })`
+- model calls that accept `signal`
+- file or process helpers that accept `AbortSignal`
+
+`ctx.signal` is typically defined during active turn events such as `tool_call`, `tool_result`, `message_update`, and `turn_end`.
+It is usually `undefined` in idle or non-turn contexts such as session events, extension commands, and shortcuts fired while pi is idle.
+
+```typescript
+pi.on("tool_result", async (event, ctx) => {
+  const response = await fetch("https://example.com/api", {
+    method: "POST",
+    body: JSON.stringify(event),
+    signal: ctx.signal,
+  });
+
+  const data = await response.json();
+  return { details: data };
+});
+```
+
 ### ctx.isIdle() / ctx.abort() / ctx.hasPendingMessages()
 
 Control flow helpers.
@@ -964,6 +1008,12 @@ pi.registerTool({
     action: StringEnum(["list", "add"] as const),
     text: Type.Optional(Type.String()),
   }),
+  prepareArguments(args) {
+    // Optional compatibility shim. Runs before schema validation.
+    // Return the current schema shape, for example to fold legacy fields
+    // into the modern parameter object.
+    return args;
+  },
 
   async execute(toolCallId, params, signal, onUpdate, ctx) {
     // Stream progress
@@ -1428,6 +1478,14 @@ pi.registerTool({
     action: StringEnum(["list", "add"] as const),  // Use StringEnum for Google compatibility
     text: Type.Optional(Type.String()),
   }),
+  prepareArguments(args) {
+    if (!args || typeof args !== "object") return args;
+    const input = args as { action?: string; oldAction?: string };
+    if (typeof input.oldAction === "string" && input.action === undefined) {
+      return { ...input, action: input.oldAction };
+    }
+    return args;
+  },
 
   async execute(toolCallId, params, signal, onUpdate, ctx) {
     // Check for cancellation
@@ -1471,6 +1529,53 @@ async execute(toolCallId, params) {
 
 **Important:** Use `StringEnum` from `@mariozechner/pi-ai` for string enums. `Type.Union`/`Type.Literal` doesn't work with Google's API.
 
+**Argument preparation:** `prepareArguments(args)` is optional. If defined, it runs before schema validation and before `execute()`. Use it to mimic an older accepted input shape when pi resumes an older session whose stored tool call arguments no longer match the current schema. Return the object you want validated against `parameters`. Keep the public schema strict. Do not add deprecated compatibility fields to `parameters` just to keep old resumed sessions working.
+
+Example: an older session may contain an `edit` tool call with top-level `oldText` and `newText`, while the current schema only accepts `edits: [{ oldText, newText }]`.
+
+```typescript
+pi.registerTool({
+  name: "edit",
+  label: "Edit",
+  description: "Edit a single file using exact text replacement",
+  parameters: Type.Object({
+    path: Type.String(),
+    edits: Type.Array(
+      Type.Object({
+        oldText: Type.String(),
+        newText: Type.String(),
+      }),
+    ),
+  }),
+  prepareArguments(args) {
+    if (!args || typeof args !== "object") return args;
+
+    const input = args as {
+      path?: string;
+      edits?: Array<{ oldText: string; newText: string }>;
+      oldText?: unknown;
+      newText?: unknown;
+    };
+
+    if (typeof input.oldText !== "string" || typeof input.newText !== "string") {
+      return args;
+    }
+
+    return {
+      ...input,
+      edits: [...(input.edits ?? []), { oldText: input.oldText, newText: input.newText }],
+    };
+  },
+  async execute(toolCallId, params, signal, onUpdate, ctx) {
+    // params now matches the current schema
+    return {
+      content: [{ type: "text", text: `Applying ${params.edits.length} edit block(s)` }],
+      details: {},
+    };
+  },
+});
+```
+
 ### Overriding Built-in Tools
 
 Extensions can override built-in tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`) by registering a tool with the same name. Interactive mode displays a warning when this happens.

package/docs/json.md

@@ -13,12 +13,15 @@ Events are defined in [`AgentSessionEvent`](https://github.com/badlogic/pi-mono/
 ```typescript
 type AgentSessionEvent =
   | AgentEvent
-  | { type: "auto_compaction_start"; reason: "threshold" | "overflow" }
-  | { type: "auto_compaction_end"; result: CompactionResult | undefined; aborted: boolean; willRetry: boolean; errorMessage?: string }
+  | { type: "queue_update"; steering: readonly string[]; followUp: readonly string[] }
+  | { type: "compaction_start"; reason: "manual" | "threshold" | "overflow" }
+  | { type: "compaction_end"; reason: "manual" | "threshold" | "overflow"; result: CompactionResult | undefined; aborted: boolean; willRetry: boolean; errorMessage?: string }
   | { type: "auto_retry_start"; attempt: number; maxAttempts: number; delayMs: number; errorMessage: string }
   | { type: "auto_retry_end"; success: boolean; attempt: number; finalError?: string };
 ```
 
+`queue_update` emits the full pending steering and follow-up queues whenever they change. `compaction_start` and `compaction_end` cover both manual and automatic compaction.
+
 Base events from [`AgentEvent`](https://github.com/badlogic/pi-mono/blob/main/packages/agent/src/types.ts#L179):
 
 ```typescript

package/docs/models.md

@@ -131,6 +131,12 @@ The `apiKey` and `headers` fields support three formats:
   "apiKey": "sk-..."
   ```
 
+For `models.json`, shell commands are resolved at request time. pi intentionally does not apply built-in TTL, stale reuse, or recovery logic for arbitrary commands. Different commands need different caching and failure strategies, and pi cannot infer the right one.
+
+If your command is slow, expensive, rate-limited, or should keep using a previous value on transient failures, wrap it in your own script or command that implements the caching or TTL behavior you want.
+
+`/model` availability checks use configured auth presence and do not execute shell commands.
+
 ### Custom Headers
 
 ```json

package/docs/rpc.md

@@ -494,7 +494,7 @@ Response:
 
 #### get_session_stats
 
-Get token usage and cost statistics.
+Get token usage, cost statistics, and current context window usage.
 
 ```json
 {"type": "get_session_stats"}
@@ -521,11 +521,20 @@ Response:
       "cacheWrite": 5000,
       "total": 105000
     },
-    "cost": 0.45
+    "cost": 0.45,
+    "contextUsage": {
+      "tokens": 60000,
+      "contextWindow": 200000,
+      "percent": 30
+    }
   }
 }
 ```
 
+`tokens` contains assistant usage totals for the current session state. `contextUsage` contains the actual current context-window estimate used for compaction and footer display.
+
+`contextUsage` is omitted when no model or context window is available. `contextUsage.tokens` and `contextUsage.percent` are `null` immediately after compaction until a fresh post-compaction assistant response provides valid usage data.
+
 #### export_html
 
 Export session to an HTML file.
@@ -716,8 +725,9 @@ Events are streamed to stdout as JSON lines during agent operation. Events do NO
 | `tool_execution_start` | Tool begins execution |
 | `tool_execution_update` | Tool execution progress (streaming output) |
 | `tool_execution_end` | Tool completes |
-| `auto_compaction_start` | Auto-compaction begins |
-| `auto_compaction_end` | Auto-compaction completes |
+| `queue_update` | Pending steering/follow-up queue changed |
+| `compaction_start` | Compaction begins |
+| `compaction_end` | Compaction completes |
 | `auto_retry_start` | Auto-retry begins (after transient error) |
 | `auto_retry_end` | Auto-retry completes (success or final failure) |
 | `extension_error` | Extension threw an error |
@@ -853,19 +863,32 @@ When complete:
 
 Use `toolCallId` to correlate events. The `partialResult` in `tool_execution_update` contains the accumulated output so far (not just the delta), allowing clients to simply replace their display on each update.
 
-### auto_compaction_start / auto_compaction_end
+### queue_update
+
+Emitted whenever the pending steering or follow-up queue changes.
+
+```json
+{
+  "type": "queue_update",
+  "steering": ["Focus on error handling"],
+  "followUp": ["After that, summarize the result"]
+}
+```
+
+### compaction_start / compaction_end
 
-Emitted when automatic compaction runs (when context is nearly full).
+Emitted when compaction runs, whether manual or automatic.
 
 ```json
-{"type": "auto_compaction_start", "reason": "threshold"}
+{"type": "compaction_start", "reason": "threshold"}
 ```
 
-The `reason` field is `"threshold"` (context getting large) or `"overflow"` (context exceeded limit).
+The `reason` field is `"manual"`, `"threshold"`, or `"overflow"`.
 
 ```json
 {
-  "type": "auto_compaction_end",
+  "type": "compaction_end",
+  "reason": "threshold",
   "result": {
     "summary": "Summary of conversation...",
     "firstKeptEntryId": "abc123",

package/docs/sdk.md

@@ -20,7 +20,7 @@ import { AuthStorage, createAgentSession, ModelRegistry, SessionManager } from "
 
 // Set up credential storage and model registry
 const authStorage = AuthStorage.create();
-const modelRegistry = new ModelRegistry(authStorage);
+const modelRegistry = ModelRegistry.create(authStorage);
 
 const { session } = await createAgentSession({
   sessionManager: SessionManager.inMemory(),
@@ -232,9 +232,12 @@ session.subscribe((event) => {
       // event.toolResults: tool results from this turn
       break;
     
-    // Session events (auto-compaction, retry)
-    case "auto_compaction_start":
-    case "auto_compaction_end":
+    // Session events (queue, compaction, retry)
+    case "queue_update":
+      console.log(event.steering, event.followUp);
+      break;
+    case "compaction_start":
+    case "compaction_end":
     case "auto_retry_start":
     case "auto_retry_end":
       break;
@@ -286,7 +289,7 @@ import { getModel } from "@mariozechner/pi-ai";
 import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
 
 const authStorage = AuthStorage.create();
-const modelRegistry = new ModelRegistry(authStorage);
+const modelRegistry = ModelRegistry.create(authStorage);
 
 // Find specific built-in model (doesn't check if API key exists)
 const opus = getModel("anthropic", "claude-opus-4-5");
@@ -334,7 +337,7 @@ import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";
 
 // Default: uses ~/.pi/agent/auth.json and ~/.pi/agent/models.json
 const authStorage = AuthStorage.create();
-const modelRegistry = new ModelRegistry(authStorage);
+const modelRegistry = ModelRegistry.create(authStorage);
 
 const { session } = await createAgentSession({
   sessionManager: SessionManager.inMemory(),
@@ -347,7 +350,7 @@ authStorage.setRuntimeApiKey("anthropic", "sk-my-temp-key");
 
 // Custom auth storage location
 const customAuth = AuthStorage.create("/my/app/auth.json");
-const customRegistry = new ModelRegistry(customAuth, "/my/app/models.json");
+const customRegistry = ModelRegistry.create(customAuth, "/my/app/models.json");
 
 const { session } = await createAgentSession({
   sessionManager: SessionManager.inMemory(),
@@ -356,7 +359,7 @@ const { session } = await createAgentSession({
 });
 
 // No custom models.json (built-in models only)
-const simpleRegistry = new ModelRegistry(authStorage);
+const simpleRegistry = ModelRegistry.inMemory(authStorage);
 ```
 
 > See [examples/sdk/09-api-keys-and-oauth.ts](../examples/sdk/09-api-keys-and-oauth.ts)
@@ -785,7 +788,7 @@ if (process.env.MY_KEY) {
 }
 
 // Model registry (no custom models.json)
-const modelRegistry = new ModelRegistry(authStorage);
+const modelRegistry = ModelRegistry.create(authStorage);
 
 // Inline tool
 const statusTool: ToolDefinition = {

package/docs/settings.md

@@ -127,6 +127,18 @@ When a provider requests a retry delay longer than `maxDelayMs` (e.g., Google's
 
 `npmCommand` is used for all npm package-manager operations, including `npm root -g`, installs, uninstalls, and `npm install` inside git packages. Use argv-style entries exactly as the process should be launched.
 
+### Sessions
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `sessionDir` | string | - | Directory where session files are stored. Accepts absolute or relative paths. |
+
+```json
+{ "sessionDir": ".pi/sessions" }
+```
+
+When multiple sources specify a session directory, `--session-dir` CLI flag takes precedence, then `sessionDir` in settings.json, then extension hooks.
+
 ### Model Cycling
 
 | Setting | Type | Default | Description |

package/docs/skills.md

@@ -34,8 +34,9 @@ Pi loads skills from:
 - CLI: `--skill <path>` (repeatable, additive even with `--no-skills`)
 
 Discovery rules:
-- Direct `.md` files in the skills directory root
-- Recursive `SKILL.md` files under subdirectories
+- In `~/.pi/agent/skills/` and `.pi/skills/`, direct root `.md` files are discovered as individual skills
+- In all skill locations, directories containing `SKILL.md` are discovered recursively
+- In `~/.agents/skills/` and project `.agents/skills/`, root `.md` files are ignored
 
 Disable discovery with `--no-skills` (explicit `--skill` paths still load).
 

package/examples/extensions/README.md

@@ -52,6 +52,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 | `qna.ts` | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
 | `status-line.ts` | Shows turn progress in footer via `ctx.ui.setStatus()` with themed colors |
 | `widget-placement.ts` | Shows widgets above and below the editor via `ctx.ui.setWidget()` placement |
+| `hidden-thinking-label.ts` | Customizes the collapsed thinking label via `ctx.ui.setHiddenThinkingLabel()` |
 | `model-status.ts` | Shows model changes in status bar via `model_select` hook |
 | `snake.ts` | Snake game with custom UI, keyboard handling, and session persistence |
 | `send-user-message.ts` | Demonstrates `pi.sendUserMessage()` for sending user messages from extensions |

package/examples/extensions/custom-compaction.ts

@@ -31,9 +31,13 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
-		// Resolve API key for the summarization model
-		const apiKey = await ctx.modelRegistry.getApiKey(model);
-		if (!apiKey) {
+		// Resolve request auth for the summarization model
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (!auth.ok) {
+			ctx.ui.notify(`Compaction auth failed: ${auth.error}`, "warning");
+			return;
+		}
+		if (!auth.apiKey) {
 			ctx.ui.notify(`No API key for ${model.provider}, using default compaction`, "warning");
 			return;
 		}
@@ -83,7 +87,16 @@ ${conversationText}
 
 		try {
 			// Pass signal to honor abort requests (e.g., user cancels compaction)
-			const response = await complete(model, { messages: summaryMessages }, { apiKey, maxTokens: 8192, signal });
+			const response = await complete(
+				model,
+				{ messages: summaryMessages },
+				{
+					apiKey: auth.apiKey,
+					headers: auth.headers,
+					maxTokens: 8192,
+					signal,
+				},
+			);
 
 			const summary = response.content
 				.filter((c): c is { type: "text"; text: string } => c.type === "text")

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "1.14.0",
+  "version": "1.15.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "1.14.0",
+      "version": "1.15.1",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-custom-provider-anthropic",
 	"private": true,
-	"version": "1.14.0",
+	"version": "1.15.1",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-custom-provider-gitlab-duo",
 	"private": true,
-	"version": "1.14.0",
+	"version": "1.15.1",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-qwen-cli/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-custom-provider-qwen-cli",
 	"private": true,
-	"version": "1.13.0",
+	"version": "1.14.1",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/handoff.ts

@@ -80,7 +80,10 @@ export default function (pi: ExtensionAPI) {
 				loader.onAbort = () => done(null);
 
 				const doGenerate = async () => {
-					const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+					const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model!);
+					if (!auth.ok || !auth.apiKey) {
+						throw new Error(auth.ok ? `No API key for ${ctx.model!.provider}` : auth.error);
+					}
 
 					const userMessage: Message = {
 						role: "user",
@@ -96,7 +99,7 @@ export default function (pi: ExtensionAPI) {
 					const response = await complete(
 						ctx.model!,
 						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
-						{ apiKey, signal: loader.signal },
+						{ apiKey: auth.apiKey, headers: auth.headers, signal: loader.signal },
 					);
 
 					if (response.stopReason === "aborted") {

package/examples/extensions/hidden-thinking-label.ts

@@ -0,0 +1,57 @@
+/**
+ * Hidden Thinking Label Extension
+ *
+ * Demonstrates `ctx.ui.setHiddenThinkingLabel()` for customizing the label shown
+ * when thinking blocks are hidden.
+ *
+ * Usage:
+ *   pi --extension examples/extensions/hidden-thinking-label.ts
+ *
+ * Test:
+ *   1. Load this extension
+ *   2. Hide thinking blocks with Ctrl+T
+ *   3. Ask for something that produces reasoning output
+ *   4. The collapsed thinking block label will show the custom text
+ *
+ * Commands:
+ *   /thinking-label <text>   Set a custom hidden thinking label
+ *   /thinking-label          Reset to the default label
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+
+const DEFAULT_LABEL = "Pondering...";
+
+export default function (pi: ExtensionAPI) {
+	let label = DEFAULT_LABEL;
+
+	const applyLabel = (ctx: ExtensionContext) => {
+		ctx.ui.setHiddenThinkingLabel(label);
+	};
+
+	pi.on("session_start", async (_event, ctx) => {
+		applyLabel(ctx);
+	});
+
+	pi.on("session_switch", async (_event, ctx) => {
+		applyLabel(ctx);
+	});
+
+	pi.registerCommand("thinking-label", {
+		description: "Set the hidden thinking label. Use without args to reset.",
+		handler: async (args, ctx) => {
+			const nextLabel = args.trim();
+
+			if (!nextLabel) {
+				label = DEFAULT_LABEL;
+				ctx.ui.setHiddenThinkingLabel();
+				ctx.ui.notify(`Hidden thinking label reset to: ${DEFAULT_LABEL}`);
+				return;
+			}
+
+			label = nextLabel;
+			ctx.ui.setHiddenThinkingLabel(label);
+			ctx.ui.notify(`Hidden thinking label set to: ${label}`);
+		},
+	});
+}

package/examples/extensions/qna.ts

@@ -77,7 +77,10 @@ export default function (pi: ExtensionAPI) {
 
 				// Do the work
 				const doExtract = async () => {
-					const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+					const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model!);
+					if (!auth.ok || !auth.apiKey) {
+						throw new Error(auth.ok ? `No API key for ${ctx.model!.provider}` : auth.error);
+					}
 					const userMessage: UserMessage = {
 						role: "user",
 						content: [{ type: "text", text: lastAssistantText! }],
@@ -87,7 +90,7 @@ export default function (pi: ExtensionAPI) {
 					const response = await complete(
 						ctx.model!,
 						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
-						{ apiKey, signal: loader.signal },
+						{ apiKey: auth.apiKey, headers: auth.headers, signal: loader.signal },
 					);
 
 					if (response.stopReason === "aborted") {

package/examples/extensions/sandbox/index.ts

@@ -5,6 +5,10 @@
  * restrictions on bash commands at the OS level (sandbox-exec on macOS,
  * bubblewrap on Linux).
  *
+ * Note: this example intentionally overrides the built-in `bash` tool to show
+ * how built-in tools can be replaced. Alternatively, you could sandbox `bash`
+ * via `tool_call` input mutation without replacing the tool.
+ *
  * Config files (merged, project takes precedence):
  * - ~/.pi/agent/sandbox.json (global)
  * - <cwd>/.pi/sandbox.json (project-local)

package/examples/extensions/summarize.ts

@@ -165,12 +165,15 @@ export default function (pi: ExtensionAPI) {
 				ctx.ui.notify("Model openai/gpt-5.2 not found", "warning");
 			}
 
-			const apiKey = model ? await ctx.modelRegistry.getApiKey(model) : undefined;
-			if (!apiKey && ctx.hasUI) {
+			const auth = model ? await ctx.modelRegistry.getApiKeyAndHeaders(model) : undefined;
+			if (auth && !auth.ok && ctx.hasUI) {
+				ctx.ui.notify(auth.error, "warning");
+			}
+			if (auth?.ok && !auth.apiKey && ctx.hasUI) {
 				ctx.ui.notify("No API key for openai/gpt-5.2", "warning");
 			}
 
-			if (!model || !apiKey) {
+			if (!model || !auth?.ok || !auth.apiKey) {
 				return;
 			}
 
@@ -182,7 +185,15 @@ export default function (pi: ExtensionAPI) {
 				},
 			];
 
-			const response = await complete(model, { messages: summaryMessages }, { apiKey, reasoningEffort: "high" });
+			const response = await complete(
+				model,
+				{ messages: summaryMessages },
+				{
+					apiKey: auth.apiKey,
+					headers: auth.headers,
+					reasoningEffort: "high",
+				},
+			);
 
 			const summary = response.content
 				.filter((c): c is { type: "text"; text: string } => c.type === "text")

package/examples/extensions/trigger-compact.ts

@@ -3,6 +3,8 @@ import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-age
 const COMPACT_THRESHOLD_TOKENS = 100_000;
 
 export default function (pi: ExtensionAPI) {
+	let previousTokens: number | null | undefined;
+
 	const triggerCompaction = (ctx: ExtensionContext, customInstructions?: string) => {
 		if (ctx.hasUI) {
 			ctx.ui.notify("Compaction started", "info");
@@ -24,7 +26,15 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("turn_end", (_event, ctx) => {
 		const usage = ctx.getContextUsage();
-		if (!usage || usage.tokens === null || usage.tokens <= COMPACT_THRESHOLD_TOKENS) {
+		const currentTokens = usage?.tokens ?? null;
+		if (currentTokens === null) {
+			return;
+		}
+
+		const crossedThreshold =
+			previousTokens !== undefined && previousTokens !== null && previousTokens <= COMPACT_THRESHOLD_TOKENS;
+		previousTokens = currentTokens;
+		if (!crossedThreshold || currentTokens <= COMPACT_THRESHOLD_TOKENS) {
 			return;
 		}
 		triggerCompaction(ctx);