@codemation/core-nodes 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core-nodes",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,7 +32,7 @@
     "@ai-sdk/provider": "^3.0.8",
     "ai": "^6.0.168",
     "lucide-react": "^0.577.0",
-    "@codemation/core": "1.0.0"
+    "@codemation/core": "1.0.1"
   },
   "devDependencies": {
     "@types/node": "^25.3.5",

package/src/nodes/AIAgentNode.ts

@@ -356,7 +356,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       return {
         config: entry.config,
         inputSchema: entry.runtime.inputSchema,
-        execute: async (input: unknown): Promise<unknown> => {
+        execute: async (input, hooks): Promise<unknown> => {
           const validated = entry.runtime.inputSchema.parse(input) as unknown;
           return await entry.runtime.execute({
             config: entry.config,
@@ -365,6 +365,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
             item,
             itemIndex,
             items,
+            hooks,
           });
         },
       } satisfies ItemScopedToolBinding;
@@ -421,11 +422,36 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       activationId: ctx.activationId,
       inputsByPort: itemInputsByPort,
     });
+    await ctx.nodeState?.appendConnectionInvocation({
+      invocationId,
+      connectionNodeId: languageModelConnectionNodeId,
+      parentAgentNodeId: ctx.nodeId,
+      parentAgentActivationId: ctx.activationId,
+      status: "queued",
+      managedInput: summarizedInput,
+      queuedAt: startedAt.toISOString(),
+      iterationId: ctx.iterationId,
+      itemIndex: ctx.itemIndex,
+      parentInvocationId: ctx.parentInvocationId,
+    });
     await ctx.nodeState?.markRunning({
       nodeId: languageModelConnectionNodeId,
       activationId: ctx.activationId,
       inputsByPort: itemInputsByPort,
     });
+    await ctx.nodeState?.appendConnectionInvocation({
+      invocationId,
+      connectionNodeId: languageModelConnectionNodeId,
+      parentAgentNodeId: ctx.nodeId,
+      parentAgentActivationId: ctx.activationId,
+      status: "running",
+      managedInput: summarizedInput,
+      queuedAt: startedAt.toISOString(),
+      startedAt: startedAt.toISOString(),
+      iterationId: ctx.iterationId,
+      itemIndex: ctx.itemIndex,
+      parentInvocationId: ctx.parentInvocationId,
+    });
     try {
       const tools = this.buildToolSet(itemScopedTools);
       const callOptions = this.resolveCallOptions(model, guardrails.modelInvocationOptions);
@@ -441,11 +467,12 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       });
       const turnResult = this.extractTurnResult(result as AnyGenerateTextResult);
       const finishedAt = new Date();
+      const managedOutput = this.summarizeTurnOutput(turnResult);
       await ctx.nodeState?.markCompleted({
         nodeId: languageModelConnectionNodeId,
         activationId: ctx.activationId,
         inputsByPort: itemInputsByPort,
-        outputs: AgentOutputFactory.fromUnknown({ content: turnResult.text }),
+        outputs: AgentOutputFactory.fromUnknown(managedOutput),
       });
       await span.attachArtifact({ kind: "ai.messages", contentType: "application/json", previewJson: summarizedInput });
       await span.attachArtifact({ kind: "ai.response", contentType: "application/json", previewJson: turnResult.text });
@@ -458,10 +485,13 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         parentAgentActivationId: ctx.activationId,
         status: "completed",
         managedInput: summarizedInput,
-        managedOutput: turnResult.text,
+        managedOutput,
         queuedAt: startedAt.toISOString(),
         startedAt: startedAt.toISOString(),
         finishedAt: finishedAt.toISOString(),
+        iterationId: ctx.iterationId,
+        itemIndex: ctx.itemIndex,
+        parentInvocationId: ctx.parentInvocationId,
       });
       return turnResult;
     } catch (error) {
@@ -504,11 +534,36 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       activationId: ctx.activationId,
       inputsByPort: itemInputsByPort,
     });
+    await ctx.nodeState?.appendConnectionInvocation({
+      invocationId,
+      connectionNodeId: languageModelConnectionNodeId,
+      parentAgentNodeId: ctx.nodeId,
+      parentAgentActivationId: ctx.activationId,
+      status: "queued",
+      managedInput: summarizedInput,
+      queuedAt: startedAt.toISOString(),
+      iterationId: ctx.iterationId,
+      itemIndex: ctx.itemIndex,
+      parentInvocationId: ctx.parentInvocationId,
+    });
     await ctx.nodeState?.markRunning({
       nodeId: languageModelConnectionNodeId,
       activationId: ctx.activationId,
       inputsByPort: itemInputsByPort,
     });
