@tshu-w/pi-agents 0.0.0-stage → 0.1.0

package/src/host/client.mjs

@@ -0,0 +1,139 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:fs';
+import { open, readdir, stat, unlink } from 'node:fs/promises';
+import net from 'node:net';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setTimeout as delay } from 'node:timers/promises';
+import { FRAME, frame, json, readFrames } from './frames.mjs';
+import { prepareDirectory } from '../roots/paths.mjs';
+
+const HOST = fileURLToPath(new URL('../../bin/host.mjs', import.meta.url));
+const START_TIMEOUT_MS = 10000;
+// Undo the terminal modes, progress, and program status Pi may have set, so the shell gets a plain terminal back.
+const RESET = '\x1b[<u\x1b[>4;0m\x1b[?2004l\x1b[?1000l\x1b[?1002l\x1b[?1003l\x1b[?1006l\x1b[?1004l\x1b[?2031l\x1b[?25h\x1b[0m\x1b]7501;state=clear\x1b\\\x1b]9;4;0\x07';
+const ALT_SCREEN = /\x1b\[\?1049([hl])/g;
+// Splits terminal input into key sequences: CSI and SS3 sequences, Alt+key, or a single character.
+const KEYS = /\x1b\[[0-?]*[ -/]*[@-~]|\x1bO[\s\S]|\x1b?[\s\S]/g;
+
+function hostStatus(path) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect(path);
+    socket.setTimeout(1000, () => socket.destroy(Object.assign(new Error('Host status timed out'), { code: 'ETIMEDOUT' })));
+    socket.on('error', reject);
+    socket.on('close', () => reject(Object.assign(new Error('Host closed without a status'), { code: 'ECONNRESET' })));
+    socket.on('connect', () => socket.write(frame(FRAME.status)));
+    readFrames(socket, (type, body) => { if (type === FRAME.status) { resolve(json(body)); socket.destroy(); } });
+  });
+}
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true; }
+  catch (error) { return error.code !== 'ESRCH'; }
+}
+
+/** Status of every running host; removes sockets left by hosts that died. */
+export async function listHosts(paths) {
+  let names;
+  try { names = await readdir(paths.runtime); }
+  catch (error) { if (error.code === 'ENOENT') return []; throw error; }
+  const hosts = [];
+  await Promise.all(names.map(async name => {
+    const match = /^h-(\d+)\.sock$/.exec(name);
+    if (!match) return;
+    const path = join(paths.runtime, name);
+    try { hosts.push({ ...await hostStatus(path), socket: path }); }
+    catch (error) {
+      if (['ECONNREFUSED', 'ENOENT'].includes(error.code) && !alive(Number(match[1]))) await unlink(path).catch(() => {});
+    }
+  }));
+  return hosts;
+}
+
+/**
+ * Starts a detached host running `pi args` in `cwd` and resolves to its socket once it accepts connections.
+ * With `waitForTerminal`, Pi starts when the first terminal attaches.
+ */
+export async function startHost(paths, { pi, args, cwd, cols = 120, rows = 40, env = process.env, waitForTerminal = false }) {
+  // spawn reports a missing cwd as ENOENT, which callers would mistake for a missing socket.
+  if (!(await stat(cwd).catch(() => undefined))?.isDirectory()) {
+    throw Object.assign(new Error(`Working directory ${cwd} does not exist`), { code: 'INVALID_CWD' });
+  }
+  await prepareDirectory(paths.runtime);
+  await prepareDirectory(paths.state);
+  const logPath = paths.hostLog;
+  const log = await open(logPath, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW, 0o600);
+  let child, failure;
+  try {
+    child = spawn(process.execPath, [HOST], {
+      cwd, detached: true, stdio: ['ignore', log.fd, log.fd],
+      env: { ...env, PI_AGENTS_HOST_CONFIG: JSON.stringify({ pi, args, cwd, cols, rows, waitForTerminal }) },
+    });
+    // A spawn error, such as a missing cwd, is emitted before the log closes.
+    child.on('error', error => { failure = error; });
+    child.once('exit', code => { failure ??= new Error(`Host exited (${code}). See ${logPath}`); });
+  } finally { await log.close(); }
+  child.unref();
+  const socket = paths.host(child.pid);
+  const deadline = performance.now() + START_TIMEOUT_MS;
+  for (;;) {
+    if (failure) throw failure;
+    try { await hostStatus(socket); return socket; }
+    catch (error) { if (!['ENOENT', 'ECONNREFUSED'].includes(error.code)) throw error; }
+    if (performance.now() > deadline) throw new Error(`Host did not start. See ${logPath}`);
+    await delay(25);
+  }
+}
+
+/**
+ * Attaches this process's terminal to a host until the host detaches it or Pi exits.
+ * The detach key detaches here, before Pi sees it, so it works whatever Pi shows.
+ * Resolves to { reason: 'detach' | 'takeover' | 'exited' | 'closed', session }.
+ */
+export function attach(socketPath, { isDetach, stdin = process.stdin, stdout = process.stdout }) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect(socketPath);
+    const size = () => ({ cols: stdout.columns, rows: stdout.rows });
+    const onResize = () => socket.write(frame(FRAME.resize, size()));
+    const onInput = data => {
+      // The workbench's stdin is decoded as UTF-8; latin1 keeps a Buffer's bytes.
+      const encoding = typeof data === 'string' ? 'utf8' : 'latin1';
+      const keys = data.toString(encoding).match(KEYS) ?? [];
+      const at = keys.findIndex(isDetach);
+      if (at < 0) return socket.write(frame(FRAME.data, data));
+      if (at > 0) socket.write(frame(FRAME.data, Buffer.from(keys.slice(0, at).join(''), encoding)));
+      socket.write(frame(FRAME.detached));
+    };
+    let result, connected = false, altScreen = false;
+    function finish() {
+      stdout.off('resize', onResize);
+      stdin.off('data', onInput);
+      if (connected) {
+        stdin.setRawMode(false);
+        stdin.pause();
+        // An exiting Pi restores the terminal itself.
+        // Leaving the alternate screen returns the cursor to the line below the command; otherwise it ends a line.
+        if (result?.reason !== 'exited') stdout.write(altScreen ? `\x1b[?1049l${RESET}` : `${RESET}\r\n`);
+      }
+      resolve(result ?? { reason: 'closed' });
+    }
+    socket.on('connect', () => {
+      connected = true;
+      stdin.setRawMode(true);
+      stdin.resume();
+      stdin.on('data', onInput);
+      stdout.on('resize', onResize);
+      socket.write(frame(FRAME.attach, size()));
+    });
+    readFrames(socket, (type, body) => {
+      if (type === FRAME.data) {
+        for (const [, mode] of body.toString('latin1').matchAll(ALT_SCREEN)) altScreen = mode === 'h';
+        stdout.write(body);
+      }
+      else if (type === FRAME.detached) result = { ...json(body) };
+      else if (type === FRAME.exited) result = { reason: 'exited', ...json(body) };
+    });
+    socket.on('error', error => { if (!connected) reject(error); });
+    socket.on('close', finish);
+  });
+}

