@codemation/core-nodes 0.4.2 → 1.0.0

package/src/nodes/AgentMessageFactory.ts

@@ -1,69 +1,77 @@
 import type { AgentMessageDto, AgentToolCall } from "@codemation/core";
 
-import { AIMessage, HumanMessage, SystemMessage, ToolMessage, type BaseMessage } from "@langchain/core/messages";
+import type { AssistantModelMessage, ModelMessage, ToolModelMessage } from "ai";
 
+import type { ExecutedToolCall } from "./aiAgentSupport.types";
+
+/**
+ * AI-SDK-shaped message construction for the AIAgent stack. Emits plain `ModelMessage[]`
+ * ( `{ role: 'system' | 'user' | 'assistant' | 'tool', content: ... }` ) as consumed by
+ * `generateText({ messages })` from the `ai` package.
+ */
 export class AgentMessageFactory {
-  static createPromptMessages(messages: ReadonlyArray<AgentMessageDto>): ReadonlyArray<BaseMessage> {
+  static createPromptMessages(messages: ReadonlyArray<AgentMessageDto>): ReadonlyArray<ModelMessage> {
     return messages.map((message) => this.createPromptMessage(message));
   }
 
-  static createSystemPrompt(systemMessage: string): SystemMessage {
-    return new SystemMessage(systemMessage);
-  }
-
-  static createUserPrompt(prompt: string): HumanMessage {
-    return new HumanMessage(prompt);
-  }
-
-  static createAssistantPrompt(prompt: string): AIMessage {
-    return new AIMessage(prompt);
-  }
-
-  static createToolMessage(toolCallId: string, content: string): ToolMessage {
-    return new ToolMessage({ tool_call_id: toolCallId, content });
-  }
-
-  static extractContent(message: unknown): string {
-    if (typeof message === "string") return message;
-    if (!this.isRecord(message)) return String(message);
-    const content = message.content;
-    if (typeof content === "string") return content;
-    if (Array.isArray(content)) {
-      return content
-        .map((part) => {
-          if (typeof part === "string") return part;
-          if (this.isRecord(part) && typeof part.text === "string") return part.text;
-          return JSON.stringify(part);
-        })
-        .join("\n");
+  /**
+   * Builds the assistant message that contains optional text plus one or more tool-call parts,
+   * matching the shape AI SDK emits between steps.
+   */
+  static createAssistantWithToolCalls(
+    text: string | undefined,
+    toolCalls: ReadonlyArray<AgentToolCall>,
+  ): AssistantModelMessage {
+    const content: AssistantModelMessage["content"] = [];
+    if (text && text.length > 0) {
+      content.push({ type: "text", text });
     }
-    return JSON.stringify(content);
+    for (const toolCall of toolCalls) {
+      content.push({
+        type: "tool-call",
+        toolCallId: toolCall.id ?? toolCall.name,
+        toolName: toolCall.name,
+        input: toolCall.input ?? {},
+      });
+    }
+    return { role: "assistant", content };
   }
 
-  static extractToolCalls(message: unknown): ReadonlyArray<AgentToolCall> {
-    if (!this.isRecord(message)) return [];
-    const toolCalls = message.tool_calls;
-    if (!Array.isArray(toolCalls)) return [];
-    return toolCalls
-      .filter((toolCall) => this.isRecord(toolCall) && typeof toolCall.name === "string")
-      .map((toolCall) => ({
-        id: typeof toolCall.id === "string" ? toolCall.id : undefined,
-        name: toolCall.name as string,
-        input: this.isRecord(toolCall) && "args" in toolCall ? toolCall.args : undefined,
-      }));
+  /**
+   * Builds the `{ role: "tool", content: [{ type: "tool-result", ... }, ...] }` message returned
+   * to the model after each tool round.
+   */
+  static createToolResultsMessage(executedToolCalls: ReadonlyArray<ExecutedToolCall>): ToolModelMessage {
+    return {
+      role: "tool",
+      content: executedToolCalls.map((executed) => ({
+        type: "tool-result",
+        toolCallId: executed.toolCallId,
+        toolName: executed.toolName,
+        output: {
+          type: "json",
+          value: AgentMessageFactory.toToolResultJson(executed.result),
+        },
+      })),
+    };
   }
 
-  private static isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === "object" && value !== null;
+  private static toToolResultJson(value: unknown): import("ai").JSONValue {
+    if (value === undefined) return null;
+    try {
+      return JSON.parse(JSON.stringify(value)) as import("ai").JSONValue;
+    } catch {
+      return String(value);
+    }
   }
 
-  private static createPromptMessage(message: AgentMessageDto): BaseMessage {
+  private static createPromptMessage(message: AgentMessageDto): ModelMessage {
     if (message.role === "system") {
-      return this.createSystemPrompt(message.content);
+      return { role: "system", content: message.content };
     }
     if (message.role === "assistant") {
-      return this.createAssistantPrompt(message.content);
+      return { role: "assistant", content: message.content };
     }
-    return this.createUserPrompt(message.content);
+    return { role: "user", content: message.content };
   }
 }

package/src/nodes/AgentStructuredOutputRunner.ts

@@ -1,18 +1,13 @@
-import type {
-  ChatModelConfig,
-  ChatModelStructuredOutputOptions,
-  LangChainChatModelLike,
-  LangChainStructuredOutputModelLike,
-  ZodSchemaAny,
-} from "@codemation/core";
+import type { ChatLanguageModel, ChatModelConfig, StructuredOutputOptions, ZodSchemaAny } from "@codemation/core";
 import { inject, injectable } from "@codemation/core";
 
-import { AIMessage, type BaseMessage } from "@langchain/core/messages";
+import type { ModelMessage } from "ai";
 import { ZodError } from "zod";
 
-import { OpenAIStructuredOutputMethodFactory } from "../chatModels/OpenAIStructuredOutputMethodFactory";
-import { AgentMessageFactory } from "./AgentMessageFactory";
+import { OpenAIChatModelFactory } from "../chatModels/OpenAIChatModelFactory";
+import { OpenAiStrictJsonSchemaFactory } from "../chatModels/OpenAiStrictJsonSchemaFactory";
 import { AgentStructuredOutputRepairPromptFactory } from "./AgentStructuredOutputRepairPromptFactory";
+import { AgentMessageFactory } from "./AgentMessageFactory";
 
 interface ParsedStructuredOutputSuccess<TValue> {
   readonly ok: true;
@@ -27,50 +22,54 @@ interface ParsedStructuredOutputFailure {
 
 type ParsedStructuredOutputResult<TValue> = ParsedStructuredOutputSuccess<TValue> | ParsedStructuredOutputFailure;
 
+export type StructuredOutputSchemaForModel = ZodSchemaAny | Readonly<Record<string, unknown>>;
+
+/**
+ * Orchestrates a 2-attempt repair loop on top of `generateText({ output: Output.object(...) })`.
+ *
+ * Strategy:
+ * 1. If the caller already has a raw final text (from a prior tool-calling turn), try parsing it
+ *    directly against the schema — fast path for models that already emit strict JSON.
+ * 2. Otherwise, run a native structured-output call via {@link invokeStructuredModel}. For the
+ *    OpenAI-strict path, a {@link OpenAiStrictJsonSchemaFactory}-built JSON Schema record is
+ *    handed to AI SDK's `jsonSchema(...)` wrapper (preserves `additionalProperties: false` at
+ *    every object depth).
+ * 3. If the structured call fails (AI_NoObjectGeneratedError / ZodError / schema reject), run a
+ *    text-mode repair prompt with the validation error appended, up to 2 attempts.
+ */
 @injectable()
 export class AgentStructuredOutputRunner {
   private static readonly repairAttemptCount = 2;
+  private static readonly structuredOutputSchemaName = "agent_output";
 
   constructor(
     @inject(AgentStructuredOutputRepairPromptFactory)
     private readonly repairPromptFactory: AgentStructuredOutputRepairPromptFactory,
-    @inject(OpenAIStructuredOutputMethodFactory)
-    private readonly openAiStructuredOutputMethodFactory: OpenAIStructuredOutputMethodFactory,
+    @inject(OpenAiStrictJsonSchemaFactory)
+    private readonly openAiStrictJsonSchemaFactory: OpenAiStrictJsonSchemaFactory,
   ) {}
 
   async resolve<TOutput>(
     args: Readonly<{
-      model: LangChainChatModelLike;
+      model: ChatLanguageModel;
       chatModelConfig: ChatModelConfig;
       schema: ZodSchemaAny;
-      conversation: ReadonlyArray<BaseMessage>;
-      rawFinalResponse?: AIMessage;
+      conversation: ReadonlyArray<ModelMessage>;
+      rawFinalText?: string;
       agentName: string;
       nodeId: string;
-      invokeTextModel: (messages: ReadonlyArray<BaseMessage>) => Promise<AIMessage>;
+      invokeTextModel: (messages: ReadonlyArray<ModelMessage>) => Promise<{ text: string }>;
       invokeStructuredModel: (
-        model: LangChainStructuredOutputModelLike,
-        messages: ReadonlyArray<BaseMessage>,
+        schema: StructuredOutputSchemaForModel,
+        messages: ReadonlyArray<ModelMessage>,
+        options: StructuredOutputOptions | undefined,
       ) => 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 (args.rawFinalText !== undefined) {
+      const directResult = this.tryParseAndValidate<TOutput>(args.rawFinalText, args.schema);
       if (directResult.ok) {
         return directResult.value;
       }
@@ -78,19 +77,18 @@ export class AgentStructuredOutputRunner {
     }
 
     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;
+      const structuredOptions = this.resolveStructuredOutputOptions(args.chatModelConfig);
+      const schemaForModel = this.resolveOutputSchemaForModel(args.schema, structuredOptions);
+      const nativeResult = this.tryValidateStructuredValue<TOutput>(
+        await args.invokeStructuredModel(schemaForModel, args.conversation, structuredOptions),
+        args.schema,
+      );
+      if (nativeResult.ok) {
+        return nativeResult.value;
       }
+      lastFailure = nativeResult;
     } catch (error) {
-      lastFailure = {
+      lastFailure = lastFailure ?? {
         ok: false,
         invalidContent: "",
         validationError: `Native structured output failed: ${this.summarizeError(error)}`,
@@ -112,16 +110,16 @@ export class AgentStructuredOutputRunner {
   private async retryWithRepairPrompt<TOutput>(
     args: Readonly<{
       schema: ZodSchemaAny;
-      conversation: ReadonlyArray<BaseMessage>;
+      conversation: ReadonlyArray<ModelMessage>;
       lastFailure: ParsedStructuredOutputFailure;
       agentName: string;
       nodeId: string;
-      invokeTextModel: (messages: ReadonlyArray<BaseMessage>) => Promise<AIMessage>;
+      invokeTextModel: (messages: ReadonlyArray<ModelMessage>) => Promise<{ text: string }>;
     }>,
   ): Promise<TOutput> {
     let failure = args.lastFailure;
     for (let attempt = 1; attempt <= AgentStructuredOutputRunner.repairAttemptCount; attempt++) {
-      const repairMessages = [
+      const repairMessages: ReadonlyArray<ModelMessage> = [
         ...args.conversation,
         ...AgentMessageFactory.createPromptMessages(
           this.repairPromptFactory.create({
@@ -132,10 +130,7 @@ export class AgentStructuredOutputRunner {
         ),
       ];
       const repairResponse = await args.invokeTextModel(repairMessages);
-      const repairResult = this.tryParseAndValidate<TOutput>(
-        AgentMessageFactory.extractContent(repairResponse),
-        args.schema,
-      );
+      const repairResult = this.tryParseAndValidate<TOutput>(repairResponse.text, args.schema);
       if (repairResult.ok) {
         return repairResult.value;
       }
@@ -146,29 +141,27 @@ export class AgentStructuredOutputRunner {
     );
   }
 
-  private createStructuredOutputModel(
-    model: LangChainChatModelLike,
-    chatModelConfig: ChatModelConfig,
-    schema: ZodSchemaAny,
-  ): LangChainStructuredOutputModelLike | undefined {
-    if (!this.supportsNativeStructuredOutput(model)) {
+  /**
+   * Chooses strict mode for OpenAI chat-model configs, off otherwise.  Extendable in future for
+   * other providers that adopt the same "supply a JSON Schema record directly" contract.
+   */
+  private resolveStructuredOutputOptions(chatModelConfig: ChatModelConfig): StructuredOutputOptions | undefined {
+    if (chatModelConfig.type !== OpenAIChatModelFactory) {
       return undefined;
     }
-    const options = this.getStructuredOutputOptions(chatModelConfig);
-    return model.withStructuredOutput(schema, options);
+    return { strict: true, schemaName: AgentStructuredOutputRunner.structuredOutputSchemaName };
   }
 
-  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 resolveOutputSchemaForModel(
+    schema: ZodSchemaAny,
+    options: StructuredOutputOptions | undefined,
+  ): StructuredOutputSchemaForModel {
+    if (!options?.strict) {
+      return schema;
+    }
+    return this.openAiStrictJsonSchemaFactory.createStructuredOutputRecord(schema, {
+      schemaName: options.schemaName ?? AgentStructuredOutputRunner.structuredOutputSchemaName,
+    });
   }
 
   private tryParseAndValidate<TOutput>(content: string, schema: ZodSchemaAny): ParsedStructuredOutputResult<TOutput> {
@@ -214,7 +207,8 @@ export class AgentStructuredOutputRunner {
 
   private toJson(value: unknown): string {
     try {
-      return JSON.stringify(value);
+      const serialized = JSON.stringify(value);
+      return serialized ?? String(value);
     } catch (error) {
       return `<<unserializable: ${this.summarizeError(error)}>>`;
     }

package/src/nodes/AgentToolExecutionCoordinator.ts

@@ -71,8 +71,8 @@ export class AgentToolExecutionCoordinator {
     });
 
     try {
-      const serialized = await plannedToolCall.binding.langChainTool.invoke(plannedToolCall.toolCall.input ?? {});
-      const result = this.parseToolOutput(serialized);
+      const result = await plannedToolCall.binding.execute(plannedToolCall.toolCall.input ?? {});
+      const serialized = typeof result === "string" ? result : JSON.stringify(result);
       const finishedAt = new Date();
       await ctx.nodeState?.markCompleted({
         nodeId: plannedToolCall.nodeId,
@@ -113,7 +113,7 @@ export class AgentToolExecutionCoordinator {
       const classification = this.errorClassifier.classify({
         error,
         toolName: plannedToolCall.binding.config.name,
-        schema: plannedToolCall.binding.langChainTool.schema,
+        schema: plannedToolCall.binding.inputSchema,
       });
 
       if (classification.kind !== "repairable_validation_error") {
@@ -324,17 +324,6 @@ export class AgentToolExecutionCoordinator {
     return `Your previous tool call for "${toolName}" was invalid because field "${fieldPath}" failed validation: ${firstIssue.message}`;
   }
 
-  private parseToolOutput(serialized: unknown): unknown {
-    if (typeof serialized !== "string") {
-      return serialized;
-    }
-    try {
-      return JSON.parse(serialized) as unknown;
-    } catch {
-      return serialized;
-    }
-  }
-
   private toJsonValue(value: unknown): JsonValue | undefined {
     if (value === undefined) {
       return undefined;

package/src/nodes/aiAgentSupport.types.ts

@@ -6,7 +6,6 @@ import type {
   ToolExecuteArgs,
   ZodSchemaAny,
 } from "@codemation/core";
-import type { DynamicStructuredTool } from "@langchain/core/tools";
 
 export class AgentItemPortMap {
   static fromItem(item: Item): NodeInputsByPort {
@@ -23,9 +22,15 @@ export type ResolvedTool = Readonly<{
   }>;
 }>;
 
+/**
+ * Per-item binding of a tool: the user config plus the resolved runtime and a snapshot of the
+ * original Zod `inputSchema` used to convert to AI SDK `Tool` + OpenAI-strict JSON Schema for
+ * repair prompts.
+ */
 export type ItemScopedToolBinding = Readonly<{
   config: ToolConfig;
-  langChainTool: DynamicStructuredTool;
+  inputSchema: ZodSchemaAny;
+  execute(input: unknown): Promise<unknown>;
 }>;
 
 export type PlannedToolCall = Readonly<{

package/src/chatModels/OpenAIStructuredOutputMethodFactory.ts

@@ -1,46 +0,0 @@
-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;
-  }
-}