+    await ctx.nodeState?.appendConnectionInvocation({
+      invocationId,
+      connectionNodeId: languageModelConnectionNodeId,
+      parentAgentNodeId: ctx.nodeId,
+      parentAgentActivationId: ctx.activationId,
+      status: "running",
+      managedInput: summarizedInput,
+      queuedAt: startedAt.toISOString(),
+      startedAt: startedAt.toISOString(),
+      iterationId: ctx.iterationId,
+      itemIndex: ctx.itemIndex,
+      parentInvocationId: ctx.parentInvocationId,
+    });
     try {
       const callOptions = this.resolveCallOptions(model, guardrails.modelInvocationOptions);
       const outputSchema =
@@ -551,6 +606,9 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         queuedAt: startedAt.toISOString(),
         startedAt: startedAt.toISOString(),
         finishedAt: finishedAt.toISOString(),
+        iterationId: ctx.iterationId,
+        itemIndex: ctx.itemIndex,
+        parentInvocationId: ctx.parentInvocationId,
       });
       return result.experimental_output;
     } catch (error) {
@@ -589,6 +647,22 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     };
   }
 
+  /**
+   * 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(turnResult: TurnResult): JsonValue {
+    if (turnResult.toolCalls.length === 0) return { content: turnResult.text };
+    const toolCalls = turnResult.toolCalls.map((toolCall) => ({
+      name: toolCall.name,
+      args: this.resultToJsonValue(toolCall.input) ?? null,
+    }));
+    return { content: turnResult.text, toolCalls };
+  }
+
   private extractTurnResult(result: AnyGenerateTextResult): TurnResult {
     const usage = this.extractUsageFromResult(result);
     const text = result.text;
@@ -642,6 +716,13 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         [CodemationTelemetryAttributeNames.connectionInvocationId]: invocationId,
         [GenAiTelemetryAttributeNames.operationName]: "chat",
         [GenAiTelemetryAttributeNames.requestModel]: this.resolveChatModelName(ctx.config.chatModel),
+        ...(ctx.iterationId ? { [CodemationTelemetryAttributeNames.iterationId]: ctx.iterationId } : {}),
+        ...(typeof ctx.itemIndex === "number"
+          ? { [CodemationTelemetryAttributeNames.iterationIndex]: ctx.itemIndex }
+          : {}),
+        ...(ctx.parentInvocationId
+          ? { [CodemationTelemetryAttributeNames.parentInvocationId]: ctx.parentInvocationId }
+          : {}),
       },
     });
   }
@@ -707,12 +788,25 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
     plannedToolCalls: ReadonlyArray<PlannedToolCall>,
     ctx: NodeExecutionContext<AIAgent<any, any>>,
   ): Promise<void> {
+    const queuedAt = new Date().toISOString();
     for (const plannedToolCall of plannedToolCalls) {
       await ctx.nodeState?.markQueued({
         nodeId: plannedToolCall.nodeId,
         activationId: ctx.activationId,
         inputsByPort: AgentToolCallPortMap.fromInput(plannedToolCall.toolCall.input ?? {}),
       });
+      await ctx.nodeState?.appendConnectionInvocation({
+        invocationId: plannedToolCall.invocationId,
+        connectionNodeId: plannedToolCall.nodeId,
+        parentAgentNodeId: ctx.nodeId,
+        parentAgentActivationId: ctx.activationId,
+        status: "queued",
+        managedInput: this.resultToJsonValue(plannedToolCall.toolCall.input),
+        queuedAt,
+        iterationId: ctx.iterationId,
+        itemIndex: ctx.itemIndex,
+        parentInvocationId: ctx.parentInvocationId,
+      });
     }
   }
 
@@ -732,6 +826,7 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
         toolCall,
         invocationIndex,
         nodeId: ConnectionNodeIdFactory.toolConnectionNodeId(parentNodeId, binding.config.name),
+        invocationId: ConnectionInvocationIdFactory.create(),
       } satisfies PlannedToolCall;
     });
   }
@@ -771,6 +866,9 @@ export class AIAgentNode implements RunnableNode<AIAgent<any, any>> {
       queuedAt: args.startedAt.toISOString(),
       startedAt: args.startedAt.toISOString(),
       finishedAt: finishedAt.toISOString(),
+      iterationId: args.ctx.iterationId,
+      itemIndex: args.ctx.itemIndex,
+      parentInvocationId: args.ctx.parentInvocationId,
     });
     return effectiveError;
   }

package/src/nodes/AgentToolExecutionCoordinator.ts

@@ -1,5 +1,5 @@
 import type { JsonValue, NodeExecutionContext } from "@codemation/core";
-import { CodemationTelemetryAttributeNames, ConnectionInvocationIdFactory, inject, injectable } from "@codemation/core";
+import { CodemationTelemetryAttributeNames, inject, injectable } from "@codemation/core";
 
 import type { AIAgent } from "./AIAgentConfig";
 import { AgentOutputFactory } from "./AgentOutputFactory";
@@ -53,7 +53,7 @@ export class AgentToolExecutionCoordinator {
   ): Promise<ExecutedToolCall> {
     const { plannedToolCall, ctx } = args;
     const toolCallInputsByPort = AgentToolCallPortMap.fromInput(plannedToolCall.toolCall.input ?? {});
-    const invocationId = ConnectionInvocationIdFactory.create();
+    const invocationId = plannedToolCall.invocationId;
     const startedAt = new Date();
     const span = ctx.telemetry.startChildSpan({
       name: "agent.tool.call",
@@ -62,6 +62,13 @@ export class AgentToolExecutionCoordinator {
       attributes: {
         [CodemationTelemetryAttributeNames.connectionInvocationId]: invocationId,
         [CodemationTelemetryAttributeNames.toolName]: plannedToolCall.binding.config.name,
+        ...(ctx.iterationId ? { [CodemationTelemetryAttributeNames.iterationId]: ctx.iterationId } : {}),
+        ...(typeof ctx.itemIndex === "number"
+          ? { [CodemationTelemetryAttributeNames.iterationIndex]: ctx.itemIndex }
+          : {}),
+        ...(ctx.parentInvocationId
+          ? { [CodemationTelemetryAttributeNames.parentInvocationId]: ctx.parentInvocationId }
+          : {}),
       },
     });
     await ctx.nodeState?.markRunning({
@@ -69,9 +76,24 @@ export class AgentToolExecutionCoordinator {
       activationId: ctx.activationId,
       inputsByPort: toolCallInputsByPort,
     });
+    await ctx.nodeState?.appendConnectionInvocation({
+      invocationId,
+      connectionNodeId: plannedToolCall.nodeId,
+      parentAgentNodeId: ctx.nodeId,
+      parentAgentActivationId: ctx.activationId,
+      status: "running",
+      managedInput: this.toJsonValue(plannedToolCall.toolCall.input),
+      queuedAt: startedAt.toISOString(),
+      startedAt: startedAt.toISOString(),
+      iterationId: ctx.iterationId,
+      parentInvocationId: ctx.parentInvocationId,
+    });
 
     try {
-      const result = await plannedToolCall.binding.execute(plannedToolCall.toolCall.input ?? {});
+      const result = await plannedToolCall.binding.execute(plannedToolCall.toolCall.input ?? {}, {
+        parentSpan: span,
+        parentInvocationId: invocationId,
+      });
       const serialized = typeof result === "string" ? result : JSON.stringify(result);
       const finishedAt = new Date();
       await ctx.nodeState?.markCompleted({
@@ -102,6 +124,8 @@ export class AgentToolExecutionCoordinator {
         queuedAt: startedAt.toISOString(),
         startedAt: startedAt.toISOString(),
         finishedAt: finishedAt.toISOString(),
+        iterationId: ctx.iterationId,
+        parentInvocationId: ctx.parentInvocationId,
       });
       return {
         toolName: plannedToolCall.binding.config.name,
@@ -262,6 +286,8 @@ export class AgentToolExecutionCoordinator {
       queuedAt: args.startedAt.toISOString(),
       startedAt: args.startedAt.toISOString(),
       finishedAt: finishedAt.toISOString(),
+      iterationId: args.ctx.iterationId,
+      parentInvocationId: args.ctx.parentInvocationId,
     });
   }
 

package/src/nodes/NodeBackedToolRuntime.ts

@@ -11,6 +11,8 @@ import type {
   ZodSchemaAny,
 } from "@codemation/core";
 import {
+  AgentConfigInspector,
+  ChildExecutionScopeFactory,
   CoreTokens,
   inject,
   injectable,
@@ -31,6 +33,8 @@ export class NodeBackedToolRuntime {
     private readonly outputNormalizer: NodeOutputNormalizer,
     @inject(RunnableOutputBehaviorResolver)
     private readonly outputBehaviorResolver: RunnableOutputBehaviorResolver,
+    @inject(ChildExecutionScopeFactory)
+    private readonly childExecutionScopeFactory: ChildExecutionScopeFactory,
   ) {}
 
   async execute(
@@ -45,10 +49,7 @@ export class NodeBackedToolRuntime {
       ctx: args.ctx,
       node: config.node,
     });
-    const nodeCtx = {
-      ...args.ctx,
-      config: config.node,
-    } as NodeExecutionContext<RunnableNodeConfig>;
+    const nodeCtx = this.resolveNodeCtx(config, args);
     const resolvedNode = this.nodeResolver.resolve(config.node.type);
     const outputs = await this.executeResolvedNode(resolvedNode, nodeInput, nodeCtx);
     return config.toToolOutput({
@@ -62,6 +63,41 @@ export class NodeBackedToolRuntime {
     });
   }
 
+  /**
+   * Returns a re-rooted child ctx for nested-agent tools (so their LLM/tool connection ids derive
+   * from the tool connection node, telemetry parents under the tool-call span, and connection
+   * invocations carry `parentInvocationId`). Plain runnable tools (non-agent) keep the orchestrator
+   * ctx with only `config` swapped — no nesting concern.
+   *
+   * The caller (`AIAgentNode.createItemScopedTools`) already wraps the orchestrator ctx via
+   * `ConnectionCredentialExecutionContextFactory.forConnectionNode`, so `args.ctx.nodeId` is the
+   * tool's own connection node id (e.g. `AIAgentNode:2__conn__tool__searchInMail`). We pass that
+   * through as the sub-agent's `nodeId`; deriving another `toolConnectionNodeId(args.ctx.nodeId,
+   * config.name)` here would prepend a duplicate `__conn__tool__<name>` segment and exponentially
+   * deepen ids on each invocation, which also breaks credential resolution because user-provided
+   * bindings sit on the single-level connection node id.
+   */
+  private resolveNodeCtx(
+    config: NodeBackedToolConfig<any, ZodSchemaAny, ZodSchemaAny>,
+    args: ToolExecuteArgs,
+  ): NodeExecutionContext<RunnableNodeConfig> {
+    const isNestedAgent = AgentConfigInspector.isAgentNodeConfig(config.node);
+    const hooks = args.hooks;
+    if (!isNestedAgent || !hooks?.parentSpan || !hooks.parentInvocationId) {
+      return {
+        ...args.ctx,
+        config: config.node,
+      } as NodeExecutionContext<RunnableNodeConfig>;
+    }
+    return this.childExecutionScopeFactory.forSubAgent({
+      parentCtx: args.ctx as NodeExecutionContext<RunnableNodeConfig>,
+      childNodeId: args.ctx.nodeId,
+      childConfig: config.node as unknown as RunnableNodeConfig,
+      parentInvocationId: hooks.parentInvocationId,
+      parentSpan: hooks.parentSpan,
+    });
+  }
+
   private async executeResolvedNode(
     resolvedNode: unknown,
     nodeInput: ToolExecuteArgs["item"],

package/src/nodes/aiAgentSupport.types.ts

@@ -1,7 +1,9 @@
 import type {
   AgentToolCall,
+  ConnectionInvocationId,
   Item,
   NodeInputsByPort,
+  TelemetrySpanScope,
   ToolConfig,
   ToolExecuteArgs,
   ZodSchemaAny,
@@ -24,13 +26,24 @@ export type ResolvedTool = Readonly<{
 
 /**
  * Per-item binding of a tool: the user config plus the resolved runtime and a snapshot of the
- * original Zod `inputSchema` 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).
  */
 export type ItemScopedToolBinding = Readonly<{
   config: ToolConfig;
   inputSchema: ZodSchemaAny;
-  execute(input: unknown): Promise<unknown>;
+  execute(input: unknown, hooks?: ItemScopedToolCallHooks): Promise<unknown>;
+}>;
+
+export type ItemScopedToolCallHooks = Readonly<{
+  /** Live agent.tool.call span (used to parent sub-agent telemetry). */
+  parentSpan?: TelemetrySpanScope;
+  /** invocationId of the parent tool call (used to thread `parentInvocationId` through ctx). */
+  parentInvocationId?: ConnectionInvocationId;
 }>;
 
 export type PlannedToolCall = Readonly<{
@@ -38,6 +51,8 @@ export type PlannedToolCall = Readonly<{
   toolCall: AgentToolCall;
   invocationIndex: number;
   nodeId: string;
+  /** Stable id reused across queued / running / completed connection invocation rows for this tool call. */
+  invocationId: string;
 }>;
 
 export type ExecutedToolCall = Readonly<{