@astralyn/pi 0.87.6 → 0.99.0

package/docs/extensions.md

@@ -1152,104 +1152,50 @@ 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.
+| `execute<T>(execution)` | Returns `{ kind: "result", result, status?, error? }` or `{ kind: "background", task }` |
+| `list()` / `get(id)` | Bounded 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 all eligible foreground tasks without restarting them |
+| `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 |
 
-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.
+`TaskExecution<T>` supplies `kind`, `title`, `toolCallId`, `run(control)`, optional `format`, `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. `format` is `"report"` (default) or `"log"`. Foreground log records have a separate history quota and are hidden from the finished panel unless selected.
 
-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 },
-      };
-    },
-  });
-}
-```
+`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.
 
-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.
+`TaskControl<T>` exposes `id`, `signal`, `mode`, `accept()`, `publish(result, projection?)`, `setOutputPath(path, cleanup?)`, `onModeChange(listener)`, and `requestCancel()`. 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.
 
-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.
+`TaskProjection` contains optional bounded `text`, executor-provided `nextStep` guidance, `shell: { name, output }`, and generic report `items`. Each item has `id`, `label`, `category`, `description`, `status`, `report`, optional `error`, live `input`/`activity`, and optional `context`/`usage` display strings. `TaskText` is `{ text, truncated }`. Report groups retain at most eight items, with 4 KiB per report; log output retains at most 40 KiB in the projection. Extensions may translate their reports into these public items; the core does not import executor internals.
 
-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:
+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
-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;
+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 +2223,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 +3200,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 }` groups related tools, as MCP servers do. Codemode tools list a namespace under one heading.
+
+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` and `tool_search` use 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`, `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,15 @@ 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`) |
+| `app.tasks.detach` | `ctrl+b` | Move all eligible current foreground managed tasks to the background |
+| `app.tasks.focusList` | `left` | Focus the task list in `/tasks` |
+| `app.tasks.focusPreview` | `right` | Focus the selected preview in `/tasks` |
+| `app.tasks.focusInfo` | `i` | Focus the selected task's information in `/tasks` |
+| `app.tasks.kill` | `k` | Ask to stop the selected ongoing task in `/tasks` (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).
+In `/tasks`, 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).
+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 +255,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`.

package/docs/mcp.md

