@codemation/core 1.0.0 → 1.0.1

package/dist/testing.cjs

@@ -1,6 +1,6 @@
-const require_runtime = require('./runtime-DWKfb0BI.cjs');
+const require_runtime = require('./runtime-B3Og-_St.cjs');
 const require_InMemoryRunEventBusRegistry = require('./InMemoryRunEventBusRegistry-B0_C4OnP.cjs');
-const require_bootstrap = require('./bootstrap-BfZE19lK.cjs');
+const require_bootstrap = require('./bootstrap-Cko6udwL.cjs');
 let tsyringe = require("tsyringe");
 tsyringe = require_runtime.__toESM(tsyringe);
 

package/dist/testing.d.cts

@@ -1,5 +1,5 @@
-import { A as NodeOutputs, E as NodeId, F as ParentExecutionRef, G as TriggerNodeConfig, H as RunnableNodeConfig, Ht as NodeExecutionRequest, Jr as CredentialSessionService, R as RunDataFactory, Vt as NodeExecutionContext, Wt as NodeExecutionScheduler, Xt as RunnableNode, Y as WorkflowDefinition, Zt as RunnableNodeExecuteArgs, ci as TypeToken, en as TriggerNode, f as Items, in as TriggerSetupStateRepository, jt as ExecutionContextFactory, k as NodeOffloadPolicy, ln as WorkflowRunnerService, n as InMemoryLiveWorkflowRepository, ni as Container, nn as TriggerSetupContext, qn as RunResult, r as Engine, t as RunIntentService, tr as WorkflowExecutionRepository, tt as WorkflowId, u as Item, wi as RunEventBus, xi as EngineExecutionLimitsPolicy } from "./RunIntentService-S-1lW-gS.cjs";
-import { a as WorkflowSnapshotCodec, n as EngineRuntimeRegistrationOptions, t as EngineWorkflowRunnerService } from "./EngineWorkflowRunnerService-DzOCa1BW.cjs";
+import { A as NodeOffloadPolicy, E as NodeId, Ei as WorkflowExecutionRepository, Gt as NodeExecutionScheduler, Ht as NodeExecutionContext, I as ParentExecutionRef, K as TriggerNodeConfig, Mt as ExecutionContextFactory, Or as TypeToken, Qt as RunnableNodeExecuteArgs, Sr as Container, U as RunnableNodeConfig, Ut as NodeExecutionRequest, Vr as EngineExecutionLimitsPolicy, Wr as RunEventBus, X as WorkflowDefinition, Zt as RunnableNode, an as TriggerSetupStateRepository, f as Items, j as NodeOutputs, mr as CredentialSessionService, n as InMemoryLiveWorkflowRepository, nt as WorkflowId, r as Engine, rn as TriggerSetupContext, t as RunIntentService, tn as TriggerNode, u as Item, un as WorkflowRunnerService, vi as RunResult, z as RunDataFactory } from "./RunIntentService-Dyh_dH0k.cjs";
+import { a as WorkflowSnapshotCodec, n as EngineRuntimeRegistrationOptions, t as EngineWorkflowRunnerService } from "./EngineWorkflowRunnerService-Ba2AvBnL.cjs";
 import { DependencyContainer, InjectionToken } from "tsyringe";
 import { ZodType } from "zod";
 

package/dist/testing.d.ts

