feat(coding-agent): codemode and MCP

This adds codemode and MCP support to pi. Codemode (packages/codemode) runs
model-written JavaScript in a QuickJS wasm VM inside a worker. From there the
script calls pi's tools as async functions, uses a per-session store, and can
read the model catalog and run classifiers. The codemode tool in coding-agent
is compatible with Codex's exec tool, and codemode.mode works like Codex's
tool modes (on or only). Large results are written to a JSON temp file. MCP
(packages/mcp) is a standalone client for stdio and streamable HTTP servers,
with OAuth.

The core only gets general mechanisms; codemode, tool_search and MCP are
built-in extensions that use them. Other extensions can replace these
built-ins. Tools declare an exposure: direct, model-only, codemode, deferred
or hidden. prepareLoadout() lets an orchestrating tool change which tool
declarations the model sees. ctx.executeTool() runs nested calls through
validation and the tool_call/tool_result hooks. Those calls emit events with
parentToolCallId and are recorded as bounded nestedCalls on the parent
result, which compaction and HTML export use. Tools can also return
structuredContent with an outputSchema, and can report errors with isError
instead of throwing. MCP servers come from mcp.json (global, or per project
after the project is trusted) or from pi.registerMcpServer(). They are
managed with /mcp and pi mcp list|login|logout, and their runtimes load on
first use.

Closes #10040

packages/agent/examples/mcp-codemode/main.ts

@@ -0,0 +1,50 @@
+/**
+ * An Agent with the tools of an MCP server plus a codemode tool that calls them from JavaScript.
+ *
+ *   ANTHROPIC_API_KEY=... node packages/agent/examples/mcp-codemode/main.ts \
+ *     npx -y @modelcontextprotocol/server-filesystem .
+ *
+ * The arguments are the command that starts a stdio MCP server.
+ */
+
+import { Agent } from "@earendil-works/pi-agent-core";
+import { createModels } from "@earendil-works/pi-ai";
+import { anthropicProvider } from "@earendil-works/pi-ai/providers/anthropic";
+import { McpClient, StdioTransport } from "@earendil-works/pi-mcp";
+import { createCodemodeTool, createMcpTools, createNestedToolRunner } from "./tools.ts";
+
+const [command, ...args] = process.argv.slice(2);
+if (!command) {
+	console.error("Usage: main.ts <mcp server command> [args...]");
+	process.exit(1);
+}
+
+const models = createModels();
+models.setProvider(anthropicProvider());
+const model = models.getModel("anthropic", "claude-sonnet-4-6");
+if (!model) throw new Error("Model not found");
+
+const client = new McpClient({ name: "pi-agent-example", version: "1.0.0" });
+await client.connect(new StdioTransport({ command, args }));
+
+try {
+	const agent = new Agent({
+		initialState: { systemPrompt: "You are a helpful assistant.", model },
+		streamFn: models.streamSimple.bind(models),
+	});
+	const mcpTools = await createMcpTools(client, "mcp");
+	// The model can call the MCP tools directly or batch them in one codemode script.
+	agent.state.tools = [...mcpTools, createCodemodeTool(mcpTools, createNestedToolRunner(agent))];
+
+	agent.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		} else if (event.type === "tool_execution_start") {
+			console.log(`\n[${event.toolName}]`);
+		}
+	});
+	await agent.prompt("Use codemode to list what the MCP tools can do, then summarize it in two sentences.");
+	console.log();
+} finally {
+	await client.close();
+}

packages/agent/examples/mcp-codemode/tools.ts

