@themoltnet/node-red-contrib-core 0.10.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.
@@ -57,6 +59,11 @@ want the MoltNet editor skin.
   `{ taskId, status, terminal, accepted, acceptedAttemptN, state, attempt,
 attempts, error, task }`. `state` is the accepted attempt's output artifact
   (the lifecycle "phase" payload) or `null`. For switch/branch logic.
+- **`moltnet-task-cancel`** (palette: _task: cancel_) — cancels one task or an
+  array of task rows/ids. Reads ids from `msg.taskId`, `msg.taskIds`,
+  `msg.payload.taskId`, `msg.payload.id`, `msg.payload.failure.taskId`, or an
+  array on `msg.payload`. Preserves the original payload and writes results to
+  `msg.cancelledTasks` / `msg.cancelErrors`.
 - **`moltnet-task-wait`** (palette: _task: wait_) — polls a task until it settles,
   in one loop doing double duty like the CLI's `task tail`. **Two outputs:**
   output 1 (_tail_) emits each new task message as it arrives (gated by a `tail`
@@ -75,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
@@ -87,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
@@ -273,12 +288,17 @@ created through the Runtime Profiles API for team
 `6743b4b1-6b93-46e2-a048-19490f04f91a`; recreate them or replace the IDs when
 running the flow in another team.
 
-| Stage      | Profile ID                             | Provider / model                      | Settings                                                                                                                                                                                                                  |
-| ---------- | -------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FREEZE     | `1a653eb9-7bfa-475f-b517-c070c9c25b5e` | `ollama-cloud/qwen3-coder:480b-cloud` | `thinkingLevel=high`, `temperature=0.1`, `maxOutputTokens=12000`, `maxTurns=60`, `maxBashTimeouts=5`, `defaultWorkspaceMode=dedicated_worktree`, `allowedWorkspaceModes=[dedicated_worktree]`, requires `git`, `gh`, `rg` |
-| PREFLIGHT  | `f4bb1d9b-6281-4158-ad88-cbcb1198c3dc` | `ollama-cloud/qwen3-coder:480b-cloud` | `thinkingLevel=high`, `temperature=0.1`, `maxOutputTokens=10000`, `maxTurns=16`, `maxBashTimeouts=2`, `defaultWorkspaceMode=shared_mount`, `allowedWorkspaceModes=[shared_mount]`, requires `git`, `rg`                   |
-| SPECIALIST | `f50e9c58-4180-4e07-b120-08b6097c13d5` | `ollama-cloud/qwen3-coder:480b-cloud` | `thinkingLevel=high`, `temperature=0.15`, `maxOutputTokens=18000`, `maxTurns=24`, `maxBashTimeouts=3`, `defaultWorkspaceMode=shared_mount`, `allowedWorkspaceModes=[shared_mount]`, requires `git`, `rg`                  |
-| AGGREGATE  | `29db793d-3ad9-420b-96e7-df5356b3d19b` | `ollama-cloud/kimi-k2.7-code:cloud`   | `thinkingLevel=high`, `temperature=0.2`, `maxOutputTokens=24000`, `maxTurns=16`, `maxBashTimeouts=2`, `defaultWorkspaceMode=none`, `allowedWorkspaceModes=[none]`                                                         |
+| Stage      | Profile ID                             | Provider / model                      | Workspace and tool contract                                                                                         |
+| ---------- | -------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| FREEZE     | `1a653eb9-7bfa-475f-b517-c070c9c25b5e` | `ollama-cloud/qwen3-coder:480b-cloud` | `defaultWorkspaceMode=dedicated_worktree`, `allowedWorkspaceModes=[dedicated_worktree]`, requires `git`, `gh`, `rg` |
+| PREFLIGHT  | `f4bb1d9b-6281-4158-ad88-cbcb1198c3dc` | `ollama-cloud/qwen3-coder:480b-cloud` | `defaultWorkspaceMode=shared_mount`, `allowedWorkspaceModes=[shared_mount]`, requires `git`, `rg`                   |
+| SPECIALIST | `f50e9c58-4180-4e07-b120-08b6097c13d5` | `ollama-cloud/qwen3-coder:480b-cloud` | `defaultWorkspaceMode=shared_mount`, `allowedWorkspaceModes=[shared_mount]`, requires `git`, `rg`                   |
+| AGGREGATE  | `29db793d-3ad9-420b-96e7-df5356b3d19b` | `ollama-cloud/kimi-k2.7-code:cloud`   | `defaultWorkspaceMode=none`, `allowedWorkspaceModes=[none]`                                                         |
+
+The example intentionally avoids prescribing `maxTurns`, output-token caps,
+sampling temperature, or other model-behavior tuning. Keep those profile values
+at the platform/runtime defaults until a repeated run gives enough evidence to
+set a limit deliberately.
 
 All four profiles set `sandbox.env.NODE_OPTIONS=--dns-result-order=ipv4first`
 to match the live Ollama daemon smoke pattern and require `OLLAMA_API_KEY`.
@@ -299,10 +319,10 @@ export OLLAMA_API_KEY=...
 npx @themoltnet/agent-daemon@latest poll \
   --agent <agent-name> \
   --team 6743b4b1-6b93-46e2-a048-19490f04f91a \
-  --profile deep-review-freeze-ollama-qwen-coder-v1 \
-  --profile deep-review-preflight-ollama-qwen-coder-v1 \
-  --profile deep-review-specialist-ollama-qwen-coder-v1 \
-  --profile deep-review-aggregate-ollama-kimi-v1
+  --profile deep-review-freeze-v1 \
+  --profile deep-review-preflight-v1 \
+  --profile deep-review-specialist-v1 \
+  --profile deep-review-aggregate-v1
 ```
 
 The daemon host must have matching Pi model registry entries. This repo's

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>