@codemation/host 1.0.1 → 1.0.2

package/src/application/queries/GetIterationCostQueryHandler.ts

@@ -0,0 +1,92 @@
+import { CostTrackingTelemetryAttributeNames, CostTrackingTelemetryMetricNames, inject } from "@codemation/core";
+import { ApplicationTokens } from "../../applicationTokens";
+import type { TelemetryMetricPointRecord, TelemetryMetricPointStore } from "../../domain/telemetry/TelemetryContracts";
+import { HandlesQuery } from "../../infrastructure/di/HandlesQueryRegistry";
+import { QueryHandler } from "../bus/QueryHandler";
+import type { IterationCostRollupDto } from "../contracts/IterationCostContracts";
+import { GetIterationCostQuery } from "./GetIterationCostQuery";
+
+interface MutableCostBucket {
+  readonly iterationId: string;
+  readonly estimatedCostMinorByCurrency: Record<string, number>;
+  readonly estimatedCostCurrencyScaleByCurrency: Record<string, number>;
+}
+
+@HandlesQuery.for(GetIterationCostQuery)
+export class GetIterationCostQueryHandler extends QueryHandler<
+  GetIterationCostQuery,
+  ReadonlyArray<IterationCostRollupDto>
+> {
+  constructor(
+    @inject(ApplicationTokens.TelemetryMetricPointStore)
+    private readonly metricPointStore: TelemetryMetricPointStore,
+  ) {
+    super();
+  }
+
+  async execute(query: GetIterationCostQuery): Promise<ReadonlyArray<IterationCostRollupDto>> {
+    const points = await this.metricPointStore.list({
+      runId: query.runId,
+      metricNames: [CostTrackingTelemetryMetricNames.estimatedCost],
+    });
+    if (points.length === 0) {
+      return [];
+    }
+    const buckets = new Map<string, MutableCostBucket>();
+    for (const point of points) {
+      this.accumulate(point, buckets);
+    }
+    return [...buckets.values()].map((bucket) => ({
+      iterationId: bucket.iterationId,
+      estimatedCostMinorByCurrency: { ...bucket.estimatedCostMinorByCurrency },
+      estimatedCostCurrencyScaleByCurrency: { ...bucket.estimatedCostCurrencyScaleByCurrency },
+    }));
+  }
+
+  private accumulate(point: TelemetryMetricPointRecord, buckets: Map<string, MutableCostBucket>): void {
+    const iterationId = point.iterationId;
+    if (!iterationId || iterationId.length === 0) {
+      return;
+    }
+    const currency = this.readCurrency(point);
+    if (!currency) {
+      return;
+    }
+    const currencyScale = this.readCurrencyScale(point);
+    const bucket = this.bucketFor(iterationId, buckets);
+    bucket.estimatedCostMinorByCurrency[currency] = (bucket.estimatedCostMinorByCurrency[currency] ?? 0) + point.value;
+    if (typeof currencyScale === "number") {
+      bucket.estimatedCostCurrencyScaleByCurrency[currency] = currencyScale;
+    }
+  }
+
+  private bucketFor(iterationId: string, buckets: Map<string, MutableCostBucket>): MutableCostBucket {
+    const existing = buckets.get(iterationId);
+    if (existing) {
+      return existing;
+    }
+    const bucket: MutableCostBucket = {
+      iterationId,
+      estimatedCostMinorByCurrency: {},
+      estimatedCostCurrencyScaleByCurrency: {},
+    };
+    buckets.set(iterationId, bucket);
+    return bucket;
+  }
+
+  private readCurrency(point: TelemetryMetricPointRecord): string | undefined {
+    const fromAttribute = point.dimensions?.[CostTrackingTelemetryAttributeNames.currency];
+    if (typeof fromAttribute === "string" && fromAttribute.length > 0) {
+      return fromAttribute;
+    }
+    if (typeof point.unit === "string" && point.unit.length > 0) {
+      return point.unit;
+    }
+    return undefined;
+  }
+
+  private readCurrencyScale(point: TelemetryMetricPointRecord): number | undefined {
+    const value = point.dimensions?.[CostTrackingTelemetryAttributeNames.currencyScale];
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+  }
+}

