@codemation/core-nodes 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core-nodes",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "publishConfig": {
     "access": "public"
   },
@@ -31,7 +31,7 @@
     "@langchain/core": "^1.1.31",
     "@langchain/openai": "^1.2.12",
     "lucide-react": "^0.577.0",
-    "@codemation/core": "0.7.0"
+    "@codemation/core": "0.8.1"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",

package/src/chatModels/openAiChatModelConfig.ts

@@ -6,6 +6,8 @@ import { OpenAIChatModelFactory } from "./OpenAIChatModelFactory";
 export class OpenAIChatModelConfig implements ChatModelConfig {
   readonly type = OpenAIChatModelFactory;
   readonly presentation: AgentCanvasPresentation<CanvasIconName>;
+  readonly provider = "openai";
+  readonly modelName: string;
 
   constructor(
     public readonly name: string,
@@ -17,6 +19,7 @@ export class OpenAIChatModelConfig implements ChatModelConfig {
       maxTokens?: number;
     }>,
   ) {
+    this.modelName = model;
     this.presentation = presentationIn ?? { icon: "builtin:openai", label: name };
   }
 

package/src/nodes/AIAgentNode.ts

@@ -22,9 +22,12 @@ import {
   AgentGuardrailDefaults,
   AgentMessageConfigNormalizer,
   CallableToolConfig,
+  CodemationTelemetryAttributeNames,
+  CodemationTelemetryMetricNames,
   ConnectionInvocationIdFactory,
   ConnectionNodeIdFactory,
   CoreTokens,
+  GenAiTelemetryAttributeNames,
   NodeBackedToolConfig,
   inject,
   node,
@@ -36,6 +39,7 @@ import { z } from "zod";
 
 import type { AIAgent } from "./AIAgentConfig";
 import { AIAgentExecutionHelpersFactory } from "./AIAgentExecutionHelpersFactory";
+import { AgentToolExecutionCoordinator } from "./AgentToolExecutionCoordinator";
 import { ConnectionCredentialExecutionContextFactory } from "./ConnectionCredentialExecutionContextFactory";
 import { AgentMessageFactory } from "./AgentMessageFactory";
 import { AgentOutputFactory } from "./AgentOutputFactory";
@@ -91,6 +95,8 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     private readonly executionHelpers: AIAgentExecutionHelpersFactory,
     @inject(AgentStructuredOutputRunner)
     private readonly structuredOutputRunner: AgentStructuredOutputRunner,
+    @inject(AgentToolExecutionCoordinator)
+    private readonly toolExecutionCoordinator: AgentToolExecutionCoordinator,
   ) {
     this.connectionCredentialExecutionContextFactory =
       this.executionHelpers.createConnectionCredentialExecutionContextFactory(credentialSessions);
@@ -178,21 +184,28 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
             prepared.guardrails.modelInvocationOptions,
           ),
       });
+      await ctx.telemetry.recordMetric({ name: CodemationTelemetryMetricNames.agentTurns, value: 1 });
+      await ctx.telemetry.recordMetric({ name: 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,
     });
+    await ctx.telemetry.recordMetric({ name: CodemationTelemetryMetricNames.agentTurns, value: loopResult.turnCount });
+    await ctx.telemetry.recordMetric({
+      name: CodemationTelemetryMetricNames.agentToolCalls,
+      value: loopResult.toolCallCount,
+    });
     const outputJson = await this.resolveFinalOutputJson(
       prepared,
       itemInputsByPort,
       conversation,
-      finalResponse,
+      loopResult.finalResponse,
       itemScopedTools.length > 0,
     );
     return this.buildOutputItem(item, outputJson);
@@ -207,13 +220,17 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     itemScopedTools: ReadonlyArray<ItemScopedToolBinding>;
     conversation: BaseMessage[];
     modelWithTools: LangChainChatModelLike;