package/src/host/extension.ts

@@ -0,0 +1,74 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import net from "node:net";
+import { treeMetadata } from "../agents/registry.ts";
+import { FRAME, frame, json, readFrames } from "./frames.mjs";
+
+const IDLE_EXIT_MS = 5 * 60_000;
+
+// Only the host's own child runs in it; children of Pi inherit the variables but have another parent.
+// They stay in the environment so a Pi that replaces itself with execve finds its host again.
+const hostSocket = process.env.PI_AGENTS_HOST && process.env.PI_AGENTS_HOST_PID === String(process.ppid) ? process.env.PI_AGENTS_HOST : undefined;
+
+export interface Host {
+	socket: string;
+	attached(): boolean;
+	onChange(listener: () => void): void;
+}
+
+/**
+ * Connects Pi to the host it runs in: reports the current Session, detaches on request,
+ * disables suspend, and exits after the tree has been idle and detached for a while.
+ * Returns the host, if Pi runs in one.
+ */
+export function hostExtension(pi: ExtensionAPI, { treeIdle }: { treeIdle: () => boolean }): Host | undefined {
+	if (!hostSocket) return;
+	const listeners: Array<() => void> = [];
+
+	let ctx: ExtensionContext | undefined;
+	let attached = true;
+	let idleSince: number | undefined;
+	let socket: net.Socket | undefined;
+	const connect = (path: string): net.Socket => {
+		const connection = net.connect(path);
+		connection.on("error", () => {});
+		connection.unref();
+		readFrames(connection, (type: number, body: Buffer) => {
+			if (type !== FRAME.control || json(body).type !== "attached" || json(body).attached === attached) return;
+			attached = json(body).attached;
+			for (const listener of listeners) listener();
+		});
+		return connection;
+	};
+	const send = (message: object): void => { socket?.write(frame(FRAME.control, message as never)); };
+	const report = () => {
+		if (!ctx) return;
+		const file = ctx.sessionManager.getSessionFile();
+		send({ type: "session", session: { id: ctx.sessionManager.getSessionId(), name: pi.getSessionName(), file } });
+	};
+
+	// Pi suspends by stopping its process group; a host has no shell to resume it, so resume at once.
+	process.on("SIGTSTP", () => process.kill(process.pid, "SIGCONT"));
+
+	const timer = setInterval(() => {
+		if (!ctx || attached || !ctx.isIdle() || ctx.hasPendingMessages() || !treeIdle()) {
+			idleSince = undefined;
+			return;
+		}
+		idleSince ??= Date.now();
+		if (Date.now() - idleSince >= IDLE_EXIT_MS) ctx.shutdown();
+	}, 1000);
+	timer.unref();
+
+	pi.on("session_start", (_event, current) => {
+		// Owned Agents run in the same process; only the root speaks for the host.
+		if (treeMetadata(current)) return;
+		ctx = current;
+		socket ??= connect(hostSocket);
+		report();
+	});
+	pi.on("session_info_changed", () => report());
+	pi.on("session_shutdown", () => { ctx = undefined; });
+
+	pi.registerCommand("detach", { description: "Detach this terminal; Pi keeps running", handler: async () => send({ type: "detach" }) });
+	return { socket: hostSocket, attached: () => attached, onChange: (listener) => { listeners.push(listener); } };
+}

