@themoltnet/node-red-contrib-core 0.11.0 → 0.12.0

package/README.md

@@ -15,10 +15,12 @@ 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 eleven
-  **action nodes** (`moltnet-tasks-create`, `moltnet-task-get`,
-  `moltnet-task-wait`, `moltnet-task-artifacts-list`,
-  `moltnet-task-artifact-upload`, `moltnet-task-artifact-download`,
+- Two **config nodes** (`moltnet-agent`, `moltnet-runtime-profile`) and the
+  MoltNet **action nodes** (`moltnet-tasks-create`, `moltnet-task-get`,
+  `moltnet-task-cancel`, `moltnet-task-wait`, `moltnet-task-artifacts-list`,
+  `moltnet-task-artifact-stage`, `moltnet-task-artifact-upload`,
+  `moltnet-task-artifact-download`, `moltnet-runtime-session-get`,
+  `moltnet-runtime-session-upload`, `moltnet-runtime-session-download`,
   `moltnet-workflow-status`, `moltnet-task-builder`, `moltnet-task-reader`,
   `moltnet-tasks-list`, `moltnet-entries-search`)
   register and appear in the palette.
@@ -80,10 +82,17 @@ attempts, error, task }`. `state` is the accepted attempt's output artifact
   `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-stage`** (palette: _task artifact: stage_) — stages
+  bytes for later binding as a task input artifact. It accepts the same payload
+  shapes and team controls as upload, but needs no task or attempt. The returned
+  metadata is emitted on `msg.payload` and `msg.artifact`; pass it to a task
+  builder's **References from** field.
 - **`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.
