@codemation/core 0.11.0 → 0.12.0

package/dist/{runtime-Duf3ClPw.js → runtime-BPZgnZ9G.js}

@@ -1,32 +1,33 @@
-import "reflect-metadata";
-import { container as container$1, delay, inject, injectAll, injectable, instanceCachingFactory, instancePerContainerCachingFactory, predicateAwareClassFactory, registry, singleton } from "tsyringe";
+import { C as resolveItemExprsForExecution, T as ConnectionNodeIdFactory, _ as NodeIterationIdFactory, a as injectable, b as AgentConfigInspector, g as CredentialUnboundError, h as SuspensionRequest, v as AgentConnectionNodeCollector } from "./di-DdsgWfVy.js";
 import { ZodError, z } from "zod";
 import { ReadableStream } from "node:stream/web";
 import { createHash } from "node:crypto";
 
-//#region src/di/CoreTokens.ts
-const CoreTokens = {
-	PersistedWorkflowTokenRegistry: Symbol.for("codemation.core.PersistedWorkflowTokenRegistry"),
-	CredentialSessionService: Symbol.for("codemation.core.CredentialSessionService"),
-	CredentialTypeRegistry: Symbol.for("codemation.core.CredentialTypeRegistry"),
-	WorkflowRunnerService: Symbol.for("codemation.core.WorkflowRunnerService"),
-	LiveWorkflowRepository: Symbol.for("codemation.core.LiveWorkflowRepository"),
-	WorkflowRepository: Symbol.for("codemation.core.WorkflowRepository"),
-	NodeResolver: Symbol.for("codemation.core.NodeResolver"),
-	WorkflowNodeInstanceFactory: Symbol.for("codemation.core.WorkflowNodeInstanceFactory"),
-	RunIdFactory: Symbol.for("codemation.core.RunIdFactory"),
-	ActivationIdFactory: Symbol.for("codemation.core.ActivationIdFactory"),
-	WorkflowExecutionRepository: Symbol.for("codemation.core.WorkflowExecutionRepository"),
-	TriggerSetupStateRepository: Symbol.for("codemation.core.TriggerSetupStateRepository"),
-	NodeActivationScheduler: Symbol.for("codemation.core.NodeActivationScheduler"),
-	RunDataFactory: Symbol.for("codemation.core.RunDataFactory"),
-	ExecutionContextFactory: Symbol.for("codemation.core.ExecutionContextFactory"),
-	RunEventBus: Symbol.for("codemation.core.RunEventBus"),
-	BinaryStorage: Symbol.for("codemation.core.BinaryStorage"),
-	WebhookBasePath: Symbol.for("codemation.core.WebhookBasePath"),
-	EngineExecutionLimitsPolicy: Symbol.for("codemation.core.EngineExecutionLimitsPolicy"),
-	WorkflowActivationPolicy: Symbol.for("codemation.core.WorkflowActivationPolicy"),
-	AgentMcpIntegration: Symbol.for("codemation.core.AgentMcpIntegration")
+//#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
@@ -139,287 +140,303 @@ function chatModel(options = {}) {
 }
 
 //#endregion
-//#region src/ai/NodeBackedToolConfig.ts
-var NodeBackedToolConfig = class {
-	type;
-	toolKind = "nodeBacked";
-	description;
-	presentation;
-	inputSchemaValue;
-	outputSchemaValue;
-	mapInputValue;
-	mapOutputValue;
-	constructor(name, node$1, options) {
-		this.name = name;
-		this.node = node$1;
-		this.type = node$1.type;
-		this.description = options.description;
-		this.presentation = options.presentation;
-		this.inputSchemaValue = options.inputSchema;
-		this.outputSchemaValue = options.outputSchema;
-		this.mapInputValue = options.mapInput;
-		this.mapOutputValue = options.mapOutput;
-	}
-	getCredentialRequirements() {
-		return this.node.getCredentialRequirements?.() ?? [];
-	}
-	getInputSchema() {
-		return this.inputSchemaValue;
-	}
-	getOutputSchema() {
-		return this.outputSchemaValue;
-	}
-	toNodeItem(args) {
-		const mapped = this.mapInputValue?.(args) ?? args.input;
-		if (this.isItem(mapped)) return mapped;
-		return { json: mapped };
-	}
-	toToolOutput(args) {
-		const raw = this.mapOutputValue?.(args) ?? this.readDefaultToolOutput(args.outputs);
-		return this.outputSchemaValue.parse(raw);
-	}
-	readDefaultToolOutput(outputs) {
-		const firstMainItem = outputs.main?.[0];
-		if (!firstMainItem) throw new Error(`Node-backed tool "${this.name}" did not produce a main output item.`);
-		return firstMainItem.json;
-	}
-	isItem(value) {
-		return typeof value === "object" && value !== null && "json" in value;
+//#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());
 	}
 };
-
-//#endregion
-//#region src/contracts/itemExpr.ts
-const ITEM_EXPR_BRAND = Symbol.for("codemation.itemExpr");
-function itemExpr(fn) {
-	return {
-		[ITEM_EXPR_BRAND]: true,
-		fn
+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);
+		}
 	};
