@codemation/core 0.11.1 → 0.13.0

package/dist/{runtime-DBzq5YBi.cjs → runtime-DjYXgOo0.cjs}

@@ -1,4 +1,4 @@
-const require_di = require('./di-BlEKdoZS.cjs');
+const require_di = require('./di-C-2ep8NZ.cjs');
 let zod = require("zod");
 zod = require_di.__toESM(zod);
 let node_stream_web = require("node:stream/web");
@@ -8,6 +8,34 @@ node_crypto = require_di.__toESM(node_crypto);
 let tsyringe = require("tsyringe");
 tsyringe = require_di.__toESM(tsyringe);
 
+//#region src/contracts/humanTaskStoreTypes.ts
+const HumanTaskStoreToken = Symbol.for("codemation.core.HumanTaskStore");
+
+//#endregion
+//#region src/contracts/hitlSeamTypes.ts
+const HitlResumeTokenSignerToken = Symbol.for("codemation.core.HitlResumeTokenSigner");
+const HitlTimeoutJobSchedulerToken = Symbol.for("codemation.core.HitlTimeoutJobScheduler");
+/**
+* Optional workspace ID injected into NodeSuspensionHandler in managed mode (T7 security fix).
+* Allows the handler to stamp the workspaceId on each HumanTaskRecord so HitlCallbackHandler
+* can assert workspace identity independently of the HMAC middleware.
+* Not registered in non-managed mode; NodeSuspensionHandler defaults to null.
+*/
+const HitlWorkspaceIdToken = Symbol.for("codemation.core.HitlWorkspaceId");
+
+//#endregion
+//#region src/authoring/DefinedNodeRegistry.ts
+var DefinedNodeRegistry = class {
+	static definitions = /* @__PURE__ */ new Map();
+	static register(definition) {
+		this.definitions.set(definition.key, definition);
+	}
+	static resolve(key) {
+		return this.definitions.get(key);
+	}
+};
+
+//#endregion
 //#region src/runtime-types/persistedRuntimeTypeModelRegistry.ts
 /** Shared metadata key used to attach persisted runtime-type information to decorated classes. */
 const persistedRuntimeTypeMetadataKey = Symbol.for("codemation.core.persistedRuntimeTypeMetadata");
@@ -116,6 +144,305 @@ function chatModel(options = {}) {
 	return InjectableRuntimeDecoratorComposer.compose("chatModel", options, require("url").pathToFileURL(__filename).href);
 }
 
