@astralyn/pi 0.85.3 → 0.86.1

package/dist/utils/wsl.js

@@ -0,0 +1,15 @@
+import { readFileSync } from "node:fs";
+/** Windows Subsystem for Linux, where Windows executables are reachable through interop. */
+export function isWSL(env = process.env) {
+    if (env.WSL_DISTRO_NAME || env.WSLENV) {
+        return true;
+    }
+    try {
+        const release = readFileSync("/proc/version", "utf-8");
+        return /microsoft|wsl/i.test(release);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=wsl.js.map

package/dist/utils/wsl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wsl.js","sourceRoot":"","sources":["../../src/utils/wsl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC,4FAA4F;AAC5F,MAAM,UAAU,KAAK,CAAC,MAAyB,OAAO,CAAC,GAAG;IACzD,IAAI,GAAG,CAAC,eAAe,IAAI,GAAG,CAAC,MAAM,EAAE,CAAC;QACvC,OAAO,IAAI,CAAC;IACb,CAAC;IAED,IAAI,CAAC;QACJ,MAAM,OAAO,GAAG,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;QACvD,OAAO,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,KAAK,CAAC;IACd,CAAC;AACF,CAAC","sourcesContent":["import { readFileSync } from \"node:fs\";\n\n/** Windows Subsystem for Linux, where Windows executables are reachable through interop. */\nexport function isWSL(env: NodeJS.ProcessEnv = process.env): boolean {\n\tif (env.WSL_DISTRO_NAME || env.WSLENV) {\n\t\treturn true;\n\t}\n\n\ttry {\n\t\tconst release = readFileSync(\"/proc/version\", \"utf-8\");\n\t\treturn /microsoft|wsl/i.test(release);\n\t} catch {\n\t\treturn false;\n\t}\n}\n"]}

package/dist/utils/zip.d.ts

@@ -0,0 +1,7 @@
+interface ZipEntry {
+    name: string;
+    data: string | Uint8Array;
+}
+export declare function writeZipArchive(filePath: string, entries: readonly ZipEntry[]): Promise<void>;
+export {};
+//# sourceMappingURL=zip.d.ts.map

package/dist/utils/zip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip.d.ts","sourceRoot":"","sources":["../../src/utils/zip.ts"],"names":[],"mappings":"AAGA,UAAU,QAAQ;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,UAAU,CAAC;CAC1B;AA+DD,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,QAAQ,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7F"}

package/dist/utils/zip.js