@@ -1,5 +1,5 @@
-import { $n as NodeExecutionContext, Ht as NodeOutputs, Ia as RunEventBus, Na as EngineExecutionLimitsPolicy, Rt as NodeId, St as Item, Un as ExecutionContextFactory, Vt as NodeOffloadPolicy, Xt as RunDataFactory, ai as RunResult, ba as TypeToken, cr as RunnableNode, en as RunnableNodeConfig, er as NodeExecutionRequest, fr as TriggerNode, gr as TriggerSetupStateRepository, l as WorkflowSnapshotCodec, lr as RunnableNodeExecuteArgs, ma as Container, mr as TriggerSetupContext, n as InMemoryLiveWorkflowRepository, nr as NodeExecutionScheduler, oa as CredentialSessionService, pi as WorkflowExecutionRepository, pn as WorkflowId, qt as ParentExecutionRef, r as EngineWorkflowRunnerService, rn as TriggerNodeConfig, sn as WorkflowDefinition, t as RunIntentService, u as Engine, wt as Items, xr as WorkflowRunnerService } from "./RunIntentService-BqhmdoA1.js";
-import { t as EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types-BP6tsaNP.js";
+import { $t as RunDataFactory, Ba as WorkflowExecutionRepository, Bt as NodeId, Et as Items, Gt as NodeOutputs, Hi as TypeToken, Ii as Container, Kn as ExecutionContextFactory, Ma as RunResult, Oi as CredentialSessionService, Wt as NodeOffloadPolicy, Xt as ParentExecutionRef, _r as TriggerSetupContext, ar as NodeExecutionScheduler, dr as RunnableNode, fr as RunnableNodeExecuteArgs, gn as WorkflowId, hr as TriggerNode, ia as RunEventBus, l as WorkflowSnapshotCodec, n as InMemoryLiveWorkflowRepository, nr as NodeExecutionContext, on as TriggerNodeConfig, r as EngineWorkflowRunnerService, rn as RunnableNodeConfig, rr as NodeExecutionRequest, t as RunIntentService, ta as EngineExecutionLimitsPolicy, u as Engine, un as WorkflowDefinition, wr as WorkflowRunnerService, wt as Item, yr as TriggerSetupStateRepository } from "./RunIntentService-dteLjNiT.js";
+import { t as EngineRuntimeRegistrationOptions } from "./EngineRuntimeRegistration.types-kxQA5NLt.js";
 import { DependencyContainer, InjectionToken } from "tsyringe";
 import { ZodType } from "zod";
 

package/dist/testing.js

@@ -1,6 +1,6 @@
-import { A as NodeExecutor, D as PersistedWorkflowTokenRegistry, E as WorkflowSnapshotCodec, F as InProcessRetryRunner, L as DefaultExecutionContextFactory, R as AllWorkflowsActiveWorkflowActivationPolicy, Rt as CoreTokens, T as NodeInstanceFactory, a as InMemoryLiveWorkflowRepository, b as DefaultDrivingScheduler, i as RunIntentService, it as emitPorts, l as Engine, st as DefaultAsyncSleeper, u as InMemoryRunDataFactory, v as InlineDrivingScheduler, y as HintOnlyOffloadPolicy } from "./runtime-u6O644ST.js";
+import { A as NodeExecutor, D as PersistedWorkflowTokenRegistry, E as WorkflowSnapshotCodec, F as InProcessRetryRunner, Ht as CoreTokens, L as DefaultExecutionContextFactory, R as AllWorkflowsActiveWorkflowActivationPolicy, T as NodeInstanceFactory, a as InMemoryLiveWorkflowRepository, b as DefaultDrivingScheduler, i as RunIntentService, it as emitPorts, l as Engine, st as DefaultAsyncSleeper, u as InMemoryRunDataFactory, v as InlineDrivingScheduler, y as HintOnlyOffloadPolicy } from "./runtime-284ok0cm.js";
 import { n as WorkflowBuilder, t as InMemoryRunEventBus } from "./InMemoryRunEventBusRegistry-C2U83Hmv.js";
-import { n as InMemoryWorkflowExecutionRepository, t as EngineRuntimeRegistrar } from "./bootstrap-jqh1kCNI.js";
+import { n as InMemoryWorkflowExecutionRepository, t as EngineRuntimeRegistrar } from "./bootstrap-CL68rqWg.js";
 import { container } from "tsyringe";
 
 //#region src/testing/RejectingCredentialSessionService.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codemation/core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "publishConfig": {
     "access": "public"
   },

package/src/ai/AiHost.ts

@@ -37,6 +37,15 @@ export type ToolExecuteArgs<TConfig extends ToolConfig = ToolConfig, TInput = un
   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?: import("../contracts/telemetryTypes").TelemetrySpanScope;
+    parentInvocationId?: import("../contracts/runTypes").ConnectionInvocationId;
+  }>;
 }>;
 
 export interface Tool<

