@codemation/core-nodes 0.13.0 → 0.14.0

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];
   },
 });

package/src/nodes/httpRequest.ts

@@ -18,7 +18,6 @@ import { HttpRequestNode } from "./HttpRequestNodeFactory";
 
 export type HttpRequestDownloadMode = "auto" | "always" | "never";
 
-/** JSON emitted by {@link HttpRequest} — response metadata only (input item fields are not passed through). */
 export type HttpRequestOutputJson = Readonly<{
   url: string;
   method: string;
@@ -30,20 +29,12 @@ export type HttpRequestOutputJson = Readonly<{
   json?: unknown;
   text?: string;
   bodyBinaryName?: string;
-  /** Set when `responseFormat === "binary"`. Name of the binary slot the response was stored in. */
   binarySlot?: string;
-  /** Set when `responseFormat === "binary"`. 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;
 }>;
 
-/**
- * The built-in HTTP request credential type IDs accepted by the `HttpRequest` node.
- * These match the four generic credential types shipped with `@codemation/core-nodes`.
- */
 export const HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES: ReadonlyArray<string> = [
   bearerTokenCredentialType.definition.typeId,
   apiKeyCredentialType.definition.typeId,
@@ -51,7 +42,6 @@ export const HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES: ReadonlyArray<string> = [
   oauth2ClientCredentialsType.definition.typeId,
 ] as const;
 
-/** Default maximum response size for binary mode: 100 MiB. */
 const DEFAULT_RESPONSE_SIZE_CAP_BYTES = 100 * 1024 * 1024;
 
 export class HttpRequest<
@@ -67,77 +57,20 @@ export class HttpRequest<
   constructor(
     public readonly name: string,
     public readonly args: Readonly<{
-      /** HTTP method (default: GET). */
       method?: string;
-      /**
-       * Legacy: field name on item.json to read the URL from.
-       * Use `url` for a literal/templated URL instead.
-       */
       urlField?: string;
-      /** Literal or templated URL. When present, takes precedence over `urlField`. */
       url?: string;
-      /** Extra headers to add to every request. */
       headers?: Readonly<Record<string, string>>;
-      /** Query parameters to append to the URL. */
       query?: Readonly<Record<string, string>>;
-      /** Request body specification. For `kind:"json"`, pass the object directly in `body.data` — it is JSON-encoded exactly once, so never a pre-stringified string. */
       body?: HttpBodySpec;
-      /**
-       * Credential slot.
-       *
-       * **String shorthand** (existing): `credentialSlot: "auth"` — the slot accepts all four
-       * default HTTP credential types (bearer, API-key, basic, OAuth2).
-       *
-       * **Object form** (new): narrows the accepted types to the caller-supplied list, useful
-       * when only a subset of credential types makes sense for a specific endpoint.
-       * ```ts
-       * credentialSlot: { name: "auth", acceptedTypes: [bearerTokenCredentialType] }
-       * ```
-       * The slot must be declared in `getCredentialRequirements()`, which is wired automatically.
-       */
       credentialSlot?: string | Readonly<{ name: string; acceptedTypes?: ReadonlyArray<AnyCredentialType> }>;
       binaryName?: string;
       downloadMode?: HttpRequestDownloadMode;
-      /**
-       * Controls how the response body is handled.
-       * - `"json"` / `"text"`: existing behaviour (parse + emit on `item.json`).
-       * - `"binary"`: read the response as raw bytes and store via `ctx.binary.attach`.
-       *   The output JSON contains `{ status, headers, binarySlot, contentType, size, filename }`
-       *   but NOT the raw bytes. Use `responseBinarySlot` to name the slot (default `"response"`).
-       *
-       * When omitted, the existing `downloadMode` logic applies (backward-compatible).
-       */
       responseFormat?: "json" | "text" | "binary";
-      /**
-       * Name of the binary slot to write the response body into when `responseFormat === "binary"`.
-       * Defaults to `"response"`.
-       */
       responseBinarySlot?: string;
-      /**
-       * Maximum response size in bytes for binary mode. Checked against the `Content-Length`
-       * response header before allocating memory. Defaults to 100 MiB (104857600).
-       * Requests whose `Content-Length` exceeds this cap are rejected before the body is read.
-       */
       responseSizeCapBytes?: number;
-      /**
-       * Operator-configurable outbound host allowlist.
-       *
-       * When set, every HTTP request target must match an entry in this list before the
-       * request is made — requests to any other host are rejected with {@link SSRFBlockedError}.
-       * Supports exact hostnames (`api.example.com`) and wildcard subdomain patterns
-       * (`*.example.com` matches `sub.example.com` but not `example.com` itself).
-       *
-       * When unset (default), the existing SSRF private-network guard applies:
-       * public hosts are allowed and private/loopback ranges are blocked.
-       *
-       * **Production warning**: when `NODE_ENV === "production"` and this is unset, a one-time
-       * warning is logged at workflow startup.
-       *
-       * Setting this to an empty array `[]` is equivalent to "block everything".
-       */
       allowedOutboundHosts?: ReadonlyArray<string>;
       id?: string;
-      /** Plain-language explanation surfaced in the node sidebar. */
       description?: string;
     }> = {},
     public readonly retryPolicy: RetryPolicySpec = RetryPolicy.defaultForHttp,
@@ -197,7 +130,6 @@ export class HttpRequest<
         },
       ];
     }
-    // Object form: use caller-supplied acceptedTypes (mapped to typeIds), falling back to all defaults.
     const acceptedTypes =
       slot.acceptedTypes && slot.acceptedTypes.length > 0
         ? slot.acceptedTypes.map((ct) => ct.definition.typeId)

package/src/nodes/isTestRun.ts

@@ -3,10 +3,6 @@ import type { RunnableNodeConfig, TypeToken } from "@codemation/core";
 import { IsTestRunNode } from "./IsTestRunNode";
 import type { NodeBaseOptions } from "./nodeOptions.types";
 
-/**
- * Branches per-item on whether the current run is a test run. Output ports: `true`, `false`.
- * The wire payload is unchanged — this is a router, not a transform.
- */
 export class IsTestRun<TInputJson = unknown> implements RunnableNodeConfig<TInputJson, TInputJson> {
   readonly kind = "node" as const;
   readonly type: TypeToken<unknown> = IsTestRunNode;

package/src/nodes/mapData.ts

@@ -19,7 +19,6 @@ export class MapData<TInputJson = unknown, TOutputJson = unknown> implements Run
   readonly kind = "node" as const;
   readonly type: TypeToken<unknown> = MapDataNode;
   readonly execution = { hint: "local" } as const;
-  /** Zero mapped items should still allow downstream nodes to run. */
   readonly continueWhenEmptyOutput = true as const;
   readonly icon = "lucide:square-pen" as const;
   readonly keepBinaries: boolean;

package/src/nodes/merge.ts

@@ -18,10 +18,6 @@ export class Merge<TInputJson = unknown, TOutputJson = TInputJson> implements Ru
     public readonly name: string,
     public readonly cfg: Readonly<{
       mode: MergeMode;
-      /**
-       * Deterministic input precedence order (only used for passThrough/append).
-       * Any inputs not listed are appended in lexicographic order.
-       */
       prefer?: ReadonlyArray<InputPortKey>;
     }> = { mode: "passThrough" },
     idOrOptions?: string | NodeBaseOptions,

package/src/nodes/mergeExecutionUtils.types.ts

@@ -5,9 +5,6 @@ export function getOriginIndex(item: Item): number | undefined {
   return getOriginIndexFromItem(item);
 }
 
-/**
- * Tags items routed to fan-in merge-by-origin (same contract as {@link IfNode} / {@link SwitchNode}).
- */
 export function tagItemForRouterFanIn<TJson>(
   args: Readonly<{
     item: Item<TJson>;

package/src/nodes/nodeOptions.types.ts

@@ -1,11 +1,3 @@
-/**
- * Options shared by every authorable built-in node: a stable `id` and a plain-language
- * `description` (the non-technical "what does this node do" line surfaced in the node sidebar).
- *
- * `description` is a first-class config option — passed inline in the node's options, exactly like
- * `id` — and is threaded onto the config instance so it flows into the persisted workflow snapshot
- * the host / canvas mappers read. Node-specific option types extend this.
- */
 export interface NodeBaseOptions {
   readonly id?: string;
   readonly description?: string;

package/src/nodes/schedulePollingTrigger.ts

@@ -0,0 +1,37 @@
+import { definePollingTrigger } from "@codemation/core";
+
+type ScheduleItem = {
+  firedAt: string;
+  tick: number;
+};
+
+type ScheduleState = {
+  tick: number;
+};
+
+export const schedulePollingTrigger = definePollingTrigger({
+  key: "schedule.interval",
+  packageName: "@codemation/core-nodes",
+  title: "Run on schedule",
+  description: "Emit one tick item on every poll cycle.",
+  icon: "lucide:clock",
+  pollIntervalMs: 60_000,
+  initialState(): ScheduleState {
+    return { tick: 0 };
+  },
+  poll({ state }) {
+    const currentState = (state ?? { tick: 0 }) as ScheduleState;
+    const tick = currentState.tick + 1;
+    const item: { json: ScheduleItem } = { json: { firedAt: new Date().toISOString(), tick } };
+    return {
+      items: [item],
+      nextState: { tick },
+    };
+  },
+  execute(items) {
+    return { main: items };
+  },
+  testItems() {
+    return [{ json: { firedAt: new Date().toISOString(), tick: 0 } }];
+  },
+});