@codemation/core 0.11.1 → 0.13.0

package/dist/{runtime-cxmUkk0l.js → runtime-6-U2Cou5.js}

@@ -1,8 +1,36 @@
-import { S as resolveItemExprsForExecution, _ as AgentConnectionNodeCollector, a as injectable, g as NodeIterationIdFactory, h as CredentialUnboundError, w as ConnectionNodeIdFactory, y as AgentConfigInspector } from "./di-0Wop7z1y.js";
+import { E as ConnectionNodeIdFactory, _ as CredentialUnboundError, a as injectable, g as SuspensionRequest, h as BINARY_DEFAULT_MAX_BYTES, v as NodeIterationIdFactory, w as resolveItemExprsForExecution, x as AgentConfigInspector, y as AgentConnectionNodeCollector } from "./di-D9Mv3kF3.js";
 import { ZodError, z } from "zod";
 import { ReadableStream } from "node:stream/web";
 import { createHash } from "node:crypto";
 
+//#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");
@@ -111,6 +139,305 @@ function chatModel(options = {}) {
 	return InjectableRuntimeDecoratorComposer.compose("chatModel", options, import.meta.url);
 }
 
+//#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 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 {
@@ -237,6 +564,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();
 	}
@@ -544,6 +890,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 = 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 {
@@ -594,6 +992,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()}`);
 	}
@@ -657,8 +1064,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 });
+		}
 	}
 };
 
@@ -703,7 +1126,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,
@@ -830,7 +1253,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 {
@@ -1297,6 +1722,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
@@ -1395,12 +1830,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({
@@ -1427,7 +1863,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);
+			}
 		};
 	}
 };
@@ -1769,6 +2209,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 {
@@ -1776,9 +2237,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();
 	}
@@ -1878,6 +2341,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);
@@ -1896,7 +2360,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 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,
@@ -1909,6 +2394,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. */
@@ -1935,8 +2421,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);
 	}
 };
 
@@ -2529,6 +3015,7 @@ var PersistedRunStateTerminalBuilder = class {
 			...args.state,
 			engineCounters: args.engineCounters,
 			status: args.status,
+			reason: args.reason,
 			pending: void 0,
 			queue: args.queue,
 			outputsByNode: args.outputsByNode,
@@ -2811,6 +3298,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],
@@ -2821,8 +3309,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;
@@ -3123,13 +3644,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);
@@ -3516,6 +4138,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}`;
@@ -4868,13 +5518,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,
@@ -4888,7 +5544,7 @@ var NodeExecutionRequestHandlerService = class {
 			workflowId: request.workflowId,
 			parent: resolvedParent,
 			executionOptions: request.executionOptions ?? state.executionOptions,
-			base,
+			base: baseWithResume,
 			data,
 			definition: {
 				id: definition.id,
@@ -4897,6 +5553,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,
@@ -4907,6 +5570,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;
 		}
@@ -5467,7 +6131,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);
@@ -5561,6 +6225,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);
 	}
@@ -5768,6 +6439,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,
@@ -5892,5 +6564,5 @@ var WorkflowRepositoryWebhookTriggerMatcherFactory = class {
 };
 
 //#endregion
