@astralyn/pi 1.4.10 → 1.5.0

package/docs/extensions.md

@@ -143,7 +143,7 @@ To share extensions via npm or git as pi packages, see [packages.md](packages.md
 |---------|---------|
 | `@astralyn/pi` | Extension types (`ExtensionAPI`, `ExtensionContext`, events) |
 | `typebox` | Schema definitions for tool parameters |
-| `@earendil-works/pi-ai` | AI utilities (`StringEnum` for Google-compatible enums) |
+| `@earendil-works/pi-ai` | AI utilities (`StringEnum` for Google-compatible enums). Inside pi it also exports TypeBox's `Type`, `Static` and `TSchema`, which the published package no longer re-exports; import them from `typebox` in new code |
 | `@earendil-works/pi-agent-core` | Agent-core types for advanced integrations |
 | `@earendil-works/pi-tui` | TUI components for custom rendering |
 
@@ -153,6 +153,18 @@ For distributed pi packages installed with `pi install` (npm or git), runtime de
 
 Node.js built-ins (`node:fs`, `node:path`, etc.) are also available.
 
+### Tool parameter schemas and TypeBox
+
+Pi validates tool arguments as JSON Schema with `@earendil-works/pi-schema`, whatever built the schema; TypeBox schemas are JSON Schema and work unchanged. Before validation, loosely typed arguments are coerced: numeric strings to numbers, `"true"` to `true`, a single value to a one-item array, `null` in an optional property dropped. TypeBox features outside JSON Schema do not apply to tool arguments:
+
+- `Type.Refine()` refinements are not run. Check such constraints in `execute()`.
+- `Type.BigInt()`, `Type.Undefined()` and `Type.Void()` reject every argument, since JSON has no such values. Codecs (`Type.Codec()`) do not decode: `execute()` receives the JSON value.
+- Formats registered with TypeBox's `Format.Set()` are not checked. The standard formats are, plus `url` and `json-pointer-uri-fragment`.
+- Property names are matched as names, not as regular expressions, and `additionalProperties` applies only to properties the object does not declare.
+- A `$ref` that names nothing rejects only arguments at its place.
+
+Validation errors the model sees use pi-schema's messages, such as `- path: missing` or `- limit: expected number, got string`, followed by field hints that name the legal fields and a bounded echo of the received arguments.
+
 ## Writing an Extension
 
 An extension exports a default factory function that receives `ExtensionAPI`. The factory can be synchronous or asynchronous:
@@ -1259,10 +1271,7 @@ Session-bound `TasksContext` supervises native and extension-owned execution. Fo
 |---|---|
 | `execute<T>(execution)` | Returns `{ kind: "result", result, status, error? }` or `{ kind: "background", task, reason }`, where `reason` is `"submitted"` when the caller asked for `background` and `"detached"` when it was moved while the work ran |
 | `list()` / `get(id)` | Bounded, read-only (frozen) retained snapshots; IDs support unique prefixes |
-| `presentOutput(id, width, theme)` | The running task's live Output lines from its executor's `present` (below), or `undefined` for an unknown, settled or presenter-less task, or when the presenter throws. Hosts that render task Output, such as `/tasks`, call it on every repaint and use the default view when it returns nothing |
-| `read(id, options?)` | Bounded head, tail, or byte-offset model-readable output; excludes human-only display text. `options`: `mode`, `bytes`, `sinceBytes`. Without `mode`, a `report` is read from its start and a `log` from its end. With `sinceBytes`, `head` continues forward from that offset and `tail` keeps the newest window at or after it. Returned ranges and `endByte` use raw source bytes. A `wait` or `waitAny` read follows the same default |
-| `wait(id, options?)` | One observation of one task. `options`: `timeoutMs`, `signal`, `toolCallId`, and `read: { bytes?, sinceBytes? }`. Returns `{ outcome, waitedMs, task, read? }` where `outcome` is `settled`, `timed_out`, `interrupted` (host steering), or `closed` (host shut down; state unconfirmed). Timeout, cancellation, or interruption ends the wait, not execution |
-| `waitAny(options?)` | Observes the first task running at call time to settle, with `timeoutMs`, `signal`, `toolCallId`, and `read: { bytes? }`. Returns `{ outcome, waitedMs, task?, read?, running }`; `outcome` adds `no_tasks` for an empty cohort. Later tasks are excluded |
+| `read(id, options?)` | Bounded head, tail, or byte-offset model-readable output; excludes human-only display text. `options`: `mode`, `bytes`, `sinceBytes`. Without `mode`, a `report` is read from its start and a `log` from its end. With `sinceBytes`, `head` continues forward from that offset and `tail` keeps the newest window at or after it. Returned ranges and `endByte` use raw source bytes |
 | `kill(id)` | Requests cancellation; `stopping` is not a terminal status |
 | `detach(id)` / `detachForeground()` | Hands off one task, or eligible foreground tasks oldest first while background slots remain, without restarting them; throws when every background slot is taken. Returns `false` / `0` while the host cannot supervise background work (see below) |
 | `canDetach(id)` | Reports whether an execution can move now, including host policy, the `tasks` tool being active, and available background slots; does not change the execution |
@@ -1275,23 +1284,22 @@ Session-bound `TasksContext` supervises native and extension-owned execution. Fo
 |---|---|
 | `label` | Human source name for the panel and completion card, such as `Bash` or `Agent`; defaults to `kind` |
 | `output` | `"log"` (default) or `"report"`. A log's outcome is at its end, so a background completion gives the model an 8 KiB tail, and `read()` returns its end unless `mode` says otherwise. A report leads with its conclusion, so it arrives from its beginning, whole when it fits the 48 KiB context budget, as its foreground result would, and `read()` returns its start unless `mode` says otherwise; a completed report renders as Markdown in `/tasks` |
-| `input` | `{ label, text, truncated, language? }`: what the task was asked to do, such as a command or briefing. Shown in Details and the expanded completion card, highlighted when `language` is set |
+| `input` | `{ label, text, truncated, language? }`: what the task was asked to do, such as a command or briefing. Shown in `/tasks` Details, highlighted when `language` is set |
 | `facts` | Up to 16 labelled `[label, value]` Details rows, such as `["Directory", cwd]` |
 | `concurrency` | `{ key, limit }`: at most `limit` executions sharing `key` run at once. Lanes belong to one `kind`, so another executor can reuse the key. Later ones wait as `queued` tasks and `run` starts when a slot frees |
 | `background`, `signal`, `onUpdate` | Requested handoff, parent cancellation, and foreground progress forwarding |
-| `present` | `(width, theme)` returning `string[]` or `undefined`: renders the running task's Output in `/tasks` with its own styling, such as colored columns or an elapsed time. Return lines already fitted to `width` (the panel clips any that are wider), or `undefined` for the default view. It runs synchronously on every repaint, so keep it cheap, and it must not return untrusted text without removing terminal sequences. It exists in memory for this execution only: never persisted, not part of any `TaskSnapshot`, dropped at settlement and absent after a restore. A throwing presenter is ignored. `display` stays the plain fallback for other consumers |
 
-`kind` is an executor-owned source label matching `[a-z][a-z0-9-]{0,63}`; the runtime never dispatches on it. Presentation is declared data: the panel and completion card render `label`, `input`, `facts`, and `output` the same way for every executor. Input and facts restore with terminal task history; facts also appear in the completion notification. At most eight background executions, queued ones included, are retained as active at once; foreground executions are not limited by them. Foreground and background results have separate history quotas.
+`kind` is an executor-owned source label matching `[a-z][a-z0-9-]{0,63}`; the runtime never dispatches on it. Presentation is declared data: the panel renders `label`, `input`, `facts`, and `output` the same way for every executor, and the completion notification shows only the label, outcome, title and error. Input and facts restore with terminal task history; facts also appear in the model-facing completion text. At most eight background executions, queued ones included, are retained as active at once; foreground executions are not limited by them. Foreground and background results have separate history quotas.
 
 A caller can be handed off to the background while its task is queued, before `run` starts, or after `run` calls `accept()`. A release requested while `run` is still preparing (a `background: true` submission, or a user detach) waits for `accept()`; if `run` settles first, the caller gets the result inline and the task stays `foreground`. `mode` is therefore `background` exactly when the caller was released with a background outcome. A queued task becomes `running` when its `run` starts; cancelling it settles it as `cancelled` without starting it.
 
-Background work is admitted, submitted or detached, only while the host can supervise it: the session's `tasks` management tool must be active, because the model could otherwise start work it cannot read, wait for or stop. A rejected submission starts nothing and its error says so; work admitted earlier keeps running and delivering if the tool is deactivated later.
+Background work is admitted, submitted or detached, only while the host can supervise it: the session's `tasks` management tool must be active, because the model could otherwise start work it cannot read or stop. A rejected submission starts nothing and its error says so; work admitted earlier keeps running and delivering if the tool is deactivated later.
 
-`run` returns `TaskCompletion<T>`: `{ result, status?, display?, error?, facts?, usage? }`. The original tool result is returned to a foreground caller; task history keeps only its bounded text. Optional `display` is the human-only view that `/tasks` shows in place of the result; `tasks read`, settled waits, and completion context always use `result`. A terminal snapshot carries a display only if this completion supplies one: the last progress display does not survive settlement. Terminal `facts` replace launch facts with the same label, as the shell does with `["Exit", "42"]`. Explicit terminal statuses are `completed`, `partial`, `failed`, `cancelled`, and `timeout`. The host settles usage once, preferring `usage`, then `result.usage`, then the latest published usage; managed foreground results omit usage to avoid billing it twice.
+`run` returns `TaskCompletion<T>`: `{ result, status?, display?, error?, facts?, usage? }`. The original tool result is returned to a foreground caller; task history keeps only its bounded text. Optional `display` is the human-only view that `/tasks` shows in place of the result; `tasks read` and completion context always use `result`. A terminal snapshot carries a display only if this completion supplies one: the last progress display does not survive settlement. Terminal `facts` replace launch facts with the same label, as the shell does with `["Exit", "42"]`. Explicit terminal statuses are `completed`, `partial`, `failed`, `cancelled`, and `timeout`. The host settles usage once, preferring `usage`, then `result.usage`, then the latest published usage; managed foreground results omit usage to avoid billing it twice.
 
 `TaskControl<T>` exposes `id`, `signal`, `mode`, `onModeChange(listener)`, `accept()`, `publish(update)`, `attachOutput(path, cleanup?)`, and `cancel()`. `publish({ result, display?, usage? })` replaces the bounded model-readable result and optionally the live human-only display and cumulative usage; while it runs `/tasks` shows the display in place of the result, while model reads and completion notifications use only the result. A task with an attached output file is read from that file instead. Call `accept()` after whole-invocation preflight, before allowing a background handoff; `onModeChange` listeners run when the mode becomes `background`. Use the control's signal throughout execution. Parent-call cancellation is disconnected after handoff, while runtime shutdown still cancels the task. Mode subscriptions concern only this task; executors do not need the global registry to observe their own handoff or cancel themselves.
 
-Completion messages store `{ version: 3, task }` in `details`, a bounded terminal `TaskSnapshot`; only their bounded `content` enters model context. Built-in `tasks wait` binds delivery to the actual tool call, and the host confirms it after successful persistence; a settled waitAny binds only its winning task. Reads and waits without a `toolCallId`, including `waitAny`, do not acknowledge delivery, and arbitrary tool-result detail fields cannot acknowledge a task. An undelivered completion is a retention lease the session holds on its task: the record and its output stay available until the model has it, and a runtime embedded without a session never holds one, so its settled records are ordinary bounded history.
+Completion messages store `{ version: 3, task }` in `details`, a bounded terminal `TaskSnapshot`; only their bounded `content` enters model context. Reads do not acknowledge delivery, and arbitrary tool-result detail fields cannot acknowledge a task. An undelivered completion is a retention lease the session holds on its task: the record and its output stay available until the model has it, and a runtime embedded without a session never holds one, so its settled records are ordinary bounded history.
 
 ```typescript
 const outcome = await ctx.tasks.execute({
@@ -1313,7 +1321,7 @@ if (outcome.kind === "result") return outcome.result;
 return { content: [{ type: "text", text: `Task ${outcome.task.id} continues in the background.` }], details: undefined };
 ```
 
-When Pi attaches the runtime to its durable session lifecycle, `ctx.tasks.session` exposes `stoppedByTreeNavigation(targetId)`, which lists running tasks that navigating to an entry would cancel. Standalone runtimes omit it. Wait receipts and steering interruption are not extension concerns: the runtime applies them inside `wait()` and `waitAny()`. In a session host, passing the tool call's `toolCallId` keeps a settled background task out of automatic notifications from before the wait until that tool result is persisted, so the persisted result acknowledges it exactly once; without a `toolCallId`, or in a standalone runtime, a wait is purely observational.
+When Pi attaches the runtime to its durable session lifecycle, `ctx.tasks.session` exposes `stoppedByTreeNavigation(targetId)`, which lists running tasks that navigating to an entry would cancel. Standalone runtimes omit it.
 
 `TaskRuntime`, `TaskRuntimeOptions`, and the public `Task*`/`TasksContext`/`TasksSessionContext` types are exported from `@astralyn/pi`. Captured capabilities close with their runtime; obtain the replacement from the new session context after reload or session replacement.
 
@@ -1913,6 +1921,7 @@ The transformer receives the Markdown string and a context with:
 - `messageType` — `"user"`, `"assistant"`, or `"assistant-thinking"`
 - `isStreaming` — `true` for partial assistant updates; `false` for user, finalized assistant, and restored messages
 - `availableWidth` — exact terminal columns available for the transformed Markdown content
+- `messageId`, `timestamp` — session-entry ID and ISO timestamp when rendering from persisted session entries; `undefined` for live messages
 
 Return the transformed Markdown:
 
@@ -1945,6 +1954,8 @@ pi.registerEntryRenderer("status-card", (entry, { expanded }, theme) => {
 pi.appendEntry("status-card", { title: "Indexed files", count: 17 });
 ```
 
+`options.expanded` follows the transcript's expand toggle. `options.outputPad` is the horizontal padding from the `outputPad` setting; inset unboxed content by it to line up with the rest of the transcript.
+
 ### pi.registerShortcut(shortcut, options)
 
 Register a keyboard shortcut. See [keybindings.md](keybindings.md) for the shortcut format and built-in keybindings.
@@ -1977,13 +1988,15 @@ if (profile) {
 
 ### pi.exec(command, args, options?)
 
-Execute a shell command.
+Execute a command without a shell.
 
 ```typescript
 const result = await pi.exec("git", ["status"], { signal, timeout: 5000 });
-// result.stdout, result.stderr, result.code, result.killed
+// result.stdout, result.stderr, result.code, result.killed, result.truncated
 ```
 
+Options: `signal` and `timeout` terminate the command, `cwd` sets the working directory, and `maxBuffer` limits stdout and stderr combined (default 256 MiB). When output exceeds `maxBuffer`, pi terminates the command and returns the output up to the limit with `truncated: true`, `killed: true`, and a nonzero `code`. `killed` is true whenever pi terminated the command: timeout, abort, or `maxBuffer`. A command that ignores SIGTERM gets SIGKILL after 5 seconds.
+
 ### pi.getActiveTools() / pi.getAllTools() / pi.setActiveTools(names)
 
 Manage active tools. This works for both built-in tools and dynamically registered tools. `pi.getActiveTools()` returns the active tool names as `string[]`; `pi.getAllTools()` returns metadata for all configured tools.
@@ -2568,7 +2581,7 @@ By default, tool output is wrapped in the active call/result shell, which owns t
 
 Set `renderShell: "self"` when the tool should render its own shell instead of using the native shell. This is useful for tools that need complete control over framing or background behavior, for example large previews that must stay visually stable after the tool settles.
 
-For live progress UI (elapsed time, retry countdowns), schedule repaints from the renderer itself: store a timer handle in `context.state`, arm a `setTimeout` that calls `context.invalidate()` only while the current view contains changing text, and clear it on the first static or settled render. Set `context.state.dispose` to the same idempotent cleanup function when a timer may still be armed; the shell invokes it when the row is disposed.
+For live progress UI (elapsed time, retry countdowns), schedule repaints from the renderer itself: store a timer handle in `context.state`, arm a `setTimeout` that calls `context.invalidate()` only while the current view contains changing text, and clear it on the first static or settled render. When you arm a timer, register its cleanup with `context.onDispose(cleanup)`: the shell runs it once when the row is disposed, or immediately if the row already was. Register when you create the resource rather than on every render.
 
 Derive displayed time from an absolute timestamp or deadline (`Date.now()`), not by decrementing a counter on every refresh. A refresh is only a repaint opportunity; event-loop stalls and machine sleep must not extend a wall-clock timeout.
 
@@ -2590,13 +2603,15 @@ pi.registerTool({
 
 `renderCall` and `renderResult` each receive a `context` object with:
 - `args` - the current tool call arguments
-- `state` - shared row-local state across `renderCall` and `renderResult`; an optional `dispose()` cleanup is called when the row is disposed
+- `state` - shared row-local state across `renderCall` and `renderResult`
+- `onDispose(cleanup)` - run `cleanup` once when the row is disposed, such as clearing a refresh timer; a cleanup that throws does not affect the row or its siblings
 - `lastComponent` - the previously returned component for that slot, if any
 - `invalidate()` - request a rerender of this tool row
 - `toolCallId`, `cwd`, `executionStarted`, `argsComplete`, `isPartial`, `expanded`, `showImages`, `isError`
 - `durationMs` - how long the tool's execution took, from the final result; `undefined` while it runs, when it did not run, or for results stored before durations were recorded
 - `outputPad` - horizontal padding from the `outputPad` setting; renderers with `renderShell: "self"` apply it themselves
 - `result` - the current partial or final result, if one has arrived
+- `keyText()`, `keyHint()` - format the user's configured keybindings, see [Keybinding Hints](#keybinding-hints)
 
 Use `context.state` for cross-slot shared state. Keep slot-local caches on the returned component instance when you want to reuse and mutate the same component across renders.
 
@@ -2647,24 +2662,24 @@ If a slot intentionally has no visible content, return an empty `Component` such
 
 #### Keybinding Hints
 
-Use `keyHint()` to display keybinding hints that respect the active keybinding configuration:
+Use `keyHint()` and `keyText()` from the render context to display keybinding hints that respect the user's keybinding configuration:
 
 ```typescript
-import { keyHint } from "@astralyn/pi";
-
 renderResult(result, { expanded }, theme, context) {
   let text = theme.fg("success", "✓ Done");
   if (!expanded) {
-    text += ` (${keyHint("app.tools.expand", "to expand")})`;
+    text += ` (${context.keyHint("app.tools.expand", "to expand")})`;
   }
   return new Text(text, 0, 0);
 }
 ```
 
-Available functions:
-- `keyHint(keybinding, description)` - Formats a configured keybinding id such as `"app.tools.expand"` or `"tui.select.confirm"`
-- `keyText(keybinding)` - Returns the raw configured key text for a keybinding id
-- `rawKeyHint(key, description)` - Format a raw key string
+The same functions are available as `options.keyHint()`/`options.keyText()` in message and entry renderers:
+
+- `keyHint(keybinding, description)` - Formats a configured keybinding id such as `"app.tools.expand"` or `"tui.select.confirm"`, followed by the description
+- `keyText(keybinding)` - Returns the raw configured key text for a keybinding id, or `""` if the id has no keys
+
+In renderers, use these instead of importing `keyHint()` or `keyText()` from `@astralyn/pi`. An extension can resolve its own copy of the package, for example from its own `node_modules`, and that copy does not see pi's configured keybindings: `app.*` ids then format as `""`. `rawKeyHint(key, description)` formats a literal key string and is safe to import.
 
 Use namespaced keybinding ids:
 - Coding-agent ids use the `app.*` namespace, for example `app.tools.expand`, `app.editor.external`, `app.session.rename`
@@ -2816,7 +2831,6 @@ Extensions can interact with users via `ctx.ui` methods and customize how messag
 - Status indicators (setStatus)
 - Working message, visibility, and indicator during streaming (`setWorkingMessage`, `setWorkingVisible`, `setWorkingIndicator`)
 - Widgets above/below editor (setWidget)
-- Ephemeral transcript notes (addTranscriptNote)
 - Autocomplete providers layered on top of built-in slash/path completion (addAutocompleteProvider)
 - Custom footers (setFooter)
 
@@ -2989,9 +3003,6 @@ ctx.ui.setWidget("my-widget", ["Line 1", "Line 2"], { placement: "belowEditor" }
 ctx.ui.setWidget("my-widget", (tui, theme) => new Text(theme.fg("accent", "Custom"), 0, 0));
 ctx.ui.setWidget("my-widget", undefined);  // Clear
 
-// Ephemeral note after a session entry; not persisted or sent to the model
-ctx.ui.addTranscriptNote("my-note", "Worked for 8s", { afterEntryId: ctx.sessionManager.getLeafId()! });
-
 // Custom footer (replaces built-in footer entirely)
 ctx.ui.setFooter((_tui, theme, footerData) => ({
   render(_width) {
@@ -3247,6 +3258,8 @@ pi.registerMessageRenderer("my-extension", (message, options, theme) => {
 
   if (expanded && message.details) {
     text += "\n" + theme.fg("dim", JSON.stringify(message.details, null, 2));
+  } else if (message.details) {
+    text += ` (${options.keyHint("app.tools.expand", "to expand")})`;
   }
 
   return new Text(text, outputPad, 0);

package/docs/keybindings.md

@@ -90,7 +90,7 @@ These actions apply when interactive mode uses `--tui-mode fullscreen` and targe
 
 Hold Alt while scrolling the mouse wheel for five-times-faster scrolling. Hovering over autocomplete or settings lists keeps their selection and scroll position unchanged; click an item to select it.
 
-Fullscreen transcript bindings take precedence over editor bindings using the same key. `pageUp` and `pageDown` therefore control the transcript in fullscreen mode while their `ctrl` variants keep controlling the editor; `home` and `end` always control the editor, while `ctrl+home` and `ctrl+end` control the transcript in fullscreen mode. Outside fullscreen mode, all of these keys control the editor.
+Fullscreen transcript bindings take precedence over editor bindings using the same key. `pageUp` and `pageDown` therefore control the transcript in fullscreen mode while their `ctrl` variants keep controlling the editor; `home` and `end` always control the editor, while `ctrl+home` and `ctrl+end` control the transcript in fullscreen mode. Outside fullscreen mode, all of these keys control the editor. While an overlay or a scrollable list such as autocomplete, `/settings`, or the model selector has focus, the scrolling and prompt-jump actions go to it instead of the transcript, so `tui.select.pageUp` and `tui.select.pageDown` move the list selection. Transcript search actions keep working.
 
 | Key | Default mode | Fullscreen mode |
 |-----|--------------|-----------------|

package/docs/llama-cpp.md

@@ -1,31 +1,36 @@
 # llama.cpp
 
-The llama.cpp integration is provided by [upstream Pi](https://github.com/earendil-works/pi) and included in `@astralyn/pi`. It supports the [llama.cpp](https://github.com/ggml-org/llama.cpp) router server, which discovers multiple GGUF models and loads or unloads them on demand.
+The llama.cpp integration is provided by [upstream Pi](https://github.com/earendil-works/pi) and included in `@astralyn/pi`. It supports the [llama.cpp](https://llama.app) router server, which discovers multiple GGUF models and loads or unloads them on demand.
 
-Use a current llama.cpp build with router support. Follow the [build instructions](https://github.com/ggml-org/llama.cpp/blob/master/docs/build.md) or install a [prebuilt release](https://github.com/ggml-org/llama.cpp/releases) for your platform.
+## Install llama.cpp
+
+Install llama.cpp with the [official installer](https://llama.app/docs/installation):
+
+```bash
+curl -LsSf https://llama.app/install.sh | sh
+```
+
+Verify the installation with `llama cli --version`. See [llama.app](https://llama.app) for other installation methods, including package managers and building from source.
 
 ## Start the router
 
-Start `llama-server` without `--model` or `-m`. Passing a model starts single-model mode instead of router mode.
+Start `llama serve` without `--model`, `-m`, or `-hf`. Passing a model starts single-model mode instead of router mode. See the [llama.cpp server guide](https://llama.app/docs/serve#serving-multiple-models-router-mode) for router configuration.
 
 ```bash
-llama-server \
-  --models-dir ~/models \
+llama serve \
   --no-models-autoload \
-  --jinja \
   --host 127.0.0.1 \
   --port 8080 \
-  -ngl 999 \
+  -ngl all \
   -c 32768
 ```
 
 Important options:
 
-- `--models-dir ~/models` discovers local GGUF files.
 - `--no-models-autoload` keeps loading explicit through `/llama`.
 - `--jinja` enables compatible chat templates and tool calling.
-- `-ngl 999` offloads as many layers as possible to the GPU.
-- `-c 32768` sets the context window for each loaded model. Omit it to use the model's native context, which may require substantially more memory.
+- `-ngl all` offloads all layers to the GPU. Omit it to use automatic GPU offloading.
+- `-c 32768` sets the context size in tokens. Use `-c 0` for the model's full context window, which may require substantially more memory. Context is shared across parallel server slots.
 
 A single-file model can sit directly in the model directory. Put multimodal and multi-shard models in separate subdirectories:
 
@@ -41,7 +46,7 @@ A single-file model can sit directly in the model directory. Put multimodal and
     └── large-model-Q4_K_M-00003-of-00003.gguf
 ```
 
-Restart the router after manually adding files. For per-model context sizes and other options, use [llama.cpp model presets](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md#model-presets). For settings tuned to a specific NVIDIA GPU and model, see [Run Pi with NVIDIA RTX and llama.cpp](nvidia-rtx-llama-cpp.md).
+Restart the router after manually adding files. The router also supports cached models and preset files via `--models-preset`, as described in the [server guide](https://llama.app/docs/serve#serving-multiple-models-router-mode). For settings tuned to a specific NVIDIA GPU and model, see [Run Pi with NVIDIA RTX and llama.cpp](nvidia-rtx-llama-cpp.md).
 
 ## Configure Pi
 
@@ -63,7 +68,7 @@ export LLAMA_API_KEY=optional-secret
 pi
 ```
 
-If the server uses an API key, start `llama-server` with the matching `--api-key` value. Keep `--host 127.0.0.1` for local-only access.
+If the server uses an API key, start `llama serve` with the matching `--api-key` value. Keep `--host 127.0.0.1` for local-only access.
 
 ## Manage models
 

package/docs/mcp.md

@@ -126,7 +126,7 @@ Remote servers that use OAuth, such as Sentry, need no credentials in `mcp.json`
 
 When the server rejects an unauthenticated connection, `/mcp` shows that it needs sign-in. Select "Sign in", run `/mcp login sentry`, or run `pi mcp login sentry`. Pi opens the authorization page and waits for approval. If the browser runs on another machine, such as over SSH, paste its redirected URL into the sign-in screen. A running session uses the new credentials on its next turn.
 
-Pi registers itself with the authorization server, stores tokens in `~/.pi/agent/mcp-auth.json`, and refreshes access tokens when they expire or the server rejects them. If a server later requests additional scope, Pi asks for sign-in again. Signing out deletes the stored credentials.
+Pi identifies itself to the authorization server with its Client ID Metadata Document or by registering a client, stores tokens in `~/.pi/agent/mcp-auth.json`, and refreshes access tokens when they expire or the server rejects them. If a server later requests additional scope, Pi asks for sign-in again. Signing out deletes the stored credentials.
 
 Credentials belong to a server name and URL. Servers with the same URL under different names, such as one per account, sign in separately; servers with the same name and URL in different `mcp.json` files share one sign-in.
 
@@ -159,17 +159,19 @@ Pi registers as `pi`. Some servers only accept registrations from known clients.
 
 The name is only sent when Pi registers a client. To register again under a new name, sign out first.
 
-Some authorization servers allow clients by their Client ID Metadata Document URL instead of registering them. Set `clientRegistration` to `cimd` to identify as Pi's document on pi.dev instead of registering:
+Without `clientId`, Pi identifies itself with its Client ID Metadata Document on pi.dev when the authorization server advertises support for documents and public clients. Otherwise it registers a client dynamically. A client registered before stays in use while its redirect URI matches, until you sign out. With the document, the client ID is `https://pi.dev/oauth/client.json` with the redirect URI `http://127.0.0.1:<port>/callback`. If the authorization server does not send the `iss` parameter in authorization responses (RFC 9207), Pi uses a document and redirect path specific to the MCP server instead: `https://pi.dev/oauth/<id>/client.json` with `http://127.0.0.1:<port>/callback/<id>`.
+
+Pi registers instead of using the document when `clientName` is set or `callbackUrl` is not `/callback` on `localhost` or `127.0.0.1`. Set `clientRegistration` to choose the method: `auto` (default) as described, `dcr` to always register, or `cimd` to always use the document. With `cimd`, sign-in fails if the authorization server does not support documents for public clients. Use `dcr` when the authorization page reports an invalid client:
 
 ```json
 {
   "mcpServers": {
-    "example": { "url": "https://mcp.example.com/mcp", "oauth": { "clientRegistration": "cimd" } }
+    "example": { "url": "https://mcp.example.com/mcp", "oauth": { "clientRegistration": "dcr" } }
   }
 }
 ```
 
-The client ID is `https://pi.dev/oauth/client.json` with the redirect URI `http://127.0.0.1:<port>/callback`. If the authorization server does not send the `iss` parameter in authorization responses (RFC 9207), Pi uses a document and redirect path specific to the MCP server instead: `https://pi.dev/oauth/<id>/client.json` with `http://127.0.0.1:<port>/callback/<id>`. The authorization server must advertise Client ID Metadata Document support and public clients, or sign-in fails. `cimd` cannot be combined with `clientId` or `clientName`, and a `callbackUrl` must use `localhost` or `127.0.0.1` with the path `/callback`.
+`pi mcp add --oauth-client-registration <mode>` sets it when adding a server. `cimd` cannot be combined with `clientId` or `clientName`, and a `callbackUrl` must use `localhost` or `127.0.0.1` with the path `/callback`.
 
 Pi finds the authorization server through the server's protected resource metadata (RFC 9728) and checks that the authorization server's metadata names the expected issuer (RFC 8414). Some servers advertise the wrong authorization server or none, so sign-in opens a page that does not exist. Set `authServerMetadataUrl` to the metadata document of the right authorization server:
 

package/docs/models-configuration.md

@@ -88,7 +88,7 @@ Each `modelOverrides` key is the ID of a built-in or extension model. Unknown ID
 
 ## Input limits
 
-See [Describe model input and caching](models.md#describe-model-input-and-caching).
+See [Image Input Limits](models.md#image-input-limits).
 
 | Field | Type | Default | Description |
 |---|---|---|---|

package/docs/models.md

@@ -153,18 +153,7 @@ At provider level, `api` is the default for entries in that provider's `models`
 
 Each key in `providers` is the provider ID used by `/model`, `--provider`, saved credentials, and model references.
 
-| Field | Description |
-| --- | --- |
-| `name` | Optional display name for the provider. Defaults to its ID. |
-| `baseUrl` | Default endpoint for this provider's models. A new provider normally needs this for its first custom model; a model may override it. |
-| `api` | Default [API tag](#api-tags) for entries in `models`. |
-| `apiKey` | Optional fallback API-key value; see [Value Resolution](#value-resolution) and [credential resolution](providers.md#resolution-order). |
-| `oauth` | Dynamic OAuth provider type. `"radius"` is the only supported value and requires a Radius gateway `baseUrl`; see [Providers: Radius](providers.md#radius). |
-| `headers` | Request headers for every model on the provider; see [Custom Headers](#custom-headers). |
-| `authHeader` | Adds `Authorization: Bearer <resolved apiKey>` after resolving authentication. |
-| `compat` | Compatibility defaults merged into the provider's models; see [Compatibility Options](#compatibility-options). |
-| `models` | Custom model definitions. On a built-in provider they are added or replaced by `id`; other catalog models remain. |
-| `modelOverrides` | Partial changes for matching final models, including built-in and extension-registered models; see [Per-model Overrides](#per-model-overrides). |
+See [Provider fields](models-configuration.md#providers) for the complete field reference and defaults. `oauth: "radius"` selects the Radius OAuth flow and requires a gateway `baseUrl`; see [Providers: Radius](providers.md#radius).
 
 A custom model needs an effective `baseUrl` and `api`. For a new provider, put both on the provider (the usual approach) or on its first model. On a built-in provider, a model that replaces an existing ID can fall back to that catalog model's endpoint and API. `contextWindow` and `maxTokens`, when supplied in a `models` entry, must be positive.
 
@@ -236,24 +225,7 @@ Provider headers apply to every request. A configured model header overrides the
 
 A `models` entry supplies a complete custom model definition with useful defaults. A model matching a built-in ID replaces that catalog entry rather than partially modifying it; use [`modelOverrides`](#per-model-overrides) for partial changes.
 
-| Field | Required | Default | Description |
-| --- | --- | --- | --- |
-| `id` | Yes | — | Model identifier sent to the API. |
-| `name` | No | `id` | Human-readable label. It is searchable by `--model` patterns and shown as model detail text. |
-| `api` | No | Provider `api` | [API tag](#api-tags) for this model. |
-| `baseUrl` | No | Provider `baseUrl` | Endpoint override for this model. |
-| `reasoning` | No | `false` | Whether the model supports Pi thinking levels. |
-| `thinkingLevelMap` | No | omitted | Maps Pi thinking levels to provider values and declares unsupported levels; see below. |
-| `input` | No | `["text"]` | Supported input kinds: `text` and `image`. |
-| `inputLimits` | No | omitted | Request limits and image preprocessing for this model; see [Image Input Limits](#image-input-limits). |
-| `contextWindow` | No | `128000` | Context window in tokens. |
-| `maxTokens` | No | `16384` | Maximum generated tokens. |
-| `samplingParamsByThinkingLevel` | No | omitted | Per-level sampling overrides; see [Configure sampling by thinking level](#configure-sampling-by-thinking-level). |
-| `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. |
+See [Model fields](models-configuration.md#models) for the complete field reference, including defaults and nested cost and input-limit shapes.
 
 `/model`, `--list-models`, and the footer show a model's `id`; `name` does not replace it. The model selector and `--model` pattern matching also search `name`.
 
@@ -506,20 +478,7 @@ Set `compat` on a provider for defaults or on a `models`/`modelOverrides` entry
 
 For `api: "anthropic-messages"`, use these options for Anthropic-compatible endpoints:
 
-| Field | Description |
-| --- | --- |
-| `supportsEagerToolInputStreaming` | Accepts per-tool `eager_input_streaming`. Default: `true`. When `false`, Pi omits it and sends the legacy `fine-grained-tool-streaming-2025-05-14` beta header for tool-enabled requests. |
-| `supportsLongCacheRetention` | Accepts `cache_control.ttl: "1h"` for long cache retention. Default: `true`. |
-| `sendSessionAffinityHeaders` | Sends `x-session-affinity` from the session ID when caching is enabled. Default: `false`; built-in model metadata can enable it for providers that need it. |
-| `supportsCacheControlOnTools` | Accepts Anthropic `cache_control` on tool definitions. Default: `true`. |
-| `supportsTemperature` | Accepts non-default `temperature`. Default: `true`; set `false` for endpoints such as Claude Opus 4.7+ that reject it. |
-| `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. |
-| `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. |
+See [Anthropic Messages compatibility fields](models-configuration.md#anthropic-messages) for the complete field reference and defaults.
 
 For example, a proxy that lacks eager streaming but supports long cache retention and adaptive thinking can use:
 
@@ -554,36 +513,9 @@ For example, a proxy that lacks eager streaming but supports long cache retentio
 
 For `api: "openai-completions"`, Pi auto-detects many defaults from the provider ID and base URL. Set an option only when the endpoint differs from that behavior.
 
-| Field | Description |
-| --- | --- |
-| `supportsStore` | Accepts `store: false`. Default: URL-detected. |
-| `supportsDeveloperRole` | Uses `developer` rather than `system` for reasoning models. Default: URL-detected. |
-| `supportsReasoningEffort` | Accepts `reasoning_effort` when the selected thinking format uses it. Default: URL-detected. |
-| `supportsUsageInStreaming` | Accepts `stream_options: { "include_usage": true }`. Default: `true`. |
-| `supportsFinishReason` | Whether streamed responses include `finish_reason`. When `false`, Pi infers `stop` or `toolUse` when the stream ends. Default: `true`. |
-| `maxTokensField` | Selects `max_completion_tokens` or `max_tokens`. Default: URL-detected. |
-| `requiresToolResultName` | Requires `name` on tool-result messages. Default: URL-detected. |
-| `requiresAssistantAfterToolResult` | Requires an assistant message before a user message following tool results. Default: URL-detected. |
-| `requiresThinkingAsText` | Replays thinking blocks as text delimited by `<thinking>`. Default: URL-detected. |
-| `requiresReasoningContentOnAssistantMessages` | Includes empty `reasoning_content` on replayed assistant messages when reasoning is enabled. Default: URL-detected. |
-| `thinkingFormat` | One of `openai`, `openrouter`, `deepseek`, `together`, `zai`, `qwen`, `chat-template`, `qwen-chat-template`, `string-thinking`, or `ant-ling`. Default: `openai` unless URL detection selects a known provider format. |
-| `chatTemplateKwargs` | `chat_template_kwargs` for `thinkingFormat: "chat-template"`. Values may be strings, numbers, booleans, `null`, or `{ "$var": "thinking.enabled" | "thinking.effort" | "thinking.budget", "omitWhenOff"?: true }`. |
-| `chatTemplateArgs` | `chat_template_args` for `thinkingFormat: "baseten"`. Values may be strings, numbers, booleans, `null`, or `{ "$var": "thinking.enabled" | "thinking.effort" | "thinking.budget", "omitWhenOff"?: true }`. |
-| `thinkingTokenBudgetField` | Top-level request field used to cap reasoning tokens from `thinkingBudgets`, clamped so at least 1024 tokens remain for the answer. Use `thinking_token_budget` for vLLM, `thinking_budget` for Qwen/DashScope/SGLang, or `thinking_budget_tokens` for llama.cpp. Off by default. |
-| `supportsThinkingTokenBudget` | Alias for `thinkingTokenBudgetField: "thinking_token_budget"` (vLLM). Prefer `thinkingTokenBudgetField`. Default: `false`. |
-| `zaiToolStream` | Sends top-level `tool_stream: true` when tools are present. Default: `false`; use only for Z.AI-compatible endpoints that require it. |
-| `cacheControlFormat` | `anthropic` applies Anthropic-style `cache_control` markers to the system prompt, last tool definition, and final text content when caching is enabled. |
-| `sendSessionAffinityHeaders` | Sends session-affinity headers from the session ID when caching is enabled. Default: `false`. |
-| `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`. |
-| `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`. |
-
-Thinking formats use these request shapes: `openai` sends `reasoning_effort`; `openrouter` sends `reasoning: { effort }`; `deepseek` sends `thinking: { type }` and, when enabled, `reasoning_effort`; `together` sends `reasoning: { enabled }` and optionally `reasoning_effort`; `zai` sends `thinking: { type }`; `qwen` sends `enable_thinking`; `qwen-chat-template` sends `chat_template_kwargs.enable_thinking` and `preserve_thinking`; `string-thinking` sends top-level `thinking` as a string; and `ant-ling` sends `reasoning: { effort }` only for a non-null mapped effort. `chat-template` sends the configured `chatTemplateKwargs`.
+See [OpenAI Chat Completions compatibility fields](models-configuration.md#openai-completions) for the complete field reference and defaults.
+
+Thinking formats use these request shapes: `openai` sends `reasoning_effort`; `openrouter` sends `reasoning: { effort }`; `deepseek` sends `thinking: { type }` and, when enabled, `reasoning_effort`; `together` sends `reasoning: { enabled }` and optionally `reasoning_effort`; `baseten` sends the configured `chatTemplateArgs` and optionally `reasoning_effort`; `zai` sends `thinking: { type }`; `qwen` sends `enable_thinking`; `qwen-chat-template` sends `chat_template_kwargs.enable_thinking` and `preserve_thinking`; `string-thinking` sends top-level `thinking` as a string; and `ant-ling` sends `reasoning: { effort }` only for a non-null mapped effort. `chat-template` sends the configured `chatTemplateKwargs`.
 
 `thinkingTokenBudgetField` is independent of `thinkingFormat`. Do not enable it on the generated Qwen catalog: those models already send `reasoning_effort`, and DashScope rejects `thinking_budget` together with `reasoning_effort`.
 
@@ -686,17 +618,7 @@ Vercel AI Gateway example:
 
 ### OpenAI Responses
 
-For `api: "openai-responses"`, the compatible fields are `supportsDeveloperRole`, `sessionAffinityFormat`, `supportsLongCacheRetention`, `supportsStrictMode`, `supportsOpenAIGrammarTools`, `supportsToolSearch`, and `supportsExplicitPromptCacheMode`.
-
-| Field | Description |
-| --- | --- |
-| `supportsDeveloperRole` | Uses `developer` rather than `system` for reasoning models. Default: `true`. |
-| `sessionAffinityFormat` | `openai` sends `session_id` and `x-client-request-id`; `openai-nosession` omits `session_id`; `openrouter` sends `x-session-id`. It does not change `prompt_cache_key`. |
-| `supportsLongCacheRetention` | Accepts long cache retention: `prompt_cache_options.ttl: "30m"` when `supportsExplicitPromptCacheMode` is enabled (including GPT-5.6+ Responses models), otherwise `prompt_cache_retention: "24h"`. Default: `true`. |
-| `supportsStrictMode` | Accepts strict JSON-schema function tools. Default: `false`. |
-| `supportsOpenAIGrammarTools` | Emits OpenAI Lark/regex grammar tools. Default: `false`. |
-| `supportsToolSearch` | Supports client-executed deferred tool search. Default: `false`. |
-| `supportsExplicitPromptCacheMode` | Accepts `prompt_cache_options: { mode: "explicit" }` when cache retention is `none`, which disables implicit prompt caching; long cache retention uses `{ ttl: "30m" }` when `supportsLongCacheRetention` is also enabled. Default: `false`. |
+For `api: "openai-responses"`, see [Responses compatibility fields](models-configuration.md#openai-responses) for the complete field reference and defaults.
 
 The public Pi AI model type also exposes the Responses compatibility shape for `azure-openai-responses` and `openai-codex-responses`. The Azure transport uses `supportsDeveloperRole`, `supportsStrictMode`, and `supportsOpenAIGrammarTools`; the Codex transport uses `supportsStrictMode`, `supportsOpenAIGrammarTools`, and `supportsToolSearch`. Other Responses options do not alter those transports.
 

package/docs/packages.md

@@ -9,6 +9,7 @@ Pi packages bundle extensions, skills, prompt templates, and themes so you can s
 - [Install and Manage](#install-and-manage)
 - [Package Sources](#package-sources)
 - [Creating a Pi Package](#creating-a-pi-package)
+- [Show a changelog](#show-a-changelog)
 - [Package Structure](#package-structure)
 - [Dependencies](#dependencies)
 - [Package Filtering](#package-filtering)
@@ -42,13 +43,17 @@ These commands manage pi packages and `pi update` can update the pi CLI installa
 
 By default, `install` and `remove` write to user settings (`~/.pi/agent/settings.json`). Use `-l` to write to project settings (`.pi/settings.json`) instead. Project settings can be shared with your team, and pi installs any missing packages automatically on startup after the project is trusted.
 
-To try a package without installing it, use `--extension` or `-e`. This installs to a temporary directory for the current run only:
+If a configured package fails to install at startup, for example because npm cannot reach the registry, pi warns about it, skips that package's resources, and keeps running. It tries again on the next start or `/reload`. `pi install` and `pi update --extensions` still report the failure and exit non-zero.
+
+To try a package without installing it, use `--extension` or `-e`. It is not added to settings:
 
 ```bash
 pi -e npm:@foo/bar
 pi -e git:github.com/user/repo
 ```
 
+Pi caches `-e` packages under `~/.pi/agent/tmp/extensions/` and checks them on every start and `/reload`. An npm package is reinstalled when the registry has a newer version that matches the specification; an exact version such as `@1.2.3` is not checked. A git package is fetched and reset to the remote branch or ref; a commit hash that is already checked out is not fetched. If the check fails or offline mode is on, pi loads the cached copy.
+
 ## Package Sources
 
 Pi accepts three source types in settings and `pi install`.
@@ -154,6 +159,26 @@ The [package gallery](https://pi.dev/packages) displays packages tagged with `pi
 
 If both are set, video takes precedence.
 
+## Show a changelog
+
+After a package update, pi can show what changed. On the next fresh launch, pi reads the package changelog and shows entries newer than the last seen version under "Extension Updates", the same way it shows its own changelog. The first time pi sees a package, it records the version without showing anything.
+
+This applies to packages that load at least one extension. Packages that only provide skills, prompt templates, or themes do not show a changelog.
+
+By default pi reads `CHANGELOG.md` from the package root. Point `pi.changelogPath` at another file inside the package, or set it to `""` to disable the changelog:
+
+```json
+{
+  "name": "my-package",
+  "version": "1.2.0",
+  "pi": {
+    "changelogPath": "./docs/CHANGELOG.md"
+  }
+}
+```
+
+Use version headings such as `## [1.2.0]` or `## 1.2.0 - 2026-01-01`. Entries are matched against the `version` field in `package.json`, so a git package only shows a changelog when that field increases. The `collapseChangelog` setting condenses the section to one line per package, such as `Updated my-package to v1.2.0.` `/changelog` does not show package changelogs; read the package's changelog file or repository for details.
+
 ## Package Structure
 
 ### Convention Directories

package/docs/rpc.md

@@ -959,7 +959,7 @@ Emitted when nothing more will happen without new input: no run, compaction, ret
 {"type": "session_quiescent"}
 ```
 
-`RpcClient.waitForQuiescence(timeout?)` resolves on this event, or at once when `get_state` reports `isQuiescent`; `collectEventsUntilQuiescent(timeout?)` collects events until it. `waitForIdle()` and `collectEvents()` still resolve on the first `agent_settled`. Closing stdin shuts the process down immediately, without waiting for Background work.
+`RpcClient.waitForQuiescence(timeout?)` resolves on this event, or at once when `get_state` reports `isQuiescent`. `collectEventsUntilQuiescent(timeout?)` collects events until the next one: start it before the prompt it should cover, since it does not resolve early when the session is quiescent before that prompt begins. `waitForIdle()` and `collectEvents()` still resolve on the first `agent_settled`. Closing stdin shuts the process down immediately, without waiting for Background work.
 
 ### turn_start / turn_end