package/src/application/queries/GetWorkflowRunDetailQueryHandler.ts

@@ -1,10 +1,14 @@
-import type { WorkflowRunDetailDto } from "@codemation/core";
+import type { RunIterationDto, WorkflowRunDetailDto } from "@codemation/core";
 import { inject } from "@codemation/core";
 import { ApplicationTokens } from "../../applicationTokens";
 import type { WorkflowRunRepository } from "../../domain/runs/WorkflowRunRepository";
 import { HandlesQuery } from "../../infrastructure/di/HandlesQueryRegistry";
 import { QueryHandler } from "../bus/QueryHandler";
+import type { IterationCostRollupDto } from "../contracts/IterationCostContracts";
+import { GetIterationCostQuery } from "./GetIterationCostQuery";
+import { GetIterationCostQueryHandler } from "./GetIterationCostQueryHandler";
 import { GetWorkflowRunDetailQuery } from "./GetWorkflowRunDetailQuery";
+import { RunIterationProjectionFactory } from "./RunIterationProjectionFactory";
 
 @HandlesQuery.for(GetWorkflowRunDetailQuery)
 export class GetWorkflowRunDetailQueryHandler extends QueryHandler<
@@ -14,11 +18,49 @@ export class GetWorkflowRunDetailQueryHandler extends QueryHandler<
   constructor(
     @inject(ApplicationTokens.WorkflowRunRepository)
     private readonly workflowRunRepository: WorkflowRunRepository,
+    @inject(RunIterationProjectionFactory)
+    private readonly runIterationProjectionFactory: RunIterationProjectionFactory,
+    @inject(GetIterationCostQueryHandler)
+    private readonly getIterationCostQueryHandler: GetIterationCostQueryHandler,
   ) {
     super();
   }
 
   async execute(query: GetWorkflowRunDetailQuery): Promise<WorkflowRunDetailDto | undefined> {
-    return await this.workflowRunRepository.loadRunDetail?.(query.runId);
+    const detail = await this.workflowRunRepository.loadRunDetail?.(query.runId);
+    if (!detail) {
+      return undefined;
+    }
+    const baseIterations = this.runIterationProjectionFactory.project(detail.executionInstances);
+    const iterations = await this.joinIterationCosts(query.runId, baseIterations);
+    return { ...detail, iterations };
+  }
+
+  private async joinIterationCosts(
+    runId: string,
+    iterations: ReadonlyArray<RunIterationDto>,
+  ): Promise<ReadonlyArray<RunIterationDto>> {
+    if (iterations.length === 0) {
+      return iterations;
+    }
+    const rollups = await this.getIterationCostQueryHandler.execute(new GetIterationCostQuery(runId));
+    if (rollups.length === 0) {
+      return iterations;
+    }
+    const rollupsByIterationId = new Map<string, IterationCostRollupDto>();
+    for (const rollup of rollups) {
+      rollupsByIterationId.set(rollup.iterationId, rollup);
+    }
+    return iterations.map((iteration) => {
+      const rollup = rollupsByIterationId.get(iteration.iterationId);
+      if (!rollup) {
+        return iteration;
+      }
+      return {
+        ...iteration,
+        estimatedCostMinorByCurrency: rollup.estimatedCostMinorByCurrency,
+        estimatedCostCurrencyScaleByCurrency: rollup.estimatedCostCurrencyScaleByCurrency,
+      };
+    });
   }
 }

package/src/application/queries/RunIterationProjectionFactory.ts

