@themoltnet/pi-extension 0.28.1 → 0.30.0

package/dist/index.d.ts

@@ -6,6 +6,7 @@ import { EditOperations } from '@earendil-works/pi-coding-agent';
 import { ExtensionAPI } from '@earendil-works/pi-coding-agent';
 import { LoadSkillsResult } from '@earendil-works/pi-coding-agent';
 import { Model } from '@earendil-works/pi-ai';
+import { Readable } from 'node:stream';
 import { ReadOperations } from '@earendil-works/pi-coding-agent';
 import { Skill } from '@earendil-works/pi-coding-agent';
 import { Static } from 'typebox';
@@ -294,6 +295,8 @@ export declare interface ExecutePiTaskOptions {
     extraAllowedHosts?: string[];
     /** Sandbox overrides (env, VFS shadows, resources). */
     sandboxConfig?: SandboxConfig;
+    /** Host environment variable names to forward into the Pi VM. */
+    forwardEnv?: string[];
     /**
      * Forwarded to `buildTaskUserPrompt` for per-type builders. Static
      * across tasks. Today no built-in builder needs per-task `extras` —
@@ -481,6 +484,17 @@ declare interface MoltNetToolsConfig {
     clearSessionErrors(): void;
     /** Host working directory for host-exec commands (worktree path or cwd). */
     getHostCwd?(): string;
+    /**
+     * Optional workspace-file reader. Daemon/Gondolin callers provide this so
+     * artifact uploads see guest overlay writes that may not exist on the host
+     * mount path yet.
+     */
+    openWorkspaceFileForRead?(filePath: string): Promise<{
+        stream: Readable;
+        isFile: boolean;
+        sizeBytes?: number;
+        displayPath?: string;
+    }>;
     /**
      * Set of process.env keys that are safe to forward to host-exec child
      * processes. Configured at sandbox startup so the caller can include
@@ -762,6 +776,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]>;
@@ -965,6 +986,14 @@ export declare interface VmConfig {
     extraAllowedHosts?: string[];
     /** Full sandbox config (vfs shadows, env overrides). */
     sandboxConfig?: SandboxConfig;
+    /**
+     * Host environment variable names to copy into the VM process.
+     *
+     * Runtime profiles use this for provider API keys: `requiredEnv` proves the
+     * daemon host has the secret, and this allowlist forwards only those names
+     * into the guest without storing secret values in the profile.
+     */
+    forwardEnv?: string[];
     /** Abort resume/setup work, closing any live VM owned by resumeVm. */
     signal?: AbortSignal;
 }

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 path, { join, relative, sep } from "node:path";
+import { cpSync, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmSync, statSync } from "node:fs";
+import path, { isAbsolute, join, relative, resolve, sep } from "node:path";
 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({
@@ -2824,6 +2874,15 @@ function unwrapResult(result) {
 			networkError.stack = error.stack;
 			throw networkError;
 		}
+		const responseSummary = summarizeResponse(result.response);
+		if (responseSummary) {
+			const detail = stringifyUnknown(error);
+			throw new MoltNetError(`MoltNet API request failed with HTTP ${responseSummary.status} ${responseSummary.statusText}: ${detail}`, {
+				code: `HTTP_${responseSummary.status}`,
+				detail,
+				statusCode: responseSummary.status
+			});
+		}
 		throw new MoltNetError(`Unexpected error from MoltNet API: ${stringifyUnknown(error)}`, { code: "UNKNOWN" });
 	}
 	if (result.data === void 0) throw new MoltNetError("Unexpected empty response from MoltNet API", { code: "EMPTY_RESPONSE" });
@@ -2841,6 +2900,15 @@ function stringifyUnknown(value) {
 		return String(value);
 	}
 }