@@ -0,0 +1,172 @@
+/**
+ * Adapters that give a pi-agent-core `Agent` MCP tools and a codemode tool, using
+ * `@earendil-works/pi-mcp` and `@earendil-works/pi-codemode`. See main.ts for how they fit together.
+ */
+
+import {
+	type Agent,
+	type AgentTool,
+	type AgentToolCallOutcome,
+	type AgentToolResult,
+	runToolCall,
+} from "@earendil-works/pi-agent-core";
+import type { ImageContent, JsonObject, JsonValue, TextContent } from "@earendil-works/pi-ai";
+import {
+	type CodemodeJsonSchema,
+	CodemodeSandbox,
+	type CodemodeTool,
+	renderDeclarations,
+} from "@earendil-works/pi-codemode";
+import { type McpClient, toLlmContent } from "@earendil-works/pi-mcp";
+import { Type } from "typebox";
+
+/** Provider tool names are limited to 64 characters of `[A-Za-z0-9_-]`. */
+function toToolName(prefix: string, name: string): string {
+	return `${prefix}_${name}`.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 64);
+}
+
+function textOf(result: AgentToolResult<unknown>): string {
+	return result.content
+		.filter((block): block is TextContent => block.type === "text")
+		.map((block) => block.text)
+		.join("\n");
+}
+
+/**
+ * One `AgentTool` per tool of a connected MCP server, named `<prefix>_<tool>`. Tools with an MCP
+ * output schema declare it as `outputSchema` and return `structuredContent`, which codemode scripts
+ * receive instead of the text.
+ */
+export async function createMcpTools(client: McpClient, prefix: string): Promise<AgentTool[]> {
+	const tools = await client.listTools();
+	return tools.map(
+		(tool): AgentTool => ({
+			name: toToolName(prefix, tool.name),
+			label: tool.title ?? tool.name,
+			description: tool.description ?? tool.title ?? `MCP tool ${tool.name}`,
+			// Providers require an object schema, and some reject one without `properties`.
+			parameters: Type.Unsafe({
+				...tool.inputSchema,
+				type: "object",
+				properties: tool.inputSchema.properties ?? {},
+			}),
+			outputSchema: tool.outputSchema ? Type.Unsafe<Record<string, unknown>>(tool.outputSchema) : undefined,
+			execute: async (_toolCallId, params, signal, onUpdate) => {
+				const result = await client.callTool(tool.name, params as Record<string, unknown>, {
+					signal,
+					onProgress: (progress) => {
+						const text = progress.message ?? `Progress ${progress.progress}`;
+						onUpdate?.({ content: [{ type: "text", text }], details: undefined });
+					},
+				});
+				const content = toLlmContent(result);
+				if (result.isError && content.length === 0) {
+					content.push({ type: "text", text: `MCP tool ${tool.name} failed` });
+				}
+				return {
+					content,
+					details: undefined,
+					structuredContent: result.structuredContent as JsonValue | undefined,
+					// MCP reports tool failures in the result instead of as a protocol error.
+					isError: result.isError === true,
+				};
+			},
+		}),
+	);
+}
+
+/**
+ * Run a tool call on behalf of another tool through the agent's pipeline: argument validation and
+ * the agent's `beforeToolCall`/`afterToolCall` hooks apply as for calls the model makes. Calling
+ * `tool.execute()` directly also works when the agent has no hooks.
+ */
+export function createNestedToolRunner(
+	agent: Agent,
+): (name: string, args: unknown, signal: AbortSignal) => Promise<AgentToolCallOutcome> {
+	let nextId = 1;
+	return (name, args, signal) => {
+		const assistantMessage = agent.state.messages.findLast((message) => message.role === "assistant");
+		if (assistantMessage?.role !== "assistant") throw new Error("Nested tool calls need an assistant message");
+		const tools = agent.state.tools;
+		return runToolCall(
+			{ type: "toolCall", id: `nested-${nextId++}`, name, arguments: (args ?? {}) as JsonObject },
+			{
+				tools,
+				assistantMessage,
+				context: { messages: agent.state.messages, tools },
+				beforeToolCall: agent.beforeToolCall,
+				afterToolCall: agent.afterToolCall,
+				signal,
+			},
+		);
+	};
+}
+
+export const CODEMODE_TOOL_NAME = "codemode";
+
+const codemodeParameters = Type.Object({
+	code: Type.String({ description: "JavaScript source. Top-level await and return work." }),
+});
+
+/**
+ * A tool that runs model-written JavaScript in the codemode sandbox, where `tools.<name>(args)`
+ * calls `tools`. Nested results stay out of the model context; only the script's output and
+ * return value come back.
+ */
+export function createCodemodeTool(
+	tools: readonly AgentTool[],
+	runTool: (name: string, args: unknown, signal: AbortSignal) => Promise<AgentToolCallOutcome>,
+): AgentTool<typeof codemodeParameters> {
+	const callable = tools.filter((tool) => tool.name !== CODEMODE_TOOL_NAME);
+	const sandboxTools: CodemodeTool[] = callable.map((tool) => ({
+		name: tool.name,
+		description: tool.description,
+		// TypeBox schemas are JSON Schema.
+		inputSchema: tool.parameters as CodemodeJsonSchema,
+		// What the script receives: the structured result if the tool declares one, else its text.
+		outputSchema: (tool.outputSchema as CodemodeJsonSchema | undefined) ?? { type: "string" },
+		execute: async (args, { signal }) => {
+			const outcome = await runTool(tool.name, args, signal);
+			if (tool.outputSchema && outcome.result.structuredContent !== undefined) {
+				return outcome.result.structuredContent;
+			}
+			const text = textOf(outcome.result);
+			if (outcome.isError) throw new Error(text || `Tool ${tool.name} failed`);
+			return text;
+		},
+	}));
+
+	return {
+		name: CODEMODE_TOOL_NAME,
+		label: "Codemode",
+		description: [
+			"Run JavaScript that calls other tools, to chain calls, run them in parallel, or filter large results.",
+			"The code is the body of an async function. There is no Node, file system, network, or timers.",
+			"Call tools as `await tools.<name>(args)`. Output with `text(value)` or `console.log()`, or `return` a value.",
+			"Only the output and the return value reach you, not the results of the tool calls.",
+			"",
+			"```ts",
+			renderDeclarations({ tools: sandboxTools }),
+			"```",
+		].join("\n"),
+		parameters: codemodeParameters,
+		execute: async (_toolCallId, params, signal) => {
+			const sandbox = new CodemodeSandbox({ tools: sandboxTools, timeoutMs: 120_000 });
+			try {
+				const result = await sandbox.execute(params.code, { signal });
+				// Items from text(), console.*, and image(), in order. They have pi-ai's content shapes.
+				const content: (TextContent | ImageContent)[] = [...result.output];
+				if (result.ok && result.value !== undefined) {
+					const value = typeof result.value === "string" ? result.value : JSON.stringify(result.value);
+					content.push({ type: "text", text: value });
+				}
+				if (!result.ok) {
+					content.push({ type: "text", text: `Script failed: ${result.error.stack ?? result.error.message}` });
+				}
+				return { content, details: { calls: result.calls }, isError: !result.ok };
+			} finally {
+				await sandbox.close();
+			}
+		},
+	};
+}