@codemation/core-nodes 0.4.0 → 0.4.2

package/dist/index.cjs

@@ -101,11 +101,14 @@ OpenAIStructuredOutputMethodFactory = _OpenAIStructuredOutputMethodFactory = __d
 var OpenAIChatModelConfig = class {
 	type = OpenAIChatModelFactory;
 	presentation;
+	provider = "openai";
+	modelName;
 	constructor(name, model, credentialSlotKey = "openai", presentationIn, options) {
 		this.name = name;
 		this.model = model;
 		this.credentialSlotKey = credentialSlotKey;
 		this.options = options;
+		this.modelName = model;
 		this.presentation = presentationIn ?? {
 			icon: "builtin:openai",
 			label: name
@@ -2222,7 +2225,7 @@ function __decorateParam(paramIndex, decorator) {
 
 //#endregion
 //#region src/nodes/AgentStructuredOutputRepairPromptFactory.ts
-var _ref$3, _AgentStructuredOutputRepairPromptFactory;
+var _ref$4, _AgentStructuredOutputRepairPromptFactory;
 let AgentStructuredOutputRepairPromptFactory = class AgentStructuredOutputRepairPromptFactory$1 {
 	static {
 		_AgentStructuredOutputRepairPromptFactory = this;
@@ -2257,7 +2260,7 @@ let AgentStructuredOutputRepairPromptFactory = class AgentStructuredOutputRepair
 AgentStructuredOutputRepairPromptFactory = _AgentStructuredOutputRepairPromptFactory = __decorate([
 	(0, __codemation_core.injectable)(),
 	__decorateParam(0, (0, __codemation_core.inject)(AIAgentExecutionHelpersFactory)),
-	__decorateMetadata("design:paramtypes", [typeof (_ref$3 = typeof AIAgentExecutionHelpersFactory !== "undefined" && AIAgentExecutionHelpersFactory) === "function" ? _ref$3 : Object])
+	__decorateMetadata("design:paramtypes", [typeof (_ref$4 = typeof AIAgentExecutionHelpersFactory !== "undefined" && AIAgentExecutionHelpersFactory) === "function" ? _ref$4 : Object])
 ], AgentStructuredOutputRepairPromptFactory);
 
 //#endregion
@@ -2592,7 +2595,7 @@ const meta = meta$1;
 
 //#endregion
 //#region src/nodes/AgentStructuredOutputRunner.ts
-var _ref$2, _ref2$2, _AgentStructuredOutputRunner;
+var _ref$3, _ref2$3, _AgentStructuredOutputRunner;
 let AgentStructuredOutputRunner = class AgentStructuredOutputRunner$1 {
 	static {
 		_AgentStructuredOutputRunner = this;
@@ -2705,7 +2708,7 @@ AgentStructuredOutputRunner = _AgentStructuredOutputRunner = __decorate([
 	(0, __codemation_core.injectable)(),
 	__decorateParam(0, (0, __codemation_core.inject)(AgentStructuredOutputRepairPromptFactory)),
 	__decorateParam(1, (0, __codemation_core.inject)(OpenAIStructuredOutputMethodFactory)),
-	__decorateMetadata("design:paramtypes", [typeof (_ref$2 = typeof AgentStructuredOutputRepairPromptFactory !== "undefined" && AgentStructuredOutputRepairPromptFactory) === "function" ? _ref$2 : Object, typeof (_ref2$2 = typeof OpenAIStructuredOutputMethodFactory !== "undefined" && OpenAIStructuredOutputMethodFactory) === "function" ? _ref2$2 : Object])
+	__decorateMetadata("design:paramtypes", [typeof (_ref$3 = typeof AgentStructuredOutputRepairPromptFactory !== "undefined" && AgentStructuredOutputRepairPromptFactory) === "function" ? _ref$3 : Object, typeof (_ref2$3 = typeof OpenAIStructuredOutputMethodFactory !== "undefined" && OpenAIStructuredOutputMethodFactory) === "function" ? _ref2$3 : Object])
 ], AgentStructuredOutputRunner);
 
 //#endregion
@@ -2716,6 +2719,390 @@ var AgentToolCallPortMap = class {
 	}
 };
 
+//#endregion
+//#region src/nodes/AgentToolErrorClassifier.ts
+let AgentToolErrorClassifier = class AgentToolErrorClassifier$1 {
+	classify(args) {
+		const effectiveError = this.toError(args.error);
+		if (this.isRepairableValidationError(args.error, effectiveError)) return {
+			kind: "repairable_validation_error",
+			effectiveError,
+			issues: this.extractIssues(args.error, effectiveError, args.toolName),
+			requiredSchemaReminder: this.toJsonValue(args.schema)
+		};
+		if (this.isTransientExecutionError(effectiveError)) return {
+			kind: "transient_execution_error",
+			effectiveError
+		};
+		return {
+			kind: "non_repairable_error",
+			effectiveError
+		};
+	}
+	isRepairableValidationError(rawError, effectiveError) {
+		if (rawError instanceof ZodError) return rawError.codemationToolValidationStage !== "output";
+		if (effectiveError.name === "ZodError") return true;
+		return effectiveError.message.includes("Received tool input did not match expected schema");
+	}
+	extractIssues(rawError, effectiveError, toolName) {
+		if (rawError instanceof ZodError) return rawError.issues.map((issue$1) => ({
+			path: issue$1.path.map((segment) => typeof segment === "number" ? segment : String(segment)),
+			code: issue$1.code,
+			message: issue$1.message,
+			expected: this.toOptionalString("expected" in issue$1 ? issue$1.expected : void 0),
+			received: this.toOptionalString("received" in issue$1 ? issue$1.received : void 0)
+		}));
+		if (effectiveError.name !== "ZodError") return;
+		return [{
+			path: [],
+			code: "invalid_tool_input",
+			message: `Tool "${toolName}" input was invalid: ${effectiveError.message}`
+		}];
+	}
+	isTransientExecutionError(error) {
+		const summary = `${error.name} ${error.message}`.toLowerCase();
+		return summary.includes("timeout") || summary.includes("timed out") || summary.includes("rate limit") || summary.includes("too many requests") || summary.includes("temporarily unavailable") || summary.includes("econnreset") || summary.includes("etimedout") || summary.includes("503");
+	}
+	toError(error) {
+		return error instanceof Error ? error : new Error(String(error));
+	}
+	toJsonValue(value) {
+		if (value === void 0) return;
+		return JSON.parse(JSON.stringify(value));
+	}
+	toOptionalString(value) {
+		if (value === void 0) return;
+		return String(value);
+	}
+};
+AgentToolErrorClassifier = __decorate([(0, __codemation_core.injectable)()], AgentToolErrorClassifier);
+
+//#endregion
+//#region src/nodes/AgentToolRepairExhaustedError.ts
+var AgentToolRepairExhaustedError = class extends Error {
+	details;
+	constructor(args) {
+		super(`AIAgent "${args.agentName}" (${args.nodeId}) could not recover from invalid tool calls for "${args.toolName}" after ${args.maxAttempts} repair attempt(s).`);
+		this.name = "AgentToolRepairExhaustedError";
+		const details = {
+			toolName: args.toolName,
+			maxAttempts: args.maxAttempts,
+			recommendation: "Check tool schema, tool description, or inject known values in code instead of asking the model to infer them."
+		};
+		if (args.lastManagedInput !== void 0) details["lastManagedInput"] = args.lastManagedInput;
+		if (args.lastValidationIssues && args.lastValidationIssues.length > 0) details["lastValidationIssues"] = args.lastValidationIssues.map((issue$1) => this.serializeIssue(issue$1));
+		this.details = details;
+	}
+	serializeIssue(issue$1) {
+		const result = {
+			path: [...issue$1.path],
+			code: issue$1.code,
+			message: issue$1.message
+		};
+		if (issue$1.expected !== void 0) result["expected"] = issue$1.expected;
+		if (issue$1.received !== void 0) result["received"] = issue$1.received;
+		return result;
+	}
+};
+
+//#endregion
+//#region src/nodes/AgentToolRepairPolicy.ts
+var _AgentToolRepairPolicy;
+let AgentToolRepairPolicy = class AgentToolRepairPolicy$1 {
+	static {
+		_AgentToolRepairPolicy = this;
+	}
+	static maxRepairAttemptsPerTool = 2;
+	createDecision(toolName, attemptsByToolName) {
+		const attempt = (attemptsByToolName.get(toolName) ?? 0) + 1;
+		attemptsByToolName.set(toolName, attempt);
+		return {
+			attempt,
+			maxAttempts: _AgentToolRepairPolicy.maxRepairAttemptsPerTool,
+			nextAction: attempt < _AgentToolRepairPolicy.maxRepairAttemptsPerTool ? "model_retry_with_tool_error_message" : "fail_agent_run"
+		};
+	}
+};
+AgentToolRepairPolicy = _AgentToolRepairPolicy = __decorate([(0, __codemation_core.injectable)()], AgentToolRepairPolicy);
+
+//#endregion
+//#region src/nodes/AgentToolExecutionCoordinator.ts
+var _ref$2, _ref2$2;
+let AgentToolExecutionCoordinator = class AgentToolExecutionCoordinator$1 {
+	constructor(errorClassifier, repairPolicy) {
+		this.errorClassifier = errorClassifier;
+		this.repairPolicy = repairPolicy;
+	}
+	async execute(args) {
+		const results = await Promise.allSettled(args.plannedToolCalls.map(async (plannedToolCall) => await this.executePlannedToolCall({
+			...args,
+			plannedToolCall
+		})));
+		const rejected = results.find((result) => result.status === "rejected");
+		if (rejected?.status === "rejected") throw rejected.reason instanceof Error ? rejected.reason : new Error(String(rejected.reason));
+		return results.filter((result) => result.status === "fulfilled").map((result) => result.value);
+	}
+	async executePlannedToolCall(args) {
+		const { plannedToolCall, ctx } = args;
+		const toolCallInputsByPort = AgentToolCallPortMap.fromInput(plannedToolCall.toolCall.input ?? {});
+		const invocationId = __codemation_core.ConnectionInvocationIdFactory.create();
+		const startedAt = /* @__PURE__ */ new Date();
+		const span = ctx.telemetry.startChildSpan({
+			name: "agent.tool.call",
+			kind: "client",
+			startedAt,
+			attributes: {
+				[__codemation_core.CodemationTelemetryAttributeNames.connectionInvocationId]: invocationId,
+				[__codemation_core.CodemationTelemetryAttributeNames.toolName]: plannedToolCall.binding.config.name
+			}
+		});
+		await ctx.nodeState?.markRunning({
+			nodeId: plannedToolCall.nodeId,
+			activationId: ctx.activationId,
+			inputsByPort: toolCallInputsByPort
+		});
+		try {
+			const serialized = await plannedToolCall.binding.langChainTool.invoke(plannedToolCall.toolCall.input ?? {});
+			const result = this.parseToolOutput(serialized);
+			const finishedAt = /* @__PURE__ */ new Date();
+			await ctx.nodeState?.markCompleted({
+				nodeId: plannedToolCall.nodeId,
+				activationId: ctx.activationId,
+				inputsByPort: toolCallInputsByPort,
+				outputs: AgentOutputFactory.fromUnknown(result)
+			});
+			await span.attachArtifact({
+				kind: "tool.input",
+				contentType: "application/json",
+				previewJson: this.toJsonValue(plannedToolCall.toolCall.input)
+			});
+			await span.attachArtifact({
+				kind: "tool.output",
+				contentType: "application/json",
+				previewJson: this.toJsonValue(result)
+			});
+			await span.end({
+				status: "ok",
+				endedAt: finishedAt
+			});
+			await ctx.nodeState?.appendConnectionInvocation({
+				invocationId,
+				connectionNodeId: plannedToolCall.nodeId,
+				parentAgentNodeId: ctx.nodeId,
+				parentAgentActivationId: ctx.activationId,
+				status: "completed",
+				managedInput: this.toJsonValue(plannedToolCall.toolCall.input),
+				managedOutput: this.toJsonValue(result),
+				queuedAt: startedAt.toISOString(),
+				startedAt: startedAt.toISOString(),
+				finishedAt: finishedAt.toISOString()
+			});
+			return {
+				toolName: plannedToolCall.binding.config.name,
+				toolCallId: plannedToolCall.toolCall.id ?? plannedToolCall.binding.config.name,
+				serialized: typeof serialized === "string" ? serialized : JSON.stringify(serialized),
+				result
+			};
+		} catch (error) {
+			const classification = this.errorClassifier.classify({
+				error,
+				toolName: plannedToolCall.binding.config.name,
+				schema: plannedToolCall.binding.langChainTool.schema
+			});
+			if (classification.kind !== "repairable_validation_error") {
+				const effectiveError = classification.effectiveError;
+				await this.recordFailedInvocation({
+					invocationId,
+					plannedToolCall,
+					ctx,
+					startedAt,
+					inputsByPort: toolCallInputsByPort,
+					managedInput: this.toJsonValue(plannedToolCall.toolCall.input),
+					error: effectiveError
+				});
+				await span.attachArtifact({
+					kind: "tool.input",
+					contentType: "application/json",
+					previewJson: this.toJsonValue(plannedToolCall.toolCall.input)
+				});
+				await span.end({
+					status: "error",
+					statusMessage: effectiveError.message,
+					endedAt: /* @__PURE__ */ new Date()
+				});
+				throw effectiveError;
+			}
+			const repairDecision = this.repairPolicy.createDecision(plannedToolCall.binding.config.name, args.repairAttemptsByToolName);
+			if (repairDecision.nextAction === "fail_agent_run") {
+				const exhaustedError = new AgentToolRepairExhaustedError({
+					agentName: args.agentName,
+					nodeId: ctx.nodeId,
+					toolName: plannedToolCall.binding.config.name,
+					maxAttempts: repairDecision.maxAttempts,
+					lastManagedInput: this.toJsonValue(plannedToolCall.toolCall.input),
+					lastValidationIssues: classification.issues
+				});
+				await this.recordFailedInvocation({
+					invocationId,
+					plannedToolCall,
+					ctx,
+					startedAt,
+					inputsByPort: toolCallInputsByPort,
+					managedInput: this.toJsonValue(plannedToolCall.toolCall.input),
+					error: exhaustedError,
+					errorDetails: exhaustedError.details
+				});
+				await span.attachArtifact({
+					kind: "tool.input",
+					contentType: "application/json",
+					previewJson: this.toJsonValue(plannedToolCall.toolCall.input)
+				});
+				await span.attachArtifact({
+					kind: "tool.error",
+					contentType: "application/json",
+					previewJson: exhaustedError.details
+				});
+				await span.end({
+					status: "error",
+					statusMessage: exhaustedError.message,
+					endedAt: /* @__PURE__ */ new Date()
+				});
+				throw exhaustedError;
+			}
+			const repairPayload = this.createRepairPayload({
+				toolName: plannedToolCall.binding.config.name,
+				issues: classification.issues,
+				requiredSchemaReminder: classification.requiredSchemaReminder
+			});
+			const repairDetails = this.createRepairDetails({
+				toolName: plannedToolCall.binding.config.name,
+				issues: classification.issues,
+				requiredSchemaReminder: classification.requiredSchemaReminder,
+				repairDecision
+			});
+			await this.recordFailedInvocation({
+				invocationId,
+				plannedToolCall,
+				ctx,
+				startedAt,
+				inputsByPort: toolCallInputsByPort,
+				managedInput: this.toJsonValue(plannedToolCall.toolCall.input),
+				error: classification.effectiveError,
+				errorDetails: repairDetails
+			});
+			await span.attachArtifact({
+				kind: "tool.input",
+				contentType: "application/json",
+				previewJson: this.toJsonValue(plannedToolCall.toolCall.input)
+			});
+			await span.attachArtifact({
+				kind: "tool.error",
+				contentType: "application/json",
+				previewJson: repairPayload
+			});
+			await span.end({
+				status: "error",
+				statusMessage: classification.effectiveError.message,
+				endedAt: /* @__PURE__ */ new Date()
+			});
+			return {
+				toolName: plannedToolCall.binding.config.name,
+				toolCallId: plannedToolCall.toolCall.id ?? plannedToolCall.binding.config.name,
+				serialized: JSON.stringify(repairPayload),
+				result: repairPayload
+			};
+		}
+	}
+	async recordFailedInvocation(args) {
+		const finishedAt = /* @__PURE__ */ new Date();
+		await args.ctx.nodeState?.markFailed({
+			nodeId: args.plannedToolCall.nodeId,
+			activationId: args.ctx.activationId,
+			inputsByPort: args.inputsByPort,
+			error: args.error
+		});
+		await args.ctx.nodeState?.appendConnectionInvocation({
+			invocationId: args.invocationId,
+			connectionNodeId: args.plannedToolCall.nodeId,
+			parentAgentNodeId: args.ctx.nodeId,
+			parentAgentActivationId: args.ctx.activationId,
+			status: "failed",
+			managedInput: args.managedInput,
+			error: {
+				message: args.error.message,
+				name: args.error.name,
+				stack: args.error.stack,
+				details: args.errorDetails ?? this.extractErrorDetails(args.error)
+			},
+			queuedAt: args.startedAt.toISOString(),
+			startedAt: args.startedAt.toISOString(),
+			finishedAt: finishedAt.toISOString()
+		});
+	}
+	createRepairPayload(args) {
+		const payload = {
+			status: "error",
+			errorType: "validation",
+			toolName: args.toolName,
+			message: this.createValidationMessage(args.toolName, args.issues),
+			instruction: "Call the tool again with all required fields present and correctly typed."
+		};
+		if (args.requiredSchemaReminder !== void 0) payload["requiredSchemaReminder"] = args.requiredSchemaReminder;
+		return payload;
+	}
+	createRepairDetails(args) {
+		const details = {
+			errorType: "validation",
+			toolName: args.toolName,
+			recoveryHint: "Call the same tool again with every required field present and correctly typed.",
+			repair: {
+				attempt: args.repairDecision.attempt,
+				maxAttempts: args.repairDecision.maxAttempts,
+				nextAction: args.repairDecision.nextAction
+			}
+		};
+		if (args.issues && args.issues.length > 0) details["issues"] = args.issues.map((issue$1) => this.serializeIssue(issue$1));
+		if (args.requiredSchemaReminder !== void 0) details["requiredSchemaReminder"] = args.requiredSchemaReminder;
+		return details;
+	}
+	createValidationMessage(toolName, issues) {
+		const firstIssue = issues?.[0];
+		if (!firstIssue) return `Your previous tool call for "${toolName}" was invalid and did not match the expected schema.`;
+		return `Your previous tool call for "${toolName}" was invalid because field "${firstIssue.path.length > 0 ? firstIssue.path.join(".") : "<root>"}" failed validation: ${firstIssue.message}`;
+	}
+	parseToolOutput(serialized) {
+		if (typeof serialized !== "string") return serialized;
+		try {
+			return JSON.parse(serialized);
+		} catch {
+			return serialized;
+		}
+	}
+	toJsonValue(value) {
+		if (value === void 0) return;
+		return JSON.parse(JSON.stringify(value));
+	}
+	extractErrorDetails(error) {
+		return error.details;
+	}
+	serializeIssue(issue$1) {
+		const result = {
+			path: [...issue$1.path],
+			code: issue$1.code,
+			message: issue$1.message
+		};
+		if (issue$1.expected !== void 0) result["expected"] = issue$1.expected;
+		if (issue$1.received !== void 0) result["received"] = issue$1.received;
+		return result;
+	}
+};
+AgentToolExecutionCoordinator = __decorate([
+	(0, __codemation_core.injectable)(),
+	__decorateParam(0, (0, __codemation_core.inject)(AgentToolErrorClassifier)),
+	__decorateParam(1, (0, __codemation_core.inject)(AgentToolRepairPolicy)),
+	__decorateMetadata("design:paramtypes", [typeof (_ref$2 = typeof AgentToolErrorClassifier !== "undefined" && AgentToolErrorClassifier) === "function" ? _ref$2 : Object, typeof (_ref2$2 = typeof AgentToolRepairPolicy !== "undefined" && AgentToolRepairPolicy) === "function" ? _ref2$2 : Object])
+], AgentToolExecutionCoordinator);
+
 //#endregion
 //#region src/nodes/NodeBackedToolRuntime.ts
 var _ref$1, _ref2$1, _ref3$1;
@@ -2806,7 +3193,7 @@ var AgentItemPortMap = class {
 
 //#endregion
 //#region src/nodes/AIAgentNode.ts
-var _ref, _ref2, _ref3;
+var _ref, _ref2, _ref3, _ref4;
 let AIAgentNode = class AIAgentNode$1 {
 	kind = "node";
 	outputPorts = ["main"];
@@ -2819,11 +3206,12 @@ let AIAgentNode = class AIAgentNode$1 {
 	connectionCredentialExecutionContextFactory;
 	/** One resolved model/tools bundle per activation context (same ctx across items in a batch). */
 	preparedByExecutionContext = /* @__PURE__ */ new WeakMap();
-	constructor(nodeResolver, credentialSessions, nodeBackedToolRuntime, executionHelpers, structuredOutputRunner) {
+	constructor(nodeResolver, credentialSessions, nodeBackedToolRuntime, executionHelpers, structuredOutputRunner, toolExecutionCoordinator) {
 		this.nodeResolver = nodeResolver;
 		this.nodeBackedToolRuntime = nodeBackedToolRuntime;
 		this.executionHelpers = executionHelpers;
 		this.structuredOutputRunner = structuredOutputRunner;
+		this.toolExecutionCoordinator = toolExecutionCoordinator;
 		this.connectionCredentialExecutionContextFactory = this.executionHelpers.createConnectionCredentialExecutionContextFactory(credentialSessions);
 	}
 	async execute(args) {
@@ -2886,17 +3274,33 @@ let AIAgentNode = class AIAgentNode$1 {
 				invokeTextModel: async (messages) => await this.invokeModel(prepared.model, prepared.languageModelConnectionNodeId, messages, ctx, itemInputsByPort, prepared.guardrails.modelInvocationOptions),
 				invokeStructuredModel: async (structuredModel, messages) => await this.invokeStructuredModel(structuredModel, prepared.languageModelConnectionNodeId, messages, ctx, itemInputsByPort, prepared.guardrails.modelInvocationOptions)
 			});
+			await ctx.telemetry.recordMetric({
+				name: __codemation_core.CodemationTelemetryMetricNames.agentTurns,
+				value: 1
+			});
+			await ctx.telemetry.recordMetric({
+				name: __codemation_core.CodemationTelemetryMetricNames.agentToolCalls,
+				value: 0
+			});
 			return this.buildOutputItem(item, structuredOutput);
 		}
 		const modelWithTools = this.bindToolsToModel(prepared.model, itemScopedTools);
-		const finalResponse = await this.runTurnLoopUntilFinalAnswer({
+		const loopResult = await this.runTurnLoopUntilFinalAnswer({
 			prepared,
 			itemInputsByPort,
 			itemScopedTools,
 			conversation,
 			modelWithTools
 		});
-		const outputJson = await this.resolveFinalOutputJson(prepared, itemInputsByPort, conversation, finalResponse, itemScopedTools.length > 0);
+		await ctx.telemetry.recordMetric({
+			name: __codemation_core.CodemationTelemetryMetricNames.agentTurns,
+			value: loopResult.turnCount
+		});
+		await ctx.telemetry.recordMetric({
+			name: __codemation_core.CodemationTelemetryMetricNames.agentToolCalls,
+			value: loopResult.toolCallCount
+		});
+		const outputJson = await this.resolveFinalOutputJson(prepared, itemInputsByPort, conversation, loopResult.finalResponse, itemScopedTools.length > 0);
 		return this.buildOutputItem(item, outputJson);
 	}
 	/**
@@ -2906,7 +3310,11 @@ let AIAgentNode = class AIAgentNode$1 {
 		const { prepared, itemInputsByPort, itemScopedTools, conversation, modelWithTools } = args;
 		const { ctx, guardrails, languageModelConnectionNodeId } = prepared;
 		let finalResponse;
+		let toolCallCount = 0;
+		let turnCount = 0;
+		const repairAttemptsByToolName = /* @__PURE__ */ new Map();
 		for (let turn = 1; turn <= guardrails.maxTurns; turn++) {
+			turnCount = turn;
 			const response = await this.invokeModel(modelWithTools, languageModelConnectionNodeId, conversation, ctx, itemInputsByPort, guardrails.modelInvocationOptions);
 			finalResponse = response;
 			const toolCalls = AgentMessageFactory.extractToolCalls(response);
@@ -2916,12 +3324,22 @@ let AIAgentNode = class AIAgentNode$1 {
 				break;
 			}
 			const plannedToolCalls = this.planToolCalls(itemScopedTools, toolCalls, ctx.nodeId);
+			toolCallCount += plannedToolCalls.length;
 			await this.markQueuedTools(plannedToolCalls, ctx);
-			const executedToolCalls = await this.executeToolCalls(plannedToolCalls, ctx);
+			const executedToolCalls = await this.toolExecutionCoordinator.execute({
+				plannedToolCalls,
+				ctx,
+				agentName: this.getAgentDisplayName(ctx),
+				repairAttemptsByToolName
+			});
 			this.appendAssistantAndToolMessages(conversation, response, executedToolCalls);
 		}
 		if (!finalResponse) throw new Error(`AIAgent "${ctx.config.name ?? ctx.nodeId}" did not produce a model response.`);
-		return finalResponse;
+		return {
+			finalResponse,
+			turnCount,
+			toolCallCount
+		};
 	}
 	cannotExecuteAnotherToolRound(turn, guardrails) {
 		return turn >= guardrails.maxTurns;
@@ -2980,6 +3398,10 @@ let AIAgentNode = class AIAgentNode$1 {
 		});
 	}
 	async invokeModel(model, nodeId, messages, ctx, inputsByPort, options) {
+		const invocationId = __codemation_core.ConnectionInvocationIdFactory.create();
+		const startedAt = /* @__PURE__ */ new Date();
+		const summarizedInput = this.summarizeLlmMessages(messages);
+		const span = this.createModelInvocationSpan(ctx, invocationId, startedAt);
 		await ctx.nodeState?.markQueued({
 			nodeId,
 			activationId: ctx.activationId,
@@ -2992,6 +3414,7 @@ let AIAgentNode = class AIAgentNode$1 {
 		});
 		try {
 			const response = await model.invoke(messages, options);
+			const finishedAt = /* @__PURE__ */ new Date();
 			await ctx.nodeState?.markCompleted({
 				nodeId,
 				activationId: ctx.activationId,
@@ -2999,22 +3422,56 @@ let AIAgentNode = class AIAgentNode$1 {
 				outputs: AgentOutputFactory.fromUnknown({ content: AgentMessageFactory.extractContent(response) })
 			});
 			const content = AgentMessageFactory.extractContent(response);
+			await span.attachArtifact({
+				kind: "ai.messages",
+				contentType: "application/json",
+				previewJson: summarizedInput
+			});
+			await span.attachArtifact({
+				kind: "ai.response",
+				contentType: "application/json",
+				previewJson: content
+			});
+			await this.recordModelUsageMetrics(span, response, ctx);
+			await span.end({
+				status: "ok",
+				endedAt: finishedAt
+			});
 			await ctx.nodeState?.appendConnectionInvocation({
-				invocationId: __codemation_core.ConnectionInvocationIdFactory.create(),
+				invocationId,
 				connectionNodeId: nodeId,
 				parentAgentNodeId: ctx.nodeId,
 				parentAgentActivationId: ctx.activationId,
 				status: "completed",
-				managedInput: this.summarizeLlmMessages(messages),
+				managedInput: summarizedInput,
 				managedOutput: content,
-				finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+				queuedAt: startedAt.toISOString(),
+				startedAt: startedAt.toISOString(),
+				finishedAt: finishedAt.toISOString()
 			});
 			return response;
 		} catch (error) {
-			throw await this.failTrackedNodeInvocation(error, nodeId, ctx, inputsByPort, this.summarizeLlmMessages(messages));
+			await span.end({
+				status: "error",
+				statusMessage: error instanceof Error ? error.message : String(error),
+				endedAt: /* @__PURE__ */ new Date()
+			});
+			throw await this.failTrackedNodeInvocation({
+				error,
+				invocationId,
+				startedAt,
+				nodeId,
+				ctx,
+				inputsByPort,
+				managedInput: this.summarizeLlmMessages(messages)
+			});
 		}
 	}
 	async invokeStructuredModel(model, nodeId, messages, ctx, inputsByPort, options) {
+		const invocationId = __codemation_core.ConnectionInvocationIdFactory.create();
+		const startedAt = /* @__PURE__ */ new Date();
+		const summarizedInput = this.summarizeLlmMessages(messages);
+		const span = this.createModelInvocationSpan(ctx, invocationId, startedAt);
 		await ctx.nodeState?.markQueued({
 			nodeId,
 			activationId: ctx.activationId,
@@ -3027,26 +3484,173 @@ let AIAgentNode = class AIAgentNode$1 {
 		});
 		try {
 			const response = await model.invoke(messages, options);
+			const finishedAt = /* @__PURE__ */ new Date();
 			await ctx.nodeState?.markCompleted({
 				nodeId,
 				activationId: ctx.activationId,
 				inputsByPort,
 				outputs: AgentOutputFactory.fromUnknown(response)
 			});
+			await span.attachArtifact({
+				kind: "ai.messages",
+				contentType: "application/json",
+				previewJson: summarizedInput
+			});
+			await span.attachArtifact({
+				kind: "ai.response.structured",
+				contentType: "application/json",
+				previewJson: this.resultToJsonValue(response)
+			});
+			await this.recordModelUsageMetrics(span, response, ctx);
+			await span.end({
+				status: "ok",
+				endedAt: finishedAt
+			});
 			await ctx.nodeState?.appendConnectionInvocation({
-				invocationId: __codemation_core.ConnectionInvocationIdFactory.create(),
+				invocationId,
 				connectionNodeId: nodeId,
 				parentAgentNodeId: ctx.nodeId,
 				parentAgentActivationId: ctx.activationId,
 				status: "completed",
-				managedInput: this.summarizeLlmMessages(messages),
+				managedInput: summarizedInput,
 				managedOutput: this.resultToJsonValue(response),
-				finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+				queuedAt: startedAt.toISOString(),
+				startedAt: startedAt.toISOString(),
+				finishedAt: finishedAt.toISOString()
 			});
 			return response;
 		} catch (error) {
-			throw await this.failTrackedNodeInvocation(error, nodeId, ctx, inputsByPort, this.summarizeLlmMessages(messages));
+			await span.end({
+				status: "error",
+				statusMessage: error instanceof Error ? error.message : String(error),
+				endedAt: /* @__PURE__ */ new Date()
+			});
+			throw await this.failTrackedNodeInvocation({
+				error,
+				invocationId,
+				startedAt,
+				nodeId,
+				ctx,
+				inputsByPort,
+				managedInput: this.summarizeLlmMessages(messages)
+			});
+		}
+	}
+	createModelInvocationSpan(ctx, invocationId, startedAt) {
+		return ctx.telemetry.startChildSpan({
+			name: "gen_ai.chat.completion",
+			kind: "client",
+			startedAt,
+			attributes: {
+				[__codemation_core.CodemationTelemetryAttributeNames.connectionInvocationId]: invocationId,
+				[__codemation_core.GenAiTelemetryAttributeNames.operationName]: "chat",
+				[__codemation_core.GenAiTelemetryAttributeNames.requestModel]: this.resolveChatModelName(ctx.config.chatModel)
+			}
+		});
+	}
+	async recordModelUsageMetrics(span, response, ctx) {
+		const usage = this.extractModelUsageMetrics(response);
+		for (const [name, value] of Object.entries(usage)) {
+			if (value === void 0) continue;
+			await span.recordMetric({
+				name,
+				value
+			});
 		}
+		await this.captureCostTrackingUsage(span, ctx, usage);
+	}
+	async captureCostTrackingUsage(span, ctx, usage) {
+		const costTracking = span.costTracking;
+		if (!costTracking) return;
+		const provider = ctx.config.chatModel.provider;
+		const pricingKey = ctx.config.chatModel.modelName;
+		if (!provider || !pricingKey) return;
+		const inputTokens = usage[__codemation_core.GenAiTelemetryAttributeNames.usageInputTokens];
+		const outputTokens = usage[__codemation_core.GenAiTelemetryAttributeNames.usageOutputTokens];
+		if (inputTokens !== void 0) await costTracking.captureUsage({
+			component: "chat",
+			provider,
+			operation: "completion.input",
+			pricingKey,
+			usageUnit: "input_tokens",
+			quantity: inputTokens,
+			modelName: pricingKey
+		});
+		if (outputTokens !== void 0) await costTracking.captureUsage({
+			component: "chat",
+			provider,
+			operation: "completion.output",
+			pricingKey,
+			usageUnit: "output_tokens",
+			quantity: outputTokens,
+			modelName: pricingKey
+		});
+	}
+	resolveChatModelName(chatModel$1) {
+		return chatModel$1.modelName ?? chatModel$1.name;
+	}
+	extractModelUsageMetrics(response) {
+		const usage = this.extractUsageObject(response);
+		const inputTokens = this.readUsageNumber(usage, [
+			"input_tokens",
+			"inputTokens",
+			"prompt_tokens",
+			"promptTokens"
+		]);
+		const outputTokens = this.readUsageNumber(usage, [
+			"output_tokens",
+			"outputTokens",
+			"completion_tokens",
+			"completionTokens"
+		]);
+		const totalTokens = this.readUsageNumber(usage, ["total_tokens", "totalTokens"]) ?? (inputTokens !== void 0 && outputTokens !== void 0 ? inputTokens + outputTokens : void 0);
+		const cachedInputTokens = this.readUsageNumber(usage, [
+			"cache_read_input_tokens",
+			"cacheReadInputTokens",
+			"input_token_details.cached_tokens"
+		]);
+		const reasoningTokens = this.readUsageNumber(usage, [
+			"reasoning_tokens",
+			"reasoningTokens",
+			"output_token_details.reasoning_tokens"
+		]);
+		return {
+			[__codemation_core.GenAiTelemetryAttributeNames.usageInputTokens]: inputTokens,
+			[__codemation_core.GenAiTelemetryAttributeNames.usageOutputTokens]: outputTokens,
+			[__codemation_core.GenAiTelemetryAttributeNames.usageTotalTokens]: totalTokens,
+			[__codemation_core.GenAiTelemetryAttributeNames.usageCacheReadInputTokens]: cachedInputTokens,
+			[__codemation_core.GenAiTelemetryAttributeNames.usageReasoningTokens]: reasoningTokens
+		};
+	}
+	extractUsageObject(response) {
+		if (!this.isRecord(response)) return;
+		const usageMetadata = response["usage_metadata"];
+		if (this.isRecord(usageMetadata)) return usageMetadata;
+		const responseMetadata = response["response_metadata"];
+		if (this.isRecord(responseMetadata)) {
+			const tokenUsage = responseMetadata["tokenUsage"];
+			if (this.isRecord(tokenUsage)) return tokenUsage;
+			const usage = responseMetadata["usage"];
+			if (this.isRecord(usage)) return usage;
+		}
+	}
+	readUsageNumber(source, keys) {
+		for (const key of keys) {
+			const value = this.readNestedUsageValue(source, key);
+			if (typeof value === "number" && Number.isFinite(value)) return value;
+		}
+	}
+	readNestedUsageValue(source, dottedKey) {
+		if (!source) return;
+		let current = source;
+		for (const segment of dottedKey.split(".")) {
+			if (!this.isRecord(current)) return;
+			current = current[segment];
+		}
+		return current;
+	}
+	isRecord(value) {
+		return typeof value === "object" && value !== null;
 	}
 	async markQueuedTools(plannedToolCalls, ctx) {
 		for (const plannedToolCall of plannedToolCalls) await ctx.nodeState?.markQueued({
@@ -3055,47 +3659,6 @@ let AIAgentNode = class AIAgentNode$1 {
 			inputsByPort: AgentToolCallPortMap.fromInput(plannedToolCall.toolCall.input ?? {})
 		});
 	}
-	async executeToolCalls(plannedToolCalls, ctx) {
-		const results = await Promise.allSettled(plannedToolCalls.map(async (plannedToolCall) => {
-			const toolCallInputsByPort = AgentToolCallPortMap.fromInput(plannedToolCall.toolCall.input ?? {});
-			await ctx.nodeState?.markRunning({
-				nodeId: plannedToolCall.nodeId,
-				activationId: ctx.activationId,
-				inputsByPort: toolCallInputsByPort
-			});
-			try {
-				const serialized = await plannedToolCall.binding.langChainTool.invoke(plannedToolCall.toolCall.input ?? {});
-				const result = this.parseToolOutput(serialized);
-				await ctx.nodeState?.markCompleted({
-					nodeId: plannedToolCall.nodeId,
-					activationId: ctx.activationId,
-					inputsByPort: toolCallInputsByPort,
-					outputs: AgentOutputFactory.fromUnknown(result)
-				});
-				await ctx.nodeState?.appendConnectionInvocation({
-					invocationId: __codemation_core.ConnectionInvocationIdFactory.create(),
-					connectionNodeId: plannedToolCall.nodeId,
-					parentAgentNodeId: ctx.nodeId,
-					parentAgentActivationId: ctx.activationId,
-					status: "completed",
-					managedInput: this.toolCallInputToJson(plannedToolCall.toolCall.input),
-					managedOutput: this.resultToJsonValue(result),
-					finishedAt: (/* @__PURE__ */ new Date()).toISOString()
-				});
-				return {
-					toolName: plannedToolCall.binding.config.name,
-					toolCallId: plannedToolCall.toolCall.id ?? plannedToolCall.binding.config.name,
-					serialized,
-					result
-				};
-			} catch (error) {
-				throw await this.failTrackedNodeInvocation(error, plannedToolCall.nodeId, ctx, toolCallInputsByPort, this.toolCallInputToJson(plannedToolCall.toolCall.input));
-			}
-		}));
-		const rejected = results.find((result) => result.status === "rejected");
-		if (rejected?.status === "rejected") throw rejected.reason instanceof Error ? rejected.reason : new Error(String(rejected.reason));
-		return results.filter((result) => result.status === "fulfilled").map((result) => result.value);
-	}
 	planToolCalls(bindings, toolCalls, parentNodeId) {
 		const invocationCountByToolName = /* @__PURE__ */ new Map();
 		return toolCalls.map((toolCall) => {
@@ -3111,35 +3674,31 @@ let AIAgentNode = class AIAgentNode$1 {
 			};
 		});
 	}
-	parseToolOutput(serialized) {
-		if (typeof serialized !== "string") return serialized;
-		try {
-			return JSON.parse(serialized);
-		} catch {
-			return serialized;
-		}
-	}
-	async failTrackedNodeInvocation(error, nodeId, ctx, inputsByPort, managedInput) {
-		const effectiveError = error instanceof Error ? error : new Error(String(error));
-		await ctx.nodeState?.markFailed({
-			nodeId,
-			activationId: ctx.activationId,
-			inputsByPort,
+	async failTrackedNodeInvocation(args) {
+		const effectiveError = args.error instanceof Error ? args.error : new Error(String(args.error));
+		const finishedAt = /* @__PURE__ */ new Date();
+		await args.ctx.nodeState?.markFailed({
+			nodeId: args.nodeId,
+			activationId: args.ctx.activationId,
+			inputsByPort: args.inputsByPort,
 			error: effectiveError
 		});
-		await ctx.nodeState?.appendConnectionInvocation({
-			invocationId: __codemation_core.ConnectionInvocationIdFactory.create(),
-			connectionNodeId: nodeId,
-			parentAgentNodeId: ctx.nodeId,
-			parentAgentActivationId: ctx.activationId,
+		await args.ctx.nodeState?.appendConnectionInvocation({
+			invocationId: args.invocationId,
+			connectionNodeId: args.nodeId,
+			parentAgentNodeId: args.ctx.nodeId,
+			parentAgentActivationId: args.ctx.activationId,
 			status: "failed",
-			managedInput,
+			managedInput: args.managedInput,
 			error: {
 				message: effectiveError.message,
 				name: effectiveError.name,
-				stack: effectiveError.stack
+				stack: effectiveError.stack,
+				details: this.extractErrorDetails(effectiveError)
 			},
-			finishedAt: (/* @__PURE__ */ new Date()).toISOString()
+			queuedAt: args.startedAt.toISOString(),
+			startedAt: args.startedAt.toISOString(),
+			finishedAt: finishedAt.toISOString()
 		});
 		return effectiveError;
 	}
@@ -3151,9 +3710,6 @@ let AIAgentNode = class AIAgentNode$1 {
 			lastMessagePreview: preview.slice(0, 4e3)
 		};
 	}
-	toolCallInputToJson(input) {
-		return this.resultToJsonValue(input);
-	}
 	resultToJsonValue(value) {
 		if (value === void 0) return;
 		const json = JSON.stringify(value);
@@ -3223,6 +3779,9 @@ let AIAgentNode = class AIAgentNode$1 {
 	getAgentDisplayName(ctx) {
 		return ctx.config.name ?? ctx.nodeId;
 	}
+	extractErrorDetails(error) {
+		return error.details;
+	}
 };
 AIAgentNode = __decorate([
 	(0, __codemation_core.node)({ packageName: "@codemation/core-nodes" }),
@@ -3231,12 +3790,14 @@ AIAgentNode = __decorate([
 	__decorateParam(2, (0, __codemation_core.inject)(NodeBackedToolRuntime)),
 	__decorateParam(3, (0, __codemation_core.inject)(AIAgentExecutionHelpersFactory)),
 	__decorateParam(4, (0, __codemation_core.inject)(AgentStructuredOutputRunner)),
+	__decorateParam(5, (0, __codemation_core.inject)(AgentToolExecutionCoordinator)),
 	__decorateMetadata("design:paramtypes", [
 		Object,
 		Object,
 		typeof (_ref = typeof NodeBackedToolRuntime !== "undefined" && NodeBackedToolRuntime) === "function" ? _ref : Object,
 		typeof (_ref2 = typeof AIAgentExecutionHelpersFactory !== "undefined" && AIAgentExecutionHelpersFactory) === "function" ? _ref2 : Object,
-		typeof (_ref3 = typeof AgentStructuredOutputRunner !== "undefined" && AgentStructuredOutputRunner) === "function" ? _ref3 : Object
+		typeof (_ref3 = typeof AgentStructuredOutputRunner !== "undefined" && AgentStructuredOutputRunner) === "function" ? _ref3 : Object,
+		typeof (_ref4 = typeof AgentToolExecutionCoordinator !== "undefined" && AgentToolExecutionCoordinator) === "function" ? _ref4 : Object
 	])
 ], AIAgentNode);
 
@@ -3458,6 +4019,7 @@ var Aggregate = class {
 	kind = "node";
 	type = AggregateNode;
 	execution = { hint: "local" };
+	keepBinaries = true;
 	icon = "lucide:layers";
 	constructor(name, aggregate, id) {
 		this.name = name;
@@ -3612,6 +4174,7 @@ var Split = class {
 	kind = "node";
 	type = SplitNode;
 	execution = { hint: "local" };
+	keepBinaries = true;
 	/**
 	* When splitting yields zero items for a batch, downstream single-input nodes still run once with an empty batch.
 	* Mirrors {@link MapData}'s empty-output behavior.
@@ -4321,6 +4884,25 @@ Object.defineProperty(exports, 'AgentStructuredOutputRunner', {
   }
 });
 exports.AgentToolCallPortMap = AgentToolCallPortMap;
+Object.defineProperty(exports, 'AgentToolErrorClassifier', {
+  enumerable: true,
+  get: function () {
+    return AgentToolErrorClassifier;
+  }
+});
+Object.defineProperty(exports, 'AgentToolExecutionCoordinator', {
+  enumerable: true,
+  get: function () {
+    return AgentToolExecutionCoordinator;
+  }
+});
+exports.AgentToolRepairExhaustedError = AgentToolRepairExhaustedError;
+Object.defineProperty(exports, 'AgentToolRepairPolicy', {
+  enumerable: true,
+  get: function () {
+    return AgentToolRepairPolicy;
+  }
+});
 exports.Aggregate = Aggregate;
 Object.defineProperty(exports, 'AggregateNode', {
   enumerable: true,