@codemation/core-nodes 0.12.0 → 0.14.0

package/src/nodes/AIAgentNode.ts

@@ -38,11 +38,6 @@ import {
 
 import type { AssistantModelMessage, GenerateTextResult, LanguageModel, ModelMessage, ToolSet } from "ai";
 
-/**
- * OUTPUT generic must extend AI SDK's `Output<OUTPUT, PARTIAL, ELEMENT>` which is parametric on
- * `any`; there is no narrower concrete type we can substitute that accepts both text-only and
- * structured turns uniformly.
- */
 type AnyGenerateTextResult = GenerateTextResult<ToolSet, any>;
 import { z } from "zod";
 
@@ -74,7 +69,6 @@ const HITL_SOLO_CONSTRAINT_SENTENCE =
 type ResolvedGuardrails = Required<Pick<AgentGuardrailConfig, "maxTurns" | "onTurnLimitReached">> &
   Pick<AgentGuardrailConfig, "modelInvocationOptions">;
 
-/** Everything needed to run the agent loop for one item (shared across items in the same activation). */
 interface PreparedAgentExecution {
   readonly ctx: NodeExecutionContext<AIAgent<any, any>>;
   readonly model: ChatLanguageModel;
@@ -84,7 +78,6 @@ interface PreparedAgentExecution {
   readonly toolLoadingStrategy: ToolLoadingStrategy;
 }
 
-/** Result of one `generateText` turn with tools disabled for auto-execution. */
 interface TurnResult {
   readonly assistantMessage: AssistantModelMessage | undefined;
   readonly text: string;
@@ -111,11 +104,6 @@ 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;
 
@@ -145,7 +133,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     const { ctx } = args;
     await this.ensureAiSdk();
 
-    // HITL resume branch (story 10): the engine re-activates us after a human decision.
     if (ctx.resumeContext) {
       return this.executeResumed(args, ctx.resumeContext);
     }
@@ -156,16 +143,10 @@ 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
-   * as a tool_result, and continues the loop from where it suspended.
-   */
   private async executeResumed(
     args: RunnableNodeExecuteArgs<AIAgent<any, any>>,
     resumeContext: ResumeContext,
@@ -176,14 +157,12 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     const onRejected = (taskMetadata["onRejected"] as "halt" | "return" | undefined) ?? "return";
 
     if (!checkpoint) {
-      // Not an agent-HITL resume (e.g., a direct HITL node, not wrapped in agent). Fall through.
       const prepared = await this.getOrPrepareExecution(ctx);
       const itemWithMappedJson = { ...args.item, json: args.input };
       const resultItem = await this.runAgentForItem(prepared, itemWithMappedJson, args.itemIndex, args.items);
       return resultItem.json;
     }
 
-    // If rejected with halt policy, the engine has already halted; return gracefully.
     if (resumeContext.decision.kind === "decided" && resumeContext.decision.value === null && onRejected === "halt") {
       return undefined;
     }
@@ -191,7 +170,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     const decision = this.normalizeDecision(resumeContext);
 
     if (decision.status === "rejected" && onRejected === "halt") {
-      // Engine halts the run. Return nothing — the run is dead.
       return undefined;
     }
 
@@ -200,8 +178,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     const itemInputsByPort = AgentItemPortMap.fromItem(item);
     const itemScopedTools = this.createItemScopedTools(prepared.resolvedTools, ctx, item, args.itemIndex, args.items);
 
-    // Reconstruct conversation: checkpoint.conversation already includes the assistant message
-    // with the pending tool_use. Append the tool_result for the decision.
     const toolResultEntry: ExecutedToolCall = {
       toolName: checkpoint.pendingToolCallId,
       toolCallId: checkpoint.pendingToolCallId,
@@ -210,7 +186,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({
@@ -236,16 +212,10 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     return this.buildOutputItem(item, outputJson).json;
   }
 
-  /**
-   * Normalizes a {@link ResumeContext} decision into a flat JSON-serializable shape
-   * suitable for injection as a tool_result content.
-   */
   private normalizeDecision(resumeContext: ResumeContext): Record<string, unknown> {
     const { decision } = resumeContext;
     if (decision.kind === "decided") {
       const value = decision.value as Record<string, unknown> | null | undefined;
-      // Convention: the decision schema for an approval tool has { approved: boolean, note?: string }.
-      // The status is "approved" when approved === true, otherwise "rejected".
       const isApproved =
         typeof value === "object" && value !== null && "approved" in value ? Boolean(value["approved"]) : true;
       return {
@@ -258,7 +228,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     if (decision.kind === "timed_out") {
       return { status: "timed_out", at: decision.at.toISOString() };
     }
-    // auto_accepted
     return { status: "auto_accepted", at: decision.at.toISOString() };
   }
 
@@ -287,7 +256,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     );
     const resolvedTools = this.resolveTools(ctx.config.tools ?? []);
 
-    // Resolve MCP tools when the config declares mcpServers and the integration is registered.
     const mcpToolsByServer = await this.prepareMcpToolsByServer(ctx);
 
     const toolLoadingStrategy = await this.toolLoadingStrategyFactory.create({
@@ -331,7 +299,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       itemIndex: ctx.itemIndex,
       parentInvocationId: ctx.parentInvocationId,
     });
-    // Cast from AgentMcpToolMap (core contract, no ai dependency) to ToolSet (ai SDK type).
     return toolMap as unknown as ReadonlyMap<string, ToolSet>;
   }
 
@@ -383,24 +350,12 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     return this.buildOutputItem(item, outputJson);
   }
 
-  /**
-   * Multi-turn loop:
-   * - Each turn is a single `generateText` call with tools exposed but **not auto-executed**
-   *   (we control tool dispatch so that {@link AgentToolExecutionCoordinator} drives repair /
-   *   connection-invocation recording / transient-error handling exactly like before).
-   * - When the model returns no tool calls the loop ends with the model's text as the final answer.
-   * - Respects `guardrails.maxTurns` and `guardrails.onTurnLimitReached`.
-   * - Strategy-owned tool calls (e.g. `find_tools`) are dispatched via the strategy, not the
-   *   coordinator; their results are tracked so subsequent turns receive the discovered tools.
-   */
   private async runTurnLoopUntilFinalAnswer(args: {
     prepared: PreparedAgentExecution;
     itemInputsByPort: NodeInputsByPort;
     itemScopedTools: ReadonlyArray<ItemScopedToolBinding>;
     conversation: ModelMessage[];
-    /** When resuming from HITL suspension, the turn count at the point of suspension. */
     resumedTurnCount?: number;
-    /** When resuming from HITL suspension, the tool-call count at the point of suspension. */
     resumedToolCallCount?: number;
   }): Promise<Readonly<{ finalText: string; turnCount: number; toolCallCount: number }>> {
     const { prepared, itemInputsByPort, itemScopedTools, conversation } = args;
@@ -410,7 +365,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     let toolCallCount = args.resumedToolCallCount ?? 0;
     let turnCount = 0;
     const repairAttemptsByToolName = new Map<string, number>();
-    /** Tool IDs surfaced by find_tools across all prior turns in this item run. */
     let previousFoundToolIds: ReadonlyArray<string> = [];
 
     for (let turn = 1; turn <= guardrails.maxTurns; turn++) {
@@ -437,11 +391,9 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         break;
       }
 
-      // Partition tool calls: strategy-owned (find_tools) vs coordinator-managed (node-backed).
       const strategyOwnedCalls = result.toolCalls.filter((tc) => toolLoadingStrategy.ownsToolName(tc.name));
       const coordinatorCalls = result.toolCalls.filter((tc) => !toolLoadingStrategy.ownsToolName(tc.name));
 
-      // Execute strategy-owned calls (find_tools) and track results for the next turn.
       const strategyExecutedCalls: ExecutedToolCall[] = [];
       for (const tc of strategyOwnedCalls) {
         const metaResult = await toolLoadingStrategy.executeMetaTool(tc.name, tc.input);
@@ -459,14 +411,11 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         });
       }
 
-      // Execute coordinator-managed calls if any.
       const coordinatorExecutedCalls: ExecutedToolCall[] = [];
       if (coordinatorCalls.length > 0) {
         const plannedToolCalls = this.planToolCalls(itemScopedTools, coordinatorCalls, ctx.nodeId);
         toolCallCount += plannedToolCalls.length;
         await this.markQueuedTools(plannedToolCalls, ctx);
-        // Snapshot conversation with the assistant message appended — this is the checkpoint
-        // conversation the agent coordinator stores if a HITL tool suspends the run.
         const assistantMsg =
           result.assistantMessage ?? AgentMessageFactory.createAssistantWithToolCalls(result.text, result.toolCalls);
         const conversationWithAssistant: ModelMessage[] = [...conversation, assistantMsg];
@@ -490,6 +439,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         result.text,
         result.toolCalls,
         allExecutedCalls,
+        ctx.config.passToolBinariesToModel !== false,
       );
     }
 
@@ -522,10 +472,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),
     );
   }
 