-}
-function isItemExpr(value) {
-	if (typeof value !== "object" || value === null) return false;
-	const v = value;
-	if (v[ITEM_EXPR_BRAND] === true) return true;
-	const keys = Object.keys(v);
-	if (keys.length === 1 && keys[0] === "fn" && typeof v.fn === "function") return true;
-	for (const sym of Object.getOwnPropertySymbols(v)) if (sym.description === "codemation.itemExpr" && v[sym] === true) return true;
-	return false;
-}
-function containsItemExprInUnknown(value, seen = /* @__PURE__ */ new WeakSet()) {
-	if (isItemExpr(value)) return true;
-	if (value === null || typeof value !== "object") return false;
-	if (seen.has(value)) return false;
-	seen.add(value);
-	if (Array.isArray(value)) return value.some((entry) => containsItemExprInUnknown(entry, seen));
-	for (const entry of Object.values(value)) if (containsItemExprInUnknown(entry, seen)) return true;
-	return false;
-}
-/**
-* Deep-resolves {@link itemExpr} leaves. Returns a new graph (does not mutate the original config object).
-*/
-async function resolveItemExprsInUnknown(value, args, seen = /* @__PURE__ */ new WeakSet()) {
-	if (isItemExpr(value)) return await Promise.resolve(value.fn(args));
-	if (value === null || typeof value !== "object") return value;
-	if (seen.has(value)) return value;
-	seen.add(value);
-	if (Array.isArray(value)) {
-		const out$1 = [];
-		for (let i = 0; i < value.length; i++) out$1.push(await resolveItemExprsInUnknown(value[i], args, seen));
-		return out$1;
-	}
-	const rec = value;
-	const entries = Object.entries(rec);
-	const proto = Object.getPrototypeOf(value);
-	if (proto !== Object.prototype && proto !== null && entries.length === 0) return value;
-	const out = Object.create(proto);
-	for (const [k, v] of entries) out[k] = await resolveItemExprsInUnknown(v, args, seen);
-	return out;
-}
-/**
-* Clones runnable config (best-effort) so per-item {@link itemExpr} resolution never mutates shared instances.
-*/
-async function resolveItemExprsForExecution(config, nodeCtx, item, itemIndex, items) {
-	const exprArgs = {
-		item,
-		itemIndex,
-		items,
-		ctx: {
-			runId: nodeCtx.runId,
-			workflowId: nodeCtx.workflowId,
-			nodeId: nodeCtx.nodeId,
-			activationId: nodeCtx.activationId,
-			data: nodeCtx.data
+	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 });
 		}
 	};
-	if (!containsItemExprInUnknown(config)) return;
-	return await resolveItemExprsInUnknown(config, exprArgs);
+	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/ai/AgentConfigInspectorFactory.ts
-var AgentConfigInspector = class {
-	static isAgentNodeConfig(config) {
-		if (!config) return false;
-		const candidate = config;
-		return !!candidate.chatModel && this.hasCompatibleMessageConfiguration(candidate);
-	}
-	static hasCompatibleMessageConfiguration(candidate) {
-		const messages = candidate.messages;
-		if (messages === void 0 || messages === null) return false;
-		if (Array.isArray(messages)) return messages.length > 0;
-		if (typeof messages === "object") {
-			if (isItemExpr(messages)) return true;
-			const o = messages;
-			return Array.isArray(o.prompt) && o.prompt.length > 0 || typeof o.buildMessages === "function";
+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)];
 		}
-		return false;
-	}
-};
+	};
+	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/workflow/definition/ConnectionNodeIdFactory.ts
+//#region src/authoring/defineHumanApprovalNode.types.ts
 /**
-* Deterministic ids for workflow connection-owned child nodes (LLM slot, tools, etc.).
-* These are stable across loads.
+* Returns `true` when `node` was created by {@link defineHumanApprovalNode}.
+* Uses the `humanApprovalToolBehavior` typed field as the discriminant.
 */
