@codemation/core-nodes 0.13.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,
@@ -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];
@@ -611,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" } };
@@ -626,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,
@@ -640,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)) {
@@ -661,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> }> =
@@ -687,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> }> =
@@ -725,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,
@@ -834,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,
@@ -888,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",
@@ -979,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) => ({
@@ -1239,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,
@@ -1265,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>>,
@@ -1289,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,
@@ -1390,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

@@ -5,20 +5,11 @@ import type { AssistantModelMessage, ModelMessage, ToolModelMessage, ToolResultP
 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>,
@@ -38,10 +29,6 @@ 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>,
     passToolBinariesToModel = true,
@@ -57,11 +44,6 @@ export class AgentMessageFactory {
     };
   }
 
-  /**
-   * 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);

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];

package/src/nodes/AgentToolResultContentFactory.ts

@@ -1,22 +1,12 @@
 import type { ToolResultPart } from "ai";
 
-/** The `value` array of a `{ type: "content" }` tool-result output, as accepted by the AI SDK. */
 type ContentOutputValue = Extract<ToolResultPart["output"], { type: "content" }>["value"];
 type ContentOutputPart = ContentOutputValue[number];
 
-/**
- * Cap on raw (pre-base64) bytes inlined from a single tool result. Base64 inflates ~33% and every
- * inlined byte eats model context, so oversize binaries are replaced with a text placeholder.
- */
 const MAX_INLINE_BYTES = 8 * 1024 * 1024;
 
-/** MCP content-block discriminators. At least one must appear for a result to be treated as MCP-shaped. */
 const KNOWN_MCP_BLOCK_TYPES: ReadonlySet<string> = new Set(["text", "image", "audio", "resource", "resource_link"]);
 
-/**
- * MCP-style content block, as returned verbatim by a `CallToolResult` (`@ai-sdk/mcp` tool `execute`).
- * Only the fields this factory reads are modelled; unknown shapes fall through to a text marker.
- */
 type McpContentBlock = Readonly<{
   type?: unknown;
   text?: unknown;
@@ -27,19 +17,6 @@ type McpContentBlock = Readonly<{
   resource?: Readonly<{ blob?: unknown; text?: unknown; mimeType?: unknown; uri?: unknown; name?: unknown }>;
 }>;
 
-/**
- * Maps a tool result that is **content-block-shaped** (an MCP `CallToolResult` with a `content`
- * array) into AI SDK `{ type: "content" }` tool-result output, so binaries reach the chat model as
- * native multimodal tool-result blocks instead of being flattened to inert JSON text.
- *
- * The `@ai-sdk/anthropic` provider maps a `content`-output part as follows:
- * `text` → text block, `image-data` → image block, `file-data` (only `application/pdf`) → document
- * block. Non-PDF `file-data` is dropped by the provider, so this factory emits `image-data` for
- * images, `file-data` only for PDFs, and a text marker for every other binary type.
- *
- * Returns `undefined` when the result is not content-block-shaped — callers keep the existing
- * `{ type: "json" }` path, so plain string/object tool results are unaffected.
- */
 export class AgentToolResultContentFactory {
   static tryMapToContentOutput(result: unknown): ContentOutputValue | undefined {
     const blocks = AgentToolResultContentFactory.contentBlocks(result);
@@ -55,12 +32,6 @@ export class AgentToolResultContentFactory {
     return parts;
   }
 
-  /**
-   * Returns the `content` array iff `result` is an object whose `content` is an array of typed
-   * blocks AND at least one block carries a known MCP discriminator. A plain JSON result that merely
-   * has a `content` key of some other shape (e.g. Notion/Slack rich-text blocks) is rejected,
-   * preserving the `{ type: "json" }` path so its payload is never lost.
-   */
   private static contentBlocks(result: unknown): ReadonlyArray<McpContentBlock> | undefined {
     if (result === null || typeof result !== "object") return undefined;
     const content = (result as { content?: unknown }).content;

package/src/nodes/AssertionNode.ts

@@ -3,17 +3,6 @@ import { node } from "@codemation/core";
 
 import { Assertion } from "./assertion";
 
-/**
- * Runs the author's `assertions` callback for each input item and emits one workflow `Item` per
- * returned {@link AssertionResult} on `main`. Persistence is handled by a host-side subscriber
- * to `nodeCompleted` events that filters on `config.emitsAssertions === true`; this node does
- * not write to any store on its own.
- *
- * If the author callback throws, we emit a single synthetic AssertionResult with `errored: true`
- * and `score: 0`. Without this catch the whole node would fail and no assertion row would be
- * persisted — making the rollup blind to "the assertion code itself is broken." The synthetic
- * row keeps `failedAssertionsByRunId` consistent and gives the UI something to surface.
- */
 @node({ packageName: "@codemation/core-nodes" })
 export class AssertionNode implements RunnableNode<Assertion<any>> {
   kind = "node" as const;
@@ -24,9 +13,6 @@ export class AssertionNode implements RunnableNode<Assertion<any>> {
     const config = ctx.config;
     try {
       const results: ReadonlyArray<AssertionResult> = await config.assertions(args.item, ctx);
-      // Engine "array → fan-out on main, each element is item.json" — returning the plain results
-      // makes downstream `item.json` exactly an AssertionResult. Wrapping in `{ json: result }`
-      // would double-wrap (engine would see `Item`-shaped values but treat them as JSON values).
       return [...results];
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);

package/src/nodes/BM25Index.ts

@@ -1,9 +1,3 @@
-/**
- * Minimal BM25 (Okapi BM25) implementation for indexing MCP tool descriptions.
- *
- * Parameters: k1=1.5, b=0.75 (standard defaults).
- * Tokenisation: lowercase, split on non-alphanumerics, filter empties.
- */
 export class BM25Index {
   private readonly k1 = 1.5;
   private readonly b = 0.75;
@@ -12,10 +6,6 @@ export class BM25Index {
   private readonly df = new Map<string, number>();
   private avgDocLen = 0;
 
-  /**
-   * Add all documents at once. After calling this, search is available.
-   * Documents are indexed in insertion order; search returns their indices.
-   */
   add(docs: ReadonlyArray<string>): void {
     const docTerms = docs.map((d) => this.tokenize(d));
 
@@ -34,10 +24,6 @@ export class BM25Index {
     this.avgDocLen = docTerms.length > 0 ? totalLen / docTerms.length : 0;
   }
 
-  /**
-   * Returns up to `limit` document indices ranked by BM25 score (highest first).
-   * Returns an empty array if the index is empty or the query matches nothing.
-   */
   search(query: string, limit: number): ReadonlyArray<number> {
     const n = this.tf.length;
     if (n === 0) return [];

package/src/nodes/ConnectionCredentialExecutionContextFactory.ts

@@ -8,11 +8,6 @@ import type {
 
 import { CredentialResolverFactory } from "@codemation/core/bootstrap";
 
-/**
- * Builds a {@link NodeExecutionContext} whose identity for credential binding and `getCredential`
- * is a **connection-owned** workflow node id (`ConnectionNodeIdFactory` in `@codemation/core`),
- * not the executing parent node. Use for LLM slots, tool slots, or any connection-scoped owner.
- */
 export class ConnectionCredentialExecutionContextFactory {
   private readonly credentialResolverFactory: CredentialResolverFactory;