@codemation/core 0.11.0 → 0.12.0

package/dist/{runtime-vH0EeZzH.cjs → runtime-CyW9c9XM.cjs}

@@ -1,59 +1,38 @@
-//#region rolldown:runtime
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-
-//#endregion
-require("reflect-metadata");
-let tsyringe = require("tsyringe");
-tsyringe = __toESM(tsyringe);
+const require_di = require('./di-tO6R7VJV.cjs');
 let zod = require("zod");
-zod = __toESM(zod);
+zod = require_di.__toESM(zod);
 let node_stream_web = require("node:stream/web");
-node_stream_web = __toESM(node_stream_web);
+node_stream_web = require_di.__toESM(node_stream_web);
 let node_crypto = require("node:crypto");
-node_crypto = __toESM(node_crypto);
+node_crypto = require_di.__toESM(node_crypto);
+let tsyringe = require("tsyringe");
+tsyringe = require_di.__toESM(tsyringe);
+
+//#region src/contracts/humanTaskStoreTypes.ts
+const HumanTaskStoreToken = Symbol.for("codemation.core.HumanTaskStore");
 
-//#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")
+//#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
@@ -166,287 +145,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 require_di.SuspensionRequest({
+					decisionSchema: opts.decisionSchema,
+					timeout,
+					onTimeout,
+					subject,
+					metadata: {
+						channel: opts.channel,
+						nodeKey: opts.key,
+						approvedPredicateSource: opts.approvedPredicate?.toString() ?? null
+					},
+					deliver: (handle) => opts.deliver({
+						task: handle,
+						config,
+						input: args.input,
+						item: args.item
+					}, ctx)
 				});
 			}
+			return await handleResume(args.item, ctx.resumeContext, opts.decisionSchema, resolvedPredicate, opts.onDecision, opts.onTimeout, ctx);
 		}
+	});
+	return Object.assign(inner, { humanApprovalToolBehavior: { onRejected: "return" } });
+}
+function resolveApprovedPredicate(schema, predicate) {
+	if (predicate) return predicate;
+	const shape = schema.shape;
+	if (shape && typeof shape === "object" && "approved" in shape) return (d) => d.approved === true;
+	throw new Error("defineHumanApprovalNode: decisionSchema has no \"approved\" field and no approvedPredicate was provided. Either add { approved: z.boolean() } to the decision schema or supply approvedPredicate explicitly.");
+}
+function buildSubject(title, item, ctx) {
+	return {
+		title,
+		summary: "",
+		attributes: {
+			workflowId: ctx.workflowId,
+			nodeId: ctx.nodeId,
+			item: item.json
+		}
+	};
+}
+function mergeDecision(item, decision) {
+	return {
+		json: {
+			...item.json,
+			decision
+		},
+		binary: item.binary,
+		meta: item.meta
+	};
+}
+async function handleResume(item, resumeContext, decisionSchema, resolvedPredicate, onDecision, onTimeoutCb, ctx) {
+	const { decision: dec, delivery, task } = resumeContext;
+	if (dec.kind === "timed_out" || dec.kind === "auto_accepted") {
+		const policy = dec.kind === "auto_accepted" ? "auto-accept" : "halt";
+		await onTimeoutCb?.({
+			task,
+			delivery,
+			item,
+			policy
+		}, ctx);
+		return mergeDecision(item, {
+			status: dec.kind === "auto_accepted" ? "auto-accepted" : "timed-out",
+			decidedAt: dec.at
+		});
 	}
-	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
@@ -574,6 +569,25 @@ var ChainCursor = class ChainCursor {
 		}
 		return new ChainCursor(this.wf, nextEndpoints);
 	}
+	/**
+	* Chainable shorthand for `.then(node.create(config, metadata?.name, metadata?.nodeId))`.
+	*
+	* Signals to readers that this step suspends the run and waits for a human decision.
+	* Throws at workflow-build time if `node` was not created via `defineHumanApprovalNode`.
+	*
+	* @example
+	* ```ts
+	* workflow
+	*   .trigger(...)
+	*   .humanApproval(inboxApproval, { title: "Approve?", body: "...", priority: "normal" })
+	*   .then(nextStep.create(...))
+	*   .build();
+	* ```
+	*/
+	humanApproval(node$1, config, metadata) {
+		if (!isHumanApprovalNode(node$1)) throw new Error(`.humanApproval() requires a node created via defineHumanApprovalNode (got '${node$1.key ?? String(node$1)}').`);
+		return this.then(node$1.create(config, metadata?.name, metadata?.nodeId));
+	}
 	build() {
 		return this.wf.build();
 	}
@@ -685,7 +699,7 @@ var WorkflowBuilder = class {
 				tokenName,
 				label: node$1.name ?? ""
 			});