-var ConnectionNodeIdFactory = class {
-	static connectionSegment = "__conn__";
-	static languageModelConnectionNodeId(parentNodeId) {
-		return `${parentNodeId}${this.connectionSegment}llm`;
-	}
-	static toolConnectionNodeId(parentNodeId, toolName) {
-		const normalized = this.normalizeToolName(toolName);
-		return `${parentNodeId}${this.connectionSegment}tool${this.connectionSegment}${normalized}`;
-	}
-	static mcpConnectionNodeId(parentNodeId, serverId) {
-		return `${parentNodeId}${this.connectionSegment}mcp${this.connectionSegment}${serverId}`;
-	}
-	static isMcpConnectionNodeId(nodeId) {
-		return nodeId.includes(`${this.connectionSegment}mcp${this.connectionSegment}`);
-	}
-	static parseMcpConnectionNodeId(nodeId) {
-		if (!this.isMcpConnectionNodeId(nodeId)) return;
-		const marker = `${this.connectionSegment}mcp${this.connectionSegment}`;
-		const idx = nodeId.lastIndexOf(marker);
-		if (idx < 0) return;
-		const parentNodeId = nodeId.slice(0, idx);
-		const serverId = nodeId.slice(idx + marker.length);
-		if (!parentNodeId || !serverId) return;
-		return {
-			parentNodeId,
-			serverId
-		};
-	}
-	static isLanguageModelConnectionNodeId(nodeId) {
-		return nodeId.endsWith(`${this.connectionSegment}llm`);
-	}
-	static isToolConnectionNodeId(nodeId) {
-		return nodeId.includes(`${this.connectionSegment}tool${this.connectionSegment}`);
-	}
-	static parseLanguageModelConnectionNodeId(nodeId) {
-		if (!this.isLanguageModelConnectionNodeId(nodeId)) return;
-		const suffix = `${this.connectionSegment}llm`;
-		const parentNodeId = nodeId.slice(0, -suffix.length);
-		return parentNodeId ? { parentNodeId } : void 0;
-	}
-	static parseToolConnectionNodeId(nodeId) {
-		if (!this.isToolConnectionNodeId(nodeId)) return;
-		const marker = `${this.connectionSegment}tool${this.connectionSegment}`;
-		const idx = nodeId.lastIndexOf(marker);
-		if (idx < 0) return;
-		const parentNodeId = nodeId.slice(0, idx);
-		const normalizedToolName = nodeId.slice(idx + marker.length);
-		if (!parentNodeId || !normalizedToolName) return;
-		return {
-			parentNodeId,
-			normalizedToolName
-		};
-	}
-	/** True when `nodeId` is a connection-owned child of `parentNodeId` (LLM or tool slot). */
-	static isConnectionOwnedDescendantOf(parentNodeId, nodeId) {
-		return nodeId.startsWith(`${parentNodeId}${this.connectionSegment}`);
-	}
-	/** Normalizes a tool display name to a stable id segment. */
-	static normalizeToolName(toolName) {
-		return toolName.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "") || "tool";
-	}
-};
-
-//#endregion
-//#region src/ai/AgentConnectionNodeCollector.ts
-const AgentConnectionNodeCollector = new class {
-	collect(parentNodeId, agentConfig, mcpServerResolver) {
-		const collected = [];
-		this.collectInto(parentNodeId, agentConfig, collected, mcpServerResolver);
-		return collected;
-	}
-	collectInto(parentNodeId, agentConfig, collected, mcpServerResolver) {
-		collected.push({
-			nodeId: ConnectionNodeIdFactory.languageModelConnectionNodeId(parentNodeId),
-			parentNodeId,
-			connectionName: "llm",
-			role: "languageModel",
-			name: agentConfig.chatModel.presentation?.label ?? agentConfig.chatModel.name,
-			typeName: agentConfig.chatModel.name,
-			icon: agentConfig.chatModel.presentation?.icon,
-			credentialSource: agentConfig.chatModel
-		});
-		for (const tool$1 of agentConfig.tools ?? []) {
-			const toolNodeId = ConnectionNodeIdFactory.toolConnectionNodeId(parentNodeId, tool$1.name);
-			const isNestedAgent = this.isNodeBackedAgentTool(tool$1);
-			collected.push({
-				nodeId: toolNodeId,
-				parentNodeId,
-				connectionName: "tools",
-				role: isNestedAgent ? "nestedAgent" : "tool",
-				name: tool$1.presentation?.label ?? tool$1.name,
-				typeName: tool$1.name,
-				icon: tool$1.presentation?.icon,
-				credentialSource: tool$1
-			});
-			this.collectNestedAgentTools(toolNodeId, tool$1, collected, mcpServerResolver);
-		}
-		if (mcpServerResolver) {
-			const mcpServers = agentConfig.mcpServers;
-			for (const serverId of mcpServers ?? []) {
-				const decl = mcpServerResolver(serverId);
-				if (!decl) continue;
-				const acceptedTypes = decl.acceptedCredentialTypes ?? [];
-				collected.push({
-					nodeId: ConnectionNodeIdFactory.mcpConnectionNodeId(parentNodeId, serverId),
-					parentNodeId,
-					connectionName: "tools",
-					role: "tool",
-					name: decl.displayName,
-					typeName: serverId,
-					icon: "lucide:plug",
-					credentialSource: { getCredentialRequirements: () => [{
-						slotKey: "credential",
-						label: decl.displayName,
-						acceptedTypes
-					}] }
+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
+		});
 	}
-	collectNestedAgentTools(toolNodeId, tool$1, collected, mcpServerResolver) {
-		if (!this.isNodeBackedAgentTool(tool$1)) return;
-		const innerAgent = tool$1 instanceof NodeBackedToolConfig ? tool$1.node : tool$1.node;
-		this.collectInto(toolNodeId, innerAgent, collected, mcpServerResolver);
-	}
-	/**
-	* After JSON round-trip (persisted snapshots), tools are plain objects — `instanceof NodeBackedToolConfig` fails.
-	* Detect node-backed tools structurally via {@link NodeBackedToolConfig#toolKind}.
-	*/
-	isNodeBackedAgentTool(tool$1) {
-		if (tool$1 instanceof NodeBackedToolConfig) return AgentConfigInspector.isAgentNodeConfig(tool$1.node);
-		if (!tool$1 || typeof tool$1 !== "object") return false;
-		const t = tool$1;
-		if (t.toolKind !== "nodeBacked") return false;
-		return AgentConfigInspector.isAgentNodeConfig(t.node);
-	}
-}();
+	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
@@ -547,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();
 	}
@@ -711,33 +747,6 @@ var ConnectionInvocationIdFactory = class {
 	}
 };
 