package/src/host/frames.mjs

@@ -0,0 +1,34 @@
+// Frames on a host socket: one type byte, a 32-bit big-endian length, then the payload.
+export const FRAME = {
+  data: 0, // terminal input to the host, Pi output to the terminal
+  attach: 1, // { cols, rows }
+  resize: 2, // { cols, rows }
+  status: 3, // request: empty; reply: host status
+  detached: 4, // host to terminal: { reason: 'detach' | 'takeover', session }; terminal to host: empty, to detach
+  exited: 5, // { session }
+  control: 6, // Pi to host: { type: 'session', session } | { type: 'detach' }; host to Pi: { type: 'attached', attached }
+};
+
+export function frame(type, payload = '') {
+  const body = Buffer.isBuffer(payload) ? payload : Buffer.from(typeof payload === 'string' ? payload : JSON.stringify(payload));
+  const header = Buffer.alloc(5);
+  header[0] = type;
+  header.writeUInt32BE(body.length, 1);
+  return Buffer.concat([header, body]);
+}
+
+export function readFrames(socket, onFrame) {
+  let buffer = Buffer.alloc(0);
+  socket.on('data', chunk => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length >= 5) {
+      const length = buffer.readUInt32BE(1);
+      if (buffer.length < 5 + length) break;
+      const type = buffer[0], body = buffer.subarray(5, 5 + length);
+      buffer = buffer.subarray(5 + length);
+      onFrame(type, body);
+    }
+  });
+}
+
+export const json = body => JSON.parse(body.toString('utf8'));

package/src/host/keys.mjs

@@ -0,0 +1,19 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+const DEFAULT_DETACH_KEY = 'ctrl+z';
+
+/** The `pi-agents.detach` keybinding in `keybindings.json`, or its default. */
+export function detachKey(agentDir) {
+  try {
+    const value = JSON.parse(readFileSync(join(agentDir, 'keybindings.json'), 'utf8'))['pi-agents.detach'];
+    if (typeof value === 'string') return value;
+    if (Array.isArray(value) && typeof value[0] === 'string') return value[0];
+  } catch { /* missing keybindings use the default */ }
+  return DEFAULT_DETACH_KEY;
+}
+
+/** Whether a key sequence presses the detach key; `tui` is Pi's pi-tui, which parses keys. */
+export function detachMatcher(tui, key) {
+  return sequence => !tui.isKeyRelease(sequence) && tui.matchesKey(sequence, key);
+}

package/src/index.ts

