@codemation/core-nodes 0.10.1 → 0.12.0

package/dist/metadata.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core-nodes",
-  "version": "0.10.1",
+  "version": "0.12.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.1"
+    "@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/http/HttpBodyBuilder.ts

@@ -28,6 +28,15 @@ export class HttpBodyBuilder {
     }
 
     if (spec.kind === "json") {
+      // Backstop for callers that reach this with a string despite the `data: object`
+      // type (e.g. via `unknown`/`as`, or a resolved expression): re-stringifying it
+      // would double-encode into `"\"...\""`. Fail loud instead of shipping bad JSON.
+      if (typeof spec.data === "string") {
+        throw new Error(
+          'HttpRequest body kind:"json" expects a serializable object for "data", but received a string. ' +
+            "Pass the object directly (e.g. { a: 1 }), not a pre-stringified JSON string (JSON.stringify(...)).",
+        );
+      }
       return {
         body: JSON.stringify(spec.data),
         contentType: "application/json",

package/src/http/httpRequest.types.ts

@@ -11,7 +11,16 @@ export type BinaryRef = string;
  */
 export type HttpBodySpec =
   | Readonly<{ kind: "none" }>
-  | Readonly<{ kind: "json"; data: unknown }>
+  | Readonly<{
+      kind: "json";
+      /**
+       * Serializable object/array to encode as the JSON body. Encoded exactly once via
+       * `JSON.stringify`, so pass the value directly (e.g. `{ a: 1 }`) — never a
+       * pre-stringified string (`JSON.stringify(...)`), which would double-encode it.
+       * Typed as `object` so a bare string/primitive is a compile-time error.
+       */
+      data: object;
+    }>
   | Readonly<{ kind: "form"; data: Readonly<Record<string, string>> }>
   | Readonly<{
       kind: "multipart";

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,23 @@ 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;
+  /**
+   * 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 +87,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 +95,10 @@ export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
   readonly mcpServers?: ReadonlyArray<string>;
   readonly pinnedMcpTools?: readonly string[];
   readonly untrustedSources?: ReadonlyArray<string>;
+  readonly passBinariesToModel?: boolean;
+  readonly binaries?:
+    | ReadonlyArray<BinaryAttachment>
+    | ((args: AgentMessageBuildArgs<TInputJson>) => ReadonlyArray<BinaryAttachment>);
 
   constructor(options: AIAgentOptions<TInputJson, TOutputJson>) {
     this.name = options.name;
@@ -81,6 +106,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 +114,8 @@ export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
     this.mcpServers = options.mcpServers;
     this.pinnedMcpTools = options.pinnedMcpTools;
     this.untrustedSources = options.untrustedSources;
+    this.passBinariesToModel = options.passBinariesToModel;
+    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
@@ -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,
@@ -596,15 +610,18 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   }
 
   /**
-   * Detects whether a tool config is backed by a `defineHumanApprovalNode` marker
-   * and returns the HITL behavior config, or `undefined` when not a HITL tool.
+   * Resolves the HITL behavior for a tool binding, or `undefined` when it is not a HITL tool.
+   * A binding is HITL if either the backing node carries a `defineHumanApprovalNode` marker or the
+   * binding sets a per-binding `onRejected` via `asTool(..., { onRejected })`. The per-binding value
+   * wins over the node marker, so two tools backed by the same node can reject differently.
    */
   private resolveHumanApprovalBehavior(config: ToolConfig): Readonly<{ onRejected: "halt" | "return" }> | undefined {
     if (!this.isNodeBackedToolConfig(config)) return undefined;
     const nodeConfig = config.node as unknown as { humanApprovalToolBehavior?: { onRejected?: "halt" | "return" } };
     const marker = nodeConfig.humanApprovalToolBehavior;
-    if (marker === undefined) return undefined;
-    return { onRejected: marker.onRejected ?? "return" };
+    const perBinding = config.onRejected;
+    if (marker === undefined && perBinding === undefined) return undefined;
+    return { onRejected: perBinding ?? marker?.onRejected ?? "return" };
   }
 
   /**
@@ -650,7 +667,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,
@@ -661,7 +679,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;
@@ -683,7 +701,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,
@@ -698,7 +717,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;
@@ -756,7 +775,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,
@@ -878,10 +897,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,
@@ -1204,12 +1223,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,
@@ -1217,7 +1236,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/CallbackNodeFactory.ts

@@ -10,6 +10,7 @@ import type {
 } from "@codemation/core";
 
 import { CallbackNode } from "./CallbackNode";
+import type { NodeBaseOptions } from "./nodeOptions.types";
 
 export type CallbackHandler<
   TInputJson = unknown,
@@ -20,12 +21,12 @@ export type CallbackHandler<
   ctx: NodeExecutionContext<TConfig>,
 ) => Promise<Items<TOutputJson> | PortsEmission | void> | Items<TOutputJson> | PortsEmission | void;
 
-export type CallbackOptions = Readonly<{
-  id?: string;
-  retryPolicy?: RetryPolicySpec;
-  nodeErrorHandler?: NodeErrorHandlerSpec;
-  declaredOutputPorts?: ReadonlyArray<string>;
-}>;
+export type CallbackOptions = NodeBaseOptions &
+  Readonly<{
+    retryPolicy?: RetryPolicySpec;
+    nodeErrorHandler?: NodeErrorHandlerSpec;
+    declaredOutputPorts?: ReadonlyArray<string>;
+  }>;
 
 export class Callback<TInputJson = unknown, TOutputJson = TInputJson> implements RunnableNodeConfig<
   TInputJson,
@@ -37,6 +38,7 @@ export class Callback<TInputJson = unknown, TOutputJson = TInputJson> implements
   readonly icon = "lucide:braces" as const;
   readonly emptyBatchExecution = "runOnce" as const;
   readonly id?: string;
+  readonly description?: string;
   readonly retryPolicy?: RetryPolicySpec;
   readonly nodeErrorHandler?: NodeErrorHandlerSpec;
   readonly declaredOutputPorts?: ReadonlyArray<string>;
@@ -52,6 +54,7 @@ export class Callback<TInputJson = unknown, TOutputJson = TInputJson> implements
   ) {
     const resolvedOptions = typeof idOrOptions === "string" ? { ...options, id: idOrOptions } : idOrOptions;
     this.id = resolvedOptions?.id;
+    this.description = resolvedOptions?.description;
     this.retryPolicy = resolvedOptions?.retryPolicy;
     this.nodeErrorHandler = resolvedOptions?.nodeErrorHandler;
     this.declaredOutputPorts = resolvedOptions?.declaredOutputPorts;

package/src/nodes/CronTriggerFactory.ts

@@ -4,6 +4,7 @@ import { Cron } from "croner";
 import type { CronCallback } from "croner";
 
 import { CronTriggerNode } from "./CronTriggerNode";
+import type { NodeBaseOptions } from "./nodeOptions.types";
 
 export type CronTickJson = { firedAt: string; scheduledFor: string };
 
@@ -21,14 +22,17 @@ export class CronTrigger implements TriggerNodeConfig<CronTickJson> {
   readonly type: TypeToken<unknown> = CronTriggerNode;
   readonly icon = "lucide:clock" as const;
   readonly id?: string;
+  readonly description?: string;
 
   constructor(
     public readonly name: string,
     private readonly args: Readonly<{ schedule: string; timezone?: string }>,
-    id?: string,
+    idOrOptions?: string | NodeBaseOptions,
   ) {
     new Cron(args.schedule, { paused: true, timezone: args.timezone });
-    this.id = id;
+    const options = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+    this.id = options?.id;
+    this.description = options?.description;
   }
 
   get schedule(): string {