@@ -609,12 +560,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     });
   }
 
-  /**
-   * 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" } };
@@ -624,11 +569,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     return { onRejected: perBinding ?? marker?.onRejected ?? "return" };
   }
 
-  /**
-   * Invoke a text turn using the merged tool set from item-scoped tools (coordinator-managed)
-   * and strategy tools (find_tools + discovered MCP tools).
-   * Strategy tools take precedence for names that overlap.
-   */
   private async invokeTextTurnWithStrategyTools(
     prepared: PreparedAgentExecution,
     itemInputsByPort: NodeInputsByPort,
@@ -638,18 +578,12 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   ): Promise<TurnResult> {
     const itemToolSet = this.buildToolSet(itemScopedTools);
     const strategyHasTools = Object.keys(strategyTools).length > 0;
-    // Strip execute callbacks from strategy tools so the AI SDK does not auto-execute them.
-    // Codemation owns all tool dispatch (coordinator for node-backed, strategy for MCP/meta-tools).
     const strippedStrategyTools = strategyHasTools ? this.stripExecuteCallbacks(strategyTools) : strategyTools;
     const mergedTools: ToolSet | undefined =
       itemToolSet || strategyHasTools ? { ...(itemToolSet ?? {}), ...strippedStrategyTools } : undefined;
     return this.invokeTextTurnWithToolSet(prepared, itemInputsByPort, messages, mergedTools);
   }
 
