@averyyy/pi-coding-agent 0.87.1-piclient.1 → 0.99.1-piclient.1

package/docs/virtual-models.md

@@ -0,0 +1,114 @@
+# Virtual Models
+
+A virtual model is a selectable model that picks a physical model for each request. Use one to route by task, cost, or conversation state. For example, a router can send quick questions to a small model and hard problems to a large one, while the user selects a single model.
+
+Register virtual models from an [extension](extensions.md). They appear in `/model`, `--model`, scoped models, and settings like any other model. A virtual model can be listed under any provider, including one with physical models, such as `openai-codex/auto`.
+
+## Selection and dispatch
+
+A virtual model selects a model and a thinking level. A router maps that pair to a physical pair for each request:
+
+```
+selected (virtual model, virtual level)  ->  dispatched (physical model, physical level)
+jev/auto:low                             ->  anthropic/claude-sonnet-4-5:high
+```
+
+The virtual thinking level is an input to the router. Its meaning is up to the router; it need not correspond to a reasoning budget.
+
+Pi keeps the two pairs apart:
+
+| | Selection | Dispatch |
+|---|---|---|
+| Recorded in | `model_change` and `thinking_level_change` entries | Each assistant message: `provider`, `api`, `model`, `thinkingLevel` |
+| Visible as | `ctx.model`, `ctx.thinkingLevel`, `PI_MODEL`, `PI_REASONING_LEVEL`, `/model` | The assistant message of each response |
+
+Providers only receive physical models. Assistant messages name the physical model, so replaying a conversation across different physical models works the same as after a manual model switch. Resuming a session restores the virtual selection from its latest `model_change` entry. If the virtual model is no longer registered, Pi falls back to the physical model that answered last.
+
+In interactive mode, the footer shows the routed model next to the selection, for example `auto • high → gpt-5.6-luna • medium`. `/session` lists the cost for each physical model.
+
+Context usage uses the limits of the physical model that produced the latest response, even if that response came before switching to the virtual model. Without such a response, it uses the limits declared on the virtual model, if any. Compaction checks the same limits, and again the limits of the model each request is routed to. If that model's context window is too small for the conversation, Pi compacts before sending the request; the route stays as the router chose it.
+
+## Register a virtual model
+
+```typescript
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerVirtualModel({
+    provider: "router",
+    id: "auto",
+    name: "Auto",
+    thinkingLevels: ["low", "high"],
+    route(request, ctx) {
+      // Tool follow-ups and retries stay on the model that handled the turn.
+      const sticky = request.failed ?? request.previous;
+      if (request.reason !== "user" && sticky) {
+        return { model: sticky.model, thinkingLevel: sticky.thinkingLevel ?? "medium" };
+      }
+      const id = request.thinkingLevel === "high" ? "claude-sonnet-4-5" : "claude-haiku-4-5";
+      return { model: ctx.modelRegistry.find("anthropic", id)!, thinkingLevel: "medium" };
+    },
+  });
+}
+```
+
+- `provider` is the provider the model is listed under. It can be any provider ID. A provider can list several virtual models next to its physical ones. On a physical provider, the virtual model is available when that provider has credentials. Under an ID that no provider uses, it is always available.
+- `id` must not be the ID of a physical model of that provider. If a catalog refresh later adds a physical model with the same ID, the virtual model hides it.
+- `thinkingLevels` lists the levels offered for selection. It defaults to `["off"]`.
+- `contextWindow` and `maxTokens` are shown before the first response. Unset limits are unknown.
+- `input` lists the input types offered for selection. It defaults to text and images; physical models without image support receive placeholders.
+
+Registration follows the same queuing and reload rules as `pi.registerProvider()`. Registering the same provider and ID again replaces the virtual model. `pi.unregisterVirtualModel(provider, id)` removes it; `pi.unregisterProvider()` does not. SDK code can register one without an extension: `modelRuntime.registerVirtualModel(definition)`.
+
+## Route requests
+
+`route(request, ctx)` runs before every request made with the virtual model and returns `{ model, thinkingLevel }`. The model can be any physical model in the catalog whose provider has credentials; look it up with `ctx.modelRegistry`. A virtual model cannot route to another virtual model. Pi clamps the thinking level to the returned model.
+
+| Field | Meaning |
+|---|---|
+| `model`, `thinkingLevel` | The selected virtual model and level |
+| `reason` | Why the request is made, see below |
+| `previous` | Physical model and thinking level of the latest successful response in `messages` |
+| `failed` | For `retry`: physical model, thinking level, and assistant `message` of the failed request, which `messages` no longer contains. The message carries `stopReason` and `errorMessage`. Absent when routing itself failed |
+| `state` | Router state last returned on this session branch, see below |
+| `messages` | The conversation for this request, including system messages |
+| `signal` | Abort signal of the request |
+
+| `reason` | Request |
+|---|---|
+| `user` | First request after a message the user wrote, including steering and follow-up messages |
+| `continuation` | Any other request in the agent loop, such as after tool results or extension messages |
+| `retry` | Automatic retry after a failed request, including after compaction for a context overflow |
+| `direct` | Request made outside the agent loop, such as a compaction summary or an extension calling `ctx.modelRegistry.streamSimple()` |
+
+Returning `previous` for `continuation` and `failed` for `retry` keeps prompt caches and thinking signatures valid. Switching models between turns is allowed but loses the prompt cache. A retry can also switch to another model, for example when `failed.message.errorMessage` reports that a provider is overloaded or the context overflowed.
+
+If `route()` throws, or returns a virtual model or a model without credentials, the request ends with an error response.
+
+## Keep routing state
+
+`route()` can return `state` next to the model. Pi stores it on the session branch and passes it back as `request.state` on later requests. Use it for decisions the transcript does not record, such as classifier results or a routing phase:
+
+```typescript
+pi.registerVirtualModel<{ phase: "plan" | "build" }>({
+  provider: "router",
+  id: "phased",
+  name: "Phased",
+  route(request, ctx) {
+    const state = request.state ?? { phase: "plan" };
+    const id = state.phase === "plan" ? "claude-opus-4-5" : "claude-haiku-4-5";
+    return { model: ctx.modelRegistry.find("anthropic", id)!, thinkingLevel: "medium", state };
+  },
+});
+```
+
+- State must be JSON-serializable. Returning `undefined` or `request.state` itself keeps the current state.
+- Pi stores any other returned object as new state, before the request is sent, even when it equals the current state. Return a new object only when the state changes. The state stays stored if the request later fails.
+- State follows the session tree, so forks and `/tree` navigation see the state of their branch. It survives compaction.
+- `direct` requests have no state, and Pi ignores state they return.
+
+The transcript already records the selection and every dispatched model, and `ctx.sessionManager.getBranch()` exposes both.
+
+Routers can call other models through `ctx.modelRegistry`, for example `ctx.modelRegistry.classify()` with a classifier model from `ctx.modelRegistry.findOfType("classifier", provider, id)`. The call adds latency before the first token of the turn.
+
+See [`jev-router.ts`](../examples/extensions/jev-router.ts) for a complete router. It plans on a strong OpenAI Codex model chosen by the Jev classifier, lets that model make the first edit, and then switches once to a cheaper model, accepting a single prompt-cache miss. It keeps the phase as router state.

