Codemode, MCP và tool search

export interface CodemodeTool {	/**	 * The script calls tools as `tools.<id>(args)`, where `<id>` is the name with characters that	 * are not valid in identifiers replaced by `_` (see `toCodemodeIdentifier`), and also as	 * `tools["<name>"](args)`. Globals are called as `<name>(args)` and must be identifiers, or	 * `<namespace>.<member>`, which groups them into a frozen namespace object.	 */	name: string;	/** Shown as a doc comment in {@link renderDeclarations}, and listed in `ALL_TOOLS` for tools. */	description?: string;	/** Schema of the single argument. Rendered as the parameter type; `unknown` when omitted. */	inputSchema?: CodemodeJsonSchema;	/** Schema of the resolved value. Rendered as the promise type; `unknown` when omitted. */	outputSchema?: CodemodeJsonSchema;	/** Globals only: `execute` receives all call arguments as an array instead of the first one. */	spread?: boolean;	/**	 * Globals only: TypeScript parameter list and return type for {@link renderDeclarations}, for	 * example `(type: string, id?: string): Promise<Model[]>`. Replaces the rendering from the schemas.	 */	signature?: string;	/**	 * `args` is whatever the script passed, after a JSON round trip. The return	 * value must be JSON-serializable; a thrown error surfaces in the script as	 * an `Error` with the same message.	 */	execute(args: unknown, context: CodemodeToolContext): Promise<unknown> | unknown;}

/** * One item of the script's output, in the order the script produced it: `text()` and `console.*` * produce text items, with `console: true` for `console.*`, and `image()` image items. `data` is base64. */export type CodemodeOutputItem =	| { type: "text"; text: string; console?: true }	| { type: "image"; data: string; mimeType: string };⋯ lược bớt dòng 50–81/** Keys the script changed with `store()`. Only successful executions report writes. */export interface CodemodeStoreWrites {	set: Record<string, unknown>;	/** Keys stored as `undefined`. */	delete: string[];}/** * `output` is kept for failed executions too, up to the failure. `exit()` completes with `value: undefined`. * `during`: in a {@link CodemodeSandboxBase.start} run that the script itself ended (it returned, threw, or exited), * the result being processed when it did. */export type CodemodeResult =	| {			ok: true;			value: unknown;			output: CodemodeOutputItem[];			calls: CodemodeCall[];			storeWrites: CodemodeStoreWrites;			during?: CodemodeDuring;	  }	| {			ok: false;			error: CodemodeError;			output: CodemodeOutputItem[];			calls: CodemodeCall[];			during?: CodemodeDuring;	  };

/** * Lark grammar for providers with grammar-constrained tool input. It only fixes the shape of the * options line; the options JSON and the code are checked by {@link parseCodemodeSource}. */export const CODEMODE_SOURCE_GRAMMAR = String.raw`start: options_source | plain_sourceoptions_source: OPTIONS_LINE NEWLINE SOURCEplain_source: SOURCEOPTIONS_LINE: /[ \t]*\/\/ @options:[^\r\n]*/NEWLINE: /\r?\n/SOURCE: /[\s\S]+/`;

/** Callbacks a launcher uses to report what its VM does. */export interface VmEvents {	/** A message from the VM. Validated here, so launchers can pass through anything they receive. */	message(message: unknown): void;	/** The VM failed or stopped outside the bridge, for example a worker exit or a remote error. */	failure(error: CodemodeError): void;}/** The host's handle on a running VM. */export interface VmChannel {	post(message: HostToWorkerMessage): void;	/** Requests VM shutdown. Called once; may resolve before a worker or remote VM actually exits. */	stop(): Promise<void>;}/** * Starts a VM for one execution. Rejections become `sandbox` errors with the rejection's message. * The VM may start reporting messages before the returned promise settles. */export type VmLauncher = (data: VmStartData, events: VmEvents) => VmChannel | Promise<VmChannel>;

export type WorkerToHostMessage =	| { type: "call"; id: number; target: "tool" | "global"; name: string; args: string | undefined }	| { type: "output"; item: CodemodeOutputItem }	/**	 * `writes` is a JSON array of `[key, json]` for `store()` and `[key]` for deletions. Deterministic mode: `during`	 * is the result the VM was processing when the script finished (0: its first run) and the calls issued by then.	 */	| { type: "done"; ok: true; value: string | undefined; writes: string; during?: CodemodeDuring }	| { type: "done"; ok: false; error: ScriptErrorJson; during?: CodemodeDuring }	/** The VM failed outside the script's control, for example a wasm trap. */	| { type: "crash"; message: string }	/** Deterministic mode, before the script runs: what the VM is, so a replay can refuse a different one. */	| { type: "started"; fingerprint: string }	/**	 * Deterministic mode, after the script waits again: having processed result `seq` (0: the script's first run), it	 * has issued `issued` calls in total.	 */	| { type: "idle"; seq: number; issued: number };export type HostToWorkerMessage =	/**	 * `payload` is the JSON result when `ok`, otherwise the error message. Deterministic mode: `seq` numbers the	 * results from 1 in the order the VM applies them, and the VM's clock reads `now` while it processes this one.	 */	{		type: "result";		id: number;		ok: boolean;		payload: string | undefined;		seq?: number;		now?: number;		/** Deterministic mode, `ok: false`: a JSON object whose properties the script's `Error` gets. */		properties?: string;	};