-  /**
-   * Removes `execute` properties from ToolSet entries so the AI SDK does not
-   * auto-execute them within `generateText`. Codemation owns all tool dispatch.
-   */
   private stripExecuteCallbacks(tools: ToolSet): ToolSet {
     const stripped: Record<string, unknown> = {};
     for (const [name, def] of Object.entries(tools)) {
@@ -659,12 +593,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     return stripped as ToolSet;
   }
 
-  /**
-   * Builds a ToolSet from resolved tools for strategy initialization.
-   * The strategy uses this for its "always-included" node-backed tool descriptions.
-   * HITL tools (detected via the `humanApprovalToolBehavior` field set by `defineHumanApprovalNode`) get the solo-constraint sentence
-   * appended to their description.
-   */
   private buildToolSetFromResolved(resolvedTools: ReadonlyArray<ResolvedTool>): ToolSet {
     if (resolvedTools.length === 0) return {};
     const toolSet: Record<string, { description?: string; inputSchema: ReturnType<typeof import("ai").jsonSchema> }> =
@@ -685,20 +613,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     return toolSet as unknown as ToolSet;
   }
 
-  /**
-   * Builds an AI SDK {@link ToolSet} where every tool ships a pre-converted JSON Schema (via
-   * {@link jsonSchema}) — not the raw Zod schema — and carries **no** `execute`. Two reasons:
-   *
-   * 1. Codemation owns tool dispatch + the per-tool repair loop (see {@link AgentToolExecutionCoordinator}),
-   *    so the AI SDK must surface tool calls back to us instead of auto-running them.
-   * 2. The AI SDK's `asSchema` helper discriminates between Zod v3 / Zod v4 / Standard Schema via
-   *    runtime feature-detection (`~standard`, `_zod`, etc.). Handing it a pre-built
-   *    {@link jsonSchema} record — which is tagged with `Symbol.for('vercel.ai.schema')` — skips all
-   *    of that detection and guarantees the provider receives a draft-07 JSON Schema with
-   *    `additionalProperties: false` at every object depth (see {@link OpenAiStrictJsonSchemaFactory}
-   *    for the same logic applied to structured-output schemas). Codemation still runs its own Zod
-   *    validation on tool inputs before execute — the schema handed to the model is advisory.
-   */
   private buildToolSet(itemScopedTools: ReadonlyArray<ItemScopedToolBinding>): ToolSet | undefined {
     if (itemScopedTools.length === 0) return undefined;
     const toolSet: Record<string, { description?: string; inputSchema: ReturnType<typeof import("ai").jsonSchema> }> =
@@ -723,10 +637,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     return toolSet as unknown as ToolSet;
   }
 
-  /**
-   * One `generateText` turn (no auto tool execution) with Codemation-owned child-span telemetry
-   * and connection-invocation state recording. Accepts a pre-built ToolSet.
-   */
   private async invokeTextTurnWithToolSet(
     prepared: PreparedAgentExecution,
     itemInputsByPort: NodeInputsByPort,
@@ -832,11 +742,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     }
   }
 