package/docs/windows.md

@@ -42,6 +42,8 @@ To replace the model-facing `bash` tool with `powershell`, add this to `~/.pi/ag
 }
 ```
 
+`["-bash", "+powershell"]` does the same while keeping any other default tools you configured.
+
 Restart Pi, then ask it to run a harmless PowerShell command. The `!` and `!!` editor commands continue to use Bash. The `powershell` tool is available only when Pi runs as a native Windows process.
 
 See [Settings](settings.md#tools) for other tool combinations.

package/examples/README.md

@@ -9,7 +9,7 @@ Example code for the pi-coding-agent SDK, process integration, and extensions.
 Build the coding-agent package before running it from a repository checkout:
 
 ```bash
-npx tsx examples/rpc-client.ts "Explain this repository"
+node examples/rpc-client.ts "Explain this repository"
 ```
 
 ## Directories

package/examples/extensions/README.md

@@ -113,6 +113,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 |-----------|-------------|
 | `message-renderer.ts` | Custom message rendering with colors and expandable details via `registerMessageRenderer` |
 | `entry-renderer.ts` | TUI-only session entry rendering via `appendEntry` and `registerEntryRenderer` |
+| `debug-provider.ts` | Toggle raw provider stream capture with `/debug-provider` and inspect each assistant message in a TUI-only session entry |
 | `event-bus.ts` | Inter-extension communication via `pi.events` |
 
 ### Session Metadata
@@ -128,6 +129,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 |-----------|-------------|
 | `custom-provider-anthropic/` | Custom Anthropic provider with OAuth support and custom streaming implementation |
 | `custom-provider-gitlab-duo/` | GitLab Duo provider using pi-ai's built-in Anthropic/OpenAI streaming via proxy |
+| `jev-router.ts` | Virtual model via `registerVirtualModel` that plans on Codex Sol or Terra (picked by the Jev classifier) and switches to Luna after the first edit |
 
 ### External Dependencies
 

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.87.1",
+  "version": "0.99.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.87.1",
+      "version": "0.99.1",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "0.87.1",
+  "version": "0.99.1",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "0.87.1",
+  "version": "0.99.1",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/test.ts

@@ -1,16 +1,16 @@
 /**
  * Test script for GitLab Duo extension
- * Run: npx tsx test.ts [model-id] [--thinking]
+ * Run: node test.ts [model-id] [--thinking]
  *
  * Examples:
- *   npx tsx test.ts                              # Test default (claude-sonnet-4-5-20250929)
- *   npx tsx test.ts gpt-5-codex                  # Test GPT-5 Codex
- *   npx tsx test.ts claude-sonnet-4-5-20250929 --thinking
+ *   node test.ts                              # Test default (claude-sonnet-4-5-20250929)
+ *   node test.ts gpt-5-codex                  # Test GPT-5 Codex
+ *   node test.ts claude-sonnet-4-5-20250929 --thinking
  */
 
 import { type Api, type Context, type Model, registerApiProvider, streamSimple } from "@earendil-works/pi-ai/compat";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { readFileSync } from "fs";
-import { getAgentDir } from "packages/coding-agent/src/config.js";
 import { join } from "path";
 import { MODELS, streamGitLabDuo } from "./index.ts";
 

package/examples/extensions/debug-provider.ts

@@ -0,0 +1,90 @@
+/**
+ * Raw provider event viewer.
+ *
+ * Usage: /debug-provider [on|off]
+ * With no argument, the command toggles capture. Captured events are persisted
+ * as expandable custom entries.
+ */
+
+import { type ExtensionAPI, keyHint } from "@earendil-works/pi-coding-agent";
+import { Box, Text } from "@earendil-works/pi-tui";
+
+const ENTRY_TYPE = "debug-provider-events";
+const STATUS_KEY = "debug-provider";
+
+interface ProviderDebugEntry {
+	provider: string;
+	api: string;
+	model: string;
+	events: unknown[];
+}
+
+export default function (pi: ExtensionAPI) {
+	let enabled = false;
+	let activeEvents: unknown[] | undefined;
+	let completedEntry: ProviderDebugEntry | undefined;
+
+	pi.registerEntryRenderer<ProviderDebugEntry>(ENTRY_TYPE, (entry, { expanded }, theme) => {
+		const data = entry.data;
+		if (!data) return new Text(theme.fg("warning", "[provider debug] Missing event data"), 0, 0);
+
+		const box = new Box(1, 1, (text) => theme.bg("customMessageBg", text));
+		const count = `${data.events.length} event${data.events.length === 1 ? "" : "s"}`;
+		const expandHint = expanded ? "" : ` (${keyHint("app.tools.expand", "to view events")})`;
+		box.addChild(
+			new Text(
+				`${theme.fg("accent", "[provider debug]")} ${data.provider}/${data.model} (${data.api}) · ${count}${expandHint}`,
+				0,
+				0,
+			),
+		);
+		if (expanded) {
+			box.addChild(new Text(JSON.stringify(data.events, null, 2), 0, 0));
+		}
+		return box;
+	});
+
+	pi.registerCommand("debug-provider", {
+		description: "Toggle capture of raw provider stream events",
+		handler: async (args, ctx) => {
+			const requestedState = args.trim().toLowerCase();
+			if (requestedState !== "" && requestedState !== "on" && requestedState !== "off") {
+				ctx.ui.notify("Usage: /debug-provider [on|off]", "warning");
+				return;
+			}
+
+			enabled = requestedState === "" ? !enabled : requestedState === "on";
+			if (!enabled) {
+				activeEvents = undefined;
+				completedEntry = undefined;
+			}
+			ctx.ui.setStatus(STATUS_KEY, enabled ? "provider debug" : undefined);
+			ctx.ui.notify(`Provider event capture ${enabled ? "enabled" : "disabled"}`, "info");
+		},
+	});
+
+	pi.on("turn_start", () => {
+		activeEvents = enabled ? [] : undefined;
+	});
+
+	pi.on("provider_stream_event", (event) => {
+		activeEvents?.push(structuredClone(event.data));
+	});
+
+	pi.on("message_end", (event) => {
+		if (event.message.role !== "assistant" || !activeEvents) return;
+		completedEntry = {
+			provider: event.message.provider,
+			api: event.message.api,
+			model: event.message.model,
+			events: activeEvents,
+		};
+		activeEvents = undefined;
+	});
+
+	pi.on("turn_end", () => {
+		if (!completedEntry) return;
+		pi.appendEntry<ProviderDebugEntry>(ENTRY_TYPE, completedEntry);
+		completedEntry = undefined;
+	});
+}

package/examples/extensions/gondolin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-gondolin",
-	"version": "0.87.1",
+	"version": "0.99.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-gondolin",
-			"version": "0.87.1",
+			"version": "0.99.1",
 			"dependencies": {
 				"@earendil-works/gondolin": "0.12.0"
 			}

package/examples/extensions/gondolin/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-gondolin",
 	"private": true,
-	"version": "0.87.1",
+	"version": "0.99.1",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/jev-router.ts

@@ -0,0 +1,113 @@
+/**
+ * Jev router - a virtual model that plans on a strong model and implements on a cheap one.
+ *
+ * Registers `jev/auto`, which routes between three OpenAI Codex models:
+ *
+ * - Planning: GPT-5.6 Sol for complex work, GPT-5.6 Terra otherwise. The Jev classifier rates the
+ *   first user message; planning stays on the chosen model.
+ * - Implementation: GPT-5.6 Luna.
+ *
+ * The planning model explores, plans, and makes the first edit. After the first successful `edit`
+ * or `write` tool call, the next request of the same turn goes to Luna, and the session stays
+ * there. A session therefore switches models once and accepts a single prompt-cache miss.
+ *
+ * The phase is router state: Pi stores it on the session branch, so it follows the session tree
+ * and survives compaction. The selected thinking level passes through as the reasoning effort of
+ * the chosen model. Requests outside the agent loop, such as compaction summaries, go to Luna.
+ *
+ * Requires TypeSafe credentials (TYPESAFE_API_KEY) and an OpenAI Codex login.
+ * Usage: pi -e ./jev-router.ts --model jev/auto
+ */
+
+import type { Message } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext, ModelRoute, ModelRouteRequest } from "@earendil-works/pi-coding-agent";
+
+const PROVIDER = "openai-codex";
+const SOL = "gpt-5.6-sol";
+const TERRA = "gpt-5.6-terra";
+const LUNA = "gpt-5.6-luna";
+
+/** Tools whose successful result means implementation has started. */
+const EDIT_TOOLS = new Set(["edit", "write"]);
+
+interface JevState {
+	phase: "planning" | "implementation";
+	/** OpenAI Codex model for this phase. */
+	model: string;
+}
+
+type JevRequest = ModelRouteRequest<JevState>;
+
+function routeTo(request: JevRequest, ctx: ExtensionContext, id: string, state?: JevState): ModelRoute<JevState> {
+	const model = ctx.modelRegistry.find(PROVIDER, id);
+	if (!model) throw new Error(`Model ${PROVIDER}/${id} is not in the catalog`);
+	return { model, thinkingLevel: request.thinkingLevel, state };
+}
+
+function lastUserText(messages: readonly Message[]): string {
+	const content = messages.filter((message) => message.role === "user").at(-1)?.content ?? "";
+	if (typeof content === "string") return content;
+	return content.flatMap((block) => (block.type === "text" ? [block.text] : [])).join("\n");
+}
+
+/** Whether a tool call since the last user message edited a file successfully. */
+function editedThisTurn(messages: readonly Message[]): boolean {
+	const lastUser = messages.findLastIndex((message) => message.role === "user");
+	return messages
+		.slice(lastUser + 1)
+		.some((message) => message.role === "toolResult" && EDIT_TOOLS.has(message.toolName) && !message.isError);
+}
+
+/** Planning model for a new session: Sol for complex work, Terra otherwise or when Jev is unavailable. */
+async function choosePlanningModel(request: JevRequest, ctx: ExtensionContext): Promise<string> {
+	// Keep a planning model the session already uses, so switching to jev/auto costs no cache miss.
+	const previous = request.previous?.model;
+	if (previous?.provider === PROVIDER && (previous.id === SOL || previous.id === TERRA)) return previous.id;
+
+	const jev = ctx.modelRegistry.findOfType("classifier", "typesafe", "jev-latest");
+	if (!jev) return TERRA;
+	const result = await ctx.modelRegistry.classify(
+		jev,
+		{
+			state: { prompt: lastUserText(request.messages).slice(0, 16_000) },
+			questions: {
+				complexity: {
+					type: "choice",
+					instructions: "How demanding is the software engineering work requested in `prompt`?",
+					criteria: {
+						standard: "Ordinary features, fixes, reviews, or questions",
+						complex: "Subtle design, cross-cutting changes, or hard debugging",
+					},
+				},
+			},
+		},
+		{ signal: request.signal },
+	);
+	const answer = result.stopReason === "stop" ? result.answers.complexity : undefined;
+	return answer?.type === "choice" && (answer.probabilities.complex ?? 0) >= 0.5 ? SOL : TERRA;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerVirtualModel<JevState>({
+		provider: "jev",
+		id: "auto",
+		name: "Auto (Jev)",
+		thinkingLevels: ["low", "medium", "high", "xhigh"],
+		// Shared by all three models; shown before the first response.
+		contextWindow: 272_000,
+		maxTokens: 128_000,
+		async route(request, ctx) {
+			if (request.reason === "direct") return routeTo(request, ctx, LUNA);
+			const state = request.state;
+			if (!state) {
+				const model = await choosePlanningModel(request, ctx);
+				return routeTo(request, ctx, model, { phase: "planning", model });
+			}
+			// The planning model made the first edit: hand the rest of the work to Luna.
+			if (state.phase === "planning" && editedThisTurn(request.messages)) {
+				return routeTo(request, ctx, LUNA, { phase: "implementation", model: LUNA });
+			}
+			return routeTo(request, ctx, state.model);
+		},
+	});
+}

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "1.17.1",
+	"version": "0.99.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "1.17.1",
+			"version": "0.99.1",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "^0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-sandbox",
 	"private": true,
