@codemation/core-nodes 0.12.0 → 0.14.0

package/src/nodes/AgentToolResultContentFactory.ts

@@ -0,0 +1,126 @@
+import type { ToolResultPart } from "ai";
+
+type ContentOutputValue = Extract<ToolResultPart["output"], { type: "content" }>["value"];
+type ContentOutputPart = ContentOutputValue[number];
+
+const MAX_INLINE_BYTES = 8 * 1024 * 1024;
+
+const KNOWN_MCP_BLOCK_TYPES: ReadonlySet<string> = new Set(["text", "image", "audio", "resource", "resource_link"]);
+
+type McpContentBlock = Readonly<{
+  type?: unknown;
+  text?: unknown;
+  data?: unknown;
+  mimeType?: unknown;
+  uri?: unknown;
+  name?: unknown;
+  resource?: Readonly<{ blob?: unknown; text?: unknown; mimeType?: unknown; uri?: unknown; name?: unknown }>;
+}>;
+
+export class AgentToolResultContentFactory {
+  static tryMapToContentOutput(result: unknown): ContentOutputValue | undefined {
+    const blocks = AgentToolResultContentFactory.contentBlocks(result);
+    if (blocks === undefined) return undefined;
+
+    const parts: ContentOutputPart[] = [];
+    let inlinedBytes = 0;
+    for (const block of blocks) {
+      const mapped = AgentToolResultContentFactory.mapBlock(block, inlinedBytes);
+      parts.push(mapped.part);
+      inlinedBytes += mapped.bytes;
+    }
+    return parts;
+  }
+
+  private static contentBlocks(result: unknown): ReadonlyArray<McpContentBlock> | undefined {
+    if (result === null || typeof result !== "object") return undefined;
+    const content = (result as { content?: unknown }).content;
+    if (!Array.isArray(content) || content.length === 0) return undefined;
+    const allTyped = content.every(
+      (block) => block !== null && typeof block === "object" && typeof (block as { type?: unknown }).type === "string",
+    );
+    if (!allTyped) return undefined;
+    const looksMcp = content.some((block) => KNOWN_MCP_BLOCK_TYPES.has((block as { type: string }).type));
+    return looksMcp ? (content as ReadonlyArray<McpContentBlock>) : undefined;
+  }
+
+  private static mapBlock(
+    block: McpContentBlock,
+    inlinedBytesSoFar: number,
+  ): Readonly<{ part: ContentOutputPart; bytes: number }> {
+    const type = block.type;
+    if (type === "text" && typeof block.text === "string") {
+      return { part: { type: "text", text: block.text }, bytes: 0 };
+    }
+    if (type === "image" && typeof block.data === "string" && typeof block.mimeType === "string") {
+      return AgentToolResultContentFactory.mapBinary({
+        base64: block.data,
+        mediaType: block.mimeType,
+        inlinedBytesSoFar,
+      });
+    }
+    if (type === "resource" && block.resource) {
+      return AgentToolResultContentFactory.mapEmbeddedResource(block.resource, inlinedBytesSoFar);
+    }
+    if (type === "resource_link" && typeof block.uri === "string") {
+      const mime = typeof block.mimeType === "string" ? ` (${block.mimeType})` : "";
+      return { part: { type: "text", text: `[linked resource: ${block.uri}${mime}]` }, bytes: 0 };
+    }
+    return { part: { type: "text", text: `[unsupported tool content block: ${String(type)}]` }, bytes: 0 };
+  }
+
+  private static mapEmbeddedResource(
+    resource: NonNullable<McpContentBlock["resource"]>,
+    inlinedBytesSoFar: number,
+  ): Readonly<{ part: ContentOutputPart; bytes: number }> {
+    if (typeof resource.text === "string") {
+      return { part: { type: "text", text: resource.text }, bytes: 0 };
+    }
+    if (typeof resource.blob === "string" && typeof resource.mimeType === "string") {
+      return AgentToolResultContentFactory.mapBinary({
+        base64: resource.blob,
+        mediaType: resource.mimeType,
+        filename: typeof resource.name === "string" ? resource.name : undefined,
+        inlinedBytesSoFar,
+      });
+    }
+    const uri = typeof resource.uri === "string" ? resource.uri : "unknown";
+    return { part: { type: "text", text: `[embedded resource: ${uri}]` }, bytes: 0 };
+  }
+
+  private static mapBinary(
+    args: Readonly<{ base64: string; mediaType: string; filename?: string; inlinedBytesSoFar: number }>,
+  ): Readonly<{ part: ContentOutputPart; bytes: number }> {
+    const rawBytes = Math.floor((args.base64.length * 3) / 4);
+    if (args.inlinedBytesSoFar + rawBytes > MAX_INLINE_BYTES) {
+      const name = args.filename ? ` "${args.filename}"` : "";
+      const kb = Math.round(rawBytes / 1024);
+      return {
+        part: {
+          type: "text",
+          text: `[binary${name} (${args.mediaType}, ~${kb} KB) omitted: exceeds the per-tool-result inline limit]`,
+        },
+        bytes: 0,
+      };
+    }
+    if (args.mediaType.startsWith("image/")) {
+      return { part: { type: "image-data", data: args.base64, mediaType: args.mediaType }, bytes: rawBytes };
+    }
+    if (args.mediaType === "application/pdf") {
+      return {
+        part: {
+          type: "file-data",
+          data: args.base64,
+          mediaType: args.mediaType,
+          ...(args.filename ? { filename: args.filename } : {}),
+        },
+        bytes: rawBytes,
+      };
+    }
+    const name = args.filename ? ` "${args.filename}"` : "";
+    return {
+      part: { type: "text", text: `[binary${name} (${args.mediaType}) not inlined: unsupported by the model]` },
+      bytes: 0,
+    };
+  }
+}

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;
 