+  downloads an artifact by task id and CID. Set an attempt number for an exact
+  attempt artifact, or omit it to resolve the CID across the task, including a
+  bound input artifact. Emits the bytes as a Buffer on `msg.payload` and
+  metadata on `msg.artifact`. Stage, 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
@@ -92,9 +101,10 @@ attempts, error, task }`. `state` is the accepted attempt's output artifact
   `tasks.create` body from the SDK fluent builder (`buildFreeform`). Pure offline
   transform: reads `teamId`/`diaryId` from the referenced `agent` (with optional
   typedInput overrides), maps **context rows** (slug ← msg/flow/global/str/json),
-  binds a prior task's output via **References from** (a `msg`-path to an
-  `outputRef` from `task: read`), and toggles the **submit-output** / schema
-  gates. Emits the flat body on `msg.payload` for a downstream `tasks: create`
+  binds a prior task's output or staged input artifact via **References from**
+  (a `msg`-path to an `outputRef` from `task: read` or metadata from
+  `task artifact: stage`), and toggles the **submit-output** / schema gates.
+  Emits the flat body on `msg.payload` for a downstream `tasks: create`
   (the SDK's `{ body, teamId }` envelope is flattened to `{ ...body, teamId }`).
   Validation errors surface on the node (red ring).
 - **`moltnet-task-reader`** (palette: _task: read_) — parses a completed snapshot

package/dist/nodes/runtime-session-download.js

@@ -1,6 +1,6 @@
 import { t as withAgent } from "./agent-call.js";
 import { t as bool } from "./query-utils.js";
-import { a as requireAttemptContext, s as resolveMaxBytes, t as collectArtifactBody } from "./task-artifact-utils.js";
+import { a as requireAttemptContext, c as resolveMaxBytes, t as collectArtifactBody } from "./task-artifact-utils.js";
 //#region src/nodes/runtime-session-download.ts
 var init = (RED) => {
 	function RuntimeSessionDownloadNode(def) {

package/dist/nodes/runtime-session-upload.js

@@ -1,6 +1,6 @@
 import { t as withAgent } from "./agent-call.js";
 import { n as compact, 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";
+import { a as requireAttemptContext, c as resolveMaxBytes, s as resolveField, u as resolveUploadBody } from "./task-artifact-utils.js";
 //#region src/nodes/runtime-session-upload.ts
 var init = (RED) => {
 	function RuntimeSessionUploadNode(def) {

package/dist/nodes/src.js

@@ -1927,7 +1927,34 @@ var findLatestRuntimeSlotForAttempt = (options) => (options.client ?? client).ge
 	...options
 });
 /**
-* Queue asynchronous deletion of terminal tasks in bulk. By default, live, unauthorized, missing, and protected tasks are skipped. Set force: true with a reason to delete protected terminal tasks.
+* Stage immutable content-addressed artifact bytes for later binding as task input artifacts via task creation references. Creates no metadata row; staged bytes are not downloadable until bound to a task, and unbound objects are garbage-collected after a grace window.
+*/
+var stageTaskArtifact = (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: "/task-artifacts/staged",
+	...options,
+	headers: {
+		"Content-Type": "application/octet-stream",
+		...options.headers
+	}
+});
+/**
+* Queue asynchronous deletion of waiting, queued, and terminal tasks in bulk. By default, dispatched, running, unauthorized, missing, and protected tasks are skipped. Set force: true with a reason to delete protected terminal tasks.
 */
 var batchDeleteTasks = (options) => (options.client ?? client).delete({
 	security: [
@@ -9633,6 +9660,11 @@ var RuntimeProfileSandboxResumeCommand = Union([String$1({
 		maximum: 6e4
 	}))
 }, { additionalProperties: false })]);
+var RuntimeProfileAllowedHost = String$1({
+	minLength: 1,
+	maxLength: 255,
+	pattern: "^(?:\\*\\.)?(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)(?:\\.(?:[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?))*$"
+});
 var RuntimeProfileSandbox = _Object_({
 	snapshot: Optional(_Object_({
 		setupCommands: Optional(_Array_(String$1({
@@ -9649,6 +9681,10 @@ var RuntimeProfileSandbox = _Object_({
 			pattern: "^[0-9]+[KMGTP]?$"
 		}))
 	}, { additionalProperties: false })),
+	network: Optional(_Object_({
+		allowedHosts: Optional(_Array_(RuntimeProfileAllowedHost, { maxItems: 50 })),
+		allowedInternalHosts: Optional(_Array_(RuntimeProfileAllowedHost, { maxItems: 50 }))
+	}, { additionalProperties: false })),
 	resumeCommands: Optional(_Array_(RuntimeProfileSandboxResumeCommand, { maxItems: 30 })),
 	vfs: Optional(_Object_({
 		shadow: Optional(_Array_(String$1({
@@ -9992,7 +10028,7 @@ _Object_({
 * (server-side schema check). Self-assessment is a truthful self-rating,
 * NOT enforcement — `verification.passed=false` does not block /complete
 * and does not affect `acceptedAttemptN`. See
-* `docs/understand/agent-runtime.md` for the full producer/judge flow.
+* `docs/use/tasks-and-runtime.md` for the full producer/judge flow.
 *
 * **Binding evaluation** (judgment tasks: `assess_brief`, `judge_pack`).
 * A separate task whose IS the application of `successCriteria` to
@@ -10108,7 +10144,7 @@ _Object_({
 		id: String$1({ format: "uuid" }),
 		teamId: String$1({ format: "uuid" }),
 		taskId: String$1({ format: "uuid" }),
-		attemptN: Integer({ minimum: 1 }),
+		attemptN: Union([Integer({ minimum: 1 }), Null()]),
 		kind: String$1({
 			minLength: 1,
 			maxLength: 100
@@ -10130,7 +10166,7 @@ _Object_({
 			minLength: 1,
 			maxLength: 100
 		}),
-		createdByAgentId: String$1({ format: "uuid" }),
+		createdByAgentId: Union([String$1({ format: "uuid" }), Null()]),
 		expiresAt: Union([String$1({ format: "date-time" }), Null()]),
 		createdAt: String$1({ format: "date-time" })
 	}, { $id: "TaskArtifact" })),
@@ -10146,6 +10182,16 @@ _Object_({
 	$id: "ListTaskArtifactsQuery",
 	additionalProperties: false
 });
+var HeaderSafeContentType = String$1({
+	minLength: 1,
+	maxLength: 200,
+	pattern: "^[\\x21-\\x7e][\\x20-\\x7e]*$"
+});
+var HeaderSafeContentEncoding = String$1({
+	minLength: 1,
+	maxLength: 100,
+	pattern: "^[\\x21-\\x7e][\\x20-\\x7e]*$"
+});
 _Object_({
 	kind: String$1({
 		minLength: 1,
@@ -10155,14 +10201,8 @@ _Object_({
 		minLength: 1,
 		maxLength: 255
 	}),
-	contentType: Optional(String$1({
-		minLength: 1,
-		maxLength: 200
-	})),
-	contentEncoding: Optional(String$1({
-		minLength: 1,
-		maxLength: 100
-	}))
+	contentType: Optional(HeaderSafeContentType),
+	contentEncoding: Optional(HeaderSafeContentEncoding)
 }, {
 	$id: "UploadTaskArtifactQuery",
 	additionalProperties: false
@@ -10194,6 +10234,34 @@ _Object_({
 	$id: "TaskArtifactContentParams",
 	additionalProperties: false
 });
+_Object_({
+	contentType: Optional(HeaderSafeContentType),
+	contentEncoding: Optional(HeaderSafeContentEncoding)
+}, {
+	$id: "StageTaskArtifactQuery",
+	additionalProperties: false
+});
+_Object_({
+	cid: String$1({
+		minLength: 1,
+		maxLength: 100
+	}),
+	sizeBytes: Integer({ minimum: 0 }),
+	contentType: String$1({
+		minLength: 1,
+		maxLength: 200
+	})
+}, { $id: "StagedTaskArtifact" });
+_Object_({
+	taskId: String$1({ format: "uuid" }),
+	cid: String$1({
+		minLength: 1,
+		maxLength: 100
+	})
+}, {
+	$id: "TaskArtifactTaskContentParams",
+	additionalProperties: false
+});
 new TextEncoder();
 new TextDecoder();
 //#endregion
@@ -13793,6 +13861,42 @@ function validateTaskCreateRequest(args) {
 		field: "references",
 		message: `At least one reference is required for task type: ${args.taskType}`
 	});
+	errors.push(...validateTaskReferences(args.references));
+	return errors;
+}
+/**
+* Cross-field rules for the reference shapes the schema alone cannot
+* express. Every reference must be exactly one of:
+*
+* - **task output ref**: taskId set, outputCid required; an optional
+*   artifact must name its producing attempt (attemptN).
+* - **input artifact ref**: taskId null, artifact without attemptN;
+*   outputCid omitted (or equal to artifact.cid when sent) -- the bytes
+*   were staged before any task existed, so there is no output to name.
+* - **external ref**: taskId null, external present, no artifact.
+*
+* Anything else used to be silently persisted into taskRefs and never
+* materialized; now it fails fast with a field error.
+*/
+function validateTaskReferences(references) {
+	const errors = [];
+	(references ?? []).forEach((ref, index) => {
+		const invalid = (message) => errors.push({
+			field: `references[${index}]`,
+			message
+		});
+		if (ref.taskId !== null) {
+			if (ref.outputCid === void 0) invalid("outputCid is required when referencing a task output");
+			if (ref.artifact && ref.artifact.attemptN === void 0) invalid("artifact references to another task must include attemptN; input artifacts are referenced with taskId null");
+			return;
+		}
+		if (ref.artifact) {
+			if (ref.artifact.attemptN !== void 0) invalid("input artifact references (taskId null) must not include attemptN; reference the producing task by id instead");
+			if (ref.outputCid !== void 0 && ref.outputCid !== ref.artifact.cid) invalid("outputCid on an input artifact reference must be omitted or equal artifact.cid");
+			return;
+		}
+		if (!ref.external) invalid("references with taskId null must carry either an artifact (input artifact) or an external descriptor");
+	});
 	return errors;
 }
 //#endregion
@@ -13909,7 +14013,7 @@ Unsafe(Cyclic({ ClaimCondition: Unsafe(Union([
 */
 var TaskRef = _Object_({
 	taskId: Union([Uuid, Null()]),
-	outputCid: Cid,
+	outputCid: Optional(Cid),
 	role: Union([
 		Literal("judged_work"),
 		Literal("reviewed_diff"),
@@ -13930,7 +14034,7 @@ var TaskRef = _Object_({
 	})),
 	artifact: Optional(_Object_({
 		cid: Cid,
-		attemptN: Integer({ minimum: 1 }),
+		attemptN: Optional(Integer({ minimum: 1 })),
 		kind: Optional(String$1({
 			minLength: 1,
 			maxLength: 100
@@ -14400,30 +14504,53 @@ var TaskBuilder = class {
 		return this;
 	}
 	/**
-	* Add a reference to a persistent task artifact while retaining the accepted
-	* output CID as the provenance anchor.
+	* Add either a staged input artifact or a persistent attempt artifact.
+	* Staged metadata returned by `tasks.artifacts.stage()` carries
+	* `artifactSource: 'staged'` and produces a reference with `taskId: null`, no
+	* `outputCid`, and no `attemptN`. Persistent artifacts require the producing
+	* task, accepted output CID, artifact CID, and positive attempt number so
+	* their provenance remains explicit.
 	*
-	* @param source - A result reader, raw artifact reference, or `TaskRef`.
+	* @param source - Staged SDK metadata, 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.
+	* @throws {TaskBuildError} when the source is ambiguous or required provenance 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 {
+		else if ("artifactSource" in source && source.artifactSource === "staged" && source.cid) ref = {
+			taskId: null,
+			role,
+			artifact: {
+				cid: source.cid,
+				...source.kind ? { kind: source.kind } : {},
+				...source.title ? { title: source.title } : {},
+				...source.contentType ? { contentType: source.contentType } : {}
+			}
+		};
+		else if ("cid" in source) throw new TaskBuildError([{
+			field: "references/artifactSource",
+			message: "top-level artifact CID is ambiguous; use metadata returned by tasks.artifacts.stage()"
+		}]);
+		else if ("artifact" in source && source.artifact?.cid) if (source.taskId === null && source.artifact.attemptN === void 0) ref = {
+			taskId: null,
+			role,
+			artifact: { ...source.artifact }
+		};
+		else 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"
+		}]);
+		else ref = {
+			...source,
+			role
+		};
+		else {
 			const s = source;
 			const errors = [];
-			if (!s.outputCid) errors.push({
+			const inputArtifact = s.taskId === null && s.attemptN === void 0;
+			if (!inputArtifact && !s.outputCid) errors.push({
 				field: "references/outputCid",
 				message: "reference is missing required outputCid"
 			});
@@ -14431,19 +14558,18 @@ var TaskBuilder = class {
 				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({
+			if (!inputArtifact && (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,
+				...!inputArtifact && s.outputCid ? { outputCid: s.outputCid } : {},
 				role,
 				artifact: {
 					cid: s.artifactCid,
-					attemptN,
+					...s.attemptN !== void 0 ? { attemptN: s.attemptN } : {},
 					...s.kind ? { kind: s.kind } : {},
 					...s.title ? { title: s.title } : {},
 					...s.contentType ? { contentType: s.contentType } : {}
@@ -14913,6 +15039,22 @@ function createTasksNamespace(context) {
 			}));
 		},
 		artifacts: {
+			async stage(body, query, options) {
+				return {
+					...unwrapResult(await stageTaskArtifact({
+						auth,
+						body,
+						client,
+						duplex: "half",
+						headers: {
+							...requiredTeamHeaders(options),
+							"content-type": "application/octet-stream"
+						},
+						query
+					})),
+					artifactSource: "staged"
+				};
+			},
 			async upload(path, body, query, options) {
 				return unwrapResult(await uploadTaskArtifact({
 					auth,
@@ -14946,17 +15088,24 @@ function createTasksNamespace(context) {
 				}));
 			},
 			async download(path, options) {
-				const result = await client.request({
+				const request = {
 					auth,
 					headers: requiredTeamHeaders(options),
 					method: "GET",
 					parseAs: "stream",
-					path,
 					security: [{
 						scheme: "bearer",
 						type: "http"
-					}],
+					}]
+				};
+				const result = "attemptN" in path ? await client.request({
+					...request,
+					path,
 					url: "/tasks/{taskId}/attempts/{attemptN}/artifacts/{cid}/content"
+				}) : await client.request({
+					...request,
+					path,
+					url: "/tasks/{taskId}/artifacts/{cid}/content"
 				});
 				const normalizedStream = normalizeDownloadStream(unwrapResult(result));
 				if (normalizedStream) return {

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

@@ -72,12 +72,17 @@
 
 <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>,
+    Downloads a task artifact by task id 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>
+    Attempt is optional. Omit it to resolve the CID across the task, including
+    input artifacts bound when the task was created. Set it to require an exact
+    attempt artifact.
+  </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

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

@@ -1,6 +1,6 @@
 import { t as withAgent } from "./agent-call.js";
 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";
+import { c as resolveMaxBytes, i as requireArtifactContext, n as payloadRecord, o as resolveAttemptSelection, r as recordField, t as collectArtifactBody } from "./task-artifact-utils.js";
 //#region src/nodes/task-artifact-download.ts
 var init = (RED) => {
 	function TaskArtifactDownloadNode(def) {
@@ -10,7 +10,10 @@ var init = (RED) => {
 			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 { taskId, teamId } = requireArtifactContext("task-artifact-download", msg, def.taskId, def.teamId, agentNode, bool(def.allowMsgTeamOverride) ?? false);
+					const attempt = resolveAttemptSelection(msg, def.attemptN);
+					if (attempt.supplied && attempt.attemptN === void 0) throw new Error("task-artifact-download: attemptN must be a positive integer");
+					const attemptN = attempt.attemptN;
 					const cid = resolveCid(msg, def.cid);
 					if (!cid) throw new Error("task-artifact-download: cid is required");
 					this.status({
@@ -18,7 +21,10 @@ var init = (RED) => {
 						shape: "dot",
 						text: "downloading…"
 					});
-					const result = await withAgent(agentNode, (agent) => agent.tasks.artifacts.download({
+					const result = await withAgent(agentNode, (agent) => agent.tasks.artifacts.download(attemptN === void 0 ? {
+						taskId,
+						cid
+					} : {
 						taskId,
 						attemptN,
 						cid
@@ -33,7 +39,7 @@ var init = (RED) => {
 					out.artifact = {
 						taskId,
 						teamId,
-						attemptN,
+						...attemptN === void 0 ? {} : { attemptN },
 						cid,
 						...metadataFromResult(result)
 					};

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

@@ -0,0 +1,93 @@
+<script type="text/javascript">
+  var moltnetTaskArtifactStageMaxBytes = 25 * 1024 * 1024;
+  RED.nodes.registerType('moltnet-task-artifact-stage', {
+    category: 'moltnet',
+    color: '#00d4c8',
+    paletteLabel: 'task artifact: stage',
+    defaults: {
+      name: { value: '' },
+      agent: { value: '', type: 'moltnet-agent', required: true },
+      teamId: { value: '' },
+      allowMsgTeamOverride: { value: false },
+      maxBytes: {
+        value: moltnetTaskArtifactStageMaxBytes,
+        validate: RED.validators.number(),
+      },
+      contentType: { value: '' },
+      contentEncoding: { value: '' },
+    },
+    inputs: 1,
+    outputs: 1,
+    icon: 'font-awesome/fa-upload',
+    label: function () {
+      return this.name || 'task artifact: stage';
+    },
+  });
+</script>
+
+<script type="text/html" data-template-name="moltnet-task-artifact-stage">
+  <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-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-maxBytes"
+      ><i class="fa fa-database"></i> Max bytes</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="application/pdf"
+    />
+  </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-stage">
+  <p>
+    Stages content-addressed bytes for later binding to a task through an input
+    artifact reference. Staging creates no visible artifact row; the returned
+    CID becomes readable only after a task binds it.
+  </p>
+  <p>
+    Reads bytes from the same payload shapes as task artifact upload and emits
+    <code>{ artifactSource: "staged", cid, sizeBytes, contentType }</code> on
+    <code>msg.payload</code> and <code>msg.artifact</code>. Wire
+    <code>msg.artifact</code> into a task builder's References from field.
+  </p>
+  <p>
+    Buffer and Uint8Array payloads avoid encoding overhead. The
+    <code>{ contentBase64 }</code> form is available for JSON-only sources. The
+    local byte limit defaults to 25 MiB.
+  </p>
+</script>

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

@@ -0,0 +1,54 @@
+import { t as withAgent } from "./agent-call.js";
+import { t as bool } from "./query-utils.js";
+import { c as resolveMaxBytes, l as resolveTeamId, s as resolveField, u as resolveUploadBody } from "./task-artifact-utils.js";
+//#region src/nodes/task-artifact-stage.ts
+var init = (RED) => {
+	function TaskArtifactStageNode(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-stage: no moltnet-agent configured");
+					const teamId = resolveTeamId(msg, def.teamId, agentNode, bool(def.allowMsgTeamOverride) ?? false);
+					if (!teamId) throw new Error("task-artifact-stage: teamId is required");
+					const body = resolveUploadBody(msg, resolveMaxBytes(def.maxBytes), "task-artifact-stage");
+					const query = {
+						contentType: resolveField(msg, "contentType", def.contentType),
+						contentEncoding: resolveField(msg, "contentEncoding", def.contentEncoding)
+					};
+					this.status({
+						fill: "blue",
+						shape: "dot",
+						text: "staging..."
+					});
+					const artifact = await withAgent(agentNode, (agent) => agent.tasks.artifacts.stage(body, query, { teamId }));
+					const out = RED.util.cloneMessage({
+						...msg,
+						payload: void 0
+					});
+					out.payload = artifact;
+					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-stage", TaskArtifactStageNode);
+};
+//#endregion
+export { init as default };

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

@@ -1,6 +1,6 @@
 import { t as withAgent } from "./agent-call.js";
 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";
+import { a as requireAttemptContext, c as resolveMaxBytes, s as resolveField, u as resolveUploadBody } from "./task-artifact-utils.js";
 //#region src/nodes/task-artifact-upload.ts
 var init = (RED) => {
 	function TaskArtifactUploadNode(def) {

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

@@ -17,8 +17,22 @@ function resolveTeamId(msg, configured, agentNode, allowMsgTeamOverride) {
 	return nonEmpty(payloadRecord(msg).teamId) ?? nonEmpty(configured) ?? agentNode.teamId;
 }
 function resolveAttemptN(msg, configured) {
+	return resolveAttemptSelection(msg, configured).attemptN;
+}
+function resolveAttemptSelection(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);
+	const candidate = [
+		msg.attemptN,
+		payload.attemptN,
+		recordField(payload.attempt, "attemptN"),
+		recordField(payload.artifact, "attemptN"),
+		configured
+	].find(isSupplied);
+	if (candidate === void 0) return { supplied: false };
+	return {
+		supplied: true,
+		attemptN: positiveInt(candidate)
+	};
 }
 function requireArtifactContext(nodeName, msg, configuredTaskId, configuredTeamId, agentNode, allowMsgTeamOverride) {
 	const taskId = resolveTaskId(msg, configuredTaskId);
@@ -59,9 +73,8 @@ function resolveUploadBody(msg, maxBytes, nodeName = "task-artifact-upload") {
 	}
 	const record = payloadRecord(msg);
 	if (typeof record.contentBase64 === "string") {
-		const normalized = record.contentBase64.replace(/\s/g, "");
-		if (decodedBase64Length(normalized) > maxBytes) throw tooLarge("upload", maxBytes, nodeName);
-		return Buffer.from(normalized, "base64");
+		if (decodedBase64Length(record.contentBase64) > maxBytes) throw tooLarge("upload", maxBytes, nodeName);
+		return Buffer.from(record.contentBase64, "base64");
 	}
 	const content = record.content ?? record.body;
 	if (Buffer.isBuffer(content)) return enforceMaxBytes(content, maxBytes, nodeName);
@@ -139,11 +152,26 @@ function pushChunk(chunks, chunk, bytes, maxBytes, nodeName) {
 }
 function decodedBase64Length(value) {
 	if (!value) return 0;
-	const padding = value.endsWith("==") ? 2 : value.endsWith("=") ? 1 : 0;
-	return Math.floor(value.length * 3 / 4) - padding;
+	let characters = 0;
+	let previous = "";
+	let last = "";
+	for (let index = 0; index < value.length; index += 1) {
+		if (isBase64Whitespace(value.charCodeAt(index))) continue;
+		characters += 1;
+		previous = last;
+		last = value[index];
+	}
+	const padding = last === "=" ? previous === "=" ? 2 : 1 : 0;
+	return Math.max(0, Math.floor(characters * 3 / 4) - padding);
+}
+function isSupplied(value) {
+	return value !== void 0 && value !== null && value !== "";
+}
+function isBase64Whitespace(code) {
+	return code === 32 || code >= 9 && code <= 13;
 }
 function tooLarge(operation, maxBytes, nodeName) {
 	return /* @__PURE__ */ new Error(`${nodeName}: ${operation} 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 };
