@themoltnet/pi-extension 0.28.1 → 0.29.0

package/dist/index.d.ts

@@ -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 { 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",
@@ -19408,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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/pi-extension",
-  "version": "0.28.1",
+  "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",