-//#endregion
-//#region src/workflow/definition/NodeIterationIdFactory.ts
-/**
-* Unique ids for one per-item iteration of a runnable node's execute loop.
-*
-* Activations are per-batch (one scheduled execution of a node, possibly with N items).
-* Iterations refine that to one identifier per item-index inside the batch loop, so per-item
-* connection invocations and telemetry can be grouped without time-window heuristics.
-*
-* Uses Web Crypto's `randomUUID` (Node 19+ and all modern browsers) so this module is safe
-* to include in the browser entry. Importing `node:crypto` here previously leaked into the
-* canvas client bundle through `browser.ts` and OOM'd consumers' Turbopack builds.
-*/
-var NodeIterationIdFactory = class {
-	static create() {
-		return `iter_${globalThis.crypto.randomUUID()}`;
-	}
-	/** Deterministic id for tests when a stable sequence is needed. */
-	static createForTest(seed, sequence) {
-		return `iter_${seed}_${sequence}`;
-	}
-	/** Deterministic id derived from a connection node id (for sub-agent / tool-call scopes). */
-	static createForConnection(connectionNodeId, sequence) {
-		return `iter_${connectionNodeId}_${sequence}`;
-	}
-};
-
 //#endregion
 //#region src/workflow/definition/WorkflowExecutableNodeClassifier.ts
 /**
@@ -1040,7 +1049,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,
@@ -1167,7 +1176,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 {
@@ -1419,20 +1430,6 @@ var DefaultAsyncSleeper = class {
 	}
 };
 
-//#endregion
-//#region src/contracts/NoOpAgentMcpIntegration.ts
-/**
-* No-op implementation of AgentMcpIntegration.
-* Registered by the core engine runtime as a fallback when the host does not
-* supply a real implementation (e.g. in unit tests or headless engine setups).
-* Always returns an empty tool map so the agent runs with node-backed tools only.
-*/
-var NoOpAgentMcpIntegration = class {
-	async prepareMcpTools() {
-		return /* @__PURE__ */ new Map();
-	}
-};
-
 //#endregion
 //#region src/contracts/emitPorts.ts
 const EMIT_PORTS_BRAND = Symbol.for("codemation.emitPorts");
