@codemation/core-nodes 0.10.1 → 0.12.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { AssistantModelMessage, ModelMessage, ToolModelMessage, ToolSet } from "ai";
 import { Cron, CronCallback } from "croner";
+import { AssistantModelMessage, ModelMessage, ToolModelMessage, ToolSet } from "ai";
 import { ZodType, input, output, z } from "zod";
 import { DependencyContainer as Container, InjectionToken as TypeToken } from "tsyringe";
 import { ReadableStream } from "node:stream/web";
@@ -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.
- */
-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.
+ * 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
  */
-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, type ExecutedToolCall, Filter, FilterNode, type FindToolsResult, HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES, HttpBodySpec, HttpCredentialDelta, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, HttpRequestResult, HttpRequestSpec, If, IfNode, IsTestRun, IsTestRunNode, type ItemScopedToolBinding, ManagedModelDto, ManagedModelFetcher, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, MapDataOptions, Merge, MergeMode, MergeNode, NoOp, NoOpNode, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAiChatModelPresets, OpenAiCredentialSession, OpenAiStrictJsonSchemaFactory, type PlannedToolCall, type ResolvedTool, RestNodeApi, RestNodeErrorPolicy, RestNodeRequestShape, RestNodeResponseContext, SSRFBlockedError, Split, SplitNode, SsrfGuard, SubWorkflow, SubWorkflowNode, Switch, SwitchCaseKeyResolver, SwitchNode, TestTrigger, TestTriggerNode, TestTriggerOptions, type ToolLoadingStrategy, type ToolLoadingStrategyInitInput, type 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, type ExecutedToolCall, Filter, FilterNode, type FindToolsResult, HTTP_REQUEST_ACCEPTED_CREDENTIAL_TYPES, HttpBodySpec, HttpCredentialDelta, HttpRequest, HttpRequestDownloadMode, HttpRequestNode, HttpRequestOutputJson, HttpRequestResult, HttpRequestSpec, If, IfNode, IsTestRun, IsTestRunNode, type ItemScopedToolBinding, ManagedComplexity, ManualTrigger, ManualTriggerNode, MapData, MapDataNode, MapDataOptions, Merge, MergeMode, MergeNode, NoOp, NoOpNode, NodeBaseOptions, OpenAIChatModelConfig, OpenAIChatModelFactory, OpenAiChatModelPresets, OpenAiCredentialSession, OpenAiStrictJsonSchemaFactory, type PlannedToolCall, type ResolvedTool, RestNodeApi, RestNodeErrorPolicy, RestNodeRequestShape, RestNodeResponseContext, SSRFBlockedError, Split, SplitNode, SsrfGuard, SubWorkflow, SubWorkflowNode, Switch, SwitchCaseKeyResolver, SwitchNode, TestTrigger, TestTriggerNode, TestTriggerOptions, type ToolLoadingStrategy, type ToolLoadingStrategyInitInput, type 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.ts.map