@codemation/host 1.0.0 → 1.0.2

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,
     }));
   }
 

package/src/infrastructure/persistence/PrismaWorkflowRunRepository.ts

@@ -49,6 +49,9 @@ type ExecutionInstanceRow = {
   successfulItemCount: number | null;
   failedItemCount: number | null;
   usedPinnedOutput: boolean | null;
+  iterationId: string | null;
+  itemIndex: number | null;
+  parentInvocationId: string | null;
 };
 
 type RunWorkItemRecord = {
@@ -513,6 +516,9 @@ export class PrismaWorkflowRunRepository implements WorkflowRunRepository, Workf
       startedAt: row.startedAt ?? undefined,
       finishedAt: row.finishedAt ?? undefined,
       updatedAt: row.updatedAt,
+      iterationId: row.iterationId ?? undefined,
+      itemIndex: row.itemIndex ?? undefined,
+      parentInvocationId: row.parentInvocationId ?? undefined,
     };
   }
 
@@ -535,6 +541,9 @@ export class PrismaWorkflowRunRepository implements WorkflowRunRepository, Workf
       inputJson: row.inputJson ? (JSON.parse(row.inputJson) as ExecutionInstanceDto["inputJson"]) : undefined,
       outputJson: row.outputJson ? (JSON.parse(row.outputJson) as ExecutionInstanceDto["outputJson"]) : undefined,
       error: row.errorJson ? (JSON.parse(row.errorJson) as ExecutionInstanceDto["error"]) : undefined,
+      iterationId: row.iterationId ?? undefined,
+      itemIndex: row.itemIndex ?? undefined,
+      parentInvocationId: row.parentInvocationId ?? undefined,
     };
   }
 
@@ -645,6 +654,9 @@ export class PrismaWorkflowRunRepository implements WorkflowRunRepository, Workf
         failedItemCount: null,
         inputStorageKind: "inline",
         outputStorageKind: "inline",
+        iterationId: inv.iterationId ?? null,
+        itemIndex: inv.itemIndex ?? null,
+        parentInvocationId: inv.parentInvocationId ?? null,
       });
       cIdx += 1;
     }