docs: add containerization guide and Gondolin example (#5356)

2026-06-03 15:53:16 +02:00
parent 564ad70fb8
commit 86314bf38d
15 changed files with 1052 additions and 3 deletions
--- a/packages/coding-agent/examples/extensions/README.md
+++ b/packages/coding-agent/examples/extensions/README.md
@@ -23,6 +23,7 @@ cp permission-gate.ts ~/.pi/agent/extensions/
 | `confirm-destructive.ts` | Confirms before destructive session actions (clear, switch, fork) |
 | `dirty-repo-guard.ts` | Prevents session changes with uncommitted git changes |
 | `sandbox/` | OS-level sandboxing using `@anthropic-ai/sandbox-runtime` with per-project config |
+| `gondolin/` | Route built-in tools and `!` commands into a Gondolin micro-VM |

 ### Custom Tools

--- a/packages/coding-agent/examples/extensions/gondolin/.gitignore
+++ b/packages/coding-agent/examples/extensions/gondolin/.gitignore
@@ -0,0 +1 @@
+node_modules/
--- a/packages/coding-agent/examples/extensions/gondolin/index.ts
+++ b/packages/coding-agent/examples/extensions/gondolin/index.ts
@@ -0,0 +1,531 @@
+/**
+ * Gondolin Tool Routing Example
+ *
+ * Runs pi's built-in tools inside a local Gondolin micro-VM. The host working
+ * directory is mounted at /workspace in the guest. File changes under
+ * /workspace write through to the host; other guest filesystem changes are
+ * isolated to the VM.
+ *
+ * Setup:
+ *   cd packages/coding-agent/examples/extensions/gondolin
+ *   npm install --ignore-scripts
+ *
+ * Usage:
+ *   cd /path/to/project
+ *   pi -e /path/to/pi/packages/coding-agent/examples/extensions/gondolin
+ *
+ * Requirements:
+ *   - Node.js >= 23.6.0 for @earendil-works/gondolin
+ *   - QEMU installed (for example, `brew install qemu` on macOS)
+ */
+
+import path from "node:path";
+import { RealFSProvider, VM } from "@earendil-works/gondolin";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	type BashOperations,
+	createBashTool,
+	createEditTool,
+	createFindTool,
+	createGrepTool,
+	createLsTool,
+	createReadTool,
+	createWriteTool,
+	DEFAULT_MAX_BYTES,
+	type EditOperations,
+	type FindOperations,
+	formatSize,
+	type GrepToolDetails,
+	type GrepToolInput,
+	type LsOperations,
+	type ReadOperations,
+	truncateHead,
+	truncateLine,
+	type WriteOperations,
+} from "@earendil-works/pi-coding-agent";
+
+const GUEST_WORKSPACE = "/workspace";
+const DEFAULT_GREP_LIMIT = 100;
+
+type TextToolResult<TDetails> = {
+	content: Array<{ type: "text"; text: string }>;
+	details: TDetails | undefined;
+};
+
+function stripAtPrefix(value: string): string {
+	return value.startsWith("@") ? value.slice(1) : value;
+}
+
+function toPosix(value: string): string {
+	return value.split(path.sep).join(path.posix.sep);
+}
+
+function isInsideHostPath(root: string, value: string): boolean {
+	const relativePath = path.relative(root, value);
+	return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
+}
+
+function hostPathToGuest(localCwd: string, hostPath: string): string {
+	const relativePath = path.relative(localCwd, hostPath);
+	if (!isInsideHostPath(localCwd, hostPath)) return toPosix(hostPath);
+	return relativePath ? path.posix.join(GUEST_WORKSPACE, toPosix(relativePath)) : GUEST_WORKSPACE;
+}
+
+function toGuestPath(localCwd: string, inputPath: string): string {
+	const trimmed = stripAtPrefix(inputPath.trim());
+	if (!trimmed) return GUEST_WORKSPACE;
+	if (path.isAbsolute(trimmed)) {
+		if (isInsideHostPath(localCwd, trimmed)) return hostPathToGuest(localCwd, trimmed);
+		return path.posix.resolve("/", toPosix(trimmed));
+	}
+	return path.posix.resolve(GUEST_WORKSPACE, toPosix(trimmed));
+}
+
+function createGondolinReadOps(vm: VM, localCwd: string): ReadOperations {
+	return {
+		readFile: async (filePath) => vm.fs.readFile(toGuestPath(localCwd, filePath)),
+		access: async (filePath) => {
+			await vm.fs.access(toGuestPath(localCwd, filePath));
+		},
+		detectImageMimeType: async (filePath) => {
+			const ext = path.posix.extname(toGuestPath(localCwd, filePath)).toLowerCase();
+			if (ext === ".png") return "image/png";
+			if (ext === ".jpg" || ext === ".jpeg") return "image/jpeg";
+			if (ext === ".gif") return "image/gif";
+			if (ext === ".webp") return "image/webp";
+			return null;
+		},
+	};
+}
+
+function createGondolinWriteOps(vm: VM, localCwd: string): WriteOperations {
+	return {
+		writeFile: async (filePath, content) => {
+			await vm.fs.writeFile(toGuestPath(localCwd, filePath), content, { encoding: "utf8" });
+		},
+		mkdir: async (dirPath) => {
+			await vm.fs.mkdir(toGuestPath(localCwd, dirPath), { recursive: true });
+		},
+	};
+}
+
+function createGondolinEditOps(vm: VM, localCwd: string): EditOperations {
+	const readOps = createGondolinReadOps(vm, localCwd);
+	const writeOps = createGondolinWriteOps(vm, localCwd);
+	return {
+		readFile: readOps.readFile,
+		writeFile: writeOps.writeFile,
+		access: readOps.access,
+	};
+}
+
+function createGondolinLsOps(vm: VM, localCwd: string): LsOperations {
+	return {
+		exists: async (filePath) => {
+			try {
+				await vm.fs.access(toGuestPath(localCwd, filePath));
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		stat: async (filePath) => vm.fs.stat(toGuestPath(localCwd, filePath)),
+		readdir: async (dirPath) => vm.fs.listDir(toGuestPath(localCwd, dirPath)),
+	};
+}
+
+async function walkGuestFiles(
+	vm: VM,
+	root: string,
+	visit: (guestPath: string, relativePath: string) => Promise<boolean>,
+	signal?: AbortSignal,
+): Promise<boolean> {
+	if (signal?.aborted) throw new Error("Operation aborted");
+	const stat = await vm.fs.stat(root, { signal });
+	if (!stat.isDirectory()) return visit(root, path.posix.basename(root));
+
+	const walkDirectory = async (dir: string, relativeDir: string): Promise<boolean> => {
+		if (signal?.aborted) throw new Error("Operation aborted");
+		const entries = await vm.fs.listDir(dir, { signal });
+		for (const entry of entries) {
+			if (entry === ".git" || entry === "node_modules") continue;
+			const guestPath = path.posix.join(dir, entry);
+			const relativePath = relativeDir ? path.posix.join(relativeDir, entry) : entry;
+			let entryStat: Awaited<ReturnType<VM["fs"]["stat"]>>;
+			try {
+				entryStat = await vm.fs.stat(guestPath, { signal });
+			} catch {
+				continue;
+			}
+			if (entryStat.isDirectory()) {
+				if (!(await walkDirectory(guestPath, relativePath))) return false;
+			} else if (!(await visit(guestPath, relativePath))) {
+				return false;
+			}
+		}
+		return true;
+	};
+
+	return walkDirectory(root, "");
+}
+
+function matchesToolGlob(relativePath: string, pattern: string): boolean {
+	const normalizedPattern = toPosix(pattern);
+	if (normalizedPattern.includes("/")) {
+		return (
+			path.posix.matchesGlob(relativePath, normalizedPattern) ||
+			path.posix.matchesGlob(relativePath, `**/${normalizedPattern}`)
+		);
+	}
+	return path.posix.matchesGlob(path.posix.basename(relativePath), normalizedPattern);
+}
+
+function createGondolinFindOps(vm: VM, localCwd: string): FindOperations {
+	return {
+		exists: async (filePath) => {
+			try {
+				await vm.fs.access(toGuestPath(localCwd, filePath));
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		glob: async (pattern, cwd, options) => {
+			const root = toGuestPath(localCwd, cwd);
+			const results: string[] = [];
+			await walkGuestFiles(vm, root, async (guestPath, relativePath) => {
+				if (results.length >= options.limit) return false;
+				if (matchesToolGlob(relativePath, pattern)) results.push(guestPath);
+				return results.length < options.limit;
+			});
+			return results;
+		},
+	};
+}
+
+function createLineMatcher(pattern: string, literal: boolean | undefined, ignoreCase: boolean | undefined) {
+	if (literal) {
+		const needle = ignoreCase ? pattern.toLowerCase() : pattern;
+		return (line: string) => (ignoreCase ? line.toLowerCase() : line).includes(needle);
+	}
+	const regex = new RegExp(pattern, ignoreCase ? "i" : undefined);
+	return (line: string) => regex.test(line);
+}
+
+function appendGrepBlock(params: {
+	outputLines: string[];
+	lines: string[];
+	relativePath: string;
+	lineIndex: number;
+	contextLines: number;
+}): boolean {
+	let linesTruncated = false;
+	const start = params.contextLines > 0 ? Math.max(0, params.lineIndex - params.contextLines) : params.lineIndex;
+	const end =
+		params.contextLines > 0
+			? Math.min(params.lines.length - 1, params.lineIndex + params.contextLines)
+			: params.lineIndex;
+
+	for (let index = start; index <= end; index++) {
+		const rawLine = params.lines[index] ?? "";
+		const { text, wasTruncated } = truncateLine(rawLine.replace(/\r/g, ""));
+		if (wasTruncated) linesTruncated = true;
+		const separator = index === params.lineIndex ? ":" : "-";
+		params.outputLines.push(`${params.relativePath}${separator}${index + 1}${separator} ${text}`);
+	}
+	return linesTruncated;
+}
+
+async function executeGondolinGrep(
+	vm: VM,
+	localCwd: string,
+	params: GrepToolInput,
+	signal?: AbortSignal,
+): Promise<TextToolResult<GrepToolDetails>> {
+	const root = toGuestPath(localCwd, params.path ?? ".");
+	const rootStat = await vm.fs.stat(root, { signal });
+	const rootIsDirectory = rootStat.isDirectory();
+	const matcher = createLineMatcher(params.pattern, params.literal, params.ignoreCase);
+	const contextLines = params.context && params.context > 0 ? params.context : 0;
+	const effectiveLimit = Math.max(1, params.limit ?? DEFAULT_GREP_LIMIT);
+	const outputLines: string[] = [];
+	const details: GrepToolDetails = {};
+	let matchCount = 0;
+	let matchLimitReached = false;
+	let linesTruncated = false;
+
+	await walkGuestFiles(
+		vm,
+		root,
+		async (guestPath, relativePath) => {
+			if (matchCount >= effectiveLimit) return false;
+			if (params.glob && !matchesToolGlob(relativePath, params.glob)) return true;
+			let content: string;
+			try {
+				content = await vm.fs.readFile(guestPath, { encoding: "utf8", signal });
+			} catch {
+				return true;
+			}
+			const lines = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+			const displayPath = rootIsDirectory ? relativePath : path.posix.basename(guestPath);
+			for (let index = 0; index < lines.length; index++) {
+				if (signal?.aborted) throw new Error("Operation aborted");
+				if (!matcher(lines[index] ?? "")) continue;
+				matchCount++;
+				if (appendGrepBlock({ outputLines, lines, relativePath: displayPath, lineIndex: index, contextLines })) {
+					linesTruncated = true;
+				}
+				if (matchCount >= effectiveLimit) {
+					matchLimitReached = true;
+					return false;
+				}
+			}
+			return true;
+		},
+		signal,
+	);
+
+	if (matchCount === 0) return { content: [{ type: "text", text: "No matches found" }], details: undefined };
+
+	const rawOutput = outputLines.join("\n");
+	const truncation = truncateHead(rawOutput, { maxLines: Number.MAX_SAFE_INTEGER });
+	const notices: string[] = [];
+	let output = truncation.content;
+
+	if (matchLimitReached) {
+		details.matchLimitReached = effectiveLimit;
+		notices.push(`${effectiveLimit} matches limit reached`);
+	}
+	if (linesTruncated) {
+		details.linesTruncated = true;
+		notices.push("long lines truncated");
+	}
+	if (truncation.truncated) {
+		details.truncation = truncation;
+		notices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);
+	}
+	if (notices.length > 0) output += `\n\n[${notices.join(". ")}]`;
+
+	return {
+		content: [{ type: "text", text: output }],
+		details: Object.keys(details).length > 0 ? details : undefined,
+	};
+}
+
+function sanitizeEnv(env: NodeJS.ProcessEnv | undefined): Record<string, string> | undefined {
+	if (!env) return undefined;
+	const result: Record<string, string> = {};
+	for (const [key, value] of Object.entries(env)) {
+		if (typeof value === "string") result[key] = value;
+	}
+	return result;
+}
+
+function createGondolinBashOps(vm: VM, localCwd: string, shellPath: string): BashOperations {
+	return {
+		exec: async (command, cwd, { onData, signal, timeout, env }) => {
+			if (signal?.aborted) throw new Error("aborted");
+			const guestCwd = toGuestPath(localCwd, cwd);
+			const controller = new AbortController();
+			const onAbort = () => controller.abort();
+			signal?.addEventListener("abort", onAbort, { once: true });
+
+			let timedOut = false;
+			const timer =
+				timeout && timeout > 0
+					? setTimeout(() => {
+							timedOut = true;
+							controller.abort();
+						}, timeout * 1000)
+					: undefined;
+
+			try {
+				const proc = vm.exec([shellPath, "-lc", command], {
+					cwd: guestCwd,
+					env: sanitizeEnv(env),
+					signal: controller.signal,
+					stdout: "pipe",
+					stderr: "pipe",
+				});
+				for await (const chunk of proc.output()) onData(chunk.data);
+				const result = await proc;
+				return { exitCode: result.exitCode };
+			} catch (error) {
+				if (signal?.aborted) throw new Error("aborted");
+				if (timedOut) throw new Error(`timeout:${timeout}`);
+				throw error;
+			} finally {
+				if (timer) clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+			}
+		},
+	};
+}
+
+export default function (pi: ExtensionAPI) {
+	const localCwd = process.cwd();
+	const localRead = createReadTool(localCwd);
+	const localWrite = createWriteTool(localCwd);
+	const localEdit = createEditTool(localCwd);
+	const localBash = createBashTool(localCwd);
+	const localGrep = createGrepTool(localCwd);
+	const localFind = createFindTool(localCwd);
+	const localLs = createLsTool(localCwd);
+
+	let vm: VM | undefined;
+	let vmStarting: Promise<VM> | undefined;
+	let shellPath = "/bin/sh";
+
+	async function startVm(ctx?: ExtensionContext): Promise<VM> {
+		ctx?.ui.setStatus("gondolin", ctx.ui.theme.fg("accent", `Gondolin: starting ${GUEST_WORKSPACE}`));
+		const created = await VM.create({
+			sessionLabel: `pi ${path.basename(localCwd)}`,
+			vfs: {
+				mounts: {
+					[GUEST_WORKSPACE]: new RealFSProvider(localCwd),
+				},
+			},
+		});
+		const bashProbe = await created.exec(["/bin/sh", "-lc", "command -v bash || true"]);
+		shellPath = bashProbe.stdout.trim() || "/bin/sh";
+		vm = created;
+		ctx?.ui.setStatus(
+			"gondolin",
+			ctx.ui.theme.fg("accent", `Gondolin: ${created.id.slice(0, 8)} (${GUEST_WORKSPACE})`),
+		);
+		ctx?.ui.notify(`Gondolin VM ready. ${localCwd} is mounted at ${GUEST_WORKSPACE}.`, "info");
+		return created;
+	}
+
+	async function ensureVm(ctx?: ExtensionContext): Promise<VM> {
+		if (vm) return vm;
+		if (!vmStarting) {
+			vmStarting = startVm(ctx).finally(() => {
+				vmStarting = undefined;
+			});
+		}
+		return vmStarting;
+	}
+
+	pi.on("session_start", async (_event, ctx) => {
+		await ensureVm(ctx);
+	});
+
+	pi.on("session_shutdown", async (_event, ctx) => {
+		const activeVm = vm;
+		vm = undefined;
+		vmStarting = undefined;
+		if (!activeVm) return;
+		ctx.ui.setStatus("gondolin", ctx.ui.theme.fg("muted", "Gondolin: stopping"));
+		try {
+			await activeVm.close();
+		} finally {
+			ctx.ui.setStatus("gondolin", undefined);
+		}
+	});
+
+	pi.registerCommand("gondolin", {
+		description: "Show Gondolin VM status",
+		handler: async (_args, ctx) => {
+			const activeVm = await ensureVm(ctx);
+			ctx.ui.notify(
+				[
+					`Gondolin VM: ${activeVm.id}`,
+					`Host workspace: ${localCwd}`,
+					`Guest workspace: ${GUEST_WORKSPACE}`,
+					`Shell: ${shellPath}`,
+				].join("\n"),
+				"info",
+			);
+		},
+	});
+
+	pi.registerTool({
+		...localRead,
+		async execute(id, params, signal, onUpdate, ctx) {
+			const activeVm = await ensureVm(ctx);
+			const tool = createReadTool(GUEST_WORKSPACE, {
+				operations: createGondolinReadOps(activeVm, localCwd),
+			});
+			return tool.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.registerTool({
+		...localWrite,
+		async execute(id, params, signal, onUpdate, ctx) {
+			const activeVm = await ensureVm(ctx);
+			const tool = createWriteTool(GUEST_WORKSPACE, {
+				operations: createGondolinWriteOps(activeVm, localCwd),
+			});
+			return tool.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.registerTool({
+		...localEdit,
+		async execute(id, params, signal, onUpdate, ctx) {
+			const activeVm = await ensureVm(ctx);
+			const tool = createEditTool(GUEST_WORKSPACE, {
+				operations: createGondolinEditOps(activeVm, localCwd),
+			});
+			return tool.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.registerTool({
+		...localBash,
+		async execute(id, params, signal, onUpdate, ctx) {
+			const activeVm = await ensureVm(ctx);
+			const tool = createBashTool(GUEST_WORKSPACE, {
+				operations: createGondolinBashOps(activeVm, localCwd, shellPath),
+			});
+			return tool.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.registerTool({
+		...localLs,
+		async execute(id, params, signal, onUpdate, ctx) {
+			const activeVm = await ensureVm(ctx);
+			const tool = createLsTool(GUEST_WORKSPACE, {
+				operations: createGondolinLsOps(activeVm, localCwd),
+			});
+			return tool.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.registerTool({
+		...localFind,
+		async execute(id, params, signal, onUpdate, ctx) {
+			const activeVm = await ensureVm(ctx);
+			const tool = createFindTool(GUEST_WORKSPACE, {
+				operations: createGondolinFindOps(activeVm, localCwd),
+			});
+			return tool.execute(id, params, signal, onUpdate);
+		},
+	});
+
+	pi.registerTool({
+		...localGrep,
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const activeVm = await ensureVm(ctx);
+			return executeGondolinGrep(activeVm, localCwd, params, signal);
+		},
+	});
+
+	pi.on("user_bash", async (_event, ctx) => {
+		const activeVm = await ensureVm(ctx);
+		return { operations: createGondolinBashOps(activeVm, localCwd, shellPath) };
+	});
+
+	pi.on("before_agent_start", async (event, ctx) => {
+		await ensureVm(ctx);
+		const localLine = `Current working directory: ${localCwd}`;
+		const guestLine = `Current working directory: ${GUEST_WORKSPACE} (Gondolin VM; host workspace mounted from ${localCwd})`;
+		const systemPrompt = event.systemPrompt.includes(localLine)
+			? event.systemPrompt.replace(localLine, guestLine)
+			: `${event.systemPrompt}\n\n${guestLine}`;
+		return { systemPrompt };
+	});
+}
--- a/packages/coding-agent/examples/extensions/gondolin/package-lock.json
+++ b/packages/coding-agent/examples/extensions/gondolin/package-lock.json
@@ -0,0 +1,185 @@
+{
+	"name": "pi-extension-gondolin",
+	"version": "0.78.0",
+	"lockfileVersion": 3,
+	"requires": true,
+	"packages": {
+		"": {
+			"name": "pi-extension-gondolin",
+			"version": "0.78.0",
+			"dependencies": {
+				"@earendil-works/gondolin": "0.12.0"
+			}
+		},
+		"node_modules/@cto.af/wtf8": {
+			"version": "0.0.5",
+			"resolved": "https://registry.npmjs.org/@cto.af/wtf8/-/wtf8-0.0.5.tgz",
+			"integrity": "sha512-LfUFi+Vv4eDzj+XAtR89e3wwjXA/NZjUSwU5NhwbBrLecxPaBYFy3exCuc1j+D4UZeOVdqlsl8G7LmOt18V0tg==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=20"
+			}
+		},
+		"node_modules/@earendil-works/gondolin": {
+			"version": "0.12.0",
+			"resolved": "https://registry.npmjs.org/@earendil-works/gondolin/-/gondolin-0.12.0.tgz",
+			"integrity": "sha512-BXbvzQKb5QmxY5NtthRDONJTu7+IDKbzqWGrJyyNXMP7N681Tx0Q9TK8pK1ba8nUvYQTipNJyGZOsJfYiZll1A==",
+			"license": "Apache-2.0",
+			"dependencies": {
+				"cbor2": "^2.3.0",
+				"node-forge": "^1.3.3",
+				"ssh2": "^1.17.0",
+				"undici": "^6.21.0"
+			},
+			"bin": {
+				"gondolin": "dist/bin/gondolin.js"
+			},
+			"engines": {
+				"node": ">=23.6.0"
+			},
+			"optionalDependencies": {
+				"@earendil-works/gondolin-krun-runner-darwin-arm64": "0.12.0",
+				"@earendil-works/gondolin-krun-runner-linux-x64": "0.12.0"
+			}
+		},
+		"node_modules/@earendil-works/gondolin-krun-runner-darwin-arm64": {
+			"version": "0.12.0",
+			"resolved": "https://registry.npmjs.org/@earendil-works/gondolin-krun-runner-darwin-arm64/-/gondolin-krun-runner-darwin-arm64-0.12.0.tgz",
+			"integrity": "sha512-ftDlusht4PcT7Y3TuPrZIKrCXy3isiBTVMvlXYK0pcud2uXY6uwFTGeunYgP+8ND/60ddb+MImqbfmkcK8B84A==",
+			"cpu": [
+				"arm64"
+			],
+			"license": "Apache-2.0",
+			"optional": true,
+			"os": [
+				"darwin"
+			],
+			"bin": {
+				"gondolin-krun-runner": "bin/gondolin-krun-runner"
+			}
+		},
+		"node_modules/@earendil-works/gondolin-krun-runner-linux-x64": {
+			"version": "0.12.0",
+			"resolved": "https://registry.npmjs.org/@earendil-works/gondolin-krun-runner-linux-x64/-/gondolin-krun-runner-linux-x64-0.12.0.tgz",
+			"integrity": "sha512-RRYsgwe2r5ApKmFNy469QgwnyjAHpAs9XANdWpTd9ol4iUYOY3sX7e0xIooAKxd+ktxGI4N/xRWicwGen3D/Ow==",
+			"cpu": [
+				"x64"
+			],
+			"license": "Apache-2.0",
+			"optional": true,
+			"os": [
+				"linux"
+			],
+			"bin": {
+				"gondolin-krun-runner": "bin/gondolin-krun-runner"
+			}
+		},
+		"node_modules/asn1": {
+			"version": "0.2.6",
+			"resolved": "https://registry.npmjs.org/asn1/-/asn1-0.2.6.tgz",
+			"integrity": "sha512-ix/FxPn0MDjeyJ7i/yoHGFt/EX6LyNbxSEhPPXODPL+KB0VPk86UYfL0lMdy+KCnv+fmvIzySwaK5COwqVbWTQ==",
+			"license": "MIT",
+			"dependencies": {
+				"safer-buffer": "~2.1.0"
+			}
+		},
+		"node_modules/bcrypt-pbkdf": {
+			"version": "1.0.2",
+			"resolved": "https://registry.npmjs.org/bcrypt-pbkdf/-/bcrypt-pbkdf-1.0.2.tgz",
+			"integrity": "sha512-qeFIXtP4MSoi6NLqO12WfqARWWuCKi2Rn/9hJLEmtB5yTNr9DqFWkJRCf2qShWzPeAMRnOgCrq0sg/KLv5ES9w==",
+			"license": "BSD-3-Clause",
+			"dependencies": {
+				"tweetnacl": "^0.14.3"
+			}
+		},
+		"node_modules/buildcheck": {
+			"version": "0.0.7",
+			"resolved": "https://registry.npmjs.org/buildcheck/-/buildcheck-0.0.7.tgz",
+			"integrity": "sha512-lHblz4ahamxpTmnsk+MNTRWsjYKv965MwOrSJyeD588rR3Jcu7swE+0wN5F+PbL5cjgu/9ObkhfzEPuofEMwLA==",
+			"optional": true,
+			"engines": {
+				"node": ">=10.0.0"
+			}
+		},
+		"node_modules/cbor2": {
+			"version": "2.3.0",
+			"resolved": "https://registry.npmjs.org/cbor2/-/cbor2-2.3.0.tgz",
+			"integrity": "sha512-76WB3hq8BoaGkMkBVJ27fW5LJU+qqDLEpgRNCG/SYKhODWXpVPOTD4UcUto3IEzYLA52nsvbhb0wabhHDn3qXg==",
+			"license": "MIT",
+			"dependencies": {
+				"@cto.af/wtf8": "0.0.5"
+			},
+			"engines": {
+				"node": ">=20"
+			}
+		},
+		"node_modules/cpu-features": {
+			"version": "0.0.10",
+			"resolved": "https://registry.npmjs.org/cpu-features/-/cpu-features-0.0.10.tgz",
+			"integrity": "sha512-9IkYqtX3YHPCzoVg1Py+o9057a3i0fp7S530UWokCSaFVTc7CwXPRiOjRjBQQ18ZCNafx78YfnG+HALxtVmOGA==",
+			"hasInstallScript": true,
+			"optional": true,
+			"dependencies": {
+				"buildcheck": "~0.0.6",
+				"nan": "^2.19.0"
+			},
+			"engines": {
+				"node": ">=10.0.0"
+			}
+		},
+		"node_modules/nan": {
+			"version": "2.27.0",
+			"resolved": "https://registry.npmjs.org/nan/-/nan-2.27.0.tgz",
+			"integrity": "sha512-hC+0LidcL3XE4rp1C4H54KujgXKzbfyTngZTwBByQxsOxCEKZT0MPQ4hOKUH2jU1OYstqdDH4onyHPDzcV0XdQ==",
+			"license": "MIT",
+			"optional": true
+		},
+		"node_modules/node-forge": {
+			"version": "1.4.0",
+			"resolved": "https://registry.npmjs.org/node-forge/-/node-forge-1.4.0.tgz",
+			"integrity": "sha512-LarFH0+6VfriEhqMMcLX2F7SwSXeWwnEAJEsYm5QKWchiVYVvJyV9v7UDvUv+w5HO23ZpQTXDv/GxdDdMyOuoQ==",
+			"license": "(BSD-3-Clause OR GPL-2.0)",
+			"engines": {
+				"node": ">= 6.13.0"
+			}
+		},
+		"node_modules/safer-buffer": {
+			"version": "2.1.2",
+			"resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
+			"integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
+			"license": "MIT"
+		},
+		"node_modules/ssh2": {
+			"version": "1.17.0",
+			"resolved": "https://registry.npmjs.org/ssh2/-/ssh2-1.17.0.tgz",
+			"integrity": "sha512-wPldCk3asibAjQ/kziWQQt1Wh3PgDFpC0XpwclzKcdT1vql6KeYxf5LIt4nlFkUeR8WuphYMKqUA56X4rjbfgQ==",
+			"hasInstallScript": true,
+			"dependencies": {
+				"asn1": "^0.2.6",
+				"bcrypt-pbkdf": "^1.0.2"
+			},
+			"engines": {
+				"node": ">=10.16.0"
+			},
+			"optionalDependencies": {
+				"cpu-features": "~0.0.10",
+				"nan": "^2.23.0"
+			}
+		},
+		"node_modules/tweetnacl": {
+			"version": "0.14.5",
+			"resolved": "https://registry.npmjs.org/tweetnacl/-/tweetnacl-0.14.5.tgz",
+			"integrity": "sha512-KXXFFdAbFXY4geFIwoyNK+f5Z1b7swfXABfL7HXCmoIWMKU3dmS26672A4EeQtDzLKy7SXmfBu51JolvEKwtGA==",
+			"license": "Unlicense"
+		},
+		"node_modules/undici": {
+			"version": "6.26.0",
+			"resolved": "https://registry.npmjs.org/undici/-/undici-6.26.0.tgz",
+			"integrity": "sha512-4yqz8a3n5HmGTlsbADNtr/dJlhkh/55Rq798G6ibiULcXbDtaLpTl1pvdqcbFfeoj3iSi52lePFM7h9H21cw/A==",
+			"license": "MIT",
+			"engines": {
+				"node": ">=18.17"
+			}
+		}
+	}
+}
--- a/packages/coding-agent/examples/extensions/gondolin/package.json
+++ b/packages/coding-agent/examples/extensions/gondolin/package.json
@@ -0,0 +1,19 @@
+{
+	"name": "pi-extension-gondolin",
+	"private": true,
+	"version": "0.78.0",
+	"type": "module",
+	"scripts": {
+		"clean": "echo 'nothing to clean'",
+		"build": "echo 'nothing to build'",
+		"check": "echo 'nothing to check'"
+	},
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"dependencies": {
+		"@earendil-works/gondolin": "0.12.0"
+	}
+}