package/src/nodes/ConnectionCredentialNode.ts

@@ -3,10 +3,6 @@ import { node } from "@codemation/core";
 
 import type { ConnectionCredentialNodeConfig } from "./ConnectionCredentialNodeConfig";
 
-/**
- * Placeholder runnable node for connection-owned workflow nodes (LLM/tool slots).
- * The engine does not schedule these; they exist for credentials, tokens, and UI identity.
- */
 @node({ packageName: "@codemation/core-nodes" })
 export class ConnectionCredentialNode implements RunnableNode<ConnectionCredentialNodeConfig> {
   kind = "node" as const;

package/src/nodes/CronTriggerFactory.ts

@@ -8,15 +8,6 @@ import type { NodeBaseOptions } from "./nodeOptions.types";
 
 export type CronTickJson = { firedAt: string; scheduledFor: string };
 
-/**
- * Schedules a workflow on a standard cron expression.
- *
- * Each tick emits one item: `{ firedAt: string, scheduledFor: string }` — both ISO-8601 timestamps.
- * `firedAt` is the wall-clock moment the callback ran; `scheduledFor` is the cron-computed
- * firing instant (these differ when the job was delayed).
- *
- * Timezone defaults to UTC when omitted — cron without an explicit TZ is a DST footgun.
- */
 export class CronTrigger implements TriggerNodeConfig<CronTickJson> {
   readonly kind = "trigger" as const;
   readonly type: TypeToken<unknown> = CronTriggerNode;

package/src/nodes/DeferredMetaToolStrategy.ts

@@ -21,26 +21,12 @@ interface McpToolEntry {
   readonly toolDef: ToolSet[string];
 }
 
-/**
- * Default tool-loading strategy: BM25-indexed MCP tool deferral via a `find_tools` meta-tool.
- *
- * - Node-backed tools and pinned MCP tools are always included in every turn.
- * - `find_tools(query, limit?)` is added to the tool set when MCP tools are indexed.
- * - Tools surfaced by `find_tools` are included in subsequent turns.
- *
- * Not DI-managed; instantiated per agent execution by DeferredMetaToolStrategyFactory.
- */
 export class DeferredMetaToolStrategy implements ToolLoadingStrategy {
   private nodeBackedTools: ToolSet = {};
   private pinnedTools: ToolSet = {};
   private mcpEntries: McpToolEntry[] = [];
   private toolsByServerId = new Map<string, Map<string, ToolSet[string]>>();
   private foundToolIds = new Set<string>();
-  /**
-   * `jsonSchema` from the `ai` SDK, loaded lazily in {@link initialize} so the SDK
-   * (~28MB RSS) stays off the boot path. `initialize` always runs before the sync
-   * `getToolsForTurn` → `buildFindToolsDefinition` path, so this is set before use.
-   */
   private jsonSchema!: typeof import("ai").jsonSchema;
 
   constructor(
@@ -124,8 +110,6 @@ export class DeferredMetaToolStrategy implements ToolLoadingStrategy {
 
   ownsToolName(toolName: string): boolean {
     if (toolName === FIND_TOOLS_NAME) return true;
-    // Any tool that came from an MCP server is strategy-owned so the coordinator
-    // does not attempt to dispatch it as a node-backed tool.
     for (const serverMap of this.toolsByServerId.values()) {
       if (serverMap.has(toolName)) return true;
     }
@@ -149,8 +133,6 @@ export class DeferredMetaToolStrategy implements ToolLoadingStrategy {
       return results;
     }
 
-    // Route to the MCP tool's execute callback (injected by AgentMcpIntegrationImpl with
-    // telemetry + 403 detection wrapping).
     for (const serverMap of this.toolsByServerId.values()) {
       const toolDef = serverMap.get(toolName);
       if (toolDef) {

package/src/nodes/DeferredMetaToolStrategyFactory.ts

@@ -3,11 +3,6 @@ import { BM25Index } from "./BM25Index";
 import { DeferredMetaToolStrategy } from "./DeferredMetaToolStrategy";
 import type { ToolLoadingStrategy, ToolLoadingStrategyInitInput } from "./ToolLoadingStrategy";
 
-/**
- * Factory for creating and initializing a DeferredMetaToolStrategy per agent execution.
- * Injected into AIAgentNode; each agent call creates its own initialized strategy instance.
- * BM25Index is constructed here (this file is a composition root via the Factory suffix).
- */
 @injectable()
 export class DeferredMetaToolStrategyFactory {
   async create(input: ToolLoadingStrategyInitInput): Promise<ToolLoadingStrategy> {

package/src/nodes/HttpRequestNodeFactory.ts

@@ -39,9 +39,6 @@ export class HttpRequestNode implements RunnableNode<HttpRequest<any, any>> {
       ctx: ctx as unknown as HttpRequestSpec["ctx"],
     };
 
-    // Build the request (headers, body encoding, URL query merge) once,
-    // then make a SINGLE fetch call and decide what to do with the response.
-    // This avoids a double-fetch regression for auto-mode binary responses.
     const executor = new HttpRequestExecutor(
       globalThis.fetch,
       new HttpBodyBuilder(),
@@ -55,7 +52,6 @@ export class HttpRequestNode implements RunnableNode<HttpRequest<any, any>> {
     const headers = this.readHeaders(response.headers);
     const mimeType = this.resolveMimeType(headers);
 
-    // New explicit responseFormat="binary" path — takes precedence over downloadMode.
     if (ctx.config.responseFormat === "binary") {
       return await this.handleBinaryResponse(response, resolvedUrl, headers, mimeType, ctx);
     }
@@ -90,7 +86,6 @@ export class HttpRequestNode implements RunnableNode<HttpRequest<any, any>> {
       return outputItem;
     }
 
-    // Non-binary path: parse JSON or read text.
     const isJson = this.isJsonMimeType(mimeType);
     let json: unknown | undefined;
     let text: string | undefined;
@@ -130,7 +125,6 @@ export class HttpRequestNode implements RunnableNode<HttpRequest<any, any>> {
     const slotName = ctx.config.responseBinarySlot;
     const sizeCap = ctx.config.responseSizeCapBytes;
 
-    // Check Content-Length against size cap before allocating.
     const contentLengthHeader = headers["content-length"];
     if (contentLengthHeader) {
       const declaredSize = parseInt(contentLengthHeader, 10);
@@ -144,11 +138,6 @@ export class HttpRequestNode implements RunnableNode<HttpRequest<any, any>> {
 
     const filename = this.resolveFilename(resolvedUrl, headers);
 
-    // Stream response.body straight into binary storage — never load the
-    // whole payload into memory. ctx.binary.attach accepts ReadableStream
-    // natively. Falls back to arrayBuffer only when response.body is null
-    // (rare; 204/304-style responses where the cap-check above already
-    // covers the meaningful size case).
     const attachment = await ctx.binary.attach({
       name: slotName,
       body: response.body
@@ -168,7 +157,6 @@ export class HttpRequestNode implements RunnableNode<HttpRequest<any, any>> {
       headers,
       binarySlot: slotName,
       contentType: mimeType,
-      // Reported by the binary storage adapter after streaming completes.
       size: attachment.size,
       ...(filename !== undefined ? { filename } : {}),
     };
@@ -189,13 +177,11 @@ export class HttpRequestNode implements RunnableNode<HttpRequest<any, any>> {
     try {
       return await ctx.getCredential<CredentialSession>(slotKey);
     } catch {
-      // Credential slot configured but not bound — treat as no credential.
       return undefined;
     }
   }
 
   private resolveUrl(item: Item, ctx: NodeExecutionContext<HttpRequest<any, any>>): string {
-    // Literal URL in args takes precedence over the legacy urlField approach.
     const literalUrl = ctx.config.args.url;
     if (literalUrl && literalUrl.trim().length > 0) {
       return literalUrl.trim();

package/src/nodes/InboxApprovalNode.types.ts

@@ -3,28 +3,12 @@ import { defineHumanApprovalNode } from "@codemation/core";
 import type { Item, JsonValue } from "@codemation/core";
 import { InboxChannelResolverToken } from "@codemation/core";
 
-/**
- * A subject field (title / body) for an inbox approval. Either a static string
- * or a contextual callback that builds the string from the item using ordinary
- * JavaScript template literals — e.g. `({ item }) => `Approve ${item.json.vendor}``.
- * Code-first: no template DSL, just functions.
- */
 type InboxSubjectField = string | ((args: { item: Item }) => string);
 
 function resolveSubjectField(field: InboxSubjectField, item: Item): string {
   return typeof field === "function" ? field({ item }) : field;
 }
 
-/**
- * Auto-detecting inbox approval node.
- *
- * Uses `ctx.resolve(InboxChannelResolverToken)` to pick the right inbox channel
- * at runtime:
- * - In managed mode (PairingConfig present): routes to the control-plane inbox.
- * - Otherwise: routes to the local inbox.
- *
- * Authors use this node directly; no extra wiring needed per deployment mode.
- */
 export const inboxApproval = defineHumanApprovalNode({
   key: "inbox.approval",
   title: "Inbox Approval",

package/src/nodes/IsTestRunNode.ts

@@ -3,14 +3,6 @@ import { emitPorts, node } from "@codemation/core";
 
 import { IsTestRun } from "./isTestRun";
 
-/**
- * Routes each item to the `true` port if `ctx.testContext` is set (the run was started by the
- * TestSuiteOrchestrator), else to `false`. Lets workflow authors guard real side-effects:
- *
- *   GmailTrigger / TestTrigger → ClassifyAgent → IsTestRun
- *                                                 ├── true → AssertionNode
- *                                                 └── false → SendReply
- */
 @node({ packageName: "@codemation/core-nodes" })
 export class IsTestRunNode implements RunnableNode<IsTestRun<unknown>> {
   kind = "node" as const;

package/src/nodes/ManualTriggerFactory.ts

@@ -15,7 +15,6 @@ export class ManualTrigger<TOutputJson = unknown> implements TriggerNodeConfig<T
   readonly defaultItems?: Items<TOutputJson>;
   readonly id?: string;
   readonly description?: string;
-  /** Manual runs often emit an empty batch; still schedule downstream by default. */
   readonly continueWhenEmptyOutput = true as const;
 
   constructor(name?: string, idOrOptions?: string | NodeBaseOptions);
@@ -29,8 +28,6 @@ export class ManualTrigger<TOutputJson = unknown> implements TriggerNodeConfig<T
     defaultItemsOrId?: ManualTriggerDefaultValue<TOutputJson> | string,
     idOrOptions?: string | NodeBaseOptions,
   ) {
-    // Position 2 keeps its existing string-vs-object meaning (string→id, object/array→default items).
-    // Options (id/description) live in the trailing slot, or position 2 when it's a bare string id.
     this.defaultItems = ManualTrigger.resolveDefaultItems(defaultItemsOrId);
     const trailing = idOrOptions ?? (typeof defaultItemsOrId === "string" ? defaultItemsOrId : undefined);
     const options = typeof trailing === "string" ? { id: trailing } : (trailing ?? {});

package/src/nodes/ManualTriggerNode.ts

@@ -11,10 +11,6 @@ import { node } from "@codemation/core";
 
 import { ManualTrigger } from "./ManualTriggerFactory";
 
-/**
- * Setup is intentionally a no-op: the engine host can run workflows manually
- * by calling `engine.runWorkflow(workflow, triggerNodeId, items)`.
- */
 @node({ packageName: "@codemation/core-nodes" })
 export class ManualTriggerNode implements TestableTriggerNode<ManualTrigger<any>> {
   kind = "trigger" as const;

package/src/nodes/MergeNode.ts

@@ -48,7 +48,6 @@ export class MergeNode implements MultiInputNode<Merge<any, any>> {
       return { main: out };
     }
 
-    // passThrough (default): for each origin index, take first available input (deterministic input precedence).
     const chosenByOrigin = new Map<number, Item>();
     const fallback: Item[] = [];
 

package/src/nodes/NodeBackedToolRuntime.ts

@@ -63,20 +63,6 @@ export class NodeBackedToolRuntime {
     });
   }
 
-  /**
-   * Returns a re-rooted child ctx for nested-agent tools (so their LLM/tool connection ids derive
-   * from the tool connection node, telemetry parents under the tool-call span, and connection
-   * invocations carry `parentInvocationId`). Plain runnable tools (non-agent) keep the orchestrator
-   * ctx with only `config` swapped — no nesting concern.
-   *
-   * The caller (`AIAgentNode.createItemScopedTools`) already wraps the orchestrator ctx via
-   * `ConnectionCredentialExecutionContextFactory.forConnectionNode`, so `args.ctx.nodeId` is the
-   * tool's own connection node id (e.g. `AIAgentNode:2__conn__tool__searchInMail`). We pass that
-   * through as the sub-agent's `nodeId`; deriving another `toolConnectionNodeId(args.ctx.nodeId,
-   * config.name)` here would prepend a duplicate `__conn__tool__<name>` segment and exponentially
-   * deepen ids on each invocation, which also breaks credential resolution because user-provided
-   * bindings sit on the single-level connection node id.
-   */
   private resolveNodeCtx(
     config: NodeBackedToolConfig<any, ZodSchemaAny, ZodSchemaAny>,
     args: ToolExecuteArgs,

package/src/nodes/SubWorkflowNode.ts

@@ -37,9 +37,6 @@ export class SubWorkflowNode implements RunnableNode<SubWorkflow<any, any>> {
         engineMaxSubworkflowDepth: args.ctx.engineMaxSubworkflowDepth,
       },
     });
-    // Annotate the parent node's snapshot with the child run id so the UI can deep-link to
-    // the specific child execution. The engine's subsequent markCompleted preserves this via
-    // NodeExecutionSnapshotFactory.completed which carries forward previous.childRunId.
     await args.ctx.nodeState?.setChildRunId?.({ nodeId: args.ctx.nodeId, childRunId: result.runId });
     if (result.status !== "completed") {
       throw new Error(`Subworkflow ${args.ctx.config.workflowId} did not complete (status=${result.status})`);

package/src/nodes/SwitchNode.ts

@@ -4,9 +4,6 @@ import { emitPorts, node } from "@codemation/core";
 import type { Switch } from "./switch";
 import { tagItemForRouterFanIn } from "./mergeExecutionUtils.types";
 
-/**
- * Routes each item to exactly one output port. Port names must match workflow edges (see {@link Switch} config).
- */
 @node({ packageName: "@codemation/core-nodes" })
 export class SwitchNode implements RunnableNode<Switch<any>> {
   kind = "node" as const;

package/src/nodes/TestTriggerNode.ts

@@ -9,15 +9,6 @@ import type {
 
 import { node } from "@codemation/core";
 
-/**
- * Author-defined test-fixture trigger. Live activation skips this trigger (filtered by
- * `triggerKind === "test"` in `TriggerRuntimeService`); the `TestSuiteOrchestrator` drives its
- * `generateItems` callback during a TestSuiteRun and dispatches one workflow run per yielded item.
- *
- * `setup` is intentionally a no-op for symmetry with other trigger nodes — the real work happens
- * in the orchestrator. `execute` is a passthrough so items provided to `engine.runWorkflow(...)`
- * (one per case) flow downstream unchanged on `main`.
- */
 @node({ packageName: "@codemation/core-nodes" })
 export class TestTriggerNode implements TriggerNode<TestTriggerNodeConfig<any>> {
   kind = "trigger" as const;

package/src/nodes/aiAgentSupport.types.ts

@@ -24,30 +24,15 @@ export type ResolvedTool = Readonly<{
   }>;
 }>;
 
-/**
- * Per-item binding of a tool: the user config plus the resolved runtime and a snapshot of the
- * original Zod `inputSchema`.
- *
- * `execute` accepts optional `hooks` so the agent coordinator can pass the live `agent.tool.call`
- * span and the planned tool-call's `invocationId`. Node-backed sub-agent tools use these hooks
- * via {@link ChildExecutionScopeFactory} to re-root their runtime ctx under the tool-call boundary
- * (fresh activationId, telemetry parented at the tool-call span, `parentInvocationId` set).
- *
- * `humanApproval` is present only when the tool was created via `defineHumanApprovalNode`
- * (via its marker) — detected during `resolveTools` in `AIAgentNode`.
- */
 export type ItemScopedToolBinding = Readonly<{
   config: ToolConfig;
   inputSchema: ZodSchemaAny;
   execute(input: unknown, hooks?: ItemScopedToolCallHooks): Promise<unknown>;
-  /** Present when this binding is backed by a HITL-approval node (story 10). */
   humanApproval?: Readonly<{ onRejected: "halt" | "return" }>;
 }>;
 
 export type ItemScopedToolCallHooks = Readonly<{
-  /** Live agent.tool.call span (used to parent sub-agent telemetry). */
   parentSpan?: TelemetrySpanScope;
-  /** invocationId of the parent tool call (used to thread `parentInvocationId` through ctx). */
   parentInvocationId?: ConnectionInvocationId;
 }>;
 
@@ -56,7 +41,6 @@ export type PlannedToolCall = Readonly<{
   toolCall: AgentToolCall;
   invocationIndex: number;
   nodeId: string;
-  /** Stable id reused across queued / running / completed connection invocation rows for this tool call. */
   invocationId: string;
 }>;
 

package/src/nodes/assertion.ts

@@ -14,22 +14,12 @@ export interface AssertionOptions<TInputJson> {
   readonly id?: string;
   readonly icon?: string;
   readonly description?: string;
-  /**
-   * Author callback. Returns one or more {@link AssertionResult}s per input item. Each becomes
-   * one emitted output item — useful for per-row reporting in the Tests tab. Return `[]` to
-   * emit nothing for this case (rare; usually you want at least a "no-op" pass).
-   */
   assertions(
     item: Item<TInputJson>,
     ctx: NodeExecutionContext<Assertion<TInputJson>>,
   ): Promise<ReadonlyArray<AssertionResult>> | ReadonlyArray<AssertionResult>;
 }
 
-/**
- * Generic assertion node — the "callback" form. For declarative shorthands (StringEquals,
- * JudgeByAgent) compose this with helpers added in later phases. Sets `emitsAssertions: true`
- * so host-side persisters know to record its outputs as `TestAssertion` rows.
- */
 export class Assertion<TInputJson = unknown> implements RunnableNodeConfig<TInputJson, AssertionResult> {
   readonly kind = "node" as const;
   readonly type: TypeToken<unknown> = AssertionNode;

package/src/nodes/codemationDocumentScannerNode.ts

@@ -5,30 +5,21 @@ import { managedHmacFetchFactory } from "../chatModels/ManagedHmacSignerFactory.
 const ANALYZER_TYPES = ["document", "invoice", "image", "auto"] as const;
 export type DocScannerAnalyzerType = (typeof ANALYZER_TYPES)[number];
 
-/** Per-field value/confidence shape as returned by apps/doc-scanner. */
 export type DocScannerField = Readonly<{
   value: unknown;
   confidence: number | null;
 }>;
 
-/** Output shape of CodemationDocumentScanner — identical to the service wire response. */
 export type DocScannerOutput = Readonly<{
   markdown: string;
   fields: Readonly<Record<string, DocScannerField>>;
 }>;
 
 export type CodemationDocumentScannerConfig = Readonly<{
-  /** Key on `item.binary` that holds the document. Default: "data". */
   binaryField?: string;
-  /** Analyzer type. Default: "auto" (routes on mime type on the service side). */
   analyzerType?: DocScannerAnalyzerType;
-  /** MIME type override. Falls back to attachment.mimeType. */
   contentType?: string;
-  /** Include per-field confidence scores (0–1). Default: false.
-   *  Enabling this roughly doubles contextualization tokens for document analyzers.
-   *  Image and auto-to-image requests silently ignore this flag (confidence stays null). */
   includeConfidence?: boolean;
-  /** Max bytes checked before any read. Default: 50 MiB (same cap as OCR nodes, LD10). */
   maxBytes?: number;
 }>;
 
@@ -54,9 +45,6 @@ export const codemationDocumentScannerNode = defineNode({
     includeConfidence: z.boolean().optional(),
     maxBytes: z.number().int().positive().optional(),
   }),
-  // keepBinaries is omitted (false) — the output replaces the item payload.
-  // To carry the source binary forward, set keepBinaries: true at the call site
-  // or use a downstream step that reads item.binary.
   inspectorSummary({ config }) {
     const cfg = config as unknown as CodemationDocumentScannerConfig;
     const rows: Array<{ label: string; value: string }> = [
@@ -79,9 +67,6 @@ export const codemationDocumentScannerNode = defineNode({
       );
     }
 
-    // Workspace pairing identity — injected by the CP provisioner (mirrors
-    // CodemationChatModelFactory). Passed to the signer; the HMAC binds THIS
-    // workspace (LD4) and does not sign the file body (LD11).
     // eslint-disable-next-line no-restricted-properties -- WORKSPACE_ID is injected by the provisioner; read at execute time.
     const workspaceId = process.env["WORKSPACE_ID"];
     // eslint-disable-next-line no-restricted-properties -- WORKSPACE_PAIRING_SECRET is injected by the provisioner; read at execute time.
@@ -104,9 +89,6 @@ export const codemationDocumentScannerNode = defineNode({
     const confidenceSuffix = includeConfidence ? "&confidence=true" : "";
     const url = `${gatewayUrl}/analyze?type=${encodeURIComponent(analyzerType)}${confidenceSuffix}`;
 
-    // signBody: false (LD11): the HMAC binds the workspace, not the file body.
-    // The signer forwards the bytes untouched and signs an empty-body hash, so
-    // we never re-read or normalise the binary payload.
     const hmacFetch = managedHmacFetchFactory(workspaceId, pairingSecret, { signBody: false });
 
     const response = await hmacFetch(url, {

package/src/nodes/collections/collectionListNode.types.ts

@@ -30,7 +30,6 @@ export const collectionListNode = defineNode({
       offset: config.offset,
       where: config.where,
     });
-    // Emit one item per row per AGENTS.md engine/node contract.
     return [...rows];
   },
 });