@codemation/core-nodes 0.10.2 → 0.13.0

package/src/nodes/AgentToolResultContentFactory.ts

@@ -0,0 +1,155 @@
+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;
+  data?: unknown;
+  mimeType?: unknown;
+  uri?: unknown;
+  name?: unknown;
+  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);
+    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;
+  }
+
+  /**
+   * 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;
+    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/CallbackNodeFactory.ts

@@ -10,6 +10,7 @@ import type {
 } from "@codemation/core";
 
 import { CallbackNode } from "./CallbackNode";
+import type { NodeBaseOptions } from "./nodeOptions.types";
 
 export type CallbackHandler<
   TInputJson = unknown,
@@ -20,12 +21,12 @@ export type CallbackHandler<
   ctx: NodeExecutionContext<TConfig>,
 ) => Promise<Items<TOutputJson> | PortsEmission | void> | Items<TOutputJson> | PortsEmission | void;
 
-export type CallbackOptions = Readonly<{
-  id?: string;
-  retryPolicy?: RetryPolicySpec;
-  nodeErrorHandler?: NodeErrorHandlerSpec;
-  declaredOutputPorts?: ReadonlyArray<string>;
-}>;
+export type CallbackOptions = NodeBaseOptions &
+  Readonly<{
+    retryPolicy?: RetryPolicySpec;
+    nodeErrorHandler?: NodeErrorHandlerSpec;
+    declaredOutputPorts?: ReadonlyArray<string>;
+  }>;
 
 export class Callback<TInputJson = unknown, TOutputJson = TInputJson> implements RunnableNodeConfig<
   TInputJson,
@@ -37,6 +38,7 @@ export class Callback<TInputJson = unknown, TOutputJson = TInputJson> implements
   readonly icon = "lucide:braces" as const;
   readonly emptyBatchExecution = "runOnce" as const;
   readonly id?: string;
+  readonly description?: string;
   readonly retryPolicy?: RetryPolicySpec;
   readonly nodeErrorHandler?: NodeErrorHandlerSpec;
   readonly declaredOutputPorts?: ReadonlyArray<string>;
@@ -52,6 +54,7 @@ export class Callback<TInputJson = unknown, TOutputJson = TInputJson> implements
   ) {
     const resolvedOptions = typeof idOrOptions === "string" ? { ...options, id: idOrOptions } : idOrOptions;
     this.id = resolvedOptions?.id;
+    this.description = resolvedOptions?.description;
     this.retryPolicy = resolvedOptions?.retryPolicy;
     this.nodeErrorHandler = resolvedOptions?.nodeErrorHandler;
     this.declaredOutputPorts = resolvedOptions?.declaredOutputPorts;

package/src/nodes/CronTriggerFactory.ts

@@ -4,6 +4,7 @@ import { Cron } from "croner";
 import type { CronCallback } from "croner";
 
 import { CronTriggerNode } from "./CronTriggerNode";
+import type { NodeBaseOptions } from "./nodeOptions.types";
 
 export type CronTickJson = { firedAt: string; scheduledFor: string };
 
@@ -21,14 +22,17 @@ export class CronTrigger implements TriggerNodeConfig<CronTickJson> {
   readonly type: TypeToken<unknown> = CronTriggerNode;
   readonly icon = "lucide:clock" as const;
   readonly id?: string;
+  readonly description?: string;
 
   constructor(
     public readonly name: string,
     private readonly args: Readonly<{ schedule: string; timezone?: string }>,
-    id?: string,
+    idOrOptions?: string | NodeBaseOptions,
   ) {
     new Cron(args.schedule, { paused: true, timezone: args.timezone });
-    this.id = id;
+    const options = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+    this.id = options?.id;
+    this.description = options?.description;
   }
 
   get schedule(): string {

package/src/nodes/DeferredMetaToolStrategy.ts

@@ -1,5 +1,4 @@
 import type { ToolSet } from "ai";
-import { jsonSchema } from "ai";
 import { z } from "zod";
 import type { BM25Index } from "./BM25Index";
 import type {
@@ -37,6 +36,12 @@ export class DeferredMetaToolStrategy implements ToolLoadingStrategy {
   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(
     private readonly bm25: BM25Index,
@@ -44,6 +49,7 @@ export class DeferredMetaToolStrategy implements ToolLoadingStrategy {
   ) {}
 
   async initialize(input: ToolLoadingStrategyInitInput): Promise<void> {
+    this.jsonSchema = (await import("ai")).jsonSchema;
     this.nodeBackedTools = { ...input.nodeBackedTools };
 
     const pinnedIds = input.pinnedMcpTools ?? [];
@@ -194,7 +200,7 @@ export class DeferredMetaToolStrategy implements ToolLoadingStrategy {
         "After this call, the tools listed in the result will be callable on your very next turn. " +
         "Use this when you need a capability not visible in your current tool list. " +
         "Do not attempt to call a tool name you have not seen yet — use find_tools to discover it first.",
-      inputSchema: jsonSchema(inputSchemaRecord),
+      inputSchema: this.jsonSchema(inputSchemaRecord),
     } as unknown as ToolSet[string];
   }
 }

package/src/nodes/ManualTriggerFactory.ts

@@ -3,6 +3,7 @@ import type { Items, NodeInspectorSummaryRow, TriggerNodeConfig, TypeToken } fro
 import { ItemsInputNormalizer } from "@codemation/core";
 
 import { ManualTriggerNode } from "./ManualTriggerNode";
+import type { NodeBaseOptions } from "./nodeOptions.types";
 
 type ManualTriggerDefaultValue<TOutputJson> = Items<TOutputJson> | ReadonlyArray<TOutputJson> | TOutputJson;
 
@@ -13,18 +14,28 @@ export class ManualTrigger<TOutputJson = unknown> implements TriggerNodeConfig<T
   readonly icon = "lucide:play" as const;
   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, id?: string);
-  constructor(name: string, defaultItems: ManualTriggerDefaultValue<TOutputJson>, id?: string);
+  constructor(name?: string, idOrOptions?: string | NodeBaseOptions);
+  constructor(
+    name: string,
+    defaultItems: ManualTriggerDefaultValue<TOutputJson> | undefined,
+    idOrOptions?: string | NodeBaseOptions,
+  );
   constructor(
     public readonly name: string = "Manual trigger",
     defaultItemsOrId?: ManualTriggerDefaultValue<TOutputJson> | string,
-    id?: 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);
-    this.id = ManualTrigger.resolveId(defaultItemsOrId, id);
+    const trailing = idOrOptions ?? (typeof defaultItemsOrId === "string" ? defaultItemsOrId : undefined);
+    const options = typeof trailing === "string" ? { id: trailing } : (trailing ?? {});
+    this.id = options.id;
+    this.description = options.description;
   }
 
   private static resolveDefaultItems<TOutputJson>(
@@ -36,13 +47,6 @@ export class ManualTrigger<TOutputJson = unknown> implements TriggerNodeConfig<T
     return this.itemsInputNormalizer.normalize(value) as Items<TOutputJson>;
   }
 
-  private static resolveId<TOutputJson>(
-    value: ManualTriggerDefaultValue<TOutputJson> | string | undefined,
-    id: string | undefined,
-  ): string | undefined {
-    return typeof value === "string" ? value : id;
-  }
-
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> {
     const rows: NodeInspectorSummaryRow[] = [{ label: "Trigger", value: "manual" }];
     if (this.defaultItems && this.defaultItems.length > 0) {

package/src/nodes/WebhookTriggerFactory.ts

@@ -8,6 +8,7 @@ import type {
 } from "@codemation/core";
 import type { ZodType } from "zod";
 import { WebhookTriggerNode } from "./webhookTriggerNode";
+import type { NodeBaseOptions } from "./nodeOptions.types";
 
 type WebhookInputSchema = ZodType<any, any, any>;
 type WebhookTriggerHandler<TConfig extends WebhookTrigger<any> = WebhookTrigger<any>> = (
@@ -21,6 +22,8 @@ export class WebhookTrigger<
   readonly kind = "trigger" as const;
   readonly type: TypeToken<unknown> = WebhookTriggerNode;
   readonly icon = "lucide:globe";
+  readonly id?: string;
+  readonly description?: string;
 
   constructor(
     public readonly name: string,
@@ -32,8 +35,12 @@ export class WebhookTrigger<
     public readonly handler: WebhookTriggerHandler<
       WebhookTrigger<TSchema>
     > = WebhookTrigger.defaultHandler as WebhookTriggerHandler<WebhookTrigger<TSchema>>,
-    public readonly id?: string,
-  ) {}
+    idOrOptions?: string | NodeBaseOptions,
+  ) {
+    const options = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+    this.id = options?.id;
+    this.description = options?.description;
+  }
 
   get endpointKey(): string {
     return this.args.endpointKey;

package/src/nodes/aggregate.ts

@@ -6,6 +6,7 @@ import type {
   TypeToken,
 } from "@codemation/core";
 import { AggregateNode } from "./AggregateNode";
+import type { NodeBaseOptions } from "./nodeOptions.types";
 
 export class Aggregate<TIn = unknown, TOut = unknown> implements RunnableNodeConfig<TIn, TOut> {
   readonly kind = "node" as const;
@@ -13,6 +14,8 @@ export class Aggregate<TIn = unknown, TOut = unknown> implements RunnableNodeCon
   readonly execution = { hint: "local" } as const;
   readonly keepBinaries = true as const;
   readonly icon = "builtin:aggregate-rows" as const;
+  readonly id?: string;
+  readonly description?: string;
 
   constructor(
     public readonly name: string,
@@ -20,8 +23,12 @@ export class Aggregate<TIn = unknown, TOut = unknown> implements RunnableNodeCon
       items: Items<TIn>,
       ctx: NodeExecutionContext<Aggregate<TIn, TOut>>,
     ) => TOut | Promise<TOut>,
-    public readonly id?: string,
-  ) {}
+    idOrOptions?: string | NodeBaseOptions,
+  ) {
+    const options = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+    this.id = options?.id;
+    this.description = options?.description;
+  }
 
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined {
     const fnName = this.aggregate.name;

package/src/nodes/assertion.ts

@@ -13,6 +13,7 @@ export interface AssertionOptions<TInputJson> {
   readonly name?: string;
   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
@@ -35,6 +36,7 @@ export class Assertion<TInputJson = unknown> implements RunnableNodeConfig<TInpu
   readonly icon: string;
   readonly name: string;
   readonly id?: string;
+  readonly description?: string;
   readonly emitsAssertions = true as const;
   readonly assertions: AssertionOptions<TInputJson>["assertions"];
 
@@ -42,6 +44,7 @@ export class Assertion<TInputJson = unknown> implements RunnableNodeConfig<TInpu
     this.name = options.name ?? "Assertion";
     this.id = options.id;
     this.icon = options.icon ?? "lucide:check-circle";
+    this.description = options.description;
     this.assertions = options.assertions;
   }
 

package/src/nodes/filter.ts

@@ -7,12 +7,15 @@ import type {
   TypeToken,
 } from "@codemation/core";
 import { FilterNode } from "./FilterNode";
+import type { NodeBaseOptions } from "./nodeOptions.types";
 
 export class Filter<TIn = unknown> implements RunnableNodeConfig<TIn, TIn> {
   readonly kind = "node" as const;
   readonly type: TypeToken<unknown> = FilterNode;
   readonly execution = { hint: "local" } as const;
   readonly icon = "lucide:filter" as const;
+  readonly id?: string;
+  readonly description?: string;
 
   constructor(
     public readonly name: string,
@@ -22,8 +25,12 @@ export class Filter<TIn = unknown> implements RunnableNodeConfig<TIn, TIn> {
       items: Items<TIn>,
       ctx: NodeExecutionContext<Filter<TIn>>,
     ) => boolean,
-    public readonly id?: string,
-  ) {}
+    idOrOptions?: string | NodeBaseOptions,
+  ) {
+    const options = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+    this.id = options?.id;
+    this.description = options?.description;
+  }
 
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined {
     const fnName = this.predicate.name;

package/src/nodes/httpRequest.ts

@@ -62,6 +62,7 @@ export class HttpRequest<
   readonly type: TypeToken<unknown> = HttpRequestNode;
   readonly execution = { hint: "local" } as const;
   readonly icon = "lucide:globe" as const;
+  readonly description?: string;
 
   constructor(
     public readonly name: string,
@@ -136,9 +137,13 @@ export class HttpRequest<
        */
       allowedOutboundHosts?: ReadonlyArray<string>;
       id?: string;