function workerLauncher(options: CodemodeSandboxOptions): VmLauncher {	return async (data, events) => {		let module: CodemodeWasmModule;		try {			module = await (options.wasm ?? loadQuickJSWasm());		} catch (error) {			throw new Error(`Failed to load QuickJS: ${errorMessage(error)}`);		}		const interrupt = new SharedArrayBuffer(4);		const workerData: WorkerData = { ...data, wasm: module, interrupt };		const releaseWorker = options.acquireWorker?.();		let worker: Worker;		try {			worker = new Worker(options.workerUrl ?? defaultWorkerUrl(), { workerData });		} catch (error) {			releaseWorker?.();			throw new Error(`Failed to start worker: ${errorMessage(error)}`);		}		if (releaseWorker) worker.once("exit", releaseWorker);⋯ lược bớt dòng 39–58		const stop = async (): Promise<void> => {			Atomics.store(new Int32Array(interrupt), 0, 1);			// A non-interruptible built-in can delay Bun's terminate() until it returns (#10748).			// Do not hold up the result while that worker exits.			void worker.terminate().catch(() => undefined);			// terminate() refs the worker internally; unref it after requesting termination.			worker.unref();		};

try {	// Called from the prelude with primitives only.	const bridge = vm.newFunction("bridge", (kind, a, b, c) => {		switch (kind.toString()) {			case "call":			case "global":				issued++;				post({					type: "call",					id: a.toNumber(),					target: kind.toString() === "call" ? "tool" : "global",					name: b.toString(),					args: c === undefined || c.isUndefined ? undefined : c.toString(),				});				break;			case "output":				post({					type: "output",					item:						a.toString() === "image"							? { type: "image", data: b.toString(), mimeType: c.toString() }							: a.toString() === "console"								? { type: "text", text: b.toString(), console: true }								: { type: "text", text: b.toString() },				});				break;⋯ lược bớt dòng 278–322	// The prefix shares the first line with the script so reported line numbers	// match the script as written.	let fn: JSValueHandle;	try {		fn = vm.evalCode(`(async (tools, console) => {${data.code}\n})`, "codemode.js");	} catch (error) {		if (!(error instanceof JSException)) throw error;		post({ type: "done", ok: false, error: describeException(error) });		return session;	}	vm.callFunction(run, api, fn).dispose();	fn.dispose();	drain();	if (clock) post({ type: "idle", seq: 0, issued });

private async handleCall(message: Extract<WorkerToHostMessage, { type: "call" }>): Promise<void> {	const { id, name } = message;	const isTool = message.target === "tool";	const record: CodemodeCall | undefined = isTool ? { name, status: "cancelled", durationMs: 0 } : undefined;	if (record) this.calls.push(record);	const pending: PendingCall = { record, startedAt: performance.now(), controller: new AbortController() };	this.pending.set(id, pending);	let status: CodemodeCallStatus;	let reply: HostToWorkerMessage;	try {		const tool = (isTool ? this.executors.tools : this.executors.globals).get(name);		if (!tool) throw new Error(`Unknown ${isTool ? "tool" : "global"} "${name}"`);		const args: unknown = message.args === undefined ? undefined : JSON.parse(message.args);		const value = await tool.execute(args, { signal: pending.controller.signal });		reply = { type: "result", id, ok: true, payload: value === undefined ? undefined : JSON.stringify(value) };		status = "ok";	} catch (error) {		reply = { type: "result", id, ok: false, payload: errorMessage(error) };		status = "error";	}	// Already cancelled by finish(): the record keeps "cancelled" and the	// VM is gone or going.	if (!this.pending.delete(id)) return;	if (record) {		record.status = status;		record.durationMs = performance.now() - pending.startedAt;	}	this.post(reply);}

// Freeze every object reachable from the built-in globals, plus the intrinsics that are only// reachable from instances (iterator and generator prototypes, %TypedArray%).//// Freezing alone breaks ordinary code through the "override mistake": a data property that is// read-only on a prototype cannot be assigned on an instance either, so// this.name = "MyError" in an Error subclass would throw. Commonly overridden properties// become accessors whose setter defines an own property on the instance instead.(function lockdown() {⋯ lược bớt dòng 59–93	for (const key of Reflect.ownKeys(globalThis)) {		const descriptor = Object.getOwnPropertyDescriptor(globalThis, key);		add(descriptor.value);		add(descriptor.get);		add(descriptor.set);		if ("value" in descriptor && descriptor.configurable) {			Object.defineProperty(globalThis, key, { writable: false, configurable: false });		}	}⋯ lược bớt dòng 103–116	while (queue.length > 0) {		const object = queue.pop();		add(Object.getPrototypeOf(object));		const descriptors = Object.getOwnPropertyDescriptors(object);		for (const key of Reflect.ownKeys(descriptors)) {			const descriptor = descriptors[key];			if ("value" in descriptor) {				add(descriptor.value);				if (					descriptor.writable &&					descriptor.configurable &&					(object === Object.prototype || OVERRIDABLE.has(key))				) {					allowOverride(object, key, descriptor.value, descriptor.enumerable);				}			} else {				add(descriptor.get);				add(descriptor.set);			}		}		Object.freeze(object);	}

function caller(kind, name, spread) {	return (...args) =>		new Promise((resolve, reject) => {			let json;			try {				json = serialize(spread ? args : args[0]);			} catch (error) {				reject(error);				return;			}			const id = nextId++;			pending.set(id, { resolve, reject });			bridge(kind, id, name, json);		});}const tools = Object.create(null);const allTools = [];for (const { name, jsName, description } of parse(toolsJson)) {	const fn = caller("call", name);	// The first tool wins when two names normalize to the same identifier.	if (!(jsName in tools)) {		tools[jsName] = fn;		allTools.push(Object.freeze({ name: jsName, description }));	}	if (!(name in tools)) tools[name] = fn;}Object.freeze(tools);Object.freeze(allTools);

const comparable = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, "");function guard(target, label, names, hint) {	return new Proxy(target, {		get(object, property, receiver) {			if (typeof property !== "string" || property in object || property in Object.prototype || property === "then" || property === "toJSON") {				return Reflect.get(object, property, receiver);			}			const wanted = comparable(property);			const exact = names.filter((name) => comparable(name) === wanted);			const close = exact.length > 0 ? exact : names.filter((name) => wanted && (comparable(name).includes(wanted) || wanted.includes(comparable(name))));			let message = label + "." + property + " does not exist.";			if (close.length > 0) message += " Did you mean " + close.slice(0, 5).map((name) => label + "." + name).join(", ") + "?";			else if (names.length <= 20) message += " Available: " + names.join(", ") + ".";			if (hint) message += " " + hint;			message += ' Check for a member with "' + property + '" in ' + label + ".";			throw new TypeErrorCtor(message);		},	});}const toolsProxy = guard(	tools,	"tools",	allTools.map((tool) => tool.name),	"ALL_TOOLS lists every tool; searchTools(query) finds tools by topic.",);

let outputChars = 0;let outputItems = 0;// Past the output limits the script fails: done() reports the error, so catching it does not// resume output, and the host ends the script.function output(kind, data, mimeType) {	if (finished) return;	outputChars += data.length;	outputItems++;	if (outputChars > ${MAX_OUTPUT_CHARS} || outputItems > ${MAX_OUTPUT_ITEMS}) {		const error = new RangeErrorCtor(			"script output exceeded the limit of ${MAX_OUTPUT_CHARS} characters or ${MAX_OUTPUT_ITEMS} text(), image(), and console calls. " +				"Print a summary instead, or write large data to a file with a tool.",		);		done(false, describeError(error));		throw error;	}	bridge("output", kind, data, mimeType);}

stalled() {	if (finished || pending.size > 0) return false;	done(		false,		stringify({			name: "Error",			message:				"The script is waiting on a promise that can never settle: no tool call is pending, and timers do not exist here.",		}),	);	return true;},

/** * Convert a JSON Schema to a TypeScript type expression: objects on one line (`{ a: string; b?: number; }`) with properties sorted by name, * or one property per line with `//` comments when a property has a description or constraints the * type cannot express (`// @integer @minimum 1 @default 20`); `Array<T>` for arrays. Local references * (`#/$defs/...`, `#/definitions/...`) resolve against `schema`; recursive and remote references * render as `unknown`. A result longer than `maxChars` is rendered again without the constraint tags, * and renders as `unknown` if it is still too long. */export function schemaToType(schema: CodemodeJsonSchema, options: { maxChars?: number } = {}): string {	const render = (tags: boolean) => toType(schema, { root: schema, resolving: new Set(), expansions: 0, tags });	const type = render(true);	if (options.maxChars === undefined || type.length <= options.maxChars) return type;	const untagged = render(false);	return untagged.length <= options.maxChars ? untagged : "unknown";}

/** * A tool's sample: the description followed by the tool's declaration. Used for tool * listings and `ALL_TOOLS` entries. */export function renderToolSample(	tool: Pick<CodemodeTool, "name" | "description" | "inputSchema" | "outputSchema">,	options: { inputMaxChars?: number } = {},): string {	const declaration = `declare const tools: { ${renderToolSignature(tool, options)} };`;	return `${tool.description?.trim() ?? ""}\n\ncodemode tool declaration:\n\`\`\`ts\n${declaration}\n\`\`\``;}

export async function startVm(options: StartVmOptions): Promise<VmSession> {	const { data, post } = options;	const maxStackSize = options.maxStackSize ?? MAX_STACK_SIZE;	const deterministic = data.deterministic;	const clock: VirtualClock | undefined = deterministic && {		creating: true,		startedAt: deterministic.startedAt,		now: deterministic.startedAt,		seed: deterministic.seed >>> 0,	};	const vm = await QuickJS.create({		wasm: options.wasm,		memoryLimit: data.memoryLimitBytes,		// Without a guard, deep recursion overflows the wasm stack and traps instead of throwing a		// catchable RangeError.		maxStackSize,		interruptHandler: options.shouldInterrupt,		wasi: clock ? deterministicWasi(clock) : discardOutput,		...(clock ? { timezoneOffset: 0, intrinsics: Intrinsics.ALL & ~Intrinsics.WEAK_REF } : {}),	});	if (clock) clock.creating = false;

const session: VmSession = {	deliver(message) {		if (disposed) return;		try {			if (!clock) {				apply(message);				return;			}			const { seq } = message;			if (seq === undefined || !Number.isInteger(seq) || seq < nextSeq || early.has(seq)) {				throw new Error(`Result ${message.id} has sequence number ${seq}, expected ${nextSeq} or later, once`);			}			early.set(seq, message);			for (let next = early.get(nextSeq); next !== undefined; next = early.get(nextSeq)) {				early.delete(nextSeq);				// Never backwards: a resumed host's clock may be behind the one that started the run.				if (next.now !== undefined && Number.isFinite(next.now)) clock.now = Math.max(clock.now, next.now);				current = nextSeq;				apply(next);				post({ type: "idle", seq: nextSeq, issued });				nextSeq++;			}		} catch (error) {			post(crashMessage(error));		}	},

* Problem: a VM on the calling thread blocks that thread while the script computes. In a Durable* Object that serves an agent session, a CPU-heavy script would stall every other request to the* session (including the user's abort) for seconds. Measured on Cloudflare (October 2026), a* script that computed for 10 seconds delayed the session's other requests by 10 seconds when it* ran in the session object or in a Dynamic Worker, but by about 50 ms when it ran in a Durable* Object of a separately deployed Worker.** Solution: the caller keeps the host role (`RemoteCodemodeSandbox`: tools, call records,* deadline, abort) and the remote side only runs the VM (`serveCodemodeRemote`, behind* `CodemodeSandboxDurableObject` in `@earendil-works/pi-codemode/cloudflare`).** Protocol, one RPC call per execution:**     client                                     remote*     remote.execute(request, exchange) ───────▶ starts the VM (in-thread, with interrupt budget)*                                      ◀─────── exchange([...outputs, call])   one call per tool call*     runs the tool, replies with result ──────▶ VM continues*                                      ◀─────── exchange([...outputs, done])   terminal, reply ignored*     execute() resolves ◀────────────────────── VM disposed

/** * The remote end of `RemoteCodemodeSandbox`: a Durable Object whose one RPC method runs a script's * VM and calls back into the client for every tool call. * * Deploy it as its own Worker and bind it from the Worker that runs your agent with `script_name`. * A separate Worker is what keeps scripts off the agent's thread: a class in the same Worker can * share an isolate, and therefore a thread, with the objects that call it. * * The object keeps no state between executions and never touches storage. Executions that reach * the same instance share its thread: they interleave while they wait on tools, and a script that * computes delays the others. Name instances per session (`getByName(sessionId)`) to keep one * session's scripts together, or per execution for full independence. * * Limits apply to every request, whatever the client asks for. Override the fields in a subclass: * *     export class CodemodeSandbox extends CodemodeSandboxDurableObject { *       protected maxInterruptBudget = 200_000; *     } */export class CodemodeSandboxDurableObject<Env = unknown> extends DurableObject<Env> {	/** Interrupt polls per execution; the client may only ask for less. See `InlineCodemodeSandboxOptions`. */	protected maxInterruptBudget: number = DEFAULT_INTERRUPT_BUDGET;	/** VM memory per execution; the client may only ask for less. */	protected maxMemoryLimitBytes: number = DEFAULT_REMOTE_MEMORY_LIMIT_BYTES;	/** Called by `RemoteCodemodeSandbox` over RPC. Resolves when the script has settled or was stopped. */	execute(request: CodemodeRemoteRequest, exchange: CodemodeRemoteExchange): Promise<void> {		return serveCodemodeRemote(request, exchange, {			wasm: quickjsWasm,			maxInterruptBudget: this.maxInterruptBudget,			maxMemoryLimitBytes: this.maxMemoryLimitBytes,		});	}}

export function createCodemodeToolDefinition(	options: CodemodeToolOptions = {},): ToolDefinition<typeof codemodeSchema, CodemodeToolDetails | undefined> {	return {		name: CODEMODE_TOOL_NAME,		label: CODEMODE_TOOL_NAME,		// Replaced with the declarations of the callable tools when the tool is activated.		description: createCodemodeDescription([], { models: options.models === true }),		promptSnippet: codemodeToolSystemPromptContribution.snippet,		promptGuidelines: [...codemodeToolSystemPromptContribution.guidelines],		parameters: codemodeSchema,		// Scripts must not start other scripts.		exposure: "model-only",		prepareLoadout: (loadout) => prepareCodemodeLoadout(loadout, options),		reachesTools: (input) => getScriptReach(input.code),		// Capable models write the script as raw text instead of a JSON-escaped string.		constrainedSampling: { type: "grammar", variants: { openai_lark: CODEMODE_SOURCE_GRAMMAR } },		// The sandbox (worker, QuickJS wasm) loads on the first call, not at startup.		execute: async (toolCallId, params, signal, onUpdate, ctx) =>			(await loadCodemodeExecutor()).executeCodemode(toolCallId, params, signal, onUpdate, ctx, options),		...codemodeRenderers,	};}

const DESCRIPTION_INTRO = `Run JavaScript that calls other tools. The input is raw JavaScript (not JSON, no code fence), run as an async function body in a QuickJS sandbox: top-level \`await\` and \`return\` work. No Node, file system, network, or timers.- \`await tools.<name>({ ...args })\` resolves to a string, or an object if the tool's declaration says so, and rejects with an Error on failure. A tool whose declaration returns an object resolves on failure too when it returned that object; check its fields. Calls still running when the script ends are cancelled.- Optional first line: \`// @options: {"max_output_tokens": 10000, "timeout_ms": 60000}\``;/** One line per global. The details live in {@link CODEMODE_DOCS_PATH}. */function describeGlobals(models: boolean): string {	const lines = [		"Globals:",		"- `text(value)`, `image(dataUrlOrImageBlock)`, `console.log(...)`, and top-level `return` add output; `exit()` ends the script. With several text items, each starts with a `==> text N/M <==` line, and `console` lines follow the other output in one `<console_output>` block. `image()` also saves the image to a temp file and the result names its path.",		"- `store(key, value)` and `load(key)` keep JSON values across codemode calls.",		"- `ALL_TOOLS`, `await searchTools(query, { limit?, namespace? })`, `await describeTool(name)`, `await describeNamespace(name)`: find unlisted tools, such as MCP tools.",	];	if (models) {		lines.push(`- \`models\`: classifiers and image generation. Read ${CODEMODE_DOCS_PATH} first.`);	}	return lines.join("\n");}

/** * Pick the tool sections that fit the budget, like OpenCode's catalog: in each round every group * (tools without a namespace first, then namespaces by name) places its cheapest remaining tool; a * group whose next tool does not fit drops out while the others continue. Every namespace is * represented before any namespace is complete. */function selectCatalog(groups: readonly CatalogGroup[], budget: number | undefined): Set<string> {	if (budget === undefined) return new Set(groups.flatMap((group) => group.entries.map((entry) => entry.name)));	const queues = groups.map((group) => [...group.entries].sort((a, b) => a.cost - b.cost));	const shown = new Set<string>();	let remaining = budget;	let active = queues.filter((queue) => queue.length > 0);	while (active.length > 0) {		active = active.filter((queue) => {			const next = queue[0];			if (next.cost > remaining) return false;			remaining -= next.cost;			shown.add(next.name);			queue.shift();			return queue.length > 0;		});	}	return shown;}

const callable = ctx ? getCodemodeCallableTools(ctx.tools) : [];// ALL_TOOLS entries carry the declaration.const guidelines = options.getToolGuidelines?.();const samples = new Map(	callable.map((tool) => [tool.name, renderToolSample(toCodemodeDeclaration(tool, guidelines?.get(tool.name)))]),);const sandboxTools: CodemodeTool[] = callable.map((tool) => ({	name: tool.name,	description: samples.get(tool.name),	execute: async (args, { signal: callSignal }) => {		const record: CodemodeNestedCall = {			id: `${toolCallId}/?`,			name: tool.name,			args: previewArgs(args),			status: "running",		};		calls.push(record);		publish();		const callStartedAt = performance.now();		// Only tools from ctx.tools are callable, so ctx is set here.		if (!ctx) throw new Error("Tool calls need a session");		const outcome = await ctx.executeTool(tool.name, args, { signal: callSignal });		record.id = outcome.toolCall.id;		record.durationMs = performance.now() - callStartedAt;		if (outcome.isError) {			record.status = callSignal.aborted ? "cancelled" : "error";			record.error = truncateText(textOf(outcome.result) || `Tool "${tool.name}" failed`, ERROR_PREVIEW_CHARS);		} else {			record.status = "ok";		}		publish();		return toScriptValue(tool, outcome);	},}));

/** * The value a script receives for a nested call: a tool that declares * `outputSchema` resolves to its `structuredContent`, also for error results that carry one (such * as MCP results with `isError`); any other tool resolves to its text content. Other failures * reject with the tool's error text. */function toScriptValue(tool: AgentTool<any>, outcome: AgentToolCallOutcome): unknown {	const { result } = outcome;	if (tool.outputSchema && result.structuredContent !== undefined) return result.structuredContent;	const text = textOf(result);	if (outcome.isError) throw new Error(text || `Tool "${tool.name}" failed`);	return text;}

// The wait for a worker counts toward the script's deadline.const deadline = sourceOptions.timeoutMs ?? Number.POSITIVE_INFINITY;const waitStartedAt = performance.now();const admission = await reserveCodemodeWorker(signal, Math.min(deadline, CODEMODE_WORKER_WAIT_MS));const waitedMs = performance.now() - waitStartedAt;⋯ lược bớt dòng 559–578let reserved = true;let sandbox: CodemodeSandbox | undefined;let result: CodemodeResult;try {	sandbox = new CodemodeSandbox({		tools: sandboxTools,		globals: [			...createDiscoveryGlobals(callable, samples, options),			...(options.models && ctx				? createModelGlobals(ctx.modelRegistry, toolCallId, calls, publish, addModelUsage, addGeneratedImages)				: []),		],		timeoutMs: Math.max(1, Math.round(deadline - waitedMs)),		memoryLimitBytes: CODEMODE_MEMORY_LIMIT_BYTES,		wasm: loadQuickJSWasm(getQuickJSWasmPath()),		workerUrl: getCodemodeWorkerSpecifier(),		acquireWorker: () => {			if (!reserved) throw new Error("The script already settled");			// From here the sandbox releases the slot when the worker actually exits.			reserved = false;			return releaseCodemodeWorker;		},	});	const store = ctx ? readCodemodeStore(ctx.sessionManager.getBranch()) : {};	result = await sandbox.execute(code, { signal, store });} finally {	await sandbox?.close();	if (reserved) {		reserved = false;		releaseCodemodeWorker();	}}

/** Values of `load()`: the `codemode-store` entries on the branch, applied from the root. */export function readCodemodeStore(branch: readonly SessionEntry[]): Record<string, unknown> {	const store = new Map<string, unknown>();	for (const entry of branch) {		if (entry.type !== "custom" || entry.customType !== CODEMODE_STORE_ENTRY_TYPE || !isStoreEntryData(entry.data)) {			continue;		}		for (const key of entry.data.delete) store.delete(key);		for (const [key, value] of Object.entries(entry.data.set)) store.set(key, value);	}	return Object.fromEntries(store);}

// Calls still marked running were cut off by the script ending, a timeout, or an abort.for (const call of calls) {	if (call.status === "running") call.status = "cancelled";}const scriptOutput = [...result.output];if (result.ok) {	const { set, delete: deleted } = result.storeWrites;	if (Object.keys(set).length > 0 || deleted.length > 0) {		options.appendEntry?.(CODEMODE_STORE_ENTRY_TYPE, { set, delete: deleted });	}	// pi extension: a returned value is appended like text().	if (result.value !== undefined) scriptOutput.push({ type: "text", text: valueText(result.value) });}const items = formatOutput(scriptOutput);if (!result.ok) items.push({ type: "text", text: `Script error:\n${formatError(result, calls)}` });⋯ lược bớt dòng 628–634const truncated = await truncateOutput(	joinAdjacentText(items),	sourceOptions.maxOutputTokens ?? DEFAULT_MAX_OUTPUT_TOKENS,);// After truncation, which joins the text items and moves images after them, so each path stays// next to its image and is never cut.const output = joinAdjacentText(await saveImages(truncated.items));const wallTime = ((performance.now() - startedAt) / 1000).toFixed(1);const header = `${result.ok ? "Script completed" : "Script failed"}\nWall time ${wallTime} seconds\nOutput:\n`;const details = snapshot();if (truncated.fullOutputPath) details.fullOutputPath = truncated.fullOutputPath;return {	content: [{ type: "text", text: header }, ...output],	details,	...(modelUsage ? { usage: modelUsage } : {}),	...(result.ok ? {} : { isError: true }),};

/** * Run a call that the tool call `parentToolCallId` made through `ctx.executeTool()`. It goes * through the agent's tool pipeline with the session's hooks, against the callable tools. */private async _executeNestedToolCall(	parentToolCallId: string,	name: string,	args: unknown,	options: ExecuteToolOptions,): Promise<AgentToolCallOutcome> {	this._nestedToolCalls ??= new NestedToolCallRunner({		getTools: () => this._getCallableTools(),		isSequential: () => this.agent.toolExecution === "sequential",		runToolCall: (toolCall, parentId, signal, onUpdate) => {			const assistantMessage = this._findLastAssistantMessage();			if (!assistantMessage) {				return Promise.resolve({					toolCall,					result: { content: [{ type: "text", text: "No assistant message issued this call" }], details: {} },					isError: true,				});			}			return runToolCall(toolCall, {				tools: this._getCallableTools(),				assistantMessage,				context: { messages: this.agent.state.messages, tools: this.agent.state.tools },				beforeToolCall: (context) => this._beforeToolCall(context, parentId),				afterToolCall: (context) => this._afterToolCall(context, parentId),				signal,				onUpdate,			});		},		emit: async (event) => {			await this._extensionRunner.emit(event);			this._emit(event);		},	});	return this._nestedToolCalls.execute(parentToolCallId, name, args, options);}

/** * Limits of the nested-call record on a tool result: arguments * over the per-call or total size are omitted, calls beyond the count are dropped, and the record * is marked incomplete when any of that happens. */export const NESTED_CALL_LIMITS = {	maxCalls: 256,	maxArgumentBytesPerCall: 8 * 1024,	maxArgumentBytesTotal: 32 * 1024,	maxErrorChars: 500,} as const;

// Record the calls a tool made through ctx.executeTool() and their usage on its result message.if (this._nestedToolCalls) {	if (event.type === "message_start" && event.message.role === "toolResult") {		const message = event.message;		const summary = this._nestedToolCalls.takeRecord(message.toolCallId);		if (summary?.calls) message.nestedCalls = summary.calls;		if (summary?.usage) {			message.usage = message.usage ? combineUsage(message.usage, summary.usage) : summary.usage;		}	} else if (event.type === "agent_end") {		this._nestedToolCalls.clear();	}}

/** A tool call that another tool made while it ran, for example from a codemode script. */export interface NestedToolCallRecord {	id: string;	name: string;	/** Omitted when over the size limits; `argumentsBytes` then gives their size. */	arguments?: JsonObject;	/** UTF-8 size of the arguments as JSON, set when `arguments` is omitted. */	argumentsBytes?: number;	/** `unfinished`: the call was still running when the calling tool finished. */	status: "ok" | "error" | "unfinished";	durationMs?: number;	/** Error text, truncated. */	error?: string;}/** Bounded record of the nested calls a tool made. Results are not recorded. */export interface NestedToolCalls {	calls: NestedToolCallRecord[];	/** False when calls were dropped, arguments omitted, or calls had not finished. */	complete: boolean;}

export interface McpTransportSendOptions {	/**	 * Aborted once the sender no longer waits for a reply (the request was cancelled, timed out, answered,	 * or the client closed). A transport must not dispatch the message after that, for example when	 * retrying it after an authorization refresh. It does not undo a message already dispatched.	 */	signal?: AbortSignal;}export interface McpTransport {	start(): Promise<void>;	send(message: JsonRpcMessage, options?: McpTransportSendOptions): Promise<void>;	close(): Promise<void>;	onMessage(listener: McpTransportMessageListener): () => void;	onError(listener: McpTransportErrorListener): () => void;	onClose(listener: McpTransportCloseListener): () => void;	setProtocolVersion?(version: string): void;}

const id = this.nextRequestId++;const progressToken = options.onProgress ? id : undefined;const requestParams =	progressToken === undefined		? params		: { ...params, _meta: { ...(isObject(params?._meta) ? params._meta : {}), progressToken } };const message: JsonRpcRequest = {	jsonrpc: "2.0",	id,	method,	...(requestParams === undefined ? {} : { params: requestParams }),};return new Promise<unknown>((resolve, reject) => {	const entry: PendingRequest = {		resolve,		reject,		timeoutMs: options.timeoutMs ?? this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,		timer: undefined,		signal: options.signal,		// The spec forbids cancelling `initialize`.		onAbort: () =>			this.cancelPending(				id,				new McpAbortError(),				method !== "initialize",				String(options.signal?.reason ?? "Aborted"),			),		sendController: new AbortController(),		cancellable: method !== "initialize",		onProgress: options.onProgress,		progressToken,	};	this.pending.set(id, entry);	if (progressToken !== undefined) this.progressRequests.set(progressToken, id);	options.signal?.addEventListener("abort", entry.onAbort, { once: true });	this.armTimeout(id, entry);	transport		.send(message, { signal: entry.sendController.signal })		.catch((error) => this.cancelPending(id, error, false));});

async close(): Promise<void> {	if (this.closed) return;	this.closed = true;	const child = this.child;	if (!child) {		this.emitClose();		return;	}	if (child.exitCode !== null || child.signalCode !== null) {		child.stdin?.end();		return;	}	// Shutdown per the spec: close stdin and let the server exit, then SIGTERM, then SIGKILL.	const closeTimeoutMs = this.options.closeTimeoutMs ?? DEFAULT_CLOSE_TIMEOUT_MS;	await new Promise<void>((resolve) => {		const timers: ReturnType<typeof setTimeout>[] = [];		child.once("close", () => {			for (const timer of timers) clearTimeout(timer);			// Children of the server that ignored stdin closing would otherwise outlive it.			killProcessTree(child, "SIGTERM");			resolve();		});		const grace = Math.min(STDIN_CLOSE_GRACE_MS, closeTimeoutMs);		timers.push(setTimeout(() => killProcessTree(child, "SIGTERM"), grace));		timers.push(setTimeout(() => killProcessTree(child, "SIGKILL"), grace + closeTimeoutMs));		child.stdin?.end();	});}

async send(message: JsonRpcMessage, { signal }: McpTransportSendOptions = {}): Promise<void> {	if (!this.started || this.closed) throw new McpConnectionClosedError();	const response = await this.authorizedFetch(		"POST",		{			headers: { accept: "application/json, text/event-stream", "content-type": "application/json" },			body: JSON.stringify(message),		},		signal,	);	await this.checkResponse(response);	this.captureSession(response);	if (!isJsonRpcRequest(message)) {		// Notifications and responses are acknowledged with 202 and carry no reply; ignore any body.		await discard(response);		// The server-to-client stream may only open once the session is initialized.		if ("method" in message && message.method === "notifications/initialized") this.startGetStream();		return;	}	if (response.status === 202 || response.status === 204) {		throw new McpHttpError(response.status, `MCP server accepted request ${message.method} without a response`);	}	const type = contentType(response);	if (type === "application/json") {		const body: unknown = await response.json();		for (const item of Array.isArray(body) ? body : [body]) this.emitMessage(parseJsonRpcMessage(item));		return;	}	if (type === "text/event-stream" && response.body) {		void this.consumeResponseStream(response.body, message.id);		return;	}	await discard(response);	throw new McpHttpError(response.status, `Unsupported MCP response content type: ${type ?? "missing"}`);}

export async function discoverAuthorizationServerMetadata(	authorizationServerUrl: string | URL,	options: { fetch?: McpFetch; protocolVersion?: string; skipIssuerValidation?: boolean; signal?: AbortSignal } = {},): Promise<AuthorizationServerMetadata | undefined> {	const fetch = options.fetch ?? globalThis.fetch;	for (const { url } of buildAuthorizationServerDiscoveryUrls(authorizationServerUrl)) {		const response = await fetchMetadata(			url,			fetch,			options.protocolVersion ?? LATEST_PROTOCOL_VERSION,			options.signal,		);		if (!response.ok) {			discard(response);			if (isDiscoveryMiss(response.status)) continue;			throw new Error(`HTTP ${response.status} loading authorization server metadata from ${url}`);		}		const metadata = parseAuthorizationServerMetadata(await response.json());		if (!options.skipIssuerValidation) {			const expected = String(authorizationServerUrl);			// URL parsing adds a trailing slash to bare origins, so compare without one on either side.			const trim = (value: string) => (value.endsWith("/") ? value.slice(0, -1) : value);			if (trim(metadata.issuer) !== trim(expected)) throw new OAuthIssuerMismatchError(expected, metadata.issuer);		}		return metadata;	}	return undefined;}

const stored = await provider.clientInformation();const clientDocument = stored ? undefined : provider.clientMetadataDocument?.(metadata);if (clientDocument) {	const url = new URL(clientDocument.url);	if (url.protocol !== "https:" || url.pathname === "/") throw new Error("Invalid OAuth client metadata URL");}let client = stored ?? (clientDocument && { client_id: clientDocument.url });if (!client) {	if (options.authorizationCode) throw new Error("OAuth client information is missing during code exchange");	if (!provider.saveClientInformation) throw new Error("OAuth client information cannot be persisted");	client = await registerClient(discovered.authorizationServerUrl, {		metadata,		clientMetadata: provider.clientMetadata,		scope,		fetch: options.fetch,		signal: options.signal,	});	await provider.saveClientInformation(client);}

if (options.authorizationCode) {	// RFC 9207: never send a code from another authorization server to this one. Without metadata there	// is no issuer to compare with, so any `iss` is rejected.	const iss = options.iss;	if (iss !== undefined || metadata?.authorization_response_iss_parameter_supported) {		if (iss !== metadata?.issuer) throw new OAuthIssuerMismatchError(metadata?.issuer, iss);	}	const tokens = await exchangeAuthorizationCode(discovered.authorizationServerUrl, {		...tokenOptions,		code: options.authorizationCode,		codeVerifier: await provider.codeVerifier(),		redirectUrl,	});	// A response without `scope` grants the requested scope (RFC 6749 §5.1). Recorded so a step-up can	// keep it. Callers pass the options of the authorization request, so `scope` is what was requested.	await provider.saveTokens(withScope(tokens, scope));	return "AUTHORIZED";

/** * Keys of a server's state: by name and URL, so servers sharing a URL keep separate accounts, and the * legacy key by URL alone, written by older versions. */function storeKeys(name: string, serverUrl: string): { key: string; legacyKey: string } {	const legacyKey = String(new URL(serverUrl));	return { key: `${mcpNamespace(name)}|${legacyKey}`, legacyKey };}

/** * pi's Client ID Metadata Document, for `clientRegistration: "cimd"`, chosen like Codex chooses its own. * The configuration ensures the default callback path. Without the `iss` parameter in authorization * responses (RFC 9207), the redirect URI and the document are specific to the MCP server, so a response * cannot be mixed up with one from another authorization server (RFC 9700 section 4.4.2.2). */function clientMetadataDocument(	serverUrl: string,	redirectUrl: string,	metadata: AuthorizationServerMetadata | undefined,): OAuthClientMetadataDocument {	if (		!metadata?.client_id_metadata_document_supported ||		!metadata.token_endpoint_auth_methods_supported?.includes("none")	) {		throw new Error(			'The authorization server does not support Client ID Metadata Documents for public clients; remove oauth.clientRegistration "cimd"',		);	}	if (metadata.authorization_response_iss_parameter_supported) {		return { url: `${CLIENT_METADATA_BASE_URL}/client.json`, redirectUrl };	}	const id = callbackId(serverUrl);	const redirect = new URL(redirectUrl);	redirect.pathname = `${CALLBACK_PATH}/${id}`;	return { url: `${CLIENT_METADATA_BASE_URL}/${id}/client.json`, redirectUrl: redirect.href };}

for (const [name, value] of Object.entries(parsed.mcpServers ?? {})) {	if (scope === "project" && isRecord(value) && isOverride(value)) {		const base = servers.get(name);		const extra = Object.keys(value).filter((key) => !OVERRIDE_KEYS.includes(key));		if (!base) {			errors.push(`${path}: server "${name}" needs "command" or "url", or a global server to override`);		} else if (extra.length > 0) {			errors.push(`${path}: server "${name}": an override can only set ${OVERRIDE_KEYS.join(", ")}`);		} else {			const config = validateMcpServerConfig(name, { ...base.config, ...value });			if (typeof config === "string") errors.push(`${path}: ${config}`);			else servers.set(name, { ...base, config, override: path });		}		continue;	}

/** * - `codemode`: tools are callable from codemode scripts but neither declared to the model nor *   listed in the codemode description, which lists only the server's namespace. Scripts find them *   with `searchTools()`. `codemode-deferred` is accepted as an alias. * - `deferred`: not declared to the model until the `tool_search` tool loads them; the model then *   calls them directly. Does not need codemode. * - `direct`: tools are declared to the model like any other tool (and callable from codemode). * - `hidden`: tools are registered but unreachable. */export type McpExposure = "codemode" | "deferred" | "direct" | "hidden";

/** * `mcp__<server>__<tool>`, sanitized and shortened with a hash suffix when too long. Like Codex, * everything but `[A-Za-z0-9_]` becomes `_`, so the name is also the identifier codemode scripts * call it by. `isTaken` reports names used by a different MCP tool: sanitizing can map two tools to * one name (`a-b` and `a_b`), which then get the hash suffix. */export function createMcpToolName(	server: string,	tool: string,	isTaken: (name: string) => boolean = () => false,): string {	const name = `mcp__${server}__${tool}`.replace(/[^A-Za-z0-9_]/g, "_");	if (name.length <= MAX_TOOL_NAME_LENGTH && !isTaken(name)) return name;	const hash = createHash("sha256").update(`${server}\0${tool}`).digest("hex").slice(0, 8);	return `${name.slice(0, MAX_TOOL_NAME_LENGTH - hash.length - 1)}_${hash}`;}

const registerTools = (connection: McpServerConnection) => {	const server = connection.entry.name;	const entry = findServer(server)?.entry ?? connection.entry;	const description = entry.config.description?.trim();	const namespace = {		name: mcpNamespace(server),		// `describeNamespace("docs")` finds `mcp__docs`.		aliases: [server],		...(description ? { description } : {}),		...(connection.instructions ? { instructions: connection.instructions } : {}),	};⋯ lược bớt dòng 398–417	for (const tool of connection.tools) {		const definition = createMcpToolDefinition({			server,			tool,			name: assignName(tool.name, `${server}\0${tool.name}`),			exposure: getMcpToolExposure(entry.config, tool.name),			namespace,⋯ lược bớt dòng 425–442		definitions.set(definition.name, definition);		pi.registerTool(definition);	}	serverTools.set(server, current);	// Tools cannot be unregistered, so tools the server dropped are re-registered as hidden. When	// the server offers them again they are registered with their configured exposure above.	for (const name of previous) {		const definition = definitions.get(name);		if (!current.has(name) && definition) pi.registerTool({ ...definition, exposure: "hidden" });	}

/** Convert an MCP result. `isError` results become error results that keep the structured result. */export async function convertMcpResult(	server: string,	tool: string,	result: CallToolResult,	options: ConvertMcpResultOptions = {},): Promise<AgentToolResult<McpToolDetails>> {	// Without content blocks, toLlmContent falls back to the structured content as JSON.	const converted: (TextContent | ImageContent)[] =		result.content.length > 0 ? await toModelContent(server, result.content, options) : toLlmContent(result);	if (result.isError && textOf(converted) === "") {		converted.push({ type: "text", text: `MCP tool ${server}/${tool} returned an error` });	}	const { content, fullOutputPath } = await limitMcpContent(converted, options.saveOutput);	const { _meta: _ignored, ...scriptResult } = result;	return {		content,		details: { server, tool, ...(fullOutputPath ? { fullOutputPath } : {}) },		structuredContent: scriptResult as unknown as JsonValue,		...(result.isError ? { isError: true } : {}),	};}

// A tool that reaches other tools (`reachesTools`) waits for the servers it may reach, so their// tools are registered before it runs: a codemode script for the servers it names, or for every// server when it searches or enumerates tools, and tool_search for every server. The resource// tools reach every server, so they wait for all of them. Direct MCP calls wait only for their// own server, including a reconnect still closing its old transport.pi.on("tool_call", async (event, ctx) => {	const tool = pi.getAllTools().find((candidate) => candidate.name === event.toolName);	if (!tool) return;	// Readiness can be pending while the display state is still connected: reconnect first	// closes the old transport, then opens a new one. Settled promises return immediately.	const readyServers = servers.filter((server) => isEnabled(server) && server.ready);	if (readyServers.length === 0) return;	let waiting: McpServer[] = [];	const reach = tool.reachesTools?.(event.input);	if (reach !== undefined) {		waiting = readyServers.filter((server) => reachesServer(reach, server.entry.name));	} else if (RESOURCE_TOOL_NAMES.has(tool.name)) {		waiting = readyServers;	} else {		const owner = toolOwners.get(event.toolName)?.split("\0", 1)[0];		waiting = readyServers.filter((server) => server.entry.name === owner);	}	await waitForServers(waiting, ctx.signal);});

private async connectOnce(): Promise<McpClient> {	const client = new McpClient({		name: "pi",		version: VERSION,		requestTimeoutMs: this.timeoutMs,		roots: [{ uri: pathToFileURL(this.cwd).href, name: basename(this.cwd) }],	});⋯ lược bớt dòng 366–376	try {		transport = this.createTransport(this.entry, this.cwd, this.authProvider);		await client.connect(transport);		client.onNotification("notifications/tools/list_changed", () => {			void this.refreshTools(client);		});		const stdio = transport instanceof StdioTransport ? transport : undefined;		client.onClose(() => this.handleClientClose(client, stdio));		// Servers without the tools capability (prompts or resources only) do not answer tools/list.		const tools = client.serverCapabilities?.tools ? await client.listTools() : [];		if (this.closed) throw new Error("shut down while connecting");		if (client.connectionState !== "connected") throw new Error("connection closed during setup");		this.client = client;		this.tools = tools;		this.hasResources = client.serverCapabilities?.resources !== undefined;		this.instructions = client.instructions?.trim() || undefined;		this.state = "connected";		this.error = undefined;		this.onTools(this);		this.changed();		return client;

/** * Search text of a tool: the name, the name with `_` * as spaces, the description, schema descriptions and property names, and the namespace with its * description and instructions. */export function createToolSearchDocument(	tool: Pick<ToolInfo, "name" | "description" | "parameters">,	namespace?: ToolNamespace,): ToolSearchDocument {	const parts = [tool.name, tool.name.replaceAll("_", " "), tool.description];	schemaText(tool.parameters, parts);	if (namespace) parts.push(namespace.name, namespace.description ?? "", namespace.instructions ?? "");	return { name: tool.name, text: parts.filter((part) => part.trim()).join(" ") };}

/** Okapi BM25 with the usual parameters. Ties keep document order. */export class Bm25Ranker implements ToolRanker {	private readonly k1: number;	private readonly b: number;	constructor(options: { k1?: number; b?: number } = {}) {		this.k1 = options.k1 ?? 1.2;		this.b = options.b ?? 0.75;	}	rank(query: string, documents: readonly ToolSearchDocument[], limit: number): ToolSearchMatch[] {		const queryTerms = [...new Set(tokenize(query))];		if (queryTerms.length === 0 || documents.length === 0 || limit <= 0) return [];		const termCounts = documents.map((document) => {			const counts = new Map<string, number>();			for (const term of tokenize(document.text)) counts.set(term, (counts.get(term) ?? 0) + 1);			return counts;		});		const lengths = termCounts.map((counts) => [...counts.values()].reduce((sum, count) => sum + count, 0));		const averageLength = lengths.reduce((sum, length) => sum + length, 0) / documents.length || 1;		const idf = new Map(			queryTerms.map((term) => {				const frequency = termCounts.filter((counts) => counts.has(term)).length;				return [term, Math.log(1 + (documents.length - frequency + 0.5) / (frequency + 0.5))] as const;			}),		);		const matches: ToolSearchMatch[] = [];		documents.forEach((document, index) => {			let score = 0;			for (const term of queryTerms) {				const count = termCounts[index].get(term);				if (!count) continue;				const norm = this.k1 * (1 - this.b + (this.b * lengths[index]) / averageLength);				score += (idf.get(term) ?? 0) * ((count * (this.k1 + 1)) / (count + norm));			}			if (score > 0) matches.push({ name: document.name, score });		});		return matches.sort((a, b) => b.score - a.score).slice(0, limit);	}}