@codemation/core-nodes 0.10.2 → 0.13.0

package/dist/metadata.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "packageName": "@codemation/core-nodes",
-  "packageVersion": "0.10.2",
+  "packageVersion": "0.13.0",
   "description": "",
   "kind": "nodes",
   "nodes": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core-nodes",
-  "version": "0.10.2",
+  "version": "0.13.0",
   "publishConfig": {
     "access": "public"
   },
@@ -28,11 +28,12 @@
     }
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.85",
     "@ai-sdk/openai": "^3.0.53",
     "@ai-sdk/provider": "^3.0.8",
     "ai": "^6.0.168",
     "croner": "^10.0.1",
-    "@codemation/core": "0.13.2"
+    "@codemation/core": "0.14.0"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",

package/src/chatModels/CodemationChatModelConfig.ts

@@ -4,25 +4,14 @@ import type { CanvasIconName } from "../canvasIconName";
 import { CodemationChatModelFactory } from "./CodemationChatModelFactory";
 
 /**
- * A platform-managed model entry as returned by GET /api/llm/managed-models.
+ * Complexity token sent to the managed LLM broker.
+ * The broker maps this to a concrete provider model and thinking effort.
+ * low    = cheapest/fastest (short classification, simple extraction)
+ * medium = default for most extraction/agent work
+ * high   = complex multi-step reasoning
+ * xhigh  = hardest problems, most capable model
  */
