@codemation/core-nodes 0.10.1 → 0.12.0

package/dist/index.d.cts

@@ -274,7 +274,6 @@ interface AssertionResult {
 }
 //#endregion
 //#region ../core/src/contracts/itemExpr.d.ts
-declare const ITEM_EXPR_BRAND: unique symbol;
 type ItemExprResolvedContext = Readonly<{
   runId: RunId;
   workflowId: WorkflowId;
@@ -294,7 +293,7 @@ type ItemExprArgs<TItemJson = unknown> = Readonly<{
 }>;
 type ItemExprCallback<T, TItemJson = unknown> = (args: ItemExprArgs<TItemJson>) => T | Promise<T>;
 type ItemExpr<T, TItemJson = unknown> = Readonly<{
-  readonly [ITEM_EXPR_BRAND]: true;
+  readonly __codemationItemExpr: "codemation.itemExpr";
   readonly fn: ItemExprCallback<T, TItemJson>;
 }>;
 //#endregion
@@ -628,6 +627,26 @@ type PortsEmission = Readonly<{
   readonly ports: Readonly<Partial<Record<OutputPortKey, Items | ReadonlyArray<JsonNonArray>>>>;
 }>;
 //#endregion
+//#region ../core/src/authoring/nodeBaseOptions.types.d.ts
+/**
+ * Core-local copy of the per-instance authoring options every `define*` factory's `create(...)`
+ * accepts in its trailing argument: a stable `id` plus a plain-language `description` (the
+ * non-technical "what does this step do" line surfaced in the node sidebar).
+ *
+ * `description` is a first-class option — passed inline exactly like `id` — and is threaded onto
+ * the config instance as an OWN ENUMERABLE field so it flows into the persisted workflow snapshot
+ * (`WorkflowSnapshotCodec` serializes via `JSON.parse(JSON.stringify(config))`, which only captures
+ * own enumerable properties — never a getter).
+ *
+ * `@codemation/core-nodes` declares an identical `NodeBaseOptions` for its bare-id built-in nodes;
+ * core keeps its own copy because core must not depend on `@codemation/core-nodes` (dependency
+ * direction). The two types are structurally identical by design.
+ */
+interface NodeBaseOptions$1 {
+  readonly id?: string;
+  readonly description?: string;
+}
+//#endregion
 //#region ../core/src/authoring/defineNode.types.d.ts
 type ResolvableCredentialType = AnyCredentialType | CredentialTypeId;
 type DefinedNodeCredentialBinding = ResolvableCredentialType | Readonly<{
@@ -644,7 +663,7 @@ interface DefinedNode<TKey$1 extends string, TConfig extends CredentialJsonRecor
   readonly key: TKey$1;
   readonly title: string;
   readonly description?: string;
-  create<TConfigItemJson = TInputJson$1>(config: DefinedNodeConfigInput<TConfig, TConfigItemJson>, name?: string, id?: string): RunnableNodeConfig<TInputJson$1, TOutputJson$1>;
+  create<TConfigItemJson = TInputJson$1>(config: DefinedNodeConfigInput<TConfig, TConfigItemJson>, name?: string, idOrOptions?: string | NodeBaseOptions$1): RunnableNodeConfig<TInputJson$1, TOutputJson$1>;
   register(context: {
     registerNode<TValue>(token: TypeToken<TValue>, implementation?: TypeToken<TValue>): void;
   }): void;
@@ -712,14 +731,44 @@ type BooleanWhenOverloads<TCurrentJson, TReturn> = {
 };
 //#endregion
 //#region ../core/src/workflow/dsl/WhenBuilder.d.ts
+/** Structurally identical to ChainCursorResolver's (unexported) ChainCursorEndpoint. */
+type WhenEndpoint = Readonly<{
+  node: NodeRef;
+  output: OutputPortKey;
+  inputPortHint?: InputPortKey;
+}>;
 declare class WhenBuilder<TCurrentJson> {
   private readonly wf;
   private readonly from;
   private readonly branchPort;
-  constructor(wf: WorkflowBuilder, from: NodeRef, branchPort: OutputPortKey);
+  /** Tails of arms added by earlier `.when(...)` calls in this chain. */
+  private readonly priorEndpoints;
+  /** Tail endpoint of the arm this builder added (set by addBranch). */
+  private armEndpoint;
+  constructor(wf: WorkflowBuilder, from: NodeRef, branchPort: OutputPortKey, /** Tails of arms added by earlier `.when(...)` calls in this chain. */
+  priorEndpoints?: ReadonlyArray<WhenEndpoint>);
   addBranch<TSteps extends ReadonlyArray<AnyRunnableNodeConfig>>(steps: TSteps & ValidStepSequence<TCurrentJson, TSteps>): this;
   readonly when: BooleanWhenOverloads<TCurrentJson, WhenBuilder<TCurrentJson>>;
+  /**
+   * Continue the trunk after a boolean `.when(...)` branch chain, auto-merging EVERY branch
+   * tail accumulated across the chain into the next node — the same fan-in the object form
+   * produces. Typed as `ChainCursor<TCurrentJson>` (the pre-branch item type): boolean arms
+   * carry no output guard so the merged item type is underdetermined — use the object form
+   * `.when({ true: [...], false: [...] })` when you need a precise merged type inline.
+   */
+  then<TOutputJson$1, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson$1>>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
+  /**
+   * Chainable human-approval step after a boolean `.when(...)` branch chain — merges every
+   * branch tail into the approval node. Mirrors `ChainCursor.humanApproval`.
+   */
+  humanApproval<TKey$1 extends string, TConfig extends Record<string, unknown>, TBindings extends DefinedNodeCredentialBindings | undefined = undefined>(node: DefinedHumanApprovalNode<TKey$1, TConfig, TCurrentJson & Record<string, unknown>, TBindings>, config: TConfig, metadata?: {
+    name?: string;
+    nodeId?: string;
+  }): ChainCursor<HumanApprovalOutputJson<TCurrentJson & Record<string, unknown>>>;
   build(): WorkflowDefinition;
+  /** Endpoints of every arm added so far in this chain (prior arms + this one). */
+  private get accumulatedEndpoints();
+  private toCursor;
 }
 //#endregion
 //#region ../core/src/workflow/dsl/ChainCursorResolver.d.ts
@@ -739,6 +788,12 @@ declare class ChainCursor<TCurrentJson> {
   private readonly endpoints;
   constructor(wf: WorkflowBuilder, endpoints: ReadonlyArray<ChainCursorEndpoint>);
   then<TOutputJson$1, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson$1>>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
+  /**
+   * Append a step whose output is MERGED onto `item.json` (shallow, output-wins) instead of
+   * replacing it — so earlier fields (e.g. trigger metadata) survive a transform/OCR/extraction
+   * node. Use for any node in a pipeline where you need data from before it.
+   */
+  thenMerge<TOutputJson$1, TConfig extends RunnableNodeConfig<TCurrentJson, TOutputJson$1>>(config: TConfig): ChainCursor<TCurrentJson & RunnableNodeOutputJson<TConfig>>;
   thenIntoInputHints<TOutputJson$1, TConfig extends RunnableNodeConfig<any, TOutputJson$1>>(config: TConfig): ChainCursor<RunnableNodeOutputJson<TConfig>>;
   readonly when: ChainCursorWhenOverloads<TCurrentJson>;
   route<TNextJson$1>(branches: Readonly<Record<OutputPortKey, (branch: ChainCursor<TCurrentJson>) => ChainCursor<TNextJson$1> | undefined>>): ChainCursor<TNextJson$1>;
@@ -929,6 +984,13 @@ interface NodeConfigBase {
   readonly name?: string;
   readonly id?: NodeId;
   readonly icon?: string;
+  /**
+   * Plain-language, non-technical explanation of what this node does, surfaced in the workflow
+   * inspector / node properties sidebar. A first-class config option every authorable node accepts
+   * directly (alongside `id`), so it flows into the persisted config the mappers read. Distinct from
+   * {@link inspectorSummary} (config-derived label/value rows).
+   */
+  readonly description?: string;
   readonly execution?: Readonly<{
     hint?: "local" | "worker";
     queue?: string;
@@ -1428,6 +1490,7 @@ declare class NodeBackedToolConfig<TNodeConfig extends RunnableNodeConfig<any, a
   readonly toolKind: "nodeBacked";
   readonly description?: string;
   readonly presentation?: AgentCanvasPresentation;
+  readonly onRejected?: "halt" | "return";
   private readonly inputSchemaValue;
   private readonly outputSchemaValue;
   private readonly mapInputValue?;
@@ -1589,6 +1652,13 @@ type NodeBackedToolConfigOptions<TNodeConfig extends RunnableNodeConfig<any, any
   outputSchema: TOutputSchema;
   mapInput?: NodeBackedToolInputMapper<TNodeConfig, input<TInputSchema>>;
   mapOutput?: NodeBackedToolOutputMapper<TNodeConfig, input<TInputSchema>, output<TOutputSchema>>;
+  /**
+   * Marks THIS tool binding as human-in-the-loop and sets the behavior when a human rejects the
+   * approval: `"return"` feeds the rejection back to the agent as a tool result, `"halt"` stops the
+   * run. Set per binding, so two tools backed by the same node can reject differently. When set, it
+   * takes precedence over any `humanApprovalToolBehavior` marker carried by the backing node.
+   */
+  onRejected?: "halt" | "return";
 }>;
 interface AgentNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown> extends RunnableNodeConfig<TInputJson$1, TOutputJson$1> {
   readonly messages: AgentMessageConfig<TInputJson$1>;
@@ -1638,10 +1708,12 @@ declare class ItemExprResolver {
 //#region ../core/src/execution/RunnableOutputBehaviorResolver.d.ts
 type RunnableOutputBehavior = Readonly<{
   keepBinaries: boolean;
+  mergeJson: boolean;
 }>;
 declare class RunnableOutputBehaviorResolver {
   resolve(config: RunnableNodeConfig): RunnableOutputBehavior;
   private isKeepBinariesEnabled;
+  private isMergeJsonEnabled;
 }
 //#endregion
 //#region ../core/src/execution/NodeOutputNormalizer.d.ts
@@ -1655,6 +1727,7 @@ declare class NodeOutputNormalizer {
   private emitPortsToOutputs;
   private normalizePortPayload;
   private isItemLike;
+  private isPlainJsonObject;
   private applyOutput;
 }
 //#endregion
@@ -1670,7 +1743,13 @@ type HttpBodySpec = Readonly<{
   kind: "none";
 }> | Readonly<{
   kind: "json";
-  data: unknown;
+  /**
+   * 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>>;
@@ -2207,37 +2286,25 @@ declare const openAiChatModelPresets: OpenAiChatModelPresets;
 //#endregion
 //#region src/chatModels/CodemationChatModelConfig.d.ts
 /**
- * A platform-managed model entry as returned by GET /api/llm/managed-models.
+ * Complexity token sent to the managed LLM broker.
+ * The broker maps this to a concrete provider model and thinking effort.
+ * low    = cheapest/fastest (short classification, simple extraction)
+ * medium = default for most extraction/agent work
+ * high   = complex multi-step reasoning
+ * xhigh  = hardest problems, most capable model
  */
-interface ManagedModelDto {
-  id: string;
-  modelId: string;
-  displayName: string;
-  providerKey: string;
-  inputCostPerMTok: number;
-  outputCostPerMTok: number;
-  contextWindow: number;
-  tier: string;
-}
-/**
- * Bifrost-namespaced model ID. Kept as `string` so runtime-fetched model IDs
- * (from the CP allowlist) work without compile-time enumeration.
- * Story C replaced the prior hardcoded union with this open type.
- */
-type CodemationManagedModel = string;
+type ManagedComplexity = "low" | "medium" | "high" | "xhigh";
 declare class CodemationChatModelConfig implements ChatModelConfig {
   readonly name: string;
-  readonly model: CodemationManagedModel;
+  readonly complexity: ManagedComplexity;
   readonly options?: Readonly<{
-    temperature?: number;
     maxTokens?: number;
   }> | undefined;
   readonly type: typeof CodemationChatModelFactory;
   readonly presentation: AgentCanvasPresentation<CanvasIconName>;
   readonly provider = "codemation-managed";
   readonly modelName: string;
-  constructor(name: string, model: CodemationManagedModel, presentationIn?: AgentCanvasPresentation<CanvasIconName>, options?: Readonly<{
-    temperature?: number;
+  constructor(name: string, complexity: ManagedComplexity, presentationIn?: AgentCanvasPresentation<CanvasIconName>, options?: Readonly<{
     maxTokens?: number;
   }> | undefined);
 }
@@ -2250,17 +2317,6 @@ declare class CodemationChatModelFactory implements ChatModelFactory<CodemationC
   }>): Promise<ChatLanguageModel>;
 }
 //#endregion
-//#region src/chatModels/ManagedModelFetcher.d.ts
-/**
- * Fetches the active platform-managed model allowlist from the CP.
- * Reads CONTROL_PLANE_URL from the workspace process env.
- * Returns an empty array if the env var is absent or the fetch fails.
- * Cache the result per session — the allowlist changes infrequently.
- */
-declare class ManagedModelFetcher {
-  fetch(): Promise<ManagedModelDto[]>;
-}
-//#endregion
 //#region src/nodes/aiAgentSupport.types.d.ts
 declare class AgentItemPortMap {
   static fromItem(item: Item): NodeInputsByPort;
@@ -2455,6 +2511,7 @@ interface AIAgentOptions<TInputJson$1 = unknown, _TOutputJson = unknown> {
   readonly chatModel: ChatModelConfig;
   readonly tools?: ReadonlyArray<ToolConfig>;
   readonly id?: string;
+  readonly description?: string;
   readonly retryPolicy?: RetryPolicySpec;
   readonly guardrails?: AgentGuardrailConfig;
   /** Engine applies with {@link RunnableNodeConfig.inputSchema} before {@link AIAgentNode.execute}. */
@@ -2484,6 +2541,21 @@ interface AIAgentOptions<TInputJson$1 = unknown, _TOutputJson = unknown> {
    * 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 binaries?: ReadonlyArray<BinaryAttachment> | ((args: AgentMessageBuildArgs<TInputJson$1>) => ReadonlyArray<BinaryAttachment>);
 }
 /**
  * AI agent: credential bindings are keyed to connection-owned LLM/tool node ids (ConnectionNodeIdFactory),
@@ -2501,6 +2573,7 @@ declare class AIAgent<TInputJson$1 = unknown, TOutputJson$1 = unknown> implement
   readonly chatModel: ChatModelConfig;
   readonly tools: ReadonlyArray<ToolConfig>;
   readonly id?: string;
+  readonly description?: string;
   readonly retryPolicy: RetryPolicySpec;
   readonly guardrails?: AgentGuardrailConfig;
   readonly inputSchema?: ZodType<TInputJson$1>;
@@ -2508,6 +2581,8 @@ declare class AIAgent<TInputJson$1 = unknown, TOutputJson$1 = unknown> implement
   readonly mcpServers?: ReadonlyArray<string>;
   readonly pinnedMcpTools?: readonly string[];
   readonly untrustedSources?: ReadonlyArray<string>;
+  readonly passBinariesToModel?: boolean;
+  readonly binaries?: ReadonlyArray<BinaryAttachment> | ((args: AgentMessageBuildArgs<TInputJson$1>) => ReadonlyArray<BinaryAttachment>);
   constructor(options: AIAgentOptions<TInputJson$1, TOutputJson$1>);
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow>;
 }
@@ -2644,8 +2719,17 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   readonly inputSchema: z.ZodUnknown;
   private readonly connectionCredentialExecutionContextFactory;
   private readonly preparedByExecutionContext;
+  /**
+   * The `ai` SDK, loaded lazily in {@link execute} so the SDK (~28MB RSS) stays
+   * off the boot path — non-AI workflows never load it. Every path runs through
+   * `execute` → `ensureAiSdk` before any sync helper touches `this.aiSdk`.
+   */
+  private aiSdk;
+  private aiSdkPromise;
   constructor(nodeResolver: NodeResolver, credentialSessions: CredentialSessionService, nodeBackedToolRuntime: NodeBackedToolRuntime, executionHelpers: AIAgentExecutionHelpersFactory, structuredOutputRunner: AgentStructuredOutputRunner, toolExecutionCoordinator: AgentToolExecutionCoordinator, toolLoadingStrategyFactory: DeferredMetaToolStrategyFactory, agentMcpIntegration: AgentMcpIntegration);
   execute(args: RunnableNodeExecuteArgs<AIAgent<any, any>>): Promise<unknown>;
+  /** Load the `ai` SDK once per node instance (cached promise guards concurrent items). */
+  private ensureAiSdk;
   /**
    * Resume path: re-enters the agent loop after a HITL suspension.
    * Reconstructs the conversation from the checkpoint, injects the human decision
@@ -2680,8 +2764,10 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   private resolveTools;
   private createItemScopedTools;
   /**
-   * Detects whether a tool config is backed by a `defineHumanApprovalNode` marker
-   * and returns the HITL behavior config, or `undefined` when not a HITL tool.
+   * Resolves the HITL behavior for a tool binding, or `undefined` when it is not a HITL tool.
+   * A binding is HITL if either the backing node carries a `defineHumanApprovalNode` marker or the
+   * binding sets a per-binding `onRejected` via `asTool(..., { onRejected })`. The per-binding value
+   * wins over the node marker, so two tools backed by the same node can reject differently.
    */
   private resolveHumanApprovalBehavior;
   /**
@@ -2752,6 +2838,22 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   private summarizeLlmMessages;
   private resultToJsonValue;
   private createPromptMessages;
+  /**
+   * Picks which attachments feed the passdown. When the author supplies `config.binaries`
+   * (a static array or a per-item function — e.g. to forward binaries from an earlier node),
+   * those replace the current item's attachments; otherwise the current item's `item.binary`
+   * is used.
+   */
+  private selectBinaryAttachments;
+  /**
+   * Reads every attachment through `ctx.binary` (storage-backed, by reference — never base64 on
+   * `item.json`) and resolves it to inline base64 so the agent can pass it to the chat model as a
+   * native multimodal block. Images become image blocks; every other type (PDF, office docs, CSV,
+   * JSON, …) becomes a file block — we don't filter by media type, so any binary can be fed to the
+   * model. If the provider rejects an unsupported type the error surfaces at runtime, and the
+   * workflow can filter the binary upstream.
+   */
+  private resolveInlineBinaries;
   /**
    * When `item.json.__source` matches an entry in `config.untrustedSources`
    * (default: `["gmail", "ocr", "webhook"]`), wraps every user-role message
@@ -2812,6 +2914,12 @@ declare class DeferredMetaToolStrategy implements ToolLoadingStrategy {
   private mcpEntries;
   private toolsByServerId;
   private foundToolIds;
+  /**
+   * `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;
   constructor(bm25: BM25Index, warnFn: (message: string) => void);
   initialize(input: ToolLoadingStrategyInitInput): Promise<void>;
   getToolsForTurn(context: ToolLoadingStrategyTurnContext): ToolSet;
@@ -2845,6 +2953,7 @@ interface AssertionOptions<TInputJson$1> {
   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
@@ -2863,12 +2972,27 @@ declare class Assertion<TInputJson$1 = unknown> implements RunnableNodeConfig<TI
   readonly icon: string;
   readonly name: string;
   readonly id?: string;
+  readonly description?: string;
   readonly emitsAssertions: true;
   readonly assertions: AssertionOptions<TInputJson$1>["assertions"];
   constructor(options: AssertionOptions<TInputJson$1>);
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined;
 }
 //#endregion
+//#region src/nodes/nodeOptions.types.d.ts
+/**
+ * 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.
+ */
+interface NodeBaseOptions {
+  readonly id?: string;
+  readonly description?: string;
+}
+//#endregion
 //#region src/nodes/CallbackNode.d.ts
 declare class CallbackNode implements RunnableNode<Callback<any, any>> {
   kind: "node";
@@ -2883,8 +3007,7 @@ declare class CallbackResultNormalizer {
 //#endregion
 //#region src/nodes/CallbackNodeFactory.d.ts
 type CallbackHandler<TInputJson$1 = unknown, TOutputJson$1 = TInputJson$1, TConfig extends Callback<TInputJson$1, TOutputJson$1> = Callback<TInputJson$1, TOutputJson$1>> = (items: Items<TInputJson$1>, ctx: NodeExecutionContext<TConfig>) => Promise<Items<TOutputJson$1> | PortsEmission | void> | Items<TOutputJson$1> | PortsEmission | void;
-type CallbackOptions = Readonly<{
-  id?: string;
+type CallbackOptions = NodeBaseOptions & Readonly<{
   retryPolicy?: RetryPolicySpec;
   nodeErrorHandler?: NodeErrorHandlerSpec;
   declaredOutputPorts?: ReadonlyArray<string>;
@@ -2900,6 +3023,7 @@ declare class Callback<TInputJson$1 = unknown, TOutputJson$1 = TInputJson$1> imp
   readonly icon: "lucide:braces";
   readonly emptyBatchExecution: "runOnce";
   readonly id?: string;
+  readonly description?: string;
   readonly retryPolicy?: RetryPolicySpec;
   readonly nodeErrorHandler?: NodeErrorHandlerSpec;
   readonly declaredOutputPorts?: ReadonlyArray<string>;
@@ -2972,7 +3096,7 @@ declare class HttpRequest<TInputJson$1 = Readonly<{
     headers?: Readonly<Record<string, string>>;
     /** Query parameters to append to the URL. */
     query?: Readonly<Record<string, string>>;
-    /** Request body specification. For canvas use, pass a JSON string in `body.data`. */
+    /** 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.
@@ -3032,6 +3156,8 @@ declare class HttpRequest<TInputJson$1 = Readonly<{
      */
     allowedOutboundHosts?: ReadonlyArray<string>;
     id?: string;
+    /** Plain-language explanation surfaced in the node sidebar. */
+    description?: string;
   }>;
   readonly retryPolicy: RetryPolicySpec;
   readonly kind: "node";
@@ -3040,6 +3166,7 @@ declare class HttpRequest<TInputJson$1 = Readonly<{
     readonly hint: "local";
   };
   readonly icon: "lucide:globe";
+  readonly description?: string;
   constructor(name: string, args?: Readonly<{
     /** HTTP method (default: GET). */
     method?: string;
@@ -3054,7 +3181,7 @@ declare class HttpRequest<TInputJson$1 = Readonly<{
     headers?: Readonly<Record<string, string>>;
     /** Query parameters to append to the URL. */
     query?: Readonly<Record<string, string>>;
-    /** Request body specification. For canvas use, pass a JSON string in `body.data`. */
+    /** 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.
@@ -3114,6 +3241,8 @@ declare class HttpRequest<TInputJson$1 = Readonly<{
      */
     allowedOutboundHosts?: ReadonlyArray<string>;
     id?: string;
+    /** Plain-language explanation surfaced in the node sidebar. */
+    description?: string;
   }>, retryPolicy?: RetryPolicySpec);
   get id(): string | undefined;
   get method(): string;
@@ -3139,7 +3268,6 @@ declare class AggregateNode implements RunnableNode<Aggregate<any, any>> {
 declare class Aggregate<TIn = unknown, TOut = unknown> implements RunnableNodeConfig<TIn, TOut> {
   readonly name: string;
   readonly aggregate: (items: Items<TIn>, ctx: NodeExecutionContext<Aggregate<TIn, TOut>>) => TOut | Promise<TOut>;
-  readonly id?: string | undefined;
   readonly kind: "node";
   readonly type: TypeToken<unknown>;
   readonly execution: {
@@ -3147,7 +3275,9 @@ declare class Aggregate<TIn = unknown, TOut = unknown> implements RunnableNodeCo
   };
   readonly keepBinaries: true;
   readonly icon: "builtin:aggregate-rows";
-  constructor(name: string, aggregate: (items: Items<TIn>, ctx: NodeExecutionContext<Aggregate<TIn, TOut>>) => TOut | Promise<TOut>, id?: string | undefined);
+  readonly id?: string;
+  readonly description?: string;
+  constructor(name: string, aggregate: (items: Items<TIn>, ctx: NodeExecutionContext<Aggregate<TIn, TOut>>) => TOut | Promise<TOut>, idOrOptions?: string | NodeBaseOptions);
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined;
 }
 //#endregion
@@ -3162,14 +3292,15 @@ declare class FilterNode implements RunnableNode<Filter<any>> {
 declare class Filter<TIn = unknown> implements RunnableNodeConfig<TIn, TIn> {
   readonly name: string;
   readonly predicate: (item: Item<TIn>, index: number, items: Items<TIn>, ctx: NodeExecutionContext<Filter<TIn>>) => boolean;
-  readonly id?: string | undefined;
   readonly kind: "node";
   readonly type: TypeToken<unknown>;
   readonly execution: {
     readonly hint: "local";
   };
   readonly icon: "lucide:filter";
-  constructor(name: string, predicate: (item: Item<TIn>, index: number, items: Items<TIn>, ctx: NodeExecutionContext<Filter<TIn>>) => boolean, id?: string | undefined);
+  readonly id?: string;
+  readonly description?: string;
+  constructor(name: string, predicate: (item: Item<TIn>, index: number, items: Items<TIn>, ctx: NodeExecutionContext<Filter<TIn>>) => boolean, idOrOptions?: string | NodeBaseOptions);
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined;
 }
 //#endregion
@@ -3183,7 +3314,6 @@ declare class IfNode implements RunnableNode<If<any>> {
 declare class If<TInputJson$1 = unknown> implements RunnableNodeConfig<TInputJson$1, TInputJson$1> {
   readonly name: string;
   readonly predicate: (item: Item<TInputJson$1>, index: number, items: Items<TInputJson$1>, ctx: NodeExecutionContext<If<TInputJson$1>>) => boolean;
-  readonly id?: string | undefined;
   readonly kind: "node";
   readonly type: TypeToken<unknown>;
   readonly execution: {
@@ -3191,7 +3321,9 @@ declare class If<TInputJson$1 = unknown> implements RunnableNodeConfig<TInputJso
   };
   readonly icon: "lucide:split@rot=90";
   readonly declaredOutputPorts: readonly ["true", "false"];
-  constructor(name: string, predicate: (item: Item<TInputJson$1>, index: number, items: Items<TInputJson$1>, ctx: NodeExecutionContext<If<TInputJson$1>>) => boolean, id?: string | undefined);
+  readonly id?: string;
+  readonly description?: string;
+  constructor(name: string, predicate: (item: Item<TInputJson$1>, index: number, items: Items<TInputJson$1>, ctx: NodeExecutionContext<If<TInputJson$1>>) => boolean, idOrOptions?: string | NodeBaseOptions);
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined;
 }
 //#endregion
@@ -3224,7 +3356,8 @@ declare class IsTestRun<TInputJson$1 = unknown> implements RunnableNodeConfig<TI
   readonly declaredOutputPorts: readonly ["true", "false"];
   readonly name: string;
   readonly id?: string;
-  constructor(name?: string, id?: string);
+  readonly description?: string;
+  constructor(name?: string, idOrOptions?: string | NodeBaseOptions);
 }
 //#endregion
 //#region src/nodes/SwitchNode.d.ts
@@ -3245,7 +3378,6 @@ declare class Switch<TInputJson$1 = unknown> implements RunnableNodeConfig<TInpu
     defaultCase: string;
     resolveCaseKey: SwitchCaseKeyResolver<TInputJson$1>;
   }>;
-  readonly id?: string | undefined;
   readonly kind: "node";
   readonly type: TypeToken<unknown>;
   readonly execution: {
@@ -3253,11 +3385,13 @@ declare class Switch<TInputJson$1 = unknown> implements RunnableNodeConfig<TInpu
   };
   readonly icon: "lucide:git-branch-plus";
   readonly declaredOutputPorts: ReadonlyArray<string>;
+  readonly id?: string;
+  readonly description?: string;
   constructor(name: string, cfg: Readonly<{
     cases: readonly string[];
     defaultCase: string;
     resolveCaseKey: SwitchCaseKeyResolver<TInputJson$1>;
-  }>, id?: string | undefined);
+  }>, idOrOptions?: string | NodeBaseOptions);
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow>;
 }
 //#endregion
@@ -3272,7 +3406,6 @@ declare class SplitNode implements RunnableNode<Split<any, any>> {
 declare class Split<TIn = unknown, TElem = unknown> implements RunnableNodeConfig<TIn, TElem> {
   readonly name: string;
   readonly getElements: (item: Item<TIn>, ctx: NodeExecutionContext<Split<TIn, TElem>>) => readonly TElem[];
-  readonly id?: string | undefined;
   readonly kind: "node";
   readonly type: TypeToken<unknown>;
   readonly execution: {
@@ -3285,7 +3418,9 @@ declare class Split<TIn = unknown, TElem = unknown> implements RunnableNodeConfi
    */
   readonly continueWhenEmptyOutput: true;
   readonly icon: "builtin:split-rows";
-  constructor(name: string, getElements: (item: Item<TIn>, ctx: NodeExecutionContext<Split<TIn, TElem>>) => readonly TElem[], id?: string | undefined);
+  readonly id?: string;
+  readonly description?: string;
+  constructor(name: string, getElements: (item: Item<TIn>, ctx: NodeExecutionContext<Split<TIn, TElem>>) => readonly TElem[], idOrOptions?: string | NodeBaseOptions);
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined;
 }
 //#endregion
@@ -3310,10 +3445,11 @@ declare class CronTrigger implements TriggerNodeConfig<CronTickJson> {
   readonly type: TypeToken<unknown>;
   readonly icon: "lucide:clock";
   readonly id?: string;
+  readonly description?: string;
   constructor(name: string, args: Readonly<{
     schedule: string;
     timezone?: string;
-  }>, id?: string);
+  }>, idOrOptions?: string | NodeBaseOptions);
   get schedule(): string;
   get timezone(): string | undefined;
   createJob(callback: CronCallback): Cron;
@@ -3353,12 +3489,12 @@ declare class ManualTrigger<TOutputJson$1 = unknown> implements TriggerNodeConfi
   readonly icon: "lucide:play";
   readonly defaultItems?: Items<TOutputJson$1>;
   readonly id?: string;
+  readonly description?: string;
   /** Manual runs often emit an empty batch; still schedule downstream by default. */
   readonly continueWhenEmptyOutput: true;
-  constructor(name?: string, id?: string);
-  constructor(name: string, defaultItems: ManualTriggerDefaultValue<TOutputJson$1>, id?: string);
+  constructor(name?: string, idOrOptions?: string | NodeBaseOptions);
+  constructor(name: string, defaultItems: ManualTriggerDefaultValue<TOutputJson$1> | undefined, idOrOptions?: string | NodeBaseOptions);
   private static resolveDefaultItems;
-  private static resolveId;
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow>;
 }
 //#endregion
@@ -3371,8 +3507,7 @@ declare class MapDataNode implements RunnableNode<MapData<any, any>> {
 }
 //#endregion
 //#region src/nodes/mapData.d.ts
-interface MapDataOptions {
-  readonly id?: string;
+interface MapDataOptions extends NodeBaseOptions {
   readonly keepBinaries?: boolean;
 }
 declare class MapData<TInputJson$1 = unknown, TOutputJson$1 = unknown> implements RunnableNodeConfig<TInputJson$1, TOutputJson$1> {
@@ -3388,6 +3523,7 @@ declare class MapData<TInputJson$1 = unknown, TOutputJson$1 = unknown> implement
   readonly continueWhenEmptyOutput: true;
   readonly icon: "lucide:square-pen";
   readonly keepBinaries: boolean;
+  readonly description?: string;
   constructor(name: string, map: (item: Item<TInputJson$1>, ctx: NodeExecutionContext<MapData<TInputJson$1, TOutputJson$1>>) => TOutputJson$1, options?: MapDataOptions);
   get id(): string | undefined;
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow> | undefined;
@@ -3412,10 +3548,11 @@ declare class Merge<TInputJson$1 = unknown, TOutputJson$1 = TInputJson$1> implem
      */
     prefer?: ReadonlyArray<InputPortKey>;
   }>;
-  readonly id?: string | undefined;
   readonly kind: "node";
   readonly type: TypeToken<unknown>;
   readonly icon: "lucide:merge@rot=90";
+  readonly id?: string;
+  readonly description?: string;
   constructor(name: string, cfg?: Readonly<{
     mode: MergeMode;
     /**
@@ -3423,7 +3560,7 @@ declare class Merge<TInputJson$1 = unknown, TOutputJson$1 = TInputJson$1> implem
      * Any inputs not listed are appended in lexicographic order.
      */
     prefer?: ReadonlyArray<InputPortKey>;
-  }>, id?: string | undefined);
+  }>, idOrOptions?: string | NodeBaseOptions);
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow>;
 }
 //#endregion
@@ -3437,14 +3574,15 @@ declare class NoOpNode implements RunnableNode<NoOp<any>> {
 //#region src/nodes/noOp.d.ts
 declare class NoOp<TItemJson = unknown> implements RunnableNodeConfig<TItemJson, TItemJson> {
   readonly name: string;
-  readonly id?: string | undefined;
   readonly kind: "node";
   readonly type: TypeToken<unknown>;
   readonly execution: {
     readonly hint: "local";
   };
   readonly icon: "lucide:circle-dashed";
-  constructor(name?: string, id?: string | undefined);
+  readonly id?: string;
+  readonly description?: string;
+  constructor(name?: string, idOrOptions?: string | NodeBaseOptions);
 }
 //#endregion
 //#region src/nodes/SubWorkflowNode.d.ts
@@ -3464,13 +3602,14 @@ declare class SubWorkflow<TInputJson$1 = unknown, TOutputJson$1 = unknown> imple
     nodeId: NodeId;
   } | UpstreamRefPlaceholder> | undefined;
   readonly startAt?: NodeId | undefined;
-  readonly id?: string | undefined;
   readonly kind: "node";
   readonly type: TypeToken<unknown>;
   readonly icon = "lucide:workflow";
+  readonly id?: string;
+  readonly description?: string;
   constructor(name: string, workflowId: string, upstreamRefs?: Array<{
     nodeId: NodeId;
-  } | UpstreamRefPlaceholder> | undefined, startAt?: NodeId | undefined, id?: string | undefined);
+  } | UpstreamRefPlaceholder> | undefined, startAt?: NodeId | undefined, idOrOptions?: string | NodeBaseOptions);
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow>;
 }
 //#endregion
@@ -3556,7 +3695,6 @@ declare class WaitNode implements RunnableNode<Wait<any>> {
 declare class Wait<TItemJson = unknown> implements RunnableNodeConfig<TItemJson, TItemJson> {
   readonly name: string;
   readonly milliseconds: number;
-  readonly id?: string | undefined;
   readonly kind: "node";
   readonly type: TypeToken<unknown>;
   readonly execution: {
@@ -3565,7 +3703,9 @@ declare class Wait<TItemJson = unknown> implements RunnableNodeConfig<TItemJson,
   /** Pass-through empty batches should still advance to downstream nodes. */
   readonly continueWhenEmptyOutput: true;
   readonly icon: "lucide:hourglass";
-  constructor(name: string, milliseconds: number, id?: string | undefined);
+  readonly id?: string;
+  readonly description?: string;
+  constructor(name: string, milliseconds: number, idOrOptions?: string | NodeBaseOptions);
   inspectorSummary(): ReadonlyArray<NodeInspectorSummaryRow>;
 }
 //#endregion
@@ -3593,15 +3733,16 @@ declare class WebhookTrigger<TSchema extends WebhookInputSchema | undefined = un
   readonly name: string;
   private readonly args;
   readonly handler: WebhookTriggerHandler<WebhookTrigger<TSchema>>;
-  readonly id?: string | undefined;
   readonly kind: "trigger";
   readonly type: TypeToken<unknown>;
   readonly icon = "lucide:globe";
+  readonly id?: string;
+  readonly description?: string;
   constructor(name: string, args: Readonly<{
     endpointKey: string;
     methods: ReadonlyArray<HttpMethod>;
     inputSchema?: TSchema;
-  }>, handler?: WebhookTriggerHandler<WebhookTrigger<TSchema>>, id?: string | undefined);
+  }>, handler?: WebhookTriggerHandler<WebhookTrigger<TSchema>>, idOrOptions?: string | NodeBaseOptions);
   get endpointKey(): string;
   get methods(): ReadonlyArray<HttpMethod>;
   get inputSchema(): TSchema | undefined;
@@ -3915,5 +4056,5 @@ declare const codemationDocumentScannerNode: DefinedNode<"codemation.document-sc
   fields: Readonly<Record<string, DocScannerField>>;
 }>, undefined>;
 //#endregion
-export { AIAgent, AIAgentConnectionWorkflowExpander, AIAgentExecutionHelpersFactory, AIAgentNode, AgentItemPortMap, AgentMessageFactory, AgentOutputFactory, AgentStructuredOutputRepairPromptFactory, AgentStructuredOutputRunner, AgentToolCallPortMap, AgentToolErrorClassifier, AgentToolExecutionCoordinator, AgentToolRepairExhaustedError, AgentToolRepairPolicy, Aggregate, AggregateNode, Assertion, AssertionNode, AssertionOptions, BM25Index, BinaryRef, Callback, CallbackHandler, CallbackNode, CallbackOptions, CallbackResultNormalizer, CanvasIconName, CodemationChatModelConfig, CodemationChatModelFactory, CodemationDocumentScannerConfig, CodemationManagedModel, ConnectionCredentialExecutionContextFactory, ConnectionCredentialNode, ConnectionCredentialNodeConfig, ConnectionCredentialNodeConfigFactory, CredentialSession, CronTickJson, CronTrigger, CronTriggerNode, DeferredMetaToolStrategy, DeferredMetaToolStrategyFactory, DefineRestNodeOptions, DocScannerAnalyzerType, DocScannerField, DocScannerOutput, ExecutedToolCall, Filter, FilterNode, FindToolsResult, HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES, HttpBodySpec, HttpCredentialDelta, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, HttpRequestResult, HttpRequestSpec, If, IfNode, IsTestRun, IsTestRunNode, ItemScopedToolBinding, ManagedModelDto, ManagedModelFetcher, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, MapDataOptions, Merge, MergeMode, MergeNode, NoOp, NoOpNode, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAiChatModelPresets, OpenAiCredentialSession, OpenAiStrictJsonSchemaFactory, PlannedToolCall, ResolvedTool, RestNodeApi, RestNodeErrorPolicy, RestNodeRequestShape, RestNodeResponseContext, SSRFBlockedError, Split, SplitNode, SsrfGuard, SubWorkflow, SubWorkflowNode, Switch, SwitchCaseKeyResolver, SwitchNode, TestTrigger, TestTriggerNode, TestTriggerOptions, ToolLoadingStrategy, ToolLoadingStrategyInitInput, ToolLoadingStrategyTurnContext, Wait, WaitDuration, WaitNode, WebhookRespondNowAndContinueError, WebhookRespondNowError, WebhookTrigger, WebhookTriggerNode, type WorkflowAgentMessages, type WorkflowAgentOptions, WorkflowAuthoringBuilder, WorkflowBranchBuilder, WorkflowChain, apiKeyCredentialType, basicAuthCredentialType, bearerTokenCredentialType, codemationDocumentScannerNode, collectionDeleteNode, collectionFindOneNode, collectionGetNode, collectionInsertNode, collectionListNode, collectionUpdateNode, createWorkflowBuilder, defineRestNode, inboxApproval, oauth2ClientCredentialsType, openAiChatModelPresets, registerCoreNodes, workflow };
+export { AIAgent, AIAgentConnectionWorkflowExpander, AIAgentExecutionHelpersFactory, AIAgentNode, AgentItemPortMap, AgentMessageFactory, AgentOutputFactory, AgentStructuredOutputRepairPromptFactory, AgentStructuredOutputRunner, AgentToolCallPortMap, AgentToolErrorClassifier, AgentToolExecutionCoordinator, AgentToolRepairExhaustedError, AgentToolRepairPolicy, Aggregate, AggregateNode, Assertion, AssertionNode, AssertionOptions, BM25Index, BinaryRef, Callback, CallbackHandler, CallbackNode, CallbackOptions, CallbackResultNormalizer, CanvasIconName, CodemationChatModelConfig, CodemationChatModelFactory, CodemationDocumentScannerConfig, ConnectionCredentialExecutionContextFactory, ConnectionCredentialNode, ConnectionCredentialNodeConfig, ConnectionCredentialNodeConfigFactory, CredentialSession, CronTickJson, CronTrigger, CronTriggerNode, DeferredMetaToolStrategy, DeferredMetaToolStrategyFactory, DefineRestNodeOptions, DocScannerAnalyzerType, DocScannerField, DocScannerOutput, ExecutedToolCall, Filter, FilterNode, FindToolsResult, HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES, HttpBodySpec, HttpCredentialDelta, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, HttpRequestResult, HttpRequestSpec, If, IfNode, IsTestRun, IsTestRunNode, ItemScopedToolBinding, ManagedComplexity, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, MapDataOptions, Merge, MergeMode, MergeNode, NoOp, NoOpNode, NodeBaseOptions, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAiChatModelPresets, OpenAiCredentialSession, OpenAiStrictJsonSchemaFactory, PlannedToolCall, ResolvedTool, RestNodeApi, RestNodeErrorPolicy, RestNodeRequestShape, RestNodeResponseContext, SSRFBlockedError, Split, SplitNode, SsrfGuard, SubWorkflow, SubWorkflowNode, Switch, SwitchCaseKeyResolver, SwitchNode, TestTrigger, TestTriggerNode, TestTriggerOptions, ToolLoadingStrategy, ToolLoadingStrategyInitInput, ToolLoadingStrategyTurnContext, Wait, WaitDuration, WaitNode, WebhookRespondNowAndContinueError, WebhookRespondNowError, WebhookTrigger, WebhookTriggerNode, type WorkflowAgentMessages, type WorkflowAgentOptions, WorkflowAuthoringBuilder, WorkflowBranchBuilder, WorkflowChain, apiKeyCredentialType, basicAuthCredentialType, bearerTokenCredentialType, codemationDocumentScannerNode, collectionDeleteNode, collectionFindOneNode, collectionGetNode, collectionInsertNode, collectionListNode, collectionUpdateNode, createWorkflowBuilder, defineRestNode, inboxApproval, oauth2ClientCredentialsType, openAiChatModelPresets, registerCoreNodes, workflow };
 //# sourceMappingURL=index.d.cts.map