@codemation/core-nodes 0.1.1 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core-nodes",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "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.5.0"
+    "@codemation/core": "0.6.0"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",

package/src/chatModels/OpenAIStructuredOutputMethodFactory.ts

@@ -0,0 +1,46 @@
+import type { ChatModelConfig, ChatModelStructuredOutputOptions } from "@codemation/core";
+import { injectable } from "@codemation/core";
+
+import { OpenAIChatModelFactory } from "./OpenAIChatModelFactory";
+
+@injectable()
+export class OpenAIStructuredOutputMethodFactory {
+  private static readonly isoDatePattern = /^\d{4}-\d{2}-\d{2}$/;
+
+  create(chatModelConfig: ChatModelConfig): ChatModelStructuredOutputOptions | undefined {
+    if (chatModelConfig.type !== OpenAIChatModelFactory) {
+      return undefined;
+    }
+    const model = this.readModelName(chatModelConfig);
+    if (!model) {
+      return { method: "functionCalling", strict: true };
+    }
+    return {
+      method: this.supportsJsonSchema(model) ? "jsonSchema" : "functionCalling",
+      strict: true,
+    };
+  }
+
+  private readModelName(chatModelConfig: ChatModelConfig): string | undefined {
+    const candidate = chatModelConfig as Readonly<{ model?: unknown }>;
+    return typeof candidate.model === "string" ? candidate.model : undefined;
+  }
+
+  private supportsJsonSchema(model: string): boolean {
+    if (model === "gpt-4o" || model === "gpt-4o-mini") {
+      return true;
+    }
+    return (
+      this.supportsSnapshotAtOrAfter(model, "gpt-4o-", "2024-08-06") ||
+      this.supportsSnapshotAtOrAfter(model, "gpt-4o-mini-", "2024-07-18")
+    );
+  }
+
+  private supportsSnapshotAtOrAfter(model: string, prefix: string, minimumSnapshotDate: string): boolean {
+    if (!model.startsWith(prefix)) {
+      return false;
+    }
+    const snapshotDate = model.slice(prefix.length);
+    return OpenAIStructuredOutputMethodFactory.isoDatePattern.test(snapshotDate) && snapshotDate >= minimumSnapshotDate;
+  }
+}

package/src/index.ts

@@ -1,5 +1,6 @@
 export * from "./canvasIconName";
 export * from "./chatModels/OpenAIChatModelFactory";
+export * from "./chatModels/OpenAIStructuredOutputMethodFactory";
 export * from "./chatModels/OpenAiCredentialSession";
 export * from "./chatModels/openAiChatModelConfig";
 export * from "./chatModels/OpenAiChatModelPresetsFactory";

package/src/nodes/AIAgentConfig.ts

@@ -23,6 +23,7 @@ export interface AIAgentOptions<TInputJson = unknown, _TOutputJson = unknown> {
   readonly guardrails?: AgentGuardrailConfig;
   /** Engine applies with {@link RunnableNodeConfig.inputSchema} before {@link AIAgentNode.execute}. */
   readonly inputSchema?: ZodType<TInputJson>;
+  readonly outputSchema?: ZodType<_TOutputJson>;
 }
 
 /**
@@ -44,6 +45,7 @@ export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
   readonly retryPolicy: RetryPolicySpec;
   readonly guardrails?: AgentGuardrailConfig;
   readonly inputSchema?: ZodType<TInputJson>;
+  readonly outputSchema?: ZodType<TOutputJson>;
 
   constructor(options: AIAgentOptions<TInputJson, TOutputJson>) {
     this.name = options.name;
@@ -54,5 +56,6 @@ export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
     this.retryPolicy = options.retryPolicy ?? RetryPolicy.defaultForAiAgent;
     this.guardrails = options.guardrails;
     this.inputSchema = options.inputSchema;
+    this.outputSchema = options.outputSchema;
   }
 }

package/src/nodes/AIAgentExecutionHelpersFactory.ts

@@ -33,10 +33,10 @@ export class AIAgentExecutionHelpersFactory {
         `Cannot create LangChain tool "${entry.config.name}": missing inputSchema (broken tool runtime resolution).`,
       );
     }
-    const schemaForOpenAi = this.normalizeToolInputSchemaForOpenAiDynamicStructuredTool(
-      entry.config.name,
-      entry.runtime.inputSchema,
-    );
+    const schemaForOpenAi = this.createJsonSchemaRecord(entry.runtime.inputSchema, {
+      schemaName: entry.config.name,
+      requireObjectRoot: true,
+    });
     return new DynamicStructuredTool({
       name: entry.config.name,
       description: entry.config.description ?? entry.runtime.defaultDescription,
@@ -63,9 +63,12 @@ export class AIAgentExecutionHelpersFactory {
    *   (duplicate `zod` copies), fall back to Zod `toJSONSchema` with draft-07.
    * - Strip root `$schema` for OpenAI; normalize invalid `required` keywords for cfworker; ensure `properties`.
    */