@@ -0,0 +1,208 @@
+import {
+	AgentSession,
+	AgentSessionRuntime,
+	ExtensionRunner,
+	getAgentDir,
+	parseSessionEntries,
+	SessionManager,
+	VERSION,
+	type ExtensionAPI,
+	type ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { readFileSync } from "node:fs";
+import * as path from "node:path";
+import { Agents, type Limits } from "./agents/agents.ts";
+import {
+	customMessage,
+	liveWork,
+	messageText,
+	rememberRoots,
+	visibleIds,
+	nodes,
+	receivedMessageIds,
+	treeIdle,
+	treeMetadata,
+	type AgentNode,
+} from "./agents/registry.ts";
+import { registerAgentTool } from "./agents/tool.ts";
+import { hostExtension } from "./host/extension.ts";
+import { CODEMODE_TOOL_NAME, loadPiCodemode } from "./programs/codemode.ts";
+import { PROGRAM_TOOL_NAME } from "./programs/execute.ts";
+import { installHostPatches } from "./programs/host-patches.ts";
+import { applyProgramOnlyFlag, PROGRAM_ONLY_FLAG } from "./programs/loadout.ts";
+import { addProgramFiles, Programs } from "./programs/programs.ts";
+import { registerProgramTools } from "./programs/tool.ts";
+import { installGuard } from "./roots/guard.mjs";
+import lockExtension from "./roots/lock-extension.mjs";
+import { statePaths } from "./roots/paths.mjs";
+import { createReporter } from "./roots/report.ts";
+import { createRootRuntime } from "./roots/runtime.ts";
+import { createPanel } from "./ui/panel.ts";
+import { openAgentViewer } from "./ui/viewer.ts";
+
+const DEFAULT_LIMITS: Limits = { maxConcurrent: 3, maxOutstanding: 8 };
+
+interface Settings extends Limits {
+	extensions: string[];
+}
+
+/** Reads the "pi-agents" section of the global settings.json. */
+export function readSettings(agentDir: string): Settings {
+	let section: Record<string, unknown> = {};
+	try {
+		const document = JSON.parse(readFileSync(path.join(agentDir, "settings.json"), "utf8")) as Record<string, unknown>;
+		const value = document["pi-agents"];
+		if (value && typeof value === "object") section = value as Record<string, unknown>;
+	} catch { /* missing settings use the defaults */ }
+	const settings: Settings = { ...DEFAULT_LIMITS, extensions: [] };
+	const { maxConcurrent = DEFAULT_LIMITS.maxConcurrent, maxOutstanding = DEFAULT_LIMITS.maxOutstanding, extensions = [] } = section;
+	const positive = (value: unknown): value is number => typeof value === "number" && Number.isInteger(value) && value >= 1;
+	if (positive(maxConcurrent) && positive(maxOutstanding) && maxConcurrent <= maxOutstanding) {
+		settings.maxConcurrent = maxConcurrent;
+		settings.maxOutstanding = maxOutstanding;
+	} else {
+		console.warn(`[pi-agents] invalid maxConcurrent/maxOutstanding ${JSON.stringify({ maxConcurrent, maxOutstanding })}; using ${DEFAULT_LIMITS.maxConcurrent}/${DEFAULT_LIMITS.maxOutstanding}`);
+	}
+	if (Array.isArray(extensions) && extensions.every((entry) => typeof entry === "string")) {
+		settings.extensions = [...new Set(extensions.map((entry) => path.resolve(agentDir, entry)))];
+	} else {
+		console.warn("[pi-agents] invalid extensions; expected an array of paths");
+	}
+	return settings;
+}
+
+const MIN_PI_VERSION = "1.0.0";
+/** How long a root process may take to clean up on exit before it is killed. */
+const EXIT_GRACE_MS = 30_000;
+
+function olderThan(version: string, minimum: string): boolean {
+	const a = version.split(/[.-]/).map((part) => Number.parseInt(part, 10) || 0);
+	const b = minimum.split(".").map(Number);
+	for (let i = 0; i < b.length; i++) if (a[i] !== b[i]) return (a[i] ?? 0) < b[i];
+	return false;
+}
+
+export default async function (pi: ExtensionAPI): Promise<void> {
+	if (olderThan(VERSION, MIN_PI_VERSION)) throw new Error(`pi-agents requires Pi ${MIN_PI_VERSION} or later, found ${VERSION}`);
+	const agentDir = getAgentDir();
+	const settings = readSettings(agentDir);
+	const piCodemode = await loadPiCodemode();
+	let node: AgentNode | undefined;
+	let programs: Programs | undefined;
+	let ctx: ExtensionContext | undefined;
+	const panel = createPanel(() => node);
+
+	installGuard({ SessionManager, AgentSession, AgentSessionRuntime, parseSessionEntries, stateDir: statePaths().locks });
+	installHostPatches(AgentSession, ExtensionRunner, piCodemode.codemodeSchema);
+	const roots = createRootRuntime(pi, {
+		receive: async (message) => {
+			const delivery = message.deliverAs ?? "followUp";
+			// The user's message from the workbench arrives as if typed in Pi's editor.
+			if (message.user) return pi.sendUserMessage(message.body, { deliverAs: delivery === "steer" ? "steer" : "followUp" });
+			// The header names the sender by a short ID unique among the roots this root sees.
+			rememberRoots((await roots.roots()).map((root) => root.id));
+			if (node) node.receive(messageText(message.sender!, false, delivery, message.body, visibleIds(node.scopeId, true)), delivery, message.id);
+		},
+		treeIdle: () => node === undefined || treeIdle(node.rootId),
+		receivedIds: receivedMessageIds,
+	});
+	lockExtension(pi, { start: (current: ExtensionContext) => roots.start(current), stop: () => roots.stop(), runner: ExtensionRunner });
+	const idle = () => node === undefined || treeIdle(node.rootId);
+	const host = hostExtension(pi, { treeIdle: idle });
+	createReporter(pi, { treeIdle: idle, liveWork: () => node ? liveWork(node) : 0, host });
+	// Event bus handlers run synchronously, so an extension that emits a query object reads the answer right after emit.
+	pi.events.on("busy:query", (query) => {
+		if (node && !treeIdle(node.rootId)) (query as { busy: boolean }).busy = true;
+	});
+
+	const requireNode = (current: ExtensionContext): AgentNode => {
+		if (!node) throw new Error("pi-agents is not initialized");
+		ctx = current;
+		node.agents.setContext(current);
+		return node;
+	};
+
+	pi.registerFlag(PROGRAM_ONLY_FLAG, { type: "boolean", description: "Present tools as with codemode.mode \"only\": scripts reach them through program" });
+
+	let warnedBothScriptTools = false;
+	pi.on("session_start", (_event, current) => {
+		applyProgramOnlyFlag(pi);
+		warnedBothScriptTools = false;
+		ctx = current;
+		const id = current.sessionManager.getSessionId();
+		const metadata = treeMetadata(current);
+		const rootId = metadata?.rootId ?? id;
+		const self = { id, rootId, scopeId: metadata?.scopeId ?? rootId, ownerId: metadata?.ownerId, name: () => pi.getSessionName() };
+		const agents = new Agents(pi, self, agentDir, settings, settings.extensions);
+		agents.setContext(current);
+		agents.restore(current);
+		node = {
+			...self,
+			agents,
+			cwd: () => ctx?.cwd ?? current.cwd,
+			busy: () => !(ctx?.isIdle() ?? true),
+			sessionFile: () => ctx?.sessionManager.getSessionFile(),
+			receive: (text, delivery, messageId) => {
+				pi.sendMessage(customMessage(text, delivery, messageId), delivery === "write"
+					? { deliverAs: "steer" }
+					: { deliverAs: delivery, triggerTurn: true });
+			},
+		};
+		nodes.set(id, node);
+		programs = new Programs(rootId, {
+			appendEntry: (customType, data) => pi.appendEntry(customType, data),
+			notify: (text) => agents.notify(text),
+			changed: () => panel.update(),
+		});
+		programs.restore(current);
+		panel.start(current);
+	});
+
+	pi.on("before_agent_start", (_event, current) => {
+		const active = pi.getActiveTools();
+		if (warnedBothScriptTools || !active.includes(PROGRAM_TOOL_NAME) || !active.includes(CODEMODE_TOOL_NAME)) return;
+		warnedBothScriptTools = true;
+		current.ui.notify("Both `program` and `codemode` are active and do a similar job; disable `codemode` to avoid declaring the script API twice.", "warning");
+	});
+
+	pi.on("session_before_compact", (event) => {
+		addProgramFiles(event.branchEntries as never, event.preparation.firstKeptEntryId, event.preparation.fileOps);
+	});
+
+	pi.on("session_shutdown", async (event) => {
+		const closing = node;
+		if (!closing) return;
+		if (event.reason === "quit" && closing.ownerId === undefined) {
+			setTimeout(() => {
+				console.error(`[pi-agents] Cleanup did not finish within ${EXIT_GRACE_MS / 1000}s; killing the process.`);
+				process.kill(process.pid, "SIGKILL");
+			}, EXIT_GRACE_MS).unref();
+		}
+		panel.stop();
+		node = undefined;
+		const stopping = programs;
+		programs = undefined;
+		try {
+			const results = await Promise.allSettled([stopping?.shutdown(), closing.agents.shutdown()]);
+			const errors = results.flatMap((result) => result.status === "rejected" ? [result.reason] : []);
+			if (errors.length > 0) throw new Error(errors.map((error) => error instanceof Error ? error.message : String(error)).join("\n"));
+		} finally {
+			if (nodes.get(closing.id) === closing) nodes.delete(closing.id);
+		}
+	});
+
+	registerAgentTool(pi, { limits: settings, roots, requireNode });
+	registerProgramTools(pi, { agentDir, settings, piCodemode, requireNode, programs: () => programs });
+
+	pi.registerCommand("tasks", {
+		description: "Hide or show the task panel",
+		handler: async () => panel.toggle(),
+	});
+
+	pi.registerCommand("agents", {
+		description: "Open an owned Agent to watch and talk to it",
+		handler: async (_args, current) => {
+			if (node) await openAgentViewer(current, requireNode(current), pi.getSettings().editorPaddingX ?? 0);
+		},
+	});
+}

package/src/output.ts

@@ -0,0 +1,56 @@
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+	DEFAULT_MAX_BYTES,
+	DEFAULT_MAX_LINES,
+	formatSize,
+	truncateHead,
+	type TruncationResult,
+} from "@earendil-works/pi-coding-agent";
+
+export interface Truncation {
+	truncation: TruncationResult;
+	fullOutputPath: string;
+}
+
+export interface BoundedText {
+	text: string;
+	/** The kept prefix of the text, without the notice. */
+	kept: string;
+	details?: Truncation;
+}
+
+/** Apply Pi's output limits, saving the full text to a file named in the notice. */
+export function boundText(text: string, prefix: string): BoundedText {
+	const truncation = truncateHead(text, { maxBytes: DEFAULT_MAX_BYTES, maxLines: DEFAULT_MAX_LINES });
+	if (!truncation.truncated) return { text, kept: text };
+	const fullOutputPath = join(mkdtempSync(join(tmpdir(), `${prefix}-`)), "output.txt");
+	writeFileSync(fullOutputPath, text, "utf8");
+	const summary = truncation.firstLineExceedsLimit
+		? `Line 1 is ${formatSize(Buffer.byteLength(text.split("\n")[0]!, "utf8"))}, exceeds ${formatSize(truncation.maxBytes)} limit.`
+		: `Showing lines 1-${truncation.outputLines} of ${truncation.totalLines}${truncation.truncatedBy === "bytes" ? ` (${formatSize(truncation.maxBytes)} limit)` : ""}.`;
+	return {
+		text: `${truncation.content}\n\n[${summary} Full output: ${fullOutputPath}]`,
+		kept: truncation.content,
+		details: { truncation, fullOutputPath },
+	};
+}
+
+/**
+ * Bounds result blocks joined by blank lines. The block that crosses the limit keeps its closing
+ * tag; `shown` counts the blocks that appear, and the caller names the omitted ones.
+ */
+export function boundBlocks(blocks: string[], tag: string, prefix: string): BoundedText & { shown: number } {
+	const bounded = boundText(blocks.join("\n\n"), prefix);
+	if (!bounded.details) return { ...bounded, shown: blocks.length };
+	const kept = bounded.kept;
+	let start = 0;
+	const shown = blocks.filter((block) => {
+		const visible = start < kept.length;
+		start += block.length + 2;
+		return visible;
+	}).length;
+	const open = kept.lastIndexOf(`<${tag} `) > kept.lastIndexOf(`</${tag}>`);
+	return { ...bounded, text: `${kept}${open ? `\n</${tag}>` : ""}${bounded.text.slice(kept.length)}`, shown };
+}