@@ -0,0 +1,60 @@
+import { writeFile } from "node:fs/promises";
+import { crc32, deflateRawSync } from "node:zlib";
+function dosDateTime(date) {
+    return {
+        time: (date.getHours() << 11) | (date.getMinutes() << 5) | (date.getSeconds() >> 1),
+        day: ((Math.max(1980, date.getFullYear()) - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate(),
+    };
+}
+/** Create the small, classic ZIP archives used by bug reports. */
+function createZipArchive(entries) {
+    const files = [];
+    const directory = [];
+    const { time, day } = dosDateTime(new Date());
+    let offset = 0;
+    for (const entry of entries) {
+        const name = Buffer.from(entry.name);
+        const data = typeof entry.data === "string" ? Buffer.from(entry.data) : Buffer.from(entry.data);
+        const compressed = deflateRawSync(data);
+        const checksum = crc32(data);
+        const local = Buffer.alloc(30);
+        local.writeUInt32LE(0x04034b50, 0);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(0x0800, 6);
+        local.writeUInt16LE(8, 8);
+        local.writeUInt16LE(time, 10);
+        local.writeUInt16LE(day, 12);
+        local.writeUInt32LE(checksum, 14);
+        local.writeUInt32LE(compressed.length, 18);
+        local.writeUInt32LE(data.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        const central = Buffer.alloc(46);
+        central.writeUInt32LE(0x02014b50, 0);
+        central.writeUInt16LE(20, 4);
+        central.writeUInt16LE(20, 6);
+        central.writeUInt16LE(0x0800, 8);
+        central.writeUInt16LE(8, 10);
+        central.writeUInt16LE(time, 12);
+        central.writeUInt16LE(day, 14);
+        central.writeUInt32LE(checksum, 16);
+        central.writeUInt32LE(compressed.length, 20);
+        central.writeUInt32LE(data.length, 24);
+        central.writeUInt16LE(name.length, 28);
+        central.writeUInt32LE(offset, 42);
+        files.push(local, name, compressed);
+        directory.push(central, name);
+        offset += local.length + name.length + compressed.length;
+    }
+    const centralDirectory = Buffer.concat(directory);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50, 0);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(centralDirectory.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...files, centralDirectory, end]);
+}
+export function writeZipArchive(filePath, entries) {
+    return writeFile(filePath, createZipArchive(entries));
+}
+//# sourceMappingURL=zip.js.map

package/dist/utils/zip.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip.js","sourceRoot":"","sources":["../../src/utils/zip.ts"],"names":[],"mappings":"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","sourcesContent":["import { writeFile } from \"node:fs/promises\";\nimport { crc32, deflateRawSync } from \"node:zlib\";\n\ninterface ZipEntry {\n\tname: string;\n\tdata: string | Uint8Array;\n}\n\nfunction dosDateTime(date: Date): { time: number; day: number } {\n\treturn {\n\t\ttime: (date.getHours() << 11) | (date.getMinutes() << 5) | (date.getSeconds() >> 1),\n\t\tday: ((Math.max(1980, date.getFullYear()) - 1980) << 9) | ((date.getMonth() + 1) << 5) | date.getDate(),\n\t};\n}\n\n/** Create the small, classic ZIP archives used by bug reports. */\nfunction createZipArchive(entries: readonly ZipEntry[]): Buffer {\n\tconst files: Buffer[] = [];\n\tconst directory: Buffer[] = [];\n\tconst { time, day } = dosDateTime(new Date());\n\tlet offset = 0;\n\n\tfor (const entry of entries) {\n\t\tconst name = Buffer.from(entry.name);\n\t\tconst data = typeof entry.data === \"string\" ? Buffer.from(entry.data) : Buffer.from(entry.data);\n\t\tconst compressed = deflateRawSync(data);\n\t\tconst checksum = crc32(data);\n\n\t\tconst local = Buffer.alloc(30);\n\t\tlocal.writeUInt32LE(0x04034b50, 0);\n\t\tlocal.writeUInt16LE(20, 4);\n\t\tlocal.writeUInt16LE(0x0800, 6);\n\t\tlocal.writeUInt16LE(8, 8);\n\t\tlocal.writeUInt16LE(time, 10);\n\t\tlocal.writeUInt16LE(day, 12);\n\t\tlocal.writeUInt32LE(checksum, 14);\n\t\tlocal.writeUInt32LE(compressed.length, 18);\n\t\tlocal.writeUInt32LE(data.length, 22);\n\t\tlocal.writeUInt16LE(name.length, 26);\n\n\t\tconst central = Buffer.alloc(46);\n\t\tcentral.writeUInt32LE(0x02014b50, 0);\n\t\tcentral.writeUInt16LE(20, 4);\n\t\tcentral.writeUInt16LE(20, 6);\n\t\tcentral.writeUInt16LE(0x0800, 8);\n\t\tcentral.writeUInt16LE(8, 10);\n\t\tcentral.writeUInt16LE(time, 12);\n\t\tcentral.writeUInt16LE(day, 14);\n\t\tcentral.writeUInt32LE(checksum, 16);\n\t\tcentral.writeUInt32LE(compressed.length, 20);\n\t\tcentral.writeUInt32LE(data.length, 24);\n\t\tcentral.writeUInt16LE(name.length, 28);\n\t\tcentral.writeUInt32LE(offset, 42);\n\n\t\tfiles.push(local, name, compressed);\n\t\tdirectory.push(central, name);\n\t\toffset += local.length + name.length + compressed.length;\n\t}\n\n\tconst centralDirectory = Buffer.concat(directory);\n\tconst end = Buffer.alloc(22);\n\tend.writeUInt32LE(0x06054b50, 0);\n\tend.writeUInt16LE(entries.length, 8);\n\tend.writeUInt16LE(entries.length, 10);\n\tend.writeUInt32LE(centralDirectory.length, 12);\n\tend.writeUInt32LE(offset, 16);\n\treturn Buffer.concat([...files, centralDirectory, end]);\n}\n\nexport function writeZipArchive(filePath: string, entries: readonly ZipEntry[]): Promise<void> {\n\treturn writeFile(filePath, createZipArchive(entries));\n}\n"]}

package/docs/compaction.md

@@ -26,12 +26,12 @@ Both use the same structured summary format and track file operations cumulative
 Auto-compaction triggers when:
 
 ```
-contextTokens > contextWindow × triggerPercent / 100
+contextTokens > contextWindow − reserveTokens
 ```
 
-By default, `triggerPercent` is 85 (configurable in `~/.pi/agent/settings.json` or `<project-dir>/.pi/settings.json`, accepted range 20–95 with out-of-range values clamped): compaction starts once context usage passes 85% of the model's context window — e.g. ~850K tokens on a 1M window or ~170K on a 200K window. Non-finite SDK values fall back to 85. Retention and summary budgets also shrink for smaller windows or lower trigger percentages, as described below.
+`reserveTokens` comes from `triggerPercent` (default 85, accepted range 20–95 with out-of-range values clamped, configurable in `~/.pi/agent/settings.json` or `<project-dir>/.pi/settings.json`): the reserve is whatever is left above that percentage of the active model's context window. Compaction therefore starts once usage passes 85% of the window — ~850K tokens on a 1M window, ~170K on a 200K window. Non-finite values fall back to 85.
 
-> **Distribution note:** upstream Pi triggers at `contextWindow − reserveTokens` (a fixed 16384-token reserve by default), which on large windows delays compaction until ~98% usage. This distribution replaces that setting with the proportional `triggerPercent`. A `reserveTokens` key left over in an existing settings file is ignored; it no longer has any effect.
+> **Distribution note:** upstream Pi's default is a fixed 16384-token reserve, which on large windows delays compaction until ~98% usage. This distribution derives the reserve from `triggerPercent` instead. Setting `compaction.reserveTokens` explicitly — globally or per model — still wins and restores upstream's fixed-reserve behavior for that model.
 
 During a multi-turn agent run, Pi checks this threshold after tools finish and their results are appended, before starting the next assistant response. If the threshold is crossed, Pi compacts inside the same agent run and resumes with the summary and retained messages. It skips this between-turn check when the completed tool batch terminates the run and no queued message requires another response. Pi also checks the threshold before a new user prompt and after a low-level agent run ends.
 
