@codemation/core-nodes 0.12.0 → 0.14.0

package/src/http/SsrfGuard.ts

@@ -3,27 +3,8 @@ import { SSRFBlockedError } from "./SSRFBlockedError";
 
 export { SSRFBlockedError } from "./SSRFBlockedError";
 
-/** Emitted once per process when NODE_ENV=production and no allowedOutboundHosts is set. */
 let _productionNoAllowlistWarned = false;
 
-/**
- * Guards HTTP requests against Server-Side Request Forgery (SSRF) by
- * DNS-resolving the target host and rejecting private/link-local/loopback
- * addresses.
- *
- * Blocked ranges:
- * - RFC-1918: 10/8, 172.16/12, 192.168/16
- * - Link-local: 169.254/16
- * - Loopback: 127/8, ::1
- *
- * When `allowedOutboundHosts` is set, every resolved DNS target must match
- * at least one entry in the list (exact hostname or `*.example.com` wildcard).
- * When unset, existing behaviour applies: private ranges blocked, public allowed.
- *
- * Call {@link check} before making any outbound HTTP request.
- * Pass `allowPrivate: true` to bypass the private-network guard for trusted workflows
- * (allowedOutboundHosts allowlist is still applied when set).
- */
 export class SsrfGuard {
   constructor(private readonly allowedOutboundHosts?: ReadonlyArray<string>) {
     if (
@@ -40,15 +21,6 @@ export class SsrfGuard {
     }
   }
 
-  /**
-   * Resolves the host of `url` via DNS and throws {@link SSRFBlockedError}
-   * if any resolved address falls in a blocked range, or if the host does not
-   * match the operator-configured allowlist (when set).
-   *
-   * @param url - Fully-qualified URL of the intended request target.
-   * @param allowPrivate - When `true`, the private-network check is skipped.
-   *   The allowedOutboundHosts check is still applied when set.
-   */
   async check(url: string, allowPrivate: boolean): Promise<void> {
     if (allowPrivate && !this.allowedOutboundHosts?.length) return;
 
@@ -56,26 +28,20 @@ export class SsrfGuard {
     try {
       host = new URL(url).hostname;
     } catch {
-      // Malformed URL — let the fetch call surface the error.
       return;
     }
 
-    // Check allowedOutboundHosts allowlist first (hostname match, no DNS needed).
     if (this.allowedOutboundHosts?.length) {
       if (!this.isHostAllowed(host)) {
         throw new SSRFBlockedError(host, host);
       }
-      // Host is in the allowlist — skip private-network checks (host is trusted).
       return;
     }
 
-    // No allowlist: apply the standard private-network SSRF guard.
     if (allowPrivate) return;
 
-    // Strip IPv6 brackets for the check below.
     const bareHost = host.startsWith("[") ? host.slice(1, -1) : host;
 
-    // If the host is already a bare IP address, check directly without DNS.
     if (this.isPrivateAddress(bareHost)) {
       throw new SSRFBlockedError(host, bareHost);
     }
@@ -84,7 +50,6 @@ export class SsrfGuard {
     try {
       addresses = (await dns.lookup(host, { all: true })) as ReadonlyArray<{ address: string; family: number }>;
     } catch {
-      // DNS failure — let the fetch call surface the real error (ENOTFOUND etc.).
       return;
     }
 
@@ -95,15 +60,10 @@ export class SsrfGuard {
     }
   }
 
-  /**
-   * Returns true when `host` matches at least one entry in `allowedOutboundHosts`.
-   * Supports exact hostnames (`api.example.com`) and wildcard prefixes (`*.example.com`).
-   */
   private isHostAllowed(host: string): boolean {
     for (const allowed of this.allowedOutboundHosts ?? []) {
       if (allowed.startsWith("*.")) {
-        // Wildcard: *.example.com matches sub.example.com but NOT example.com itself.
-        const suffix = allowed.slice(1); // ".example.com"
+        const suffix = allowed.slice(1);
         if (host.endsWith(suffix) && host.length > suffix.length) return true;
       } else {
         if (host === allowed) return true;
@@ -122,20 +82,20 @@ export class SsrfGuard {
       return false;
     }
     const [a, b] = parts as [number, number, number, number];
-    if (a === 127) return true; // loopback 127/8
-    if (a === 10) return true; // RFC-1918 10/8
-    if (a === 172 && b >= 16 && b <= 31) return true; // RFC-1918 172.16/12
-    if (a === 192 && b === 168) return true; // RFC-1918 192.168/16
-    if (a === 169 && b === 254) return true; // link-local 169.254/16
-    if (a === 100 && b >= 64 && b <= 127) return true; // CGN 100.64.0.0/10
+    if (a === 127) return true;
+    if (a === 10) return true;
+    if (a === 172 && b >= 16 && b <= 31) return true;
+    if (a === 192 && b === 168) return true;
+    if (a === 169 && b === 254) return true;
+    if (a === 100 && b >= 64 && b <= 127) return true;
     return false;
   }
 
   private isPrivateIPv6(ip: string): boolean {
     const lower = ip.toLowerCase().replace(/^\[/, "").replace(/\]$/, "");
-    if (lower === "::1" || lower === "0:0:0:0:0:0:0:1") return true; // loopback
-    if (lower.startsWith("fc") || lower.startsWith("fd")) return true; // fc00::/7 ULA
-    if (lower.startsWith("fe80")) return true; // fe80::/10 link-local
+    if (lower === "::1" || lower === "0:0:0:0:0:0:0:1") return true;
+    if (lower.startsWith("fc") || lower.startsWith("fd")) return true;
+    if (lower.startsWith("fe80")) return true;
     return false;
   }
 }

package/src/http/httpRequest.types.ts

@@ -1,24 +1,12 @@
 import type { NodeExecutionContext } from "@codemation/core";
 import type { RunnableNodeConfig } from "@codemation/core";
 
-/**
- * Binary reference key into `item.binary`.
- */
 export type BinaryRef = string;
 
-/**
- * Discriminated union for the HTTP request body.
- */
 export type HttpBodySpec =
   | Readonly<{ kind: "none" }>
   | Readonly<{
       kind: "json";
-      /**
-       * Serializable object/array to encode as the JSON body. Encoded exactly once via
-       * `JSON.stringify`, so pass the value directly (e.g. `{ a: 1 }`) — never a
-       * pre-stringified string (`JSON.stringify(...)`), which would double-encode it.
-       * Typed as `object` so a bare string/primitive is a compile-time error.
-       */
       data: object;
     }>
   | Readonly<{ kind: "form"; data: Readonly<Record<string, string>> }>
@@ -28,37 +16,19 @@ export type HttpBodySpec =
       binaries?: Readonly<Record<string, BinaryRef>>;
     }>
   | Readonly<{
-      /**
-       * Send raw bytes from a binary slot as the request body.
-       * The binary attachment's `mimeType` is used as `Content-Type` unless
-       * the request `headers` map already contains `content-type`.
-       */
       kind: "binary";
-      /** Key into `item.binary` to read the request body bytes from. */
       slot: string;
     }>;
 
-/**
- * Session interface that credential types implement.
- * Returns header/query deltas so the executor can merge them without
- * mutating the immutable HttpRequestSpec.
- */
 export interface CredentialSession {
   applyToRequest(spec: HttpRequestSpec): HttpCredentialDelta;
 }
 
-/**
- * Mutations the credential session wants to apply to the outgoing request.
- */
 export type HttpCredentialDelta = Readonly<{
   headers?: Readonly<Record<string, string>>;
   query?: Readonly<Record<string, string>>;
 }>;
 
-/**
- * Full specification of one HTTP request. All URLs are fully resolved before
- * being passed here (template substitution already applied by the caller).
- */
 export type HttpRequestSpec = Readonly<{
   url: string;
   method: string;
@@ -67,28 +37,13 @@ export type HttpRequestSpec = Readonly<{
   body?: HttpBodySpec;
   credential?: CredentialSession;
   download?: Readonly<{ mode: "auto" | "always" | "never"; binaryName: string }>;
-  /**
-   * When set to `"binary"`, the response body is written to a binary slot
-   * instead of being parsed as JSON/text. Overrides `download` mode.
-   */
   responseFormat?: "json" | "text" | "binary";
-  /** Binary slot name for the response body when `responseFormat === "binary"`. Defaults to `"response"`. */
   responseBinarySlot?: string;
-  /** Maximum allowed response size in bytes (checked against Content-Length before allocating). Defaults to 100 MiB. */
   responseSizeCapBytes?: number;
-  /**
-   * When `false` (default), requests whose target host resolves to an RFC-1918,
-   * link-local (169.254/16), or loopback address are blocked to prevent SSRF attacks.
-   * Set to `true` only for workflows that intentionally reach private infrastructure.
-   */
   allowPrivateNetworkTargets?: boolean;
-  /** Execution context — needed for binary attach. */
   ctx: NodeExecutionContext<RunnableNodeConfig<unknown, unknown>>;
 }>;
 
-/**
- * Result of executing an HTTP request.
- */
 export type HttpRequestResult = Readonly<{
   url: string;
   method: string;
@@ -100,12 +55,8 @@ export type HttpRequestResult = Readonly<{
   json?: unknown;
   text?: string;
   bodyBinaryName?: string;
-  /** Set when `responseFormat === "binary"`. Name of the binary slot the response body was written to. */
   binarySlot?: string;
-  /** Set when `responseFormat === "binary"`. The MIME type of the stored response. */
   contentType?: string;
-  /** Set when `responseFormat === "binary"`. Size in bytes of the stored response. */
   size?: number;
-  /** Set when `responseFormat === "binary"`. Filename inferred from URL or Content-Disposition. */
   filename?: string;
 }>;

package/src/index.ts

@@ -34,6 +34,7 @@ export * from "./nodes/webhookRespondNowAndContinueError";
 export * from "./nodes/webhookRespondNowError";
 export * from "./nodes/WebhookTriggerFactory";
 export * from "./nodes/webhookTriggerNode";
+export { schedulePollingTrigger } from "./nodes/schedulePollingTrigger";
 export * from "./register.types";
 export * from "./workflowBuilder.types";
 export * from "./workflowAuthoring.types";

package/src/nodes/AIAgentConfig.ts

@@ -25,56 +25,18 @@ export interface AIAgentOptions<TInputJson = unknown, _TOutputJson = unknown> {
   readonly description?: string;
   readonly retryPolicy?: RetryPolicySpec;
   readonly guardrails?: AgentGuardrailConfig;
-  /** Engine applies with {@link RunnableNodeConfig.inputSchema} before {@link AIAgentNode.execute}. */
   readonly inputSchema?: ZodType<TInputJson>;
   readonly outputSchema?: ZodType<_TOutputJson>;
-  /**
-   * MCP servers to connect for this agent run. Each entry is the server id from
-   * the MCP catalog (e.g. `"gmail"`). Credential instances are bound via the
-   * standard credential-binding flow — each server materializes an MCP connection
-   * node and the slot lives on that node, keyed by
-   * `(workflowId, mcpConnectionNodeId, "credential")` (same shape as ChatModel and
-   * Tool connection nodes). There is no inline credential field; bind through the
-   * canvas credential dropdown before activation.
-   */
   readonly mcpServers?: ReadonlyArray<string>;
-  /**
-   * Tool ids to always include without going through `find_tools`.
-   * Format: `"serverId:toolName"` (e.g. `"gmail:send_message"`). Max 16.
-   */
   readonly pinnedMcpTools?: readonly string[];
-  /**
-   * Source identifiers that should be treated as untrusted external content.
-   * When an incoming `Item.json.__source` matches one of these values, every
-   * user-role message is wrapped with an untrusted-source preamble so the LLM
-   * treats the content as data rather than instructions (prompt-injection defense).
-   *
-   * Defaults to `["gmail", "ocr", "webhook"]` when unset.
-   */
   readonly untrustedSources?: ReadonlyArray<string>;
-  /**
-   * Whether file binaries are automatically passed to the chat model as native inline
-   * multimodal blocks. Defaults to `true`. Set to `false` to skip the binary-passdown step
-   * entirely (the node then behaves as if no binaries were present).
-   */
   readonly passBinariesToModel?: boolean;
-  /**
-   * Explicit binaries to pass to the chat model, instead of the ones on the current item.
-   * Either a static array or a function resolved per item (so an author can forward binaries
-   * produced by an earlier node further back in the workflow). When provided, these replace
-   * `item.binary` as the passdown source. Ignored when {@link passBinariesToModel} is `false`.
-   * Every binary is passed (images as image blocks, all other types as file blocks); the
-   * provider surfaces an error at runtime if it doesn't support a given file type.
-   */
+  readonly passToolBinariesToModel?: boolean;
   readonly binaries?:
     | ReadonlyArray<BinaryAttachment>
     | ((args: AgentMessageBuildArgs<TInputJson>) => ReadonlyArray<BinaryAttachment>);
 }
 
-/**
- * AI agent: credential bindings are keyed to connection-owned LLM/tool node ids (ConnectionNodeIdFactory),
- * not to the agent workflow node id.
- */
 export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
   implements RunnableNodeConfig<TInputJson, TOutputJson>, AgentNodeConfig<TInputJson, TOutputJson>
 {
@@ -96,6 +58,7 @@ export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
   readonly pinnedMcpTools?: readonly string[];
   readonly untrustedSources?: ReadonlyArray<string>;
   readonly passBinariesToModel?: boolean;
+  readonly passToolBinariesToModel?: boolean;
   readonly binaries?:
     | ReadonlyArray<BinaryAttachment>
     | ((args: AgentMessageBuildArgs<TInputJson>) => ReadonlyArray<BinaryAttachment>);
@@ -115,6 +78,7 @@ export class AIAgent<TInputJson = unknown, TOutputJson = unknown>
     this.pinnedMcpTools = options.pinnedMcpTools;
     this.untrustedSources = options.untrustedSources;
     this.passBinariesToModel = options.passBinariesToModel;
+    this.passToolBinariesToModel = options.passToolBinariesToModel;
     this.binaries = options.binaries;
   }
 

package/src/nodes/AIAgentExecutionHelpersFactory.ts

@@ -5,27 +5,8 @@ import { toJSONSchema as frameworkToJSONSchema } from "zod/v4/core";
 
 import { ConnectionCredentialExecutionContextFactory } from "./ConnectionCredentialExecutionContextFactory";
 
-/**
- * Shape of the instance-level `toJSONSchema` method that Zod v4 schemas expose. Conversions must go
- * through this instance method (see {@link AIAgentExecutionHelpersFactory#createJsonSchemaRecord})
- * rather than the module-level `toJSONSchema` import because the consumer's workflow-loader (see
- * `CodemationConsumerConfigLoader.toNamespace`) can load Zod under a separate tsx namespace. That
- * produces two runtime copies of Zod whose internal class / symbol identities don't overlap, so the
- * framework-side module-level `toJSONSchema` throws "Cannot read properties of undefined (reading
- * 'def')" on consumer-created schemas. The instance method is bound inside the schema's own module
- * and therefore uses the matching Zod internals.
- */
 type ZodInstanceToJsonSchema = (params?: Readonly<{ target: "draft-07" | "draft-7" | "draft-2020-12" }>) => unknown;
 
-/**
- * Helper utilities shared by {@link AIAgentNode} and supporting runners.
- *
- * Responsibilities:
- * - {@link #createConnectionCredentialExecutionContextFactory} centralizes credential-context wiring.
- * - {@link #createJsonSchemaRecord} is a pure Zod → draft-07 converter used by both
- *   `OpenAiStrictJsonSchemaFactory` (to feed OpenAI-strict structured output) and the
- *   `AgentStructuredOutputRepairPromptFactory` (to show a required-schema reminder).
- */
 @injectable()
 export class AIAgentExecutionHelpersFactory {
   createConnectionCredentialExecutionContextFactory(
@@ -34,15 +15,6 @@ export class AIAgentExecutionHelpersFactory {
     return new ConnectionCredentialExecutionContextFactory(credentialSessions);
   }
 
-  /**
-   * Produces a plain JSON Schema object (`draft-07`) from a Zod schema, as needed by
-   * OpenAI tool-parameter schemas and the structured-output repair prompt.
-   * - Prefers the schema's **instance** `toJSONSchema(...)` method so we stay inside the Zod
-   *   instance that created the schema (works across consumer/framework tsx namespaces — see
-   *   {@link ZodInstanceToJsonSchema}). Falls back to the framework-imported module function.
-   * - Strips root `$schema` (OpenAI ignores it).
-   * - Sanitizes `required` for cfworker json-schema compatibility (must be a string array or absent).
-   */
   createJsonSchemaRecord(
     inputSchema: ZodSchemaAny,
     options: Readonly<{
@@ -75,12 +47,6 @@ export class AIAgentExecutionHelpersFactory {
     return rest;
   }
 
-  /**
-   * Runs Zod's `toJSONSchema` via the schema's own instance method when available, so consumer
-   * schemas loaded under a different tsx namespace still convert correctly. If the caller handed us
-   * a payload that lacks that method (e.g. a plain JSON Schema record or a Zod instance whose
-   * prototype was stripped), we fall back to the framework-bundled module function.
-   */
   private convertZodSchemaToJsonSchema(inputSchema: ZodSchemaAny, params: Readonly<{ target: "draft-07" }>): unknown {
     const candidate = (inputSchema as unknown as { toJSONSchema?: ZodInstanceToJsonSchema }).toJSONSchema;
     if (typeof candidate === "function") {
@@ -89,9 +55,6 @@ export class AIAgentExecutionHelpersFactory {
     return frameworkToJSONSchema(inputSchema as unknown as Parameters<typeof frameworkToJSONSchema>[0], params);
   }
 
-  /**
-   * `@cfworker/json-schema` iterates `schema.required` with `for...of`; it must be a string array or absent.
-   */
   private sanitizeJsonSchemaRequiredKeywordsForCfworker(node: unknown): void {
     if (!node || typeof node !== "object" || Array.isArray(node)) {
       return;