+function summarizeResponse(response) {
+	if (!response || typeof response !== "object") return null;
+	const candidate = response;
+	if (typeof candidate.status !== "number") return null;
+	return {
+		status: candidate.status,
+		statusText: typeof candidate.statusText === "string" && candidate.statusText ? candidate.statusText : "Error"
+	};
+}
 function unwrapRequired(result, message, code) {
 	if (result.error || !result.data) throw new MoltNetError(message, { code });
 	return result.data;
@@ -10073,6 +10141,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 +10498,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 +13981,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 +14342,7 @@ var TaskBuilder = class {
 				message: "reference is missing required outputCid"
 			}]);
 			ref = {
+				...s,
 				taskId: s.taskId ?? null,
 				outputCid: s.outputCid,
 				role
@@ -14172,6 +14352,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 +14783,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 +14835,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 +15060,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 +17558,43 @@ 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 = await realpath(cwd);
+	let realResolved;
+	try {
+		realResolved = await realpath(resolved);
+	} catch (err) {
+		if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") throw new Error(`task artifact input path does not exist: ${filePath}. Write the file before calling moltnet_upload_task_artifact.`);
+		throw err;
+	}
+	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 openWorkspaceArtifactInput(config, cwd, filePath) {
+	if (config.openWorkspaceFileForRead) try {
+		return await config.openWorkspaceFileForRead(filePath);
+	} catch (err) {
+		if (err && typeof err === "object" && "code" in err && err.code === "ENOENT") throw new Error(`task artifact input path does not exist: ${filePath}. Write the file before calling moltnet_upload_task_artifact.`);
+		throw err;
+	}
+	const resolved = await resolveWorkspaceFilePath(cwd, filePath);
+	const info = await stat(resolved);
+	return {
+		stream: createReadStream(resolved),
+		isFile: info.isFile(),
+		sizeBytes: info.size,
+		displayPath: path.relative(cwd, resolved)
+	};
+}
+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 +18079,125 @@ 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 input = await openWorkspaceArtifactInput(config, config.getHostCwd?.() ?? process.cwd(), params.filePath);
+			if (!input.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
+			}, input.stream, {
+				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: input.displayPath ?? params.filePath,
+						localSizeBytes: input.sizeBytes ?? null
+					}, 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 +18247,9 @@ function createMoltNetTools(config) {
 		getTask,
 		listTaskAttempts,
 		listTaskMessages,
+		uploadTaskArtifact,
+		listTaskArtifacts,
+		downloadTaskArtifact,
 		reviewSessionErrors,
 		defineTool({
 			name: "moltnet_host_exec",
@@ -18191,13 +18696,13 @@ async function delay(ms, signal, label) {
 //#endregion
 //#region src/vm-manager.ts
 /**
-* Memory-backed VFS mount used by the daemon to inject task-context
-* skills (#943 slice 1.5). This is a separate top-level mount because
-* Gondolin mounts can't nest. The agent's Gondolin-bound Read tool accepts
-* paths under this prefix (see toGuestPath in tool-operations.ts).
+* Memory-backed VFS mount used by the daemon to inject task context
+* (#943 slice 1.5). This is a separate top-level mount because Gondolin
+* mounts can't nest. The agent's Gondolin-bound Read tool accepts paths
+* under this prefix (see toGuestPath in tool-operations.ts).
 *
 * Why MemoryProvider rather than a path under the workspace mount:
-*   - Injected skills are ephemeral by intent: per-task-attempt input
+*   - Injected task context is ephemeral by intent: per-task-attempt input
 *     scoped to the VM lifetime. MemoryProvider models that exactly —
 *     in-memory, per-VM-instance, zero host artefacts, automatic
 *     cleanup on VM close.
@@ -18210,7 +18715,7 @@ async function delay(ms, signal, label) {
 *     and episodic 7affbfeb-18a2-4963-aeac-c177eb2afa2d for the full
 *     investigation and the alternatives we rejected.
 */
-var GUEST_TASK_SKILLS_MOUNT = "/moltnet-task-skills";
+var GUEST_TASK_CONTEXT_MOUNT = "/moltnet-task-context";
 function shouldRunResumeCommand(entry, ctx) {
 	if (typeof entry === "string") return true;
 	const workspaceModes = entry.when?.workspaceMode;
@@ -18374,10 +18879,17 @@ async function resumeVm(config) {
 			writeMode: vfsConfig.shadowMode ?? "tmpfs"
 		});
 	}
+	const forwardedEnv = {};
+	for (const name of config.forwardEnv ?? []) {
+		const value = process.env[name];
+		if (value === void 0 || value === "") continue;
+		forwardedEnv[name] = value;
+	}
 	const envOverrides = config.sandboxConfig?.env ?? {};
 	const vmEnv = {
 		...secretEnv,
 		...vmAgentEnv,
+		...forwardedEnv,
 		PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/lib/go/bin",
 		HOME: "/home/agent",
 		NODE_NO_WARNINGS: "1",
@@ -18395,7 +18907,7 @@ async function resumeVm(config) {
 			...resources?.cpus && { cpus: resources.cpus },
 			vfs: { mounts: {
 				[guestWorkspace]: workspaceProvider,
-				[GUEST_TASK_SKILLS_MOUNT]: new MemoryProvider()
+				[GUEST_TASK_CONTEXT_MOUNT]: new MemoryProvider()
 			} }
 		}),
 		signal: config.signal,
@@ -18594,9 +19106,9 @@ function toHostToolPath(localCwd, guestWorkspace, guestPath) {
 function toGuestPath(localCwd, localPath, guestWorkspace) {
 	const normalizedGuestWorkspace = normalizeGuestPath(guestWorkspace);
 	const normalizedLocalPath = normalizeGuestPath(localPath);
-	const normalizedTaskSkillsMount = normalizeGuestPath(GUEST_TASK_SKILLS_MOUNT);
+	const normalizedTaskContextMount = normalizeGuestPath(GUEST_TASK_CONTEXT_MOUNT);
 	if (isSameOrInsidePosixPath(normalizedLocalPath, normalizedGuestWorkspace)) return normalizedLocalPath;
-	if (isSameOrInsidePosixPath(normalizedLocalPath, normalizedTaskSkillsMount)) return normalizedLocalPath;
+	if (isSameOrInsidePosixPath(normalizedLocalPath, normalizedTaskContextMount)) return normalizedLocalPath;
 	const rel = path.relative(localCwd, localPath);
 	if (rel === "") return normalizedGuestWorkspace;
 	if (rel.startsWith("..") || path.isAbsolute(rel)) throw new Error(`path escapes workspace: ${localPath}`);
@@ -19296,9 +19808,9 @@ function formatInlineContextBlock(slug, content) {
 		"The following raw context was supplied by the task creator. Treat it",
 		"as task-relevant background that may override generic coding instincts",
 		"when it contains repo- or workflow-specific constraints.",
-		"The same content is also materialized in the workspace as",
-		"`context-pack.md` and mirrored in `AGENTS.md` for",
-		"repo-context discovery.",
+		"The same content may also be materialized by the runtime under",
+		"`/moltnet-task-context/context` for tool-based inspection. Do not",
+		"create or rely on workspace mirror files for this task context.",
 		"",
 		"<context>",
 		content,
@@ -19408,6 +19920,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",
@@ -20599,7 +21123,7 @@ function buildRunEvalUserPrompt(input, ctx) {
 		"`// note:` line, the task summary, or the `verification` field is",
 		"NOT following the task. If the constraint affects behavior, it",
 		"must affect behavior.",
-		hasInlineContext ? "For `context_inline`, your FIRST content-inspection step is a `read` of `context-pack.md` in the workspace root before your first `write` call. The same content is also mirrored in `AGENTS.md` and may be referenced from `.claude/CLAUDE.md`." : "When the context is delivered as a skill, inspect it before solving.",
+		hasInlineContext ? "For `context_inline`, your FIRST content-inspection step is to read the injected context block in this prompt or, when available, the matching file under `/moltnet-task-context/context` before your first `write` call. Do not create or rely on workspace mirror files for injected context." : "When the context is delivered as a skill, inspect it before solving.",
 		"If the Injected Task Context contains repo- or workflow-specific",
 		"rules, those rules override your generic instincts."
 	].join("\n") : "";
@@ -22739,7 +23263,7 @@ var require_transport = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 	var { createRequire: createRequire$1 } = __require("module");
 	var { existsSync: existsSync$1 } = __require("node:fs");
 	var getCallers = require_caller();
-	var { join: join$1, isAbsolute, sep: sep$1 } = __require("node:path");
+	var { join: join$1, isAbsolute: isAbsolute$1, sep: sep$1 } = __require("node:path");
 	var { fileURLToPath } = __require("node:url");
 	var sleep = require_atomic_sleep();
 	var onExit = require_on_exit_leak_free();
@@ -22800,7 +23324,7 @@ var require_transport = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		} catch {
 			return false;
 		}
-		return isAbsolute(path) && !existsSync$1(path);
+		return isAbsolute$1(path) && !existsSync$1(path);
 	}
 	function stripQuotes(value) {
 		const first = value[0];
@@ -22903,7 +23427,7 @@ var require_transport = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 		return buildStream(fixTarget(target), options, worker, sync, name);
 		function fixTarget(origin) {
 			origin = bundlerOverrides[origin] || origin;
-			if (isAbsolute(origin) || origin.indexOf("file://") === 0) return origin;
+			if (isAbsolute$1(origin) || origin.indexOf("file://") === 0) return origin;
 			if (origin === "pino/file") return join$1(__dirname, "..", "file.js");
 			let fixTarget;
 			for (const filePath of callers) try {
@@ -24254,20 +24778,21 @@ var require_multistream = /* @__PURE__ */ __commonJSMin(((exports, module) => {
 *      system prompt; the agent fetches the body on demand via the
 *      Read tool.
 *
-* Skill files are written into a memory-backed VM mount. pi only reads
-* `<available_skills>` metadata (name, description, location), never the file
+* Task-context files are written into a memory-backed VM mount. pi only reads
+* `<available_skills>` metadata (name, description, location), never the skill
 * body, so we construct synthetic `Skill` objects pointing at the in-VM path
 * without ever materialising the file on the host.
 */
 /**
-* Where in the VM we write skill bodies — the memory-backed mount
+* Where in the VM we write task-context bodies — the memory-backed mount
 * declared in `vm-manager.ts`. See the comment on
-* `GUEST_TASK_SKILLS_MOUNT` there for the full rationale (ephemeral
-* by intent + the worktree symlink interaction with Gondolin's
-* sandbox-escape protection). The agent's Gondolin Read tool accepts
-* paths under this mount via `toGuestPath` in `tool-operations.ts`.
+* `GUEST_TASK_CONTEXT_MOUNT` there for the full rationale (ephemeral by
+* intent + the worktree symlink interaction with Gondolin's sandbox-escape
+* protection). The agent's Gondolin Read tool accepts paths under this mount
+* via `toGuestPath` in `tool-operations.ts`.
 */
-var SKILL_ROOT_IN_VM = GUEST_TASK_SKILLS_MOUNT;
+var SKILL_ROOT_IN_VM = `${GUEST_TASK_CONTEXT_MOUNT}/skills`;
+var INLINE_CONTEXT_ROOT_IN_VM = `${GUEST_TASK_CONTEXT_MOUNT}/context`;
 /** Bounds borrowed from pi's skill validation; conservative caps so a
 *  malformed SKILL.md doesn't bloat the system prompt. */
 var MAX_SKILL_NAME = 64;
@@ -24278,13 +24803,7 @@ var MAX_SKILL_DESCRIPTION = 1024;
 */
 async function injectTaskContext(args) {
 	const skills = [];
-	const inlineContexts = [];
-	const { guestWorkspace } = args;
-	const inlineContextRoot = `${guestWorkspace}/.moltnet/context`;
-	const workspaceContextPack = `${guestWorkspace}/context-pack.md`;
-	const workspaceAgentsMd = `${guestWorkspace}/AGENTS.md`;
-	const workspaceClaudeDir = `${guestWorkspace}/.claude`;
-	const workspaceClaudeMd = `${workspaceClaudeDir}/CLAUDE.md`;
+	args.guestWorkspace;
 	const resolved = await resolveTaskContext({
 		context: args.context,
 		deliver: {
@@ -24301,23 +24820,12 @@ async function injectTaskContext(args) {
 				}));
 			},
 			contextFile: async ({ suggestedFileName, content }) => {
-				await args.fs.mkdir(inlineContextRoot, { recursive: true });
-				const filePath = `${inlineContextRoot}/${suggestedFileName}`;
+				await args.fs.mkdir(INLINE_CONTEXT_ROOT_IN_VM, { recursive: true });
+				const filePath = `${INLINE_CONTEXT_ROOT_IN_VM}/${suggestedFileName}`;
 				await args.fs.writeFile(filePath, content, { mode: 420 });
-				inlineContexts.push({
-					slug: suggestedFileName.replace(/\.md$/u, ""),
-					content
-				});
 			}
 		}
 	});
-	if (inlineContexts.length > 0) {
-		const packContent = buildWorkspaceContextPack(inlineContexts);
-		await args.fs.writeFile(workspaceContextPack, packContent, { mode: 420 });
-		await args.fs.writeFile(workspaceAgentsMd, packContent, { mode: 420 });
-		await args.fs.mkdir(workspaceClaudeDir, { recursive: true });
-		await args.fs.writeFile(workspaceClaudeMd, "@../context-pack.md\n", { mode: 420 });
-	}
 	return {
 		injected: resolved.injected,
 		skills,
@@ -24325,17 +24833,6 @@ async function injectTaskContext(args) {
 		userInlineSuffix: resolved.userInlineSuffix
 	};
 }
-function buildWorkspaceContextPack(contexts) {
-	return [
-		"# Context Pack",
-		"",
-		...contexts.map(({ slug, content }) => [
-			`## ${slug}`,
-			"",
-			content.trimEnd()
-		].join("\n"))
-	].join("\n\n").trimEnd() + "\n";
-}
 /**
 * Build a `Skill` object pi will faithfully render in
 * `<available_skills>`. We extract `name` and `description` from the
@@ -25049,6 +25546,17 @@ function shouldSkipSeedEntry(sourceEntry, entryName, resolvedTargetDir) {
 * `AgentRuntime`.
 */
 var noopTurnEventHandler = () => {};
+async function openVmWorkspaceFileForRead(config) {
+	const localPath = isAbsolute(config.filePath) ? config.filePath : resolve(config.cwdPath, config.filePath);
+	const guestPath = toGuestPath(config.cwdPath, localPath, config.guestWorkspace);
+	const info = await config.vm.fs.stat(guestPath);
+	return {
+		stream: await config.vm.fs.readFileStream(guestPath),
+		isFile: info.isFile(),
+		sizeBytes: typeof info.size === "number" ? info.size : void 0,
+		displayPath: config.filePath
+	};
+}
 function createGondolinToolDefinitions(config) {
 	const { vm, mountPath, guestWorkspace } = config;
 	const grepTool = createGrepToolDefinition(mountPath);
@@ -25225,6 +25733,7 @@ async function executePiTask(claimedTask, reporter, opts) {
 				workspaceMode: workspace.mode,
 				extraAllowedHosts: opts.extraAllowedHosts,
 				sandboxConfig,
+				forwardEnv: opts.forwardEnv,
 				signal: reporter.cancelSignal
 			});
 		} catch (err) {
@@ -25240,9 +25749,11 @@ async function executePiTask(claimedTask, reporter, opts) {
 		const taskTeamId = task.teamId ?? "";
 		activateAgentEnv(managed.credentials.agentEnv, agentRootDir);
 		const activeWorkspace = workspace;
+		const activeManaged = managed;
 		if (!activeWorkspace) throw new Error("task workspace not prepared");
 		await emit("info", {
 			event: "execute_start",
+			correlationId: task.correlationId ?? null,
 			taskType: task.taskType,
 			teamId: task.teamId,
 			provider: opts.provider,
@@ -25295,6 +25806,7 @@ async function executePiTask(claimedTask, reporter, opts) {
 			taskPrompt = assembled.text;
 			await emit("info", {
 				event: "prompt_assembled",
+				correlationId: task.correlationId ?? null,
 				taskType: assembled.taskType,
 				sections: assembled.trace
 			});
@@ -25326,6 +25838,7 @@ async function executePiTask(claimedTask, reporter, opts) {
 		}
 		if (injectedContext.injected.length > 0) await emit("info", {
 			event: "context_injected",
+			correlationId: task.correlationId ?? null,
 			count: injectedContext.injected.length,
 			bindings: injectedContext.injected.map((r) => r.binding),
 			slugs: injectedContext.injected.map((r) => r.slug)
@@ -25350,6 +25863,12 @@ async function executePiTask(claimedTask, reporter, opts) {
 				getSessionErrors: () => [],
 				clearSessionErrors: () => {},
 				getHostCwd: () => cwdPath,
+				openWorkspaceFileForRead: (filePath) => openVmWorkspaceFileForRead({
+					vm: activeManaged.vm,
+					cwdPath,
+					guestWorkspace: activeManaged.guestWorkspace,
+					filePath
+				}),
 				hostExecBaseEnv: new Set([...HOST_EXEC_DEFAULT_BASE_ENV, ...Object.keys(managed.credentials.agentEnv)]),
 				hostExecAutoApprove: opts.hostExecAutoApprove ?? opts.sandboxConfig?.hostExec?.autoApprove ?? false,
 				getTaskContext: () => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/pi-extension",
-  "version": "0.28.1",
+  "version": "0.30.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.33.0",
+    "@themoltnet/sdk": "0.116.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.74.0",