@@ -0,0 +1,123 @@
+import {
+  injectable,
+  type ExecutionInstanceDto,
+  type NodeExecutionStatus,
+  type RunIterationDto,
+} from "@codemation/core";
+
+/**
+ * Builds the per-iteration projection from a run's connection invocations.
+ *
+ * One iteration represents a single item being processed by an agent within an activation. All
+ * invocations (LLM rounds, tool calls) emitted while handling that item share the same iterationId
+ * and project into one {@link RunIterationDto}.
+ *
+ * Old runs (persisted before iteration ids existed) fall back to grouping by the agent
+ * activationId so the UI still sees coherent groups instead of a flat list.
+ */
+@injectable()
+export class RunIterationProjectionFactory {
+  project(executionInstances: ReadonlyArray<ExecutionInstanceDto>): ReadonlyArray<RunIterationDto> {
+    const invocations = executionInstances.filter((row) => row.kind === "connectionInvocation");
+    if (invocations.length === 0) {
+      return [];
+    }
+    const grouped = new Map<string, ExecutionInstanceDto[]>();
+    for (const invocation of invocations) {
+      const key = this.iterationKey(invocation);
+      if (!key) {
+        continue;
+      }
+      const bucket = grouped.get(key);
+      if (bucket) {
+        bucket.push(invocation);
+      } else {
+        grouped.set(key, [invocation]);
+      }
+    }
+    const iterations: RunIterationDto[] = [];
+    for (const [key, group] of grouped.entries()) {
+      iterations.push(this.toIteration(key, group));
+    }
+    iterations.sort((left, right) => this.compareIterations(left, right));
+    return iterations;
+  }
+
+  private iterationKey(invocation: ExecutionInstanceDto): string | undefined {
+    if (invocation.iterationId) {
+      return invocation.iterationId;
+    }
+    if (invocation.activationId) {
+      return `legacy::${invocation.workflowNodeId}::${invocation.activationId}::${invocation.itemIndex ?? 0}`;
+    }
+    return undefined;
+  }
+
+  private toIteration(iterationKey: string, group: ReadonlyArray<ExecutionInstanceDto>): RunIterationDto {
+    const sorted = [...group].sort((a, b) => this.compareInvocations(a, b));
+    const first = sorted[0]!;
+    const status = this.aggregateStatus(sorted);
+    const iterationId = first.iterationId ?? iterationKey;
+    return {
+      iterationId,
+      agentNodeId: first.workflowNodeId,
+      activationId: first.activationId ?? "synthetic",
+      itemIndex: first.itemIndex ?? 0,
+      status,
+      startedAt: this.minIso(sorted.map((row) => row.startedAt)),
+      finishedAt: status === "running" ? undefined : this.maxIso(sorted.map((row) => row.finishedAt)),
+      invocationIds: sorted.map((row) => row.instanceId),
+      parentInvocationId: first.parentInvocationId,
+    };
+  }
+
+  private aggregateStatus(group: ReadonlyArray<ExecutionInstanceDto>): NodeExecutionStatus {
+    if (group.some((row) => row.status === "failed")) {
+      return "failed";
+    }
+    if (group.every((row) => row.status === "completed")) {
+      return "completed";
+    }
+    return "running";
+  }
+
+  private minIso(values: ReadonlyArray<string | undefined>): string | undefined {
+    let min: string | undefined;
+    for (const value of values) {
+      if (!value) continue;
+      if (!min || value < min) {
+        min = value;
+      }
+    }
+    return min;
+  }
+
+  private maxIso(values: ReadonlyArray<string | undefined>): string | undefined {
+    let max: string | undefined;
+    for (const value of values) {
+      if (!value) continue;
+      if (!max || value > max) {
+        max = value;
+      }
+    }
+    return max;
+  }
+
+  private compareInvocations(left: ExecutionInstanceDto, right: ExecutionInstanceDto): number {
+    const leftStart = left.startedAt ?? left.queuedAt ?? "";
+    const rightStart = right.startedAt ?? right.queuedAt ?? "";
+    if (leftStart !== rightStart) {
+      return leftStart.localeCompare(rightStart);
+    }
+    return left.runIndex - right.runIndex;
+  }
+
+  private compareIterations(left: RunIterationDto, right: RunIterationDto): number {
+    if (left.itemIndex !== right.itemIndex) {
+      return left.itemIndex - right.itemIndex;
+    }
+    const leftStart = left.startedAt ?? "";
+    const rightStart = right.startedAt ?? "";
+    return leftStart.localeCompare(rightStart);
+  }
+}