-  /**
-   * Structured-output turn: runs `generateText({ output: Output.object({ schema }) })` via the
-   * structured-output runner.  We keep this as a separate helper because the runner needs the raw
-   * validated value (not just text) back, and must be able to retry on Zod failures.
-   */
   private async invokeStructuredTurn(
     prepared: PreparedAgentExecution,
     itemInputsByPort: NodeInputsByPort,
@@ -886,11 +791,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     });
     try {
       const callOptions = this.resolveCallOptions(model, guardrails.modelInvocationOptions);
-      // Always feed the AI SDK a plain JSON Schema, never a raw Zod schema. A consumer
-      // workflow's outputSchema is created with the consumer's tsx-loaded Zod — a different
-      // runtime copy than the framework's Zod — so handing that object to `Output.object`
-      // throws "schema is not a function". Convert via the schema's own instance method
-      // (dual-zod safe; see AIAgentExecutionHelpersFactory) before wrapping with jsonSchema().
       const schemaRecord = this.isZodSchema(schema)
         ? this.executionHelpers.createJsonSchemaRecord(schema, {
             schemaName: structuredOptions?.schemaName ?? "structured_output",
@@ -977,13 +877,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     };
   }
 
-  /**
-   * Build a no-code-friendly output payload for an LLM round.
-   *
-   * Always includes `content` (matching the canvas snapshot shape used elsewhere) and adds a
-   * `toolCalls` array when the round produced tool calls so the execution inspector surfaces the
-   * planned calls instead of just an empty `""` for tool-only rounds.
-   */
   private summarizeTurnOutput(turnResult: TurnResult): JsonValue {
     if (turnResult.toolCalls.length === 0) return { content: turnResult.text };
     const toolCalls = turnResult.toolCalls.map((toolCall) => ({
@@ -1237,19 +1130,12 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     });
     const wrapped = this.wrapUntrustedSourceMessages(messages, item, ctx.config);
     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,
@@ -1263,14 +1149,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     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>>,
@@ -1287,12 +1165,6 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     return resolved;
   }
 
-  /**
-   * When `item.json.__source` matches an entry in `config.untrustedSources`
-   * (default: `["gmail", "ocr", "webhook"]`), wraps every user-role message
-   * content with an untrusted-external-source preamble so the LLM treats the
-   * content as data, not instructions.
-   */
   private wrapUntrustedSourceMessages(
     messages: ReadonlyArray<AgentMessageDto>,
     item: Item,
@@ -1388,5 +1260,3 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     return candidate.details;
   }
 }
-
-// MARKER_12345

package/src/nodes/AgentBinaryContentFactory.ts

@@ -1,23 +1,11 @@
 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/")) {

package/src/nodes/AgentLoopCheckpoint.types.ts

@@ -1,23 +1,10 @@
 import type { ModelMessage } from "ai";
 
-/**
- * Snapshot of the agent loop state at the moment of HITL suspension.
- * Serialized as JSON and stored on `SuspensionRequest.request.metadata.agentCheckpoint`
- * so the resumed node can reconstruct and continue the conversation.
- *
- * Defined here (story 10) and consumed in `AIAgentNode` resume branch.
- */
 export type AgentLoopCheckpoint = Readonly<{
-  /** Full conversation history up to and including the assistant message that emitted tool_use. */
   conversation: ModelMessage[];
-  /** Turn count at the point of suspension (1-based, matches loop counter in runTurnLoopUntilFinalAnswer). */
   turnCount: number;
-  /** Total tool-call count accumulated before suspension. */
   toolCallCount: number;
-  /** The tool_use id that triggered suspension; matched against the tool_result on resume. */
   pendingToolCallId: string;
-  /** Display name of the agent (for logging / telemetry continuity). */
   agentName: string;
-  /** Model identifier carried for migration-safety redundancy. */
   modelId: string;
 }>;

package/src/nodes/AgentMessageFactory.ts

@@ -1,23 +1,15 @@
 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";
 
-/**
- * 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<ModelMessage> {
     return messages.map((message) => this.createPromptMessage(message));
   }
 
-  /**
-   * 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>,
@@ -37,25 +29,31 @@ export class AgentMessageFactory {
     return { role: "assistant", content };
   }
 
-  /**
-   * 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),
       })),
     };
   }
 
+  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 {

package/src/nodes/AgentStructuredOutputRunner.ts

@@ -24,19 +24,6 @@ type ParsedStructuredOutputResult<TValue> = ParsedStructuredOutputSuccess<TValue
 
 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;
@@ -141,10 +128,6 @@ export class AgentStructuredOutputRunner {
     );
   }
 
-  /**
-   * 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;

package/src/nodes/AgentToolExecutionCoordinator.ts

@@ -27,18 +27,12 @@ export class AgentToolExecutionCoordinator {
       ctx: NodeExecutionContext<AIAgent<any, any>>;
       agentName: string;
       repairAttemptsByToolName: Map<string, number>;
-      /** Conversation including the assistant message that emitted these tool_use blocks. Stored in checkpoint on HITL suspension. */
       conversationSnapshot?: ReadonlyArray<ModelMessage>;
-      /** Turn count at the moment of this coordinator invocation. */
       turnCount?: number;
-      /** Cumulative tool-call count up to and including this batch. */
       toolCallCount?: number;
-      /** Model id for checkpoint migration safety. */
       modelId?: string;
     }>,
   ): Promise<ReadonlyArray<ExecutedToolCall>> {
-    // Solo enforcement: if any HITL tool appears alongside other tools, return error results
-    // for all calls so the model self-corrects on the next turn.
     const hitlCalls = args.plannedToolCalls.filter((c) => c.binding.humanApproval !== undefined);
     if (hitlCalls.length > 0 && args.plannedToolCalls.length > 1) {
       return args.plannedToolCalls.map((c) => ({
@@ -68,7 +62,6 @@ export class AgentToolExecutionCoordinator {
     const rejected = results.find((result) => result.status === "rejected");
     if (rejected?.status === "rejected") {
       const reason = rejected.reason;
-      // Preserve SuspensionRequest (not an Error subclass) before falling back to Error wrapping.
       if (reason instanceof SuspensionRequest) throw reason;
       throw reason instanceof Error ? reason : new Error(String(reason));
     }
@@ -173,7 +166,6 @@ export class AgentToolExecutionCoordinator {
         result,
       } satisfies ExecutedToolCall;
     } catch (error) {
-      // D1: Suspension catch — intercept before error classifier, augment with agent checkpoint.
       if (error instanceof SuspensionRequest) {
         const pendingToolCallId = plannedToolCall.toolCall.id ?? plannedToolCall.binding.config.name;
         const checkpoint: AgentLoopCheckpoint = {
@@ -427,10 +419,6 @@ export class AgentToolExecutionCoordinator {
     return candidate.details;
   }
 
-  /**
-   * Extracts the text content from the last assistant message in the conversation snapshot.
-   * Used to populate `agentReasoning` in the HITL suspension metadata.
-   */
   private extractLastAssistantText(conversation: ReadonlyArray<ModelMessage>): string {
     for (let i = conversation.length - 1; i >= 0; i--) {
       const msg = conversation[i];