@@ -41,17 +41,15 @@ You can also trigger manually with `/compact [instructions]`, where optional ins
 
 ### How It Works
 
-1. **Find cut point**: Walk backwards from newest message until the effective retention target is reached: `keepRecentTokens` (default 20k), capped at half the configured trigger's token budget
+1. **Find cut point**: Walk backwards from newest message until the effective retention target is reached: `keepRecentTokens` (default 20k), capped at half the trigger line when the reserve comes from `triggerPercent`
 2. **Extract messages**: Collect messages from the previous kept boundary (or session start) up to the cut point
 3. **Generate summary**: Call LLM to summarize with structured format, passing the previous summary as iterative context when present
 4. **Append entry**: Save `CompactionEntry` with summary and `firstKeptEntryId`
 5. **Rebuilds context**: Session rebuilds the context for the next request, using summary + messages from `firstKeptEntryId` onwards
 
-For both automatic and manual compaction, the model's context window limits the recent-message target to half the trigger budget. The internal summary reserve is capped at one quarter of that budget, up to its existing 16384-token maximum. History summaries can use 80% of this reserve and split-turn prefix summaries can use 50%; each is also limited by the model's output cap. This leaves room below the trigger for summary framing and continued work instead of retaining the entire context at a low threshold. The configured settings are not rewritten.
+Retaining more than half the trigger line would leave the compacted context close to the line again, so a derived reserve also caps the recent-message target at half that line. History summaries can use 80% of `reserveTokens` and split-turn prefix summaries can use 50%; each is also limited by the model's output cap, which is the binding limit whenever the derived reserve is large. These are budget targets, not hard bounds on retained content: whole messages and tool-call/result groups remain intact and can exceed the target.
 
-For example, a 64K window with `triggerPercent: 20` triggers above 12.8K tokens. Its recent-message target is at most 6.4K, with output limits of 2560 tokens for a history summary and 1600 for a split-turn prefix summary. Default 200K and 1M windows keep the existing retention and summary budgets. These are budget targets, not hard bounds on retained content: whole messages and tool-call/result groups remain intact and can exceed the target.
-
-SDK callers using `prepareCompaction()` directly should pass `model.contextWindow` as the third argument to apply the same retention cap. The two-argument form preserves the configured retention target when the window is unknown.
+For example, a 64K window with `triggerPercent: 20` triggers above 12.8K tokens, reserves the remaining 51.2K, and retains at most 6.4K of recent messages. The configured settings are not rewritten; `compaction.keepRecentTokens` keeps its configured value for models whose window is unknown.
 
 ```
 Before compaction:
@@ -299,7 +297,7 @@ pi.on("session_before_compact", async (event, ctx) => {
   // preparation.fileOps - extracted file operations
   // preparation.tokensBefore - context tokens before compaction
   // preparation.firstKeptEntryId - where kept messages start
-  // preparation.settings - compaction settings
+  // preparation.settings - effective settings after applying model overrides
 
   // branchEntries - all entries on current branch (for custom state)
   // reason - "manual" (/compact), "threshold", or "overflow"
@@ -421,8 +419,31 @@ Configure compaction in `~/.pi/agent/settings.json` or `<project-dir>/.pi/settin
 |---------|---------|-------------|
 | `enabled` | `true` | Enable auto-compaction |
 | `triggerPercent` | `85` | Percentage of the context window that triggers auto-compaction (clamped to 20–95) |
-| `keepRecentTokens` | `20000` | Recent-message retention target, capped at half the trigger token budget when the model window is known |
+| `reserveTokens` | derived | Fixed reserve below the window; overrides `triggerPercent` for the models it applies to |
+| `keepRecentTokens` | `20000` | Recent-message retention target, capped at half the trigger line when the reserve is derived |
 
 Disable auto-compaction with `"enabled": false`. You can still compact manually with `/compact`.
 