-export interface ManagedModelDto {
-  id: string;
-  modelId: string;
-  displayName: string;
-  providerKey: string;
-  inputCostPerMTok: number;
-  outputCostPerMTok: number;
-  contextWindow: number;
-  tier: string;
-}
-
-/**
- * Bifrost-namespaced model ID. Kept as `string` so runtime-fetched model IDs
- * (from the CP allowlist) work without compile-time enumeration.
- * Story C replaced the prior hardcoded union with this open type.
- */
-export type CodemationManagedModel = string;
+export type ManagedComplexity = "low" | "medium" | "high" | "xhigh";
 
 export class CodemationChatModelConfig implements ChatModelConfig {
   readonly type = CodemationChatModelFactory;
@@ -32,14 +21,13 @@ export class CodemationChatModelConfig implements ChatModelConfig {
 
   constructor(
     public readonly name: string,
-    public readonly model: CodemationManagedModel,
+    public readonly complexity: ManagedComplexity,
     presentationIn?: AgentCanvasPresentation<CanvasIconName>,
     public readonly options?: Readonly<{
-      temperature?: number;
       maxTokens?: number;
     }>,
   ) {
-    this.modelName = model;
+    this.modelName = complexity;
     this.presentation = presentationIn ?? { icon: "lucide:bot", label: name };
   }
 

package/src/chatModels/CodemationChatModelFactory.ts

@@ -1,14 +1,12 @@
 import type { ChatLanguageModel, ChatModelFactory, NodeExecutionContext } from "@codemation/core";
 import { chatModel } from "@codemation/core";
 
-import { createOpenAI } from "@ai-sdk/openai";
-
 import type { CodemationChatModelConfig } from "./CodemationChatModelConfig";
 import { managedHmacFetchFactory } from "./ManagedHmacSignerFactory.types";
 
 @chatModel({ packageName: "@codemation/core-nodes" })
 export class CodemationChatModelFactory implements ChatModelFactory<CodemationChatModelConfig> {
-  create(
+  async create(
     args: Readonly<{ config: CodemationChatModelConfig; ctx: NodeExecutionContext<any> }>,
   ): Promise<ChatLanguageModel> {
     // D5: read at session-create time so unpairing or misconfiguration surfaces at workflow run, not boot.
@@ -27,18 +25,23 @@ export class CodemationChatModelFactory implements ChatModelFactory<CodemationCh
     }
 
     const hmacFetch = managedHmacFetchFactory(workspaceId, pairingSecret);
+    // Lazy import: pulls @ai-sdk/anthropic + the `ai` SDK (~28MB RSS) only when a
+    // chat model is actually built. Non-AI workflows never load it.
+    // Using the Anthropic-native route so the broker's injected `thinking` /
+    // `output_config.effort` fields survive (they are stripped by the OpenAI-compat route).
+    const { createAnthropic } = await import("@ai-sdk/anthropic");
     // apiKey is required by the AI SDK but unused — authentication is handled by the HMAC-signed fetch wrapper.
-    const provider = createOpenAI({ baseURL: `${gatewayUrl}/v1`, apiKey: "codemation-managed", fetch: hmacFetch });
-    const languageModel = provider.chat(args.config.model);
+    // baseURL: the SDK appends /messages → hits the broker's /v1/messages Anthropic-native route.
+    const provider = createAnthropic({ baseURL: `${gatewayUrl}/v1`, apiKey: "codemation-managed", fetch: hmacFetch });
+    const languageModel = provider(args.config.complexity);
 
-    return Promise.resolve({
+    return {
       languageModel,
-      modelName: args.config.model,
+      modelName: args.config.complexity,
       provider: "codemation-managed",
       defaultCallOptions: {
         maxOutputTokens: args.config.options?.maxTokens,
-        temperature: args.config.options?.temperature,
       },
-    });
+    };
   }
 }

package/src/chatModels/OpenAIChatModelFactory.ts

@@ -1,8 +1,6 @@
 import type { ChatLanguageModel, ChatModelFactory, NodeExecutionContext } from "@codemation/core";
 import { chatModel } from "@codemation/core";
 
-import { createOpenAI } from "@ai-sdk/openai";
-
 import type { OpenAiCredentialSession } from "./OpenAiCredentialSession";
 import type { OpenAIChatModelConfig } from "./openAiChatModelConfig";
 
@@ -12,6 +10,9 @@ export class OpenAIChatModelFactory implements ChatModelFactory<OpenAIChatModelC
     args: Readonly<{ config: OpenAIChatModelConfig; ctx: NodeExecutionContext<any> }>,
   ): Promise<ChatLanguageModel> {
     const session = await args.ctx.getCredential<OpenAiCredentialSession>(args.config.credentialSlotKey);
+    // Lazy import: pulls @ai-sdk/openai + the `ai` SDK (~28MB RSS) only when a
+    // chat model is actually built. Non-AI workflows never load it.
+    const { createOpenAI } = await import("@ai-sdk/openai");
     const provider = createOpenAI({
       apiKey: session.apiKey,
       baseURL: session.baseUrl,

package/src/index.ts

@@ -10,7 +10,6 @@ export * from "./chatModels/openAiChatModelConfig";
 export * from "./chatModels/OpenAiChatModelPresetsFactory";
 export * from "./chatModels/CodemationChatModelFactory";
 export * from "./chatModels/CodemationChatModelConfig";
-export * from "./chatModels/ManagedModelFetcher";
 export * from "./nodes/aiAgent";
 export * from "./nodes/assertion";
 export * from "./nodes/CallbackNodeFactory";
@@ -26,6 +25,7 @@ export * from "./nodes/CronTriggerNode";
 export * from "./nodes/ManualTriggerFactory";
 export * from "./nodes/mapData";
 export * from "./nodes/merge";
+export * from "./nodes/nodeOptions.types";
 export * from "./nodes/noOp";
 export * from "./nodes/subWorkflow";
 export * from "./nodes/testTrigger";

package/src/nodes/AIAgentConfig.ts

@@ -1,8 +1,10 @@
 import {
   RetryPolicy,
   type AgentGuardrailConfig,
+  type AgentMessageBuildArgs,
   type AgentMessageConfig,
   type AgentNodeConfig,
+  type BinaryAttachment,
   type ChatModelConfig,
   type NodeInspectorSummaryRow,
   type RetryPolicySpec,
@@ -20,6 +22,7 @@ export interface AIAgentOptions<TInputJson = unknown, _TOutputJson = unknown> {
   readonly chatModel: ChatModelConfig;
   readonly tools?: ReadonlyArray<ToolConfig>;
   readonly id?: string;
+  readonly description?: string;
   readonly retryPolicy?: RetryPolicySpec;
   readonly guardrails?: AgentGuardrailConfig;
   /** Engine applies with {@link RunnableNodeConfig.inputSchema} before {@link AIAgentNode.execute}. */
@@ -49,6 +52,29 @@ export interface AIAgentOptions<TInputJson = unknown, _TOutputJson = unknown> {
    * Defaults to `["gmail", "ocr", "webhook"]` when unset.
    */
   readonly untrustedSources?: ReadonlyArray<string>;
+  /**
+   * Whether file binaries are automatically passed to the chat model as native inline
+   * multimodal blocks. Defaults to `true`. Set to `false` to skip the binary-passdown step
+   * entirely (the node then behaves as if no binaries were present).
+   */
+  readonly passBinariesToModel?: boolean;
+  /**
+   * Whether binaries returned by a tool (e.g. an MCP tool returning a PDF or image) are passed to
+   * the chat model as native multimodal tool-result blocks. Defaults to `true`. Set to `false` to
+   * keep tool results as inert JSON text (the model then never "sees" the document).
+   */
+  readonly passToolBinariesToModel?: boolean;
+  /**
+   * Explicit binaries to pass to the chat model, instead of the ones on the current item.
+   * Either a static array or a function resolved per item (so an author can forward binaries
+   * produced by an earlier node further back in the workflow). When provided, these replace
+   * `item.binary` as the passdown source. Ignored when {@link passBinariesToModel} is `false`.
+   * Every binary is passed (images as image blocks, all other types as file blocks); the
+   * provider surfaces an error at runtime if it doesn't support a given file type.
+   */
+  readonly binaries?:
+    | ReadonlyArray<BinaryAttachment>
+    | ((args: AgentMessageBuildArgs<TInputJson>) => ReadonlyArray<BinaryAttachment>);
 }
 
 /**
@@ -67,6 +93,7 @@ export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
   readonly chatModel: ChatModelConfig;
   readonly tools: ReadonlyArray<ToolConfig>;
   readonly id?: string;
+  readonly description?: string;
   readonly retryPolicy: RetryPolicySpec;
   readonly guardrails?: AgentGuardrailConfig;
   readonly inputSchema?: ZodType<TInputJson>;
@@ -74,6 +101,11 @@ export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
   readonly mcpServers?: ReadonlyArray<string>;
   readonly pinnedMcpTools?: readonly string[];
   readonly untrustedSources?: ReadonlyArray<string>;
+  readonly passBinariesToModel?: boolean;
+  readonly passToolBinariesToModel?: boolean;
+  readonly binaries?:
+    | ReadonlyArray<BinaryAttachment>
+    | ((args: AgentMessageBuildArgs<TInputJson>) => ReadonlyArray<BinaryAttachment>);
 
   constructor(options: AIAgentOptions<TInputJson, TOutputJson>) {
     this.name = options.name;
@@ -81,6 +113,7 @@ export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
     this.chatModel = options.chatModel;
     this.tools = options.tools ?? [];
     this.id = options.id;
+    this.description = options.description;
     this.retryPolicy = options.retryPolicy ?? RetryPolicy.defaultForAiAgent;
     this.guardrails = options.guardrails;
     this.inputSchema = options.inputSchema;
@@ -88,6 +121,9 @@ export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
     this.mcpServers = options.mcpServers;
     this.pinnedMcpTools = options.pinnedMcpTools;
     this.untrustedSources = options.untrustedSources;
+    this.passBinariesToModel = options.passBinariesToModel;
+    this.passToolBinariesToModel = options.passToolBinariesToModel;
+    this.binaries = options.binaries;
   }
 
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> {

package/src/nodes/AIAgentNode.ts

@@ -2,6 +2,7 @@ import type {
   AgentGuardrailConfig,
   AgentMessageDto,
   AgentToolCall,
+  BinaryAttachment,
   ChatLanguageModel,
   ChatLanguageModelCallOptions,
   ChatModelConfig,
@@ -36,7 +37,6 @@ import {
 } from "@codemation/core";
 
 import type { AssistantModelMessage, GenerateTextResult, LanguageModel, ModelMessage, ToolSet } from "ai";
-import { Output, generateText, jsonSchema } from "ai";
 
 /**
  * OUTPUT generic must extend AI SDK's `Output<OUTPUT, PARTIAL, ELEMENT>` which is parametric on
@@ -52,6 +52,7 @@ import { AIAgentExecutionHelpersFactory } from "./AIAgentExecutionHelpersFactory
 import { AgentToolExecutionCoordinator } from "./AgentToolExecutionCoordinator";
 import { ConnectionCredentialExecutionContextFactory } from "./ConnectionCredentialExecutionContextFactory";
 import { AgentMessageFactory } from "./AgentMessageFactory";
+import { AgentBinaryContentFactory, type ResolvedAgentBinary } from "./AgentBinaryContentFactory";
 import { AgentOutputFactory } from "./AgentOutputFactory";
 import { AgentStructuredOutputRunner } from "./AgentStructuredOutputRunner";
 import { AgentToolCallPortMap } from "./AgentToolCallPortMapFactory";
@@ -110,6 +111,13 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     NodeExecutionContext<AIAgent<any, any>>,
     Promise<PreparedAgentExecution>
   >();
+  /**
+   * The `ai` SDK, loaded lazily in {@link execute} so the SDK (~28MB RSS) stays
+   * off the boot path — non-AI workflows never load it. Every path runs through
+   * `execute` → `ensureAiSdk` before any sync helper touches `this.aiSdk`.
+   */
+  private aiSdk!: typeof import("ai");
+  private aiSdkPromise: Promise<typeof import("ai")> | null = null;
 
   constructor(
     @inject(CoreTokens.NodeResolver)
@@ -135,6 +143,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
 
   async execute(args: RunnableNodeExecuteArgs<AIAgent<any, any>>): Promise<unknown> {
     const { ctx } = args;
+    await this.ensureAiSdk();
 
     // HITL resume branch (story 10): the engine re-activates us after a human decision.
     if (ctx.resumeContext) {
@@ -147,6 +156,11 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     return resultItem.json;
   }
 
+  /** Load the `ai` SDK once per node instance (cached promise guards concurrent items). */
+  private async ensureAiSdk(): Promise<void> {
+    this.aiSdk = await (this.aiSdkPromise ??= import("ai"));
+  }
+
   /**
    * Resume path: re-enters the agent loop after a HITL suspension.
    * Reconstructs the conversation from the checkpoint, injects the human decision
@@ -196,7 +210,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     };
     const conversation: ModelMessage[] = [
       ...checkpoint.conversation,
-      AgentMessageFactory.createToolResultsMessage([toolResultEntry]),
+      AgentMessageFactory.createToolResultsMessage([toolResultEntry], ctx.config.passToolBinariesToModel !== false),
     ];
 
     const loopResult = await this.runTurnLoopUntilFinalAnswer({
@@ -330,7 +344,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     const { ctx } = prepared;
     const itemInputsByPort = AgentItemPortMap.fromItem(item);
     const itemScopedTools = this.createItemScopedTools(prepared.resolvedTools, ctx, item, itemIndex, items);
-    const conversation: ModelMessage[] = [...this.createPromptMessages(item, itemIndex, items, ctx)];
+    const conversation: ModelMessage[] = [...(await this.createPromptMessages(item, itemIndex, items, ctx))];
     if (ctx.config.outputSchema && itemScopedTools.length === 0) {
       const structuredOutput = await this.structuredOutputRunner.resolve({
         model: prepared.model,
@@ -476,6 +490,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         result.text,
         result.toolCalls,
         allExecutedCalls,
+        ctx.config.passToolBinariesToModel !== false,
       );
     }
 
@@ -508,10 +523,11 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     text: string,
     toolCalls: ReadonlyArray<AgentToolCall>,
     executedToolCalls: ReadonlyArray<ExecutedToolCall>,
+    passToolBinariesToModel: boolean,
   ): void {
     conversation.push(
       assistantMessage ?? AgentMessageFactory.createAssistantWithToolCalls(text, toolCalls),
-      AgentMessageFactory.createToolResultsMessage(executedToolCalls),
+      AgentMessageFactory.createToolResultsMessage(executedToolCalls, passToolBinariesToModel),
     );
   }
 
@@ -653,7 +669,8 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
    */
   private buildToolSetFromResolved(resolvedTools: ReadonlyArray<ResolvedTool>): ToolSet {
     if (resolvedTools.length === 0) return {};
-    const toolSet: Record<string, { description?: string; inputSchema: ReturnType<typeof jsonSchema> }> = {};
+    const toolSet: Record<string, { description?: string; inputSchema: ReturnType<typeof import("ai").jsonSchema> }> =
+      {};
     for (const entry of resolvedTools) {
       const schemaRecord = this.executionHelpers.createJsonSchemaRecord(entry.runtime.inputSchema, {
         schemaName: entry.config.name,
@@ -664,7 +681,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       const description = isHitl ? `${baseDescription} ${HITL_SOLO_CONSTRAINT_SENTENCE}` : baseDescription;
       toolSet[entry.config.name] = {
         description,
-        inputSchema: jsonSchema(schemaRecord as Parameters<typeof jsonSchema>[0]),
+        inputSchema: this.aiSdk.jsonSchema(schemaRecord as Parameters<typeof import("ai").jsonSchema>[0]),
       };
     }
     return toolSet as unknown as ToolSet;
@@ -686,7 +703,8 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
    */
   private buildToolSet(itemScopedTools: ReadonlyArray<ItemScopedToolBinding>): ToolSet | undefined {
     if (itemScopedTools.length === 0) return undefined;
-    const toolSet: Record<string, { description?: string; inputSchema: ReturnType<typeof jsonSchema> }> = {};
+    const toolSet: Record<string, { description?: string; inputSchema: ReturnType<typeof import("ai").jsonSchema> }> =
+      {};
     for (const entry of itemScopedTools) {
       const schemaRecord = this.executionHelpers.createJsonSchemaRecord(entry.inputSchema, {
         schemaName: entry.config.name,
@@ -701,7 +719,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
             : baseDescription;
       toolSet[entry.config.name] = {
         description,
-        inputSchema: jsonSchema(schemaRecord as Parameters<typeof jsonSchema>[0]),
+        inputSchema: this.aiSdk.jsonSchema(schemaRecord as Parameters<typeof import("ai").jsonSchema>[0]),
       };
     }
     return toolSet as unknown as ToolSet;
@@ -759,7 +777,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     });
     try {
       const callOptions = this.resolveCallOptions(model, guardrails.modelInvocationOptions);
-      const result = await generateText({
+      const result = await this.aiSdk.generateText({
         model: model.languageModel as LanguageModel,
         messages: [...messages],
         tools,
@@ -881,10 +899,10 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
             requireObjectRoot: true,
           })
         : schema;
-      const outputSchema = Output.object({
-        schema: jsonSchema(schemaRecord as Parameters<typeof jsonSchema>[0]) as never,
+      const outputSchema = this.aiSdk.Output.object({
+        schema: this.aiSdk.jsonSchema(schemaRecord as Parameters<typeof import("ai").jsonSchema>[0]) as never,
       });
-      const result = await generateText({
+      const result = await this.aiSdk.generateText({
         model: model.languageModel as LanguageModel,
         messages: [...messages],
         experimental_output: outputSchema,
@@ -1207,12 +1225,12 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     return JSON.parse(json) as JsonValue;
   }
 
-  private createPromptMessages(
+  private async createPromptMessages(
     item: Item,
     itemIndex: number,
     items: Items,
     ctx: NodeExecutionContext<AIAgent<any, any>>,
-  ): ReadonlyArray<ModelMessage> {
+  ): Promise<ReadonlyArray<ModelMessage>> {
     const messages = AgentMessageConfigNormalizer.resolveFromInputOrConfig(item.json, ctx.config, {
       item,
       itemIndex,
@@ -1220,7 +1238,55 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       ctx,
     });
     const wrapped = this.wrapUntrustedSourceMessages(messages, item, ctx.config);
-    return AgentMessageFactory.createPromptMessages(wrapped);
+    const promptMessages = AgentMessageFactory.createPromptMessages(wrapped);
+    // Skip the passdown step entirely when the author opted out (default is on).
+    if (ctx.config.passBinariesToModel === false) return promptMessages;
+    const attachments = this.selectBinaryAttachments(item, itemIndex, items, ctx);
+    const binaries = await this.resolveInlineBinaries(attachments, ctx);
+    return AgentBinaryContentFactory.withBinaries(promptMessages, binaries);
+  }
+
+  /**
+   * Picks which attachments feed the passdown. When the author supplies `config.binaries`
+   * (a static array or a per-item function — e.g. to forward binaries from an earlier node),
+   * those replace the current item's attachments; otherwise the current item's `item.binary`
+   * is used.
+   */
+  private selectBinaryAttachments(
+    item: Item,
+    itemIndex: number,
+    items: Items,
+    ctx: NodeExecutionContext<AIAgent<any, any>>,
+  ): ReadonlyArray<BinaryAttachment> {
+    const manual = ctx.config.binaries;
+    if (manual !== undefined) {
+      return typeof manual === "function" ? manual({ item, itemIndex, items, ctx }) : manual;
+    }
+    return item.binary ? Object.values(item.binary) : [];
+  }
+
+  /**
+   * Reads every attachment through `ctx.binary` (storage-backed, by reference — never base64 on
+   * `item.json`) and resolves it to inline base64 so the agent can pass it to the chat model as a
+   * native multimodal block. Images become image blocks; every other type (PDF, office docs, CSV,
+   * JSON, …) becomes a file block — we don't filter by media type, so any binary can be fed to the
+   * model. If the provider rejects an unsupported type the error surfaces at runtime, and the
+   * workflow can filter the binary upstream.
+   */
+  private async resolveInlineBinaries(
+    attachments: ReadonlyArray<BinaryAttachment>,
+    ctx: NodeExecutionContext<AIAgent<any, any>>,
+  ): Promise<ReadonlyArray<ResolvedAgentBinary>> {
+    const resolved: ResolvedAgentBinary[] = [];
+    for (const attachment of attachments) {
+      const bytes = await ctx.binary.getBytes(attachment);
+      resolved.push({
+        mediaType: attachment.mimeType,
+        base64: Buffer.from(bytes).toString("base64"),
+        ...(attachment.filename ? { filename: attachment.filename } : {}),
+      });
+    }
+    return resolved;
   }
 
   /**

package/src/nodes/AgentBinaryContentFactory.ts

@@ -0,0 +1,74 @@
+import type { FilePart, ImagePart, ModelMessage, TextPart, UserModelMessage } from "ai";
+
+/** A binary attachment already resolved to inline bytes, ready to become an AI SDK content part. */
+export type ResolvedAgentBinary = Readonly<{
+  mediaType: string;
+  /** Base64-encoded bytes of the attachment. */
+  base64: string;
+  filename?: string;
+}>;
+
+/**
+ * Turns resolved file binaries into native AI SDK multimodal content parts and merges them into the
+ * agent prompt. Images (`image/*`) become {@link ImagePart}s; every other type (PDFs, office docs,
+ * CSV, JSON, …) becomes a {@link FilePart}. The provider maps these to its wire-level `image` /
+ * `document` blocks; an unsupported file type surfaces as a provider error at runtime.
+ *
+ * Parts are appended to the LAST user message so the binary travels alongside the author's prompt
+ * text (preserving any untrusted-source preamble that already wrapped that text). When no user
+ * message exists, a new user message carrying only the binaries is appended.
+ */
+export class AgentBinaryContentFactory {
+  static toContentPart(binary: ResolvedAgentBinary): ImagePart | FilePart {
+    if (binary.mediaType.startsWith("image/")) {
+      return { type: "image", image: binary.base64, mediaType: binary.mediaType };
+    }
+    return {
+      type: "file",
+      data: binary.base64,
+      mediaType: binary.mediaType,
+      ...(binary.filename ? { filename: binary.filename } : {}),
+    };
+  }
+
+  static withBinaries(
+    messages: ReadonlyArray<ModelMessage>,
+    binaries: ReadonlyArray<ResolvedAgentBinary>,
+  ): ReadonlyArray<ModelMessage> {
+    if (binaries.length === 0) return messages;
+    const parts = binaries.map((binary) => AgentBinaryContentFactory.toContentPart(binary));
+
+    const lastUserIndex = AgentBinaryContentFactory.lastUserMessageIndex(messages);
+    if (lastUserIndex === -1) {
+      const appended: UserModelMessage = { role: "user", content: parts };
+      return [...messages, appended];
+    }
+
+    const next = [...messages];
+    next[lastUserIndex] = AgentBinaryContentFactory.appendPartsToUserMessage(
+      messages[lastUserIndex] as UserModelMessage,
+      parts,
+    );
+    return next;
+  }
+
+  private static lastUserMessageIndex(messages: ReadonlyArray<ModelMessage>): number {
+    for (let index = messages.length - 1; index >= 0; index--) {
+      if (messages[index]?.role === "user") return index;
+    }
+    return -1;
+  }
+
+  private static appendPartsToUserMessage(
+    message: UserModelMessage,
+    parts: ReadonlyArray<ImagePart | FilePart>,
+  ): UserModelMessage {
+    const existing: ReadonlyArray<TextPart | ImagePart | FilePart> =
+      typeof message.content === "string"
+        ? message.content.length > 0
+          ? [{ type: "text", text: message.content }]
+          : []
+        : message.content;
+    return { ...message, content: [...existing, ...parts] };
+  }
+}

package/src/nodes/AgentMessageFactory.ts

@@ -1,7 +1,8 @@
 import type { AgentMessageDto, AgentToolCall } from "@codemation/core";
 
-import type { AssistantModelMessage, ModelMessage, ToolModelMessage } from "ai";
+import type { AssistantModelMessage, ModelMessage, ToolModelMessage, ToolResultPart } from "ai";
 
+import { AgentToolResultContentFactory } from "./AgentToolResultContentFactory";
 import type { ExecutedToolCall } from "./aiAgentSupport.types";
 
 /**
@@ -41,21 +42,36 @@ export class AgentMessageFactory {
    * Builds the `{ role: "tool", content: [{ type: "tool-result", ... }, ...] }` message returned
    * to the model after each tool round.
    */
-  static createToolResultsMessage(executedToolCalls: ReadonlyArray<ExecutedToolCall>): ToolModelMessage {
+  static createToolResultsMessage(
+    executedToolCalls: ReadonlyArray<ExecutedToolCall>,
+    passToolBinariesToModel = true,
+  ): 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),
-        },
+        output: AgentMessageFactory.toToolResultOutput(executed.result, passToolBinariesToModel),
       })),
     };
   }
 
+  /**
+   * Routes a tool result to a native multimodal `{ type: "content" }` output when it is
+   * content-block-shaped (an MCP `CallToolResult`) and binary passdown is enabled; otherwise keeps
+   * the inert `{ type: "json" }` path.
+   */
+  private static toToolResultOutput(result: unknown, passToolBinariesToModel: boolean): ToolResultPart["output"] {
+    if (passToolBinariesToModel) {
+      const content = AgentToolResultContentFactory.tryMapToContentOutput(result);
+      if (content !== undefined) {
+        return { type: "content", value: content };
+      }
+    }
+    return { type: "json", value: AgentMessageFactory.toToolResultJson(result) };
+  }
+
   private static toToolResultJson(value: unknown): import("ai").JSONValue {
     if (value === undefined) return null;
     try {