+      /** Plain-language explanation surfaced in the node sidebar. */
+      description?: string;
     }> = {},
     public readonly retryPolicy: RetryPolicySpec = RetryPolicy.defaultForHttp,
-  ) {}
+  ) {
+    this.description = args.description;
+  }
 
   get id(): string | undefined {
     return this.args.id;

package/src/nodes/if.ts

@@ -7,6 +7,7 @@ import type {
   TypeToken,
 } from "@codemation/core";
 import { IfNode } from "./IfNode";
+import type { NodeBaseOptions } from "./nodeOptions.types";
 
 export class If<TInputJson = unknown> implements RunnableNodeConfig<TInputJson, TInputJson> {
   readonly kind = "node" as const;
@@ -14,6 +15,8 @@ export class If<TInputJson = unknown> implements RunnableNodeConfig<TInputJson,
   readonly execution = { hint: "local" } as const;
   readonly icon = "lucide:split@rot=90" as const;
   readonly declaredOutputPorts = ["true", "false"] as const;
+  readonly id?: string;
+  readonly description?: string;
   constructor(
     public readonly name: string,
     public readonly predicate: (
@@ -22,8 +25,12 @@ export class If<TInputJson = unknown> implements RunnableNodeConfig<TInputJson,
       items: Items<TInputJson>,
       ctx: NodeExecutionContext<If<TInputJson>>,
     ) => boolean,
-    public readonly id?: string,
-  ) {}
+    idOrOptions?: string | NodeBaseOptions,
+  ) {
+    const options = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+    this.id = options?.id;
+    this.description = options?.description;
+  }
 
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined {
     const fnName = this.predicate.name;

package/src/nodes/isTestRun.ts

@@ -1,6 +1,7 @@
 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`.
@@ -14,10 +15,13 @@ export class IsTestRun<TInputJson = unknown> implements RunnableNodeConfig<TInpu
   readonly declaredOutputPorts = ["true", "false"] as const;
   readonly name: string;
   readonly id?: string;
+  readonly description?: string;
 
-  constructor(name: string = "Is test run?", id?: string) {
+  constructor(name: string = "Is test run?", idOrOptions?: string | NodeBaseOptions) {
     this.name = name;
-    this.id = id;
+    const options = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+    this.id = options?.id;
+    this.description = options?.description;
   }
 }
 

package/src/nodes/mapData.ts

@@ -6,9 +6,9 @@ import type {
   TypeToken,
 } from "@codemation/core";
 import { MapDataNode } from "./MapDataNode";
+import type { NodeBaseOptions } from "./nodeOptions.types";
 
-export interface MapDataOptions {
-  readonly id?: string;
+export interface MapDataOptions extends NodeBaseOptions {
   readonly keepBinaries?: boolean;
 }
 
@@ -23,6 +23,7 @@ export class MapData<TInputJson = unknown, TOutputJson = unknown> implements Run
   readonly continueWhenEmptyOutput = true as const;
   readonly icon = "lucide:square-pen" as const;
   readonly keepBinaries: boolean;
+  readonly description?: string;
 
   constructor(
     public readonly name: string,
@@ -33,6 +34,7 @@ export class MapData<TInputJson = unknown, TOutputJson = unknown> implements Run
     private readonly options: MapDataOptions = {},
   ) {
     this.keepBinaries = options.keepBinaries ?? true;
+    this.description = options.description;
   }
 
   get id(): string | undefined {

package/src/nodes/merge.ts

@@ -1,5 +1,6 @@
 import type { InputPortKey, NodeInspectorSummaryRow, RunnableNodeConfig, TypeToken } from "@codemation/core";
 import { MergeNode } from "./MergeNode";
+import type { NodeBaseOptions } from "./nodeOptions.types";
 
 export type MergeMode = "passThrough" | "append" | "mergeByPosition";
 
@@ -10,6 +11,8 @@ export class Merge<TInputJson = unknown, TOutputJson = TInputJson> implements Ru
   readonly kind = "node" as const;
   readonly type: TypeToken<unknown> = MergeNode;
   readonly icon = "lucide:merge@rot=90" as const;
+  readonly id?: string;
+  readonly description?: string;
 
   constructor(
     public readonly name: string,
@@ -21,8 +24,12 @@ export class Merge<TInputJson = unknown, TOutputJson = TInputJson> implements Ru
        */
       prefer?: ReadonlyArray<InputPortKey>;
     }> = { mode: "passThrough" },
-    public readonly id?: string,
-  ) {}
+    idOrOptions?: string | NodeBaseOptions,
+  ) {
+    const options = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+    this.id = options?.id;
+    this.description = options?.description;
+  }
 
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> {
     const rows: NodeInspectorSummaryRow[] = [{ label: "Mode", value: this.cfg.mode }];

package/src/nodes/noOp.ts

@@ -1,16 +1,23 @@
 import type { RunnableNodeConfig, TypeToken } from "@codemation/core";
 import { NoOpNode } from "./NoOpNode";
+import type { NodeBaseOptions } from "./nodeOptions.types";
 
 export class NoOp<TItemJson = unknown> implements RunnableNodeConfig<TItemJson, TItemJson> {
   readonly kind = "node" as const;
   readonly type: TypeToken<unknown> = NoOpNode;
   readonly execution = { hint: "local" } as const;
   readonly icon = "lucide:circle-dashed" as const;
+  readonly id?: string;
+  readonly description?: string;
 
   constructor(
     public readonly name: string = "NoOp",
-    public readonly id?: string,
-  ) {}
+    idOrOptions?: string | NodeBaseOptions,
+  ) {
+    const options = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+    this.id = options?.id;
+    this.description = options?.description;
+  }
 }
 
 export { NoOpNode } from "./NoOpNode";

package/src/nodes/nodeOptions.types.ts

@@ -0,0 +1,12 @@
+/**
+ * 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/split.ts

@@ -6,6 +6,7 @@ import type {
   TypeToken,
 } from "@codemation/core";
 import { SplitNode } from "./SplitNode";
+import type { NodeBaseOptions } from "./nodeOptions.types";
 
 export class Split<TIn = unknown, TElem = unknown> implements RunnableNodeConfig<TIn, TElem> {
   readonly kind = "node" as const;
@@ -18,12 +19,18 @@ export class Split<TIn = unknown, TElem = unknown> implements RunnableNodeConfig
    */
   readonly continueWhenEmptyOutput = true as const;
   readonly icon = "builtin:split-rows" as const;
+  readonly id?: string;
+  readonly description?: string;
 
   constructor(
     public readonly name: string,
     public readonly getElements: (item: Item<TIn>, ctx: NodeExecutionContext<Split<TIn, TElem>>) => readonly TElem[],
-    public readonly id?: string,
-  ) {}
+    idOrOptions?: string | NodeBaseOptions,
+  ) {
+    const options = typeof idOrOptions === "string" ? { id: idOrOptions } : idOrOptions;
+    this.id = options?.id;
+    this.description = options?.description;
+  }
 
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined {
     const fnName = this.getElements.name;