-			if (AgentConfigInspector.isAgentNodeConfig(node$1.config)) for (const child of AgentConnectionNodeCollector.collect(node$1.id, node$1.config)) entries.push({
+			if (require_di.AgentConfigInspector.isAgentNodeConfig(node$1.config)) for (const child of require_di.AgentConnectionNodeCollector.collect(node$1.id, node$1.config)) entries.push({
 				nodeId: child.nodeId,
 				tokenName: child.typeName,
 				label: child.name
@@ -738,33 +752,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
 /**
@@ -1067,7 +1054,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,
@@ -1194,7 +1181,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 {
@@ -1446,20 +1435,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");
@@ -1522,21 +1497,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 = {
@@ -1658,19 +1618,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). */
@@ -1703,6 +1650,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
@@ -1728,13 +1685,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 {
@@ -1808,12 +1758,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({
@@ -1840,7 +1791,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);
+			}
 		};
 	}
 };
@@ -2016,7 +1971,7 @@ var InProcessRetryRunner = class InProcessRetryRunner {
 var ItemExprResolver = class {
 	async resolveConfigForItem(ctx, item, itemIndex, items) {
 		if (!ctx) throw new Error("ItemExprResolver.resolveConfigForItem: ctx is required");
-		const resolvedConfig = await resolveItemExprsForExecution(ctx.config, ctx, item, itemIndex, items);
+		const resolvedConfig = await require_di.resolveItemExprsForExecution(ctx.config, ctx, item, itemIndex, items);
 		const merged = resolvedConfig !== void 0 && resolvedConfig !== null ? resolvedConfig : ctx.config;
 		if (merged === void 0 || merged === null) return ctx;
 		return {
@@ -2182,6 +2137,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 {
@@ -2189,9 +2165,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();
 	}
@@ -2212,8 +2190,8 @@ var NodeExecutor = class {
 		}
 	}
 	isCredentialError(e) {
-		if (e instanceof CredentialUnboundError) return true;
-		return (e instanceof Error ? e.cause : void 0) instanceof CredentialUnboundError;
+		if (e instanceof require_di.CredentialUnboundError) return true;
+		return (e instanceof Error ? e.cause : void 0) instanceof require_di.CredentialUnboundError;
 	}
 	async executeMultiInputActivation(request, node$1) {
 		const multiInputNode = node$1;
@@ -2291,6 +2269,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);
@@ -2299,7 +2278,7 @@ var NodeExecutor = class {
 			const resolvedCtx = await this.itemExprResolver.resolveConfigForItem(runnableCtx, item, i, inputBatch);
 			const iterationCtx = {
 				...this.pickExecutionContext(runnableCtx, resolvedCtx),
-				iterationId: NodeIterationIdFactory.create(),
+				iterationId: require_di.NodeIterationIdFactory.create(),
 				itemIndex: i
 			};
 			const args = {
@@ -2309,7 +2288,28 @@ var NodeExecutor = class {
 				items: inputBatch,
 				ctx: iterationCtx
 			};
-			const raw = await Promise.resolve(node$1.execute(args));
+			let raw;
+			try {
+				raw = await Promise.resolve(node$1.execute(args));
+			} catch (e) {
+				if (e instanceof require_di.SuspensionRequest || e instanceof Error && e.name === "SuspensionRequest" && typeof e.request === "object") {
+					if (!this.suspensionHandler || !this.loadRunState) throw new Error(`Node ${request.nodeId} threw SuspensionRequest but this NodeExecutor has no suspensionHandler configured.`, { cause: e });
+					const state = await this.loadRunState(request.runId);
+					if (!state) throw new Error(`NodeExecutor: run state not found for runId ${request.runId} during suspension`, { cause: e });
+					await this.suspensionHandler.handle({
+						runId: request.runId,
+						nodeId: request.nodeId,
+						activationId: request.activationId,
+						itemIndex: i,
+						suspensionRequest: e,
+						state,
+						telemetry: iterationCtx.telemetry
+					});
+					hasSuspension = true;
+					continue;
+				}
+				throw e;
+			}
 			const normalized = this.outputNormalizer.normalizeExecuteResult({
 				baseItem: item,
 				raw,
@@ -2322,6 +2322,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. */
@@ -2348,8 +2349,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);
 	}
 };
 
@@ -2942,6 +2943,7 @@ var PersistedRunStateTerminalBuilder = class {
 			...args.state,
 			engineCounters: args.engineCounters,
 			status: args.status,
+			reason: args.reason,
 			pending: void 0,
 			queue: args.queue,
 			outputsByNode: args.outputsByNode,
@@ -3224,6 +3226,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],
@@ -3234,8 +3237,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;
@@ -3536,13 +3572,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);
@@ -3929,6 +4066,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}`;
@@ -4201,7 +4366,7 @@ var CurrentStateFrontierPlanner = class CurrentStateFrontierPlanner {
 	isRuntimeDescendant(nodeId, descendantNodeIds) {
 		for (const descendantNodeId of descendantNodeIds) {
 			if (nodeId === descendantNodeId) return false;
-			if (ConnectionNodeIdFactory.isConnectionOwnedDescendantOf(descendantNodeId, nodeId)) return true;
+			if (require_di.ConnectionNodeIdFactory.isConnectionOwnedDescendantOf(descendantNodeId, nodeId)) return true;
 		}
 		return false;
 	}
@@ -5281,13 +5446,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,
@@ -5301,7 +5472,7 @@ var NodeExecutionRequestHandlerService = class {
 			workflowId: request.workflowId,
 			parent: resolvedParent,
 			executionOptions: request.executionOptions ?? state.executionOptions,
-			base,
+			base: baseWithResume,
 			data,
 			definition: {
 				id: definition.id,
@@ -5310,6 +5481,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,
@@ -5320,6 +5498,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;
 		}
@@ -5880,7 +6059,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);
@@ -5974,6 +6153,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);
 	}
@@ -6181,6 +6367,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,
@@ -6305,18 +6492,6 @@ var WorkflowRepositoryWebhookTriggerMatcherFactory = class {
 };
 
 //#endregion
-Object.defineProperty(exports, 'AgentConfigInspector', {
-  enumerable: true,
-  get: function () {
-    return AgentConfigInspector;
-  }
-});
-Object.defineProperty(exports, 'AgentConnectionNodeCollector', {
-  enumerable: true,
-  get: function () {
-    return AgentConnectionNodeCollector;
-  }
-});
 Object.defineProperty(exports, 'AllWorkflowsActiveWorkflowActivationPolicy', {
   enumerable: true,
   get: function () {
@@ -6371,18 +6546,6 @@ Object.defineProperty(exports, 'ConnectionInvocationIdFactory', {
     return ConnectionInvocationIdFactory;
   }
 });
-Object.defineProperty(exports, 'ConnectionNodeIdFactory', {
-  enumerable: true,
-  get: function () {
-    return ConnectionNodeIdFactory;
-  }
-});
-Object.defineProperty(exports, 'CoreTokens', {
-  enumerable: true,
-  get: function () {
-    return CoreTokens;
-  }
-});
 Object.defineProperty(exports, 'CostTrackingTelemetryAttributeNames', {
   enumerable: true,
   get: function () {
@@ -6401,12 +6564,6 @@ Object.defineProperty(exports, 'CredentialResolverFactory', {
     return CredentialResolverFactory;
   }
 });
-Object.defineProperty(exports, 'CredentialUnboundError', {
-  enumerable: true,
-  get: function () {
-    return CredentialUnboundError;
-  }
-});
 Object.defineProperty(exports, 'DefaultAsyncSleeper', {
   enumerable: true,
   get: function () {
@@ -6437,6 +6594,12 @@ Object.defineProperty(exports, 'DefaultWorkflowGraphFactory', {
     return DefaultWorkflowGraphFactory;
   }
 });
+Object.defineProperty(exports, 'DefinedNodeRegistry', {
+  enumerable: true,
+  get: function () {
+    return DefinedNodeRegistry;
+  }
+});
 Object.defineProperty(exports, 'ENGINE_EXECUTION_LIMITS_DEFAULTS', {
   enumerable: true,
   get: function () {
@@ -6491,6 +6654,30 @@ Object.defineProperty(exports, 'HintOnlyOffloadPolicy', {
     return HintOnlyOffloadPolicy;
   }
 });
+Object.defineProperty(exports, 'HitlResumeTokenSignerToken', {
+  enumerable: true,
+  get: function () {
+    return HitlResumeTokenSignerToken;
+  }
+});
+Object.defineProperty(exports, 'HitlTimeoutJobSchedulerToken', {
+  enumerable: true,
+  get: function () {
+    return HitlTimeoutJobSchedulerToken;
+  }
+});
+Object.defineProperty(exports, 'HitlWorkspaceIdToken', {
+  enumerable: true,
+  get: function () {
+    return HitlWorkspaceIdToken;
+  }
+});
+Object.defineProperty(exports, 'HumanTaskStoreToken', {
+  enumerable: true,
+  get: function () {
+    return HumanTaskStoreToken;
+  }
+});
 Object.defineProperty(exports, 'InMemoryBinaryStorage', {
   enumerable: true,
   get: function () {
@@ -6551,12 +6738,6 @@ Object.defineProperty(exports, 'MissingRuntimeTriggerToken', {
     return MissingRuntimeTriggerToken;
   }
 });
-Object.defineProperty(exports, 'NoOpAgentMcpIntegration', {
-  enumerable: true,
-  get: function () {
-    return NoOpAgentMcpIntegration;
-  }
-});
 Object.defineProperty(exports, 'NoOpCostTrackingTelemetry', {
   enumerable: true,
   get: function () {
@@ -6611,12 +6792,6 @@ Object.defineProperty(exports, 'NoRetryPolicy', {
     return NoRetryPolicy;
   }
 });
-Object.defineProperty(exports, 'NodeBackedToolConfig', {
-  enumerable: true,
-  get: function () {
-    return NodeBackedToolConfig;
-  }
-});
 Object.defineProperty(exports, 'NodeEventPublisher', {
   enumerable: true,
   get: function () {
@@ -6653,12 +6828,6 @@ Object.defineProperty(exports, 'NodeInstanceFactoryFactory', {
     return NodeInstanceFactoryFactory;
   }
 });
-Object.defineProperty(exports, 'NodeIterationIdFactory', {
-  enumerable: true,
-  get: function () {
-    return NodeIterationIdFactory;
-  }
-});
 Object.defineProperty(exports, 'NodeOutputNormalizer', {
   enumerable: true,
   get: function () {
@@ -6701,12 +6870,6 @@ Object.defineProperty(exports, 'RetryPolicy', {
     return RetryPolicy;
   }
 });
-Object.defineProperty(exports, 'RunFinishedAtFactory', {
-  enumerable: true,
-  get: function () {
-    return RunFinishedAtFactory;
-  }
-});
 Object.defineProperty(exports, 'RunIntentService', {
   enumerable: true,
   get: function () {
@@ -6725,6 +6888,12 @@ Object.defineProperty(exports, 'RunPolicySnapshotFactory', {
     return RunPolicySnapshotFactory;
   }
 });
+Object.defineProperty(exports, 'RunSuspendedError', {
+  enumerable: true,
+  get: function () {
+    return RunSuspendedError;
+  }
+});
 Object.defineProperty(exports, 'RunTerminalPersistenceCoordinator', {
   enumerable: true,
   get: function () {
@@ -6815,22 +6984,28 @@ Object.defineProperty(exports, 'WorkflowStoragePolicyEvaluator', {
     return WorkflowStoragePolicyEvaluator;
   }
 });
-Object.defineProperty(exports, '__toESM', {
+Object.defineProperty(exports, 'chatModel', {
   enumerable: true,
   get: function () {
-    return __toESM;
+    return chatModel;
   }
 });
-Object.defineProperty(exports, 'branchRef', {
+Object.defineProperty(exports, 'defineBatchNode', {
   enumerable: true,
   get: function () {
-    return branchRef;
+    return defineBatchNode;
   }
 });
-Object.defineProperty(exports, 'chatModel', {
+Object.defineProperty(exports, 'defineHumanApprovalNode', {
   enumerable: true,
   get: function () {
-    return chatModel;
+    return defineHumanApprovalNode;
+  }
+});
+Object.defineProperty(exports, 'defineNode', {
+  enumerable: true,
+  get: function () {
+    return defineNode;
   }
 });
 Object.defineProperty(exports, 'emitPorts', {
@@ -6851,10 +7026,10 @@ Object.defineProperty(exports, 'getPersistedRuntimeTypeMetadata', {
     return getPersistedRuntimeTypeMetadata;
   }
 });
-Object.defineProperty(exports, 'isItemExpr', {
+Object.defineProperty(exports, 'isHumanApprovalNode', {
   enumerable: true,
   get: function () {
-    return isItemExpr;
+    return isHumanApprovalNode;
   }
 });
 Object.defineProperty(exports, 'isPortsEmission', {
@@ -6869,40 +7044,16 @@ Object.defineProperty(exports, 'isUnbrandedPortsEmissionShape', {
     return isUnbrandedPortsEmissionShape;
   }
 });
-Object.defineProperty(exports, 'itemExpr', {
-  enumerable: true,
-  get: function () {
-    return itemExpr;
-  }
-});
 Object.defineProperty(exports, 'node', {
   enumerable: true,
   get: function () {
     return node;
   }
 });
-Object.defineProperty(exports, 'nodeRef', {
-  enumerable: true,
-  get: function () {
-    return nodeRef;
-  }
-});
-Object.defineProperty(exports, 'resolveItemExprsForExecution', {
-  enumerable: true,
-  get: function () {
-    return resolveItemExprsForExecution;
-  }
-});
-Object.defineProperty(exports, 'resolveItemExprsInUnknown', {
-  enumerable: true,
-  get: function () {
-    return resolveItemExprsInUnknown;
-  }
-});
 Object.defineProperty(exports, 'tool', {
   enumerable: true,
   get: function () {
     return tool;
   }
 });
-//# sourceMappingURL=runtime-vH0EeZzH.cjs.map
+//# sourceMappingURL=runtime-CyW9c9XM.cjs.map