+//#endregion
+//#region src/authoring/defineNode.types.ts
+const definedNodeCredentialRequirementFactory = {
+	create(bindings) {
+		if (!bindings) return [];
+		return Object.entries(bindings).map(([slotKey, binding]) => {
+			if (typeof binding === "string" || this.isCredentialType(binding)) return {
+				slotKey,
+				label: this.humanize(slotKey),
+				acceptedTypes: [this.resolveTypeId(binding)]
+			};
+			const types = Array.isArray(binding.type) ? binding.type : [binding.type];
+			return {
+				slotKey,
+				label: binding.label ?? this.humanize(slotKey),
+				acceptedTypes: types.map((entry) => this.resolveTypeId(entry)),
+				optional: binding.optional,
+				helpText: binding.helpText,
+				helpUrl: binding.helpUrl
+			};
+		});
+	},
+	isCredentialType(value) {
+		return Boolean(value) && typeof value === "object" && "definition" in value && typeof value.definition?.typeId === "string";
+	},
+	resolveTypeId(type) {
+		return typeof type === "string" ? type : type.definition.typeId;
+	},
+	humanize(key) {
+		return key.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/[-_.]+/g, " ").replace(/\s+/g, " ").trim().replace(/^./, (character) => character.toUpperCase());
+	}
+};
+const definedNodeCredentialAccessorFactory = { create(bindings, ctx) {
+	if (!bindings) return {};
+	const entries = Object.keys(bindings).map((slotKey) => [slotKey, () => ctx.getCredential(slotKey)]);
+	return Object.fromEntries(entries);
+} };
+function defineNode(options) {
+	const credentialRequirements = definedNodeCredentialRequirementFactory.create(options.credentials);
+	const DefinedNodeRuntime = class {
+		kind = "node";
+		outputPorts = ["main"];
+		inputSchema = options.inputSchema;
+		async execute(args) {
+			const ctx = args.ctx;
+			const context = {
+				config: ctx.config.config,
+				credentials: definedNodeCredentialAccessorFactory.create(options.credentials, ctx),
+				execution: ctx
+			};
+			const payload = {
+				input: args.input,
+				item: args.item,
+				itemIndex: args.itemIndex,
+				items: args.items,
+				ctx
+			};
+			return await options.execute(payload, context);
+		}
+	};
+	node({ name: options.key })(DefinedNodeRuntime);
+	const DefinedRunnableNodeConfig = class {
+		kind = "node";
+		type = DefinedNodeRuntime;
+		icon = options.icon;
+		inputSchema = options.inputSchema;
+		keepBinaries = options.keepBinaries ?? false;
+		constructor(name, config, id) {
+			this.name = name;
+			this.id = id;
+			this.config = config;
+		}
+		config;
+		getCredentialRequirements() {
+			return credentialRequirements;
+		}
+		inspectorSummary() {
+			return options.inspectorSummary?.({ config: this.config });
+		}
+	};
+	const definition = {
+		kind: "defined-node",
+		key: options.key,
+		title: options.title,
+		description: options.description,
+		create(config, name = options.title, id) {
+			return new DefinedRunnableNodeConfig(name, config, id);
+		},
+		register(context) {
+			context.registerNode(DefinedNodeRuntime);
+		}
+	};
+	DefinedNodeRegistry.register(definition);
+	return definition;
+}
+function defineBatchNode(options) {
+	const credentialRequirements = definedNodeCredentialRequirementFactory.create(options.credentials);
+	const DefinedNodeRuntime = class {
+		kind = "node";
+		outputPorts = ["main"];
+		async execute(args) {
+			if (args.itemIndex !== args.items.length - 1) return [];
+			const ctx = args.ctx;
+			const context = {
+				config: ctx.config.config,
+				credentials: definedNodeCredentialAccessorFactory.create(options.credentials, ctx),
+				execution: ctx
+			};
+			return [...await options.run(args.items.map((item) => item.json), context)];
+		}
+	};
+	node({ name: options.key })(DefinedNodeRuntime);
+	const DefinedRunnableNodeConfig = class {
+		kind = "node";
+		type = DefinedNodeRuntime;
+		icon = options.icon;
+		constructor(name, config, id) {
+			this.name = name;
+			this.id = id;
+			this.config = config;
+		}
+		config;
+		getCredentialRequirements() {
+			return credentialRequirements;
+		}
+		inspectorSummary() {
+			return options.inspectorSummary?.({ config: this.config });
+		}
+	};
+	const definition = {
+		kind: "defined-node",
+		key: options.key,
+		title: options.title,
+		description: options.description,
+		create(config, name = options.title, id) {
+			return new DefinedRunnableNodeConfig(name, config, id);
+		},
+		register(context) {
+			context.registerNode(DefinedNodeRuntime);
+		}
+	};
+	DefinedNodeRegistry.register(definition);
+	return definition;
+}
+
+//#endregion
+//#region src/authoring/defineHumanApprovalNode.types.ts
+/**
+* Returns `true` when `node` was created by {@link defineHumanApprovalNode}.
+* Uses the `humanApprovalToolBehavior` typed field as the discriminant.
+*/
+function isHumanApprovalNode(node$1) {
+	return typeof node$1 === "object" && node$1 !== null && "humanApprovalToolBehavior" in node$1 && typeof node$1.humanApprovalToolBehavior === "object";
+}
+/**
+* Authoring helper that compiles a HITL approval channel down to a regular
+* {@link defineNode}-backed node with `SuspensionRequest` semantics.
+*
+* **Fast-forward decision semantics:**
+* - On the first `execute` call (no `ctx.resumeContext`): throws a `SuspensionRequest`
+*   that calls the author's `deliver`. The engine persists the suspension and continues.
+* - On resume (`ctx.resumeContext` set): calls `onDecision`/`onTimeout` as appropriate,
+*   merges a `decision` key into `item.json`, and returns an item with the original
+*   `binary` map passed by reference (no copy).
+*
+* **Output shape per item:**
+* ```ts
+* // Input:  { json: { invoiceId: 42 }, binary?: {...} }
+* // Output: { json: { invoiceId: 42, decision: { status: "approved", actor, decidedAt } }, binary: <unchanged> }
+* ```
+* If `item.json` already has a `decision` key it is **overwritten**. Namespace as
+* needed if your schema reserves that key for another purpose.
+*
+* **Predicate persistence:**
+* The `approvedPredicate` function is NOT serialized to the suspension record (except
+* as an audit-only string via `toString()`). On resume, the workflow definition is
+* reloaded from code at process start and the predicate closure is rebuilt naturally.
+* If a deploy ships a changed predicate between suspend and resume, the *new* predicate
+* runs — document this in your runbook when the predicate carries business logic that
+* may change across deploys.
+*
+* @example
+* ```ts
+* export const slackApprovalNode = defineHumanApprovalNode({
+*   key: "my-plugin.slackApproval",
+*   title: "Slack Approval",
+*   channel: "slack",
+*   configSchema: z.object({ channel: z.string(), message: z.string() }),
+*   decisionSchema: z.object({ approved: z.boolean(), note: z.string().optional() }),
+*
+*   async deliver({ task, config, item }, ctx) {
+*     const ts = await postSlackMessage(config.channel, `Approve? <${task.resumeUrl}>`);
+*     return { channel: config.channel, ts };
+*   },
+*
+*   async onDecision({ decision, actor, delivery }, ctx) {
+*     await updateSlackMessage(delivery.channel, delivery.ts, decision.approved ? "✅" : "❌");
+*   },
+* });
+* ```
+*/
+function defineHumanApprovalNode(opts) {
+	const resolvedPredicate = resolveApprovedPredicate(opts.decisionSchema, opts.approvedPredicate);
+	const timeout = opts.defaultTimeout ?? "24h";
+	const onTimeout = opts.defaultOnTimeout ?? "halt";
+	const inner = defineNode({
+		key: opts.key,
+		title: opts.title,
+		description: opts.description,
+		icon: opts.icon,
+		configSchema: opts.configSchema,
+		inputSchema: opts.inputSchema,
+		credentials: opts.credentials,
+		inspectorSummary: opts.inspectorSummary ? ({ config }) => opts.inspectorSummary(config) : void 0,
+		async execute(args, { config, execution: ctx }) {
+			if (!ctx.resumeContext) {
+				const subject = buildSubject(opts.title, args.item, ctx);
+				throw new require_di.SuspensionRequest({
+					decisionSchema: opts.decisionSchema,
+					timeout,
+					onTimeout,
+					subject,
+					metadata: {
+						channel: opts.channel,
+						nodeKey: opts.key,
+						approvedPredicateSource: opts.approvedPredicate?.toString() ?? null
+					},
+					deliver: (handle) => opts.deliver({
+						task: handle,
+						config,
+						input: args.input,
+						item: args.item
+					}, ctx)
+				});
+			}
+			return await handleResume(args.item, ctx.resumeContext, opts.decisionSchema, resolvedPredicate, opts.onDecision, opts.onTimeout, ctx);
+		}
+	});
+	return Object.assign(inner, { humanApprovalToolBehavior: { onRejected: "return" } });
+}
+function resolveApprovedPredicate(schema, predicate) {
+	if (predicate) return predicate;
+	const shape = schema.shape;
+	if (shape && typeof shape === "object" && "approved" in shape) return (d) => d.approved === true;
+	throw new Error("defineHumanApprovalNode: decisionSchema has no \"approved\" field and no approvedPredicate was provided. Either add { approved: z.boolean() } to the decision schema or supply approvedPredicate explicitly.");
+}
+function buildSubject(title, item, ctx) {
+	return {
+		title,
+		summary: "",
+		attributes: {
+			workflowId: ctx.workflowId,
+			nodeId: ctx.nodeId,
+			item: item.json
+		}
+	};
+}
+function mergeDecision(item, decision) {
+	return {
+		json: {
+			...item.json,
+			decision
+		},
+		binary: item.binary,
+		meta: item.meta
+	};
+}
+async function handleResume(item, resumeContext, decisionSchema, resolvedPredicate, onDecision, onTimeoutCb, ctx) {
+	const { decision: dec, delivery, task } = resumeContext;
+	if (dec.kind === "timed_out" || dec.kind === "auto_accepted") {
+		const policy = dec.kind === "auto_accepted" ? "auto-accept" : "halt";
+		await onTimeoutCb?.({
+			task,
+			delivery,
+			item,
+			policy
+		}, ctx);
+		return mergeDecision(item, {
+			status: dec.kind === "auto_accepted" ? "auto-accepted" : "timed-out",
+			decidedAt: dec.at
+		});
+	}
+	const parsed = decisionSchema.parse(dec.value);
+	await onDecision?.({
+		decision: parsed,
+		actor: dec.actor,
+		task,
+		delivery,
+		item
+	}, ctx);
+	return mergeDecision(item, {
+		status: resolvedPredicate(parsed) ? "approved" : "rejected",
+		actor: dec.actor,
+		decidedAt: dec.decidedAt,
+		note: parsed.note,
+		payload: parsed
+	});
+}
+
 //#endregion
 //#region src/workflow/dsl/WhenBuilder.ts
 var WhenBuilder = class WhenBuilder {
@@ -242,6 +569,25 @@ var ChainCursor = class ChainCursor {
 		}
 		return new ChainCursor(this.wf, nextEndpoints);
 	}