-Upstream Pi's `compaction.reserveTokens` setting does not exist here and is ignored when present; the trigger is always the percentage above.
+### Per-model overrides
+
+Use `compaction.modelOverrides` to tune the reserve and the retention target per model:
+
+```json
+{
+  "compaction": {
+    "keepRecentTokens": 20000,
+    "modelOverrides": {
+      "some-provider/big-model": {
+        "reserveTokens": 32768,
+        "keepRecentTokens": 150000
+      }
+    }
+  }
+}
+```
+
+Keys are exact, case-sensitive `provider/modelId` values, including any slashes within the model ID. Each value falls back independently from the model override to the ordinary setting to the built-in default; an override's `reserveTokens` replaces the percentage-derived reserve for that model only. Values must be non-negative safe integers. Invalid values in the matching model override produce an error when read; only omitted fields fall back to the ordinary setting. Model override entries must be objects. Invalid ordinary token settings produce an error when read, even if the active model has a valid override. `enabled` and `triggerPercent` remain global, not model-specific.
+
+These resolved values are used for manual compaction, all automatic threshold checks, overflow recovery, and extension-visible `preparation.settings`, which carries the resolved `reserveTokens` rather than the percentage. Model switches affect subsequent checks and compactions without changing ordinary settings. Compaction already in progress uses the model and settings captured for that operation. Branch summarization settings are unaffected.
+
+Overrides work in both global and project settings. The files merge recursively before lookup, so a global model-specific value beats a project-wide fallback; a project must override that model entry to change it. See [settings.md](settings.md#per-model-compaction-overrides) for details.

package/docs/custom-provider.md

@@ -303,24 +303,32 @@ Implement `streamSimple` only for a protocol that cannot use a built-in API tag
 
 The configuration-form handler signature is exactly:
 
+The context is a normalized transcript: the system prompt and tool declarations live in its system messages, so read them with `getCurrentSystemPrompt(context.messages)` and `getCurrentTools(context.messages)` rather than expecting `context.systemPrompt` or `context.tools`. Models that accept system messages mid-conversation can send them in place; otherwise call `collapseSystemMessages(context)` first to fold later system messages into the leading one.
+
 ```typescript
 import {
   type Api,
   type AssistantMessage,
   type AssistantMessageEventStream,
-  calculateCost,
-  type Context,
-  createAssistantMessageEventStream,
   type Model,
   type SimpleStreamOptions,
+  type TranscriptContext,
+  calculateCost,
+  collapseSystemMessages,
+  createAssistantMessageEventStream,
+  getCurrentSystemPrompt,
+  getCurrentTools,
 } from "@earendil-works/pi-ai";
 
 function streamMyProvider(
-  model: Model<Api>,
-  context: Context,
-  options?: SimpleStreamOptions,
+  model: Model<any>,
+  context: TranscriptContext,
+  options?: SimpleStreamOptions
 ): AssistantMessageEventStream {
   const stream = createAssistantMessageEventStream();
+  const transcript = collapseSystemMessages(context);
+  const systemPrompt = getCurrentSystemPrompt(transcript.messages);
+  const tools = getCurrentTools(transcript.messages);
 
   void (async () => {
     const output: AssistantMessage = {
@@ -496,10 +504,10 @@ interface ProviderConfig {
   /** API type for streaming. Required at provider or model level when defining models. */
   api?: Api;
 
-  /** Custom streaming implementation for non-standard APIs. */
+  /** Custom streaming implementation for non-standard APIs. Receives a normalized transcript. */
   streamSimple?: (
     model: Model<Api>,
-    context: Context,
+    context: TranscriptContext,
     options?: SimpleStreamOptions
   ) => AssistantMessageEventStream;
 
@@ -555,6 +563,9 @@ interface ProviderModelConfig {
     cacheWrite: number;
   };
 
+  /** Best-effort prompt cache lifetime in seconds per retention tier. Unset disables cache warming. */
+  promptCache?: { short?: number; long?: number };
+
   /** Maximum context window size in tokens. */
   contextWindow: number;
 

package/docs/environment-variables.md

@@ -86,6 +86,7 @@ These variables are read by Pi itself:
 | `PI_TELEMETRY` | Override optional provider attribution headers: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable version checks |
 | `PI_CACHE_RETENTION` | Set to `long` for extended provider prompt caching where supported |
 | `PI_SHARE_VIEWER_URL` | Override the base URL used by `/share` |
+| `PI_RADIUS_GATEWAY` | Override the Radius gateway origin used by `/bug` uploads and Radius relay connections |
 | `PI_HARDWARE_CURSOR` | Set to `1` to show the hardware cursor; see [Terminal setup](terminal-setup.md) |
 | `PI_HYPERLINKS` | Override OSC 8 hyperlink detection with `1`, `0`, or `auto` |
 | `PI_IMAGE_PROTOCOL` | Override inline image detection with `kitty`, `iterm2`, `none`, or `auto` |

package/docs/extensions.md

@@ -550,10 +550,13 @@ pi.on("before_agent_start", async (event, ctx) => {
   // event.systemPrompt - current chained system prompt for this handler
   //   (includes changes from earlier before_agent_start handlers)
   // event.systemPromptOptions - structured options used to build the system prompt
-  //   .customPrompt - any custom system prompt (from --system-prompt, SYSTEM.md, or custom templates)
+  //   .customPrompt - exact prompt prefix from --system-prompt, SYSTEM.md, or custom templates
+  //   .forceSystemPrompt - optional exact replacement for the complete prompt
   //   .selectedTools - tools currently active in the prompt
   //   .toolSnippets - one-line descriptions for each tool
-  //   .promptGuidelines - custom guideline bullets
+  //   .toolGuidelines - guideline bullets keyed by tool name
+  //   .promptGuidelines - additional custom guideline bullets
+  //   .sections - custom XML-wrapped sections keyed by tag name
   //   .appendSystemPrompt - text from --append-system-prompt flags
   //   .cwd - working directory
   //   .contextFiles - AGENTS.md files and other loaded context files
@@ -572,7 +575,7 @@ pi.on("before_agent_start", async (event, ctx) => {
 });
 ```
 
-The `systemPromptOptions` field gives extensions access to the same structured data Pi uses to build the system prompt. This lets you inspect what Pi has loaded — custom prompts, guidelines, tool snippets, context files, skills — without re-discovering resources or re-parsing flags. Use it when your extension needs to make deep, informed changes to the system prompt while respecting user-provided configuration.
+The `systemPromptOptions` field gives extensions access to the same structured data Pi uses to build the system prompt. Collections are mutable. Prefer changing `sections`, `selectedTools`, or `promptGuidelines`: Pi diffs the resulting prompt sections against what the model already has and appends one system message patching only the changed sections. Returning `systemPrompt`, or setting `forceSystemPrompt`, replaces the whole prompt for the run: every provider receives the forced text as its leading system prompt (a cache miss when it changes), and the session transcript keeps recording the structured sections. Tool selection changes update both the prompt contributions and executable provider tools; calling `pi.setActiveTools()` inside the handler has the same effect as editing `selectedTools`. Models that accept system messages mid-conversation receive the patch in place and keep their cached prefix; other models get the replayed prompt as their system prompt, which is a cache miss once per change.
 
 Inside `before_agent_start`, `event.systemPrompt` and `ctx.getSystemPrompt()` both reflect the chained system prompt as of the current handler. Later `before_agent_start` handlers can still modify it again.
 
@@ -749,6 +752,25 @@ pi.on("after_provider_response", (event, ctx) => {
 
 Header availability depends on provider and transport. Providers that abstract HTTP responses may not expose headers.
 
+#### cache_warming_decision
+
+Fired before each prompt-cache refresh with pi's decision filled in. The event carries only pi's cost estimates; use `ctx.model`, `ctx.isIdle()`, and `ctx.getContextUsage()` for everything else.
+
+```typescript
+pi.on("cache_warming_decision", (event, ctx) => {
+  // event.warmCost: price of this refresh
+  // event.missCost: extra price of the next request if the entry is lost
+  // event.continuationProbability: pi's estimate that a request arrives in time
+  // event.action: "warm" | "stop", pi's decision
+
+  if (ctx.model?.provider === "my-provider") {
+    return { action: "stop" };
+  }
+});
+```
+
+Return `{ action: "warm" }` or `{ action: "stop" }` to override; the last handler that returns an action wins. `"stop"` ends warming until the next real request.
+
 ### Model Events
 
 #### model_select
@@ -923,6 +945,8 @@ pi.on("user_bash", (event, ctx) => {
 });
 ```
 
+Returning `undefined` continues to the next handler, then local execution if none handles the event. A valid result stops propagation: `operations` executes the command through the supplied backend, while `result` records the completed command without executing it.
+
 ### Input Events
 
 #### input
@@ -1033,6 +1057,12 @@ Access to models, providers, and resolved authentication. `ctx.modelRegistry.get
 
 `ctx.scopedModels` is the read-only list of models scoped to the current session—the same set shown by `/scoped-models`. Pi resolves it at session start from `--models` and the `enabledModels` setting, matching `provider/modelId` or bare `modelId` patterns with minimatch. An empty list means no scope is configured and every available model is usable. Each entry is `{ model, thinkingLevel? }`; use this list when a custom model picker should mirror the built-in scope rather than enumerate the full registry.
 
+#### Streaming model calls
+
+Use `ctx.modelRegistry.streamSimple(model, context, options)` for provider-neutral options such as `reasoning`, or `stream()` for API-specific options. Both use configured providers and resolve authentication, including for providers registered with `pi.registerProvider()`. Use these instead of `pi-ai/compat` streaming functions, which cannot see extension provider registrations.
+
+Both return an `AssistantMessageEventStream`. Iterate it for response events and await `.result()` for the final message. Setup failures produce error events and error results.
+
 ### ctx.signal
 
 The current agent abort signal, or `undefined` when no agent turn is active.
@@ -1194,6 +1224,8 @@ if (usage && usage.tokens > 100_000) {
 
 Returns a `Promise<ContextSnapshot>` with detached stable messages, effective system prompt, model, thinking level, active tool metadata in order, source session/leaf IDs, capture time, and `streamOptions`. It captures source state synchronously before awaiting preparation; partially streamed assistant frames are excluded. It throws if no model is selected.
 
+`messages` is the prepared transcript, so it starts with the session's `system` message once a request has been made, and `systemPrompt` is the prompt replayed from that transcript, including a prompt forced by `before_agent_start` for the last request. A native `Agent` seeded with these messages keeps that leading system message instead of declaring `systemPrompt` again. Before the first request, `messages` carry no system message and `systemPrompt` is the session's current prompt.
+
 The SDK reuses the message prefix already prepared for the most recent main request when it still matches the current branch and image policy, then converts newly settled messages. This preserves context-hook changes without replaying those hooks over the prefix. Before the first request, or after replacing the branch or image policy, it prepares the detached context once through the current context hooks and message conversion. It does not rerun `before_agent_start`, persist messages, or execute tools.
 
 `streamOptions` includes transport, thinking budgets, timeouts, retries, provider hooks and header transforms. It contains callbacks, so the snapshot is not a JSON serialization format. Credentials are resolved through `ctx.modelRuntime`; the main run's abort signal and tool executors are never included. Provider hooks still run for each request and can change serialized payloads, so arbitrary external hooks can affect prefix reuse.
@@ -1252,7 +1284,7 @@ const options = ctx.getSystemPromptOptions();
 const contextPaths = options.contextFiles?.map((file) => file.path) ?? [];
 ```
 
-This has the same shape and mutability as `before_agent_start` `event.systemPromptOptions`: custom prompt, active tools, tool snippets, prompt guidelines, appended system prompt text, cwd, loaded context files, and loaded skills. It may include full context file contents, so treat it as sensitive extension-local data and avoid exposing it through command lists, logs, or autocomplete metadata.
+This has the same shape and mutability as `before_agent_start` `event.systemPromptOptions`: custom or forced prompt, active tools, tool snippets, per-tool and custom rules, custom sections, appended prompt text, cwd, loaded context files, and loaded skills. It may include full context file contents, so treat it as sensitive extension-local data and avoid exposing it through command lists, logs, or autocomplete metadata.
 
 This reports the current base prompt inputs. It does not include per-turn `before_agent_start` chained system-prompt changes, later `context` event message mutations, or `before_provider_request` payload rewrites.
 
@@ -1330,7 +1362,7 @@ Options:
 
 ### ctx.navigateTree(targetId, options?)
 
-Navigate to a different point in the session tree:
+Navigate to a different point in the session tree. Rejects while an agent response, manual or automatic compaction, or another tree navigation is active, even with `summarize: false`. These conflicts leave the active branch unchanged and reject the promise rather than returning `{ cancelled: true }`. Wait for the active operation to finish (for example, with `await ctx.waitForIdle()` in a command handler) and retry:
 
 ```typescript
 const result = await ctx.navigateTree("entry-id-456", {
@@ -1499,7 +1531,16 @@ export default function (pi: ExtensionAPI) {
 
 ### pi.on(event, handler)
 
-Subscribe to events. See [Events](#events) for event types and return values.
+Subscribe to events. Returns an unsubscribe function that removes only that registration. See [Events](#events) for event types and return values.
+
+```typescript
+const unsubscribe = pi.on("agent_end", async (event) => {
+  unsubscribe();
+  await updateIntegration(event.messages);
+});
+```
+
+Handlers run in extension load order, then registration order within each extension. Adding or removing a handler does not affect a dispatch already in progress.
 
 ### pi.registerTool(definition)
 
@@ -2523,38 +2564,13 @@ If a slot renderer is not defined or throws:
 
 ### Dynamic Tool Loading
 
-Extensions can register many tools while keeping only a small initial set active. A tool can then add more tools with `pi.setActiveTools()` during execution. Pi detects purely additive changes, records the newly available tool names on that tool result, and applies the updated active set before the next model request.
-
-This works with every model. Models with native deferred-loading support preserve the stable prompt prefix and load the new definitions at the tool-result position. Other models use the fallback described below.
+Extensions can register many tools while keeping only a small initial set active. A tool can then change the active set with `pi.setActiveTools()` during execution. Pi stores the initial prompt and tool loadout in the transcript's first system message, then appends tool and prompt deltas before the next model request. Providers that cannot represent a transition receive a complete transcript checkpoint, which may invalidate the cached prefix.
 
 The lifecycle is:
 
 1. Register every tool with `pi.registerTool()` so it appears in `pi.getAllTools()`.
 2. Keep loader tools, such as `search_tools`, active and leave searchable tools inactive.
-3. During loader execution, call `pi.setActiveTools([...currentTools, ...matchingTools])`. The change must be additive: do not remove currently active tools in the same call.
-4. Pi records which tools were added on the loader's tool result.
-5. Before the next model response, Pi exposes the added definitions using native deferred loading when supported, or the normal active tool list otherwise.
-
-You do not need to return provider-specific tool references or mark the loader as a special search tool. The active-tool change is the signal. Names passed to `pi.setActiveTools()` must already be registered; unknown names are ignored.
-
-#### Models with native deferred loading
-
-- **Anthropic**
-  - **Models:** Sonnet, Opus, Fable version 4.5 or newer (without Haiku)
-  - **Native representation:** Deferred definitions use `defer_loading`; the load point uses `tool_reference` content.
-- **OpenAI**
-  - **Models:** `gpt-5.4` and newer family
-  - **Native representation:** Pi adds completed client `tool_search_call` and `tool_search_output` items at the load point.
-
-For a verified custom model or proxy, native handling can be enabled with `compat.supportsToolReferences: true` for `anthropic-messages`, or `compat.supportsToolSearch: true` for `openai-responses` and `openai-codex-responses`. Leave these disabled unless the endpoint and model accept the corresponding native protocol.
-
-#### Fallback behavior
-
-For all other models and providers, dynamic activation still works: Pi sends the complete current active tool list normally on the next request. The model can call the newly activated tools, but adding their definitions may invalidate the provider's cached prompt prefix.
-
-Pi also uses this safe fallback when the active set is not purely additive, such as replacing one group of tools with another. Tool removals therefore work, but they do not use deferred loading.
-
-For the best cache behavior, keep the loader tool active for the whole session and add tools instead of replacing the active set. Also note that activating a tool with `promptSnippet` or `promptGuidelines` rebuilds the system prompt; that system-prompt change can invalidate the prefix even when the provider supports deferred schemas. Lazily loaded tools should usually rely on their tool `description` and omit active-only prompt metadata.
+3. During loader execution, call `pi.setActiveTools()` with the desired active tool names. Names must already be registered; unknown names are ignored.
 
 #### Search tool example
 
@@ -2656,7 +2672,7 @@ export default function (pi: ExtensionAPI) {
 }
 ```
 
-When `search_tools` adds a match, the model receives that definition on the immediately following request. On a native-capable model the definition is anchored after the search result without changing the initial tool-schema prefix. On other models it appears in the normal tool list on that same following request.
+When `search_tools` adds a match, the model receives the complete updated tool list on the immediately following request.
 
 ## Custom UI
 

package/docs/models.md

@@ -15,6 +15,7 @@ Pi reads this file at startup and on a model refresh, including when you open `/
   - [Custom Headers](#custom-headers)
 - [Model Configuration](#model-configuration)
   - [Thinking Level Map](#thinking-level-map)
+  - [Prompt Cache Lifetimes](#prompt-cache-lifetimes)
 - [Overriding Built-in Providers](#overriding-built-in-providers)
 - [Per-model Overrides](#per-model-overrides)
 - [Compatibility Options](#compatibility-options)
@@ -246,6 +247,7 @@ A `models` entry supplies a complete custom model definition with useful default
 | `maxTokens` | No | `16384` | Maximum generated tokens. |
 | `samplingParams` | No | omitted | Free-form sampling parameters merged verbatim into every request body; see [Sampling Parameters](#sampling-parameters). |
 | `cost` | No | all rates `0` | Per-million-token rates and optional request-wide price tiers. |
+| `promptCache` | No | omitted | Best-effort prompt cache lifetime in seconds per retention tier; see [Prompt Cache Lifetimes](#prompt-cache-lifetimes). |
 | `headers` | No | omitted | Model-specific request headers; see [Custom Headers](#custom-headers). |
 | `compat` | No | provider `compat` | Compatibility refinements merged with provider defaults. |
 
@@ -273,6 +275,19 @@ When `cost` is supplied on a `models` entry, it must contain all four base rates
 }
 ```
 
+### Prompt Cache Lifetimes
+
+`promptCache` states how long the provider keeps a prompt cache entry alive for each retention tier Pi can request (`short` is the default tier; `long` is used when `PI_CACHE_RETENTION=long`). Values are seconds and are estimates: providers publish ranges, so pick the conservative end.
+
+```json
+{
+  "id": "claude-sonnet-5",
+  "promptCache": { "short": 300, "long": 3600 }
+}
+```
+
+The built-in catalog fills this in for direct Anthropic (5 min / 1 h). Other providers, including direct OpenAI, have no built-in lifetime until their cache-expiry and replay behavior has been validated for warming. A model without a value for the tier a request used is never warmed; custom models and provider overrides can opt in when the backing cache behavior is known. See [Cache Warming](settings.md#cache-warming).
+
 ### Sampling Parameters
 
 `samplingParams` is a free-form object merged verbatim into every request body for the model, after the fields pi sets itself, so its keys win. Use it to send sampling parameters pi does not model — including server-specific ones like llama.cpp's `min_p` or vLLM's `top_k`:
@@ -390,7 +405,23 @@ The built-in models remain. A new custom `id` is added, while a matching ID is r
 }
 ```
 
-An override supports `name`, `reasoning`, `thinkingLevelMap`, `input`, `cost`, `contextWindow`, `maxTokens`, `samplingParams` (merged per key), `headers`, and `compat`. Its `cost` base rates are individually optional and retain omitted values; a supplied `tiers` array replaces the existing array. Thinking maps merge by level. `compat` merges by field, and its `openRouterRouting`, `vercelGatewayRouting`, and `chatTemplateKwargs` objects merge by key.
+An override supports `name`, `reasoning`, `thinkingLevelMap`, `input`, `cost`, `promptCache` (merged per tier), `contextWindow`, `maxTokens`, `samplingParams` (merged per key), `headers`, and `compat`. Its `cost` base rates are individually optional and retain omitted values; a supplied `tiers` array replaces the existing array. Thinking maps merge by level. `compat` merges by field, and its `openRouterRouting`, `vercelGatewayRouting`, and `chatTemplateKwargs` objects merge by key.
+
+Use a `promptCache` override to enable cache warming through a proxy whose backing cache you know, for example OpenRouter routed to Anthropic:
+
+```json
+{
+  "providers": {
+    "openrouter": {
+      "modelOverrides": {
+        "anthropic/claude-sonnet-4": {
+          "promptCache": { "short": 300 }
+        }
+      }
+    }
+  }
+}
+```
 
 Direct OpenAI GPT-5.6 Sol, Terra, and Luna default to a `272000` context window so requests remain within OpenAI's short-context pricing tier. To use the 1.05M context window, override each model you use:
 
@@ -428,7 +459,10 @@ For `api: "anthropic-messages"`, use these options for Anthropic-compatible endp
 | `forceAdaptiveThinking` | Uses adaptive thinking (`thinking.type: "adaptive"` and `output_config.effort`) regardless of model ID. Default: `false`. |
 | `allowEmptySignature` | Replays an empty thinking signature as `signature: ""` instead of converting the thinking block to text. Default: `false`. |
 | `supportsStrictTools` | Accepts strict JSON-schema tool definitions. Default: `false`; capable built-in Anthropic models set it in their metadata. |
-| `supportsToolReferences` | Accepts deferred tool loading with `tool_reference` blocks. The default is enabled only for supported recent first-party Anthropic models, and otherwise `false`. |
+| `supportsMidConvoEffort` | Accepts effort-only system messages and thinking binding controls. Default: `false`. |
+| `supportsMidConvoSystemMessages` | Accepts system-role messages inside the conversation. When `false`, later system messages fold into the top-level system prompt. Default: `false`. |
+| `supportsMidConvoToolChanges` | Accepts mid-conversation `tool_addition` and `tool_removal` blocks. Requires `supportsMidConvoSystemMessages`. Default: `false`. |
+| `allowedFallbackModels` | Models Anthropic accepts in `fallbacks` for server-side refusal fallback, with local pricing metadata for returned fallback responses. Omit `fallbacks` when empty. |
 
 For example, a proxy that lacks eager streaming but supports long cache retention and adaptive thinking can use:
 
@@ -486,7 +520,8 @@ For `api: "openai-completions"`, Pi auto-detects many defaults from the provider
 | `sessionAffinityFormat` | `openai` sends `session_id`, `x-client-request-id`, and `x-session-affinity`; `openai-nosession` omits `session_id`; `openrouter` sends `x-session-id`. It does not change `prompt_cache_key`. Default: URL-detected. |
 | `supportsStrictMode` | Accepts strict JSON-schema function tools. Default: URL-detected. |
 | `supportsOpenAIGrammarTools` | Emits OpenAI Lark/regex grammar tools. When `false`, grammar-constrained tools fall back to normal function tools. Default: `false`. |
-| `deferredToolsMode` | Provider-specific deferred-tool serialization. The only value is `kimi`. |
+| `supportsMidConvoSystemMessages` | Accepts system or developer messages after the conversation has started. When `false`, later system messages fold into the leading system message. Default: `false`. |
+| `supportsMidConvoToolAdditions` | Accepts tools introduced by mid-conversation system messages. Requires `supportsMidConvoSystemMessages`. Default: `false`. |
 | `supportsLongCacheRetention` | Accepts long prompt-cache retention: `prompt_cache_retention: "24h"`, or `cache_control.ttl: "1h"` with `cacheControlFormat: "anthropic"`. Default: `true` except URL-detected incompatible endpoints. |
 | `openRouterRouting` | OpenRouter routing preferences sent unchanged in the request `provider` field. |
 | `vercelGatewayRouting` | Vercel AI Gateway routing preferences (`only`, `order`) sent as `providerOptions.gateway`. |

package/docs/providers.md

@@ -20,6 +20,7 @@ Use `/login` in interactive mode, then select a provider:
 - Claude Pro/Max
 - GitHub Copilot
 - xAI (Grok/X subscription)
+- Meta (Muse subscription)
 - OpenRouter (OAuth-minted API key billed from OpenRouter credits)
 - Radius
 
@@ -44,6 +45,12 @@ Anthropic subscription auth is active for Claude Pro/Max accounts. Third-party h
 - Run `/login xai`, then select **Use a subscription**
 - `XAI_API_KEY` remains available through **Use an API key**
 
+### Meta (Muse subscription)
+
+- Run `/login meta`, then select **Sign in with Meta** to open the device authorization flow
+- The login mints a Model API key that is re-minted automatically about once a day
+- `META_API_KEY` remains available through **Use an API key**
+
 ### OpenRouter
 
 - Run `/login openrouter`, then select **Sign in with OpenRouter** to open the OpenRouter PKCE authorization flow
@@ -53,7 +60,7 @@ Anthropic subscription auth is active for Claude Pro/Max accounts. Third-party h
 
 ### Radius
 
-Radius is a dynamic `pi-messages` gateway. `/login radius` stores OAuth tokens in `auth.json`; the gateway catalog is refreshed independently and cached in `models-store.json`. Custom Radius gateways can be declared in `models.json` with `"oauth": "radius"` and a gateway `baseUrl`.
+Radius is a `pi-messages` gateway. Pi ships the public Radius model catalog for immediate and offline model lookup, then overlays it with the effective gateway catalog after authentication. `/login radius` stores OAuth tokens in `auth.json`; refreshed catalogs are cached in `models-store.json`. Custom Radius gateways can be declared in `models.json` with `"oauth": "radius"` and a gateway `baseUrl`; they do not inherit the public `radius.pi.dev` catalog.
 
 ## API Keys
 
@@ -94,6 +101,7 @@ pi
 | Together AI | `TOGETHER_API_KEY` | `together` |
 | Baseten | `BASETEN_API_KEY` | `baseten` |
 | Kimi For Coding | `KIMI_API_KEY` | `kimi-coding` |
+| Meta | `META_API_KEY` | `meta` |
 | MiniMax | `MINIMAX_API_KEY` | `minimax` |
 | MiniMax (China) | `MINIMAX_CN_API_KEY` | `minimax-cn` |
 | Qwen Token Plan (existing catalog) | `QWEN_TOKEN_PLAN_API_KEY` | `qwen-token-plan` |

package/docs/sdk.md

@@ -118,6 +118,8 @@ interface AgentSession {
 }
 ```
 
+`session.navigateTree()` rejects while an agent response, manual or automatic compaction, or another tree navigation is active, even with `summarize: false`. It does not queue navigation or return `{ cancelled: true }` for these conflicts. Wait for the active operation to finish (for example, with `await session.waitForIdle()`) and retry. Rejection leaves the active branch unchanged.
+
 Session replacement APIs such as new-session, resume, fork, and import live on `AgentSessionRuntime`, not on `AgentSession`.
 
 ### createAgentSessionRuntime() and AgentSessionRuntime
@@ -330,8 +332,8 @@ const state = session.agent.state;
 // state.messages: AgentMessage[] - conversation history
 // state.model: Model - current model
 // state.thinkingLevel: ThinkingLevel - current thinking level
-// state.systemPrompt: string - system prompt
-// state.tools: AgentTool[] - available tools
+// state.systemPrompt: string - read-only, replayed from the transcript's system messages
+// state.tools: AgentTool[] - executable tools; changes are declared to the model before the next request
 // state.streamingMessage?: AgentMessage - current partial assistant message
 // state.errorMessage?: string - latest assistant error