@@ -0,0 +1,188 @@
+# MCP Servers
+
+The MCP integration is provided by [upstream Pi](https://github.com/earendil-works/pi) and included in `@astralyn/pi`. It connects to [Model Context Protocol](https://modelcontextprotocol.io) servers over stdio or streamable HTTP and makes their tools available to the model.
+
+## Configure servers
+
+Add servers to `~/.pi/agent/mcp.json`, or to `.pi/mcp.json` in a project. The format matches other MCP clients, so existing `mcpServers` entries can be copied over:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
+    },
+    "docs": {
+      "url": "https://example.com/mcp",
+      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" },
+      "exposure": "direct"
+    }
+  }
+}
+```
+
+- stdio servers take `command`, `args`, `env`, and `cwd`. Relative `cwd` resolves against the session directory. A leading `~/` in `command`, an argument, or `cwd` names the home directory.
+- HTTP servers take `url`, `headers`, and `oauth` (see [Sign in with OAuth](#sign-in-with-oauth)). The legacy SSE transport is not supported.
+- `env` and `headers` values can reference environment variables (`${NAME}`) or commands (`!command`), like provider API keys.
+- `timeout` sets the per-request timeout in seconds (default 60). Progress notifications from the server reset it.
+- `enabled: false` keeps an entry without connecting to it.
+
+Project entries replace global entries with the same name. A project `mcp.json` is only read after the project is trusted, because stdio servers run commands.
+
+`pi mcp add` and `pi mcp remove` edit the file from a shell (see [MCP commands](usage.md#mcp-commands)):
+
+```bash
+pi mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
+pi mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKEN --exposure direct
+pi mcp add -l tools --env API_KEY='${TOOLS_KEY}' -- uvx tools-mcp
+pi mcp remove docs
+```
+
+Rules that are easy to get wrong:
+
+- Server names may only contain letters, digits, `_`, and `-`. Tools are named `mcp__<server>__<tool>`.
+- `type` is optional: a `command` makes a stdio server and a `url` a streamable HTTP server. When present, it must be `stdio`, `http`, or `streamable-http`. `sse` is rejected; most servers that document an SSE endpoint also serve streamable HTTP, often at `/mcp` instead of `/sse`.
+- `command` is a single executable and `args` its arguments, not one shell string.
+- Keep secrets out of the file: use `${NAME}` for environment variables, as in `"Authorization": "Bearer ${GITHUB_TOKEN}"`, or `!command` to run a command. A command must make up the whole value, so it has to print the header value itself: `"Authorization": "!echo Bearer $(gh auth token)"`.
+- Invalid entries are skipped and reported; the other servers still connect.
+
+## Set up servers
+
+When asked to add an MCP server, the agent should:
+
+1. Add simple servers with `pi mcp add` (add `-l` for the project file), or edit `mcp.json` directly for settings the command does not cover. Put personal servers and servers with credentials in `~/.pi/agent/mcp.json`. Use the project `.pi/mcp.json` only for servers the project itself needs, and only in trusted projects.
+2. Convert entries written for other clients:
+   - Claude Desktop, Claude Code, and Cursor use the same `mcpServers` shape; copy the entry.
+   - VS Code uses a top-level `servers` object and `inputs` prompts; move the entry under `mcpServers` and replace `${input:...}` with `${NAME}` environment variables.
+   - Codex uses TOML (`[mcp_servers.<name>]` with `command`, `args`, `env`, or `url`); write the same fields as JSON.
+   - opencode uses `"type": "local"` with `command` as an array (split it into `command` and `args`), `"type": "remote"` for URLs, `environment` for `env`, and `{env:NAME}` for `${NAME}`.
+3. Run `pi mcp list` to check the entry. It connects to every enabled server and prints the state, the tools, and errors such as the stderr of a stdio server that failed to start. It exits with 1 while anything is wrong.
+4. For a server that needs a sign-in, run `pi mcp login <server>`. It opens the authorization page in the user's browser and waits until the user approves access; tell the user to approve it. A running session uses the new credentials on its next turn.
+5. Tell the user to run `/reload` (or start a new session) so the running session connects to added or changed servers.
+
+Pi connects when a session starts. The first prompt waits up to 10 seconds for startup connections; the tools of servers that take longer become available once they connect. HTTP connections that fail with a network error or a transient status (408, 429, 5xx) are retried twice. A server that drops its connection shows as disconnected and is reconnected on the next call. When a server announces that its tool list changed, new tools are added and withdrawn tools become unreachable until the server offers them again.
+
+Config errors, servers that failed to connect, and servers that need a sign-in are reported once after startup.
+
+Log messages servers send with MCP logging notifications are appended to `~/.pi/agent/mcp.log` as `<time> [<server>] <level> <logger>: <message>`. The file is moved to `mcp.log.1` when it grows past 5 MB.
+
+## Manage servers
+
+`/mcp` opens the server manager. It lists every configured server with its state, tool count, exposure, and whether it comes from the global or the project `mcp.json`; servers that need attention come first. Select a server to:
+
+- sign in, for OAuth servers that need it (see [Sign in with OAuth](#sign-in-with-oauth))
+- see its tools, its command or URL, and the full connection error, including the tail of a stdio server's stderr
+- reconnect
+- sign out, which deletes the stored OAuth credentials
+- change its exposure (see [Exposure](#exposure))
+- disable or enable it
+
+Exposure changes and enabling or disabling are saved to the `mcp.json` that defines the server; other content of the file is kept. Disabled servers stay listed so they can be enabled again.
+
+Outside the interactive TUI, `/mcp` prints the server status. `/mcp login <server>`, `/mcp logout <server>`, and `/mcp reconnect <server>` run those actions directly.
+
+From a shell, `pi mcp add`, `pi mcp remove`, `pi mcp list`, `pi mcp login <server>`, and `pi mcp logout <server>` manage servers without a session (see [MCP commands](usage.md#mcp-commands)).
+
+Stopping a stdio server closes its stdin, then sends SIGTERM and finally SIGKILL to its whole process group, so servers started through wrappers such as `npx` or `uvx` do not linger.
+
+## Sign in with OAuth
+
+Remote servers that use OAuth, such as Sentry, need no credentials in `mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "sentry": { "url": "https://mcp.sentry.dev/mcp" }
+  }
+}
+```
+
+When such a server rejects the connection, `/mcp` shows it as needing sign-in. Select it and choose "Sign in" (or run `/mcp login sentry`, or `pi mcp login sentry` in a shell) to open the authorization page in your browser. After you approve access, the browser redirects to a temporary server on `127.0.0.1` and pi connects. If the browser runs on another machine, for example over SSH, paste the URL it was redirected to into the sign-in screen instead.
+
+Pi registers itself with the authorization server (dynamic client registration), stores tokens in `~/.pi/agent/mcp-auth.json`, and refreshes access tokens automatically when they expire or the server rejects them. If the server later asks for more scope than was granted, it shows as needing sign-in again, and signing in requests the new scope. "Sign out" in `/mcp` (or `/mcp logout sentry`) deletes the stored credentials.
+
+OAuth applies to HTTP servers without an `Authorization` header. For authorization servers that do not support dynamic client registration, configure a pre-registered client:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "oauth": { "clientId": "my-client", "clientSecret": "${EXAMPLE_SECRET}", "callbackPort": 8765 }
+    }
+  }
+}
+```
+
+The redirect URI must match the one registered for the client. `callbackPort` fixes it to `http://127.0.0.1:<port>/callback`. For another redirect URI, set `callbackUrl`, for example `"callbackUrl": "http://localhost:8080/oauth/callback"`. It must be an `http` URI on `localhost`, `127.0.0.1`, or `[::1]`, and is sent exactly as written. Without a port in `callbackUrl`, pi listens on `callbackPort`, or on a free port, and adds it to the URI; authorization servers accept any port for loopback redirects (RFC 8252). `clientSecret` is optional and can reference environment variables or commands.
+
+`scope` sets the scopes to request, separated by spaces, for servers that do not advertise the ones they need. Without it, pi requests the scopes the server advertises. When a server later asks for more scope, pi requests those on top of `scope`.
+
+## Exposure
+
+Each server's tools are registered as `mcp__<server>__<tool>`. The `exposure` setting controls how the model reaches them:
+
+- `codemode` (default): the tools are callable from [`codemode`](usage.md#tools) scripts and listed in the `codemode` tool's description, but are not declared to the model. Large MCP tool lists stay out of the model's tool declarations, and scripts can call several MCP tools, in parallel if needed, while returning only the part of the result the model needs. Pi activates the `codemode` tool when such a server connects. Large servers do not fill the description: declarations share a token budget, and scripts find the remaining tools with `searchTools()` (see [`codemode`](usage.md#tools)).
+- `codemode-deferred`: like `codemode`, but the tools are not listed in the `codemode` tool's description either; it only names the server and its tool count. Scripts call them by name and find them with `searchTools()` or in `ALL_TOOLS`. Use it for large servers that codemode scripts use rarely.
+- `deferred`: the tools are not declared to the model until the [`tool_search`](usage.md#tools) tool loads them. The model searches, and the matches are declared from its next call on and called directly, without codemode. Pi activates the `tool_search` tool when such a server connects. Use it for large servers without codemode.
+- `direct`: the tools are declared to the model like built-in tools, and are also callable from codemode.
+- `hidden`: the tools are registered but cannot be called.
+
+`toolExposure` sets the exposure of single tools and overrides `exposure` for them. Keys are tool names as the server offers them, or patterns where `*` matches any characters. An exact name wins over patterns; among patterns, the first match in the object wins. With `hidden` as the server's exposure, only the listed tools are reachable:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "url": "https://api.githubcopilot.com/mcp/",
+      "exposure": "deferred",
+      "toolExposure": {
+        "search_code": "direct",
+        "get_*": "codemode",
+        "delete_*": "hidden"
+      }
+    }
+  }
+}
+```
+
+`pi mcp list` marks tools whose exposure differs from the server's, and the Tools view in `/mcp` shows it too.
+
+Tools that are not declared (`codemode`, `codemode-deferred`, and `deferred` exposure) are reachable through either tool: codemode scripts can call all of them, and `tool_search` can load any of them. For example, with `codemode` active, scripts can call the tools of a `deferred` server, and with `tool_search` active, the model can load the tools of a `codemode` server.
+
+Tools called from codemode scripts do not depend on the active tool set, so they stay callable after `/tree`, resume, and fork. Tools loaded by `tool_search` are recorded in the transcript like any other tool change and stay declared on that branch. To keep `codemode` active without MCP servers too, add `"defaultTools": ["+codemode"]` to [settings](settings.md#tools). To keep pi from activating the `codemode` tool, set `"autoEnableCodemode": false` at the top level of `mcp.json`, next to `mcpServers`. A project `mcp.json` value overrides the global one. Pi warns once when neither `codemode` nor `tool_search` is active, since the tools then cannot be called.
+
+Text results over 20KB reach the model with the middle cut out, in the format Codex uses: the start and end of the text around a `…N chars truncated…` marker. The full text is saved to a temp file whose path the result names. Codemode scripts always receive the whole result, so a script can filter a large result down to what the model needs.
+
+Codemode scripts receive an MCP tool's whole `CallToolResult` (`content` blocks as sent by the server, `structuredContent`, and `isError`), and the `codemode` description declares it as `CallToolResult<T>`. A result with `isError` resolves in scripts and is reported to the model as an error for direct calls. `image(result.content[0])` forwards an image block to the model. The server's `instructions` describe its tools in the `codemode` description.
+
+## Resources
+
+When a connected server offers [resources](https://modelcontextprotocol.io/specification/2025-11-25/server/resources), pi adds the resource tools Codex and opencode use:
+
+- `list_mcp_resources` lists resources as JSON: `{ server?, resources: [{ server, uri, name, ... }], nextCursor? }`. With `server`, it lists one page of that server, and `cursor` continues with the next one. Without, it lists every resource of every server.
+- `list_mcp_resource_templates` lists URI templates for resources the servers do not list, in the same way.
+- `read_mcp_resource` reads a resource given `server` and `uri`. Text resources reach the model as text and images as images; other binary resources are saved to temp files, and the model sees the file path. Scripts receive `{ server, uri, contents }`.
+
+The tools reach every enabled server with resources whose exposure is not `hidden`, and take the widest exposure among them: `direct` if one of the servers is direct, else `codemode`, else `codemode-deferred`, else `deferred`. Resource links in tool results name `read_mcp_resource` and the server.
+
+Resources for MCP Apps (`ui://` URIs or `text/html;profile=mcp-app`) are left out of the listings, since pi does not render them, and so are resource icons.
+
+Reading and listing resources is retried once after a transient HTTP error (408, 429, 5xx). Tool calls are not retried, since the server may have run them.
+
+## Permissions
+
+Every MCP call goes through pi's tool pipeline, so `tool_call` and `tool_result` extension handlers, including permission gates, apply to MCP tools. Calls made from codemode scripts carry the `codemode` call's id as `parentToolCallId`. `pi.getAllTools()` reports the tool annotations servers declare (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`), so a permission extension can confirm only calls that change something (see [Extensions](extensions.md#tool-exposure)). The resource tools are marked read-only.
+
+## Servers from extensions
+
+Extensions can add servers for the current session with `pi.registerMcpServer(name, config)`, using the same config shape as `mcp.json` (see [Extensions](extensions.md#mcp-servers)). They connect like configured servers and appear in `/mcp` with the extension as their source. Enabling, disabling, and exposure changes for them apply to the current session only. A server in `mcp.json` with the same name takes precedence; `/mcp` lists the overridden registration. `pi mcp` shell commands do not load extensions and only see `mcp.json` servers.
+
+## Other MCP extensions
+
+An installed extension that registers the `/mcp` command, such as `pi-mcp-adapter`, replaces the built-in MCP support: pi then neither reads `mcp.json` in sessions nor connects servers, and `/mcp` belongs to that extension. Remove the extension to use the built-in support. To turn off the built-in support without installing another extension, disable `mcp` under Built-in in `pi config`, or set `"extensions": ["-builtin:mcp"]` in [settings](settings.md#resources); `pi mcp` shell commands still work. Likewise, an extension that registers a tool named `codemode` or `tool_search` replaces the built-in tool of that name. `pi mcp` shell commands always use the built-in support.
+
+## SDK
+
+SDK sessions do not load the built-in extensions. Add the MCP extension, the codemode extension for `codemode` and `codemode-deferred` servers, and the tool search extension for `deferred` servers to the resource loader. See [SDK](sdk.md#codemode-mcp).

package/docs/models.md

@@ -673,3 +673,38 @@ For `api: "openai-responses"`, the compatible fields are `supportsDeveloperRole`
 The public Pi AI model type also exposes the Responses compatibility shape for `azure-openai-responses` and `openai-codex-responses`. The Azure transport uses `supportsDeveloperRole`, `supportsStrictMode`, and `supportsOpenAIGrammarTools`; the Codex transport uses `supportsStrictMode`, `supportsOpenAIGrammarTools`, and `supportsToolSearch`. Other Responses options do not alter those transports.
 
 For `bedrock-converse-stream`, `compat.supportsStrictMode` controls Bedrock strict JSON-schema tool definitions and defaults to `false`. The other built-in API tags do not define model compatibility options.
+
+## Use classifier models
+
+Classifier models do not chat. They answer typed questions about JSON state: pick one of several choices, answer yes or no, or give a score, each with probabilities. Pi includes TypeSafe's Jev model from these providers:
+
+| Provider | Model IDs | Authentication |
+|---|---|---|
+| `typesafe` | `jev-latest` | `TYPESAFE_API_KEY` |
+| `openrouter` | `typesafe/jev-1.13`, `~typesafe/jev-latest` | `OPENROUTER_API_KEY` or `/login` |
+| `cloudflare-workers-ai` | `typesafe/jev` | `CLOUDFLARE_API_KEY` and `CLOUDFLARE_ACCOUNT_ID` |
+| `vercel-ai-gateway` | `typesafe-ai/jev` | `AI_GATEWAY_API_KEY` |
+| `opencode` | `jev-1.13`, `jev-1.13-free` | `OPENCODE_API_KEY` |
+
+Chat models on a [llama.cpp router](llama-cpp.md#classification) are also listed as classifier models.
+
+Classifier models do not appear in `/model`. The model reaches them through the [`codemode`](usage.md#enable-codemode) tool, which is off unless an MCP server turned it on. Enable it with `"defaultTools": ["+codemode"]` in [settings](settings.md#tools). Scripts then list classifier models with `models.getAvailableOfType("classifier")` and call `models.classify(model, { state, questions })`:
+
+```js
+const jev = await models.getModelOfType("classifier", "typesafe", "jev-latest");
+const result = await models.classify(jev, {
+  state: { message: "The change works, thanks." },
+  questions: {
+    approved: {
+      type: "bool",
+      instructions: "Does the user approve of the result?",
+      criteria: { true: "Approval", false: "No approval" },
+    },
+  },
+});
+return result.answers;
+```
+
+When the service reports token counts, as all System One services do, `result.usage` carries them with their cost. Pi adds the usage of a script's classifier calls to the `codemode` tool result, so it counts toward the session cost in the footer and `/session`. The cost uses the model's catalog price; models without one, such as TypeSafe's direct `jev-latest`, report tokens at no cost.
+
+Extensions call classifiers through `ctx.modelRegistry.classify()`, without codemode. [Virtual models](virtual-models.md#route-requests) can use them to route requests; see the `jev-router.ts` example.

package/docs/packages.md

@@ -227,3 +227,7 @@ Packages can appear in both global and project settings. If the same package app
 - npm: package name
 - git: repository URL without ref
 - local: resolved absolute path
+
+## Built-in extensions and host dependencies
+
+`pi config` also manages built-in extensions. Managed npm and git packages suppress automatic installation of host-provided Pi peer dependencies. Declare these as peers, not production dependencies: physical copies can create duplicate classes and registries, and Pi warns about that manifest configuration. Local packages keep their own dependency trees.

package/docs/providers.md

@@ -323,3 +323,9 @@ When resolving credentials for a provider:
 2. `auth.json` entry (API key or OAuth token)
 3. Environment variable
 4. Custom provider keys from `models.json`
+
+## OpenAI subscriptions and classifiers
+
+`/login openai` offers Sign in with ChatGPT. The older OpenAI Codex provider remains available as OpenAI Codex (legacy), with `gpt-6.1-sol` as its default model. GPT-6.1 Sol is also available through OpenAI and Azure OpenAI.
+
+TypeSafe classifier models use `TYPESAFE_API_KEY`; see [Classifier models](models.md#use-classifier-models).

package/docs/rpc.md

@@ -70,7 +70,7 @@ If the agent is streaming and no `streamingBehavior` is specified, the command r
 
 Response:
 ```json
-{"id": "req-1", "type": "response", "command": "prompt", "success": true}
+{"id": "req-1", "type": "response", "command": "prompt", "success": true, "data": {"disposition": "started"}}
 ```
 
 `success: true` means the prompt was accepted, queued, or handled immediately. `success: false` means the prompt was rejected before acceptance. Failures after acceptance are reported through the normal event and message stream, not as a second `response` for the same request id.
@@ -94,7 +94,7 @@ The `images` field is optional. Each image uses `ImageContent` format (same as `
 
 Response:
 ```json
-{"type": "response", "command": "steer", "success": true}
+{"type": "response", "command": "steer", "success": true, "data": {"disposition": "queued"}}
 ```
 
 See [set_steering_mode](#set_steering_mode) for controlling how steering messages are processed.
@@ -116,7 +116,7 @@ The `images` field is optional. Each image uses `ImageContent` format (same as `
 
 Response:
 ```json
-{"type": "response", "command": "follow_up", "success": true}
+{"type": "response", "command": "follow_up", "success": true, "data": {"disposition": "queued"}}
 ```
 
 See [set_follow_up_mode](#set_follow_up_mode) for controlling how follow-up messages are processed.
@@ -1651,3 +1651,5 @@ process.on("SIGINT", () => {
     agent.stdin.write(JSON.stringify({ type: "abort" }) + "\n");
 });
 ```
+
+Successful `prompt` responses include `data.disposition`: `handled`, `queued`, or `started`. `steer` and `follow_up` return `handled` or `queued`. This describes the submitted input, not completion. When an extension handles input, do not wait for a run to settle on its behalf.