-  }): Promise<AIMessage> {
+  }): Promise<Readonly<{ finalResponse: AIMessage; turnCount: number; toolCallCount: number }>> {
     const { prepared, itemInputsByPort, itemScopedTools, conversation, modelWithTools } = args;
     const { ctx, guardrails, languageModelConnectionNodeId } = prepared;
 
     let finalResponse: AIMessage | undefined;
+    let toolCallCount = 0;
+    let turnCount = 0;
+    const repairAttemptsByToolName = new Map<string, number>();
 
     for (let turn = 1; turn <= guardrails.maxTurns; turn++) {
+      turnCount = turn;
       const response = await this.invokeModel(
         modelWithTools,
         languageModelConnectionNodeId,
@@ -235,15 +252,25 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       }
 
       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,
+    };
   }
 
   private cannotExecuteAnotherToolRound(turn: number, guardrails: ResolvedGuardrails): boolean {
@@ -374,10 +401,15 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     inputsByPort: NodeInputsByPort,
     options?: AgentGuardrailConfig["modelInvocationOptions"],
   ): Promise<AIMessage> {
+    const invocationId = ConnectionInvocationIdFactory.create();
+    const startedAt = new Date();
+    const summarizedInput = this.summarizeLlmMessages(messages);
+    const span = this.createModelInvocationSpan(ctx, invocationId, startedAt);
     await ctx.nodeState?.markQueued({ nodeId, activationId: ctx.activationId, inputsByPort });
     await ctx.nodeState?.markRunning({ nodeId, activationId: ctx.activationId, inputsByPort });
     try {
       const response = (await model.invoke(messages, options)) as AIMessage;
+      const finishedAt = new Date();
       await ctx.nodeState?.markCompleted({
         nodeId,
         activationId: ctx.activationId,
@@ -387,19 +419,46 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         }),
       });
       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: ConnectionInvocationIdFactory.create(),
+        invocationId,
         connectionNodeId: nodeId,
         parentAgentNodeId: ctx.nodeId,
         parentAgentActivationId: ctx.activationId,
         status: "completed",
-        managedInput: this.summarizeLlmMessages(messages),
+        managedInput: summarizedInput,
         managedOutput: content,
-        finishedAt: 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: new Date(),
+      });
+      throw await this.failTrackedNodeInvocation({
+        error,
+        invocationId,
+        startedAt,
+        nodeId,
+        ctx,
+        inputsByPort,
+        managedInput: this.summarizeLlmMessages(messages),
+      });
     }
   }
 
