@invect/core 0.0.1

package/dist/services/flow-orchestration/node-execution-coordinator.js

@@ -0,0 +1,657 @@
+import { NodeExecutionStatus } from "../../types/base.js";
+import { BatchProvider } from "../ai/ai-types.js";
+import "../ai/base-client.js";
+import { GraphNodeType } from "../../types/graph-node-types.js";
+import "../../types-fresh.js";
+import { generateNodeSlug } from "../../utils/node-slug.js";
+import { detectProviderFromCredential } from "../../utils/provider-detection.js";
+import { createTemplateService } from "../templating/template.service.js";
+import { JsExpressionError } from "../templating/js-expression.service.js";
+import { getGlobalActionRegistry } from "../../actions/action-registry.js";
+import { executeActionAsNode } from "../../actions/action-executor.js";
+//#region src/services/flow-orchestration/node-execution-coordinator.ts
+/**
+* Coordinates the execution of individual nodes within a flow run.
+*/
+var NodeExecutionCoordinator = class {
+	templateService;
+	constructor(deps) {
+		this.deps = deps;
+		if (deps.templateService) this.templateService = deps.templateService;
+		else if (deps.jsExpressionService) this.templateService = createTemplateService(deps.jsExpressionService, deps.logger);
+		else this.templateService = createTemplateService(void 0, deps.logger);
+	}
+	/**
+	* Ensure a provider adapter is registered in BaseAIClient for the given
+	* provider. If the adapter doesn't exist yet, the credential is resolved
+	* and its API key is used to create one on-the-fly.
+	*/
+	async ensureAdapterRegistered(provider, credentialId) {
+		if (this.deps.baseAIClient.hasAdapter(provider)) return;
+		if (!credentialId) throw new Error(`No adapter registered for provider "${provider}" and no credentialId provided to create one.`);
+		const { credentialsService, logger } = this.deps;
+		if (!credentialsService) throw new Error("Credentials service not available — cannot resolve API key for adapter registration.");
+		const credential = await credentialsService.getDecryptedWithRefresh(credentialId);
+		const apiKey = credential.config?.apiKey;
+		if (!apiKey) throw new Error(`Credential "${credentialId}" does not contain an apiKey — cannot register adapter.`);
+		const detectedProvider = detectProviderFromCredential(credential) ?? provider;
+		const providerLabel = detectedProvider === BatchProvider.OPENAI ? "OPENAI" : detectedProvider === BatchProvider.ANTHROPIC ? "ANTHROPIC" : detectedProvider === BatchProvider.OPENROUTER ? "OPENROUTER" : detectedProvider;
+		logger.debug("Auto-registering adapter from credential", {
+			provider: providerLabel,
+			credentialId
+		});
+		this.deps.baseAIClient.registerAdapter(providerLabel, apiKey);
+	}
+	/**
+	* Build the node-keyed incoming data object for template resolution.
+	* This aggregates outputs from all source nodes connected to the target node.
+	*
+	* Structure:
+	* {
+	*   "source_node_slug": {
+	*     nodeId: "abc-123",
+	*     nodeType: GraphNodeType.TEMPLATE_STRING,
+	*     label: "Source Node",
+	*     slug: "source_node_slug",
+	*     output: "the value",        // flattened from data.variables.output.value
+	*     data: { variables: { ... } },
+	*     _rawOutput: { nodeType: ..., data: { ... } },
+	*     toString(): string          // returns primary output value for direct template use
+	*   },
+	*   ...
+	* }
+	*
+	* Input data structure matches the execution-process.md documentation:
+	* - Keys: upstream node reference_id (or slug from label), normalized to snake_case
+	* - Values: direct output value (the node's primary output, JSON-parsed if valid)
+	*
+	* Example: { "fetch_user": { "id": 123, "name": "Alice" }, "get_config": "production" }
+	*
+	* Template usage:
+	* - {{ fetch_user }} renders the full output object/value
+	* - {{ fetch_user.id }} accesses nested properties directly
+	*/
+	buildIncomingDataObject(node, nodeOutputs, edges, nodeMap) {
+		const incomingData = {};
+		const incomingEdges = edges.filter((edge) => edge.target === node.id);
+		for (const edge of incomingEdges) {
+			const sourceNode = nodeMap.get(edge.source);
+			const sourceOutput = nodeOutputs.get(edge.source);
+			if (!sourceNode) continue;
+			const nodeLabel = sourceNode.label ?? "";
+			const referenceId = sourceNode.referenceId ?? "";
+			const nodeId = sourceNode.id;
+			const nodeType = sourceNode.type;
+			const slug = referenceId || generateNodeSlug(nodeLabel || nodeType || nodeId, nodeId);
+			let outputValue = null;
+			const variables = sourceOutput?.data?.variables;
+			if (variables && typeof variables === "object") {
+				const outputVar = variables.output;
+				if (outputVar && typeof outputVar === "object" && "value" in outputVar) outputValue = outputVar.value;
+				else if (outputVar !== void 0) outputValue = outputVar;
+				else {
+					const firstKey = Object.keys(variables)[0];
+					if (firstKey) {
+						const firstVar = variables[firstKey];
+						if (firstVar && typeof firstVar === "object" && "value" in firstVar) outputValue = firstVar.value;
+						else outputValue = firstVar;
+					}
+				}
+			}
+			if (typeof outputValue === "string") try {
+				const parsed = JSON.parse(outputValue);
+				if (typeof parsed === "object" && parsed !== null) outputValue = parsed;
+			} catch {}
+			incomingData[slug] = outputValue;
+		}
+		this.deps.logger.debug("Built incoming data object", {
+			nodeId: node.id,
+			nodeType: node.type,
+			incomingNodeCount: Object.keys(incomingData).length,
+			incomingKeys: Object.keys(incomingData)
+		});
+		return incomingData;
+	}
+	/**
+	* Resolve {{ expression }} templates in node params using the incoming data context.
+	* Returns the params with all templatable string values resolved.
+	*
+	* @param params - Node parameters to resolve
+	* @param incomingData - Context data keyed by source node reference IDs
+	* @param skipKeys - Param keys to skip (their values should not be resolved as templates)
+	*/
+	resolveTemplateParams(params, incomingData, skipKeys = []) {
+		const resolved = {};
+		for (const [key, value] of Object.entries(params)) {
+			if (skipKeys.includes(key)) {
+				resolved[key] = value;
+				continue;
+			}
+			if (typeof value === "string" && this.templateService.isTemplate(value)) try {
+				const renderedValue = this.templateService.render(value, incomingData);
+				resolved[key] = renderedValue;
+				this.deps.logger.debug("Resolved template param", {
+					param: key,
+					template: value,
+					resolved: renderedValue
+				});
+			} catch (error) {
+				this.deps.logger.warn("Failed to resolve template param", {
+					param: key,
+					template: value,
+					error: error instanceof Error ? error.message : String(error)
+				});
+				resolved[key] = value;
+			}
+			else resolved[key] = value;
+		}
+		return resolved;
+	}
+	prepareNodeInputs(node, nodeOutputs, edges, nodeMap) {
+		const nodeInputs = {};
+		const missingInputs = [];
+		const handleValidationErrors = [];
+		const incomingEdges = edges.filter((edge) => edge.target === node.id);
+		for (const edge of incomingEdges) {
+			const sourceNodeOutput = nodeOutputs.get(edge.source);
+			const sourceNode = nodeMap?.get(edge.source);
+			if (sourceNode) {
+				const validation = this.validateEdgeHandles(edge, sourceNode, node);
+				if (!validation.isValid) handleValidationErrors.push(...validation.errors);
+			}
+			if (sourceNodeOutput) {
+				const targetInputKey = edge.targetHandle || "input";
+				const sourceOutputKey = edge.sourceHandle || "output";
+				const outputValue = this.getOutputValue(sourceNodeOutput, sourceOutputKey, sourceNode?.type, edge.source);
+				if (outputValue !== void 0) nodeInputs[targetInputKey] = outputValue;
+				else missingInputs.push(`${edge.source}:${sourceOutputKey} -> ${targetInputKey}`);
+			} else missingInputs.push(`${edge.source} (no output available) -> ${edge.targetHandle || "input"}`);
+		}
+		if (handleValidationErrors.length > 0) this.deps.logger.error("Edge handle validation errors detected", {
+			nodeId: node.id,
+			nodeType: node.type,
+			errors: handleValidationErrors
+		});
+		if (missingInputs.length > 0) this.deps.logger.warn("Node has missing inputs", {
+			nodeId: node.id,
+			nodeType: node.type,
+			missingInputs,
+			availableInputs: Object.keys(nodeInputs)
+		});
+		this.deps.logger.debug("Prepared node inputs", {
+			nodeId: node.id,
+			nodeType: node.type,
+			incomingEdgeCount: incomingEdges.length,
+			inputKeys: Object.keys(nodeInputs),
+			inputs: nodeInputs,
+			missingInputCount: missingInputs.length,
+			handleValidationErrorCount: handleValidationErrors.length
+		});
+		return nodeInputs;
+	}
+	async executeNode(flowRunId, node, inputs, flowInputs = {}, definition, skippedNodeIds, useBatchProcessing, incomingData) {
+		const { logger } = this.deps;
+		logger.debug("Executing node", {
+			flowRunId,
+			nodeId: node.id,
+			nodeType: node.type
+		});
+		const mapperConfig = node.mapper;
+		if (mapperConfig?.enabled && mapperConfig?.expression && this.deps.jsExpressionService) {
+			logger.debug("Node has mapper configuration, evaluating mapper expression", {
+				flowRunId,
+				nodeId: node.id,
+				mode: mapperConfig.mode
+			});
+			return this.executeNodeWithMapper(flowRunId, node, inputs, flowInputs, definition, skippedNodeIds, useBatchProcessing, incomingData ?? {}, mapperConfig);
+		}
+		return this.executeNodeOnce(flowRunId, node, inputs, flowInputs, definition, skippedNodeIds, useBatchProcessing, incomingData);
+	}
+	/**
+	* Execute a node once (standard execution without looping).
+	*/
+	async executeNodeOnce(flowRunId, node, inputs, flowInputs = {}, definition, skippedNodeIds, useBatchProcessing, incomingData) {
+		const { logger, nodeExecutionService, nodeRegistry, nodeDataService, graphService, credentialsService } = this.deps;
+		const safeInputs = inputs || {};
+		const executor = nodeRegistry.get(node.type);
+		const actionRegistry = getGlobalActionRegistry();
+		const action = !executor ? actionRegistry.get(node.type) : void 0;
+		if (!executor && !action) throw new Error(`No executor or action found for node type: ${node.type}`);
+		let defaultParams = {};
+		if (executor) defaultParams = executor.getDefinition().defaultParams ?? {};
+		else if (action) defaultParams = Object.fromEntries((action.params.fields ?? []).filter((f) => f.defaultValue !== void 0).map((f) => [f.name, f.defaultValue]));
+		const nodeParams = {
+			...defaultParams,
+			...node.params ?? {}
+		};
+		const skipTemplateResolutionKeys = [];
+		const nodeTypeStr = node.type;
+		if (nodeTypeStr === GraphNodeType.TEMPLATE_STRING || nodeTypeStr === "core.template_string") skipTemplateResolutionKeys.push("template");
+		const resolvedParams = incomingData ? this.resolveTemplateParams(nodeParams, incomingData, skipTemplateResolutionKeys) : nodeParams;
+		logger.debug("Resolved node params", {
+			nodeId: node.id,
+			nodeType: node.type,
+			defaultParamKeys: Object.keys(defaultParams),
+			nodeParamKeys: Object.keys(node.params ?? {}),
+			resolvedParamKeys: Object.keys(resolvedParams),
+			skippedKeys: skipTemplateResolutionKeys
+		});
+		({ ...node });
+		const traceInputs = incomingData && Object.keys(incomingData).length > 0 ? incomingData : safeInputs;
+		const trace = await nodeExecutionService.createNodeExecution(flowRunId, node.id, node.type, traceInputs);
+		try {
+			await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.RUNNING);
+			const executionContext = {
+				nodeId: node.id,
+				flowRunId,
+				logger,
+				globalConfig: {},
+				flowInputs,
+				functions: {
+					markDownstreamNodesAsSkipped: (nodeId, edges, skippedNodes, isFromIfElse) => {
+						logger.debug("Marking downstream nodes as skipped", {
+							nodeId,
+							edges: edges.length,
+							skippedNodes: Array.from(skippedNodes),
+							isFromIfElse
+						});
+						graphService.markDownstreamNodesAsSkipped(nodeId, edges, skippedNodes, isFromIfElse);
+					},
+					runTemplateReplacement: (template, variables) => {
+						return nodeDataService.runTemplateReplacement(template, variables);
+					},
+					getCredential: async (credentialId) => {
+						if (!credentialsService) {
+							logger.warn("Credentials service not available", { credentialId });
+							return null;
+						}
+						try {
+							return await credentialsService.getDecryptedWithRefresh(credentialId);
+						} catch (error) {
+							logger.error("Failed to retrieve credential", {
+								credentialId,
+								error: error instanceof Error ? error.message : String(error)
+							});
+							return null;
+						}
+					},
+					submitPrompt: async (request) => {
+						logger.debug("Submitting model prompt", {
+							model: request.model,
+							provider: request.provider,
+							useBatchProcessing: request.useBatchProcessing
+						});
+						await this.ensureAdapterRegistered(request.provider, request.credentialId);
+						return this.deps.baseAIClient.executePrompt(request);
+					},
+					submitAgentPrompt: async (request) => {
+						logger.debug("Submitting agent prompt", {
+							model: request.model,
+							toolCount: request.tools.length,
+							messageCount: request.messages.length
+						});
+						await this.ensureAdapterRegistered(request.provider, request.credentialId);
+						return this.deps.baseAIClient.runAgentPrompt(request, request.provider);
+					},
+					recordToolExecution: async (input) => {
+						const { agentToolExecutionService } = this.deps;
+						if (!agentToolExecutionService) {
+							logger.warn("Agent tool execution service not available");
+							return null;
+						}
+						try {
+							return { id: (await agentToolExecutionService.recordToolExecution(input)).id };
+						} catch (error) {
+							logger.error("Failed to record tool execution", {
+								toolId: input.toolId,
+								error: error instanceof Error ? error.message : String(error)
+							});
+							return null;
+						}
+					}
+				},
+				nodes: definition?.nodes || [],
+				edges: definition?.edges || [],
+				nodeExecutionResults: /* @__PURE__ */ new Map(),
+				allNodeOutputs: /* @__PURE__ */ new Map(),
+				allNodeInputs: /* @__PURE__ */ new Map(),
+				skippedNodeIds: skippedNodeIds || /* @__PURE__ */ new Set(),
+				startedAt: /* @__PURE__ */ new Date(),
+				flowId: "",
+				flowVersion: 1,
+				flowParams: { useBatchProcessing: useBatchProcessing ?? true },
+				incomingData: incomingData || {}
+			};
+			let hookResolvedParams = resolvedParams;
+			if (this.deps.pluginHookRunner) try {
+				const beforeResult = await this.deps.pluginHookRunner.runBeforeNodeExecute({
+					flowRun: {
+						flowId: executionContext.flowId || "",
+						flowRunId,
+						flowVersion: executionContext.flowVersion || 1,
+						inputs: flowInputs
+					},
+					nodeId: node.id,
+					nodeType: node.type,
+					nodeLabel: node.label,
+					inputs: traceInputs,
+					params: hookResolvedParams
+				});
+				if (beforeResult.skipped) {
+					logger.info("Node execution skipped by plugin hook", {
+						flowRunId,
+						nodeId: node.id
+					});
+					return await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.SKIPPED);
+				}
+				if (beforeResult.params) hookResolvedParams = beforeResult.params;
+			} catch (hookError) {
+				logger.warn("beforeNodeExecute plugin hook error (non-fatal)", {
+					nodeId: node.id,
+					error: hookError instanceof Error ? hookError.message : String(hookError)
+				});
+			}
+			const finalNodeWithParams = {
+				...node,
+				params: hookResolvedParams
+			};
+			let executionResult;
+			const dispatchStartTime = Date.now();
+			if (executor) {
+				const inputValidation = executor.validateInputs(inputs);
+				if (!inputValidation.isValid) throw new Error(`Input validation failed: ${inputValidation.error}`);
+				executionResult = await executor.execute(inputValidation.data, finalNodeWithParams, executionContext);
+			} else if (action) executionResult = await executeActionAsNode(action, hookResolvedParams, executionContext);
+			else throw new Error(`No executor or action found for node type: ${node.type}`);
+			const dispatchDuration = Date.now() - dispatchStartTime;
+			const rawOutput = executionResult.state === NodeExecutionStatus.SUCCESS ? executionResult.output : void 0;
+			let finalOutput = rawOutput;
+			if (this.deps.pluginHookRunner && executionResult.state !== NodeExecutionStatus.PENDING) try {
+				const afterResult = await this.deps.pluginHookRunner.runAfterNodeExecute({
+					flowRun: {
+						flowId: executionContext.flowId || "",
+						flowRunId,
+						flowVersion: executionContext.flowVersion || 1,
+						inputs: flowInputs
+					},
+					nodeId: node.id,
+					nodeType: node.type,
+					nodeLabel: node.label,
+					inputs: traceInputs,
+					params: hookResolvedParams,
+					status: executionResult.state === NodeExecutionStatus.FAILED ? "FAILED" : "SUCCESS",
+					output: rawOutput,
+					error: executionResult.state === NodeExecutionStatus.FAILED ? executionResult.errors.join(", ") : void 0,
+					duration: dispatchDuration
+				});
+				if (afterResult.output !== void 0) finalOutput = afterResult.output;
+			} catch (hookError) {
+				logger.warn("afterNodeExecute plugin hook error (non-fatal)", {
+					nodeId: node.id,
+					error: hookError instanceof Error ? hookError.message : String(hookError)
+				});
+			}
+			if (executionResult.state === NodeExecutionStatus.FAILED) {
+				const errorMessage = executionResult.errors.join(", ");
+				logger.error("Node execution failed", {
+					flowRunId,
+					nodeId: node.id,
+					error: errorMessage
+				});
+				return await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.FAILED, { error: errorMessage });
+			} else if (executionResult.state === NodeExecutionStatus.PENDING) {
+				logger.debug("Node submitted for batch processing", {
+					flowRunId,
+					nodeId: node.id,
+					batchJobId: executionResult.batchJobId
+				});
+				return await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.BATCH_SUBMITTED);
+			} else {
+				logger.debug("Node execution completed successfully", {
+					flowRunId,
+					nodeId: node.id,
+					outputKeys: Object.keys(finalOutput || {})
+				});
+				return await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.SUCCESS, { outputs: finalOutput });
+			}
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			logger.error("Node execution failed", {
+				flowRunId,
+				nodeId: node.id,
+				error: errorMessage
+			});
+			return await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.FAILED, { error: errorMessage });
+		}
+	}
+	/**
+	* Execute a node with a data mapper.
+	*
+	* 1. Evaluate the mapper JS expression against upstream data
+	* 2. If result is array + mode allows → iterate (execute once per item)
+	* 3. If result is object → single execution with mapped data as context
+	* 4. Primitives → single execution with { item: value } context
+	*/
+	async executeNodeWithMapper(flowRunId, node, inputs, flowInputs, definition, skippedNodeIds, useBatchProcessing, incomingData, mapperConfig) {
+		const { logger, nodeExecutionService } = this.deps;
+		const jsService = this.deps.jsExpressionService;
+		if (!jsService) throw new Error("JS expression service is required for mapper execution.");
+		let mappedResult;
+		try {
+			mappedResult = jsService.evaluate(mapperConfig.expression, incomingData);
+		} catch (e) {
+			const errorMessage = e instanceof JsExpressionError ? e.message : `Mapper expression error: ${String(e)}`;
+			logger.error("Mapper expression failed", {
+				flowRunId,
+				nodeId: node.id,
+				expression: mapperConfig.expression,
+				error: errorMessage
+			});
+			const trace = await nodeExecutionService.createNodeExecution(flowRunId, node.id, node.type, {
+				...incomingData,
+				_mapper: {
+					expression: mapperConfig.expression,
+					error: errorMessage
+				}
+			});
+			return await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.FAILED, { error: errorMessage });
+		}
+		const mode = mapperConfig.mode ?? "auto";
+		const isArray = Array.isArray(mappedResult);
+		if (mode === "iterate" && !isArray) {
+			const errorMessage = `Mapper mode is "iterate" but expression returned ${typeof mappedResult}, not an array`;
+			logger.error(errorMessage, {
+				flowRunId,
+				nodeId: node.id
+			});
+			const trace = await nodeExecutionService.createNodeExecution(flowRunId, node.id, node.type, {
+				...incomingData,
+				_mapper: {
+					expression: mapperConfig.expression,
+					error: errorMessage
+				}
+			});
+			return await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.FAILED, { error: errorMessage });
+		}
+		if (mode === "reshape" && isArray) mappedResult = { items: mappedResult };
+		if (mode === "iterate" || mode === "auto" && isArray) return this.executeNodeMapperIterating(flowRunId, node, inputs, flowInputs, definition, skippedNodeIds, useBatchProcessing, incomingData, mappedResult, mapperConfig);
+		let mappedData;
+		if (mappedResult !== null && typeof mappedResult === "object" && !isArray) mappedData = mappedResult;
+		else mappedData = { item: mappedResult };
+		return this.executeNodeOnce(flowRunId, node, inputs, flowInputs, definition, skippedNodeIds, useBatchProcessing, mappedData);
+	}
+	/**
+	* Execute a node repeatedly — once per item from the mapper array result.
+	* Handles concurrency, empty array behavior, and result packaging.
+	*/
+	async executeNodeMapperIterating(flowRunId, node, inputs, flowInputs, definition, skippedNodeIds, useBatchProcessing, incomingData, items, mapperConfig) {
+		const { logger, nodeExecutionService } = this.deps;
+		if (items.length === 0) {
+			const trace = await nodeExecutionService.createNodeExecution(flowRunId, node.id, node.type, {
+				...incomingData,
+				_mapper: {
+					expression: mapperConfig.expression,
+					itemCount: 0
+				}
+			});
+			if (mapperConfig.onEmpty === "error") return await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.FAILED, { error: "Mapper returned empty array and onEmpty is \"error\"" });
+			return await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.SUCCESS, { outputs: {
+				nodeType: node.type,
+				data: { variables: { output: {
+					value: [],
+					type: "object"
+				} } }
+			} });
+		}
+		const trace = await nodeExecutionService.createNodeExecution(flowRunId, node.id, node.type, {
+			...incomingData,
+			_mapper: {
+				expression: mapperConfig.expression,
+				itemCount: items.length
+			}
+		});
+		try {
+			await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.RUNNING);
+			const results = [];
+			const concurrency = mapperConfig.concurrency ?? 1;
+			let hasFailure = false;
+			let failureError;
+			if (concurrency === 1) for (let i = 0; i < items.length; i++) {
+				const itemContext = this.buildMapperItemContext(items[i], i, items.length, incomingData);
+				const result = await this.executeSingleMapperIteration(flowRunId, node, inputs, flowInputs, definition, skippedNodeIds, useBatchProcessing, itemContext);
+				results.push(result);
+			}
+			else for (let start = 0; start < items.length; start += concurrency) {
+				const batch = items.slice(start, start + concurrency);
+				const batchResults = await Promise.allSettled(batch.map((item, batchIdx) => {
+					const globalIdx = start + batchIdx;
+					const itemContext = this.buildMapperItemContext(item, globalIdx, items.length, incomingData);
+					return this.executeSingleMapperIteration(flowRunId, node, inputs, flowInputs, definition, skippedNodeIds, useBatchProcessing, itemContext);
+				}));
+				for (const r of batchResults) if (r.status === "fulfilled") results.push(r.value);
+				else {
+					hasFailure = true;
+					failureError = r.reason;
+				}
+				if (hasFailure) break;
+			}
+			if (hasFailure) {
+				const errorMessage = failureError instanceof Error ? failureError.message : String(failureError);
+				return await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.FAILED, { error: `Mapper iteration failed: ${errorMessage}` });
+			}
+			const packagedOutput = this.packageMapperResults(results, mapperConfig);
+			return await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.SUCCESS, { outputs: {
+				nodeType: node.type,
+				data: {
+					variables: { output: {
+						value: packagedOutput,
+						type: "object"
+					} },
+					metadata: {
+						mapper: true,
+						iterationCount: items.length,
+						outputMode: mapperConfig.outputMode ?? "array"
+					}
+				}
+			} });
+		} catch (error) {
+			const errorMessage = error instanceof Error ? error.message : String(error);
+			logger.error("Mapper iteration failed", {
+				flowRunId,
+				nodeId: node.id,
+				error: errorMessage
+			});
+			return await nodeExecutionService.updateNodeExecutionStatus(trace.id, NodeExecutionStatus.FAILED, { error: errorMessage });
+		}
+	}
+	/**
+	* Execute a single iteration within a mapper loop.
+	* Returns the output value from the node execution.
+	*/
+	async executeSingleMapperIteration(flowRunId, node, inputs, flowInputs, definition, skippedNodeIds, useBatchProcessing, itemContext) {
+		const outputs = (await this.executeNodeOnce(flowRunId, node, inputs, flowInputs, definition, skippedNodeIds, useBatchProcessing, itemContext)).outputs;
+		const outputVar = outputs?.data?.variables?.output;
+		if (outputVar && typeof outputVar === "object" && "value" in outputVar) return outputVar.value;
+		return outputs?.data ?? null;
+	}
+	/**
+	* Build the context object for a single iteration item.
+	*
+	* Layering (later wins on collision):
+	* 1. incomingData — all upstream outputs preserved
+	* 2. Item properties spread (if object) or { item: value } for primitives
+	* 3. _item metadata (index, total, first/last)
+	*/
+	buildMapperItemContext(item, index, total, incomingData) {
+		const context = { ...incomingData };
+		if (item !== null && typeof item === "object" && !Array.isArray(item)) Object.assign(context, item);
+		else context.item = item;
+		context._item = {
+			value: item,
+			index,
+			iteration: index + 1,
+			first: index === 0,
+			last: index === total - 1,
+			total
+		};
+		return context;
+	}
+	/**
+	* Package iteration results according to outputMode.
+	*/
+	packageMapperResults(results, config) {
+		switch (config.outputMode ?? "array") {
+			case "array": return results;
+			case "object": {
+				const keyField = config.keyField ?? "id";
+				const obj = {};
+				for (const r of results) if (r && typeof r === "object") {
+					const key = String(r[keyField] ?? "");
+					if (key) obj[key] = r;
+				}
+				return obj;
+			}
+			case "first": return results[0] ?? null;
+			case "last": return results[results.length - 1] ?? null;
+			case "concat": return results.map((r) => String(r ?? "")).join("");
+			default: return results;
+		}
+	}
+	validateEdgeHandles(_edge, _sourceNode, _targetNode) {
+		return {
+			isValid: true,
+			errors: []
+		};
+	}
+	getOutputValue(nodeOutput, outputKey, sourceNodeType, sourceNodeId) {
+		if (!nodeOutput?.data?.variables) {
+			this.deps.logger.debug("getOutputValue: Missing variables in nodeOutput", {
+				outputKey,
+				sourceNodeType,
+				sourceNodeId
+			});
+			return;
+		}
+		const { variables } = nodeOutput.data;
+		if (outputKey in variables) {
+			const variable = variables[outputKey];
+			this.deps.logger.debug("getOutputValue: Found variable", {
+				outputKey,
+				valueType: typeof variable.value,
+				sourceNodeType,
+				sourceNodeId
+			});
+			return variable.value;
+		}
+		this.deps.logger.warn("getOutputValue: Variable not found", {
+			outputKey,
+			sourceNodeType,
+			sourceNodeId,
+			availableVariables: Object.keys(variables)
+		});
+	}
+};
+//#endregion
+export { NodeExecutionCoordinator };
+
+//# sourceMappingURL=node-execution-coordinator.js.map