@@ -1495,21 +1492,6 @@ var ExpRetryPolicy = class {
 	}
 };
 
-//#endregion
-//#region src/contracts/credentialTypes.ts
-var CredentialUnboundError = class CredentialUnboundError extends Error {
-	constructor(bindingKey, acceptedTypes = []) {
-		super(CredentialUnboundError.createMessage(bindingKey, acceptedTypes));
-		this.bindingKey = bindingKey;
-		this.acceptedTypes = acceptedTypes;
-		this.name = "CredentialUnboundError";
-	}
-	static createMessage(bindingKey, acceptedTypes) {
-		const acceptedTypesSuffix = acceptedTypes.length > 0 ? ` Accepted credential types: ${acceptedTypes.join(", ")}.` : "";
-		return `Credential slot "${bindingKey.slotKey}" is not bound for workflow ${bindingKey.workflowId} node ${bindingKey.nodeId}.${acceptedTypesSuffix}`;
-	}
-};
-
 //#endregion
 //#region src/contracts/CostTrackingTelemetryContract.ts
 const CostTrackingTelemetryMetricNames = {
@@ -1631,19 +1613,6 @@ var NoOpExecutionTelemetryFactory = class {
 	}
 };
 
-//#endregion
-//#region src/contracts/runFinishedAtFactory.ts
-/** Derives workflow end time from persisted run root or node snapshots for run listings. */
-var RunFinishedAtFactory = class {
-	static resolveIso(state) {
-		if (state.finishedAt && state.status !== "running" && state.status !== "pending") return state.finishedAt;
-		if (state.status === "running" || state.status === "pending") return;
-		let max;
-		for (const snap of Object.values(state.nodeSnapshotsByNodeId)) if (snap?.finishedAt && (!max || snap.finishedAt > max)) max = snap.finishedAt;
-		return max;
-	}
-};
-
 //#endregion
 //#region src/contracts/workflowActivationPolicy.ts
 /** Default for tests and harnesses: every workflow is treated as active (legacy behavior). */
@@ -1676,6 +1645,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
@@ -1701,13 +1680,6 @@ var CodemationTelemetryMetricNames = class {
 	static gmailAttachmentBytes = "codemation.gmail.attachment_bytes";
 };
 
-//#endregion
-//#region src/contracts/workflowTypes.ts
-function nodeRef(nodeId) {
-	return nodeId;
-}
-const branchRef = (index) => `$${index}`;
-
 //#endregion
 //#region src/execution/ExecutionTelemetryCostTrackingDecoratorFactory.ts
 var ExecutionTelemetryCostTrackingDecoratorFactory = class {
@@ -1781,12 +1753,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({
@@ -1813,7 +1786,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);
+			}
 		};
 	}
 };
@@ -2155,6 +2132,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 {
@@ -2162,9 +2160,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();
 	}
@@ -2264,6 +2264,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);
@@ -2282,7 +2283,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,
@@ -2295,6 +2317,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. */
@@ -2321,8 +2344,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);
 	}
 };
 