+export { requireAttemptContext as a, resolveMaxBytes as c, requireArtifactContext as i, resolveTeamId as l, payloadRecord as n, resolveAttemptSelection as o, recordField as r, resolveField as s, collectArtifactBody as t, resolveUploadBody as u };

package/dist/nodes/task-builder.js

@@ -75,7 +75,8 @@ var init = (RED) => {
 				}
 				if (def.referencesFrom) {
 					const ref = RED.util.getMessageProperty(msg, def.referencesFrom);
-					if (ref && ref.outputCid) builder.references(ref, def.referencesRole ?? "context");
+					if (ref?.artifact || ref?.artifactSource === "staged" || ref?.cid) builder.artifactReference(ref, def.referencesRole ?? "context");
+					else if (ref?.outputCid) builder.references(ref, def.referencesRole ?? "context");
 				}
 				if (def.submitOutputGate) builder.requireSubmitOutput();
 				if (def.schemaCid) builder.requireSchema(def.schemaCid);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@themoltnet/node-red-contrib-core",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "description": "Node-RED nodes for the MoltNet API",
   "keywords": [
@@ -30,6 +30,7 @@
       "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-stage": "dist/nodes/task-artifact-stage.js",
       "moltnet-task-artifact-download": "dist/nodes/task-artifact-download.js",
       "moltnet-runtime-session-get": "dist/nodes/runtime-session-get.js",
       "moltnet-runtime-session-upload": "dist/nodes/runtime-session-upload.js",
@@ -45,7 +46,7 @@
   },
   "main": "dist/nodes/agent.js",
   "dependencies": {
-    "@themoltnet/sdk": "0.119.0"
+    "@themoltnet/sdk": "0.120.0"
   },
   "devDependencies": {
     "@types/node": "^22.19.0",