@@ -411,30 +470,222 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     inputsByPort: NodeInputsByPort,
     options?: AgentGuardrailConfig["modelInvocationOptions"],
   ): Promise<unknown> {
+    const invocationId = ConnectionInvocationIdFactory.create();
+    const startedAt = new Date();
+    const summarizedInput = this.summarizeLlmMessages(messages);
+    const span = this.createModelInvocationSpan(ctx, invocationId, startedAt);
     await ctx.nodeState?.markQueued({ nodeId, activationId: ctx.activationId, inputsByPort });
     await ctx.nodeState?.markRunning({ nodeId, activationId: ctx.activationId, inputsByPort });
     try {
       const response = await model.invoke(messages, options);
+      const finishedAt = 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: ConnectionInvocationIdFactory.create(),
+        invocationId,
         connectionNodeId: nodeId,
         parentAgentNodeId: ctx.nodeId,
         parentAgentActivationId: ctx.activationId,
         status: "completed",
-        managedInput: this.summarizeLlmMessages(messages),
+        managedInput: summarizedInput,
         managedOutput: this.resultToJsonValue(response),
-        finishedAt: 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: new Date(),
+      });
+      throw await this.failTrackedNodeInvocation({
+        error,
+        invocationId,
+        startedAt,
+        nodeId,
+        ctx,
+        inputsByPort,
+        managedInput: this.summarizeLlmMessages(messages),
+      });
+    }
+  }
+
+  private createModelInvocationSpan(
+    ctx: NodeExecutionContext<AIAgent<any, any>>,
+    invocationId: string,
+    startedAt: Date,
+  ) {
+    return ctx.telemetry.startChildSpan({
+      name: "gen_ai.chat.completion",
+      kind: "client",
+      startedAt,
+      attributes: {
+        [CodemationTelemetryAttributeNames.connectionInvocationId]: invocationId,
+        [GenAiTelemetryAttributeNames.operationName]: "chat",
+        [GenAiTelemetryAttributeNames.requestModel]: this.resolveChatModelName(ctx.config.chatModel),
+      },
+    });
+  }
+
+  private async recordModelUsageMetrics(
+    span: ReturnType<NodeExecutionContext["telemetry"]["startChildSpan"]>,
+    response: unknown,
+    ctx: NodeExecutionContext<AIAgent<any, any>>,
+  ) {
+    const usage = this.extractModelUsageMetrics(response);
+    for (const [name, value] of Object.entries(usage)) {
+      if (value === undefined) {
+        continue;
+      }
+      await span.recordMetric({ name, value });
     }
+    await this.captureCostTrackingUsage(span, ctx, usage);
+  }
+
+  private async captureCostTrackingUsage(
+    span: ReturnType<NodeExecutionContext["telemetry"]["startChildSpan"]>,
+    ctx: NodeExecutionContext<AIAgent<any, any>>,
+    usage: Readonly<Record<string, number | undefined>>,
+  ): Promise<void> {
+    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[GenAiTelemetryAttributeNames.usageInputTokens];
+    const outputTokens = usage[GenAiTelemetryAttributeNames.usageOutputTokens];
+    if (inputTokens !== undefined) {
+      await costTracking.captureUsage({
+        component: "chat",
+        provider,
+        operation: "completion.input",
+        pricingKey,
+        usageUnit: "input_tokens",
+        quantity: inputTokens,
+        modelName: pricingKey,
+      });
+    }
+    if (outputTokens !== undefined) {
+      await costTracking.captureUsage({
+        component: "chat",
+        provider,
+        operation: "completion.output",
+        pricingKey,
+        usageUnit: "output_tokens",
+        quantity: outputTokens,
+        modelName: pricingKey,
+      });
+    }
+  }
+
+  private resolveChatModelName(chatModel: ChatModelConfig): string {
+    return chatModel.modelName ?? chatModel.name;
+  }
+
+  private extractModelUsageMetrics(response: unknown): Readonly<Record<string, number | undefined>> {
+    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 !== undefined && outputTokens !== undefined ? inputTokens + outputTokens : undefined);
+    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 {
+      [GenAiTelemetryAttributeNames.usageInputTokens]: inputTokens,
+      [GenAiTelemetryAttributeNames.usageOutputTokens]: outputTokens,
+      [GenAiTelemetryAttributeNames.usageTotalTokens]: totalTokens,
+      [GenAiTelemetryAttributeNames.usageCacheReadInputTokens]: cachedInputTokens,
+      [GenAiTelemetryAttributeNames.usageReasoningTokens]: reasoningTokens,
+    };
+  }
+
+  private extractUsageObject(response: unknown): Readonly<Record<string, unknown>> | undefined {
+    if (!this.isRecord(response)) {
+      return undefined;
+    }
+    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;
+      }
+    }
+    return undefined;
+  }
+
+  private readUsageNumber(
+    source: Readonly<Record<string, unknown>> | undefined,
+    keys: ReadonlyArray<string>,
+  ): number | undefined {
+    for (const key of keys) {
+      const value = this.readNestedUsageValue(source, key);
+      if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+      }
+    }
+    return undefined;
+  }
+
+  private readNestedUsageValue(source: Readonly<Record<string, unknown>> | undefined, dottedKey: string): unknown {
+    if (!source) {
+      return undefined;
+    }
+    let current: unknown = source;
+    for (const segment of dottedKey.split(".")) {
+      if (!this.isRecord(current)) {
+        return undefined;
+      }
+      current = current[segment];
+    }
+    return current;
+  }
+
+  private isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null;
   }
 
   private async markQueuedTools(
@@ -450,65 +701,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     }
   }
 
-  private async executeToolCalls(
-    plannedToolCalls: ReadonlyArray<PlannedToolCall>,
-    ctx: NodeExecutionContext<AIAgent<any, any>>,
-  ): Promise<ReadonlyArray<ExecutedToolCall>> {
-    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: ConnectionInvocationIdFactory.create(),
-            connectionNodeId: plannedToolCall.nodeId,
-            parentAgentNodeId: ctx.nodeId,
-            parentAgentActivationId: ctx.activationId,
-            status: "completed",
-            managedInput: this.toolCallInputToJson(plannedToolCall.toolCall.input),
-            managedOutput: this.resultToJsonValue(result),
-            finishedAt: new Date().toISOString(),
-          });
-          return {
-            toolName: plannedToolCall.binding.config.name,
-            toolCallId: plannedToolCall.toolCall.id ?? plannedToolCall.binding.config.name,
-            serialized,
-            result,
-          } satisfies ExecutedToolCall;
-        } 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 is PromiseFulfilledResult<ExecutedToolCall> => result.status === "fulfilled")
-      .map((result) => result.value);
-  }
-
   private planToolCalls(
     bindings: ReadonlyArray<ItemScopedToolBinding>,
     toolCalls: ReadonlyArray<AgentToolCall>,
@@ -529,42 +721,41 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     });
   }
 