@@ -2915,6 +2938,7 @@ var PersistedRunStateTerminalBuilder = class {
 			...args.state,
 			engineCounters: args.engineCounters,
 			status: args.status,
+			reason: args.reason,
 			pending: void 0,
 			queue: args.queue,
 			outputsByNode: args.outputsByNode,
@@ -3197,6 +3221,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],
@@ -3207,8 +3232,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;
@@ -3509,13 +3567,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);
@@ -3902,6 +4061,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}`;
@@ -5254,13 +5441,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,
@@ -5274,7 +5467,7 @@ var NodeExecutionRequestHandlerService = class {
 			workflowId: request.workflowId,
 			parent: resolvedParent,
 			executionOptions: request.executionOptions ?? state.executionOptions,
-			base,
+			base: baseWithResume,
 			data,
 			definition: {
 				id: definition.id,
@@ -5283,6 +5476,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,
@@ -5293,6 +5493,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;
 		}
@@ -5853,7 +6054,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);
@@ -5947,6 +6148,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);
 	}
@@ -6154,6 +6362,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,
@@ -6278,5 +6487,5 @@ var WorkflowRepositoryWebhookTriggerMatcherFactory = class {
 };
 
 //#endregion
-export { NoOpCostTrackingTelemetryFactory as $, registry as $t, PersistedWorkflowTokenRegistry as A, ConnectionNodeIdFactory as At, DefaultExecutionContextFactory as B, tool as Bt, DefaultDrivingScheduler as C, ConnectionInvocationIdFactory as Ct, NodeInstanceFactoryFactory as D, ChainCursor as Dt, StaticCostCatalog as E, NodeIdSlugifier as Et, RunnableOutputBehaviorResolver as F, resolveItemExprsInUnknown as Ft, CodemationTelemetryAttributeNames as G, container$1 as Gt, nodeRef as H, PersistedRuntimeTypeMetadataStore as Ht, NodeOutputNormalizer as I, NodeBackedToolConfig as It, NoOpExecutionTelemetryFactory as J, injectAll as Jt, AllWorkflowsActiveWorkflowActivationPolicy as K, delay as Kt, ItemExprResolver as L, chatModel as Lt, NodeExecutorFactory as M, isItemExpr as Mt, NodeExecutor as N, itemExpr as Nt, NodeInstanceFactory as O, WhenBuilder as Ot, InProcessRetryRunnerFactory as P, resolveItemExprsForExecution as Pt, NoOpTelemetryArtifactReference as Q, predicateAwareClassFactory as Qt, InProcessRetryRunner as R, getPersistedRuntimeTypeMetadata as Rt, HintOnlyOffloadPolicy as S, NodeIterationIdFactory as St, RunPolicySnapshotFactory as T, WorkflowDefinitionError as Tt, CodemationTelemetryMetricNames as U, StackTraceCallSitePathResolver as Ut, branchRef as V, InjectableRuntimeDecoratorComposer as Vt, GenAiTelemetryAttributeNames as W, PersistedRuntimeTypeNameResolver as Wt, NoOpNodeExecutionTelemetry as X, instanceCachingFactory as Xt, NoOpExecutionTelemetry as Y, injectable as Yt, NoOpTelemetrySpanScope as Z, instancePerContainerCachingFactory as Zt, RunTerminalPersistenceCoordinator as _, NodeEventPublisher as _t, InMemoryLiveWorkflowRepository as a, RetryPolicy as at, LocalOnlyScheduler as b, WorkflowExecutableNodeClassifierFactory as bt, EngineFactory as c, isPortsEmission as ct, PollingTriggerRuntime as d, DefaultAsyncSleeper as dt, singleton as en, NoOpCostTrackingTelemetry as et, PollingTriggerDedupWindow as f, CredentialResolverFactory as ft, WorkflowPolicyErrorServices as g, UnavailableBinaryStorage as gt, WorkflowStoragePolicyEvaluator as h, DefaultExecutionBinaryService as ht, RunIntentService as i, ExpRetryPolicy as it, MissingRuntimeTriggerToken as j, AgentConfigInspector as jt, WorkflowSnapshotCodec as k, AgentConnectionNodeCollector as kt, Engine as l, isUnbrandedPortsEmissionShape as lt, InMemoryBinaryStorage as m, ChildExecutionScopeFactory as mt, WorkflowRepositoryWebhookTriggerMatcher as n, CostTrackingTelemetryMetricNames as nt, EngineWorkflowRunnerServiceFactory as o, NoRetryPolicy as ot, InMemoryRunDataFactory as p, getOriginIndexFromItem as pt, RunFinishedAtFactory as q, inject as qt, RunIntentServiceFactory as r, CredentialUnboundError as rt, EngineWorkflowRunnerService as s, emitPorts as st, WorkflowRepositoryWebhookTriggerMatcherFactory as t, CoreTokens as tn, CostTrackingTelemetryAttributeNames as tt, NoOpPollingTriggerLogger as u, NoOpAgentMcpIntegration as ut, ENGINE_EXECUTION_LIMITS_DEFAULTS as v, ConnectionInvocationEventPublisher as vt, ConfigDrivenOffloadPolicy as w, WorkflowBuilder as wt, InlineDrivingScheduler as x, WorkflowExecutableNodeClassifier as xt, EngineExecutionLimitsPolicy as y, DefaultWorkflowGraphFactory as yt, CatalogBackedCostTrackingTelemetryFactory as z, node as zt };
-//# sourceMappingURL=runtime-Duf3ClPw.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-BPZgnZ9G.js.map