-  private normalizeToolInputSchemaForOpenAiDynamicStructuredTool(
-    toolName: string,
+  createJsonSchemaRecord(
     inputSchema: ZodSchemaAny,
+    options: Readonly<{
+      schemaName: string;
+      requireObjectRoot: boolean;
+    }>,
   ): Record<string, unknown> {
     const draft07Params = { target: "draft-07" as const };
     let converted: unknown;
@@ -79,17 +82,21 @@ export class AIAgentExecutionHelpersFactory {
     }
     const record = converted as Record<string, unknown>;
     const { $schema: _draftSchemaOmitted, ...rest } = record;
-    if (rest.type !== "object") {
+    if (options.requireObjectRoot && rest.type !== "object") {
       throw new Error(
-        `Cannot create LangChain tool "${toolName}": tool input schema must be a JSON Schema object type (got type=${String(rest.type)}).`,
+        `Cannot create LangChain tool "${options.schemaName}": tool input schema must be a JSON Schema object type (got type=${String(rest.type)}).`,
       );
     }
-    if (rest.properties !== undefined && (typeof rest.properties !== "object" || Array.isArray(rest.properties))) {
+    if (
+      options.requireObjectRoot &&
+      rest.properties !== undefined &&
+      (typeof rest.properties !== "object" || Array.isArray(rest.properties))
+    ) {
       throw new Error(
-        `Cannot create LangChain tool "${toolName}": tool input schema "properties" must be an object (got ${JSON.stringify(rest.properties)}).`,
+        `Cannot create LangChain tool "${options.schemaName}": tool input schema "properties" must be an object (got ${JSON.stringify(rest.properties)}).`,
       );
     }
-    if (rest.properties === undefined) {
+    if (options.requireObjectRoot && rest.properties === undefined) {
       rest.properties = {};
     }
     this.sanitizeJsonSchemaRequiredKeywordsForCfworker(rest);

package/src/nodes/AIAgentNode.ts

@@ -13,6 +13,7 @@ import type {
   RunnableNodeExecuteArgs,
   Tool,
   ToolConfig,
+  LangChainStructuredOutputModelLike,
   ZodSchemaAny,
 } from "@codemation/core";
 
@@ -20,6 +21,7 @@ import type { CredentialSessionService } from "@codemation/core";
 import {
   AgentGuardrailDefaults,
   AgentMessageConfigNormalizer,
+  CallableToolConfig,
   ConnectionInvocationIdFactory,
   ConnectionNodeIdFactory,
   CoreTokens,
@@ -37,6 +39,7 @@ import { AIAgentExecutionHelpersFactory } from "./AIAgentExecutionHelpersFactory
 import { ConnectionCredentialExecutionContextFactory } from "./ConnectionCredentialExecutionContextFactory";
 import { AgentMessageFactory } from "./AgentMessageFactory";
 import { AgentOutputFactory } from "./AgentOutputFactory";
+import { AgentStructuredOutputRunner } from "./AgentStructuredOutputRunner";
 import { AgentToolCallPortMap } from "./AgentToolCallPortMapFactory";
 import { NodeBackedToolRuntime } from "./NodeBackedToolRuntime";
 import {
@@ -86,6 +89,8 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     private readonly nodeBackedToolRuntime: NodeBackedToolRuntime,
     @inject(AIAgentExecutionHelpersFactory)
     private readonly executionHelpers: AIAgentExecutionHelpersFactory,
+    @inject(AgentStructuredOutputRunner)
+    private readonly structuredOutputRunner: AgentStructuredOutputRunner,
   ) {
     this.connectionCredentialExecutionContextFactory =
       this.executionHelpers.createConnectionCredentialExecutionContextFactory(credentialSessions);
@@ -146,6 +151,35 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     const itemInputsByPort = AgentItemPortMap.fromItem(item);
     const itemScopedTools = this.createItemScopedTools(prepared.resolvedTools, ctx, item, itemIndex, items);
     const conversation: BaseMessage[] = [...this.createPromptMessages(item, itemIndex, items, ctx)];
+    if (ctx.config.outputSchema && itemScopedTools.length === 0) {
+      const structuredOutput = await this.structuredOutputRunner.resolve({
+        model: prepared.model,
+        chatModelConfig: ctx.config.chatModel,
+        schema: ctx.config.outputSchema,
+        conversation,
+        agentName: this.getAgentDisplayName(ctx),
+        nodeId: ctx.nodeId,
+        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,
+          ),
+      });
+      return this.buildOutputItem(item, structuredOutput);
+    }
     const modelWithTools = this.bindToolsToModel(prepared.model, itemScopedTools);
     const finalResponse = await this.runTurnLoopUntilFinalAnswer({
       prepared,
@@ -154,7 +188,14 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       conversation,
       modelWithTools,
     });
-    return this.buildOutputItem(item, finalResponse);
+    const outputJson = await this.resolveFinalOutputJson(
+      prepared,
+      itemInputsByPort,
+      conversation,
+      finalResponse,
+      itemScopedTools.length > 0,
+    );
+    return this.buildOutputItem(item, outputJson);
   }
 
   /**
@@ -234,11 +275,47 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     );
   }
 
-  private buildOutputItem(item: Item, finalResponse: AIMessage): Item {
-    return AgentOutputFactory.replaceJson(
-      item,
-      AgentOutputFactory.fromAgentContent(AgentMessageFactory.extractContent(finalResponse)),
-    );
+  private async resolveFinalOutputJson(
+    prepared: PreparedAgentExecution,
+    itemInputsByPort: NodeInputsByPort,
+    conversation: ReadonlyArray<BaseMessage>,
+    finalResponse: AIMessage,
+    wasToolEnabledRun: boolean,
+  ): Promise<unknown> {
+    if (!prepared.ctx.config.outputSchema) {
+      return AgentOutputFactory.fromAgentContent(AgentMessageFactory.extractContent(finalResponse));
+    }
+    return await this.structuredOutputRunner.resolve({
+      model: prepared.model,
+      chatModelConfig: prepared.ctx.config.chatModel,
+      schema: prepared.ctx.config.outputSchema,
+      conversation: wasToolEnabledRun ? [...conversation, finalResponse] : conversation,
+      rawFinalResponse: finalResponse,
+      agentName: this.getAgentDisplayName(prepared.ctx),
+      nodeId: prepared.ctx.nodeId,
+      invokeTextModel: async (messages) =>
+        await this.invokeModel(
+          prepared.model,
+          prepared.languageModelConnectionNodeId,
+          messages,
+          prepared.ctx,
+          itemInputsByPort,
+          prepared.guardrails.modelInvocationOptions,
+        ),
+      invokeStructuredModel: async (structuredModel, messages) =>
+        await this.invokeStructuredModel(
+          structuredModel,
+          prepared.languageModelConnectionNodeId,
+          messages,
+          prepared.ctx,
+          itemInputsByPort,
+          prepared.guardrails.modelInvocationOptions,
+        ),
+    });
+  }
+
+  private buildOutputItem(item: Item, outputJson: unknown): Item {
+    return AgentOutputFactory.replaceJson(item, outputJson);
   }
 
   private bindToolsToModel(
@@ -326,6 +403,40 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     }
   }
 
+  private async invokeStructuredModel(
+    model: LangChainStructuredOutputModelLike,
+    nodeId: string,
+    messages: ReadonlyArray<BaseMessage>,
+    ctx: NodeExecutionContext<AIAgent<any, any>>,
+    inputsByPort: NodeInputsByPort,
+    options?: AgentGuardrailConfig["modelInvocationOptions"],
+  ): Promise<unknown> {
+    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);
+      await ctx.nodeState?.markCompleted({
+        nodeId,
+        activationId: ctx.activationId,
+        inputsByPort,
+        outputs: AgentOutputFactory.fromUnknown(response),
+      });
+      await ctx.nodeState?.appendConnectionInvocation({
+        invocationId: ConnectionInvocationIdFactory.create(),
+        connectionNodeId: nodeId,
+        parentAgentNodeId: ctx.nodeId,
+        parentAgentActivationId: ctx.activationId,
+        status: "completed",
+        managedInput: this.summarizeLlmMessages(messages),
+        managedOutput: this.resultToJsonValue(response),
+        finishedAt: new Date().toISOString(),
+      });
+      return response;
+    } catch (error) {
+      throw await this.failTrackedNodeInvocation(error, nodeId, ctx, inputsByPort, this.summarizeLlmMessages(messages));
+    }
+  }
+
   private async markQueuedTools(
     plannedToolCalls: ReadonlyArray<PlannedToolCall>,
     ctx: NodeExecutionContext<AIAgent<any, any>>,
@@ -514,6 +625,20 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         execute: async (args) => await this.nodeBackedToolRuntime.execute(config, args),
       };
     }
+    if (this.isCallableToolConfig(config)) {
+      const inputSchema = config.getInputSchema();
+      if (inputSchema == null) {
+        throw new Error(
+          `AIAgent tool "${config.name}": callable tool is missing inputSchema (cannot build LangChain tool).`,
+        );
+      }
+      return {
+        defaultDescription: config.description ?? `Callable tool "${config.name}".`,
+        inputSchema,
+        execute: async (args) =>
+          await config.executeTool({ ...args, config: config as CallableToolConfig<ZodSchemaAny, ZodSchemaAny> }),
+      };
+    }
     const tool = this.nodeResolver.resolve(config.type) as Tool<ToolConfig, ZodSchemaAny, ZodSchemaAny>;
     if (tool.inputSchema == null) {
       throw new Error(`AIAgent tool "${config.name}": plugin tool "${String(config.type)}" is missing inputSchema.`);
@@ -537,6 +662,16 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     );
   }
 
+  /**
+   * Callable tools use {@link CallableToolConfig#toolKind} for cross-package / JSON round-trip safety.
+   */
+  private isCallableToolConfig(config: ToolConfig): config is CallableToolConfig<ZodSchemaAny, ZodSchemaAny> {
+    return (
+      config instanceof CallableToolConfig ||
+      (typeof config === "object" && config !== null && (config as { toolKind?: unknown }).toolKind === "callable")
+    );
+  }
+
   private resolveGuardrails(guardrails: AgentGuardrailConfig | undefined): ResolvedGuardrails {
     const maxTurns = guardrails?.maxTurns ?? AgentGuardrailDefaults.maxTurns;
     if (!Number.isInteger(maxTurns) || maxTurns < 1) {
@@ -548,4 +683,8 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       modelInvocationOptions: guardrails?.modelInvocationOptions,
     };
   }
+
+  private getAgentDisplayName(ctx: NodeExecutionContext<AIAgent<any, any>>): string {
+    return ctx.config.name ?? ctx.nodeId;
+  }
 }

package/src/nodes/AgentStructuredOutputRepairPromptFactory.ts

@@ -0,0 +1,61 @@
+import type { AgentMessageDto, ZodSchemaAny } from "@codemation/core";
+import { inject, injectable } from "@codemation/core";
+
+import { AIAgentExecutionHelpersFactory } from "./AIAgentExecutionHelpersFactory";
+
+@injectable()
+export class AgentStructuredOutputRepairPromptFactory {
+  private static readonly maxSchemaLength = 8000;
+  private static readonly maxInvalidContentLength = 4000;
+  private static readonly maxValidationErrorLength = 4000;
+
+  constructor(
+    @inject(AIAgentExecutionHelpersFactory)
+    private readonly executionHelpers: AIAgentExecutionHelpersFactory,
+  ) {}
+
+  create(
+    args: Readonly<{
+      schema: ZodSchemaAny;
+      invalidContent: string;
+      validationError: string;
+    }>,
+  ): ReadonlyArray<AgentMessageDto> {
+    return [
+      {
+        role: "system",
+        content:
+          "Return only JSON that matches the required schema exactly. Do not include markdown fences, commentary, or prose.",
+      },
+      {
+        role: "user",
+        content: JSON.stringify({
+          requiredSchema: this.truncate(
+            JSON.stringify(
+              this.executionHelpers.createJsonSchemaRecord(args.schema, {
+                schemaName: "agent_output",
+                requireObjectRoot: false,
+              }),
+            ),
+            AgentStructuredOutputRepairPromptFactory.maxSchemaLength,
+          ),
+          invalidModelOutput: this.truncate(
+            args.invalidContent,
+            AgentStructuredOutputRepairPromptFactory.maxInvalidContentLength,
+          ),
+          validationError: this.truncate(
+            args.validationError,
+            AgentStructuredOutputRepairPromptFactory.maxValidationErrorLength,
+          ),
+        }),
+      },
+    ];
+  }
+
+  private truncate(value: string, maxLength: number): string {
+    if (value.length <= maxLength) {
+      return value;
+    }
+    return `${value.slice(0, maxLength)}...(truncated)`;
+  }
+}

package/src/nodes/AgentStructuredOutputRunner.ts

@@ -0,0 +1,222 @@
+import type {
+  ChatModelConfig,
+  ChatModelStructuredOutputOptions,
+  LangChainChatModelLike,
+  LangChainStructuredOutputModelLike,
+  ZodSchemaAny,
+} from "@codemation/core";
+import { inject, injectable } from "@codemation/core";
+
+import { AIMessage, type BaseMessage } from "@langchain/core/messages";
+import { ZodError } from "zod";
+
+import { OpenAIStructuredOutputMethodFactory } from "../chatModels/OpenAIStructuredOutputMethodFactory";
+import { AgentMessageFactory } from "./AgentMessageFactory";
+import { AgentStructuredOutputRepairPromptFactory } from "./AgentStructuredOutputRepairPromptFactory";
+
+interface ParsedStructuredOutputSuccess<TValue> {
+  readonly ok: true;
+  readonly value: TValue;
+}
+
+interface ParsedStructuredOutputFailure {
+  readonly ok: false;
+  readonly invalidContent: string;
+  readonly validationError: string;
+}
+
+type ParsedStructuredOutputResult<TValue> = ParsedStructuredOutputSuccess<TValue> | ParsedStructuredOutputFailure;
+
+@injectable()
+export class AgentStructuredOutputRunner {
+  private static readonly repairAttemptCount = 2;
+
+  constructor(
+    @inject(AgentStructuredOutputRepairPromptFactory)
+    private readonly repairPromptFactory: AgentStructuredOutputRepairPromptFactory,
+    @inject(OpenAIStructuredOutputMethodFactory)
+    private readonly openAiStructuredOutputMethodFactory: OpenAIStructuredOutputMethodFactory,
+  ) {}
+
+  async resolve<TOutput>(
+    args: Readonly<{
+      model: LangChainChatModelLike;
+      chatModelConfig: ChatModelConfig;
+      schema: ZodSchemaAny;
+      conversation: ReadonlyArray<BaseMessage>;
+      rawFinalResponse?: AIMessage;
+      agentName: string;
+      nodeId: string;
+      invokeTextModel: (messages: ReadonlyArray<BaseMessage>) => Promise<AIMessage>;
+      invokeStructuredModel: (
+        model: LangChainStructuredOutputModelLike,
+        messages: ReadonlyArray<BaseMessage>,
+      ) => Promise<unknown>;
+    }>,
+  ): Promise<TOutput> {
+    let lastFailure: ParsedStructuredOutputFailure | undefined;
+
+    if (args.rawFinalResponse) {
+      const directResult = this.tryParseAndValidate<TOutput>(
+        AgentMessageFactory.extractContent(args.rawFinalResponse),
+        args.schema,
+      );
+      if (directResult.ok) {
+        return directResult.value;
+      }
+      lastFailure = directResult;
+    } else if (!this.supportsNativeStructuredOutput(args.model)) {
+      const rawResponse = await args.invokeTextModel(args.conversation);
+      const directResult = this.tryParseAndValidate<TOutput>(
+        AgentMessageFactory.extractContent(rawResponse),
+        args.schema,
+      );
+      if (directResult.ok) {
+        return directResult.value;
+      }
+      lastFailure = directResult;
+    }
+
+    try {
+      const nativeStructuredModel = this.createStructuredOutputModel(args.model, args.chatModelConfig, args.schema);
+      if (nativeStructuredModel) {
+        const nativeResult = this.tryValidateStructuredValue<TOutput>(
+          await args.invokeStructuredModel(nativeStructuredModel, args.conversation),
+          args.schema,
+        );
+        if (nativeResult.ok) {
+          return nativeResult.value;
+        }
+        lastFailure = nativeResult;
+      }
+    } catch (error) {
+      lastFailure = {
+        ok: false,
+        invalidContent: "",
+        validationError: `Native structured output failed: ${this.summarizeError(error)}`,
+      };
+    }
+
+    return await this.retryWithRepairPrompt<TOutput>({
+      ...args,
+      lastFailure:
+        lastFailure ??
+        ({
+          ok: false,
+          invalidContent: "",
+          validationError: "Structured output was required but no valid structured response was produced.",
+        } satisfies ParsedStructuredOutputFailure),
+    });
+  }
+
+  private async retryWithRepairPrompt<TOutput>(
+    args: Readonly<{
+      schema: ZodSchemaAny;
+      conversation: ReadonlyArray<BaseMessage>;
+      lastFailure: ParsedStructuredOutputFailure;
+      agentName: string;
+      nodeId: string;
+      invokeTextModel: (messages: ReadonlyArray<BaseMessage>) => Promise<AIMessage>;
+    }>,
+  ): Promise<TOutput> {
+    let failure = args.lastFailure;
+    for (let attempt = 1; attempt <= AgentStructuredOutputRunner.repairAttemptCount; attempt++) {
+      const repairMessages = [
+        ...args.conversation,
+        ...AgentMessageFactory.createPromptMessages(
+          this.repairPromptFactory.create({
+            schema: args.schema,
+            invalidContent: failure.invalidContent,
+            validationError: failure.validationError,
+          }),
+        ),
+      ];
+      const repairResponse = await args.invokeTextModel(repairMessages);
+      const repairResult = this.tryParseAndValidate<TOutput>(
+        AgentMessageFactory.extractContent(repairResponse),
+        args.schema,
+      );
+      if (repairResult.ok) {
+        return repairResult.value;
+      }
+      failure = repairResult;
+    }
+    throw new Error(
+      `Structured output required for AIAgent "${args.agentName}" (${args.nodeId}) but validation still failed after ${AgentStructuredOutputRunner.repairAttemptCount} repair attempts: ${failure.validationError}`,
+    );
+  }
+
+  private createStructuredOutputModel(
+    model: LangChainChatModelLike,
+    chatModelConfig: ChatModelConfig,
+    schema: ZodSchemaAny,
+  ): LangChainStructuredOutputModelLike | undefined {
+    if (!this.supportsNativeStructuredOutput(model)) {
+      return undefined;
+    }
+    const options = this.getStructuredOutputOptions(chatModelConfig);
+    return model.withStructuredOutput(schema, options);
+  }
+
+  private getStructuredOutputOptions(chatModelConfig: ChatModelConfig): ChatModelStructuredOutputOptions | undefined {
+    return this.openAiStructuredOutputMethodFactory.create(chatModelConfig) ?? { strict: true };
+  }
+
+  private supportsNativeStructuredOutput(model: LangChainChatModelLike): model is LangChainChatModelLike & {
+    withStructuredOutput: (
+      outputSchema: ZodSchemaAny,
+      config?: ChatModelStructuredOutputOptions,
+    ) => LangChainStructuredOutputModelLike;
+  } {
+    return typeof model.withStructuredOutput === "function";
+  }
+
+  private tryParseAndValidate<TOutput>(content: string, schema: ZodSchemaAny): ParsedStructuredOutputResult<TOutput> {
+    try {
+      return this.tryValidateStructuredValue<TOutput>(JSON.parse(content) as unknown, schema, content);
+    } catch (error) {
+      return {
+        ok: false,
+        invalidContent: content,
+        validationError: `Response was not valid JSON: ${this.summarizeError(error)}`,
+      };
+    }
+  }
+
+  private tryValidateStructuredValue<TOutput>(
+    value: unknown,
+    schema: ZodSchemaAny,
+    invalidContent?: string,
+  ): ParsedStructuredOutputResult<TOutput> {
+    try {
+      return {
+        ok: true,
+        value: schema.parse(value) as TOutput,
+      };
+    } catch (error) {
+      return {
+        ok: false,
+        invalidContent: invalidContent ?? this.toJson(value),
+        validationError: this.summarizeError(error),
+      };
+    }
+  }
+
+  private summarizeError(error: unknown): string {
+    if (error instanceof ZodError) {
+      return error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
+    }
+    if (error instanceof Error) {
+      return error.message;
+    }
+    return String(error);
+  }
+
+  private toJson(value: unknown): string {
+    try {
+      return JSON.stringify(value);
+    } catch (error) {
+      return `<<unserializable: ${this.summarizeError(error)}>>`;
+    }
+  }
+}