+	/**
+	* Chainable shorthand for `.then(node.create(config, metadata?.name, metadata?.nodeId))`.
+	*
+	* Signals to readers that this step suspends the run and waits for a human decision.
+	* Throws at workflow-build time if `node` was not created via `defineHumanApprovalNode`.
+	*
+	* @example
+	* ```ts
+	* workflow
+	*   .trigger(...)
+	*   .humanApproval(inboxApproval, { title: "Approve?", body: "...", priority: "normal" })
+	*   .then(nextStep.create(...))
+	*   .build();
+	* ```
+	*/
+	humanApproval(node$1, config, metadata) {
+		if (!isHumanApprovalNode(node$1)) throw new Error(`.humanApproval() requires a node created via defineHumanApprovalNode (got '${node$1.key ?? String(node$1)}').`);
+		return this.then(node$1.create(config, metadata?.name, metadata?.nodeId));
+	}
 	build() {
 		return this.wf.build();
 	}
@@ -549,6 +895,58 @@ var NodeEventPublisher = class {
 	}
 };
 
+//#endregion
+//#region src/binaries/boundedReadBinary.types.ts
+/**
+* Reads all bytes from an already-opened binary stream into a contiguous `Uint8Array`.
+*
+* Safety contract:
+*  - `attachment.size` is checked against `maxBytes` *before* any allocation (no OOM).
+*  - A single buffer of exactly `attachment.size` is pre-allocated; the stream fills it
+*    directly — no chunks array, no doubling.
+*  - A byte-count mismatch between the declared size and actual stream content is an error.
+*
+* This is the single canonical implementation; `ExecutionBinaryService.getBytes`,
+* `getText`, and `getJson` all delegate here. The per-package `readBinaryBody` helpers
+* in `core-nodes` and `core-nodes-ocr` have been removed in favour of this function.
+*/
+async function boundedReadBinary(result, attachment, maxBytes = require_di.BINARY_DEFAULT_MAX_BYTES) {
+	if (attachment.size > maxBytes) throw new Error(`Binary attachment size ${attachment.size} bytes exceeds maxBytes ${maxBytes}. Raise the node's maxBytes setting if this document is expected to be larger.`);
+	const out = new Uint8Array(attachment.size);
+	const reader = result.body.getReader();
+	let offset = 0;
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		if (!value) continue;
+		if (offset + value.byteLength > out.byteLength) throw new Error(`Binary stream produced more bytes than the attachment's declared size (${attachment.size}).`);
+		out.set(value, offset);
+		offset += value.byteLength;
+	}
+	if (offset !== out.byteLength) throw new Error(`Binary stream produced ${offset} bytes but attachment declared size ${attachment.size}.`);
+	return out;
+}
+/** Shared implementation of `getBytes` used by both binary-service classes. */
+async function readBinaryAsBytes(storage, attachment, maxBytes) {
+	const result = await storage.openReadStream(attachment.storageKey);
+	if (!result) throw new Error("Binary attachment stream is unavailable.");
+	return boundedReadBinary(result, attachment, maxBytes);
+}
+/** Shared implementation of `getText` used by both binary-service classes. */
+async function readBinaryAsText(storage, attachment, maxBytes) {
+	const bytes = await readBinaryAsBytes(storage, attachment, maxBytes);
+	return new TextDecoder().decode(bytes);
+}
+/** Shared implementation of `getJson` used by both binary-service classes. */
+async function readBinaryAsJson(storage, attachment, maxBytes) {
+	const text = await readBinaryAsText(storage, attachment, maxBytes);
+	try {
+		return JSON.parse(text);
+	} catch (cause) {
+		throw new SyntaxError(`Binary attachment at storage key "${attachment.storageKey}" is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+}
+
 //#endregion
 //#region src/binaries/DefaultNodeBinaryAttachmentServiceFactory.ts
 var DefaultNodeBinaryAttachmentService = class DefaultNodeBinaryAttachmentService {
@@ -599,6 +997,15 @@ var DefaultNodeBinaryAttachmentService = class DefaultNodeBinaryAttachmentServic
 	async openReadStream(attachment) {
 		return await this.storage.openReadStream(attachment.storageKey);
 	}
+	async getBytes(attachment, maxBytes) {
+		return readBinaryAsBytes(this.storage, attachment, maxBytes);
+	}
+	async getText(attachment, maxBytes) {
+		return readBinaryAsText(this.storage, attachment, maxBytes);
+	}
+	async getJson(attachment, maxBytes) {
+		return readBinaryAsJson(this.storage, attachment, maxBytes);
+	}
 	createAttachmentId() {
 		return DefaultNodeBinaryAttachmentService.createAttachmentIdValue(`${this.activationId}-${this.now().getTime()}`);
 	}
@@ -662,8 +1069,24 @@ var DefaultExecutionBinaryService = class {
 	forNode(args) {
 		return new DefaultNodeBinaryAttachmentService(this.storage, this.workflowId, this.runId, args.nodeId, args.activationId, this.now);
 	}
-	async openReadStream(attachment) {
-		return await this.storage.openReadStream(attachment.storageKey);
+	openReadStream(attachment) {
+		return this.storage.openReadStream(attachment.storageKey);
+	}
+	async getBytes(attachment, maxBytes) {
+		const stream = await this.openReadStream(attachment);
+		if (!stream) throw new Error("Binary attachment stream is unavailable.");
+		return boundedReadBinary(stream, attachment, maxBytes);
+	}
+	async getText(attachment, maxBytes) {
+		return new TextDecoder().decode(await this.getBytes(attachment, maxBytes));
+	}
+	async getJson(attachment, maxBytes) {
+		const text = await this.getText(attachment, maxBytes);
+		try {
+			return JSON.parse(text);
+		} catch (cause) {
+			throw new SyntaxError(`Binary attachment at storage key "${attachment.storageKey}" is not valid JSON: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+		}
 	}
 };
 
