@themoltnet/pi-extension 0.28.0 → 0.28.1

package/README.md

@@ -6,7 +6,8 @@ agent's MoltNet identity fully available inside the sandbox.
 ## How it works
 
 Every pi session boots a lightweight Alpine Linux VM from a cached snapshot.
-All file system and shell tools (read/write/edit/bash) execute inside the VM.
+All file system, search, and shell tools (read/write/edit/bash/ls/find/grep)
+execute inside the VM.
 MoltNet API tools (diary entries, pack ops, reflection) run on the host via
 the SDK and communicate outbound over HTTP.
 
@@ -24,7 +25,8 @@ pi + extension                $MOLTNET_GUEST_WORKSPACE
   │   (via gitconfig           ssh/allowed_signers
   │    in VM)               /home/agent/.pi/agent/auth.json  (pi OAuth)
   │
-  └─ read/write/edit/bash ─▶  vm.exec() / vm.fs.*
+  └─ read/write/edit/bash/ls/find/grep
+                              ─▶  vm.exec() / vm.fs.*
       (redirected to VM)
 ```
 
@@ -104,6 +106,7 @@ tools can use structured in-process calls rather than shell round-trips.
 | Tool                                | Runs in | Mechanism                                                                        |
 | ----------------------------------- | ------- | -------------------------------------------------------------------------------- |
 | `read`, `write`, `edit`             | VM      | Gondolin VFS — agent's FS view is `$MOLTNET_GUEST_WORKSPACE`                     |
+| `ls`, `find`, `grep`                | VM      | Gondolin VFS — search/listing observes the sandboxed workspace                   |
 | `bash`                              | VM      | `vm.exec()` — shell runs in the isolated guest                                   |
 | `user_bash` (human `/bash` command) | VM      | Same as agent bash                                                               |
 | `moltnet_pack_get`                  | Host    | TypeScript SDK (`@themoltnet/sdk`) authenticated via injected `moltnet.json`     |

package/dist/index.d.ts

@@ -181,7 +181,7 @@ export declare interface CreateSubagentToolArgs {
     agentName: string;
     /**
      * Custom tools every subagent inherits (Gondolin-routed
-     * Read/Write/Edit/Bash + moltnet_* tools, etc). MUST NOT include
+     * built-ins + moltnet_* tools, etc). MUST NOT include
      * the parent's submit-output tool, the parent's `subagent` tool,
      * or any other parent-only artefact — the caller is responsible
      * for filtering. The subagent appends its own submit tool.

package/dist/index.js

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 import { execFileSync } from "node:child_process";
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
 import path, { join, relative, sep } from "node:path";
-import { DefaultResourceLoader, SessionManager, createAgentSession, createBashTool, createBashToolDefinition, createEditTool, createEditToolDefinition, createReadTool, createReadToolDefinition, createSyntheticSourceInfo, createWriteTool, createWriteToolDefinition, defineTool, parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_MAX_BYTES, DefaultResourceLoader, SessionManager, createAgentSession, createBashTool, createBashToolDefinition, createEditTool, createEditToolDefinition, createFindTool, createFindToolDefinition, createGrepTool, createGrepToolDefinition, createLsTool, createLsToolDefinition, createReadTool, createReadToolDefinition, createSyntheticSourceInfo, createWriteTool, createWriteToolDefinition, defineTool, formatSize, parseFrontmatter, truncateHead, truncateLine } from "@earendil-works/pi-coding-agent";
 import { createHash } from "node:crypto";
 import { Readable } from "node:stream";
 import crypto, { createHash as createHash$1 } from "crypto";
@@ -18559,11 +18559,13 @@ function rewriteMoltnetJsonPaths(moltnetJson, vmAgentDir, vmSshDir, githubAppPem
 //#region src/tool-operations.ts
 /**
 * Gondolin tool operations: redirect pi's built-in tool operations
-* (read, write, edit, bash) to execute inside the VM.
+* (read, write, edit, bash, ls, find, grep) to execute inside the VM.
 *
 * Follows the same pattern as upstream pi-gondolin.ts — pi's tool factories
 * accept an `operations` object that provides the underlying I/O.
 */
+var DEFAULT_GREP_LIMIT = 100;
+var GREP_MAX_FILE_SIZE = "2M";
 function shQuote(s) {
 	return "'" + s.replace(/'/g, "'\\''") + "'";
 }
@@ -18573,6 +18575,18 @@ function normalizeGuestPath(p) {
 function isSameOrInsidePosixPath(candidate, root) {
 	return candidate === root || candidate.startsWith(`${root}/`);
 }
+function resolveLocalPath(localCwd, inputPath) {
+	return path.isAbsolute(inputPath) ? inputPath : path.resolve(localCwd, inputPath);
+}
+function toHostToolPath(localCwd, guestWorkspace, guestPath) {
+	const normalizedGuestWorkspace = normalizeGuestPath(guestWorkspace);
+	const normalizedGuestPath = normalizeGuestPath(guestPath);
+	if (isSameOrInsidePosixPath(normalizedGuestPath, normalizedGuestWorkspace)) {
+		const rel = path.posix.relative(normalizedGuestWorkspace, normalizedGuestPath);
+		return rel ? path.join(localCwd, ...rel.split("/")) : localCwd;
+	}
+	return normalizedGuestPath;
+}
 /**
 * Map a host-side absolute path to a guest-side workspace path.
 * Throws if the path escapes the workspace.
@@ -18592,17 +18606,10 @@ function toGuestPath(localCwd, localPath, guestWorkspace) {
 function createGondolinReadOps(vm, localCwd, guestWorkspace) {
 	return {
 		readFile: async (p) => {
-			const r = await vm.exec(["/bin/cat", toGuestPath(localCwd, p, guestWorkspace)]);
-			if (!r.ok) throw new Error(`cat failed (${r.exitCode}): ${r.stderr}`);
-			return r.stdoutBuffer;
-		},
-		access: async (p) => {
-			if (!(await vm.exec([
-				"/bin/sh",
-				"-lc",
-				`test -r ${shQuote(toGuestPath(localCwd, p, guestWorkspace))}`
-			])).ok) throw new Error(`not readable: ${p}`);
+			const content = await vm.fs.readFile(toGuestPath(localCwd, p, guestWorkspace));
+			return typeof content === "string" ? Buffer.from(content, "utf8") : Buffer.from(content);
 		},
+		access: async (p) => vm.fs.access(toGuestPath(localCwd, p, guestWorkspace)),
 		detectImageMimeType: async (p) => {
 			try {
 				const r = await vm.exec([
@@ -18660,6 +18667,253 @@ function createGondolinEditOps(vm, localCwd, guestWorkspace) {
 		writeFile: w.writeFile
 	};
 }
+function createGondolinLsOps(vm, localCwd, guestWorkspace) {
+	return {
+		exists: async (p) => {
+			try {
+				await vm.fs.access(toGuestPath(localCwd, p, guestWorkspace));
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		stat: async (p) => vm.fs.stat(toGuestPath(localCwd, p, guestWorkspace)),
+		readdir: async (p) => vm.fs.listDir(toGuestPath(localCwd, p, guestWorkspace))
+	};
+}
+async function walkGuestFiles(vm, root, visit, signal) {
+	if (signal?.aborted) throw new Error("Operation aborted");
+	if (!(await vm.fs.stat(root, { signal })).isDirectory()) return visit(root, path.posix.basename(root));
+	const walkDirectory = async (dir, relativeDir) => {
+		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;
+			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 matchesGlob(relativePath, pattern) {
+	return path.posix.matchesGlob(relativePath, pattern);
+}
+function matchesToolGlob(relativePath, pattern) {
+	const normalizedPattern = normalizeGuestPath(pattern);
+	if (normalizedPattern.includes("/")) return matchesGlob(relativePath, normalizedPattern) || matchesGlob(relativePath, `**/${normalizedPattern}`);
+	return matchesGlob(path.posix.basename(relativePath), normalizedPattern);
+}
+function createGondolinFindOps(vm, localCwd, guestWorkspace) {
+	return {
+		exists: async (p) => {
+			try {
+				await vm.fs.access(toGuestPath(localCwd, p, guestWorkspace));
+				return true;
+			} catch {
+				return false;
+			}
+		},
+		glob: async (pattern, cwd, options) => {
+			const root = toGuestPath(localCwd, cwd, guestWorkspace);
+			const results = [];
+			await walkGuestFiles(vm, root, (guestPath, relativePath) => {
+				if (results.length >= options.limit) return Promise.resolve(false);
+				if (options.ignore.some((ignore) => matchesToolGlob(relativePath, ignore))) return Promise.resolve(true);
+				if (matchesToolGlob(relativePath, pattern)) results.push(toHostToolPath(localCwd, guestWorkspace, guestPath));
+				return Promise.resolve(results.length < options.limit);
+			});
+			return results;
+		}
+	};
+}
+function appendGrepBlock(params) {
+	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 { text, wasTruncated } = truncateLine((params.lines[index] ?? "").replace(/\r/g, ""));
+		if (wasTruncated) linesTruncated = true;
+		const separator = index === params.lineIndex ? ":" : "-";
+		params.outputLines.push(`${params.relativePath}${separator}${index + 1}${separator} ${text}`);
+	}
+	return linesTruncated;
+}
+function parseRgJsonLines(params) {
+	const parts = `${params.carry}${params.chunk}`.split("\n");
+	const carry = parts.pop() ?? "";
+	let limitReached = false;
+	for (const line of parts) {
+		if (!line.trim() || params.matches.length >= params.effectiveLimit) continue;
+		let event;
+		try {
+			event = JSON.parse(line);
+		} catch {
+			continue;
+		}
+		const candidate = event;
+		if (candidate.type !== "match") continue;
+		const guestPath = candidate.data?.path?.text;
+		const lineNumber = candidate.data?.line_number;
+		if (!guestPath || typeof lineNumber !== "number") continue;
+		params.matches.push({
+			guestPath,
+			lineNumber,
+			lineText: candidate.data?.lines?.text
+		});
+		if (params.matches.length >= params.effectiveLimit) {
+			limitReached = true;
+			break;
+		}
+	}
+	return {
+		carry,
+		limitReached
+	};
+}
+async function readGuestLines(vm, guestPath, signal) {
+	try {
+		return (await vm.fs.readFile(guestPath, {
+			encoding: "utf8",
+			signal
+		})).replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+	} catch {
+		return [];
+	}
+}
+async function executeGondolinGrep(vm, localCwd, guestWorkspace, params, signal) {
+	const root = toGuestPath(localCwd, resolveLocalPath(localCwd, params.path ?? "."), guestWorkspace);
+	let rootStat;
+	try {
+		rootStat = await vm.fs.stat(root, { signal });
+	} catch {
+		throw new Error(`Path not found: ${resolveLocalPath(localCwd, params.path ?? ".")}`);
+	}
+	const rootIsDirectory = rootStat.isDirectory();
+	const contextLines = params.context && params.context > 0 ? params.context : 0;
+	const effectiveLimit = Math.max(1, params.limit ?? DEFAULT_GREP_LIMIT);
+	const args = [
+		"--json",
+		"--line-number",
+		"--color=never",
+		"--hidden",
+		"--max-filesize",
+		GREP_MAX_FILE_SIZE
+	];
+	if (params.ignoreCase) args.push("--ignore-case");
+	if (params.literal) args.push("--fixed-strings");
+	if (params.glob) args.push("--glob", params.glob);
+	args.push("--", params.pattern, root);
+	const outputLines = [];
+	const details = {};
+	const matches = [];
+	let matchLimitReached = false;
+	let linesTruncated = false;
+	let stderr = "";
+	let carry = "";
+	const ac = new AbortController();
+	const onAbort = () => ac.abort();
+	signal?.addEventListener("abort", onAbort, { once: true });
+	try {
+		const proc = vm.exec(["/bin/rg", ...args], {
+			signal: ac.signal,
+			stdout: "pipe",
+			stderr: "pipe"
+		});
+		for await (const chunk of proc.output()) {
+			const text = typeof chunk.data === "string" ? chunk.data : Buffer.from(chunk.data).toString("utf8");
+			if (chunk.stream === "stderr") {
+				stderr += text;
+				continue;
+			}
+			const parsed = parseRgJsonLines({
+				chunk: text,
+				carry,
+				matches,
+				effectiveLimit
+			});
+			carry = parsed.carry;
+			if (parsed.limitReached) {
+				matchLimitReached = true;
+				ac.abort();
+				break;
+			}
+		}
+		const r = await proc;
+		if (!signal?.aborted && !matchLimitReached && r.exitCode !== 0 && r.exitCode !== 1) throw new Error(stderr.trim() || `ripgrep exited with code ${r.exitCode}`);
+	} catch (err) {
+		if (signal?.aborted) throw new Error("Operation aborted");
+		if (matchLimitReached) {} else throw err;
+	} finally {
+		signal?.removeEventListener("abort", onAbort);
+	}
+	if (matches.length === 0) return {
+		content: [{
+			type: "text",
+			text: "No matches found"
+		}],
+		details: void 0
+	};
+	const fileCache = /* @__PURE__ */ new Map();
+	for (const match of matches) {
+		if (signal?.aborted) throw new Error("Operation aborted");
+		const displayPath = rootIsDirectory ? path.posix.relative(root, match.guestPath) : path.posix.basename(match.guestPath);
+		if (contextLines === 0 && match.lineText !== void 0) {
+			const { text, wasTruncated } = truncateLine(match.lineText.replace(/\r\n/g, "\n").replace(/\r/g, "").replace(/\n$/, ""));
+			if (wasTruncated) linesTruncated = true;
+			outputLines.push(`${displayPath}:${match.lineNumber}: ${text}`);
+			continue;
+		}
+		let lines = fileCache.get(match.guestPath);
+		if (!lines) {
+			lines = await readGuestLines(vm, match.guestPath, signal);
+			fileCache.set(match.guestPath, lines);
+		}
+		if (lines.length === 0) {
+			outputLines.push(`${displayPath}:${match.lineNumber}: (unable to read file)`);
+			continue;
+		}
+		if (appendGrepBlock({
+			outputLines,
+			lines,
+			relativePath: displayPath,
+			lineIndex: match.lineNumber - 1,
+			contextLines
+		})) linesTruncated = true;
+	}
+	const truncation = truncateHead(outputLines.join("\n"), { maxLines: Number.MAX_SAFE_INTEGER });
+	const notices = [];
+	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 : void 0
+	};
+}
 function createGondolinBashOps(vm, localCwd, guestWorkspace) {
 	return { exec: async (command, cwd, { onData, signal, timeout, env }) => {
 		const guestCwd = toGuestPath(localCwd, cwd, guestWorkspace);
@@ -24292,7 +24546,7 @@ function subagentToolDescription() {
 		"",
 		"The subagent starts with no conversation history and only the `task` ",
 		"string you provide as its instructions. It runs in the same VM with ",
-		"the same tools you have (Gondolin-routed Read/Write/Edit/Bash, ",
+		"the same tools you have (Gondolin-routed built-ins, ",
 		"moltnet_* tools), and is expected to call ",
 		`\`${SUBAGENT_SUBMIT_TOOL_NAME}\` with a payload matching the named `,
 		"contract before its session ends.",