package/src/application/queries/WorkflowQueryHandlers.ts

@@ -5,6 +5,7 @@ export { GetTelemetryDashboardRunsQueryHandler } from "./GetTelemetryDashboardRu
 export { GetTelemetryRunTraceQueryHandler } from "./GetTelemetryRunTraceQueryHandler";
 export { GetTelemetryDashboardSummaryQueryHandler } from "./GetTelemetryDashboardSummaryQueryHandler";
 export { GetTelemetryDashboardTimeseriesQueryHandler } from "./GetTelemetryDashboardTimeseriesQueryHandler";
+export { GetIterationCostQueryHandler } from "./GetIterationCostQueryHandler";
 export { GetWorkflowRunDetailQueryHandler } from "./GetWorkflowRunDetailQueryHandler";
 export { GetWorkflowDebuggerOverlayQueryHandler } from "./GetWorkflowDebuggerOverlayQueryHandler";
 export { GetWorkflowDetailQueryHandler } from "./GetWorkflowDetailQueryHandler";

package/src/application/telemetry/OtelExecutionTelemetry.types.ts

@@ -38,4 +38,7 @@ export type StoredSpanScopeArgs = StoredExecutionTelemetryDeps &
     initialStartTime?: Date;
     connectionInvocationId?: string;
     modelName?: string;
+    iterationId?: string;
+    itemIndex?: number;
+    parentInvocationId?: string;
   }>;

package/src/application/telemetry/RunEventBusTelemetryReporter.ts

@@ -67,6 +67,13 @@ export class RunEventBusTelemetryReporter {
       case "nodeFailed":
         await this.handleNodeSnapshot(event);
         return;
+      case "connectionInvocationStarted":
+      case "connectionInvocationCompleted":
+      case "connectionInvocationFailed":
+        // Per-invocation events are surfaced to the realtime UI via the websocket bridge;
+        // they do not need additional span/metric persistence here because the underlying
+        // child spans are already produced by the engine's telemetry scopes.
+        return;
     }
   }
 

package/src/application/telemetry/StoredNodeExecutionTelemetry.ts

@@ -13,6 +13,13 @@ export class StoredNodeExecutionTelemetry extends StoredTelemetrySpanScope imple
   }
 
   startChildSpan(args: TelemetryChildSpanStart): TelemetrySpanScope {
+    // Iteration / parent-invocation identity is read from the attribute bag when present (the
+    // engine passes them in for runnable per-item loops and sub-agent boundaries) and falls back
+    // to the parent scope's identity otherwise (so spans started outside the iteration loop still
+    // inherit a non-iteration scope).
+    const iterationIdFromAttrs = this.toStringAttribute(args.attributes?.["codemation.iteration.id"]);
+    const itemIndexFromAttrs = this.toNumberAttribute(args.attributes?.["codemation.iteration.index"]);
+    const parentInvocationIdFromAttrs = this.toStringAttribute(args.attributes?.["codemation.parent.invocation_id"]);
     // eslint-disable-next-line codemation/no-manual-di-new
     const span = new StoredTelemetrySpanScope({
       ...this.deps,
@@ -28,8 +35,15 @@ export class StoredNodeExecutionTelemetry extends StoredTelemetrySpanScope imple
         args.attributes?.["codemation.connection.invocation_id"] ?? args.attributes?.["connection.invocation_id"],
       ),
       modelName: this.toStringAttribute(args.attributes?.[GenAiTelemetryAttributeNames.requestModel]),
+      iterationId: iterationIdFromAttrs ?? this.iterationId,
+      itemIndex: itemIndexFromAttrs ?? this.itemIndex,
+      parentInvocationId: parentInvocationIdFromAttrs ?? this.parentInvocationId,
     });
     void span.markStarted();
     return span;
   }