@@ -708,7 +1131,7 @@ var NodeExecutionSnapshotFactory = class {
 			nodeId: args.nodeId,
 			activationId: args.activationId,
 			parent: args.parent,
-			status: "completed",
+			status: args.hitlStatus ?? "completed",
 			queuedAt: args.previous?.queuedAt,
 			startedAt,
 			finishedAt: args.finishedAt,
@@ -835,7 +1258,9 @@ var ActivationEnqueueService = class {
 			nodeSnapshotsByNodeId: {
 				...args.previousNodeSnapshotsByNodeId,
 				[args.request.nodeId]: queuedSnapshot
-			}
+			},
+			...args.suspension !== void 0 ? { suspension: args.suspension } : {},
+			...args.pendingResume !== void 0 ? { pendingResume: args.pendingResume } : {}
 		});
 		await this.dispatchPreparedActivation(preparedDispatch);
 		return {
@@ -1302,6 +1727,16 @@ var CodemationTelemetryAttributeNames = class {
 	static mcpServerId = "mcp.server_id";
 	/** MCP tool name on spans created for callTool invocations. */
 	static mcpToolName = "mcp.tool_name";
+	/** Terminal node-execution status (e.g. `"hitl-approved"`, `"hitl-rejected"`) on HITL outcome spans. */
+	static nodeExecutionStatus = "codemation.node.execution_status";
+	/** Populated on run-halted spans; discriminates the halt reason (e.g. `"hitl-rejected"`). */
+	static runHaltReason = "codemation.run.halt_reason";
+	/** Human task ID on `hitl.task.*` span events. */
+	static hitlTaskId = "codemation.hitl.task_id";
+	/** HITL channel name (e.g. `"inbox"`, `"control-plane-inbox"`) on `hitl.task.*` span events. */
+	static hitlChannel = "codemation.hitl.channel";
+	/** Decision outcome (e.g. `"approved"`, `"rejected"`) on `hitl.task.decided` span events. */
+	static hitlDecisionStatus = "codemation.hitl.decision_status";
 };
 
 //#endregion
@@ -1400,12 +1835,13 @@ var ExecutionTelemetryCostTrackingDecoratorFactory = class {
 //#region src/execution/DefaultExecutionContextFactory.ts
 var DefaultExecutionContextFactory = class {
 	telemetryDecoratorFactory = new ExecutionTelemetryCostTrackingDecoratorFactory();
-	constructor(binaryStorage = new UnavailableBinaryStorage(), telemetryFactory = new NoOpExecutionTelemetryFactory(), costTrackingFactory = new NoOpCostTrackingTelemetryFactory(), currentDate = () => /* @__PURE__ */ new Date(), collections) {
+	constructor(binaryStorage = new UnavailableBinaryStorage(), telemetryFactory = new NoOpExecutionTelemetryFactory(), costTrackingFactory = new NoOpCostTrackingTelemetryFactory(), currentDate = () => /* @__PURE__ */ new Date(), collections, nodeResolver) {
 		this.binaryStorage = binaryStorage;
 		this.telemetryFactory = telemetryFactory;
 		this.costTrackingFactory = costTrackingFactory;
 		this.currentDate = currentDate;
 		this.collections = collections;
+		this.nodeResolver = nodeResolver;
 	}
 	create(args) {
 		const baseTelemetry = args.telemetry ?? this.telemetryFactory.create({
@@ -1432,7 +1868,11 @@ var DefaultExecutionContextFactory = class {
 			binary: new DefaultExecutionBinaryService(this.binaryStorage, args.workflowId, args.runId, this.currentDate),
 			getCredential: args.getCredential,
 			testContext: args.testContext,
-			collections: this.collections
+			collections: this.collections,
+			resolve: (token) => {
+				if (!this.nodeResolver) throw new Error("ExecutionContext.resolve() is not available: no NodeResolver was provided to DefaultExecutionContextFactory.");
+				return this.nodeResolver.resolve(token);
+			}
 		};
 	}
 };
@@ -1774,6 +2214,27 @@ var NodeActivationRequestComposer = class {
 	}
 };
 
+//#endregion
+//#region src/execution/RunSuspendedError.ts
+/**
+* Internal sentinel thrown by {@link NodeSuspensionHandler} after persisting a suspension
+* entry. `NodeExecutionRequestHandlerService` catches this specifically and returns cleanly —
+* no continuation call, preventing `resumeFromNodeResult` / `resumeFromNodeError` from
+* overwriting the `"suspended"` run status.
+*
+* The `Error` suffix satisfies the ESLint `no-manual-di-new` allowlist. This is NOT a
+* user-facing error — it is an engine-internal control-flow primitive and should NOT be
+* exported from the public barrel.
+*/
+var RunSuspendedError = class extends Error {
+	constructor(runId, taskId) {
+		super(`RunSuspendedError: run ${runId} suspended on task ${taskId}`);
+		this.runId = runId;
+		this.taskId = taskId;
+		this.name = "RunSuspendedError";
+	}
+};
+
 //#endregion
 //#region src/execution/NodeExecutor.ts
 var NodeExecutor = class {
@@ -1781,9 +2242,11 @@ var NodeExecutor = class {
 	outputNormalizer = new NodeOutputNormalizer();
 	itemExprResolver;
 	outputBehaviorResolver;
-	constructor(nodeInstanceFactory, retryRunner, itemExprResolver, outputBehaviorResolver) {
+	constructor(nodeInstanceFactory, retryRunner, itemExprResolver, outputBehaviorResolver, suspensionHandler, loadRunState) {
 		this.nodeInstanceFactory = nodeInstanceFactory;
 		this.retryRunner = retryRunner;
+		this.suspensionHandler = suspensionHandler;
+		this.loadRunState = loadRunState;
 		this.itemExprResolver = itemExprResolver ?? new ItemExprResolver();
 		this.outputBehaviorResolver = outputBehaviorResolver ?? new RunnableOutputBehaviorResolver();
 	}
@@ -1883,6 +2346,7 @@ var NodeExecutor = class {
 			});
 		}
 		const byPort = {};
+		let hasSuspension = false;
 		for (let i = 0; i < inputBatch.length; i++) {
 			const item = inputBatch[i];
 			this.assertItemJsonNotTopLevelArray(request.nodeId, item);
@@ -1901,7 +2365,28 @@ var NodeExecutor = class {
 				items: inputBatch,
 				ctx: iterationCtx
 			};
-			const raw = await Promise.resolve(node$1.execute(args));
+			let raw;
+			try {
+				raw = await Promise.resolve(node$1.execute(args));
+			} catch (e) {
+				if (e instanceof require_di.SuspensionRequest || e instanceof Error && e.name === "SuspensionRequest" && typeof e.request === "object") {
+					if (!this.suspensionHandler || !this.loadRunState) throw new Error(`Node ${request.nodeId} threw SuspensionRequest but this NodeExecutor has no suspensionHandler configured.`, { cause: e });
+					const state = await this.loadRunState(request.runId);
+					if (!state) throw new Error(`NodeExecutor: run state not found for runId ${request.runId} during suspension`, { cause: e });
+					await this.suspensionHandler.handle({
+						runId: request.runId,
+						nodeId: request.nodeId,
+						activationId: request.activationId,
+						itemIndex: i,
+						suspensionRequest: e,
+						state,
+						telemetry: iterationCtx.telemetry
+					});
+					hasSuspension = true;
+					continue;
+				}
+				throw e;
+			}
 			const normalized = this.outputNormalizer.normalizeExecuteResult({
 				baseItem: item,
 				raw,
@@ -1914,6 +2399,7 @@ var NodeExecutor = class {
 				byPort[port] = list;
 			}
 		}
+		if (hasSuspension) throw new RunSuspendedError(request.runId, "unknown");
 		return byPort;
 	}
 	/** Use resolver ctx only when {@link NodeExecutionContext.config} is non-nullish. */
@@ -1940,8 +2426,8 @@ var NodeExecutor = class {
 //#endregion
 //#region src/execution/NodeExecutorFactory.ts
 var NodeExecutorFactory = class {
-	create(workflowNodeInstanceFactory, retryRunner, outputBehaviorResolver) {
-		return new NodeExecutor(workflowNodeInstanceFactory, retryRunner, void 0, outputBehaviorResolver);
+	create(workflowNodeInstanceFactory, retryRunner, outputBehaviorResolver, suspensionHandler, loadRunState) {
+		return new NodeExecutor(workflowNodeInstanceFactory, retryRunner, void 0, outputBehaviorResolver, suspensionHandler, loadRunState);
 	}
 };
 
@@ -2534,6 +3020,7 @@ var PersistedRunStateTerminalBuilder = class {
 			...args.state,
 			engineCounters: args.engineCounters,
 			status: args.status,
+			reason: args.reason,
 			pending: void 0,
 			queue: args.queue,
 			outputsByNode: args.outputsByNode,
@@ -2816,6 +3303,7 @@ var RunContinuationService = class {
 		});
 		data.setOutputs(args.nodeId, args.outputs);
 		const completedAt = (/* @__PURE__ */ new Date()).toISOString();
+		const hitlResolution = this.resolveHitlStatus(args.outputs);
 		const completedSnapshot = this.semantics.createFinishedSnapshot({
 			workflow: wf,
 			previous: state.nodeSnapshotsByNodeId?.[args.nodeId],
@@ -2826,8 +3314,41 @@ var RunContinuationService = class {
 			parent: state.parent,
 			finishedAt: completedAt,
 			inputsByPort: pendingExecution.inputsByPort,
-			outputs: args.outputs
+			outputs: args.outputs,
+			hitlStatus: hitlResolution?.nodeStatus
 		});
+		if (hitlResolution?.halt) {
+			const haltedState = this.persistedRunStateTerminalBuilder.mergeTerminal({
+				state,
+				engineCounters: state.engineCounters ?? { completedNodeActivations: 0 },
+				status: "halted",
+				reason: hitlResolution.reason,
+				queue: [],
+				outputsByNode: data.dump(),
+				nodeSnapshotsByNodeId: {
+					...state.nodeSnapshotsByNodeId ?? {},
+					[args.nodeId]: completedSnapshot
+				},
+				finishedAtIso: completedAt
+			});
+			await this.workflowExecutionRepository.save(haltedState);
+			await this.nodeEventPublisher.publish("nodeCompleted", completedSnapshot);
+			await this.terminalPersistence.maybeDeleteAfterTerminalState({
+				workflow: wf,
+				state: haltedState,
+				finalStatus: "failed",
+				finishedAt: completedAt
+			});
+			const result = {
+				runId: state.runId,
+				workflowId: state.workflowId,
+				startedAt: state.startedAt,
+				status: "halted",
+				reason: hitlResolution.reason
+			};
+			this.waiters.resolveRunCompletion(result);
+			return result;
+		}
 		const completedActivations = (state.engineCounters?.completedNodeActivations ?? 0) + 1;
 		const engineCounters = { completedNodeActivations: completedActivations };
 		const maxNodeActivations = state.executionOptions?.maxNodeActivations ?? this.executionLimitsPolicy.createRootExecutionOptions().maxNodeActivations;
@@ -3128,13 +3649,114 @@ var RunContinuationService = class {
 			status: "failed",
 			error: { message: "Run failed" }
 		};
+		if (existing?.status === "halted") return {
+			runId: existing.runId,
+			workflowId: existing.workflowId,
+			startedAt: existing.startedAt,
+			status: "halted",
+			reason: existing.reason ?? "hitl-rejected"
+		};
 		const result = await this.waiters.waitForCompletion(runId);
-		if (result.status !== "completed" && result.status !== "failed") throw new Error(`Unexpected run completion status: ${result.status}`);
+		if (result.status !== "completed" && result.status !== "failed" && result.status !== "halted") throw new Error(`Unexpected run completion status: ${result.status}`);
 		return result;
 	}
 	async waitForWebhookResponse(runId) {
 		return await this.waiters.waitForWebhookResponse(runId);
 	}
+	/**
+	* Re-activate a previously suspended run item with a human decision.
+	*
+	* Called by the HITL resume endpoint. This method:
+	* 1. Loads `PersistedRunState` and locates the suspension entry by `taskId`.
+	* 2. Removes the entry from the `suspension` array; if empty, run stays `"suspended"` until
+	*    enqueue flips it to `"pending"`.
+	* 3. Writes `pendingResume` onto the state so `NodeExecutionRequestHandlerService` can
+	*    splice `resumeContext` into the node's execution context.
+	* 4. Reconstructs the original input from `outputsByNode` of the upstream node and
+	*    enqueues a new activation via `activationEnqueueService`.
+	*
+	* @throws if the run is not found, not suspended, or the `taskId` is unknown.
+	*/
+	async resumeRun(args) {
+		const state = await this.workflowExecutionRepository.load(args.runId);
+		if (!state) throw new Error(`Unknown runId: ${args.runId}`);
+		if (state.status !== "suspended") throw new Error(`Run ${args.runId} is not suspended (status: ${state.status})`);
+		const suspensionEntry = (state.suspension ?? []).find((s) => s.taskId === args.taskId);
+		if (!suspensionEntry) throw new Error(`No suspension entry with taskId "${args.taskId}" found on run ${args.runId}`);
+		const wf = this.resolvePersistedWorkflow(state);
+		if (!wf) throw new Error(`Unknown workflowId: ${state.workflowId}`);
+		const { topology, planner } = this.planningFactory.create(wf);
+		const def = topology.defsById.get(suspensionEntry.nodeId);
+		if (!def || def.kind !== "node") throw new Error(`Node ${suspensionEntry.nodeId} is not a runnable node`);
+		const data = this.runDataFactory.create(state.outputsByNode);
+		const limits = this.resolveEngineLimitsFromState(state);
+		const base = this.runExecutionContextFactory.create({
+			runId: state.runId,
+			workflowId: state.workflowId,
+			nodeId: suspensionEntry.nodeId,
+			parent: state.parent,
+			policySnapshot: state.policySnapshot,
+			subworkflowDepth: state.executionOptions?.subworkflowDepth ?? 0,
+			engineMaxNodeActivations: limits.engineMaxNodeActivations,
+			engineMaxSubworkflowDepth: limits.engineMaxSubworkflowDepth,
+			data,
+			nodeState: this.nodeStatePublisherFactory.create(state.runId, state.workflowId, state.parent),
+			testContext: state.executionOptions?.testContext
+		});
+		const parentEdges = wf.edges.filter((e) => e.to.nodeId === suspensionEntry.nodeId);
+		const parentNodeId = parentEdges[0]?.from.nodeId;
+		const parentOutputPort = parentEdges[0]?.from.output ?? "main";
+		const allParentItems = parentNodeId ? data.getOutputItems(parentNodeId, parentOutputPort) ?? [] : [];
+		const resumeInput = allParentItems.length > suspensionEntry.itemIndex ? [allParentItems[suspensionEntry.itemIndex]] : allParentItems;
+		const newActivationId = this.activationIdFactory.makeActivationId();
+		const pendingResume = {
+			activationId: newActivationId,
+			nodeId: suspensionEntry.nodeId,
+			resumeContext: args.resumeContext
+		};
+		const remainingSuspensions = (state.suspension ?? []).filter((s) => s.taskId !== args.taskId);
+		const baseWithResume = {
+			...base,
+			resumeContext: args.resumeContext
+		};
+		const batchId = `resume_${newActivationId}`;
+		const request = this.nodeActivationRequestComposer.createSingleFromDefinitionWithActivation({
+			activationId: newActivationId,
+			runId: state.runId,
+			workflowId: state.workflowId,
+			parent: state.parent,
+			executionOptions: state.executionOptions,
+			base: baseWithResume,
+			data,
+			definition: {
+				id: suspensionEntry.nodeId,
+				config: def.config
+			},
+			batchId,
+			input: resumeInput
+		});
+		const { result, queuedSnapshot } = await this.activationEnqueueService.enqueueActivationWithSnapshot({
+			runId: state.runId,
+			workflowId: state.workflowId,
+			startedAt: state.startedAt,
+			parent: state.parent,
+			executionOptions: state.executionOptions,
+			control: state.control,
+			workflowSnapshot: state.workflowSnapshot,
+			mutableState: state.mutableState,
+			policySnapshot: state.policySnapshot,
+			pendingQueue: [],
+			request,
+			previousNodeSnapshotsByNodeId: state.nodeSnapshotsByNodeId ?? {},
+			planner,
+			engineCounters: state.engineCounters,
+			connectionInvocations: state.connectionInvocations ?? [],
+			suspension: remainingSuspensions.length > 0 ? remainingSuspensions : void 0,
+			pendingResume
+		});
+		await this.nodeEventPublisher.publish("nodeQueued", queuedSnapshot);
+		return result;
+	}
 	async resumeFromWebhookControl(args) {
 		const data = this.runDataFactory.create(args.state.outputsByNode);
 		const { topology, planner } = this.planningFactory.create(args.workflow);
@@ -3521,6 +4143,34 @@ var RunContinuationService = class {
 		this.waiters.resolveRunCompletion(result);
 		return result;
 	}
+	/**
+	* Inspects node outputs for a `decision.status` written by `defineHumanApprovalNode`.
+	* Returns the first-class HITL node status and halt classification, or `undefined`
+	* when the node is not a HITL approval node.
+	*/
+	resolveHitlStatus(outputs) {
+		const firstItem = outputs?.main?.[0];
+		const decisionStatus = firstItem && typeof firstItem === "object" && "json" in firstItem && firstItem.json && typeof firstItem.json === "object" && "decision" in firstItem.json && firstItem.json.decision && typeof firstItem.json.decision === "object" && "status" in firstItem.json.decision ? firstItem.json.decision.status : void 0;
+		if (!decisionStatus) return void 0;
+		if (decisionStatus === "approved") return {
+			nodeStatus: "hitl-approved",
+			halt: false
+		};
+		if (decisionStatus === "auto-accepted") return {
+			nodeStatus: "hitl-auto-accepted",
+			halt: false
+		};
+		if (decisionStatus === "rejected") return {
+			nodeStatus: "hitl-rejected",
+			halt: true,
+			reason: "hitl-rejected"
+		};
+		if (decisionStatus === "timed-out") return {
+			nodeStatus: "hitl-timeout",
+			halt: true,
+			reason: "hitl-timeout"
+		};
+	}
 	formatNodeLabel(args) {
 		const tokenName = typeof args.definition?.type === "function" ? args.definition.type.name : "Node";
 		return args.definition?.name ? `"${args.definition.name}" (${tokenName}:${args.nodeId})` : `${tokenName}:${args.nodeId}`;
@@ -4873,13 +5523,19 @@ var NodeExecutionRequestHandlerService = class {
 		const portKeys = Object.keys(inputsByPort);
 		const kind = portKeys.length === 1 && portKeys[0] === "in" ? "single" : "multi";
 		const batchId = pendingExecution.batchId ?? "batch_1";
+		const pendingResume = state.pendingResume;
+		const resumeContext = pendingResume?.activationId === request.activationId && pendingResume?.nodeId === request.nodeId ? pendingResume.resumeContext : void 0;
+		const baseWithResume = resumeContext != null ? {
+			...base,
+			resumeContext
+		} : base;
 		const activationRequest = kind === "multi" ? this.nodeActivationRequestComposer.createMultiFromDefinitionWithActivation({
 			activationId: request.activationId,
 			runId: request.runId,
 			workflowId: request.workflowId,
 			parent: resolvedParent,
 			executionOptions: request.executionOptions ?? state.executionOptions,
-			base,
+			base: baseWithResume,
 			data,
 			definition: {
 				id: definition.id,
@@ -4893,7 +5549,7 @@ var NodeExecutionRequestHandlerService = class {
 			workflowId: request.workflowId,
 			parent: resolvedParent,
 			executionOptions: request.executionOptions ?? state.executionOptions,
-			base,
+			base: baseWithResume,
 			data,
 			definition: {
 				id: definition.id,
@@ -4902,6 +5558,13 @@ var NodeExecutionRequestHandlerService = class {
 			batchId,
 			input: inputsByPort.in ?? request.input ?? []
 		});
+		if (resumeContext != null) {
+			const clearedState = await this.workflowExecutionRepository.load(request.runId);
+			if (clearedState?.pendingResume?.activationId === request.activationId) await this.workflowExecutionRepository.save({
+				...clearedState,
+				pendingResume: void 0
+			});
+		}
 		await this.continuation.markNodeRunning({
 			runId: activationRequest.runId,
 			activationId: activationRequest.activationId,
@@ -4912,6 +5575,7 @@ var NodeExecutionRequestHandlerService = class {
 		try {
 			outputs = await this.nodeExecutor.execute(activationRequest);
 		} catch (error) {
+			if (error instanceof RunSuspendedError) return;
 			await this.resumeAfterExecutionError(activationRequest, this.asError(error));
 			return;
 		}
@@ -5472,7 +6136,7 @@ var EngineWaiters = class {
 		});
 	}
 	resolveRunCompletion(result) {
-		if (result.status !== "completed" && result.status !== "failed") return;
+		if (result.status !== "completed" && result.status !== "failed" && result.status !== "halted") return;
 		const list = this.completionWaiters.get(result.runId);
 		if (!list || list.length === 0) return;
 		this.completionWaiters.delete(result.runId);
@@ -5566,6 +6230,13 @@ var Engine = class {
 	async waitForWebhookResponse(runId) {
 		return await this.deps.runContinuationService.waitForWebhookResponse(runId);
 	}
+	/**
+	* Re-activate a suspended run item with a human decision (HITL).
+	* The HTTP resume endpoint calls this; this method exposes the engine primitive.
+	*/
+	async resumeRun(args) {
+		return await this.deps.runContinuationService.resumeRun(args);
+	}
 	async handleNodeExecutionRequest(request) {
 		await this.deps.nodeExecutionRequestHandler.handleNodeExecutionRequest(request);
 	}
@@ -5773,6 +6444,7 @@ var RunIntentService = class {
 		};
 		return await Promise.race([this.engine.waitForWebhookResponse(scheduled.runId), this.engine.waitForCompletion(scheduled.runId).then((completed) => {
 			if (completed.status === "failed") throw new Error(completed.error.message);
+			if (completed.status === "halted") throw new Error(`Run halted: ${completed.reason}`);
 			return {
 				runId: completed.runId,
 				workflowId: completed.workflowId,
@@ -5999,6 +6671,12 @@ Object.defineProperty(exports, 'DefaultWorkflowGraphFactory', {
     return DefaultWorkflowGraphFactory;
   }
 });
+Object.defineProperty(exports, 'DefinedNodeRegistry', {
+  enumerable: true,
+  get: function () {
+    return DefinedNodeRegistry;
+  }
+});
 Object.defineProperty(exports, 'ENGINE_EXECUTION_LIMITS_DEFAULTS', {
   enumerable: true,
   get: function () {
@@ -6053,6 +6731,30 @@ Object.defineProperty(exports, 'HintOnlyOffloadPolicy', {
     return HintOnlyOffloadPolicy;
   }
 });
+Object.defineProperty(exports, 'HitlResumeTokenSignerToken', {
+  enumerable: true,
+  get: function () {
+    return HitlResumeTokenSignerToken;
+  }
+});
+Object.defineProperty(exports, 'HitlTimeoutJobSchedulerToken', {
+  enumerable: true,
+  get: function () {
+    return HitlTimeoutJobSchedulerToken;
+  }
+});
+Object.defineProperty(exports, 'HitlWorkspaceIdToken', {
+  enumerable: true,
+  get: function () {
+    return HitlWorkspaceIdToken;
+  }
+});
+Object.defineProperty(exports, 'HumanTaskStoreToken', {
+  enumerable: true,
+  get: function () {
+    return HumanTaskStoreToken;
+  }
+});
 Object.defineProperty(exports, 'InMemoryBinaryStorage', {
   enumerable: true,
   get: function () {
@@ -6263,6 +6965,12 @@ Object.defineProperty(exports, 'RunPolicySnapshotFactory', {
     return RunPolicySnapshotFactory;
   }
 });
+Object.defineProperty(exports, 'RunSuspendedError', {
+  enumerable: true,
+  get: function () {
+    return RunSuspendedError;
+  }
+});
 Object.defineProperty(exports, 'RunTerminalPersistenceCoordinator', {
   enumerable: true,
   get: function () {
@@ -6359,6 +7067,24 @@ Object.defineProperty(exports, 'chatModel', {
     return chatModel;
   }
 });
+Object.defineProperty(exports, 'defineBatchNode', {
+  enumerable: true,
+  get: function () {
+    return defineBatchNode;
+  }
+});
+Object.defineProperty(exports, 'defineHumanApprovalNode', {
+  enumerable: true,
+  get: function () {
+    return defineHumanApprovalNode;
+  }
+});
+Object.defineProperty(exports, 'defineNode', {
+  enumerable: true,
+  get: function () {
+    return defineNode;
+  }
+});
 Object.defineProperty(exports, 'emitPorts', {
   enumerable: true,
   get: function () {
@@ -6377,6 +7103,12 @@ Object.defineProperty(exports, 'getPersistedRuntimeTypeMetadata', {
     return getPersistedRuntimeTypeMetadata;
   }
 });
+Object.defineProperty(exports, 'isHumanApprovalNode', {
+  enumerable: true,
+  get: function () {
+    return isHumanApprovalNode;
+  }
+});
 Object.defineProperty(exports, 'isPortsEmission', {
   enumerable: true,
   get: function () {
@@ -6401,4 +7133,4 @@ Object.defineProperty(exports, 'tool', {
     return tool;
   }
 });
-//# sourceMappingURL=runtime-DBzq5YBi.cjs.map
+//# sourceMappingURL=runtime-DjYXgOo0.cjs.map