package/src/params.ts

@@ -0,0 +1,4 @@
+export function rejectFields(params: Record<string, unknown>, action: string, fields: string[]): void {
+	const present = fields.filter((field) => params[field] !== undefined);
+	if (present.length > 0) throw new Error(`${action} does not accept: ${present.join(", ")}`);
+}

package/src/pi.mjs

@@ -0,0 +1,16 @@
+// pd and the workbench run outside Pi, so they load Pi's modules from the package of the `pi` they run.
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+const PACKAGE = '@earendil-works/pi-coding-agent';
+
+/** Pi's package directory, found from its executable: an npm bin link or a Homebrew wrapper. */
+export function piPackage(executable) {
+  for (let dir = dirname(realpathSync(executable)); ; dir = dirname(dir)) {
+    for (const candidate of [dir, join(dir, 'lib/node_modules', PACKAGE), join(dir, 'libexec/lib/node_modules', PACKAGE)]) {
+      try { if (JSON.parse(readFileSync(join(candidate, 'package.json'), 'utf8')).name === PACKAGE) return candidate; }
+      catch (error) { if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error; }
+    }
+    if (dirname(dir) === dir) throw new Error(`Cannot find ${PACKAGE} from ${executable}`);
+  }
+}

package/src/programs/codemode.ts

