@themoltnet/pi-extension 0.28.0 → 0.29.0

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.
@@ -762,6 +762,13 @@ declare const Task: Type.TObject<{
             commit_sha: Type.TOptional<Type.TString>;
             snapshot_cid: Type.TOptional<Type.TString>;
         }>>;
+        artifact: Type.TOptional<Type.TObject<{
+            cid: Type.TString;
+            attemptN: Type.TInteger;
+            kind: Type.TOptional<Type.TString>;
+            title: Type.TOptional<Type.TString>;
+            contentType: Type.TOptional<Type.TString>;
+        }>>;
     }>>;
     correlationId: Type.TUnion<[Type.TString, Type.TNull]>;
     proposedByAgentId: Type.TUnion<[Type.TString, Type.TNull]>;

package/dist/index.js

@@ -1,13 +1,14 @@
 import { createRequire } from "node:module";
 import { execFileSync } from "node:child_process";
-import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
+import { cpSync, createReadStream, createWriteStream, 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";
-import { readFile } from "node:fs/promises";
+import { readFile, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
+import { pipeline } from "node:stream/promises";
 import { Type, getModel } from "@earendil-works/pi-ai";
 import { MemoryProvider, RealFSProvider, ShadowProvider, VM, VmCheckpoint, createHttpHooks, createShadowPathPredicate, ensureImageSelector, loadGuestAssets } from "@earendil-works/gondolin";
 import { parseEnv } from "node:util";
@@ -2308,6 +2309,55 @@ var claimTask = (options) => (options.client ?? client).post({
 	}
 });
 /**
+* List task artifact metadata for the current team.
+*/
+var listTaskArtifacts = (options) => (options.client ?? client).get({
+	security: [
+		{
+			scheme: "bearer",
+			type: "http"
+		},
+		{
+			name: "X-Moltnet-Session-Token",
+			type: "apiKey"
+		},
+		{
+			in: "cookie",
+			name: "ory_kratos_session",
+			type: "apiKey"
+		}
+	],
+	url: "/tasks/{taskId}/artifacts",
+	...options
+});
+/**
+* Upload immutable content-addressed artifact content for a task attempt.
+*/
+var uploadTaskArtifact = (options) => (options.client ?? client).put({
+	bodySerializer: null,
+	security: [
+		{
+			scheme: "bearer",
+			type: "http"
+		},
+		{
+			name: "X-Moltnet-Session-Token",
+			type: "apiKey"
+		},
+		{
+			in: "cookie",
+			name: "ory_kratos_session",
+			type: "apiKey"
+		}
+	],
+	url: "/tasks/{taskId}/attempts/{attemptN}/artifacts",
+	...options,
+	headers: {
+		"Content-Type": "application/octet-stream",
+		...options.headers
+	}
+});
+/**
 * List teams the caller belongs to.
 */
 var listTeams = (options) => (options?.client ?? client).get({
@@ -10073,6 +10123,97 @@ var VerificationRecord = _Object_({
 	$id: "VerificationRecord",
 	additionalProperties: false
 });
+_Object_({
+	artifacts: _Array_(_Object_({
+		id: String$1({ format: "uuid" }),
+		teamId: String$1({ format: "uuid" }),
+		taskId: String$1({ format: "uuid" }),
+		attemptN: Integer({ minimum: 1 }),
+		kind: String$1({
+			minLength: 1,
+			maxLength: 100
+		}),
+		title: String$1({
+			minLength: 1,
+			maxLength: 255
+		}),
+		contentType: String$1({
+			minLength: 1,
+			maxLength: 200
+		}),
+		contentEncoding: Union([String$1({
+			minLength: 1,
+			maxLength: 100
+		}), Null()]),
+		sizeBytes: Integer({ minimum: 0 }),
+		cid: String$1({
+			minLength: 1,
+			maxLength: 100
+		}),
+		createdByAgentId: String$1({ format: "uuid" }),
+		expiresAt: Union([String$1({ format: "date-time" }), Null()]),
+		createdAt: String$1({ format: "date-time" })
+	}, { $id: "TaskArtifact" })),
+	nextCursor: Union([String$1({ minLength: 1 }), Null()])
+}, { $id: "TaskArtifactList" });
+_Object_({
+	limit: Optional(Integer({
+		minimum: 1,
+		maximum: 100
+	})),
+	cursor: Optional(String$1({ minLength: 1 }))
+}, {
+	$id: "ListTaskArtifactsQuery",
+	additionalProperties: false
+});
+_Object_({
+	kind: String$1({
+		minLength: 1,
+		maxLength: 100
+	}),
+	title: String$1({
+		minLength: 1,
+		maxLength: 255
+	}),
+	contentType: Optional(String$1({
+		minLength: 1,
+		maxLength: 200
+	})),
+	contentEncoding: Optional(String$1({
+		minLength: 1,
+		maxLength: 100
+	}))
+}, {
+	$id: "UploadTaskArtifactQuery",
+	additionalProperties: false
+});
+String$1({
+	$id: "TaskArtifactContent",
+	description: "Task artifact content stream.",
+	format: "binary"
+});
+_Object_({ taskId: String$1({ format: "uuid" }) }, {
+	$id: "TaskArtifactTaskParams",
+	additionalProperties: false
+});
+_Object_({
+	taskId: String$1({ format: "uuid" }),
+	attemptN: Integer({ minimum: 1 })
+}, {
+	$id: "TaskArtifactAttemptParams",
+	additionalProperties: false
+});
+_Object_({
+	taskId: String$1({ format: "uuid" }),
+	attemptN: Integer({ minimum: 1 }),
+	cid: String$1({
+		minLength: 1,
+		maxLength: 100
+	})
+}, {
+	$id: "TaskArtifactContentParams",
+	additionalProperties: false
+});
 //#endregion
 //#region ../../node_modules/.pnpm/multiformats@13.4.2/node_modules/multiformats/dist/src/codecs/json.js
 var textEncoder$2 = new TextEncoder();
@@ -10339,6 +10480,10 @@ var FreeformArtifact = _Object_({
 	description: Optional(String$1({ minLength: 1 })),
 	url: Optional(String$1({ minLength: 1 })),
 	path: Optional(String$1({ minLength: 1 })),
+	cid: Optional(String$1({ minLength: 1 })),
+	contentType: Optional(String$1({ minLength: 1 })),
+	contentEncoding: Optional(String$1({ minLength: 1 })),
+	sizeBytes: Optional(Integer({ minimum: 0 })),
 	body: Optional(String$1({ maxLength: 65536 }))
 }, {
 	$id: "FreeformArtifact",
@@ -13818,7 +13963,23 @@ var TaskRef = _Object_({
 		url: Optional(String$1()),
 		commit_sha: Optional(String$1()),
 		snapshot_cid: Optional(Cid)
-	}))
+	})),
+	artifact: Optional(_Object_({
+		cid: Cid,
+		attemptN: Integer({ minimum: 1 }),
+		kind: Optional(String$1({
+			minLength: 1,
+			maxLength: 100
+		})),
+		title: Optional(String$1({
+			minLength: 1,
+			maxLength: 255
+		})),
+		contentType: Optional(String$1({
+			minLength: 1,
+			maxLength: 200
+		}))
+	}, { additionalProperties: false }))
 }, {
 	$id: "TaskRef",
 	additionalProperties: false
@@ -14163,6 +14324,7 @@ var TaskBuilder = class {
 				message: "reference is missing required outputCid"
 			}]);
 			ref = {
+				...s,
 				taskId: s.taskId ?? null,
 				outputCid: s.outputCid,
 				role
@@ -14172,6 +14334,60 @@ var TaskBuilder = class {
 		return this;
 	}
 	/**
+	* Add a reference to a persistent task artifact while retaining the accepted
+	* output CID as the provenance anchor.
+	*
+	* @param source - A result reader, raw artifact reference, or `TaskRef`.
+	* @param role - The role the referenced artifact plays.
+	* @returns This builder, for chaining.
+	* @throws {TaskBuildError} when output or artifact CID is missing.
+	*/
+	artifactReference(source, role) {
+		let ref;
+		if ("artifactRef" in source && typeof source.artifactRef === "function") ref = source.artifactRef(role);
+		else if ("artifact" in source && source.artifact?.cid) {
+			if (typeof source.artifact.attemptN !== "number" || !Number.isInteger(source.artifact.attemptN) || source.artifact.attemptN < 1) throw new TaskBuildError([{
+				field: "references/artifact/attemptN",
+				message: "artifact reference is missing required attemptN"
+			}]);
+			ref = {
+				...source,
+				role
+			};
+		} else {
+			const s = source;
+			const errors = [];
+			if (!s.outputCid) errors.push({
+				field: "references/outputCid",
+				message: "reference is missing required outputCid"
+			});
+			if (!s.artifactCid) errors.push({
+				field: "references/artifact/cid",
+				message: "artifact reference is missing required cid"
+			});
+			if (typeof s.attemptN !== "number" || !Number.isInteger(s.attemptN) || s.attemptN < 1) errors.push({
+				field: "references/artifact/attemptN",
+				message: "artifact reference is missing required attemptN"
+			});
+			if (errors.length > 0) throw new TaskBuildError(errors);
+			const attemptN = s.attemptN;
+			ref = {
+				taskId: s.taskId ?? null,
+				outputCid: s.outputCid,
+				role,
+				artifact: {
+					cid: s.artifactCid,
+					attemptN,
+					...s.kind ? { kind: s.kind } : {},
+					...s.title ? { title: s.title } : {},
+					...s.contentType ? { contentType: s.contentType } : {}
+				}
+			};
+		}
+		this.refs.push(ref);
+		return this;
+	}
+	/**
 	* Set the owning team (required by the wire schema).
 	*
 	* @param teamId - Team UUID.
@@ -14549,6 +14765,34 @@ var TaskResultReader = class {
 			role
 		};
 	}
+	/**
+	* Build a `TaskRef` that anchors a downstream task to this accepted output
+	* and points at one persistent task artifact by CID.
+	*
+	* @param filter - Artifact object or a filter resolved against output artifacts.
+	* @param role - The role this artifact plays in the downstream task.
+	* @returns A `TaskRef` with `artifact.cid` populated.
+	* @throws {TaskResultError} if no matching artifact has a CID.
+	*/
+	artifactRef(filter, role) {
+		const artifact = typeof filter === "object" && "cid" in filter && "kind" in filter ? filter : this.artifact(filter);
+		if (!artifact?.cid) throw new TaskResultError([{
+			field: "artifacts/cid",
+			message: "no matching artifact with a cid"
+		}]);
+		return {
+			taskId: this.taskId,
+			outputCid: this.outputCid,
+			role,
+			artifact: {
+				cid: artifact.cid,
+				attemptN: this.accepted.attemptN,
+				kind: artifact.kind,
+				title: artifact.title,
+				...artifact.contentType ? { contentType: artifact.contentType } : {}
+			}
+		};
+	}
 };
 /**
 * Validate and construct a {@link TaskResultReader} from a task and its
@@ -14573,6 +14817,63 @@ function createTasksNamespace(context) {
 				auth
 			}));
 		},
+		artifacts: {
+			async upload(path, body, query, options) {
+				return unwrapResult(await uploadTaskArtifact({
+					auth,
+					body,
+					client,
+					duplex: "half",
+					headers: {
+						...requiredTeamHeaders(options),
+						"content-type": "application/octet-stream"
+					},
+					path,
+					query
+				}));
+			},
+			async list(taskId, options, query) {
+				return unwrapResult(await listTaskArtifacts({
+					client,
+					auth,
+					headers: requiredTeamHeaders(options),
+					path: { taskId },
+					query
+				})).artifacts;
+			},
+			async listPage(taskId, query, options) {
+				return unwrapResult(await listTaskArtifacts({
+					client,
+					auth,
+					headers: requiredTeamHeaders(options),
+					path: { taskId },
+					query
+				}));
+			},
+			async download(path, options) {
+				const result = await client.request({
+					auth,
+					headers: requiredTeamHeaders(options),
+					method: "GET",
+					parseAs: "stream",
+					path,
+					security: [{
+						scheme: "bearer",
+						type: "http"
+					}],
+					url: "/tasks/{taskId}/attempts/{attemptN}/artifacts/{cid}/content"
+				});
+				const normalizedStream = normalizeDownloadStream(unwrapResult(result));
+				if (normalizedStream) return {
+					artifactId: header(result.response, "x-moltnet-task-artifact-id"),
+					cid: header(result.response, "x-moltnet-task-artifact-cid"),
+					contentEncoding: header(result.response, "x-moltnet-task-artifact-content-encoding"),
+					contentType: header(result.response, "x-moltnet-task-artifact-content-type"),
+					stream: normalizedStream
+				};
+				throw new MoltNetError("Unexpected task artifact download response stream", { code: "INVALID_RESPONSE" });
+			}
+		},
 		async list(query, options) {
 			return unwrapResult(await listTasks({
 				client,
@@ -14741,6 +15042,33 @@ function createTasksNamespace(context) {
 		}
 	};
 }
+function header(response, name) {
+	const value = response?.headers.get(name) ?? null;
+	return value === "" ? null : value;
+}
+function normalizeDownloadStream(stream) {
+	if (isAsyncIterable(stream)) return stream;
+	if (isReadableStream(stream)) return readableStreamToAsyncIterable(stream);
+	return null;
+}
+function isAsyncIterable(value) {
+	return typeof value === "object" && value !== null && Symbol.asyncIterator in value && typeof value[Symbol.asyncIterator] === "function";
+}
+function isReadableStream(value) {
+	return typeof value === "object" && value !== null && "getReader" in value && typeof value.getReader === "function";
+}
+async function* readableStreamToAsyncIterable(stream) {
+	const reader = stream.getReader();
+	try {
+		while (true) {
+			const result = await reader.read();
+			if (result.done) return;
+			yield result.value;
+		}
+	} finally {
+		reader.releaseLock();
+	}
+}
 //#endregion
 //#region ../sdk/src/namespaces/teams.ts
 function createTeamsNamespace(context) {
@@ -17212,6 +17540,20 @@ function shouldAutoApproveHostExec(params, config) {
 	if (!Array.isArray(policy)) return false;
 	return policy.some((rule) => hostExecMatchesAutoApproveRule(params, rule));
 }
+async function resolveWorkspaceFilePath(cwd, filePath) {
+	const resolved = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(cwd, filePath);
+	const [realCwd, realResolved] = await Promise.all([realpath(cwd), realpath(resolved)]);
+	const rel = path.relative(realCwd, realResolved);
+	if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) throw new Error(`task artifact path escapes workspace: ${filePath}`);
+	return realResolved;
+}
+async function resolveWorkspaceOutputPath(cwd, filePath) {
+	const resolved = path.isAbsolute(filePath) ? path.resolve(filePath) : path.resolve(cwd, filePath);
+	const [realCwd, realParent] = await Promise.all([realpath(cwd), realpath(path.dirname(resolved))]);
+	const rel = path.relative(realCwd, realParent);
+	if (rel.startsWith("..") || path.isAbsolute(rel)) throw new Error(`task artifact output path escapes workspace: ${filePath}`);
+	return resolved;
+}
 /**
 * Expand the `taskFilter` shorthand on the diary list/search tools into
 * the matching `task:*` provenance tags emitted by `moltnet_create_entry`
@@ -17696,6 +18038,127 @@ function createMoltNetTools(config) {
 			};
 		}
 	});
+	const uploadTaskArtifact = defineTool({
+		name: "moltnet_upload_task_artifact",
+		label: "Upload MoltNet Task Artifact",
+		description: "Upload a file from the current task workspace as an immutable task artifact. Only available during an active task attempt; the tool attaches the artifact to the active taskId/attemptN and returns metadata including cid, sizeBytes, kind, and title. Use this for large logs, reports, build outputs, screenshots, generated files, or other bytes that should be referenced by CID instead of pasted into structured task output.",
+		parameters: Type.Object({
+			filePath: Type.String({ description: "Path to a file under the current task workspace. Relative paths are resolved from the workspace root." }),
+			kind: Type.String({ description: "Artifact category, e.g. log, report, patch, screenshot, bundle, dataset, trace." }),
+			title: Type.String({ description: "Human-readable artifact title, usually the file name." }),
+			contentType: Type.Optional(Type.String({ description: "MIME type. Defaults to application/octet-stream when omitted." })),
+			contentEncoding: Type.Optional(Type.String({ description: "Optional content encoding if the file is already encoded, e.g. gzip." }))
+		}),
+		async execute(_id, params) {
+			const { agent, teamId } = ensureConnected(config);
+			if (!teamId) throw new Error("moltnet_upload_task_artifact requires a team context");
+			const taskCtx = config.getTaskContext?.() ?? null;
+			if (!taskCtx) throw new Error("moltnet_upload_task_artifact is only available during an active task attempt");
+			const cwd = config.getHostCwd?.() ?? process.cwd();
+			const resolved = await resolveWorkspaceFilePath(cwd, params.filePath);
+			const info = await stat(resolved);
+			if (!info.isFile()) throw new Error(`task artifact path is not a file: ${params.filePath}`);
+			const artifact = await agent.tasks.artifacts.upload({
+				taskId: taskCtx.taskId,
+				attemptN: taskCtx.attemptN
+			}, createReadStream(resolved), {
+				kind: params.kind,
+				title: params.title,
+				contentType: params.contentType ?? "application/octet-stream",
+				contentEncoding: params.contentEncoding
+			}, { teamId });
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({
+						...artifact,
+						filePath: path.relative(cwd, resolved),
+						localSizeBytes: info.size
+					}, null, 2)
+				}],
+				details: {}
+			};
+		}
+	});
+	const listTaskArtifacts = defineTool({
+		name: "moltnet_list_task_artifacts",
+		label: "List MoltNet Task Artifacts",
+		description: "List immutable artifacts attached to a task, including each artifact CID, attempt number, kind, title, content type, size, uploader, and creation time. Use this when judging or continuing work that references task artifacts.",
+		parameters: Type.Object({
+			taskId: Type.Optional(Type.String({ description: "Task ID. Defaults to the active task when running inside a task attempt." })),
+			limit: Type.Optional(Type.Integer({
+				minimum: 1,
+				maximum: 100,
+				description: "Maximum artifacts to return. Defaults to the server page size."
+			})),
+			cursor: Type.Optional(Type.String({ description: "Pagination cursor returned by a previous moltnet_list_task_artifacts call." }))
+		}),
+		async execute(_id, params) {
+			const { agent, teamId } = ensureConnected(config);
+			if (!teamId) throw new Error("moltnet_list_task_artifacts requires a team context");
+			const taskId = params.taskId ?? config.getTaskContext?.()?.taskId;
+			if (!taskId) throw new Error("moltnet_list_task_artifacts requires taskId outside an active task");
+			const page = await agent.tasks.artifacts.listPage(taskId, {
+				cursor: params.cursor,
+				limit: params.limit
+			}, { teamId });
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify(page, null, 2)
+				}],
+				details: {}
+			};
+		}
+	});
+	const downloadTaskArtifact = defineTool({
+		name: "moltnet_download_task_artifact",
+		label: "Download MoltNet Task Artifact",
+		description: "Download immutable task artifact bytes by taskId, attemptN, and CID into a new file in the current task workspace. Use moltnet_list_task_artifacts first to choose the correct CID for referenced task inputs.",
+		parameters: Type.Object({
+			taskId: Type.Optional(Type.String({ description: "Task ID. Defaults to the active task when running inside a task attempt." })),
+			attemptN: Type.Integer({
+				minimum: 1,
+				description: "Attempt number that produced the artifact."
+			}),
+			cid: Type.String({
+				minLength: 1,
+				description: "Artifact CID returned by moltnet_list_task_artifacts."
+			}),
+			outputPath: Type.String({ description: "New file path under the current task workspace. The tool refuses to overwrite existing files." })
+		}),
+		async execute(_id, params) {
+			const { agent, teamId } = ensureConnected(config);
+			if (!teamId) throw new Error("moltnet_download_task_artifact requires a team context");
+			const taskId = params.taskId ?? config.getTaskContext?.()?.taskId;
+			if (!taskId) throw new Error("moltnet_download_task_artifact requires taskId outside an active task");
+			const cwd = config.getHostCwd?.() ?? process.cwd();
+			const outputPath = await resolveWorkspaceOutputPath(cwd, params.outputPath);
+			const download = await agent.tasks.artifacts.download({
+				taskId,
+				attemptN: params.attemptN,
+				cid: params.cid
+			}, { teamId });
+			await pipeline(download.stream, createWriteStream(outputPath, { flags: "wx" }));
+			const info = await stat(outputPath);
+			return {
+				content: [{
+					type: "text",
+					text: JSON.stringify({
+						taskId,
+						attemptN: params.attemptN,
+						cid: params.cid,
+						artifactId: download.artifactId,
+						contentType: download.contentType,
+						contentEncoding: download.contentEncoding,
+						outputPath: path.relative(cwd, outputPath),
+						sizeBytes: info.size
+					}, null, 2)
+				}],
+				details: {}
+			};
+		}
+	});
 	const reviewSessionErrors = defineTool({
 		name: "moltnet_review_session_errors",
 		label: "Review Session Tool Errors",
@@ -17745,6 +18208,9 @@ function createMoltNetTools(config) {
 		getTask,
 		listTaskAttempts,
 		listTaskMessages,
+		uploadTaskArtifact,
+		listTaskArtifacts,
+		downloadTaskArtifact,
 		reviewSessionErrors,
 		defineTool({
 			name: "moltnet_host_exec",
@@ -18559,11 +19025,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 +19041,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 +19072,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 +19133,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);
@@ -19154,6 +19874,18 @@ function buildFinalOutputBlock(opts) {
 		`Your final assistant text before that tool call may explain your work,`,
 		`but the submit-tool call itself must be your VERY LAST action.`,
 		"",
+		`Task artifacts: when you produce large files, binary files, logs, reports,`,
+		`screenshots, traces, bundles, or datasets, save them in the task workspace`,
+		`and call \`moltnet_upload_task_artifact\` before the submit-output tool.`,
+		`Put the returned artifact CID in the structured output where the schema`,
+		`allows artifact metadata (for example \`artifacts[].cid\`). Do not paste`,
+		`large bytes into structured output.`,
+		"",
+		`Referenced inputs: if this task depends on prior task artifacts, call`,
+		`\`moltnet_list_task_artifacts\` for the referenced task and download the`,
+		`specific CID you need with \`moltnet_download_task_artifact\` before judging`,
+		`or continuing that work.`,
+		"",
 		`Output shape:`,
 		"",
 		"```json",
@@ -24292,7 +25024,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 +25516,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 +25527,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 +25809,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 +26341,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 +26454,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.29.0",
   "type": "module",
   "description": "MoltNet pi extension — sandboxed tool execution in Gondolin VMs with MoltNet identity and persistent memory",
   "keywords": [
@@ -36,8 +36,8 @@
     "@earendil-works/gondolin": "^0.9.1",
     "@opentelemetry/api": "^1.9.0",
     "typebox": "^1.2.8",
-    "@themoltnet/agent-runtime": "0.31.1",
-    "@themoltnet/sdk": "0.114.0"
+    "@themoltnet/agent-runtime": "0.32.0",
+    "@themoltnet/sdk": "0.115.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.74.0",