@@ -24784,7 +25038,7 @@ function shouldSkipSeedEntry(sourceEntry, entryName, resolvedTargetDir) {
 *
 * This is the pi-specific task executor. It owns:
 *   - VM lifecycle (ensureSnapshot + resumeVm + close)
-*   - Gondolin-redirected tool wiring (read/write/edit/bash → VM)
+*   - Gondolin-redirected tool wiring (read/write/edit/bash/ls/find/grep → VM)
 *   - MoltNet custom tools (diary entries, pack render/judge, etc.)
 *   - pi createAgentSession + event → TaskReporter bridge
 *
@@ -24795,6 +25049,25 @@ function shouldSkipSeedEntry(sourceEntry, entryName, resolvedTargetDir) {
 * `AgentRuntime`.
 */
 var noopTurnEventHandler = () => {};
+function createGondolinToolDefinitions(config) {
+	const { vm, mountPath, guestWorkspace } = config;
+	const grepTool = createGrepToolDefinition(mountPath);
+	return [
+		createReadToolDefinition(mountPath, { operations: createGondolinReadOps(vm, mountPath, guestWorkspace) }),
+		createWriteToolDefinition(mountPath, { operations: createGondolinWriteOps(vm, mountPath, guestWorkspace) }),
+		createEditToolDefinition(mountPath, { operations: createGondolinEditOps(vm, mountPath, guestWorkspace) }),
+		createBashToolDefinition(mountPath, { operations: createGondolinBashOps(vm, mountPath, guestWorkspace) }),
+		createLsToolDefinition(mountPath, { operations: createGondolinLsOps(vm, mountPath, guestWorkspace) }),
+		createFindToolDefinition(mountPath, { operations: createGondolinFindOps(vm, mountPath, guestWorkspace) }),
+		{
+			...grepTool,
+			async execute(...args) {
+				const [_id, params, signal] = args;
+				return executeGondolinGrep(vm, mountPath, guestWorkspace, params, signal);
+			}
+		}
+	];
+}
 /**
 * Factory that builds a pi-specific `executeTask` function suitable for
 * injection into `AgentRuntime`. The returned function caches the resolved
@@ -25058,12 +25331,11 @@ async function executePiTask(claimedTask, reporter, opts) {
 			slugs: injectedContext.injected.map((r) => r.slug)
 		});
 		if (injectedContext.userInlineSuffix) taskPrompt = `${taskPrompt}\n\n---\n\n${injectedContext.userInlineSuffix}`;
-		const gondolinCustomTools = [
-			createReadToolDefinition(mountPath, { operations: createGondolinReadOps(managed.vm, mountPath, managed.guestWorkspace) }),
-			createWriteToolDefinition(mountPath, { operations: createGondolinWriteOps(managed.vm, mountPath, managed.guestWorkspace) }),
-			createEditToolDefinition(mountPath, { operations: createGondolinEditOps(managed.vm, mountPath, managed.guestWorkspace) }),
-			createBashToolDefinition(mountPath, { operations: createGondolinBashOps(managed.vm, mountPath, managed.guestWorkspace) })
-		];
+		const gondolinCustomTools = createGondolinToolDefinitions({
+			vm: managed.vm,
+			mountPath,
+			guestWorkspace: managed.guestWorkspace
+		});
 		const { handle: submitToolHandle, tools: submitToolDefs } = resolveSubmitTools(task.taskType, {
 			model: opts.model,
 			input: task.input
@@ -25591,6 +25863,9 @@ function moltnetExtension(pi) {
 	const localWrite = createWriteTool(localCwd);
 	const localEdit = createEditTool(localCwd);
 	const localBash = createBashTool(localCwd);
+	const localLs = createLsTool(localCwd);
+	const localFind = createFindTool(localCwd);
+	const localGrep = createGrepTool(localCwd);
 	const initialGuestWorkspace = path.resolve(localCwd);
 	let vm = null;
 	let guestWorkspace = initialGuestWorkspace;
@@ -25701,6 +25976,24 @@ function moltnetExtension(pi) {
 			return createBashTool(localCwd, { operations: createGondolinBashOps(await ensureVm(ctx), localCwd, guestWorkspace) }).execute(id, params, signal, onUpdate);
 		}
 	});
+	pi.registerTool({
+		...localLs,
+		async execute(id, params, signal, onUpdate, ctx) {
+			return createLsTool(localCwd, { operations: createGondolinLsOps(await ensureVm(ctx), localCwd, guestWorkspace) }).execute(id, params, signal, onUpdate);
+		}
+	});
+	pi.registerTool({
+		...localFind,
+		async execute(id, params, signal, onUpdate, ctx) {
+			return createFindTool(localCwd, { operations: createGondolinFindOps(await ensureVm(ctx), localCwd, guestWorkspace) }).execute(id, params, signal, onUpdate);
+		}
+	});
+	pi.registerTool({
+		...localGrep,
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			return executeGondolinGrep(await ensureVm(ctx), localCwd, guestWorkspace, params, signal);
+		}
+	});
 	pi.on("user_bash", (_event, _ctx) => {
 		if (!vm) return;
 		return { operations: createGondolinBashOps(vm, localCwd, guestWorkspace) };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/pi-extension",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "type": "module",
   "description": "MoltNet pi extension — sandboxed tool execution in Gondolin VMs with MoltNet identity and persistent memory",
   "keywords": [