@astralyn/pi 0.87.6 → 1.0.0

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.
+- `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/custom-provider.md

@@ -614,3 +614,47 @@ interface ProviderModelConfig {
 `openrouter` sends `reasoning: { effort }`. `deepseek` sends `thinking: { type: "enabled" | "disabled" }` and `reasoning_effort` when enabled. `together` sends `reasoning: { enabled }` and also `reasoning_effort` when `supportsReasoningEffort` is enabled. `qwen` is for DashScope-style top-level `enable_thinking`. Use `qwen-chat-template` for local Qwen-compatible servers that read `chat_template_kwargs.enable_thinking` and need `preserve_thinking`. Use `chat-template` for configurable `chat_template_kwargs`, for example DeepSeek V3.x behind vLLM with `chatTemplateKwargs: { "thinking": { "$var": "thinking.enabled" } }`. Use `thinkingFormat: "baseten"` with `chatTemplateArgs` when the provider expects toggle values under `chat_template_args` and optionally supports top-level `reasoning_effort`.
 `thinkingTokenBudgetField` sends a clamped per-level thinking budget as a top-level request field (`thinking_token_budget` on vLLM, `thinking_budget` on Qwen/SGLang, `thinking_budget_tokens` on llama.cpp). `supportsThinkingTokenBudget: true` is an alias for the vLLM field name. Do not combine it with `reasoning_effort` on DashScope Qwen models.
 `cacheControlFormat: "anthropic"` applies Anthropic-style `cache_control` markers to the system prompt, last tool definition, and last user, assistant, or tool-result text content.
+
+## Image and classifier operations
+
+Registering only `baseUrl` or `headers` for an existing provider preserves its built-in models. Supplying `models` in the legacy form replaces that provider's models across chat, image, and classifier operations. An omitted `type` means `"chat"`; image and classifier models require explicit discriminants and implementations keyed by their `api` values through the `images` and `classifiers` fields.
+
+For example, a mixed-operation provider can register non-chat models and their implementations together:
+
+```typescript
+pi.registerProvider("media-tools", {
+  apiKey: "$MEDIA_TOOLS_API_KEY",
+  models: [
+    {
+      type: "image",
+      id: "image-v1",
+      name: "Image V1",
+      api: "media-images",
+      baseUrl: "https://media.example.com/v1",
+      input: ["text"],
+      output: ["image"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    },
+    {
+      type: "classifier",
+      id: "classifier-v1",
+      name: "Classifier V1",
+      api: "media-classifier",
+      baseUrl: "https://media.example.com/v1",
+      input: ["text"],
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+      contextWindow: 64000,
+    },
+  ],
+  images: {
+    "media-images": { generateImages: async (model, context, options) => result },
+  },
+  classifiers: {
+    "media-classifier": { classify: async (model, context, options) => result },
+  },
+});
+```
+
+Model-level `baseUrl` values take precedence over the provider endpoint. If no `models` list is supplied, built-in models of every operation remain registered. Equal model IDs in different operations remain distinct, including their model-specific headers.
+
+Await `options.onProviderStreamEvent?.(providerEvent, model)` before normalizing each parsed stream event. Chat models need context and output limits; classifiers need a context window; image models declare output modalities. Legacy `refreshModels` returns a mixed-operation catalog.

package/docs/docs.json

@@ -57,8 +57,8 @@
           "path": "bundled/README.md"
         },
         {
-          "title": "Background",
-          "path": "bundled/extensions/background.md"
+          "title": "Tasks",
+          "path": "bundled/tasks.md"
         },
         {
           "title": "BTW",
@@ -80,14 +80,6 @@
           "title": "Statusline",
           "path": "bundled/extensions/statusline.md"
         },
-        {
-          "title": "Subagent",
-          "path": "bundled/extensions/subagent.md"
-        },
-        {
-          "title": "Todo",
-          "path": "bundled/extensions/todo.md"
-        },
         {
           "title": "Web Search",
           "path": "bundled/extensions/web-search.md"
@@ -132,6 +124,18 @@
         {
           "title": "Custom Providers",
           "path": "custom-provider.md"
+        },
+        {
+          "title": "Codemode",
+          "path": "codemode.md"
+        },
+        {
+          "title": "MCP Servers",
+          "path": "mcp.md"
+        },
+        {
+          "title": "Virtual Models",
+          "path": "virtual-models.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).

package/docs/extensions.md

@@ -1152,104 +1152,48 @@ pi.on("tool_result", async (event, ctx) => {
 });
 ```
 
-### ctx.background
+### ctx.tasks
 
-Session-bound `BackgroundContext` for supervising shell tasks and whole Subagent invocations. The host owns execution lifetime; a tool can either wait for its final result or return a background reference. Check `ctx.background.enabled` before offering background work. Interactive mode enables it; ordinary SDK sessions and built-in print/JSON/RPC hosts leave it disabled. See [SDK host policy](sdk.md#background-execution) and [Background behavior](bundled/extensions/background.md).
+Session-bound `TasksContext` supervises native and extension-owned execution. Foreground work uses the same runtime even when background handoff is disabled. `ctx.tasks.enabled` tells whether this host permits handoff; interactive mode enables it. See [Tasks](bundled/tasks.md) and [SDK host policy](sdk.md#background-execution).
 
-Public types are exported from `@astralyn/pi`: `BackgroundContext`, `BackgroundExecution<T>`, `BackgroundControl<T>`, `BackgroundCompletion<T>`, `BackgroundToolOutcome<T>`, `BackgroundTask`, `BackgroundRead`, `BackgroundProjection`, `BackgroundWorker`, `BackgroundWorkerReport`, `BackgroundText`, `BackgroundCompletionSnapshot`, `BackgroundKind`, `BackgroundMode`, `BackgroundStatus`, and `BackgroundTerminalStatus`.
-
-Use the optional projection in `control.publish(result, projection)` for portable presentation facts. `BackgroundText` is `{ text: string, truncated: boolean }`; record truncation where it happens instead of embedding a marker for the renderer to parse. Shell projections carry `shell: { name, output }`. Worker projections carry `id`, `label`, `profile`, `description`, observed `status`, `report`, optional `error`, plus `prompt`, `activity` and optional `model`/`usage` display strings. The host bounds each field, retaining at most eight workers, 40 KiB of shell output and 4 KiB per report.
-
-Automatic completions persist a terminal `BackgroundCompletionSnapshot` in message `details`, independently of the tool's private result details. Completion workers omit live prompt/activity/model/usage fields, and display metadata is never billed. The host generates bounded model prose from the same facts; renderers read the structured snapshot. Executors without a projection get a bounded plain result fallback. See [Background records](session-format.md#background-records) for the complete format and replay rules.
-
-| Member | Contract |
+| Method | Contract |
 |---|---|
-| `enabled` | Whether this runtime/role permits managed execution |
-| `execute<T>(execution)` | Returns `Promise<BackgroundToolOutcome<T>>`: `{ kind: "result", result }` or `{ kind: "background", task }` |
-| `list()` / `get(id)` | Serializable retained `BackgroundTask` snapshots, not live handles |
-| `read(id, options?)` | Bounded `BackgroundRead` with `task`, `text`, `totalBytes`, `truncated`, optional `fromByte` and `readError`; options: `mode`, `bytes`, `sinceBytes` |
-| `wait(id, timeoutMs?, signal?)` | Bounded observational wait (default 20s, maximum 60s); expiry/abort does not kill execution, and returning a terminal snapshot does not itself acknowledge model delivery |
-| `kill(id)` | Requests cancellation of one task or whole group; returns whether a new request was made |
-| `subscribe(listener)` | Observation only; returns an `off()` function |
-| `pin(id)` | Temporarily defers retained-record eviction; returns an idempotent release function |
-
-`BackgroundExecution<T>` supplies `kind` (`"bash"` or `"subagent"`), `title`, `toolCallId`, optional `command`, `cwd`, `background`, `signal`, `onUpdate`, and `run(control)`. This is supervision, not a generic executor registry: the extension still implements its own domain execution. `run` returns `{ result, status?, error?, usage? }`. Optional `error` is a bounded terminal diagnostic kept independently of log slices; optional `usage` is authoritative cumulative usage. Explicit terminal statuses are `completed`, `partial`, `failed`, `cancelled`, or `timeout`. Status and foreground/background mode are separate dimensions.
-
-Inside `run`, perform whole-invocation preflight, then call **`control.accept()`** before a handoff can return. Start no partial worker batch on failed preflight. Use **`control.signal`**, not the original parent signal, for ongoing work; detach releases the parent wait/cancellation link without restarting execution. `control.publish(result, projection?)` updates observers and forwards foreground progress only while the caller still waits. `control.setOutputPath(path, cleanup?)` registers one exclusively created, executor-owned output file. Never register a shared or pre-existing path. The optional cleanup callback must close its writer before removing only that file; the host invokes it on record eviction or runtime shutdown. A saved path is not a durable attachment. `control.id` and `control.mode` identify the execution and its current wait mode.
-
-Minimal supervised tool (a bounded result, no persistent log):
-
-```typescript
-import type { ExtensionAPI } from "@astralyn/pi";
-import { truncateHead } from "@astralyn/pi";
-import { Type } from "typebox";
-
-export default function (pi: ExtensionAPI) {
-  pi.registerTool({
-    name: "git_status_task",
-    label: "Git status task",
-    description: "Read Git status through the session Background host",
-    parameters: Type.Object({ background: Type.Optional(Type.Boolean()) }),
-    async execute(toolCallId, params, signal, onUpdate, ctx) {
-      if (!ctx.background.enabled) throw new Error("This tool requires an enabled Background host");
-      const outcome = await ctx.background.execute({
-        kind: "bash",
-        title: "Git status",
-        toolCallId,
-        background: params.background,
-        signal,
-        onUpdate,
-        async run(control) {
-          control.signal.throwIfAborted();
-          // All fixed-input preflight is complete; allow handoff.
-          control.accept();
-          const command = await pi.exec("git", ["status", "--short"], {
-            cwd: ctx.cwd,
-            signal: control.signal,
-            timeout: 10_000,
-          });
-          return {
-            status: command.code === 0 ? "completed" : "failed",
-            result: {
-              content: [{ type: "text", text: truncateHead(command.stdout + command.stderr).content }],
-              details: {},
-            },
-          };
-        },
-      });
-      if (outcome.kind === "result") return outcome.result;
-      return {
-        content: [{ type: "text", text: `Accepted: ${outcome.task.id}; use bg to read, wait, or stop.` }],
-        details: { taskId: outcome.task.id },
-      };
-    },
-  });
-}
-```
-
-Return nested LLM `usage` on the completion (`completion.usage` or `completion.result.usage`), not on the submission reference. `completion.usage` takes precedence over result usage, which takes precedence over published partial usage. When publishing partial results, supply cumulative usage accrued by the whole execution, not per-update deltas; the latest published usage is the fallback if execution rejects without a final result. Include retries, failures, cancellation and provider-supplied worker compaction usage, but do not fabricate missing provider usage. The host persists independent usage once and removes it from the managed foreground return, so do not add it back or charge again from a notification/read. Keep results and projections bounded and serializable; never put SDK sessions, processes, abort controllers, functions, or timers into snapshot details. Shell commands should normally use the native Bash/PowerShell tool, which also preserves shell settings, session environment, output limits, and process-tree cleanup.
-
-A read can fall back to the stored bounded result when the log is unreadable or expired. Inspect `readError` separately from `text`, `fromByte` and `totalBytes`: a diagnostic is not log data and must not be hidden by byte-offset paging. Read failure does not turn a completed execution into a failed one.
-
-Subscriptions and pins have a lifetime independent of tool waiting. Release them when the view closes or the extension shuts down; capture only cleanup functions, not an old session context for later use:
-
-```typescript
-let off: (() => void) | undefined;
-pi.on("session_start", (_event, ctx) => {
-  off?.();
-  const background = ctx.background;
-  off = background.subscribe(() => {
-    // Read snapshots or invalidate a visible view; do not inject progress messages.
-    background.list();
-  });
-});
-pi.on("session_shutdown", () => {
-  off?.();
-  off = undefined;
+| `execute<T>(execution)` | Returns `{ kind: "result", result, status?, error? }` or `{ kind: "background", task }` |
+| `list()` / `get(id)` | Bounded, read-only (frozen) retained snapshots; IDs support unique prefixes |
+| `read(id, options?)` | Bounded head, tail, or byte-offset output |
+| `wait(id, timeoutMs?, signal?)` | Observation only; timeout or cancellation ends the wait, not execution |
+| `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 |
+| `subscribe(listener)` | Observes task state and progress |
+| `retain(id)` | Returns an idempotent release function protecting retained data, without delaying notifications |
+| `holdDelivery(id)` | Explicitly retains data and delays automatic delivery until released |
+
+`TaskExecution<T>` supplies `kind`, `title`, `toolCallId`, `run(control)`, optional `command`, `cwd`, `background`, `signal`, and `onUpdate`. `kind` is an executor-owned source label matching `[a-z][a-z0-9-]{0,63}`; the runtime never dispatches on it. At most eight background executions run at once; foreground executions are not limited by them. Foreground and background results have separate history quotas.
+
+`run` returns `TaskCompletion<T>`: `{ result, status?, error?, exitCode?, usage? }`. The original tool result is returned to a foreground caller; private `result.details` is not copied into task history. Explicit terminal statuses are `completed`, `partial`, `failed`, `cancelled`, and `timeout`. Usage is settled by the host once; managed foreground results omit usage to avoid billing it twice.
+
+`TaskControl<T>` exposes `id`, `signal`, `mode`, `accept()`, `publish(result)`, `setOutputPath(path, cleanup?)`, `onModeChange(listener)`, and `requestCancel()`. `publish` replaces the task's bounded text result, which the `/tasks` panel, `tasks read`, and the completion notification show; a task with an output path is read from that log instead. Call `accept()` after whole-invocation preflight, before allowing a background handoff. 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 a self-contained `TaskCompletionSnapshot`; 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. Ordinary extension reads/waits do not acknowledge delivery, and arbitrary tool-result detail fields cannot acknowledge a task.
+
+```typescript
+const outcome = await ctx.tasks.execute({
+  kind: "report-job",
+  title: "Inspect project",
+  toolCallId,
+  signal,
+  background: params.background,
+  async run(control) {
+    control.accept();
+    const report = await inspectProject(control.signal);
+    return { result: { content: [{ type: "text", text: report }], details: undefined } };
+  },
 });
+if (outcome.kind === "result") return outcome.result;
+return { content: [{ type: "text", text: `Task ${outcome.task.id} continues in the background.` }], details: undefined };
 ```
 
-Captured capabilities belong to one runtime. Reload/replacement closes old execution admission and cancels its work; obtain a fresh `ctx.background` on the new `session_start`. A pin does not keep a runtime alive. A worker role cannot enable background execution even if its model supplies `background: true`; built-in workers also receive a no-background prompt rule. This is not an OS sandbox or a daemon, and persisted snapshots do not resume execution.
+`TaskRuntime`, `TaskRuntimeOptions`, and the public `Task*`/`TasksContext` 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.
 
 ### ctx.isIdle() / ctx.abort() / ctx.hasPendingMessages()
 
@@ -2277,7 +2221,7 @@ pi.registerTool(myTool);
 
 **Constrained sampling:** `constrainedSampling: { type: "json_schema", strict: "prefer" }` requests provider-side schema enforcement when the active provider supports it, otherwise normal tool calling is used. Use `strict: "require"` only when the request should fail on unsupported providers. For provider-specific grammars, use `{ type: "grammar", variants: { openai_lark: "...", openai_regex: "..." } }`; each variant is optional, and unsupported providers fall back to normal function tools. `constrainedSampling: false` explicitly opts out (the same behavior as omitting it).
 
-**Usage accounting:** For unmanaged tools, if a tool makes nested LLM calls, return their combined `Usage` as `usage`. Pi persists it on the tool result and includes it in footer, `/session`, and RPC session totals. `tool_result` handlers can inspect or replace this value. Managed executions instead settle usage independently through [`ctx.background`](#ctxbackground); do not duplicate it on the handoff or managed foreground result.
+**Usage accounting:** For unmanaged tools, if a tool makes nested LLM calls, return their combined `Usage` as `usage`. Pi persists it on the tool result and includes it in footer, `/session`, and RPC session totals. `tool_result` handlers can inspect or replace this value. Managed executions instead settle usage independently through [`ctx.tasks`](#ctxtasks); do not duplicate it on the handoff or managed foreground result.
 
 **Signaling errors:** To mark a tool execution as failed (sets `isError: true` on the result and reports it to the LLM), throw an error from `execute`. Returning a value never sets the error flag regardless of what properties you include in the return object.
 
@@ -3254,3 +3198,60 @@ Use `ctx.mode === "tui"` before TUI-specific features (`custom()`, component fac
 ## Examples
 
 The complete, maintained catalog is [examples/extensions/README.md](../examples/extensions/README.md). Use it to find a focused starting point by capability.
+
+## Tool orchestration
+
+Declare `outputSchema` and return a matching `structuredContent` when the result is data. The model still receives `content`; programmatic callers such as codemode scripts receive `structuredContent` instead of the text. Tools without `outputSchema` are passed to scripts as their text content. To report a failure that still carries data, return the result with `isError: true` instead of throwing: the model sees an error, and scripts still receive `structuredContent`.
+
+A tool can run other tools with `ctx.executeTool(name, args, { signal, onUpdate })`. Nested calls go through argument validation and the `tool_call` and `tool_result` handlers like model-issued calls, and emit `tool_execution_start`, `tool_execution_update`, and `tool_execution_end`; all of these events carry `parentToolCallId`, and their `toolCallId` is assigned by pi as `<parent id>/<n>`. These ids do not appear as tool calls or tool results in the transcript. Nested calls do not add transcript entries: their results only reach the calling tool, which reports them itself, for example through `onUpdate` and `details`. The session keeps a bounded record of them (name, arguments, status, duration, error; never results) as `nestedCalls` on the calling tool's result message. It is used for compaction file lists and shown in HTML exports. Arguments over 8 KiB per call or 32 KiB per tool result are omitted, at most 256 calls are kept, and `complete: false` marks a record that lost anything. The `usage` of nested results, at every depth, is added to the calling tool's result `usage`, so a tool reports only its own usage, not that of the tools it called. `ctx.tools` lists the tools `ctx.executeTool()` can call. `tool_result` handlers that redact `content` should also replace `structuredContent`; replacing only `content` drops it.
+
+### Tool exposure
+
+`exposure` controls how the model reaches a tool. "Callable" means callable from other tools through `ctx.executeTool()` (`ctx.tools`), as the `codemode` tool's scripts do:
+
+- `direct` (default): declared to the model while active, and callable while active.
+- `model-only`: declared to the model while active, never callable. Use it for tools that orchestrate other tools or ask the user.
+- `codemode`: callable whenever registered, and listed by the `codemode` tool. Not declared to the model unless activated explicitly.
+- `deferred`: like `codemode`, but codemode tools do not list it; `tool_search` can find and activate it.
+- `hidden`: registered but unreachable. Re-register a tool with `exposure: "hidden"` to withdraw it, since tools cannot be unregistered.
+
+`namespace: { name, description, instructions }` groups related tools, as MCP servers do. Codemode tools list a namespace under one heading with its `description`. `instructions` holds longer usage guidance; it is not listed, and codemode scripts read it with `describeNamespace(name)`.
+
+Registering a `direct` or `model-only` tool activates it; the other exposures are not activated on registration. The active set (`pi.getActiveTools()`, `pi.setActiveTools()`) is the set of tools declared to the model. `pi.getAllTools()` reports each tool's `exposure`, `namespace`, and `annotations`.
+
+`annotations` are hints about what a tool does, with the meaning of MCP tool annotations: `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint`. MCP tools carry the hints their server declares. Missing hints take the MCP defaults: a tool is not read-only, and may be destructive and reach an open world. The hints are not verified, but a permission extension can use them to decide which calls to confirm. This confirms the calls Codex asks approval for:
+
+```typescript
+pi.on("tool_call", async (event, ctx) => {
+  const hints = pi.getAllTools().find((tool) => tool.name === event.toolName)?.annotations;
+  const needsApproval =
+    hints?.destructiveHint === true ||
+    (!hints?.readOnlyHint && ((hints?.destructiveHint ?? true) || (hints?.openWorldHint ?? true)));
+  if (needsApproval && !(await ctx.ui.confirm("Allow tool call?", event.toolName))) {
+    return { block: true, reason: `${event.toolName} was not approved` };
+  }
+});
+```
+
+A tool that orchestrates other tools can adjust what the model sees while it is active with `prepareLoadout(loadout)`. It runs whenever the active tools change and receives the declared tools, the callable tools, and every registered tool with its exposure and namespace. It returns replacement `descriptions` for declared tools (including its own) and `hiddenDeclarations`: active tools whose declarations requests leave out while they stay active and callable. `codemode` uses only this hook, `exposure`, and `ctx.executeTool()`, so another tool can implement the same behavior under a different name.
+
+### MCP servers
+
+`pi.registerMcpServer(name, config)` adds an MCP server for the current session. `config` has the shape of an `mcpServers` entry in [`mcp.json`](mcp.md): `command`, `args`, `env`, and `cwd` for stdio servers, `url`, `headers`, and `oauth` for HTTP servers, plus `exposure`, `toolExposure`, `description`, `enabled`, and `timeout`.
+
+```typescript
+pi.registerMcpServer("jira", { url: "https://mcp.example.com/jira", exposure: "codemode" });
+pi.unregisterMcpServer("jira");
+```
+
+Servers registered while the extension loads connect when the session starts, together with the `mcp.json` servers; servers registered later connect right away, and `pi.unregisterMcpServer()` closes the connection and makes the server's tools unreachable. Registrations are not saved: register again on every load, for example based on the extension's own settings. A server in `mcp.json` with the same name takes precedence, and `/mcp` shows the override. Registering the same name again replaces the extension's earlier registration; names registered by another extension, invalid names, and invalid configs throw.
+
+The built-in MCP support connects registered servers. When nothing does, because another extension replaced it (see [MCP](mcp.md#other-mcp-extensions)), each registration is reported as an extension error. Other MCP extensions can connect registered servers too: read them with `pi.getMcpServers()` on `session_start` and handle the `mcp_servers_change` event for later changes.
+
+### Provider stream events
+
+<a id="provider_stream_event"></a>
+
+`provider_stream_event` fires for each parsed provider stream event before Pi normalizes it. The event identifies the provider, API, and model; `event.data` is the earliest structured value available to Pi, not necessarily the original HTTP bytes or SSE frame. Treat it as read-only because mutation can affect normalization. The event is notification-only and is not persisted.
+
+Handlers are awaited in stream order, so slow handlers delay stream consumption. Handler errors are reported without changing the provider response. See [`debug-provider.ts`](../examples/extensions/debug-provider.ts) for an opt-in viewer that groups raw events by assistant message.

package/docs/index.md

@@ -16,7 +16,8 @@ A task-oriented map for the installed package.
 
 ## Bundled package features
 
-- [Bundled features overview](bundled/README.md) — the complete shipped-feature and extension catalog.
+- [Bundled features overview](bundled/README.md) — upstream Pi features and distribution-maintained additions.
+- [llama.cpp](llama-cpp.md), [Codemode](usage.md#enable-codemode), [MCP](mcp.md), and [Tool search](usage.md#tool-search) — official upstream extensions included in this package.
 
 ## Customize and integrate
 

package/docs/keybindings.md

@@ -128,14 +128,22 @@ This routing remains configurable through the ordinary action bindings. For exam
 | `app.suspend` | `ctrl+z` (none on Windows) | Suspend to background |
 | `app.editor.external` | `ctrl+g` | Open in external editor (`externalEditor`, `$VISUAL`, `$EDITOR`, Notepad on Windows, or `nano` elsewhere) |
 | `app.clipboard.pasteImage` | `ctrl+v` (`alt+v` on Windows and WSL) | Paste image or text from clipboard |
-| `app.backgroundTasks.detach` | `ctrl+b` | Move all eligible current foreground shell tasks and Subagent groups to the background |
-| `app.backgroundTasks.focusList` | `left` | Focus the task list in `/bg` |
-| `app.backgroundTasks.focusPreview` | `right` | Focus the selected preview in `/bg` |
-| `app.backgroundTasks.kill` | `k` | Ask to stop the selected shell task or whole Subagent group in `/bg` (confirmed with `y`) |
-
-In `/bg`, Up/Down and Page Up/Page Down target the focused pane: row selection/list paging or preview scrolling/paging. Enter focuses the preview; Escape returns to the list before closing. Left/Right focus controls can be rebound independently of editor cursor actions. List paging uses `tui.select.pageUp`/`pageDown`; preview paging uses `tui.editor.pageUp`/`pageDown` (including their default Ctrl+Page Up/Down aliases).
-
-Ctrl+B also works while `/bg` owns focus. It does not restart execution, reset shell timeouts, detach individual workers, or affect user `!` commands. With no eligible work it only reports that nothing can be moved. See [Background tasks](bundled/extensions/background.md).
+| `app.tasks.detach` | `ctrl+b` | Move all eligible current foreground managed tasks to the background |
+| `app.tasks.nextFocus` | `tab` | Switch between task list and inspector |
+| `app.tasks.previousFocus` | `shift+tab` | Switch between task inspector and list |
+| `app.tasks.previousTab` | `left` | Show Output while the inspector has focus |
+| `app.tasks.nextTab` | `right` | Show Details while the inspector has focus |
+| `app.tasks.search` | `/` | Locate a retained task; Enter chooses, Escape restores selection |
+| `app.tasks.follow` | `f` | Follow latest or final output while Output has focus |
+| `app.tasks.top` / `app.tasks.bottom` | `home` / `end` | Beginning / end of the focused list or content |
+| `app.tasks.kill` | `k` | Ask to stop the selected ongoing task |
+| `app.tasks.confirmStop` | `enter` | Confirm stopping the task named in the confirmation |
+| `app.tasks.detachSelected` | `b` | Move only the selected foreground task to the background |
+| `app.tasks.help` | `?` | Show task controls |
+
+In `/tasks`, Tab switches between two panes and preserves the inspector's Output/Details tab. Left/Right only change that tab while the inspector has focus. Up/Down and Page Up/Page Down select tasks or scroll the focused content. Escape closes the current search, help or confirmation first, and otherwise closes the panel from either pane. Narrow terminals use the same rules. List paging uses `tui.select.pageUp`/`pageDown`; inspector paging uses `tui.editor.pageUp`/`pageDown` (including their default Ctrl+Page Up/Down aliases).
+
+Ctrl+B also works while `/tasks` owns focus. It does not restart execution, reset shell timeouts, or affect user `!` commands. With no eligible work the key falls through to other bindings. See [Background tasks](bundled/tasks.md).
 
 ### Question Details
 
@@ -254,7 +262,7 @@ Disable the detach action before restoring Ctrl+B as cursor-left (or rebind deta
 {
   "tui.editor.historyPrevious": "ctrl+p",
   "tui.editor.historyNext": "ctrl+n",
-  "app.backgroundTasks.detach": [],
+  "app.tasks.detach": [],
   "tui.editor.cursorLeft": ["left", "ctrl+b"],
   "tui.editor.cursorRight": ["right", "ctrl+f"],
   "tui.editor.cursorWordLeft": ["alt+left", "alt+b"],

package/docs/llama-cpp.md

@@ -1,6 +1,6 @@
 # llama.cpp
 
-Pi supports the [llama.cpp](https://github.com/ggml-org/llama.cpp) router server. The router 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://github.com/ggml-org/llama.cpp) 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.
 
@@ -99,3 +99,14 @@ curl http://127.0.0.1:8080/models
 - **Model missing from `/model`:** Load it with `/llama` first and wait for loading to finish. Idle-sleeping models remain selectable.
 - **Load fails or uses too much memory:** Lower `-c` or unload another model.
 - **Server is not in router mode:** Start it without `--model`, `-m`, or `-hf`.
+
+## Classification
+
+Every model listed for chat is also listed as a classifier model with the same ID and the `llama-cpp-classify` API. Classifier models answer typed `choice`, `bool`, and `score` questions about JSON state, like TypeSafe's Jev models. The model reaches them from [`codemode`](usage.md#enable-codemode) scripts, and extensions through `ctx.modelRegistry.classify()`; see [Classifier models](models.md#use-classifier-models).
+
+The model does not generate an answer. Each question becomes one chat prompt: the state, every question of the request, the state again, and then the question with its answers under single-token labels. Labels are letters for a choice (up to 62 options), `Yes`/`No` for a bool, and digits for a score (up to 10 levels). The second copy of the state is read with the questions in view, which improved accuracy on JevBench with small models. Pi reads the probabilities of the labels as the next token and normalizes them. A choice returns every option's probability and a confidence of `(n * peak - 1) / (n - 1)`; a score returns the expected level.
+
+- Raw label probabilities are usually overconfident. The per-request `temperature` option divides the label logits before normalizing; values above 1 soften the distribution. It changes no answer.
+- Questions run one after another. Everything before the final question is the same for all questions of a request, so the server's prompt cache evaluates it once. The state appears twice, so it needs twice its size in context.
+- Small models may follow instructions written inside the state. The prompt tells the model to judge the state as data, but that is not a guarantee.
+- Hybrid models such as Qwen3.5 cannot rewind a partially cached prompt without context checkpoints. If each question reprocesses the whole state, start the router with `--ctx-checkpoints 32 --checkpoint-min-step 0`.