-  private parseToolOutput(serialized: unknown): unknown {
-    if (typeof serialized !== "string") return serialized;
-    try {
-      return JSON.parse(serialized);
-    } catch {
-      return serialized;
-    }
-  }
-
   private async failTrackedNodeInvocation(
-    error: unknown,
-    nodeId: string,
-    ctx: NodeExecutionContext<AIAgent<any, any>>,
-    inputsByPort: NodeInputsByPort,
-    managedInput?: JsonValue,
+    args: Readonly<{
+      error: unknown;
+      invocationId: string;
+      startedAt: Date;
+      nodeId: string;
+      ctx: NodeExecutionContext<AIAgent<any, any>>;
+      inputsByPort: NodeInputsByPort;
+      managedInput?: JsonValue;
+    }>,
   ): Promise<Error> {
-    const effectiveError = error instanceof Error ? error : new Error(String(error));
-    await ctx.nodeState?.markFailed({
-      nodeId,
-      activationId: ctx.activationId,
-      inputsByPort,
+    const effectiveError = args.error instanceof Error ? args.error : new Error(String(args.error));
+    const finishedAt = new Date();
+    await args.ctx.nodeState?.markFailed({
+      nodeId: args.nodeId,
+      activationId: args.ctx.activationId,
+      inputsByPort: args.inputsByPort,
       error: effectiveError,
     });
-    await ctx.nodeState?.appendConnectionInvocation({
-      invocationId: 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,
+        details: this.extractErrorDetails(effectiveError),
       },
-      finishedAt: new Date().toISOString(),
+      queuedAt: args.startedAt.toISOString(),
+      startedAt: args.startedAt.toISOString(),
+      finishedAt: finishedAt.toISOString(),
     });
     return effectiveError;
   }
@@ -583,10 +774,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     };
   }
 
-  private toolCallInputToJson(input: unknown): JsonValue | undefined {
-    return this.resultToJsonValue(input);
-  }
-
   private resultToJsonValue(value: unknown): JsonValue | undefined {
     if (value === undefined) {
       return undefined;
@@ -687,4 +874,9 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   private getAgentDisplayName(ctx: NodeExecutionContext<AIAgent<any, any>>): string {
     return ctx.config.name ?? ctx.nodeId;
   }
+
+  private extractErrorDetails(error: Error): JsonValue | undefined {
+    const candidate = error as Error & { details?: JsonValue };
+    return candidate.details;
+  }
 }

package/src/nodes/AgentToolErrorClassifier.ts

@@ -0,0 +1,106 @@
+import type { JsonValue } from "@codemation/core";
+import { injectable } from "@codemation/core";
+import { ZodError } from "zod";
+
+import type { AgentToolFailureClassification, AgentToolValidationIssue } from "./AgentToolRepair.types";
+
+@injectable()
+export class AgentToolErrorClassifier {
+  classify(
+    args: Readonly<{
+      error: unknown;
+      toolName: string;
+      schema?: unknown;
+    }>,
+  ): AgentToolFailureClassification {
+    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,
+    };
+  }
+
+  private isRepairableValidationError(rawError: unknown, effectiveError: Error): boolean {
+    if (rawError instanceof ZodError) {
+      const stage = (rawError as ZodError & { codemationToolValidationStage?: "input" | "output" })
+        .codemationToolValidationStage;
+      return stage !== "output";
+    }
+    if (effectiveError.name === "ZodError") {
+      return true;
+    }
+    return effectiveError.message.includes("Received tool input did not match expected schema");
+  }
+
+  private extractIssues(
+    rawError: unknown,
+    effectiveError: Error,
+    toolName: string,
+  ): ReadonlyArray<AgentToolValidationIssue> | undefined {
+    if (rawError instanceof ZodError) {
+      return rawError.issues.map((issue) => ({
+        path: issue.path.map((segment) => (typeof segment === "number" ? segment : String(segment))),
+        code: issue.code,
+        message: issue.message,
+        expected: this.toOptionalString("expected" in issue ? issue.expected : undefined),
+        received: this.toOptionalString("received" in issue ? issue.received : undefined),
+      }));
+    }
+    if (effectiveError.name !== "ZodError") {
+      return undefined;
+    }
+    return [
+      {
+        path: [],
+        code: "invalid_tool_input",
+        message: `Tool "${toolName}" input was invalid: ${effectiveError.message}`,
+      },
+    ];
+  }
+
+  private isTransientExecutionError(error: Error): boolean {
+    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")
+    );
+  }
+
+  private toError(error: unknown): Error {
+    return error instanceof Error ? error : new Error(String(error));
+  }
+
+  private toJsonValue(value: unknown): JsonValue | undefined {
+    if (value === undefined) {
+      return undefined;
+    }
+    return JSON.parse(JSON.stringify(value)) as JsonValue;
+  }
+
+  private toOptionalString(value: unknown): string | undefined {
+    if (value === undefined) {
+      return undefined;
+    }
+    return String(value);
+  }
+}