-	"version": "1.17.1",
+	"version": "0.99.1",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "0.87.1",
+  "version": "0.99.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "0.87.1",
+      "version": "0.99.1",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-with-deps",
   "private": true,
-  "version": "0.87.1",
+  "version": "0.99.1",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/rpc-client.ts

@@ -2,7 +2,7 @@
  * Run one prompt through a Pi RPC child process.
  *
  * Build the coding-agent package first, then run:
- * npx tsx examples/rpc-client.ts "Explain this repository"
+ * node examples/rpc-client.ts "Explain this repository"
  */
 
 import { dirname, join } from "node:path";

package/examples/rpc-extension-ui.ts

@@ -5,7 +5,7 @@
  * Demonstrates how to build a custom UI on top of the RPC protocol,
  * including handling extension UI requests (select, confirm, input, editor).
  *
- * Usage: npx tsx examples/rpc-extension-ui.ts
+ * Usage: node examples/rpc-extension-ui.ts
  *
  * Slash commands:
  *   /select  - demo select dialog

package/examples/sdk/14-codemode-mcp.ts

@@ -0,0 +1,61 @@
+/**
+ * Codemode, Tool Search, and MCP
+ *
+ * The CLI loads `codemode`, `tool_search`, and MCP as built-in extensions. SDK sessions add
+ * them to the resource loader's extension factories.
+ *
+ * `codemode` and `tool_search` are registered inactive. Enable them through the `defaultTools` setting
+ * (`tools` would also restrict the session to the named tools, which hides MCP tools), or let the
+ * MCP extension activate them: `codemode` for servers with `codemode` or `codemode-deferred` exposure,
+ * `tool_search` for servers with `deferred` exposure.
+ */
+
+import {
+	createAgentSession,
+	createCodemodeExtension,
+	createMcpExtension,
+	createToolSearchExtension,
+	DefaultResourceLoader,
+	getAgentDir,
+	SessionManager,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+
+const cwd = process.cwd();
+
+const resourceLoader = new DefaultResourceLoader({
+	cwd,
+	agentDir: getAgentDir(),
+	extensionFactories: [
+		createCodemodeExtension({ mode: "on" }),
+		createToolSearchExtension(),
+		// Reads mcp.json from the agent directory and the trusted project, like the CLI.
+		createMcpExtension(),
+	],
+});
+await resourceLoader.reload();
+
+const settingsManager = SettingsManager.create(cwd);
+// `+name` adds to the configured default tools instead of replacing them.
+settingsManager.applyOverrides({ defaultTools: ["+codemode", "+tool_search"] });
+
+const { session } = await createAgentSession({
+	resourceLoader,
+	settingsManager,
+	sessionManager: SessionManager.inMemory(),
+});
+
+try {
+	// Emits session_start, which connects the MCP servers in the background.
+	await session.bindExtensions({});
+	console.log("Active tools:", session.getActiveToolNames().join(", "));
+	session.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		}
+	});
+	await session.prompt("Use codemode to count the TypeScript files in src/ and list the three largest.");
+	console.log();
+} finally {
+	session.dispose();
+}

package/examples/sdk/README.md

@@ -21,12 +21,13 @@ The runtime example shows how to build a recreate function that closes over proc
 | `11-sessions.ts` | In-memory, persistent, continue, list sessions |
 | `12-full-control.ts` | Replace everything, no discovery |
 | `13-session-runtime.ts` | Manage runtime-backed session replacement |
+| `14-codemode-mcp.ts` | Add the `codemode`, `tool_search`, and MCP extensions |
 
 ## Running
 
 ```bash
 cd packages/coding-agent
-npx tsx examples/sdk/01-minimal.ts
+node examples/sdk/01-minimal.ts
 ```
 
 ## Quick Reference