@@ -0,0 +1,74 @@
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { getKeybindings } from "@earendil-works/pi-tui";
+import { getPackageDir, type AgentToolResult, type AgentToolUpdateCallback, type ExtensionToolContext, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+type Codemode = typeof import("@earendil-works/pi-codemode");
+
+export const CODEMODE_TOOL_NAME = "codemode";
+
+let loaded: Promise<Codemode> | undefined;
+
+/** Imports a package from Pi's own dependencies rather than the copy Pi aliases for extensions. */
+function importPiDependency(name: string) {
+	const dirs = createRequire(join(getPackageDir(), "package.json")).resolve.paths(name) ?? [];
+	const entry = dirs.map((dir) => join(dir, name, "dist/index.js")).find(existsSync);
+	if (!entry) throw new Error(`pi-agents requires Pi with ${name}`);
+	return import(pathToFileURL(entry).href);
+}
+
+/** Pi ships `@earendil-works/pi-codemode` but does not alias it for extensions, so load Pi's copy. */
+export function loadCodemode(): Promise<Codemode> {
+	loaded ??= importPiDependency("@earendil-works/pi-codemode");
+	return loaded;
+}
+
+/** Parts of Pi's `codemode` tool that its package entry does not export. */
+export interface PiCodemode {
+	/** Pi's `codemode` tool definition; `program` reuses its `prepareLoadout`. */
+	createCodemodeToolDefinition(options: Record<string, unknown>): ToolDefinition;
+	createCodemodeDescription(tools: unknown[], options?: Record<string, unknown>): string;
+	/** The `codemode` parameter schema, by which the MCP extension recognizes the tool. */
+	codemodeSchema: unknown;
+	executeCodemode(
+		toolCallId: string,
+		input: { code: string },
+		signal: AbortSignal | undefined,
+		onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+		ctx: ExtensionToolContext,
+		options: Record<string, unknown>,
+	): Promise<AgentToolResult<unknown> & { isError?: boolean }>;
+	/** Renders a script result: its nested calls, then its output without the header. */
+	renderResult(result: unknown, options: unknown, theme: unknown, context: unknown): unknown;
+}
+
+let internals: Promise<PiCodemode> | undefined;
+
+/** Loads those parts from Pi's `dist/` by path, so Programs match Pi's script API. */
+export function loadPiCodemode(): Promise<PiCodemode> {
+	internals ??= (async () => {
+		const dist = join(getPackageDir(), "dist");
+		const load = (file: string) => import(pathToFileURL(join(dist, file)).href);
+		const [tool, execute, renderer, tui] = await Promise.all([
+			load("extensions/codemode/tool.js"),
+			load("extensions/codemode/execute.js"),
+			load("extensions/codemode/renderer.js"),
+			importPiDependency("@earendil-works/pi-tui"),
+		]);
+		return {
+			createCodemodeToolDefinition: tool.createCodemodeToolDefinition,
+			createCodemodeDescription: tool.createCodemodeDescription,
+			codemodeSchema: tool.codemodeSchema,
+			executeCodemode: execute.executeCodemode,
+			// A bundled Pi keeps its keybindings in its embedded pi-tui, which `dist/` does not import;
+			// share them so key hints name the configured keys.
+			renderResult(...args: unknown[]) {
+				tui.setKeybindings(getKeybindings());
+				return renderer.codemodeRenderers.renderResult(...args);
+			},
+		};
+	})();
+	return internals;
+}