-export { CostTrackingTelemetryMetricNames as $, PersistedWorkflowTokenRegistry as A, PersistedRuntimeTypeNameResolver as At, DefaultExecutionContextFactory as B, DefaultDrivingScheduler as C, chatModel as Ct, NodeInstanceFactoryFactory as D, InjectableRuntimeDecoratorComposer as Dt, StaticCostCatalog as E, tool as Et, RunnableOutputBehaviorResolver as F, NoOpExecutionTelemetryFactory as G, GenAiTelemetryAttributeNames as H, NodeOutputNormalizer as I, NoOpTelemetrySpanScope as J, NoOpExecutionTelemetry as K, ItemExprResolver as L, NodeExecutorFactory as M, NodeExecutor as N, NodeInstanceFactory as O, PersistedRuntimeTypeMetadataStore as Ot, InProcessRetryRunnerFactory as P, CostTrackingTelemetryAttributeNames as Q, InProcessRetryRunner as R, HintOnlyOffloadPolicy as S, WhenBuilder as St, RunPolicySnapshotFactory as T, node as Tt, CodemationTelemetryAttributeNames as U, CodemationTelemetryMetricNames as V, AllWorkflowsActiveWorkflowActivationPolicy as W, NoOpCostTrackingTelemetryFactory as X, NoOpTelemetryArtifactReference as Y, NoOpCostTrackingTelemetry as Z, RunTerminalPersistenceCoordinator as _, ConnectionInvocationIdFactory as _t, InMemoryLiveWorkflowRepository as a, isUnbrandedPortsEmissionShape as at, LocalOnlyScheduler as b, NodeIdSlugifier as bt, EngineFactory as c, getOriginIndexFromItem as ct, PollingTriggerRuntime as d, UnavailableBinaryStorage as dt, ExpRetryPolicy as et, PollingTriggerDedupWindow as f, NodeEventPublisher as ft, WorkflowPolicyErrorServices as g, WorkflowExecutableNodeClassifier as gt, WorkflowStoragePolicyEvaluator as h, WorkflowExecutableNodeClassifierFactory as ht, RunIntentService as i, isPortsEmission as it, MissingRuntimeTriggerToken as j, WorkflowSnapshotCodec as k, StackTraceCallSitePathResolver as kt, Engine as l, ChildExecutionScopeFactory as lt, InMemoryBinaryStorage as m, DefaultWorkflowGraphFactory as mt, WorkflowRepositoryWebhookTriggerMatcher as n, NoRetryPolicy as nt, EngineWorkflowRunnerServiceFactory as o, DefaultAsyncSleeper as ot, InMemoryRunDataFactory as p, ConnectionInvocationEventPublisher as pt, NoOpNodeExecutionTelemetry as q, RunIntentServiceFactory as r, emitPorts as rt, EngineWorkflowRunnerService as s, CredentialResolverFactory as st, WorkflowRepositoryWebhookTriggerMatcherFactory as t, RetryPolicy as tt, NoOpPollingTriggerLogger as u, DefaultExecutionBinaryService as ut, ENGINE_EXECUTION_LIMITS_DEFAULTS as v, WorkflowBuilder as vt, ConfigDrivenOffloadPolicy as w, getPersistedRuntimeTypeMetadata as wt, InlineDrivingScheduler as x, ChainCursor as xt, EngineExecutionLimitsPolicy as y, WorkflowDefinitionError as yt, CatalogBackedCostTrackingTelemetryFactory as z };
-//# sourceMappingURL=runtime-cxmUkk0l.js.map
+export { CostTrackingTelemetryAttributeNames as $, PersistedWorkflowTokenRegistry as A, node as At, CatalogBackedCostTrackingTelemetryFactory as B, HumanTaskStoreToken as Bt, DefaultDrivingScheduler as C, WhenBuilder as Ct, NodeInstanceFactoryFactory as D, defineNode as Dt, StaticCostCatalog as E, defineBatchNode as Et, InProcessRetryRunnerFactory as F, PersistedRuntimeTypeNameResolver as Ft, AllWorkflowsActiveWorkflowActivationPolicy as G, CodemationTelemetryMetricNames as H, RunnableOutputBehaviorResolver as I, DefinedNodeRegistry as It, NoOpNodeExecutionTelemetry as J, NoOpExecutionTelemetryFactory as K, NodeOutputNormalizer as L, HitlResumeTokenSignerToken as Lt, NodeExecutorFactory as M, InjectableRuntimeDecoratorComposer as Mt, NodeExecutor as N, PersistedRuntimeTypeMetadataStore as Nt, NodeInstanceFactory as O, chatModel as Ot, RunSuspendedError as P, StackTraceCallSitePathResolver as Pt, NoOpCostTrackingTelemetry as Q, ItemExprResolver as R, HitlTimeoutJobSchedulerToken as Rt, HintOnlyOffloadPolicy as S, ChainCursor as St, RunPolicySnapshotFactory as T, isHumanApprovalNode as Tt, GenAiTelemetryAttributeNames as U, DefaultExecutionContextFactory as V, CodemationTelemetryAttributeNames as W, NoOpTelemetryArtifactReference as X, NoOpTelemetrySpanScope as Y, NoOpCostTrackingTelemetryFactory as Z, RunTerminalPersistenceCoordinator as _, WorkflowExecutableNodeClassifier as _t, InMemoryLiveWorkflowRepository as a, isPortsEmission as at, LocalOnlyScheduler as b, WorkflowDefinitionError as bt, EngineFactory as c, CredentialResolverFactory as ct, PollingTriggerRuntime as d, DefaultExecutionBinaryService as dt, CostTrackingTelemetryMetricNames as et, PollingTriggerDedupWindow as f, UnavailableBinaryStorage as ft, WorkflowPolicyErrorServices as g, WorkflowExecutableNodeClassifierFactory as gt, WorkflowStoragePolicyEvaluator as h, DefaultWorkflowGraphFactory as ht, RunIntentService as i, emitPorts as it, MissingRuntimeTriggerToken as j, tool as jt, WorkflowSnapshotCodec as k, getPersistedRuntimeTypeMetadata as kt, Engine as l, getOriginIndexFromItem as lt, InMemoryBinaryStorage as m, ConnectionInvocationEventPublisher as mt, WorkflowRepositoryWebhookTriggerMatcher as n, RetryPolicy as nt, EngineWorkflowRunnerServiceFactory as o, isUnbrandedPortsEmissionShape as ot, InMemoryRunDataFactory as p, NodeEventPublisher as pt, NoOpExecutionTelemetry as q, RunIntentServiceFactory as r, NoRetryPolicy as rt, EngineWorkflowRunnerService as s, DefaultAsyncSleeper as st, WorkflowRepositoryWebhookTriggerMatcherFactory as t, ExpRetryPolicy as tt, NoOpPollingTriggerLogger as u, ChildExecutionScopeFactory as ut, ENGINE_EXECUTION_LIMITS_DEFAULTS as v, ConnectionInvocationIdFactory as vt, ConfigDrivenOffloadPolicy as w, defineHumanApprovalNode as wt, InlineDrivingScheduler as x, NodeIdSlugifier as xt, EngineExecutionLimitsPolicy as y, WorkflowBuilder as yt, InProcessRetryRunner as z, HitlWorkspaceIdToken as zt };
+//# sourceMappingURL=runtime-6-U2Cou5.js.map