@themoltnet/node-red-contrib-core 0.3.3 → 0.6.0

package/README.md

@@ -15,12 +15,19 @@ Empirically validated against **Node-RED 5.0.0** (Node 22):
   package carries no private-package runtime dependency. `@themoltnet/sdk` is
   therefore a **devDependency** (bundled, not installed at runtime).
 - The `.html` editor files are copied to `dist/nodes/` as assets (not compiled).
-- Two **config nodes** (`moltnet-agent`, `moltnet-runtime-profile`) and eight
+- Two **config nodes** (`moltnet-agent`, `moltnet-runtime-profile`) and eleven
   **action nodes** (`moltnet-tasks-create`, `moltnet-task-get`,
-  `moltnet-task-wait`, `moltnet-workflow-status`, `moltnet-task-builder`,
-  `moltnet-task-reader`, `moltnet-tasks-list`, `moltnet-entries-search`)
+  `moltnet-task-wait`, `moltnet-task-artifacts-list`,
+  `moltnet-task-artifact-upload`, `moltnet-task-artifact-download`,
+  `moltnet-workflow-status`, `moltnet-task-builder`, `moltnet-task-reader`,
+  `moltnet-tasks-list`, `moltnet-entries-search`)
   register and appear in the palette.
 
+For editor styling, install the separate companion package
+`@themoltnet/node-red-theme`. The theme is intentionally not bundled with these
+runtime nodes so it can be used independently by Node-RED instances that only
+want the MoltNet editor skin.
+
 ## Nodes
 
 - **`moltnet-agent`** (config) — holds one MoltNet agent identity (OAuth2 client
@@ -57,6 +64,21 @@ attempts, error, task }`. `state` is the accepted attempt's output artifact
   snapshot once. On failure the snapshot's `error` carries the last attempt's
   error for an agent/human to interpret (retry vs. escalate) — the same hook the
   `issue-lifecycle` supervisor uses.
+- **`moltnet-task-artifacts-list`** (palette: _task artifacts: list_) — lists a
+  task's artifacts for the configured team. Reads task id from
+  `msg.taskId`/`msg.payload.taskId`/`msg.payload.id` or the node field, supports
+  `limit`/`cursor`, emits artifact rows on `msg.payload`, and places
+  pagination/query metadata on `msg.artifacts`.
+- **`moltnet-task-artifact-upload`** (palette: _task artifact: upload_) —
+  uploads bytes for a task attempt. Reads bytes from `msg.payload` when it is a
+  string/Buffer/Uint8Array/ArrayBuffer, or from object payload fields
+  `content`, `body`, or base64 `contentBase64`. Team context is the configured
+  node/agent by default; message team overrides require an explicit checkbox.
+  Emits artifact metadata on `msg.payload` and `msg.artifact`.
+- **`moltnet-task-artifact-download`** (palette: _task artifact: download_) —
+  downloads an artifact by task id, attempt number, and CID. Emits the artifact
+  bytes as a Buffer on `msg.payload` and metadata on `msg.artifact`. Upload and
+  download nodes enforce a local 25 MiB byte limit by default.
 - **`moltnet-workflow-status`** (palette: _workflow: status_) — reads the tasks of
   one workflow run (by `correlationId`) and emits a table-shaped `msg.payload`
   (array of `{ taskId, type, title, status, queuedAt, completedAt }`) plus

package/dist/nodes/src.js

@@ -2271,6 +2271,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({
@@ -10036,6 +10085,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
+});
 new TextEncoder();
 new TextDecoder();
 //#endregion
@@ -10295,6 +10435,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",
@@ -13765,7 +13909,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
@@ -14110,6 +14270,7 @@ var TaskBuilder = class {
 				message: "reference is missing required outputCid"
 			}]);
 			ref = {
+				...s,
 				taskId: s.taskId ?? null,
 				outputCid: s.outputCid,
 				role
@@ -14119,6 +14280,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.
@@ -14496,6 +14711,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
@@ -14520,6 +14763,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,
@@ -14688,6 +14988,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) {

package/dist/nodes/task-artifact-download.html

@@ -0,0 +1,86 @@
+<script type="text/javascript">
+  RED.nodes.registerType('moltnet-task-artifact-download', {
+    category: 'moltnet',
+    color: '#00d4c8',
+    paletteLabel: 'task artifact: download',
+    defaults: {
+      name: { value: '' },
+      agent: { value: '', type: 'moltnet-agent', required: true },
+      taskId: { value: '' },
+      teamId: { value: '' },
+      allowMsgTeamOverride: { value: false },
+      attemptN: { value: '', validate: RED.validators.number() },
+      maxBytes: { value: 26214400, validate: RED.validators.number() },
+      cid: { value: '' },
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: 'font-awesome/fa-download',
+    label: function () {
+      return this.name || 'task artifact: download';
+    },
+  });
+</script>
+
+<script type="text/html" data-template-name="moltnet-task-artifact-download">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-agent"><i class="fa fa-user"></i> Agent</label>
+    <input type="text" id="node-input-agent" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-taskId"><i class="fa fa-hashtag"></i> Task ID</label>
+    <input
+      type="text"
+      id="node-input-taskId"
+      placeholder="msg.payload.taskId"
+    />
+  </div>
+  <div class="form-row">
+    <label for="node-input-teamId"><i class="fa fa-users"></i> Team ID</label>
+    <input type="text" id="node-input-teamId" placeholder="agent teamId" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-allowMsgTeamOverride"
+      ><i class="fa fa-random"></i> Team override</label
+    >
+    <input
+      type="checkbox"
+      id="node-input-allowMsgTeamOverride"
+      style="display: inline-block; width: auto; vertical-align: top"
+    />
+    <span>Allow <code>msg.teamId</code></span>
+  </div>
+  <div class="form-row">
+    <label for="node-input-attemptN"
+      ><i class="fa fa-history"></i> Attempt</label
+    >
+    <input type="number" id="node-input-attemptN" placeholder="msg.attemptN" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-cid"><i class="fa fa-fingerprint"></i> CID</label>
+    <input type="text" id="node-input-cid" placeholder="msg.payload.cid" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-maxBytes"><i class="fa fa-database"></i> Max</label>
+    <input type="number" id="node-input-maxBytes" />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="moltnet-task-artifact-download">
+  <p>
+    Downloads a task artifact by task id, attempt number, and CID. CID is taken
+    from <code>msg.cid</code>, <code>msg.payload.cid</code>,
+    <code>msg.payload.artifact.cid</code>, or the configured CID. Team ID is
+    taken from this node or the configured agent unless Team override is
+    enabled.
+  </p>
+  <p>
+    Emits the artifact bytes as a Buffer on <code>msg.payload</code>. Download
+    metadata is placed on <code>msg.artifact</code>. The local byte limit
+    defaults to 25 MiB.
+  </p>
+</script>

package/dist/nodes/task-artifact-download.js

@@ -0,0 +1,75 @@
+import { a as nonEmpty, t as bool } from "./query-utils.js";
+import { a as requireAttemptContext, n as payloadRecord, r as recordField, s as resolveMaxBytes, t as collectArtifactBody } from "./task-artifact-utils.js";
+//#region src/nodes/task-artifact-download.ts
+var init = (RED) => {
+	function TaskArtifactDownloadNode(def) {
+		RED.nodes.createNode(this, def);
+		const agentNode = def.agent ? RED.nodes.getNode(def.agent) : null;
+		this.on("input", (msg, send, done) => {
+			const run = async () => {
+				try {
+					if (!agentNode || typeof agentNode.getAgent !== "function") throw new Error("task-artifact-download: no moltnet-agent configured");
+					const { taskId, teamId, attemptN } = requireAttemptContext("task-artifact-download", msg, def.taskId, def.teamId, def.attemptN, agentNode, bool(def.allowMsgTeamOverride) ?? false);
+					const cid = resolveCid(msg, def.cid);
+					if (!cid) throw new Error("task-artifact-download: cid is required");
+					this.status({
+						fill: "blue",
+						shape: "dot",
+						text: "downloading…"
+					});
+					const result = await (await agentNode.getAgent()).tasks.artifacts.download({
+						taskId,
+						attemptN,
+						cid
+					}, { teamId });
+					const body = await collectArtifactBody(result, resolveMaxBytes(def.maxBytes));
+					const out = RED.util.cloneMessage({
+						...msg,
+						payload: void 0
+					});
+					out.payload = body;
+					out.taskId = taskId;
+					out.artifact = {
+						taskId,
+						teamId,
+						attemptN,
+						cid,
+						...metadataFromResult(result)
+					};
+					this.status({
+						fill: "green",
+						shape: "dot",
+						text: `${body.byteLength} byte(s)`
+					});
+					send(out);
+					done();
+				} catch (err) {
+					this.status({
+						fill: "red",
+						shape: "ring",
+						text: "error"
+					});
+					done(err instanceof Error ? err : new Error(String(err)));
+				}
+			};
+			run();
+		});
+	}
+	RED.nodes.registerType("moltnet-task-artifact-download", TaskArtifactDownloadNode);
+};
+function resolveCid(msg, configured) {
+	if (typeof msg.cid === "string" && msg.cid) return msg.cid;
+	const payload = payloadRecord(msg);
+	return nonEmpty(payload.cid) ?? nonEmpty(recordField(payload.artifact, "cid")) ?? nonEmpty(configured);
+}
+function metadataFromResult(result) {
+	if (!result || typeof result !== "object") return {};
+	const record = result;
+	return {
+		artifactId: record.artifactId,
+		contentType: record.contentType,
+		contentEncoding: record.contentEncoding
+	};
+}
+//#endregion
+export { init as default };

package/dist/nodes/task-artifact-upload.html

@@ -0,0 +1,118 @@
+<script type="text/javascript">
+  RED.nodes.registerType('moltnet-task-artifact-upload', {
+    category: 'moltnet',
+    color: '#00d4c8',
+    paletteLabel: 'task artifact: upload',
+    defaults: {
+      name: { value: '' },
+      agent: { value: '', type: 'moltnet-agent', required: true },
+      taskId: { value: '' },
+      teamId: { value: '' },
+      allowMsgTeamOverride: { value: false },
+      attemptN: { value: '', validate: RED.validators.number() },
+      maxBytes: { value: 26214400, validate: RED.validators.number() },
+      kind: { value: 'output' },
+      title: { value: '' },
+      contentType: { value: 'application/octet-stream' },
+      contentEncoding: { value: '' },
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: 'font-awesome/fa-upload',
+    label: function () {
+      return this.name || 'task artifact: upload';
+    },
+  });
+</script>
+
+<script type="text/html" data-template-name="moltnet-task-artifact-upload">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-agent"><i class="fa fa-user"></i> Agent</label>
+    <input type="text" id="node-input-agent" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-taskId"><i class="fa fa-hashtag"></i> Task ID</label>
+    <input
+      type="text"
+      id="node-input-taskId"
+      placeholder="msg.payload.taskId"
+    />
+  </div>
+  <div class="form-row">
+    <label for="node-input-teamId"><i class="fa fa-users"></i> Team ID</label>
+    <input type="text" id="node-input-teamId" placeholder="agent teamId" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-allowMsgTeamOverride"
+      ><i class="fa fa-random"></i> Team override</label
+    >
+    <input
+      type="checkbox"
+      id="node-input-allowMsgTeamOverride"
+      style="display: inline-block; width: auto; vertical-align: top"
+    />
+    <span>Allow <code>msg.teamId</code></span>
+  </div>
+  <div class="form-row">
+    <label for="node-input-attemptN"
+      ><i class="fa fa-history"></i> Attempt</label
+    >
+    <input type="number" id="node-input-attemptN" placeholder="msg.attemptN" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-kind"><i class="fa fa-archive"></i> Kind</label>
+    <select id="node-input-kind">
+      <option value="output">Output</option>
+      <option value="input">Input</option>
+      <option value="log">Log</option>
+      <option value="other">Other</option>
+    </select>
+  </div>
+  <div class="form-row">
+    <label for="node-input-title"><i class="fa fa-font"></i> Title</label>
+    <input type="text" id="node-input-title" placeholder="summary.md" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-maxBytes"><i class="fa fa-database"></i> Max</label>
+    <input type="number" id="node-input-maxBytes" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-contentType"
+      ><i class="fa fa-file-o"></i> Type</label
+    >
+    <input
+      type="text"
+      id="node-input-contentType"
+      placeholder="text/markdown"
+    />
+  </div>
+  <div class="form-row">
+    <label for="node-input-contentEncoding"
+      ><i class="fa fa-compress"></i> Encoding</label
+    >
+    <input type="text" id="node-input-contentEncoding" placeholder="gzip" />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="moltnet-task-artifact-upload">
+  <p>
+    Uploads bytes as an artifact for a task attempt. Task id, attempt, kind,
+    title, content type, and content encoding can be supplied by the node fields
+    or matching fields on <code>msg.payload</code>. Team ID is taken from this
+    node or the configured agent unless Team override is enabled.
+  </p>
+  <p>
+    The body is read from <code>msg.payload</code> when it is a string, Buffer,
+    Uint8Array, or ArrayBuffer. Object payloads may provide
+    <code>content</code>, <code>body</code>, or base64
+    <code>contentBase64</code>. The local byte limit defaults to 25 MiB.
+  </p>
+  <p>
+    Emits the artifact metadata on <code>msg.payload</code> and
+    <code>msg.artifact</code>.
+  </p>
+</script>

package/dist/nodes/task-artifact-upload.js

@@ -0,0 +1,61 @@
+import { t as bool } from "./query-utils.js";
+import { a as requireAttemptContext, c as resolveUploadBody, o as resolveField, s as resolveMaxBytes } from "./task-artifact-utils.js";
+//#region src/nodes/task-artifact-upload.ts
+var init = (RED) => {
+	function TaskArtifactUploadNode(def) {
+		RED.nodes.createNode(this, def);
+		const agentNode = def.agent ? RED.nodes.getNode(def.agent) : null;
+		this.on("input", (msg, send, done) => {
+			const run = async () => {
+				try {
+					if (!agentNode || typeof agentNode.getAgent !== "function") throw new Error("task-artifact-upload: no moltnet-agent configured");
+					const { taskId, teamId, attemptN } = requireAttemptContext("task-artifact-upload", msg, def.taskId, def.teamId, def.attemptN, agentNode, bool(def.allowMsgTeamOverride) ?? false);
+					const body = resolveUploadBody(msg, resolveMaxBytes(def.maxBytes));
+					const query = buildUploadQuery(def, msg);
+					this.status({
+						fill: "blue",
+						shape: "dot",
+						text: "uploading…"
+					});
+					const artifact = await (await agentNode.getAgent()).tasks.artifacts.upload({
+						taskId,
+						attemptN
+					}, body, query, { teamId });
+					const out = RED.util.cloneMessage({
+						...msg,
+						payload: void 0
+					});
+					out.payload = artifact;
+					out.taskId = taskId;
+					out.artifact = artifact;
+					this.status({
+						fill: "green",
+						shape: "dot",
+						text: artifact.cid
+					});
+					send(out);
+					done();
+				} catch (err) {
+					this.status({
+						fill: "red",
+						shape: "ring",
+						text: "error"
+					});
+					done(err instanceof Error ? err : new Error(String(err)));
+				}
+			};
+			run();
+		});
+	}
+	RED.nodes.registerType("moltnet-task-artifact-upload", TaskArtifactUploadNode);
+};
+function buildUploadQuery(def, msg) {
+	return {
+		kind: resolveField(msg, "kind", def.kind) ?? "output",
+		title: resolveField(msg, "title", def.title) ?? "artifact",
+		contentType: resolveField(msg, "contentType", def.contentType) ?? "application/octet-stream",
+		contentEncoding: resolveField(msg, "contentEncoding", def.contentEncoding)
+	};
+}
+//#endregion
+export { init as default };

package/dist/nodes/task-artifact-utils.js

@@ -0,0 +1,149 @@
+import { a as nonEmpty, c as positiveInt } from "./query-utils.js";
+import { Readable } from "node:stream";
+import { Buffer } from "node:buffer";
+function payloadRecord(msg) {
+	if (!msg.payload || typeof msg.payload !== "object") return {};
+	if (Buffer.isBuffer(msg.payload)) return {};
+	return msg.payload;
+}
+function resolveTaskId(msg, configured) {
+	if (typeof msg.taskId === "string" && msg.taskId) return msg.taskId;
+	const payload = payloadRecord(msg);
+	return nonEmpty(payload.taskId) ?? nonEmpty(payload.id) ?? nonEmpty(recordField(payload.task, "id")) ?? nonEmpty(configured);
+}
+function resolveTeamId(msg, configured, agentNode, allowMsgTeamOverride) {
+	if (!allowMsgTeamOverride) return nonEmpty(configured) ?? agentNode.teamId;
+	if (typeof msg.teamId === "string" && msg.teamId) return msg.teamId;
+	return nonEmpty(payloadRecord(msg).teamId) ?? nonEmpty(configured) ?? agentNode.teamId;
+}
+function resolveAttemptN(msg, configured) {
+	const payload = payloadRecord(msg);
+	return positiveInt(msg.attemptN) ?? positiveInt(payload.attemptN) ?? positiveInt(recordField(payload.attempt, "attemptN")) ?? positiveInt(recordField(payload.artifact, "attemptN")) ?? positiveInt(configured);
+}
+function requireArtifactContext(nodeName, msg, configuredTaskId, configuredTeamId, agentNode, allowMsgTeamOverride) {
+	const taskId = resolveTaskId(msg, configuredTaskId);
+	if (!taskId) throw new Error(`${nodeName}: taskId is required`);
+	const teamId = resolveTeamId(msg, configuredTeamId, agentNode, allowMsgTeamOverride);
+	if (!teamId) throw new Error(`${nodeName}: teamId is required`);
+	return {
+		taskId,
+		teamId
+	};
+}
+function requireAttemptContext(nodeName, msg, configuredTaskId, configuredTeamId, configuredAttemptN, agentNode, allowMsgTeamOverride) {
+	const context = requireArtifactContext(nodeName, msg, configuredTaskId, configuredTeamId, agentNode, allowMsgTeamOverride);
+	const attemptN = resolveAttemptN(msg, configuredAttemptN);
+	if (!attemptN) throw new Error(`${nodeName}: attemptN is required`);
+	return {
+		...context,
+		attemptN
+	};
+}
+function resolveField(msg, name, configured) {
+	return nonEmpty(payloadRecord(msg)[name]) ?? nonEmpty(configured);
+}
+function resolveMaxBytes(configured) {
+	return positiveInt(configured) ?? 26214400;
+}
+function resolveUploadBody(msg, maxBytes) {
+	const payload = msg.payload;
+	if (Buffer.isBuffer(payload)) return enforceMaxBytes(payload, maxBytes);
+	if (payload instanceof Uint8Array) return enforceMaxBytes(payload, maxBytes);
+	if (payload instanceof ArrayBuffer) {
+		if (payload.byteLength > maxBytes) throw tooLarge("upload", maxBytes);
+		return new Uint8Array(payload);
+	}
+	if (typeof payload === "string") {
+		if (Buffer.byteLength(payload) > maxBytes) throw tooLarge("upload", maxBytes);
+		return new TextEncoder().encode(payload);
+	}
+	const record = payloadRecord(msg);
+	if (typeof record.contentBase64 === "string") {
+		const normalized = record.contentBase64.replace(/\s/g, "");
+		if (decodedBase64Length(normalized) > maxBytes) throw tooLarge("upload", maxBytes);
+		return Buffer.from(normalized, "base64");
+	}
+	const content = record.content ?? record.body;
+	if (Buffer.isBuffer(content)) return enforceMaxBytes(content, maxBytes);
+	if (content instanceof Uint8Array) return enforceMaxBytes(content, maxBytes);
+	if (content instanceof ArrayBuffer) {
+		if (content.byteLength > maxBytes) throw tooLarge("upload", maxBytes);
+		return new Uint8Array(content);
+	}
+	if (typeof content === "string") {
+		if (Buffer.byteLength(content) > maxBytes) throw tooLarge("upload", maxBytes);
+		return new TextEncoder().encode(content);
+	}
+	throw new Error("task-artifact-upload: payload content is required");
+}
+async function collectArtifactBody(value, maxBytes) {
+	const source = value && typeof value === "object" && "stream" in value ? value.stream : value;
+	if (Buffer.isBuffer(source)) {
+		if (source.byteLength > maxBytes) throw tooLarge("download", maxBytes);
+		return source;
+	}
+	if (source instanceof Uint8Array) {
+		if (source.byteLength > maxBytes) throw tooLarge("download", maxBytes);
+		return Buffer.from(source);
+	}
+	if (source instanceof ArrayBuffer) {
+		if (source.byteLength > maxBytes) throw tooLarge("download", maxBytes);
+		return Buffer.from(source);
+	}
+	if (typeof source === "string") {
+		if (Buffer.byteLength(source) > maxBytes) throw tooLarge("download", maxBytes);
+		return Buffer.from(source);
+	}
+	if (source instanceof Readable) {
+		const chunks = [];
+		let bytes = 0;
+		for await (const chunk of source) bytes = pushChunk(chunks, chunk, bytes, maxBytes);
+		return Buffer.concat(chunks);
+	}
+	if (source && typeof source === "object" && Symbol.asyncIterator in source) {
+		const chunks = [];
+		let bytes = 0;
+		for await (const chunk of source) bytes = pushChunk(chunks, chunk, bytes, maxBytes);
+		return Buffer.concat(chunks);
+	}
+	if (source && typeof source === "object" && "arrayBuffer" in source) {
+		const size = source.size;
+		if (typeof size === "number" && size > maxBytes) throw tooLarge("download", maxBytes);
+		const arrayBuffer = await source.arrayBuffer();
+		if (arrayBuffer.byteLength > maxBytes) throw tooLarge("download", maxBytes);
+		return Buffer.from(arrayBuffer);
+	}
+	throw new Error("task-artifact-download: unsupported artifact body");
+}
+function toBuffer(value) {
+	if (Buffer.isBuffer(value)) return value;
+	if (value instanceof Uint8Array) return Buffer.from(value);
+	if (value instanceof ArrayBuffer) return Buffer.from(value);
+	if (typeof value === "string") return Buffer.from(value);
+	return Buffer.from(String(value));
+}
+function recordField(value, key) {
+	if (!value || typeof value !== "object") return void 0;
+	return value[key];
+}
+function enforceMaxBytes(value, maxBytes) {
+	if (value.byteLength > maxBytes) throw tooLarge("upload", maxBytes);
+	return value;
+}
+function pushChunk(chunks, chunk, bytes, maxBytes) {
+	const next = toBuffer(chunk);
+	const total = bytes + next.byteLength;
+	if (total > maxBytes) throw tooLarge("download", maxBytes);
+	chunks.push(next);
+	return total;
+}
+function decodedBase64Length(value) {
+	if (!value) return 0;
+	const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
+	return Math.floor(value.length * 3 / 4) - padding;
+}
+function tooLarge(operation, maxBytes) {
+	return /* @__PURE__ */ new Error(`task-artifact-${operation}: artifact body exceeds ${maxBytes} bytes`);
+}
+//#endregion
+export { requireAttemptContext as a, resolveUploadBody as c, requireArtifactContext as i, payloadRecord as n, resolveField as o, recordField as r, resolveMaxBytes as s, collectArtifactBody as t };

package/dist/nodes/task-artifacts-list.html

@@ -0,0 +1,78 @@
+<script type="text/javascript">
+  RED.nodes.registerType('moltnet-task-artifacts-list', {
+    category: 'moltnet',
+    color: '#00d4c8',
+    paletteLabel: 'task artifacts: list',
+    defaults: {
+      name: { value: '' },
+      agent: { value: '', type: 'moltnet-agent', required: true },
+      taskId: { value: '' },
+      teamId: { value: '' },
+      allowMsgTeamOverride: { value: false },
+      limit: { value: 20, validate: RED.validators.number() },
+      cursor: { value: '' },
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: 'font-awesome/fa-list',
+    label: function () {
+      return this.name || 'task artifacts: list';
+    },
+  });
+</script>
+
+<script type="text/html" data-template-name="moltnet-task-artifacts-list">
+  <div class="form-row">
+    <label for="node-input-name"><i class="fa fa-tag"></i> Name</label>
+    <input type="text" id="node-input-name" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-agent"><i class="fa fa-user"></i> Agent</label>
+    <input type="text" id="node-input-agent" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-taskId"><i class="fa fa-hashtag"></i> Task ID</label>
+    <input
+      type="text"
+      id="node-input-taskId"
+      placeholder="msg.payload.taskId"
+    />
+  </div>
+  <div class="form-row">
+    <label for="node-input-teamId"><i class="fa fa-users"></i> Team ID</label>
+    <input type="text" id="node-input-teamId" placeholder="agent teamId" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-allowMsgTeamOverride"
+      ><i class="fa fa-random"></i> Team override</label
+    >
+    <input
+      type="checkbox"
+      id="node-input-allowMsgTeamOverride"
+      style="display: inline-block; width: auto; vertical-align: top"
+    />
+    <span>Allow <code>msg.teamId</code></span>
+  </div>
+  <div class="form-row">
+    <label for="node-input-limit"><i class="fa fa-hashtag"></i> Limit</label>
+    <input type="number" id="node-input-limit" />
+  </div>
+  <div class="form-row">
+    <label for="node-input-cursor"><i class="fa fa-forward"></i> Cursor</label>
+    <input type="text" id="node-input-cursor" />
+  </div>
+</script>
+
+<script type="text/html" data-help-name="moltnet-task-artifacts-list">
+  <p>
+    Lists artifacts for a MoltNet task. The task id is taken from
+    <code>msg.taskId</code>, <code>msg.payload.taskId</code>,
+    <code>msg.payload.id</code>, or the configured Task ID. Team ID is taken
+    from this node or the configured agent. Enable Team override to allow
+    <code>msg.teamId</code> or <code>msg.payload.teamId</code>.
+  </p>
+  <p>
+    Emits artifact rows on <code>msg.payload</code>. Pagination metadata, the
+    final query, and the full page are on <code>msg.artifacts</code>.
+  </p>
+</script>

package/dist/nodes/task-artifacts-list.js

@@ -0,0 +1,61 @@
+import { a as nonEmpty, c as positiveInt, n as compact, t as bool } from "./query-utils.js";
+import { i as requireArtifactContext, n as payloadRecord } from "./task-artifact-utils.js";
+//#region src/nodes/task-artifacts-list.ts
+var init = (RED) => {
+	function TaskArtifactsListNode(def) {
+		RED.nodes.createNode(this, def);
+		const agentNode = def.agent ? RED.nodes.getNode(def.agent) : null;
+		this.on("input", (msg, send, done) => {
+			const run = async () => {
+				try {
+					if (!agentNode || typeof agentNode.getAgent !== "function") throw new Error("task-artifacts-list: no moltnet-agent configured");
+					const { taskId, teamId } = requireArtifactContext("task-artifacts-list", msg, def.taskId, def.teamId, agentNode, bool(def.allowMsgTeamOverride) ?? false);
+					this.status({
+						fill: "blue",
+						shape: "dot",
+						text: "loading…"
+					});
+					const agent = await agentNode.getAgent();
+					const query = buildQuery(def, msg);
+					const page = await agent.tasks.artifacts.listPage(taskId, query, { teamId });
+					const out = RED.util.cloneMessage(msg);
+					out.payload = page.artifacts;
+					out.taskId = taskId;
+					out.artifacts = {
+						taskId,
+						teamId,
+						query,
+						count: page.artifacts.length,
+						nextCursor: page.nextCursor,
+						page
+					};
+					this.status({
+						fill: "green",
+						shape: "dot",
+						text: `${page.artifacts.length} artifact(s)`
+					});
+					send(out);
+					done();
+				} catch (err) {
+					this.status({
+						fill: "red",
+						shape: "ring",
+						text: "error"
+					});
+					done(err instanceof Error ? err : new Error(String(err)));
+				}
+			};
+			run();
+		});
+	}
+	RED.nodes.registerType("moltnet-task-artifacts-list", TaskArtifactsListNode);
+};
+function buildQuery(def, msg) {
+	const payload = payloadRecord(msg);
+	return compact({
+		limit: positiveInt(payload.limit) ?? positiveInt(def.limit),
+		cursor: nonEmpty(payload.cursor) ?? nonEmpty(def.cursor)
+	});
+}
+//#endregion
+export { init as default };

package/dist/nodes/task-reader.js

@@ -19,16 +19,13 @@ var init = (RED) => {
 				} : def.artifactKind : void 0;
 				let artifactBody;
 				const artifact = filter ? reader.artifact(filter) : void 0;
-				if (filter && artifact && typeof artifact.body === "string") try {
-					artifactBody = JSON.parse(artifact.body);
-				} catch {
-					artifactBody = void 0;
-				}
+				if (filter && artifact && typeof artifact.body === "string") artifactBody = reader.artifactBody(filter);
 				const out = RED.util.cloneMessage(msg);
 				out.payload = reader.output;
 				out.result = {
 					summary: reader.summary,
 					outputRef: reader.outputRef(role),
+					artifactRef: artifact?.cid !== void 0 ? reader.artifactRef(artifact, role) : void 0,
 					artifact,
 					artifactBody,
 					accepted: reader.accepted,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/node-red-contrib-core",
-  "version": "0.3.3",
+  "version": "0.6.0",
   "type": "module",
   "description": "Node-RED nodes for the MoltNet API",
   "keywords": [
@@ -27,6 +27,9 @@
       "moltnet-tasks-list": "dist/nodes/tasks-list.js",
       "moltnet-task-get": "dist/nodes/task-get.js",
       "moltnet-task-wait": "dist/nodes/task-wait.js",
+      "moltnet-task-artifacts-list": "dist/nodes/task-artifacts-list.js",
+      "moltnet-task-artifact-upload": "dist/nodes/task-artifact-upload.js",
+      "moltnet-task-artifact-download": "dist/nodes/task-artifact-download.js",
       "moltnet-workflow-status": "dist/nodes/workflow-status.js",
       "moltnet-task-builder": "dist/nodes/task-builder.js",
       "moltnet-task-reader": "dist/nodes/task-reader.js",
@@ -38,7 +41,7 @@
   },
   "main": "dist/nodes/agent.js",
   "dependencies": {
-    "@themoltnet/sdk": "0.114.0"
+    "@themoltnet/sdk": "0.115.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.0",