package/src/bootstrap/runtime/EngineRuntimeRegistrar.ts

@@ -2,6 +2,7 @@ import { instanceCachingFactory, type DependencyContainer } from "../../di";
 import { CoreTokens } from "../../di";
 import { EngineExecutionLimitsPolicyFactory } from "../../policies/executionLimits/EngineExecutionLimitsPolicyFactory";
 import {
+  ChildExecutionScopeFactory,
   DefaultAsyncSleeper,
   InProcessRetryRunnerFactory,
   ItemExprResolver,
@@ -50,6 +51,9 @@ export class EngineRuntimeRegistrar {
     if (!container.isRegistered(RunnableOutputBehaviorResolver, true)) {
       container.registerSingleton(RunnableOutputBehaviorResolver, RunnableOutputBehaviorResolver);
     }
+    if (!container.isRegistered(ChildExecutionScopeFactory, true)) {
+      container.registerSingleton(ChildExecutionScopeFactory, ChildExecutionScopeFactory);
+    }
     container.registerSingleton(EngineExecutionLimitsPolicyFactory, EngineExecutionLimitsPolicyFactory);
     container.registerSingleton(NodeInstanceFactoryFactory, NodeInstanceFactoryFactory);
     container.registerSingleton(DefaultAsyncSleeper, DefaultAsyncSleeper);

package/src/browser.ts

@@ -9,6 +9,7 @@ export type {
 } from "./ai/AgentConnectionNodeCollector";
 export type { AgentNodeConfig } from "./ai/AiHost";
 export { ConnectionNodeIdFactory } from "./workflow/definition/ConnectionNodeIdFactory";
+export { NodeIterationIdFactory } from "./workflow/definition/NodeIterationIdFactory";
 export * from "./contracts/credentialTypes";
 export * from "./contracts/runtimeTypes";
 export * from "./contracts/runFinishedAtFactory";

package/src/contracts/CodemationTelemetryAttributeNames.ts

@@ -9,4 +9,10 @@ export class CodemationTelemetryAttributeNames {
   static readonly connectionInvocationId = "codemation.connection.invocation_id";
   static readonly toolName = "codemation.tool.name";
   static readonly traceParentRunId = "codemation.parent.run.id";
+  /** Per-item iteration that emitted this span/metric. Set on spans recorded inside a runnable per-item loop. */
+  static readonly iterationId = "codemation.iteration.id";
+  /** Item index (0-based) of the iteration. */
+  static readonly iterationIndex = "codemation.iteration.index";
+  /** Set when this span/metric was recorded under a sub-agent triggered by an outer LLM/tool call. */
+  static readonly parentInvocationId = "codemation.parent.invocation_id";
 }

package/src/contracts/NoOpNodeExecutionTelemetry.ts

@@ -1,15 +1,6 @@
-import type { NodeActivationId, NodeId } from "./workflowTypes";
-import type { NodeExecutionTelemetry, TelemetryChildSpanStart, TelemetrySpanScope } from "./telemetryTypes";
+import type { NodeExecutionTelemetry } from "./telemetryTypes";
 import { NoOpTelemetrySpanScope } from "./NoOpTelemetrySpanScope";
 
 export class NoOpNodeExecutionTelemetry {
-  static readonly value: NodeExecutionTelemetry = {
-    ...NoOpTelemetrySpanScope.value,
-    forNode(_: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>): NodeExecutionTelemetry {
-      return NoOpNodeExecutionTelemetry.value;
-    },
-    startChildSpan(_: TelemetryChildSpanStart): TelemetrySpanScope {
-      return NoOpTelemetrySpanScope.value;
-    },
-  };
+  static readonly value: NodeExecutionTelemetry = NoOpTelemetrySpanScope.nodeExecutionTelemetryValue;
 }

package/src/contracts/NoOpTelemetrySpanScope.ts

@@ -1,6 +1,9 @@
+import type { NodeActivationId, NodeId } from "./workflowTypes";
 import type {
+  NodeExecutionTelemetry,
   TelemetryArtifactAttachment,
   TelemetryArtifactReference,
+  TelemetryChildSpanStart,
   TelemetryMetricRecord,
   TelemetrySpanEnd,
   TelemetrySpanEventRecord,
@@ -8,15 +11,48 @@ import type {
 } from "./telemetryTypes";
 import { NoOpTelemetryArtifactReference } from "./NoOpTelemetryArtifactReference";
 
+/**
+ * Standalone no-op {@link NodeExecutionTelemetry} value used as the return for `asNodeTelemetry`.
+ *
+ * Defined here (instead of in `NoOpNodeExecutionTelemetry.ts`) so that {@link NoOpTelemetrySpanScope}
+ * can return it without importing the other module — both no-ops share this leaf.
+ */
+const noOpNodeExecutionTelemetry: NodeExecutionTelemetry = {
+  traceId: "00000000000000000000000000000000",
+  spanId: "0000000000000000",
+  addSpanEvent(_: TelemetrySpanEventRecord): void {},
+  recordMetric(_: TelemetryMetricRecord): void {},
+  attachArtifact(_: TelemetryArtifactAttachment): TelemetryArtifactReference {
+    return NoOpTelemetryArtifactReference.value;
+  },
+  end(_: TelemetrySpanEnd = {}): void {},
+  asNodeTelemetry(_: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>): NodeExecutionTelemetry {
+    return noOpNodeExecutionTelemetry;
+  },
+  forNode(_: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>): NodeExecutionTelemetry {
+    return noOpNodeExecutionTelemetry;
+  },
+  startChildSpan(_: TelemetryChildSpanStart): TelemetrySpanScope {
+    return noOpTelemetrySpanScope;
+  },
+};
+
+const noOpTelemetrySpanScope: TelemetrySpanScope = {
+  traceId: "00000000000000000000000000000000",
+  spanId: "0000000000000000",
+  addSpanEvent(_: TelemetrySpanEventRecord): void {},
+  recordMetric(_: TelemetryMetricRecord): void {},
+  attachArtifact(_: TelemetryArtifactAttachment): TelemetryArtifactReference {
+    return NoOpTelemetryArtifactReference.value;
+  },
+  end(_: TelemetrySpanEnd = {}): void {},
+  asNodeTelemetry(_: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>): NodeExecutionTelemetry {
+    return noOpNodeExecutionTelemetry;
+  },
+};
+
 export class NoOpTelemetrySpanScope {
-  static readonly value: TelemetrySpanScope = {
-    traceId: "00000000000000000000000000000000",
-    spanId: "0000000000000000",
-    addSpanEvent(_: TelemetrySpanEventRecord): void {},
-    recordMetric(_: TelemetryMetricRecord): void {},
-    attachArtifact(_: TelemetryArtifactAttachment): TelemetryArtifactReference {
-      return NoOpTelemetryArtifactReference.value;
-    },
-    end(_: TelemetrySpanEnd = {}): void {},
-  };
+  static readonly value: TelemetrySpanScope = noOpTelemetrySpanScope;
+  /** Internal: the shared no-op {@link NodeExecutionTelemetry} that {@link NoOpNodeExecutionTelemetry} re-exposes. */
+  static readonly nodeExecutionTelemetryValue: NodeExecutionTelemetry = noOpNodeExecutionTelemetry;
 }

package/src/contracts/executionPersistenceContracts.ts

@@ -148,6 +148,30 @@ export interface WorkflowRunDetailDto {
   readonly mutableState?: PersistedMutableRunState;
   readonly slotStates: ReadonlyArray<SlotExecutionStateDto>;
   readonly executionInstances: ReadonlyArray<ExecutionInstanceDto>;
+  readonly iterations?: ReadonlyArray<RunIterationDto>;
+}
+
+/**
+ * Per-item iteration projected from connection invocations and node activations.
+ *
+ * One iteration = one item processed by an agent within an activation. Multiple invocations
+ * (LLM rounds, tool calls) belonging to the same iteration share the iterationId.
+ */
+export interface RunIterationDto {
+  readonly iterationId: string;
+  readonly agentNodeId: NodeId;
+  readonly activationId: NodeActivationId;
+  readonly itemIndex: number;
+  readonly itemSummary?: string;
+  readonly status: NodeExecutionStatus;
+  readonly startedAt?: string;
+  readonly finishedAt?: string;
+  readonly invocationIds: ReadonlyArray<string>;
+  readonly parentInvocationId?: string;
+  /** Estimated cost rolled up from telemetry cost metric points, keyed by ISO currency code (e.g. "USD"). Values are minor units (cents-of-cents per the metric's `cost.currency_scale`). */
+  readonly estimatedCostMinorByCurrency?: Readonly<Record<string, number>>;
+  /** Currency scale (denominator) per currency, when present on the metric points. Joined with `estimatedCostMinorByCurrency` to format human-readable amounts. */
+  readonly estimatedCostCurrencyScaleByCurrency?: Readonly<Record<string, number>>;
 }
 
 export interface SlotExecutionStateDto {
@@ -178,6 +202,12 @@ export interface ExecutionInstanceDto {
   readonly inputJson?: JsonValue;
   readonly outputJson?: JsonValue;
   readonly error?: Readonly<NodeExecutionError>;
+  /** Per-item iteration that produced this instance. Set on connectionInvocation rows produced inside per-item runnable loops. */
+  readonly iterationId?: string;
+  /** Item index (0-based) of the iteration. */
+  readonly itemIndex?: number;
+  /** Parent invocation id when this instance was emitted by a sub-agent triggered by an outer LLM/tool call. */
+  readonly parentInvocationId?: string;
 }
 
 export interface WorkflowDetailSelectionState {

package/src/contracts/runTypes.ts

@@ -7,6 +7,7 @@ import type {
   JsonValue,
   NodeActivationId,
   NodeId,
+  NodeIterationId,
   NodeKind,
   NodeOutputs,
   OutputPortKey,
@@ -154,6 +155,12 @@ export interface ConnectionInvocationRecord {
   readonly startedAt?: string;
   readonly finishedAt?: string;
   readonly updatedAt: string;
+  /** Per-item iteration id minted by the engine when this invocation occurred inside a runnable node's per-item loop. */
+  readonly iterationId?: NodeIterationId;
+  /** Item index (0-based) of the iteration that produced this invocation. */
+  readonly itemIndex?: number;
+  /** When set, this invocation was produced inside a sub-agent triggered by the named parent invocation. */
+  readonly parentInvocationId?: ConnectionInvocationId;
 }
 
 /** Arguments for appending a {@link ConnectionInvocationRecord} (engine fills run/workflow ids and timestamps). */
@@ -169,6 +176,9 @@ export type ConnectionInvocationAppendArgs = Readonly<{
   queuedAt?: string;
   startedAt?: string;
   finishedAt?: string;
+  iterationId?: NodeIterationId;
+  itemIndex?: number;
+  parentInvocationId?: ConnectionInvocationId;
 }>;
 
 export interface RunCurrentState {

package/src/contracts/runtimeTypes.ts

@@ -5,6 +5,7 @@ import type { CredentialSessionService } from "./credentialTypes";
 import type { ExecutionTelemetry, ExecutionTelemetryFactory, NodeExecutionTelemetry } from "./telemetryTypes";
 import type {
   ConnectionInvocationAppendArgs,
+  ConnectionInvocationId,
   NodeInputsByPort,
   PersistedWorkflowSnapshot,
   PersistedWorkflowTokenRegistryLike,
@@ -25,6 +26,7 @@ import type {
   NodeActivationId,
   NodeConfigBase,
   NodeId,
+  NodeIterationId,
   NodeOutputs,
   RunnableNodeConfig,
   OutputPortKey,
@@ -154,6 +156,12 @@ export 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;
 }
 
 export interface ExecutionContextFactory {

package/src/contracts/telemetryTypes.ts

@@ -73,6 +73,14 @@ export 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;
 }
 
 export interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {

package/src/contracts/workflowTypes.ts

@@ -194,6 +194,12 @@ export type NodeOutputs = Partial<Record<OutputPortKey, Items>>;
 
 export type RunId = string;
 export 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.
+ */
+export type NodeIterationId = string;
 
 export interface ParentExecutionRef {
   runId: RunId;

package/src/events/ConnectionInvocationEventPublisher.ts

@@ -0,0 +1,46 @@
+import type { ConnectionInvocationRecord } from "../contracts/runTypes";
+import type { ParentExecutionRef } from "../types";
+import type { RunEventBus } from "./runEvents";
+
+/**
+ * Publishes per-invocation lifecycle records onto the run {@link RunEventBus}.
+ *
+ * Surgical, per-invocation events let the UI update the right-side inspector
+ * timeline as each LLM round / tool call transitions through `running` → `completed`
+ * (or `failed`) without depending on a coarse `runSaved` poll.
+ */
+export class ConnectionInvocationEventPublisher {
+  constructor(
+    private readonly eventBus: RunEventBus | undefined,
+    private readonly parent: ParentExecutionRef | undefined,
+  ) {}
+
+  async publish(record: ConnectionInvocationRecord): Promise<void> {
+    if (!this.eventBus) return;
+    const kind = this.kindFor(record);
+    if (!kind) return;
+    await this.eventBus.publish({
+      kind,
+      runId: record.runId,
+      workflowId: record.workflowId,
+      parent: this.parent,
+      at: record.updatedAt,
+      record,
+    });
+  }
+
+  private kindFor(
+    record: ConnectionInvocationRecord,
+  ): "connectionInvocationStarted" | "connectionInvocationCompleted" | "connectionInvocationFailed" | undefined {
+    if (record.status === "running" || record.status === "queued") {
+      return "connectionInvocationStarted";
+    }
+    if (record.status === "completed") {
+      return "connectionInvocationCompleted";
+    }
+    if (record.status === "failed") {
+      return "connectionInvocationFailed";
+    }
+    return undefined;
+  }
+}

package/src/events/index.ts

@@ -1,3 +1,4 @@
+export { ConnectionInvocationEventPublisher } from "./ConnectionInvocationEventPublisher";
 export { NodeEventPublisher } from "./NodeEventPublisher";
 export { InMemoryRunEventBus } from "./InMemoryRunEventBusRegistry";
 export { EventPublishingWorkflowExecutionRepository } from "./EventPublishingWorkflowExecutionRepository";

package/src/events/runEvents.ts

@@ -1,3 +1,4 @@
+import type { ConnectionInvocationRecord } from "../contracts/runTypes";
 import type { NodeExecutionSnapshot, ParentExecutionRef, PersistedRunState, RunId, WorkflowId } from "../types";
 
 export type RunEvent =
@@ -41,6 +42,30 @@ export type RunEvent =
       parent?: ParentExecutionRef;
       at: string;
       snapshot: NodeExecutionSnapshot;
+    }>
+  | Readonly<{
+      kind: "connectionInvocationStarted";
+      runId: RunId;
+      workflowId: WorkflowId;
+      parent?: ParentExecutionRef;
+      at: string;
+      record: ConnectionInvocationRecord;
+    }>
+  | Readonly<{
+      kind: "connectionInvocationCompleted";
+      runId: RunId;
+      workflowId: WorkflowId;
+      parent?: ParentExecutionRef;
+      at: string;
+      record: ConnectionInvocationRecord;
+    }>
+  | Readonly<{
+      kind: "connectionInvocationFailed";
+      runId: RunId;
+      workflowId: WorkflowId;
+      parent?: ParentExecutionRef;
+      at: string;
+      record: ConnectionInvocationRecord;
     }>;
 
 export interface RunEventSubscription {

package/src/execution/ChildExecutionScopeFactory.ts

@@ -0,0 +1,58 @@
+import { CoreTokens } from "../di/CoreTokens";
+import { inject, injectable } from "../di";
+import type {
+  ActivationIdFactory,
+  ConnectionInvocationId,
+  NodeExecutionContext,
+  NodeId,
+  RunnableNodeConfig,
+  TelemetrySpanScope,
+} from "../types";
+
+/**
+ * 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.
+ */
+@injectable()
+export class ChildExecutionScopeFactory {
+  constructor(
+    @inject(CoreTokens.ActivationIdFactory)
+    private readonly activationIdFactory: ActivationIdFactory,
+  ) {}
+
+  forSubAgent<TConfig extends RunnableNodeConfig<any, any>>(
+    args: Readonly<{
+      parentCtx: NodeExecutionContext<TConfig>;
+      childNodeId: NodeId;
+      childConfig: TConfig;
+      parentInvocationId: ConnectionInvocationId;
+      parentSpan: TelemetrySpanScope;
+    }>,
+  ): NodeExecutionContext<TConfig> {
+    const childActivationId = this.activationIdFactory.makeActivationId();
+    const childTelemetry = args.parentSpan.asNodeTelemetry({
+      nodeId: args.childNodeId,
+      activationId: childActivationId,
+    });
+    const childBinary = args.parentCtx.binary.forNode({
+      nodeId: args.childNodeId,
+      activationId: childActivationId,
+    });
+    return {
+      ...args.parentCtx,
+      nodeId: args.childNodeId,
+      activationId: childActivationId,
+      config: args.childConfig,
+      telemetry: childTelemetry,
+      binary: childBinary,
+      parentInvocationId: args.parentInvocationId,
+      iterationId: undefined,
+    };
+  }
+}

package/src/execution/ExecutionTelemetryCostTrackingDecoratorFactory.ts

@@ -62,6 +62,15 @@ export class ExecutionTelemetryCostTrackingDecoratorFactory {
           costTracking: args.costTracking.forScope(nodeTelemetry),
         });
       },
+      asNodeTelemetry: (
+        rescope: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>,
+      ): NodeExecutionTelemetry => {
+        const nodeTelemetry = args.telemetry.asNodeTelemetry(rescope);
+        return this.decorateNodeExecutionTelemetry({
+          telemetry: nodeTelemetry,
+          costTracking: args.costTracking.forScope(nodeTelemetry),
+        });
+      },
     };
   }
 
@@ -79,6 +88,15 @@ export class ExecutionTelemetryCostTrackingDecoratorFactory {
         artifact: TelemetryArtifactAttachment,
       ): Promise<TelemetryArtifactReference> | TelemetryArtifactReference => args.scope.attachArtifact(artifact),
       end: (endArgs?: TelemetrySpanEnd) => args.scope.end(endArgs),
+      asNodeTelemetry: (
+        rescope: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>,
+      ): NodeExecutionTelemetry => {
+        const nodeTelemetry = args.scope.asNodeTelemetry(rescope);
+        return this.decorateNodeExecutionTelemetry({
+          telemetry: nodeTelemetry,
+          costTracking: args.costTracking.forScope(nodeTelemetry),
+        });
+      },
     };
   }
 }

package/src/execution/NodeExecutor.ts

@@ -13,6 +13,7 @@ import type {
   TriggerNode,
   WorkflowNodeInstanceFactory,
 } from "../types";
+import { NodeIterationIdFactory } from "../workflow/definition/NodeIterationIdFactory";
 
 import { FanInMergeByOriginMerger } from "./FanInMergeByOriginMerger";
 import { ItemExprResolver } from "./ItemExprResolver";
@@ -158,13 +159,20 @@ export class NodeExecutor {
       const parsed = inputSchema.parse(item.json);
       const runnableCtx = request.ctx as NodeExecutionContext<RunnableNodeConfig>;
       const resolvedCtx = await this.itemExprResolver.resolveConfigForItem(runnableCtx, item, i, inputBatch);
-      const ctx = this.pickExecutionContext(runnableCtx, resolvedCtx);
+      const baseCtx = this.pickExecutionContext(runnableCtx, resolvedCtx);
+      // Mint a per-item iteration id and stamp it (with the item index) onto the ctx so connection
+      // invocations and telemetry written from inside `node.execute` carry the per-item identity.
+      const iterationCtx = {
+        ...baseCtx,
+        iterationId: NodeIterationIdFactory.create(),
+        itemIndex: i,
+      } as NodeExecutionContext<RunnableNodeConfig>;
       const args: RunnableNodeExecuteArgs = {
         input: parsed,
         item,
         itemIndex: i,
         items: inputBatch,
-        ctx,
+        ctx: iterationCtx,
       };
       const raw = await Promise.resolve(node.execute(args));
       const normalized = this.outputNormalizer.normalizeExecuteResult({

package/src/execution/NodeRunStateWriter.ts

@@ -28,6 +28,7 @@ export class NodeRunStateWriter implements NodeExecutionStatePublisher {
       kind: "nodeQueued" | "nodeStarted" | "nodeCompleted" | "nodeFailed",
       snapshot: NodeExecutionSnapshot,
     ) => Promise<void>,
+    private readonly publishConnectionInvocationEvent?: (record: ConnectionInvocationRecord) => Promise<void>,
   ) {}
 
   markQueued(args: {
@@ -148,11 +149,17 @@ export class NodeRunStateWriter implements NodeExecutionStatePublisher {
         startedAt: args.startedAt,
         finishedAt: args.finishedAt,
         updatedAt,
+        iterationId: args.iterationId,
+        itemIndex: args.itemIndex,
+        parentInvocationId: args.parentInvocationId,
       };
       await this.workflowExecutionRepository.save({
         ...state,
         connectionInvocations: [...(state.connectionInvocations ?? []), record],
       });
+      if (this.publishConnectionInvocationEvent) {
+        await this.publishConnectionInvocationEvent(record);
+      }
     });
   }
 

package/src/execution/NodeRunStateWriterFactory.ts

@@ -6,16 +6,20 @@ import type {
   WorkflowId,
 } from "../types";
 
+import { ConnectionInvocationEventPublisher } from "../events/ConnectionInvocationEventPublisher";
 import { NodeEventPublisher } from "../events/NodeEventPublisher";
+import type { RunEventBus } from "../events/runEvents";
 import { NodeRunStateWriter } from "./NodeRunStateWriter";
 
 export class NodeRunStateWriterFactory {
   constructor(
     private readonly workflowExecutionRepository: WorkflowExecutionRepository,
     private readonly nodeEventPublisher: NodeEventPublisher,
+    private readonly eventBus?: RunEventBus,
   ) {}
 
   create(runId: RunId, workflowId: WorkflowId, parent: ParentExecutionRef | undefined): NodeExecutionStatePublisher {
+    const connectionInvocationEventPublisher = new ConnectionInvocationEventPublisher(this.eventBus, parent);
     return new NodeRunStateWriter(
       this.workflowExecutionRepository,
       runId,
@@ -24,6 +28,9 @@ export class NodeRunStateWriterFactory {
       async (kind, snapshot) => {
         await this.nodeEventPublisher.publish(kind, snapshot);
       },
+      async (record) => {
+        await connectionInvocationEventPublisher.publish(record);
+      },
     );
   }
 }

package/src/execution/index.ts

@@ -1,4 +1,5 @@
 export { ActivationEnqueueService } from "./ActivationEnqueueService";
+export { ChildExecutionScopeFactory } from "./ChildExecutionScopeFactory";
 export { NodeActivationRequestInputPreparer } from "./NodeActivationRequestInputPreparer";
 export { NodeInputContractError } from "./NodeInputContractError";
 export { CredentialResolverFactory } from "./CredentialResolverFactory";

package/src/index.ts

@@ -14,6 +14,7 @@ export * from "./runtime-types/runtimeTypeDecorators.types";
 export * from "./serialization/ItemsInputNormalizer";
 export { DefaultExecutionBinaryService, UnavailableBinaryStorage } from "./binaries";
 export {
+  ChildExecutionScopeFactory,
   CredentialResolverFactory,
   DefaultAsyncSleeper,
   DefaultExecutionContextFactory,

package/src/runtime/EngineFactory.ts

@@ -49,6 +49,7 @@ export class EngineFactory {
     const nodeStatePublisherFactory = new NodeRunStateWriterFactory(
       deps.workflowExecutionRepository,
       nodeEventPublisher,
+      deps.eventBus,
     );
     const planningFactory = new EngineWorkflowPlanningFactory(deps.workflowNodeInstanceFactory);
     const executionLimitsPolicy = deps.executionLimitsPolicy ?? new EngineExecutionLimitsPolicy();