+
+  private toNumberAttribute(value: unknown): number | undefined {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+  }
 }

package/src/application/telemetry/StoredTelemetrySpanScope.ts

@@ -1,4 +1,7 @@
 import type {
+  NodeActivationId,
+  NodeExecutionTelemetry,
+  NodeId,
   TelemetryArtifactAttachment,
   TelemetryArtifactReference,
   TelemetryAttributes,
@@ -25,6 +28,9 @@ export class StoredTelemetrySpanScope implements TelemetrySpanScope {
   private readonly initialStartTime: Date | undefined;
   private readonly connectionInvocationId: string | undefined;
   private readonly modelName: string | undefined;
+  protected readonly iterationId: string | undefined;
+  protected readonly itemIndex: number | undefined;
+  protected readonly parentInvocationId: string | undefined;
 
   constructor(args: StoredSpanScopeArgs) {
     this.deps = args;
@@ -39,6 +45,9 @@ export class StoredTelemetrySpanScope implements TelemetrySpanScope {
     this.initialStartTime = args.initialStartTime;
     this.connectionInvocationId = args.connectionInvocationId;
     this.modelName = args.modelName;
+    this.iterationId = args.iterationId;
+    this.itemIndex = args.itemIndex;
+    this.parentInvocationId = args.parentInvocationId;
   }
 
   async addSpanEvent(args: TelemetrySpanEventRecord): Promise<void> {
@@ -66,6 +75,9 @@ export class StoredTelemetrySpanScope implements TelemetrySpanScope {
       nodeType: enrichment.nodeType,
       nodeRole: enrichment.nodeRole,
       modelName: this.modelName,
+      iterationId: this.iterationId,
+      itemIndex: this.itemIndex,
+      parentInvocationId: this.parentInvocationId,
       retentionExpiresAt: this.deps.telemetryRetentionTimestampFactory.createMetricExpiry(
         this.deps.policySnapshot,
         observedAt,
@@ -121,16 +133,93 @@ export class StoredTelemetrySpanScope implements TelemetrySpanScope {
     });
   }
 
+  asNodeTelemetry(args: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>): NodeExecutionTelemetry {
+    return this.buildNodeTelemetryView(args);
+  }
+
+  private buildNodeTelemetryView(
+    args: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>,
+  ): NodeExecutionTelemetry {
+    // Returns a NodeExecutionTelemetry view of THIS span: children created via the returned
+    // telemetry's `startChildSpan` parent under this span (e.g. agent.tool.call) and inherit the
+    // child execution scope's nodeId/activationId. Used at the sub-agent boundary so nested
+    // runtime telemetry parents under the tool-call span instead of the orchestrator's node span.
+    const buildChildScope = (
+      childName: string,
+      childKind: "internal" | "client",
+      childAttrs?: TelemetryAttributes,
+      childStart?: Date,
+    ): StoredTelemetrySpanScope => {
+      // eslint-disable-next-line codemation/no-manual-di-new
+      const child = new StoredTelemetrySpanScope({
+        ...this.deps,
+        spanId: this.deps.otelIdentityFactory.createEphemeralSpanId(),
+        parentSpanId: this.spanId,
+        nodeId: args.nodeId,
+        activationId: args.activationId,
+        spanName: childName,
+        spanKind: childKind,
+        initialAttributes: childAttrs,
+        initialStartTime: childStart,
+        connectionInvocationId: this.toStringAttribute(
+          childAttrs?.["codemation.connection.invocation_id"] ?? childAttrs?.["connection.invocation_id"],
+        ),
+        modelName: this.toStringAttribute(childAttrs?.["gen_ai.request.model"]),
+        iterationId: this.iterationId,
+        itemIndex: this.itemIndex,
+        parentInvocationId: this.parentInvocationId,
+      });
+      void child.markStarted();
+      return child;
+    };
+    const view: NodeExecutionTelemetry = {
+      traceId: this.traceId,
+      spanId: this.spanId,
+      addSpanEvent: (event) => this.addSpanEvent(event),
+      recordMetric: (metric) => this.recordMetric(metric),
+      attachArtifact: (artifact) => this.attachArtifact(artifact),
+      end: (endArgs) => this.end(endArgs),
+      asNodeTelemetry: (rescope) => this.asNodeTelemetry(rescope),
+      forNode: () => view,
+      startChildSpan: (childArgs) =>
+        buildChildScope(childArgs.name, childArgs.kind ?? "internal", childArgs.attributes, childArgs.startedAt),
+    };
+    return view;
+  }
+
   async markStarted(): Promise<void> {
     await this.upsert({
       status: "running",
       startTime: (this.initialStartTime ?? new Date()).toISOString(),
-      attributes: this.initialAttributes,
+      attributes: this.attributesWithIdentity(this.initialAttributes),
       modelName: this.modelName,
       connectionInvocationId: this.connectionInvocationId,
+      iterationId: this.iterationId,
+      itemIndex: this.itemIndex,
+      parentInvocationId: this.parentInvocationId,
     });
   }
 
+  /**
+   * Stamps `codemation.iteration.id`, `codemation.iteration.index`, and
+   * `codemation.parent.invocation_id` onto the attribute bag so dashboards/queries can filter by
+   * iteration without joining on the dedicated columns. The dedicated columns are still the
+   * authoritative source — these attributes are convenience for downstream consumers.
+   */
+  protected attributesWithIdentity(attrs: TelemetryAttributes | undefined): TelemetryAttributes | undefined {
+    const base: Record<string, TelemetryAttributes[string]> = { ...(attrs ?? {}) };
+    if (typeof this.iterationId === "string" && this.iterationId.length > 0) {
+      base["codemation.iteration.id"] = this.iterationId;
+    }
+    if (typeof this.itemIndex === "number") {
+      base["codemation.iteration.index"] = this.itemIndex;
+    }
+    if (typeof this.parentInvocationId === "string" && this.parentInvocationId.length > 0) {
+      base["codemation.parent.invocation_id"] = this.parentInvocationId;
+    }
+    return Object.keys(base).length > 0 ? base : undefined;
+  }
+
   protected async upsert(update: Partial<TelemetrySpanUpsert>): Promise<void> {
     const enrichment = await this.resolveEnrichment();
     const observedAt = this.resolveObservedAt(update);

package/src/bootstrap/AppContainerFactory.ts

@@ -62,6 +62,7 @@ import {
   VerifyUserInviteQueryHandler,
 } from "../application/queries/UserAccountQueryHandlers";
 import {
+  GetIterationCostQueryHandler,
   GetRunBinaryAttachmentQueryHandler,
   GetTelemetryDashboardDimensionsQueryHandler,
   GetTelemetryDashboardRunsQueryHandler,
@@ -76,6 +77,7 @@ import {
   GetWorkflowSummariesQueryHandler,
   ListWorkflowRunsQueryHandler,
 } from "../application/queries/WorkflowQueryHandlers";
+import { RunIterationProjectionFactory } from "../application/queries/RunIterationProjectionFactory";
 import { OpenAiApiKeyCredentialHealthTester } from "../infrastructure/credentials/OpenAiApiKeyCredentialHealthTester";
 import { OpenAiApiKeyCredentialTypeFactory } from "../infrastructure/credentials/OpenAiApiKeyCredentialTypeFactory";
 import { CodemationPluginRegistrar } from "../infrastructure/config/CodemationPluginRegistrar";
@@ -222,6 +224,7 @@ export class AppContainerFactory {
     ListCredentialTypesQueryHandler,
     ListUserAccountsQueryHandler,
     VerifyUserInviteQueryHandler,
+    GetIterationCostQueryHandler,
     GetRunBinaryAttachmentQueryHandler,
     GetTelemetryDashboardDimensionsQueryHandler,
     GetTelemetryDashboardRunsQueryHandler,
@@ -442,6 +445,8 @@ export class AppContainerFactory {
       }),
     });
     container.registerSingleton(PrismaClientFactory, PrismaClientFactory);
+    container.registerSingleton(RunIterationProjectionFactory, RunIterationProjectionFactory);
+    container.registerSingleton(GetIterationCostQueryHandler, GetIterationCostQueryHandler);
     container.registerSingleton(WorkflowPolicyUiPresentationFactory, WorkflowPolicyUiPresentationFactory);
     container.registerSingleton(WorkflowDefinitionMapper, WorkflowDefinitionMapper);
     container.registerSingleton(RequestToWebhookItemMapper, RequestToWebhookItemMapper);

package/src/domain/telemetry/TelemetryContracts.ts

@@ -40,6 +40,9 @@ export interface TelemetrySpanRecord {
   readonly attributes?: TelemetryAttributes;
   readonly events?: ReadonlyArray<TelemetrySpanEventRecord>;
   readonly retentionExpiresAt?: string;
+  readonly iterationId?: string;
+  readonly itemIndex?: number;
+  readonly parentInvocationId?: string;
 }
 
 export interface TelemetrySpanUpsert {
@@ -64,6 +67,9 @@ export interface TelemetrySpanUpsert {
   readonly attributes?: TelemetryAttributes;
   readonly events?: ReadonlyArray<TelemetrySpanEventRecord>;
   readonly retentionExpiresAt?: string;
+  readonly iterationId?: string;
+  readonly itemIndex?: number;
+  readonly parentInvocationId?: string;
 }
 
 export interface TelemetryArtifactRecord {
@@ -115,6 +121,9 @@ export interface TelemetryMetricPointRecord {
   readonly modelName?: string;
   readonly dimensions?: TelemetryAttributes;
   readonly retentionExpiresAt?: string;
+  readonly iterationId?: string;
+  readonly itemIndex?: number;
+  readonly parentInvocationId?: string;
 }
 
 export interface TelemetryMetricPointWrite extends TelemetryMetricRecord {
@@ -130,6 +139,9 @@ export interface TelemetryMetricPointWrite extends TelemetryMetricRecord {
   readonly nodeRole?: string;
   readonly modelName?: string;
   readonly retentionExpiresAt?: string;
+  readonly iterationId?: string;
+  readonly itemIndex?: number;
+  readonly parentInvocationId?: string;
 }
 
 export interface TelemetrySpanListQuery {

package/src/infrastructure/persistence/InMemoryTelemetryMetricPointStore.ts

@@ -32,6 +32,9 @@ export class InMemoryTelemetryMetricPointStore implements TelemetryMetricPointSt
       modelName: record.modelName,
       dimensions: record.attributes,
       retentionExpiresAt: record.retentionExpiresAt,
+      iterationId: record.iterationId,
+      itemIndex: record.itemIndex,
+      parentInvocationId: record.parentInvocationId,
     };
     this.rows.set(created.metricPointId, created);
     return created;

package/src/infrastructure/persistence/InMemoryTelemetrySpanStore.ts

@@ -63,6 +63,9 @@ export class InMemoryTelemetrySpanStore implements TelemetrySpanStore {
       },
       events: [...(existing?.events ?? []), ...(update.events ?? [])],
       retentionExpiresAt: update.retentionExpiresAt ?? existing?.retentionExpiresAt,
+      iterationId: update.iterationId ?? existing?.iterationId,
+      itemIndex: update.itemIndex ?? existing?.itemIndex,
+      parentInvocationId: update.parentInvocationId ?? existing?.parentInvocationId,
     };
   }
 

package/src/infrastructure/persistence/InMemoryWorkflowRunRepository.ts

@@ -121,6 +121,29 @@ export class InMemoryWorkflowRunRepository implements WorkflowRunRepository, Wor
         error: snapshot.error,
       }),
     );
+    const invocationInstances: ExecutionInstanceDto[] = (state.connectionInvocations ?? []).map(
+      (invocation, index) => ({
+        instanceId: invocation.invocationId,
+        slotNodeId: invocation.connectionNodeId,
+        workflowNodeId: invocation.parentAgentNodeId,
+        kind: "connectionInvocation",
+        runIndex: index,
+        batchId: state.pending?.batchId ?? "batch_1",
+        activationId: invocation.parentAgentActivationId,
+        status: invocation.status,
+        queuedAt: invocation.queuedAt,
+        startedAt: invocation.startedAt,
+        finishedAt: invocation.finishedAt,
+        itemCount: 0,
+        inputJson: invocation.managedInput as never,
+        outputJson: invocation.managedOutput as never,
+        error: invocation.error,
+        iterationId: invocation.iterationId,
+        itemIndex: invocation.itemIndex,
+        parentInvocationId: invocation.parentInvocationId,
+      }),
+    );
+    executionInstances.push(...invocationInstances);
     return {
       runId: state.runId,
       workflowId: state.workflowId,

package/src/infrastructure/persistence/PrismaTelemetryMetricPointStore.ts

@@ -38,6 +38,9 @@ export class PrismaTelemetryMetricPointStore implements TelemetryMetricPointStor
         modelName: record.modelName ?? null,
         dimensionsJson: record.attributes ? JSON.stringify(record.attributes) : null,
         retentionExpiresAt: record.retentionExpiresAt ?? null,
+        iterationId: record.iterationId ?? null,
+        itemIndex: record.itemIndex ?? null,
+        parentInvocationId: record.parentInvocationId ?? null,
       },
     });
     return {
@@ -58,6 +61,9 @@ export class PrismaTelemetryMetricPointStore implements TelemetryMetricPointStor
       modelName: record.modelName,
       dimensions: record.attributes,
       retentionExpiresAt: record.retentionExpiresAt,
+      iterationId: record.iterationId,
+      itemIndex: record.itemIndex,
+      parentInvocationId: record.parentInvocationId,
     };
   }
 
