@codemation/core-nodes 1.0.0 → 1.0.2

package/dist/index.d.cts

@@ -14,6 +14,69 @@ import { AssistantModelMessage, ModelMessage, ToolModelMessage } from "ai";
  */
 type CanvasIconName = string;
 //#endregion
+//#region ../core/src/contracts/runTypes.d.ts
+
+type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
+type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
+interface NodeExecutionError {
+  message: string;
+  name?: string;
+  stack?: string;
+  details?: JsonValue;
+}
+/** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
+type ConnectionInvocationId = string;
+/** Arguments for appending a {@link ConnectionInvocationRecord} (engine fills run/workflow ids and timestamps). */
+type ConnectionInvocationAppendArgs = Readonly<{
+  invocationId: ConnectionInvocationId;
+  connectionNodeId: NodeId;
+  parentAgentNodeId: NodeId;
+  parentAgentActivationId: NodeActivationId;
+  status: NodeExecutionStatus;
+  managedInput?: JsonValue;
+  managedOutput?: JsonValue;
+  error?: NodeExecutionError;
+  queuedAt?: string;
+  startedAt?: string;
+  finishedAt?: string;
+  iterationId?: NodeIterationId;
+  itemIndex?: number;
+  parentInvocationId?: ConnectionInvocationId;
+}>;
+interface PendingNodeExecution {
+  runId: RunId;
+  activationId: NodeActivationId;
+  workflowId: WorkflowId;
+  nodeId: NodeId;
+  itemsIn: number;
+  inputsByPort: NodeInputsByPort;
+  receiptId: string;
+  queue?: string;
+  batchId?: string;
+  enqueuedAt: string;
+}
+type RunResult = {
+  runId: RunId;
+  workflowId: WorkflowId;
+  startedAt: string;
+  status: "completed";
+  outputs: Items;
+} | {
+  runId: RunId;
+  workflowId: WorkflowId;
+  startedAt: string;
+  status: "pending";
+  pending: PendingNodeExecution;
+} | {
+  runId: RunId;
+  workflowId: WorkflowId;
+  startedAt: string;
+  status: "failed";
+  error: {
+    message: string;
+  };
+};
+//#endregion
 //#region ../core/src/contracts/emitPorts.d.ts
 declare const EMIT_PORTS_BRAND: unique symbol;
 type PortsEmission = Readonly<{
@@ -134,6 +197,17 @@ interface TelemetrySpanScope extends TelemetryScope {
   readonly traceId: string;
   readonly spanId: string;
   end(args?: TelemetrySpanEnd): Promise<void> | void;
+  /**
+   * Lift this span into a {@link NodeExecutionTelemetry} scoped to a different (nodeId, activationId).
+   * Children created via the returned telemetry's `startChildSpan` get this span as their parent.
+   *
+   * Used at the sub-agent boundary so that nested runtime telemetry parents under the agent.tool.call
+   * span instead of the orchestrator's node-level span.
+   */
+  asNodeTelemetry(args: Readonly<{
+    nodeId: NodeId;
+    activationId: NodeActivationId;
+  }>): NodeExecutionTelemetry;
 }
 interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {
   startChildSpan(args: TelemetryChildSpanStart): TelemetrySpanScope;
@@ -170,65 +244,6 @@ interface CostTrackingTelemetry {
   forScope(scope: TelemetryScope): CostTrackingTelemetry;
 }
 //#endregion
-//#region ../core/src/contracts/runTypes.d.ts
-type NodeInputsByPort = Readonly<Record<InputPortKey, Items>>;
-type NodeExecutionStatus = "pending" | "queued" | "running" | "completed" | "failed" | "skipped";
-interface NodeExecutionError {
-  message: string;
-  name?: string;
-  stack?: string;
-  details?: JsonValue;
-}
-/** Stable id for a single connection invocation row in {@link ConnectionInvocationRecord}. */
-type ConnectionInvocationId = string;
-/** Arguments for appending a {@link ConnectionInvocationRecord} (engine fills run/workflow ids and timestamps). */
-type ConnectionInvocationAppendArgs = Readonly<{
-  invocationId: ConnectionInvocationId;
-  connectionNodeId: NodeId;
-  parentAgentNodeId: NodeId;
-  parentAgentActivationId: NodeActivationId;
-  status: NodeExecutionStatus;
-  managedInput?: JsonValue;
-  managedOutput?: JsonValue;
-  error?: NodeExecutionError;
-  queuedAt?: string;
-  startedAt?: string;
-  finishedAt?: string;
-}>;
-interface PendingNodeExecution {
-  runId: RunId;
-  activationId: NodeActivationId;
-  workflowId: WorkflowId;
-  nodeId: NodeId;
-  itemsIn: number;
-  inputsByPort: NodeInputsByPort;
-  receiptId: string;
-  queue?: string;
-  batchId?: string;
-  enqueuedAt: string;
-}
-type RunResult = {
-  runId: RunId;
-  workflowId: WorkflowId;
-  startedAt: string;
-  status: "completed";
-  outputs: Items;
-} | {
-  runId: RunId;
-  workflowId: WorkflowId;
-  startedAt: string;
-  status: "pending";
-  pending: PendingNodeExecution;
-} | {
-  runId: RunId;
-  workflowId: WorkflowId;
-  startedAt: string;
-  status: "failed";
-  error: {
-    message: string;
-  };
-};
-//#endregion
 //#region ../core/src/contracts/webhookTypes.d.ts
 type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
 interface WebhookControlSignal {
@@ -385,6 +400,12 @@ interface ExecutionContext {
   telemetry: ExecutionTelemetry;
   binary: ExecutionBinaryService;
   getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
+  /** Per-item iteration id, set by {@link NodeExecutor} on the ctx passed into runnable `execute`. */
+  iterationId?: NodeIterationId;
+  /** Item index (0-based) within the current activation's batch; set alongside {@link iterationId}. */
+  itemIndex?: number;
+  /** When set, this ctx is executing inside a sub-agent triggered by the named parent invocation. */
+  parentInvocationId?: ConnectionInvocationId;
 }
 interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfigBase> extends ExecutionContext {
   nodeId: NodeId;
@@ -620,6 +641,12 @@ type Items<TJson = unknown> = ReadonlyArray<Item<TJson>>;
 type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
 type RunId = string;
 type NodeActivationId = string;
+/**
+ * One per-item iteration of a runnable node's execute loop. Refines `NodeActivationId` for
+ * per-item connection invocations and telemetry. Undefined when the executing node is a batch
+ * node or trigger that does not iterate items.
+ */
+type NodeIterationId = string;
 interface ParentExecutionRef {
   runId: RunId;
   workflowId: WorkflowId;
@@ -636,6 +663,9 @@ interface RunDataSnapshot {
   getOutputItems<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, output?: OutputPortKey): Items<TJson>;
   getOutputItem<TJson = unknown>(nodeId: NodeId | NodeIdRef<TJson>, itemIndex: number, output?: OutputPortKey): Item<TJson> | undefined;
 }
+interface ActivationIdFactory {
+  makeActivationId(): NodeActivationId;
+}
 type UpstreamRefPlaceholder = `$${number}`;
 /** Whether to persist run execution data after the workflow finishes. */
 type WorkflowStoragePolicyMode = "ALL" | "SUCCESS" | "ERROR" | "NEVER";
@@ -897,6 +927,15 @@ type ToolExecuteArgs<TConfig extends ToolConfig = ToolConfig, TInput = unknown>
   item: Item;
   itemIndex: number;
   items: Items;
+  /**
+   * Optional sub-agent boundary hooks: when present, the live `agent.tool.call` span and the
+   * planned tool-call invocationId are forwarded so node-backed runtimes can re-root their child
+   * execution scope. Plain function tools may safely ignore these hooks.
+   */
+  hooks?: Readonly<{
+    parentSpan?: TelemetrySpanScope;
+    parentInvocationId?: ConnectionInvocationId;
+  }>;
 }>;
 type AgentMessageRole = "system" | "user" | "assistant";
 type AgentMessageBuildArgs<TInputJson$1 = unknown> = Readonly<{
@@ -1024,6 +1063,29 @@ interface AgentNodeConfig<TInputJson$1 = unknown, TOutputJson$1 = unknown> exten
   readonly outputSchema?: ZodType<TOutputJson$1>;
 }
 //#endregion
+//#region ../core/src/execution/ChildExecutionScopeFactory.d.ts
+/**
+ * Builds a re-rooted child execution context for sub-agent (and other deeply-nested) invocations.
+ *
+ * At the orchestrator's `agent.tool.call` boundary the inner runtime needs a ctx whose:
+ * - `nodeId` is the tool's connection node id (so inner LLM/tool connection ids derive correctly),
+ * - `activationId` is fresh (so its connection-invocation rows are uniquely identifiable),
+ * - `telemetry` parents children under the tool-call span (not the orchestrator's node span),
+ * - `binary` is scoped to the new (nodeId, activationId),
+ * - `parentInvocationId` points back to the tool-call invocation for downstream lineage.
+ */
+declare class ChildExecutionScopeFactory {
+  private readonly activationIdFactory;
+  constructor(activationIdFactory: ActivationIdFactory);
+  forSubAgent<TConfig extends RunnableNodeConfig<any, any>>(args: Readonly<{
+    parentCtx: NodeExecutionContext<TConfig>;
+    childNodeId: NodeId;
+    childConfig: TConfig;
+    parentInvocationId: ConnectionInvocationId;
+    parentSpan: TelemetrySpanScope;
+  }>): NodeExecutionContext<TConfig>;
+}
+//#endregion
 //#region ../core/src/execution/ItemExprResolver.d.ts
 /**
  * Resolves {@link import("../contracts/itemExpr").ItemExpr} leaves on runnable config before {@link RunnableNode.execute}.
@@ -1205,19 +1267,31 @@ type ResolvedTool = Readonly<{
 }>;
 /**
  * Per-item binding of a tool: the user config plus the resolved runtime and a snapshot of the
- * original Zod `inputSchema` used to convert to AI SDK `Tool` + OpenAI-strict JSON Schema for
- * repair prompts.
+ * original Zod `inputSchema`.
+ *
+ * `execute` accepts optional `hooks` so the agent coordinator can pass the live `agent.tool.call`
+ * span and the planned tool-call's `invocationId`. Node-backed sub-agent tools use these hooks
+ * via {@link ChildExecutionScopeFactory} to re-root their runtime ctx under the tool-call boundary
+ * (fresh activationId, telemetry parented at the tool-call span, `parentInvocationId` set).
  */
 type ItemScopedToolBinding = Readonly<{
   config: ToolConfig;
   inputSchema: ZodSchemaAny;
-  execute(input: unknown): Promise<unknown>;
+  execute(input: unknown, hooks?: ItemScopedToolCallHooks): Promise<unknown>;
+}>;
+type ItemScopedToolCallHooks = Readonly<{
+  /** Live agent.tool.call span (used to parent sub-agent telemetry). */
+  parentSpan?: TelemetrySpanScope;
+  /** invocationId of the parent tool call (used to thread `parentInvocationId` through ctx). */
+  parentInvocationId?: ConnectionInvocationId;
 }>;
 type PlannedToolCall = Readonly<{
   binding: ItemScopedToolBinding;
   toolCall: AgentToolCall;
   invocationIndex: number;
   nodeId: string;
+  /** Stable id reused across queued / running / completed connection invocation rows for this tool call. */
+  invocationId: string;
 }>;
 type ExecutedToolCall = Readonly<{
   toolName: string;
@@ -1442,8 +1516,24 @@ declare class NodeBackedToolRuntime {
   private readonly itemExprResolver;
   private readonly outputNormalizer;
   private readonly outputBehaviorResolver;
-  constructor(nodeResolver: NodeResolver, itemExprResolver: ItemExprResolver, outputNormalizer: NodeOutputNormalizer, outputBehaviorResolver: RunnableOutputBehaviorResolver);
+  private readonly childExecutionScopeFactory;
+  constructor(nodeResolver: NodeResolver, itemExprResolver: ItemExprResolver, outputNormalizer: NodeOutputNormalizer, outputBehaviorResolver: RunnableOutputBehaviorResolver, childExecutionScopeFactory: ChildExecutionScopeFactory);
   execute(config: NodeBackedToolConfig<any, ZodSchemaAny, ZodSchemaAny>, args: ToolExecuteArgs): Promise<unknown>;
+  /**
+   * Returns a re-rooted child ctx for nested-agent tools (so their LLM/tool connection ids derive
+   * from the tool connection node, telemetry parents under the tool-call span, and connection
+   * invocations carry `parentInvocationId`). Plain runnable tools (non-agent) keep the orchestrator
+   * ctx with only `config` swapped — no nesting concern.
+   *
+   * The caller (`AIAgentNode.createItemScopedTools`) already wraps the orchestrator ctx via
+   * `ConnectionCredentialExecutionContextFactory.forConnectionNode`, so `args.ctx.nodeId` is the
+   * tool's own connection node id (e.g. `AIAgentNode:2__conn__tool__searchInMail`). We pass that
+   * through as the sub-agent's `nodeId`; deriving another `toolConnectionNodeId(args.ctx.nodeId,
+   * config.name)` here would prepend a duplicate `__conn__tool__<name>` segment and exponentially
+   * deepen ids on each invocation, which also breaks credential resolution because user-provided
+   * bindings sit on the single-level connection node id.
+   */
+  private resolveNodeCtx;
   private executeResolvedNode;
   private isRunnableNode;
   private isMultiInputNode;
@@ -1510,6 +1600,14 @@ declare class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
   private invokeStructuredTurn;
   private isZodSchema;
   private resolveCallOptions;
+  /**
+   * Build a no-code-friendly output payload for an LLM round.
+   *
+   * Always includes `content` (matching the canvas snapshot shape used elsewhere) and adds a
+   * `toolCalls` array when the round produced tool calls so the execution inspector surfaces the
+   * planned calls instead of just an empty `""` for tool-only rounds.
+   */
+  private summarizeTurnOutput;
   private extractTurnResult;
   private extractAssistantMessage;
   private extractUsageFromResult;
@@ -1615,6 +1713,7 @@ declare class HttpRequest<TInputJson$1 = Readonly<{
   readonly execution: {
     readonly hint: "local";
   };
+  readonly icon: "lucide:globe";
   constructor(name: string, args?: Readonly<{
     method?: string;
     urlField?: string;
@@ -1647,7 +1746,7 @@ declare class Aggregate<TIn = unknown, TOut = unknown> implements RunnableNodeCo
     readonly hint: "local";
   };
   readonly keepBinaries: true;
-  readonly icon: "lucide:layers";
+  readonly icon: "builtin:aggregate-rows";
   constructor(name: string, aggregate: (items: Items<TIn>, ctx: NodeExecutionContext<Aggregate<TIn, TOut>>) => TOut | Promise<TOut>, id?: string | undefined);
 }
 //#endregion
@@ -1688,7 +1787,7 @@ declare class If<TInputJson$1 = unknown> implements RunnableNodeConfig<TInputJso
   readonly execution: {
     readonly hint: "local";
   };
-  readonly icon: "lucide:split";
+  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);
 }
@@ -1749,7 +1848,7 @@ declare class Split<TIn = unknown, TElem = unknown> implements RunnableNodeConfi
    * Mirrors {@link MapData}'s empty-output behavior.
    */
   readonly continueWhenEmptyOutput: true;
-  readonly icon: "lucide:ungroup";
+  readonly icon: "builtin:split-rows";
   constructor(name: string, getElements: (item: Item<TIn>, ctx: NodeExecutionContext<Split<TIn, TElem>>) => readonly TElem[], id?: string | undefined);
 }
 //#endregion
@@ -1809,6 +1908,7 @@ declare class MapData<TInputJson$1 = unknown, TOutputJson$1 = unknown> implement
   };
   /** Zero mapped items should still allow downstream nodes to run. */
   readonly continueWhenEmptyOutput: true;
+  readonly icon: "lucide:square-pen";
   readonly keepBinaries: boolean;
   constructor(name: string, map: (item: Item<TInputJson$1>, ctx: NodeExecutionContext<MapData<TInputJson$1, TOutputJson$1>>) => TOutputJson$1, options?: MapDataOptions);
   get id(): string | undefined;
@@ -1836,7 +1936,7 @@ declare class Merge<TInputJson$1 = unknown, TOutputJson$1 = TInputJson$1> implem
   readonly id?: string | undefined;
   readonly kind: "node";
   readonly type: TypeToken<unknown>;
-  readonly icon: "lucide:git-merge";
+  readonly icon: "lucide:merge@rot=90";
   constructor(name: string, cfg?: Readonly<{
     mode: MergeMode;
     /**
@@ -1863,6 +1963,7 @@ declare class NoOp<TItemJson = unknown> implements RunnableNodeConfig<TItemJson,
   readonly execution: {
     readonly hint: "local";
   };
+  readonly icon: "lucide:circle-dashed";
   constructor(name?: string, id?: string | undefined);
 }
 //#endregion
@@ -1915,6 +2016,7 @@ 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);
 }
 //#endregion
@@ -1945,7 +2047,7 @@ declare class WebhookTrigger<TSchema extends WebhookInputSchema | undefined = un
   readonly id?: string | undefined;
   readonly kind: "trigger";
   readonly type: TypeToken<unknown>;
-  readonly icon = "lucide:globe";
+  readonly icon = "lucide:webhook";
   constructor(name: string, args: Readonly<{
     endpointKey: string;
     methods: ReadonlyArray<HttpMethod>;