@astralyn/pi 0.99.0 → 1.0.1

package/dist/utils/image-convert.js

@@ -1,11 +1,7 @@
+import { getCapabilities, setImageTranscoder } from "@earendil-works/pi-tui";
 import { applyExifOrientation } from "./exif-orientation.js";
 import { loadPhoton } from "./photon.js";
-export async function convertImageBytesToPng(bytes) {
-    const photon = await loadPhoton();
-    if (!photon) {
-        // Photon not available, can't convert
-        return null;
-    }
+function encodePng(photon, bytes) {
     try {
         const rawImage = photon.PhotonImage.new_from_byteslice(bytes);
         const image = applyExifOrientation(photon, rawImage, bytes);
@@ -23,6 +19,14 @@ export async function convertImageBytesToPng(bytes) {
         return null;
     }
 }
+export async function convertImageBytesToPng(bytes) {
+    const photon = await loadPhoton();
+    if (!photon) {
+        // Photon not available, can't convert
+        return null;
+    }
+    return encodePng(photon, bytes);
+}
 /**
  * Convert image to PNG format for terminal display.
  * Kitty graphics protocol requires PNG format (f=100).
@@ -42,4 +46,39 @@ export async function convertToPng(base64Data, mimeType) {
         mimeType: "image/png",
     };
 }
+/**
+ * Load photon and return a synchronous PNG transcoder for pi-tui's Kitty image rendering.
+ * Returns undefined if photon cannot be loaded.
+ */
+export async function loadPngTranscoder() {
+    const photon = await loadPhoton();
+    if (!photon)
+        return undefined;
+    return (base64Data) => {
+        const pngBytes = encodePng(photon, new Uint8Array(Buffer.from(base64Data, "base64")));
+        return pngBytes ? Buffer.from(pngBytes).toString("base64") : null;
+    };
+}
+let pngTranscoderLoad;
+let pngTranscoderRegistered = false;
+/**
+ * On Kitty-protocol terminals, register photon as pi-tui's image transcoder so non-PNG images render.
+ * Loads photon once. `onRegistered` runs after registration so callers can re-render images that
+ * showed text fallbacks; it is not called if the transcoder was already registered or cannot load.
+ */
+export function ensurePngTranscoder(onRegistered) {
+    if (pngTranscoderRegistered || getCapabilities().images !== "kitty")
+        return;
+    pngTranscoderLoad ??= loadPngTranscoder().then((transcoder) => {
+        if (!transcoder)
+            return false;
+        setImageTranscoder(transcoder);
+        pngTranscoderRegistered = true;
+        return true;
+    });
+    void pngTranscoderLoad.then((registered) => {
+        if (registered)
+            onRegistered();
+    });
+}
 //# sourceMappingURL=image-convert.js.map

package/dist/utils/image-convert.js.map

@@ -1 +1 @@
-{"version":3,"file":"image-convert.js","sourceRoot":"","sources":["../../src/utils/image-convert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,KAAiB;IAC7D,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAClC,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,sCAAsC;QACtC,OAAO,IAAI,CAAC;IACb,CAAC;IAED,IAAI,CAAC;QACJ,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,oBAAoB,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC5D,IAAI,KAAK,KAAK,QAAQ;YAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;QACxC,IAAI,CAAC;YACJ,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;QAC1C,CAAC;gBAAS,CAAC;YACV,KAAK,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;IACF,CAAC;IAAC,MAAM,CAAC;QACR,oBAAoB;QACpB,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,UAAkB,EAClB,QAAgB;IAEhB,oCAAoC;IACpC,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC9B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,MAAM,sBAAsB,CAAC,KAAK,CAAC,CAAC;IACrD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACb,CAAC;IAED,OAAO;QACN,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAC9C,QAAQ,EAAE,WAAW;KACrB,CAAC;AACH,CAAC","sourcesContent":["import { applyExifOrientation } from \"./exif-orientation.ts\";\nimport { loadPhoton } from \"./photon.ts\";\n\nexport async function convertImageBytesToPng(bytes: Uint8Array): Promise<Uint8Array | null> {\n\tconst photon = await loadPhoton();\n\tif (!photon) {\n\t\t// Photon not available, can't convert\n\t\treturn null;\n\t}\n\n\ttry {\n\t\tconst rawImage = photon.PhotonImage.new_from_byteslice(bytes);\n\t\tconst image = applyExifOrientation(photon, rawImage, bytes);\n\t\tif (image !== rawImage) rawImage.free();\n\t\ttry {\n\t\t\treturn new Uint8Array(image.get_bytes());\n\t\t} finally {\n\t\t\timage.free();\n\t\t}\n\t} catch {\n\t\t// Conversion failed\n\t\treturn null;\n\t}\n}\n\n/**\n * Convert image to PNG format for terminal display.\n * Kitty graphics protocol requires PNG format (f=100).\n */\nexport async function convertToPng(\n\tbase64Data: string,\n\tmimeType: string,\n): Promise<{ data: string; mimeType: string } | null> {\n\t// Already PNG, no conversion needed\n\tif (mimeType === \"image/png\") {\n\t\treturn { data: base64Data, mimeType };\n\t}\n\n\tconst bytes = new Uint8Array(Buffer.from(base64Data, \"base64\"));\n\tconst pngBytes = await convertImageBytesToPng(bytes);\n\tif (!pngBytes) {\n\t\treturn null;\n\t}\n\n\treturn {\n\t\tdata: Buffer.from(pngBytes).toString(\"base64\"),\n\t\tmimeType: \"image/png\",\n\t};\n}\n"]}
+{"version":3,"file":"image-convert.js","sourceRoot":"","sources":["../../src/utils/image-convert.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAwB,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACnG,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAIzC,SAAS,SAAS,CAAC,MAAc,EAAE,KAAiB;IACnD,IAAI,CAAC;QACJ,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC;QAC9D,MAAM,KAAK,GAAG,oBAAoB,CAAC,MAAM,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC5D,IAAI,KAAK,KAAK,QAAQ;YAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;QACxC,IAAI,CAAC;YACJ,OAAO,IAAI,UAAU,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC;QAC1C,CAAC;gBAAS,CAAC;YACV,KAAK,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;IACF,CAAC;IAAC,MAAM,CAAC;QACR,oBAAoB;QACpB,OAAO,IAAI,CAAC;IACb,CAAC;AACF,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,KAAiB;IAC7D,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAClC,IAAI,CAAC,MAAM,EAAE,CAAC;QACb,sCAAsC;QACtC,OAAO,IAAI,CAAC;IACb,CAAC;IACD,OAAO,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;AACjC,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CACjC,UAAkB,EAClB,QAAgB;IAEhB,oCAAoC;IACpC,IAAI,QAAQ,KAAK,WAAW,EAAE,CAAC;QAC9B,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC;IACvC,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC;IAChE,MAAM,QAAQ,GAAG,MAAM,sBAAsB,CAAC,KAAK,CAAC,CAAC;IACrD,IAAI,CAAC,QAAQ,EAAE,CAAC;QACf,OAAO,IAAI,CAAC;IACb,CAAC;IAED,OAAO;QACN,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAC9C,QAAQ,EAAE,WAAW;KACrB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACtC,MAAM,MAAM,GAAG,MAAM,UAAU,EAAE,CAAC;IAClC,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,OAAO,CAAC,UAAU,EAAE,EAAE;QACrB,MAAM,QAAQ,GAAG,SAAS,CAAC,MAAM,EAAE,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;QACtF,OAAO,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACnE,CAAC,CAAC;AACH,CAAC;AAED,IAAI,iBAA+C,CAAC;AACpD,IAAI,uBAAuB,GAAG,KAAK,CAAC;AAEpC;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,YAAwB;IAC3D,IAAI,uBAAuB,IAAI,eAAe,EAAE,CAAC,MAAM,KAAK,OAAO;QAAE,OAAO;IAC5E,iBAAiB,KAAK,iBAAiB,EAAE,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE;QAC7D,IAAI,CAAC,UAAU;YAAE,OAAO,KAAK,CAAC;QAC9B,kBAAkB,CAAC,UAAU,CAAC,CAAC;QAC/B,uBAAuB,GAAG,IAAI,CAAC;QAC/B,OAAO,IAAI,CAAC;IACb,CAAC,CAAC,CAAC;IACH,KAAK,iBAAiB,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE;QAC1C,IAAI,UAAU;YAAE,YAAY,EAAE,CAAC;IAChC,CAAC,CAAC,CAAC;AACJ,CAAC","sourcesContent":["import { getCapabilities, type ImageTranscoder, setImageTranscoder } from \"@earendil-works/pi-tui\";\nimport { applyExifOrientation } from \"./exif-orientation.ts\";\nimport { loadPhoton } from \"./photon.ts\";\n\ntype Photon = NonNullable<Awaited<ReturnType<typeof loadPhoton>>>;\n\nfunction encodePng(photon: Photon, bytes: Uint8Array): Uint8Array | null {\n\ttry {\n\t\tconst rawImage = photon.PhotonImage.new_from_byteslice(bytes);\n\t\tconst image = applyExifOrientation(photon, rawImage, bytes);\n\t\tif (image !== rawImage) rawImage.free();\n\t\ttry {\n\t\t\treturn new Uint8Array(image.get_bytes());\n\t\t} finally {\n\t\t\timage.free();\n\t\t}\n\t} catch {\n\t\t// Conversion failed\n\t\treturn null;\n\t}\n}\n\nexport async function convertImageBytesToPng(bytes: Uint8Array): Promise<Uint8Array | null> {\n\tconst photon = await loadPhoton();\n\tif (!photon) {\n\t\t// Photon not available, can't convert\n\t\treturn null;\n\t}\n\treturn encodePng(photon, bytes);\n}\n\n/**\n * Convert image to PNG format for terminal display.\n * Kitty graphics protocol requires PNG format (f=100).\n */\nexport async function convertToPng(\n\tbase64Data: string,\n\tmimeType: string,\n): Promise<{ data: string; mimeType: string } | null> {\n\t// Already PNG, no conversion needed\n\tif (mimeType === \"image/png\") {\n\t\treturn { data: base64Data, mimeType };\n\t}\n\n\tconst bytes = new Uint8Array(Buffer.from(base64Data, \"base64\"));\n\tconst pngBytes = await convertImageBytesToPng(bytes);\n\tif (!pngBytes) {\n\t\treturn null;\n\t}\n\n\treturn {\n\t\tdata: Buffer.from(pngBytes).toString(\"base64\"),\n\t\tmimeType: \"image/png\",\n\t};\n}\n\n/**\n * Load photon and return a synchronous PNG transcoder for pi-tui's Kitty image rendering.\n * Returns undefined if photon cannot be loaded.\n */\nexport async function loadPngTranscoder(): Promise<ImageTranscoder | undefined> {\n\tconst photon = await loadPhoton();\n\tif (!photon) return undefined;\n\treturn (base64Data) => {\n\t\tconst pngBytes = encodePng(photon, new Uint8Array(Buffer.from(base64Data, \"base64\")));\n\t\treturn pngBytes ? Buffer.from(pngBytes).toString(\"base64\") : null;\n\t};\n}\n\nlet pngTranscoderLoad: Promise<boolean> | undefined;\nlet pngTranscoderRegistered = false;\n\n/**\n * On Kitty-protocol terminals, register photon as pi-tui's image transcoder so non-PNG images render.\n * Loads photon once. `onRegistered` runs after registration so callers can re-render images that\n * showed text fallbacks; it is not called if the transcoder was already registered or cannot load.\n */\nexport function ensurePngTranscoder(onRegistered: () => void): void {\n\tif (pngTranscoderRegistered || getCapabilities().images !== \"kitty\") return;\n\tpngTranscoderLoad ??= loadPngTranscoder().then((transcoder) => {\n\t\tif (!transcoder) return false;\n\t\tsetImageTranscoder(transcoder);\n\t\tpngTranscoderRegistered = true;\n\t\treturn true;\n\t});\n\tvoid pngTranscoderLoad.then((registered) => {\n\t\tif (registered) onRegistered();\n\t});\n}\n"]}

package/docs/bundled/README.md

@@ -24,7 +24,6 @@ The following extensions are additions maintained by `@astralyn/pi`:
 | [Question](extensions/question.md) | `question` | Ask structured questions through native interactive UI |
 | [Provider](extensions/provider.md) | `/provider` | Edit models.json providers: connection, API type, and models |
 | [Statusline](extensions/statusline.md) | Footer status | Show concise extension-managed activity state |
-| [Todo](extensions/todo.md) | `todo`, `/todos` | Track ordered multi-step work in a compact one-line widget |
 | [Web Search](extensions/web-search.md) | `web_search` | Search the live web through MiniMax and DeepSeek with fused results |
 
 All bundled extensions use the public Extension API. Enable or disable them in `pi config` or through `builtin:<name>` entries in [settings](../settings.md#codemode-and-tool-selection). `--no-extensions` disables them; `-e builtin:<name>` loads one explicitly.

package/docs/bundled/extensions/question.md

@@ -34,7 +34,7 @@ Adds a `question` tool for asking one to four multiple-choice questions when the
 }
 ```
 
-Only `content` reaches the model. Successful results are numbered, clearly identify single/custom/multi answers, retain notes, and state when a preview was selected without echoing its full source. Cancelling — via `Esc` or a turn abort — lists any answers already given as partial answers alongside the decline message. Model-facing output is capped at 12,000 characters; if it is truncated, the result instructs the model to ask a focused follow-up question. Notes and custom answers are capped at 4,000 characters in the dialog. Only `outcome: "error"` is mapped to Pi's protocol-level tool error flag; answered, cancelled, and clarification outcomes remain normal results.
+Only `content` reaches the model. Successful results are numbered, clearly identify single/custom/multi answers, retain notes, and state when a preview was selected without echoing its full source. Cancelling — via `Esc` or a turn abort — lists any answers already given as partial answers alongside the decline message. Model-facing output is capped at 12,000 characters. To fit, only user-written text — answers, selections, and notes — is shortened: short texts stay whole, long ones are cut evenly, keeping their start and end around a `…N chars truncated…` marker, and the result asks the model to follow up on the omitted part. Every question, header, and closing instruction is always kept. Notes and custom answers are capped at 4,000 characters in the dialog. Only `outcome: "error"` is mapped to Pi's protocol-level tool error flag; answered, cancelled, and clarification outcomes remain normal results.
 
 The transcript uses a private `renderCall` / `renderResult` only to replace raw question JSON and model-oriented result text with concise user summaries. The collapsed call keeps a bounded header; expanding lists every question in full and marks multi-select prompts. Cancelled and clarification outcomes report `answered N of M`, and the expanded result preserves partial decisions and notes. Human-readable validation errors are shown instead of machine codes, while older or malformed session details fall back defensively to bounded content. Schema-level argument failures show only the first bounded error (plus any remaining count) when collapsed and reveal the bounded validator report with received arguments only when expanded. Pi retains its native tool shell and pending/error state.
 
@@ -44,7 +44,7 @@ Dialog footers use configured keybindings where Pi exposes them, format compact
 
 - Questions, labels, descriptions, and previews have input-length limits so the dialog stays usable.
 - Notes and custom answers are capped at 4,000 characters.
-- Model-facing output is capped at 12,000 characters; if truncated, the result instructs the model to ask a focused follow-up question.
+- Model-facing output is capped at 12,000 characters by shortening long answers and notes evenly; every decision stays in the result.
 - Only available in TUI mode. RPC, JSON, and print calls return a structured `no_ui` error.
 
 ## Implementation notes

package/docs/bundled/extensions/statusline.md

@@ -19,7 +19,7 @@ CTX 2.1%/1.0M                    ↑13k ↓13k R440k CH99.4% $0.074
 - **Model:** human-readable model name, falling back to the model id.
 - **Provider:** the model source in parentheses, such as `(deepseek)` or
   `(opencode-go)`.
-- **Effort:** the latest thinking level when the model supports reasoning and
+- **Effort:** the current runtime thinking level when the model supports reasoning and
   the level is not `off`.
 
 **Right**
@@ -66,19 +66,26 @@ Zero-value usage fields are omitted. Without any accounted usage, the right side
 
 When the terminal is too narrow for the full layout:
 
-**Line 1** (first drop → last):
+**Line 1** uses the first complete pair that fits:
 
-1. Drop the git branch.
-2. Keep the full path alone on the right.
-3. Shorten the path to `~/basename` (or bare basename).
-4. Drop the provider parentheses.
-5. Truncate the remaining left/right text.
+1. Model/provider/effort with the full path and git branch.
+2. Model/provider/effort with the full path alone.
+3. Model/provider/effort with the short path and git branch, then the short path alone.
+4. Model/effort with the short path and git branch, then the short path alone.
+5. Model/effort alone.
+
+The short path is `~/basename` (or bare basename). Shortening the path or dropping
+the provider can make room for the branch again. If none of these pairs fits,
+the model/effort and short path are truncated.
 
 **Line 2** (first drop → last):
 
-1. Drop extension status from the middle gap.
-2. Drop `W`, then `R`, from the usage cluster.
-3. Truncate CTX / remaining usage as a last resort.
+1. Keep the fullest usage cluster that fits beside CTX, trying full usage,
+   then without `W`, then without `W` and `R`.
+2. Include centered extension status only if the selected pair leaves enough room.
+3. If no usage variant fits, omit status and truncate CTX with the full usage cluster.
+
+Status therefore yields to usage; it never causes an extra usage field to be dropped.
 
 ## Layout and colors
 
@@ -106,9 +113,11 @@ may be removed manually.
 
 ## Implementation notes
 
-Footer paint is hot (every TUI render). The extension caches:
-
-- **Branch path** by current leaf id.
-- **Branch stats** (thinking level + cumulative usage) by branch length, leaf entry identity, and a leaf usage fingerprint.
+Footer paint runs on every TUI render. Each footer instance keeps one cache for
+active-branch usage totals and the latest assistant cache-hit percentage, keyed
+by session manager, session id, and leaf id. It clears on footer `invalidate()`.
+Session entries are append-only: finalized messages and usage records advance
+the leaf, so accounting does not need to inspect streaming message mutations.
 
-Both caches clear on footer `invalidate()`.
+Thinking level and context usage come from the live Extension API. Rendering
+receives plain display data and owns no session state or subscriptions.

package/docs/bundled/tasks.md

@@ -10,9 +10,9 @@ Start Bash through the native `bash` tool (the optional native Windows `powershe
 { "command": "npm run build", "timeout": 120, "background": true }
 ```
 
-Omitting `background` keeps the normal foreground wait. A background submission returns an execution reference, not a successful final outcome. `bg create` has been removed; old stored create results and background notifications still render in transcripts.
+Omitting `background` keeps the normal foreground wait. A background submission returns an execution reference, not a successful final outcome. Up to eight background executions run at once; a ninth background submission is rejected without starting. Foreground commands are never limited by background work. `bg create` has been removed; its old stored results and background notifications show their saved text in transcripts.
 
-In interactive mode, **Ctrl+B** moves all eligible foreground managed tasks to the background. Once a foreground execution has run for ten seconds and can still move, the statusline shows `Ctrl+B to background`. It works even when `/tasks` owns focus. The same execution continues: no cancellation, restart or timeout reset. It does not detach ordinary file tools, or user `!` shell commands.
+In interactive mode, **Ctrl+B** moves eligible foreground managed tasks to the background, oldest first, while background slots remain; when every slot is taken it says so instead. Once a foreground execution has run for ten seconds and can still move, the statusline shows `Ctrl+B to background`. It works even when `/tasks` owns focus. The same execution continues: no cancellation, restart or timeout reset. It does not detach ordinary file tools, or user `!` shell commands.
 
 When nothing is eligible, the key is not consumed: it falls through to other bindings instead of reporting a no-op.
 
@@ -37,13 +37,13 @@ Use the execution ID returned by the native tool or `tasks list`. An unknown or
 { "action": "read", "taskId": "<execution-id>", "mode": "tail", "bytes": 8192 }
 ```
 
-Reads default to an 8KB tail. `bytes` clamps between 256 bytes and 50KB at the tool boundary (the core currently limits the actual slice to 48KB); `mode` can be `head` or `tail`. A Bash output path is included when available. Report tasks return their authoritative bounded result.
+Reads default to an 8KB tail. `bytes` clamps between 256 bytes and 48KB; `mode` can be `head` or `tail`. A Bash output path is included when available. Tasks without a log return their bounded published result. Every read and wait reports the byte range it returned and where to continue, for example `bytes 92160–100352 of 100352 · next sinceBytes 100352`.
 
 ```json
 { "action": "wait", "taskId": "<execution-id>", "waitMs": 20000, "sinceBytes": 4096 }
 ```
 
-`waitMs` defaults to 20 seconds and clamps between 1 and 60 seconds. Wait output is limited to 32KB, optionally starting after `sinceBytes`. Expiry or cancellation ends only the wait, not execution. Continue independent work instead of sleep-polling or repeatedly reading; wait when the next step genuinely depends on the result.
+`waitMs` defaults to 20 seconds and clamps between 1 and 60 seconds. Wait output is limited to 32KB, optionally starting after `sinceBytes`. When more than 32KB was written after `sinceBytes`, the wait returns the newest 32KB and reports how many bytes it skipped. Expiry or cancellation ends only the wait, not execution. Continue independent work instead of sleep-polling or repeatedly reading; wait when the next step genuinely depends on the result.
 
 ```json
 { "action": "kill", "taskId": "<execution-id>" }
@@ -55,68 +55,54 @@ All model-facing management responses, including listings and error messages, ar
 
 ## `/tasks` panel
 
-The fullscreen panel lists only **ongoing tasks**, including queued, running and stopping work in both foreground (`fg`) and background (`bg`) modes. Completed tasks leave the list immediately. If the selected task finishes, its final view stays on the right until another task is selected or the panel closes. Opening the panel again does not list finished work; results remain available in the transcript and through `tasks read` / `tasks wait`.
+The fullscreen panel has one scrollable list. **Active** groups queued, running and stopping work; **Finished** groups all retained results on the selected branch, including foreground shell results, newest first. Empty groups are hidden. Task summaries show status and elapsed time; foreground/background mode is available in Details. The background action is offered only when the selected task can move.
 
-At 100 columns or more, the left task list sits beside two independently scrollable regions: **Information** above **Output**. Narrow terminals stack the regions. The panel owns selection, focus, scrolling and cancellation; the execution module owns its information and output components:
+Selection follows the task when it finishes; new work does not steal focus or replace browsed output. The list preserves the selected row's screen position where space permits. Reopening remembers the selected ID and right-hand tab while the runtime remains available. Runtime replacement resets these preferences, and branch navigation removes results outside the visible branch. History remains bounded by the retention limits below.
 
-- Bash and PowerShell show their command, directory, log path and exit code, with live plain-text output.
-- Other extensions can register their own structure. A missing or failing renderer falls back to the saved task information and result text.
+At 100 columns or more, the task list sits beside an inspector. **Output** shows the result directly; **Details** holds the full command, directory, task ID, log location and executor-specific details. Each task and tab keeps its reading position for the lifetime of the panel. Tab switches between the two panes, preserving the right-hand tab. Left/Right switch Output/Details only when the inspector has focus.
+
+The focused pane has a highlighted border. Task selection uses a persistent row background, and the selected right-hand tab uses an underline; neither changes when focus moves. When the system theme has no background colors, the selected row uses inverse text. There are no focus arrows or extra title colors. Narrow terminals show one pane at full width with the same Tab navigation and no focus highlight. The inspector includes task context when the list is hidden. Escape closes the panel from either pane. The minimum supported size is 60 columns by 14 rows.
+
+Bash and PowerShell show live plain-text output. Other executors show their published result, and a task without a command is labeled by its title. Missing logs fall back to the saved result. Task status, failure reasons and output-read errors remain distinct.
 
 | Default key | Action |
 |---|---|
-| Left | Focus the task list |
-| `i` | Focus information |
-| Right / Enter | Focus output |
+| `/` | Locate any retained task by title, command, kind or ID; Up/Down choose a candidate, Enter or clicking locates it and restores the full list, Escape restores the prior selection and focus |
+| Left / Right | Output / Details, only while the inspector has focus |
+| Tab / Shift+Tab | Switch between list and inspector, preserving the current tab |
 | Up / Down | Select a task or scroll the focused region |
 | Page Up / Page Down | Page the focused list or region |
-| `k`, then `y` | Request cancellation of the selected ongoing task; any other key cancels confirmation |
-| Escape | Return to the list, then close |
-| Ctrl+B | Detach eligible foreground executions through the host |
-
-Shell output initially follows the tail. Scrolling up enters **browsing** and keeps a bounded output snapshot while status continues updating. Explicit downward scrolling to the bottom resumes **following**. Scrolling and closing never pause, reattach or cancel execution. Information scrolls independently, so long commands and parameters remain accessible. Task selection and each task's reading positions survive unrelated updates.
-
-The panel polls only selected tail output once per second, up to 48 KiB per read; navigation can request an immediate refresh. A settled selected task gets a final read; browsing defers that read until following resumes. The output range describes the bounded preview, not the entire log. Selecting a task retains its result and log without delaying completion notifications. Closing releases the view, subscriptions, retention lease and timers.
-
-Controls use `app.tasks.focusList`, `app.tasks.focusInfo`, `app.tasks.focusPreview`, `app.tasks.kill` and `app.tasks.detach`. List paging uses `tui.select.pageUp` / `pageDown`; information and output paging use `tui.editor.pageUp` / `pageDown`. All are configurable.
+| Home / End | Top / bottom of the list or bounded preview |
+| `f` | Follow the latest output, or load the final output after completion, while Output has focus |
+| `b` | Move only the selected eligible foreground task to the background |
+| `k`, then Enter | Request cancellation of the selected whole task; Escape cancels confirmation. Confirmation has no time limit and closes if its target finishes |
+| `?` | Show configurable controls; Up/Down scroll the help |
+| Escape | Close the current search, help or confirmation first; otherwise close the panel |
+| Ctrl+B | Detach **all** eligible foreground executions through the host |
 
-## Extension-owned task views
+Click a pane to focus it, a task row to select it, or a tab label to display it. The mouse wheel scrolls the pane under the pointer without changing keyboard focus or task selection. Search, help and confirmation consume their own input without activating the panel behind them.
 
-Register a `TaskViewProvider` in `session_start` with `ctx.tasks.views.register(kind, provider)`. The returned function unregisters it. Registrations belong to the current runtime and are cleared on shutdown or replacement; duplicate registrations for a kind are rejected. Native Bash and PowerShell providers are installed by the interactive host.
+Shell output initially follows the tail, marked **Live** next to the output. Scrolling up enters **Browsing**, which holds a bounded output snapshot while status continues updating. In Output, press `f`, End, or scroll down to the bottom to resume following. If the task finishes while browsing, the panel offers to load its final output. Closing or scrolling never pauses, restarts or cancels execution.
 
-A provider declares `outputMode: "snapshot" | "tail"` and implements `create({ theme, requestRender })`, returning:
-
-- `info` and `output`: TUI components whose content the panel wraps and scrolls.
-- `update(task, output?)`: receives the latest detached task snapshot and, for tail providers, the bounded `TaskRead`.
-- Optional `dispose()`: releases view-owned resources on selection change, provider removal or panel close.
-
-The panel consumes navigation keys and forwards remaining keys to the focused component. Providers can request a repaint without polling or owning the execution. Use semantic theme colors. Keep log source lines unwrapped when possible so the panel can preserve their scroll anchors across resize.
-
-An executor can publish independent, versioned display data:
-
-```typescript
-control.publishView({
-  version: 1,
-  data: { phase: "Scanning", findings: [{ path: "src/main.ts", count: 2 }] },
-});
-```
+The panel polls only selected tail output once per second, up to 48 KiB per read; navigation and settlement can request an immediate refresh. Progress updates and animation do not add log reads. A truncated tail shows its preview and total byte counts; ordinary complete output omits these statistics. Empty output and expired logs have explicit messages; an unavailable log falls back to the saved result when available. Selecting a task retains its result and log without delaying completion notifications. Closing releases subscriptions, the retention lease and timers.
 
-This becomes `task.viewData`. Its version and fields belong to the execution module. Only plain JSON data is accepted, with a 120 KiB storage budget and bounded nesting. Invalid or oversized data is rejected before replacing the previous value; callbacks and accessors cannot enter snapshots. The executor should publish a useful plain tool result as well, which remains readable without its provider.
+Controls use the `app.tasks.*` bindings: `search`, `previousTab`, `nextTab`, `nextFocus`, `previousFocus`, `top`, `bottom`, `follow`, `kill`, `confirmStop`, `detachSelected`, `detach` and `help`. List paging uses `tui.select.pageUp` / `pageDown`; Details and Output paging use `tui.editor.pageUp` / `pageDown`. All are configurable. The former view and direct-focus bindings have been removed.
 
-On settlement, `viewData` is saved in the session JSONL's `task-result` entry. Renderers and live processes are never serialized. The existing completion projection remains separate: changing a panel view does not change tool schemas, model-facing results or notification structure. Built-in views may use the existing saved task fields and projection directly.
+The statusline counts all active managed work and points to `/tasks`. When only retained background results remain, it labels that scope explicitly. The model-facing `tasks list` keeps its background-only scope and foreground omission count.
 
 ## Completion notifications
 
-Interactive `task-completion` messages have a compact collapsed summary: outcome, execution kind, short ID, and a command or group brief. Failures retain a short reason; log paths, output and worker reports stay out of the collapsed view. In fullscreen mode, left-click the notification to expand or collapse that message independently. The blank spacer above it is not a click target. The configured tool-output expansion binding (default Ctrl+O) remains available for toggling output expansion across the transcript.
+Interactive `task-completion` messages have a compact collapsed summary: outcome, execution kind, duration, short ID, and the command or, without one, the task title. Failures retain a short reason; log paths, output and worker reports stay out of the collapsed view. In fullscreen mode, left-click the notification to expand or collapse that message independently. The blank spacer above it is not a click target. The configured tool-output expansion binding (default Ctrl+O) remains available for toggling output expansion across the transcript.
 
-Expanded shell notifications separate **Command**, **Directory**, **Result** or **Error**, a bounded plain-text **Output** tail, **Log** and the full execution ID. Expanded report completions show executor-provided items and Markdown reports; failures keep their reason separate from any partial report. Each saved output/report carries an explicit truncation flag. Screen line limits are independent of source truncation, and every report item retains an allowance. These are previews of the saved bounded completion.
+Expanded notifications separate **Command** (or **Task** for a titled task), **Directory**, **Result** or **Error** with the recorded exit code, a bounded plain-text **Output** tail, **Log** and the full execution ID. The saved output keeps the end of the result, where the outcome is, and carries an explicit truncation flag. Screen line limits are independent of source truncation. These are previews of the saved bounded completion.
 
-Rendering reads the self-contained `TaskCompletionSnapshot` in message `details`, so `/reload`, history eviction, expired logs and restart do not require a live task lookup. The session generates model-facing `content` from the same facts; `details` never enters model context or usage accounting. Commands containing `Output:`, worker reports containing headings or error-wrapper examples, and literal truncation notices remain ordinary data. See the [snapshot contract](../session-format.md#background-records).
+Rendering reads the self-contained `TaskCompletionSnapshot` in message `details`, so `/reload`, history eviction, expired logs and restart do not require a live task lookup. The session generates model-facing `content` from the same facts; `details` never enters model context or usage accounting. Commands containing `Output:` and literal truncation notices remain ordinary data. See the [snapshot contract](../session-format.md#background-records).
 
-Only the current structured completion format is specialized. Older text-only completions and malformed details receive a bounded plain **Details** view; no text reconstruction or migration is performed. Legacy `background-task` notifications keep their existing renderer. HTML export and `/tree` selector labels continue to display the saved message content.
+Only the current structured completion format (version 2) is specialized. Older completions, including version-1 shell and report completions, and malformed details receive a bounded plain **Details** view of their saved message; no text reconstruction or migration is performed. Legacy `background-task` notifications show as plain messages. HTML export and `/tree` selector labels continue to display the saved message content.
 
 ## Lifetime
 
-Background execution belongs to the current session runtime, not a daemon. Parent-turn cancellation still cancels foreground-owned work; after detach it does not cancel background work. Shutdown, `/reload`, `/new`, `/resume`, and `/fork` close admission, stop delivery, cancel work and perform bounded cleanup. `/tree` cancels executions whose launch anchor is absent from the destination branch and suppresses their completion delivery there; navigating back to a branch revives its undelivered completions, and ordinary conversation progress along the same branch does not cancel them. A completion already handed to the prompt queue when its run was aborted is not recalled — the next run delivers it, like any other queued message. Active processes and workers are not reattached across process restart or copied into a fork.
+Background execution belongs to the current session runtime, not a daemon. Parent-turn cancellation still cancels foreground-owned work; after detach it does not cancel background work. Shutdown, `/reload`, `/new`, `/resume`, and `/fork` close admission, stop delivery, cancel work and perform bounded cleanup. `/tree` cancels executions whose launch anchor is absent from the destination branch and suppresses their completion delivery there. Results are saved on their launch branch, so interactive `/tree` first lists those running tasks and asks before stopping them; navigating back to a branch revives its undelivered completions, and ordinary conversation progress along the same branch does not cancel them. A completion already handed to the prompt queue when its run was aborted is not recalled — the next run delivers it, like any other queued message. Active processes and workers are not reattached across process restart or copied into a fork.
 
 The panel is an observer, not a cleanup engine. Admission, bounded history/output retention, completion delivery and headless exit policy are enforced by the core service and hosting mode.
 
@@ -124,9 +110,9 @@ Interactive mode enables Background. Built-in print, JSON, and RPC modes and ord
 
 Managed shell output is collected continuously from startup, including before detach. Background shell output is capped at 20 MiB; crossing the cap fails and stops the command. Foreground output retains its existing uncapped log behavior: detaching a command already over the background budget stops it without deleting the prior bytes. No timeout is supplied by default, and a supplied timeout remains measured from command startup, in seconds, across detach.
 
-Managed logs are ephemeral: they are retained with the runtime record and cleaned up when that record is evicted or the runtime shuts down. Save needed output elsewhere before then. The core defaults to eight active managed executions and two independent terminal histories: 32 reports/background log tasks, plus 32 foreground log records. Report tasks count toward the first history in either mode. Foreground shell traffic can only evict older foreground shell records. Pending delivery, pins, active reads and cleanup use a separate allowance within the bounded total; pins temporarily defer history eviction, not runtime shutdown. These are service limits, not new user settings.
+Managed logs are ephemeral: they are retained with the runtime record and cleaned up when that record is evicted or the runtime shuts down. Save needed output elsewhere before then. The core defaults to eight concurrent background executions and two independent terminal histories: 32 background results plus 32 foreground results. Foreground work of any kind can only evict older foreground records. Pending delivery, pins, active reads and cleanup use a separate allowance within the bounded total; pins temporarily defer history eviction, not runtime shutdown. These are service limits, not new user settings.
 
-Terminal snapshots persist as version-2 `task-result` custom entries, including the presentation projection and optional executor-owned `viewData`; usage remains in independent version-1 `task-usage` entries. The runtime restores version-2 terminal history from the selected branch for programmatic reads, selecting the newest records independently for each history. The panel lists ongoing work only. Older result records are left in the session file and are not migrated or restored. Live execution never resumes after restart, and restoration does not replay accounting or completion events. A saved log path is not a durable attachment. See [session format](../session-format.md#background-records).
+Terminal snapshots persist as version-2 `task-result` custom entries; usage remains in independent version-1 `task-usage` entries. A foreground snapshot omits its output, which the transcript already saves in the tool result, and restoration reads it back from there. The runtime restores version-2 terminal history from the selected branch for programmatic reads and the panel's Finished group, selecting the newest records independently for each history. Older result records are left in the session file and are not migrated or restored. Live execution never resumes after restart, and restoration does not replay accounting or completion events. Restored records drop their log path: logs never outlive the runtime that wrote them. See [session format](../session-format.md#background-records).
 
 Delivered history outside the selected branch can be released and restored on return, so it does not fill the new branch's history budget. Undelivered completions stay protected while their branch is hidden. Pending delivery, pins and active reads use a separate allowance within the total runtime retention cap; restoration respects the same cap.
 
@@ -138,4 +124,4 @@ Queued extension `nextTurn` context accompanies completion turns and stays queue
 
 If an executor ignores cancellation and settles after bounded cleanup has retired its runtime or branch, the old session quarantines its bounded result and reported usage: the latest 32 records remain in memory, and persisted sessions also append `<session-file>.tasks-late.jsonl`. These audit records are excluded from active totals and are not automatically reconciled. A completed cleanup grace period is not proof that an uncooperative executor stopped.
 
-The previous extension-owned interactive-prompt stall watchdog was not ported. Pi no longer automatically flags a prompt-looking shell tail as `waiting for input` or sends stall remediation notifications. Use non-interactive commands and inspect/stop stalled work manually; legacy stall notifications still render from saved transcripts.
+The previous extension-owned interactive-prompt stall watchdog was not ported. Pi no longer automatically flags a prompt-looking shell tail as `waiting for input` or sends stall remediation notifications. Use non-interactive commands and inspect/stop stalled work manually; legacy stall notifications show as plain saved messages.

package/docs/codemode.md

@@ -0,0 +1,207 @@
+# Codemode
+
+The `codemode` tool lets the model write a JavaScript script that calls pi's other tools and runs non-LLM models, such as classifiers and image models. Only the script's output reaches the model, so a script can run calls in parallel and filter large results before the model sees them. To turn it on, see [Enable codemode](usage.md#enable-codemode).
+
+## Scripts
+
+The tool input is raw JavaScript source, not JSON and not a markdown code fence. It runs as the body of an async function in a QuickJS sandbox, so top-level `await` and `return` work. The sandbox has no Node APIs, file system, network, or timers; scripts reach the outside world only through tools and `models`.
+
+A script may start with an options line:
+
+```js
+// @options: {"max_output_tokens": 2000, "timeout_ms": 60000}
+```
+
+- `max_output_tokens` (default 10000) limits the output. Longer output keeps its start and end, and the full text is written to a temp file whose path is included in the result. A script fails when its output passes 16777216 characters of text and base64 image data or 100000 `text()`, `image()`, and `console` calls; write large data to a file with a tool instead.
+- `timeout_ms` is a hard deadline for the whole script. It is unset by default. Image generation can take minutes, so do not set a short deadline for scripts that generate images.
+
+The result starts with `Script completed` or `Script failed`, the wall time, and the output. A failed script keeps its partial output, followed by `Script error:` and the error. Tool calls are real: calls made before a failure are not undone. Calls still running when the script ends are cancelled, and unawaited promises are discarded.
+
+## Globals
+
+| Global | Purpose |
+|---|---|
+| `tools.<name>(args)` | Call a tool. See [Call tools](#call-tools). |
+| `text(value)` | Add a text item to the output. Strings are added as is, other values as JSON. |
+| `image(value)` | Add an image to the output: a base64 `data:` URL, an `{ image_url }` object, or an image block `{ type: "image", data, mimeType }` such as those returned by MCP tools and `models.generateImages()`. Remote URLs are not supported. PNG, JPEG, GIF, and WebP are accepted. |
+| `console.log(...)` | Like `text()`; `info`, `warn`, `error`, and `debug` do the same. |
+| `return value` | A top-level `return` adds the value like `text()`. |
+| `exit()` | End the script successfully. |
+| `store(key, value)` / `load(key)` | Keep small JSON values across `codemode` calls. See [Store values](#store-values). |
+| `ALL_TOOLS` | Every callable tool as `{ name, description }`, including tools the description does not list. |
+| `searchTools(query, { limit?, namespace? })` | Rank callable tools by relevance (BM25, default limit 8). Resolves to `{ name, description }[]`. |
+| `describeTool(name)` | Resolves to a tool's description and TypeScript declaration, or `undefined`. |
+| `describeNamespace(name)` | Resolves to `{ name, description?, instructions?, tools }` for a namespace such as an MCP server, or `undefined`. |
+| `models` | List and run non-LLM models. See [Models](#models). |
+
+## Call tools
+
+Every tool the session can call is a method of `tools`, named by its identifier: characters that are not valid in a JavaScript identifier become `_`, so the MCP tool `mcp__dev-radius__search` is `tools.mcp__dev_radius__search`. Each method takes one object with the tool's arguments.
+
+What a call resolves to depends on the tool:
+
+- Tools with an output schema resolve to a structured value. `bash` resolves to `{ output, truncated, full_output_path?, exit_code, wall_time_seconds }`, also for non-zero exit codes. Its `output` is not limited to the 2000 lines or 50KB the model sees: it holds up to 1 MiB, and longer output keeps its first and last 512 KiB around an omission marker, with `truncated` set and the full output in `full_output_path`. A command moved to the background resolves to `{ task_id, status }` instead; see [Tasks](bundled/tasks.md).
+- MCP tools resolve to their `CallToolResult`, including `isError` and `structuredContent`.
+- Other tools, such as `read`, `edit`, and `write`, resolve to their text output.
+
+A call that fails, is blocked, or gets invalid arguments rejects with an `Error` that carries the tool's error text. Use `Promise.allSettled()` to keep the results of the calls that succeed.
+
+The `codemode` description lists tools with their TypeScript declarations, grouped by namespace (for example one MCP server). Tools with `deferred` exposure, which includes MCP tools with the default `codemode` exposure, are not listed, so the description stays the same while MCP servers connect. Listed declarations share a budget of 3000 estimated tokens (`codemode.inlineBudget` in [settings](settings.md#tools)). Scripts find the other tools with `searchTools()`, `describeTool()`, `describeNamespace()`, or by filtering `ALL_TOOLS`.
+
+While `codemode` is active, `codemode.mode` in [settings](settings.md#tools) decides how the other tools are presented. With `on` (default) declared tools stay declared, and their descriptions say how to call them from scripts. With `only` they are hidden from the model and listed in the `codemode` description instead, so the model calls them through scripts.
+
+## Store values
+
+`store(key, value)` keeps a JSON value under a string key for later `codemode` calls; storing `undefined` deletes the key. `load(key)` returns the value, or `undefined`. Writes are kept only when the script succeeds: each successful script that stores values appends a `codemode-store` custom entry to the session, so resumed sessions keep the values and each branch sees only the values written on its path.
+
+The store is for small state such as IDs, cursors, or summaries. One value may have at most 262144 characters of JSON and all values together at most 1048576. Do not store image data; show images with `image()` or write them to a file with a tool.
+
+## Models
+
+`models` reaches the model catalog and runs non-LLM models with the session's credentials: classifiers, which answer typed questions about JSON state, and image models, which generate images. Chat models are listed but cannot be run from scripts. Which classifier and image models exist is described in [Use classifier models](models.md#use-classifier-models) and [Use image models](models.md#use-image-models).
+
+```ts
+type ModelType = "chat" | "image" | "classifier";
+
+/** A catalog entry. `provider` and `id` identify it; other fields depend on the type. */
+interface ModelInfo {
+  type?: ModelType;
+  provider: string;
+  id: string;
+  name: string;
+  api: string;
+  input: ("text" | "image")[];
+  contextWindow?: number;
+  [key: string]: unknown;
+}
+
+declare const models: {
+  /** Every known model of a type, optionally for one provider. */
+  getModelsOfType(type: ModelType, provider?: string): Promise<ModelInfo[]>;
+  /** Models of a type whose provider has working credentials. */
+  getAvailableOfType(type: ModelType, provider?: string): Promise<ModelInfo[]>;
+  /** One catalog entry, or undefined. */
+  getModelOfType(type: ModelType, provider: string, id: string): Promise<ModelInfo | undefined>;
+  /** Answer `context.questions` about `context.state`; answers are in `result.answers` by question ID. */
+  classify(model: ModelInfo, context: ClassifierContext): Promise<ClassifierResult>;
+  /** Generate images from `context.input` text and image blocks; show `result.output` blocks with image(). Can take minutes. */
+  generateImages(model: ModelInfo, context: ImagesContext): Promise<ImagesResult>;
+};
+```
+
+`classify()` and `generateImages()` use only the `provider` and `id` of `model`, so `{ provider, id }` works as well. They do not throw on provider errors: check `stopReason` and `errorMessage`. At most four such calls run at once per script; more calls wait for a free slot, so `Promise.all()` over many items is fine. Their usage is added to the `codemode` tool result and counts toward the session cost.
+
+Model IDs differ between providers, for example `typesafe/jev-latest` and `openrouter/typesafe/jev-1.13`. Use `models.getAvailableOfType(type)` to find the IDs that work with the current credentials.
+
+### Classify
+
+```ts
+interface ClassifierContext {
+  /** The data to classify. */
+  state: Record<string, unknown>;
+  /** Questions by ID. One call answers all of them. */
+  questions: Record<string, ClassifierQuestion>;
+}
+
+type ClassifierQuestion =
+  /** Pick one label. `criteria` maps each label to what it means. */
+  | { type: "choice"; instructions: string; criteria: Record<string, string> }
+  /** Score on an ordered scale. `criteria` describes each level, lowest first. */
+  | { type: "score"; instructions: string; criteria: string[] }
+  /** Yes or no. */
+  | { type: "bool"; instructions: string; criteria: { true: string; false: string } };
+
+interface ClassifierResult {
+  provider: string;
+  model: string;
+  /** Answers by question ID. */
+  answers: Record<string, ClassifierAnswer>;
+  usage?: ModelUsage;
+  stopReason: "stop" | "error" | "aborted";
+  errorMessage?: string;
+}
+
+type ClassifierAnswer =
+  | { type: "choice"; choice: string; probabilities: Record<string, number>; confidence: number }
+  /** `score` is the expected level index, from 0 to `criteria.length - 1`. */
+  | { type: "score"; score: number; confidence: number }
+  /** Probability of `true`. */
+  | { type: "bool"; probability: number };
+
+/** Token counts and cost in USD, when the service reports them. */
+type ModelUsage = { input: number; output: number; totalTokens: number; cost: { total: number } };
+```
+
+Classify several items by calling `classify()` once per item. This script sorts feedback messages, for example ones a tool returned earlier in the script:
+
+```js
+const jev = await models.getModelOfType("classifier", "typesafe", "jev-latest");
+const results = await Promise.all(
+  messages.map((message) =>
+    models.classify(jev, {
+      state: { message },
+      questions: {
+        sentiment: {
+          type: "choice",
+          instructions: "How does the user feel about the product?",
+          criteria: { positive: "Satisfied or happy", negative: "Unhappy or frustrated", neutral: "Neither" },
+        },
+        urgency: {
+          type: "score",
+          instructions: "How urgently does this need a reply?",
+          criteria: ["no reply needed", "reply this week", "reply today"],
+        },
+      },
+    }),
+  ),
+);
+return results.map((result, i) =>
+  result.stopReason === "stop"
+    ? { message: messages[i], sentiment: result.answers.sentiment.choice, urgency: result.answers.urgency.score }
+    : { message: messages[i], error: result.errorMessage },
+);
+```
+
+### Generate images
+
+```ts
+interface ImagesContext {
+  /** The prompt as text blocks, plus image blocks to edit or use as references. */
+  input: (TextBlock | ImageBlock)[];
+}
+
+interface ImagesResult {
+  provider: string;
+  model: string;
+  /** Generated images, and text blocks for models that also return text. */
+  output: (TextBlock | ImageBlock)[];
+  usage?: ModelUsage;
+  stopReason: "stop" | "error" | "aborted";
+  errorMessage?: string;
+}
+
+type TextBlock = { type: "text"; text: string };
+/** `data` is base64. */
+type ImageBlock = { type: "image"; data: string; mimeType: string };
+```
+
+Show generated images with `image(block)`. Do not print `data` with `text()`, `console`, or `return`: it is large and the model cannot read it as text. Generated images are not saved to disk; to keep one, write it to a file with a tool.
+
+```js
+// @options: {"timeout_ms": 300000}
+const painter = await models.getModelOfType("image", "openrouter", "google/gemini-2.5-flash-image");
+const result = await models.generateImages(painter, {
+  input: [{ type: "text", text: "A red fox in the snow, watercolor" }],
+});
+if (result.stopReason !== "stop") return result.errorMessage;
+for (const block of result.output) {
+  if (block.type === "image") image(block);
+  else text(block.text);
+}
+```
+
+## Limits
+
+- A script's VM has 256 MB of memory. Running out throws `InternalError: out of memory`; filter or aggregate large data instead of accumulating it.
+- A script that waits on a promise that can never settle (no tool call pending) fails immediately, since there are no timers.
+- Scripts cannot start other `codemode` scripts.

package/docs/docs.json

@@ -80,10 +80,6 @@
           "title": "Statusline",
           "path": "bundled/extensions/statusline.md"
         },
-        {
-          "title": "Todo",
-          "path": "bundled/extensions/todo.md"
-        },
         {
           "title": "Web Search",
           "path": "bundled/extensions/web-search.md"
@@ -129,6 +125,10 @@
           "title": "Custom Providers",
           "path": "custom-provider.md"
         },
+        {
+          "title": "Codemode",
+          "path": "codemode.md"
+        },
         {
           "title": "MCP Servers",
           "path": "mcp.md"

package/docs/environment-variables.md

@@ -95,6 +95,6 @@ These variables are read by Pi itself:
 | `VISUAL`, `EDITOR` | Fallback external editor for Ctrl+G when `externalEditor` is unset; defaults to Notepad on Windows and `nano` elsewhere |
 | `HTTP_PROXY`, `HTTPS_PROXY` | Proxy outbound HTTP requests |
 
-Provider credentials such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and cloud-provider configuration are listed in [Providers](providers.md#environment-variables-or-auth-file).
+Provider credentials such as `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, and provider-specific configuration are listed in [Providers](providers.md#environment-variables-or-auth-file).
 
 `PI_SERVER_DIR` and `PI_SERVER_ID` apply only to the source-only [experimental remote harness](development.md#experimental-remote-harness).