@@ -96,6 +102,9 @@ export class PrismaTelemetryMetricPointStore implements TelemetryMetricPointStor
       modelName: row.modelName ?? undefined,
       dimensions: this.parseJson<TelemetryAttributes>(row.dimensionsJson),
       retentionExpiresAt: row.retentionExpiresAt ?? undefined,
+      iterationId: row.iterationId ?? undefined,
+      itemIndex: row.itemIndex ?? undefined,
+      parentInvocationId: row.parentInvocationId ?? undefined,
     }));
   }
 

package/src/infrastructure/persistence/PrismaTelemetrySpanStore.ts

@@ -49,6 +49,9 @@ export class PrismaTelemetrySpanStore implements TelemetrySpanStore {
       attributesJson: attributes ? JSON.stringify(attributes) : null,
       eventsJson: events.length > 0 ? JSON.stringify(events) : null,
       retentionExpiresAt: record.retentionExpiresAt ?? existing?.retentionExpiresAt ?? null,
+      iterationId: record.iterationId ?? existing?.iterationId ?? null,
+      itemIndex: record.itemIndex ?? existing?.itemIndex ?? null,
+      parentInvocationId: record.parentInvocationId ?? existing?.parentInvocationId ?? null,
       updatedAt: new Date().toISOString(),
     };
     await this.prisma.telemetrySpan.upsert({
@@ -100,6 +103,9 @@ export class PrismaTelemetrySpanStore implements TelemetrySpanStore {
       attributes: this.parseJson<TelemetryAttributes>(row.attributesJson),
       events: this.parseJson<ReadonlyArray<TelemetrySpanEventRecord>>(row.eventsJson) ?? [],
       retentionExpiresAt: row.retentionExpiresAt ?? undefined,
+      iterationId: row.iterationId ?? undefined,
+      itemIndex: row.itemIndex ?? undefined,
+      parentInvocationId: row.parentInvocationId ?? undefined,
     }));
   }