@codemation/core 0.7.0 → 0.8.1

package/src/contracts/CostTrackingTelemetryContract.ts

@@ -0,0 +1,47 @@
+import type { ExecutionTelemetry } from "./telemetryTypes";
+import type { TelemetryAttributes, TelemetryScope } from "./telemetryTypes";
+
+export type CostTrackingComponent = "chat" | "ocr" | "rag";
+
+export const CostTrackingTelemetryMetricNames = {
+  usage: "codemation.cost.usage",
+  estimatedCost: "codemation.cost.estimated",
+} as const;
+
+export const CostTrackingTelemetryAttributeNames = {
+  component: "cost.component",
+  provider: "cost.provider",
+  operation: "cost.operation",
+  pricingKey: "cost.pricing_key",
+  usageUnit: "cost.usage_unit",
+  currency: "cost.currency",
+  currencyScale: "cost.currency_scale",
+  estimateKind: "cost.estimate_kind",
+} as const;
+
+export interface CostTrackingUsageRecord {
+  readonly component: CostTrackingComponent;
+  readonly provider: string;
+  readonly operation: string;
+  readonly pricingKey: string;
+  readonly usageUnit: string;
+  readonly quantity: number;
+  readonly modelName?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+
+export interface CostTrackingPriceQuote {
+  readonly currency: string;
+  readonly currencyScale: number;
+  readonly estimatedAmountMinor: number;
+  readonly estimateKind: "catalog";
+}
+
+export interface CostTrackingTelemetry {
+  captureUsage(args: CostTrackingUsageRecord): Promise<CostTrackingPriceQuote | undefined>;
+  forScope(scope: TelemetryScope): CostTrackingTelemetry;
+}
+
+export interface CostTrackingTelemetryFactory {
+  create(args: Readonly<{ telemetry: ExecutionTelemetry }>): CostTrackingTelemetry;
+}

package/src/contracts/GenAiTelemetryAttributeNames.ts

@@ -0,0 +1,10 @@
+export class GenAiTelemetryAttributeNames {
+  static readonly operationName = "gen_ai.operation.name";
+  static readonly requestModel = "gen_ai.request.model";
+  static readonly usageInputTokens = "gen_ai.usage.input_tokens";
+  static readonly usageOutputTokens = "gen_ai.usage.output_tokens";
+  static readonly usageTotalTokens = "gen_ai.usage.total_tokens";
+  static readonly usageCacheReadInputTokens = "gen_ai.usage.cache_read.input_tokens";
+  static readonly usageCacheCreationInputTokens = "gen_ai.usage.cache_creation.input_tokens";
+  static readonly usageReasoningTokens = "codemation.gen_ai.usage.reasoning_tokens";
+}

package/src/contracts/NoOpCostTrackingTelemetry.ts

@@ -0,0 +1,16 @@
+import type {
+  CostTrackingPriceQuote,
+  CostTrackingTelemetry,
+  CostTrackingUsageRecord,
+} from "./CostTrackingTelemetryContract";
+import type { TelemetryScope } from "./telemetryTypes";
+
+export class NoOpCostTrackingTelemetry implements CostTrackingTelemetry {
+  async captureUsage(_: CostTrackingUsageRecord): Promise<CostTrackingPriceQuote | undefined> {
+    return undefined;
+  }
+
+  forScope(_: TelemetryScope): CostTrackingTelemetry {
+    return this;
+  }
+}

package/src/contracts/NoOpCostTrackingTelemetryFactory.ts

@@ -0,0 +1,9 @@
+import type { CostTrackingTelemetry, CostTrackingTelemetryFactory } from "./CostTrackingTelemetryContract";
+import type { ExecutionTelemetry } from "./telemetryTypes";
+import { NoOpCostTrackingTelemetry } from "./NoOpCostTrackingTelemetry";
+
+export class NoOpCostTrackingTelemetryFactory implements CostTrackingTelemetryFactory {
+  create(_: Readonly<{ telemetry: ExecutionTelemetry }>): CostTrackingTelemetry {
+    return new NoOpCostTrackingTelemetry();
+  }
+}

package/src/contracts/NoOpExecutionTelemetry.ts

@@ -0,0 +1,26 @@
+import type {
+  ExecutionTelemetry,
+  NodeExecutionTelemetry,
+  TelemetryArtifactAttachment,
+  TelemetryArtifactReference,
+  TelemetryMetricRecord,
+  TelemetrySpanEventRecord,
+} from "./telemetryTypes";
+import type { NodeActivationId, NodeId } from "./workflowTypes";
+import { NoOpNodeExecutionTelemetry } from "./NoOpNodeExecutionTelemetry";
+import { NoOpTelemetryArtifactReference } from "./NoOpTelemetryArtifactReference";
+
+export class NoOpExecutionTelemetry {
+  static readonly value: ExecutionTelemetry = {
+    traceId: "00000000000000000000000000000000",
+    spanId: "0000000000000000",
+    addSpanEvent(_: TelemetrySpanEventRecord): void {},
+    recordMetric(_: TelemetryMetricRecord): void {},
+    attachArtifact(_: TelemetryArtifactAttachment): TelemetryArtifactReference {
+      return NoOpTelemetryArtifactReference.value;
+    },
+    forNode(_: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>): NodeExecutionTelemetry {
+      return NoOpNodeExecutionTelemetry.value;
+    },
+  };
+}

package/src/contracts/NoOpExecutionTelemetryFactory.ts

@@ -0,0 +1,16 @@
+import type { ParentExecutionRef, PersistedRunPolicySnapshot, RunId, WorkflowId } from "./workflowTypes";
+import type { ExecutionTelemetry, ExecutionTelemetryFactory } from "./telemetryTypes";
+import { NoOpExecutionTelemetry } from "./NoOpExecutionTelemetry";
+
+export class NoOpExecutionTelemetryFactory implements ExecutionTelemetryFactory {
+  create(
+    _: Readonly<{
+      runId: RunId;
+      workflowId: WorkflowId;
+      parent?: ParentExecutionRef;
+      policySnapshot?: PersistedRunPolicySnapshot;
+    }>,
+  ): ExecutionTelemetry {
+    return NoOpExecutionTelemetry.value;
+  }
+}

package/src/contracts/NoOpNodeExecutionTelemetry.ts

@@ -0,0 +1,15 @@
+import type { NodeActivationId, NodeId } from "./workflowTypes";
+import type { NodeExecutionTelemetry, TelemetryChildSpanStart, TelemetrySpanScope } 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;
+    },
+  };
+}

package/src/contracts/NoOpTelemetryArtifactReference.ts

@@ -0,0 +1,9 @@
+import type { TelemetryArtifactReference } from "./telemetryTypes";
+
+export class NoOpTelemetryArtifactReference {
+  static readonly value: TelemetryArtifactReference = {
+    artifactId: "telemetry-artifact-noop",
+    traceId: undefined,
+    spanId: undefined,
+  };
+}

package/src/contracts/NoOpTelemetrySpanScope.ts

@@ -0,0 +1,22 @@
+import type {
+  TelemetryArtifactAttachment,
+  TelemetryArtifactReference,
+  TelemetryMetricRecord,
+  TelemetrySpanEnd,
+  TelemetrySpanEventRecord,
+  TelemetrySpanScope,
+} from "./telemetryTypes";
+import { NoOpTelemetryArtifactReference } from "./NoOpTelemetryArtifactReference";
+
+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 {},
+  };
+}

package/src/contracts/index.ts

@@ -5,6 +5,7 @@ export * from "./itemMeta";
 export * from "./params";
 export * from "./itemExpr";
 export * from "./runtimeTypes";
+export * from "./telemetryTypes";
 export * from "./runFinishedAtFactory";
 export * from "./runTypes";
 export * from "./webhookTypes";

package/src/contracts/runTypes.ts

@@ -112,6 +112,7 @@ export interface NodeExecutionError {
   message: string;
   name?: string;
   stack?: string;
+  details?: JsonValue;
 }
 
 export interface NodeExecutionSnapshot {
@@ -291,7 +292,9 @@ export interface RunPruneCandidate {
 }
 
 export interface WorkflowExecutionPruneRepository {
-  listRunsOlderThan(args: Readonly<{ beforeIso: string; limit?: number }>): Promise<ReadonlyArray<RunPruneCandidate>>;
+  listRunsOlderThan(
+    args: Readonly<{ nowIso: string; defaultRetentionSeconds: number; limit?: number }>,
+  ): Promise<ReadonlyArray<RunPruneCandidate>>;
 }
 
 export type RunResult =

package/src/contracts/runtimeTypes.ts

@@ -2,6 +2,7 @@ import type { ReadableStream as BinaryReadableStream } from "node:stream/web";
 import type { TypeToken } from "../di";
 import type { RunEventBus } from "../events/runEvents";
 import type { CredentialSessionService } from "./credentialTypes";
+import type { ExecutionTelemetry, ExecutionTelemetryFactory, NodeExecutionTelemetry } from "./telemetryTypes";
 import type {
   ConnectionInvocationAppendArgs,
   NodeInputsByPort,
@@ -28,6 +29,7 @@ import type {
   RunnableNodeConfig,
   OutputPortKey,
   ParentExecutionRef,
+  PersistedRunPolicySnapshot,
   RunDataFactory,
   RunDataSnapshot,
   RunId,
@@ -149,6 +151,7 @@ export interface ExecutionContext {
   now: () => Date;
   data: RunDataSnapshot;
   nodeState?: NodeExecutionStatePublisher;
+  telemetry: ExecutionTelemetry;
   binary: ExecutionBinaryService;
   getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
 }
@@ -158,11 +161,13 @@ export interface ExecutionContextFactory {
     runId: RunId;
     workflowId: WorkflowId;
     parent?: ParentExecutionRef;
+    policySnapshot?: PersistedRunPolicySnapshot;
     subworkflowDepth: number;
     engineMaxNodeActivations: number;
     engineMaxSubworkflowDepth: number;
     data: RunDataSnapshot;
     nodeState?: NodeExecutionStatePublisher;
+    telemetry?: ExecutionTelemetry;
     getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
   }): ExecutionContext;
 }
@@ -171,6 +176,7 @@ export interface NodeExecutionContext<TConfig extends NodeConfigBase = NodeConfi
   nodeId: NodeId;
   activationId: NodeActivationId;
   config: TConfig;
+  telemetry: NodeExecutionTelemetry;
   binary: NodeBinaryAttachmentService;
 }
 
@@ -416,6 +422,7 @@ export interface EngineDeps {
   activationScheduler: NodeActivationScheduler;
   runDataFactory: RunDataFactory;
   executionContextFactory: ExecutionContextFactory;
+  executionTelemetryFactory?: ExecutionTelemetryFactory;
   nodeExecutor: NodeExecutor;
   eventBus?: RunEventBus;
   tokenRegistry: PersistedWorkflowTokenRegistryLike;

package/src/contracts/telemetryTypes.ts

@@ -0,0 +1,105 @@
+import type {
+  JsonValue,
+  NodeActivationId,
+  NodeId,
+  ParentExecutionRef,
+  PersistedRunPolicySnapshot,
+  RunId,
+  WorkflowId,
+} from "./workflowTypes";
+import type { CostTrackingTelemetry } from "./CostTrackingTelemetryContract";
+
+export type TelemetryAttributePrimitive = string | number | boolean | null;
+
+export interface TelemetryAttributes {
+  readonly [key: string]: TelemetryAttributePrimitive | undefined;
+}
+
+export interface TelemetryMetricRecord {
+  readonly name: string;
+  readonly value: number;
+  readonly unit?: string;
+  readonly attributes?: TelemetryAttributes;
+}
+
+export interface TelemetrySpanEventRecord {
+  readonly name: string;
+  readonly occurredAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+
+export interface TelemetryArtifactAttachment {
+  readonly kind: string;
+  readonly contentType: string;
+  readonly previewText?: string;
+  readonly previewJson?: JsonValue;
+  readonly payloadText?: string;
+  readonly payloadJson?: JsonValue;
+  readonly bytes?: number;
+  readonly truncated?: boolean;
+  readonly expiresAt?: Date;
+}
+
+export interface TelemetryArtifactReference {
+  readonly artifactId: string;
+  readonly traceId?: string;
+  readonly spanId?: string;
+}
+
+export interface TelemetrySpanEnd {
+  readonly status?: "ok" | "error";
+  readonly statusMessage?: string;
+  readonly endedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+
+export interface TelemetryChildSpanStart {
+  readonly name: string;
+  readonly kind?: "internal" | "client";
+  readonly startedAt?: Date;
+  readonly attributes?: TelemetryAttributes;
+}
+
+export interface TelemetryScope {
+  readonly traceId?: string;
+  readonly spanId?: string;
+  readonly costTracking?: CostTrackingTelemetry;
+  addSpanEvent(args: TelemetrySpanEventRecord): Promise<void> | void;
+  recordMetric(args: TelemetryMetricRecord): Promise<void> | void;
+  attachArtifact(args: TelemetryArtifactAttachment): Promise<TelemetryArtifactReference> | TelemetryArtifactReference;
+}
+
+export interface TelemetrySpanScope extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  end(args?: TelemetrySpanEnd): Promise<void> | void;
+}
+
+export interface NodeExecutionTelemetry extends ExecutionTelemetry, TelemetrySpanScope {
+  startChildSpan(args: TelemetryChildSpanStart): TelemetrySpanScope;
+}
+
+export interface ExecutionTelemetry extends TelemetryScope {
+  readonly traceId: string;
+  readonly spanId: string;
+  forNode(args: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>): NodeExecutionTelemetry;
+}
+
+export interface ExecutionTelemetryFactory {
+  create(
+    args: Readonly<{
+      runId: RunId;
+      workflowId: WorkflowId;
+      parent?: ParentExecutionRef;
+      policySnapshot?: PersistedRunPolicySnapshot;
+    }>,
+  ): ExecutionTelemetry;
+}
+export { NoOpTelemetryArtifactReference } from "./NoOpTelemetryArtifactReference";
+export { NoOpTelemetrySpanScope } from "./NoOpTelemetrySpanScope";
+export { NoOpNodeExecutionTelemetry } from "./NoOpNodeExecutionTelemetry";
+export { NoOpExecutionTelemetry } from "./NoOpExecutionTelemetry";
+export { NoOpExecutionTelemetryFactory } from "./NoOpExecutionTelemetryFactory";
+export { CodemationTelemetryAttributeNames } from "./CodemationTelemetryAttributeNames";
+export { GenAiTelemetryAttributeNames } from "./GenAiTelemetryAttributeNames";
+export { CodemationTelemetryMetricNames } from "./CodemationTelemetryMetricNames";

package/src/contracts/workflowTypes.ts

@@ -269,11 +269,17 @@ export interface WorkflowStoragePolicyDecisionArgs {
 export interface WorkflowPrunePolicySpec {
   readonly runDataRetentionSeconds?: number;
   readonly binaryRetentionSeconds?: number;
+  readonly telemetrySpanRetentionSeconds?: number;
+  readonly telemetryArtifactRetentionSeconds?: number;
+  readonly telemetryMetricRetentionSeconds?: number;
 }
 
 export interface PersistedRunPolicySnapshot {
   readonly retentionSeconds?: number;
   readonly binaryRetentionSeconds?: number;
+  readonly telemetrySpanRetentionSeconds?: number;
+  readonly telemetryArtifactRetentionSeconds?: number;
+  readonly telemetryMetricRetentionSeconds?: number;
   readonly storagePolicy: WorkflowStoragePolicyMode;
 }
 
@@ -311,5 +317,8 @@ export type NodeErrorHandlerSpec = TypeToken<NodeErrorHandler> | NodeErrorHandle
 export interface WorkflowPolicyRuntimeDefaults {
   readonly retentionSeconds?: number;
   readonly binaryRetentionSeconds?: number;
+  readonly telemetrySpanRetentionSeconds?: number;
+  readonly telemetryArtifactRetentionSeconds?: number;
+  readonly telemetryMetricRetentionSeconds?: number;
   readonly storagePolicy?: WorkflowStoragePolicyMode;
 }

package/src/events/EventPublishingWorkflowExecutionRepository.ts

@@ -63,7 +63,7 @@ export class EventPublishingWorkflowExecutionRepository
   }
 
   async listRunsOlderThan(
-    args: Readonly<{ beforeIso: string; limit?: number }>,
+    args: Readonly<{ nowIso: string; defaultRetentionSeconds: number; limit?: number }>,
   ): Promise<ReadonlyArray<RunPruneCandidate>> {
     const pruneRepository = this.inner as unknown as Partial<WorkflowExecutionPruneRepository>;
     if (!pruneRepository.listRunsOlderThan) return [];

package/src/execution/CatalogBackedCostTrackingTelemetry.ts

@@ -0,0 +1,81 @@
+import type { CostCatalog } from "../contracts/CostCatalogContract";
+import {
+  CostTrackingTelemetryAttributeNames,
+  CostTrackingTelemetryMetricNames,
+  type CostTrackingPriceQuote,
+  type CostTrackingTelemetry,
+  type CostTrackingUsageRecord,
+} from "../contracts/CostTrackingTelemetryContract";
+import type { TelemetryAttributes, TelemetryScope } from "../types";
+
+export class CatalogBackedCostTrackingTelemetry implements CostTrackingTelemetry {
+  constructor(
+    private readonly currentScope: TelemetryScope,
+    private readonly costCatalog: CostCatalog,
+  ) {}
+
+  async captureUsage(args: CostTrackingUsageRecord): Promise<CostTrackingPriceQuote | undefined> {
+    const usageAttributes = this.createUsageAttributes(args);
+    await this.currentScope.recordMetric({
+      name: CostTrackingTelemetryMetricNames.usage,
+      value: args.quantity,
+      unit: args.usageUnit,
+      attributes: usageAttributes,
+    });
+
+    const catalogEntry = this.costCatalog.findEntry(args);
+    if (!catalogEntry) {
+      return undefined;
+    }
+
+    const estimatedAmountMinor = Math.round(args.quantity * catalogEntry.pricePerUnitMinor);
+    const costAttributes = this.createCostAttributes(args, catalogEntry.currency, catalogEntry.currencyScale);
+    await this.currentScope.recordMetric({
+      name: CostTrackingTelemetryMetricNames.estimatedCost,
+      value: estimatedAmountMinor,
+      unit: catalogEntry.currency,
+      attributes: costAttributes,
+    });
+
+    return {
+      currency: catalogEntry.currency,
+      currencyScale: catalogEntry.currencyScale,
+      estimatedAmountMinor,
+      estimateKind: "catalog",
+    };
+  }
+
+  forScope(scope: TelemetryScope): CostTrackingTelemetry {
+    // eslint-disable-next-line codemation/no-manual-di-new
+    return new CatalogBackedCostTrackingTelemetry(scope, this.costCatalog);
+  }
+
+  private createUsageAttributes(args: CostTrackingUsageRecord): TelemetryAttributes {
+    return {
+      ...args.attributes,
+      [CostTrackingTelemetryAttributeNames.component]: args.component,
+      [CostTrackingTelemetryAttributeNames.provider]: args.provider,
+      [CostTrackingTelemetryAttributeNames.operation]: args.operation,
+      [CostTrackingTelemetryAttributeNames.pricingKey]: args.pricingKey,
+      [CostTrackingTelemetryAttributeNames.usageUnit]: args.usageUnit,
+    };
+  }
+
+  private createCostAttributes(
+    args: CostTrackingUsageRecord,
+    currency: string,
+    currencyScale: number,
+  ): TelemetryAttributes {
+    return {
+      ...args.attributes,
+      [CostTrackingTelemetryAttributeNames.component]: args.component,
+      [CostTrackingTelemetryAttributeNames.provider]: args.provider,
+      [CostTrackingTelemetryAttributeNames.operation]: args.operation,
+      [CostTrackingTelemetryAttributeNames.pricingKey]: args.pricingKey,
+      [CostTrackingTelemetryAttributeNames.usageUnit]: args.usageUnit,
+      [CostTrackingTelemetryAttributeNames.currency]: currency,
+      [CostTrackingTelemetryAttributeNames.currencyScale]: currencyScale,
+      [CostTrackingTelemetryAttributeNames.estimateKind]: "catalog",
+    };
+  }
+}

package/src/execution/CatalogBackedCostTrackingTelemetryFactory.ts

@@ -0,0 +1,12 @@
+import type { CostCatalog } from "../contracts/CostCatalogContract";
+import type { CostTrackingTelemetry, CostTrackingTelemetryFactory } from "../contracts/CostTrackingTelemetryContract";
+import type { ExecutionTelemetry } from "../contracts/telemetryTypes";
+import { CatalogBackedCostTrackingTelemetry } from "./CatalogBackedCostTrackingTelemetry";
+
+export class CatalogBackedCostTrackingTelemetryFactory implements CostTrackingTelemetryFactory {
+  constructor(private readonly costCatalog: CostCatalog) {}
+
+  create(args: Readonly<{ telemetry: ExecutionTelemetry }>): CostTrackingTelemetry {
+    return new CatalogBackedCostTrackingTelemetry(args.telemetry, this.costCatalog);
+  }
+}

package/src/execution/DefaultExecutionContextFactory.ts

@@ -1,22 +1,30 @@
 import type {
   BinaryStorage,
+  CostTrackingTelemetryFactory,
   ExecutionContext,
   ExecutionContextFactory,
+  ExecutionTelemetryFactory,
   NodeExecutionStatePublisher,
   ParentExecutionRef,
   RunDataSnapshot,
   RunId,
   WorkflowId,
 } from "../types";
+import { NoOpCostTrackingTelemetryFactory, NoOpExecutionTelemetryFactory } from "../types";
 
 import {
   DefaultExecutionBinaryService,
   UnavailableBinaryStorage,
 } from "../binaries/DefaultExecutionBinaryServiceFactory";
+import { ExecutionTelemetryCostTrackingDecoratorFactory } from "./ExecutionTelemetryCostTrackingDecoratorFactory";
 
 export class DefaultExecutionContextFactory implements ExecutionContextFactory {
+  private readonly telemetryDecoratorFactory = new ExecutionTelemetryCostTrackingDecoratorFactory();
+
   constructor(
     private readonly binaryStorage: BinaryStorage = new UnavailableBinaryStorage(),
+    private readonly telemetryFactory: ExecutionTelemetryFactory = new NoOpExecutionTelemetryFactory(),
+    private readonly costTrackingFactory: CostTrackingTelemetryFactory = new NoOpCostTrackingTelemetryFactory(),
     private readonly currentDate: () => Date = () => new Date(),
   ) {}
 
@@ -24,13 +32,27 @@ export class DefaultExecutionContextFactory implements ExecutionContextFactory {
     runId: RunId;
     workflowId: WorkflowId;
     parent?: ParentExecutionRef;
+    policySnapshot?: import("../types").PersistedRunPolicySnapshot;
     subworkflowDepth: number;
     engineMaxNodeActivations: number;
     engineMaxSubworkflowDepth: number;
     data: RunDataSnapshot;
     nodeState?: NodeExecutionStatePublisher;
+    telemetry?: ExecutionContext["telemetry"];
     getCredential<TSession = unknown>(slotKey: string): Promise<TSession>;
   }): ExecutionContext {
+    const baseTelemetry =
+      args.telemetry ??
+      this.telemetryFactory.create({
+        runId: args.runId,
+        workflowId: args.workflowId,
+        parent: args.parent,
+        policySnapshot: args.policySnapshot,
+      });
+    const telemetry = this.telemetryDecoratorFactory.decorateExecutionTelemetry({
+      telemetry: baseTelemetry,
+      costTracking: baseTelemetry.costTracking ?? this.costTrackingFactory.create({ telemetry: baseTelemetry }),
+    });
     return {
       runId: args.runId,
       workflowId: args.workflowId,
@@ -41,6 +63,7 @@ export class DefaultExecutionContextFactory implements ExecutionContextFactory {
       now: this.currentDate,
       data: args.data,
       nodeState: args.nodeState,
+      telemetry,
       binary: new DefaultExecutionBinaryService(this.binaryStorage, args.workflowId, args.runId, this.currentDate),
       getCredential: args.getCredential,
     };

package/src/execution/ExecutionTelemetryCostTrackingDecoratorFactory.ts

@@ -0,0 +1,84 @@
+import type { CostTrackingTelemetry } from "../contracts/CostTrackingTelemetryContract";
+import type {
+  ExecutionTelemetry,
+  NodeExecutionTelemetry,
+  TelemetryArtifactAttachment,
+  TelemetryArtifactReference,
+  TelemetryChildSpanStart,
+  TelemetryMetricRecord,
+  TelemetrySpanEnd,
+  TelemetrySpanEventRecord,
+  TelemetrySpanScope,
+} from "../contracts/telemetryTypes";
+import type { NodeActivationId, NodeId } from "../contracts/workflowTypes";
+
+export class ExecutionTelemetryCostTrackingDecoratorFactory {
+  decorateExecutionTelemetry(args: {
+    telemetry: ExecutionTelemetry;
+    costTracking: CostTrackingTelemetry;
+  }): ExecutionTelemetry {
+    return {
+      traceId: args.telemetry.traceId,
+      spanId: args.telemetry.spanId,
+      costTracking: args.costTracking,
+      addSpanEvent: (event: TelemetrySpanEventRecord) => args.telemetry.addSpanEvent(event),
+      recordMetric: (metric: TelemetryMetricRecord) => args.telemetry.recordMetric(metric),
+      attachArtifact: (
+        artifact: TelemetryArtifactAttachment,
+      ): Promise<TelemetryArtifactReference> | TelemetryArtifactReference => args.telemetry.attachArtifact(artifact),
+      forNode: (nodeArgs: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>): NodeExecutionTelemetry => {
+        const nodeTelemetry = args.telemetry.forNode(nodeArgs);
+        return this.decorateNodeExecutionTelemetry({
+          telemetry: nodeTelemetry,
+          costTracking: args.costTracking.forScope(nodeTelemetry),
+        });
+      },
+    };
+  }
+
+  private decorateNodeExecutionTelemetry(args: {
+    telemetry: NodeExecutionTelemetry;
+    costTracking: CostTrackingTelemetry;
+  }): NodeExecutionTelemetry {
+    return {
+      traceId: args.telemetry.traceId,
+      spanId: args.telemetry.spanId,
+      costTracking: args.costTracking,
+      addSpanEvent: (event: TelemetrySpanEventRecord) => args.telemetry.addSpanEvent(event),
+      recordMetric: (metric: TelemetryMetricRecord) => args.telemetry.recordMetric(metric),
+      attachArtifact: (
+        artifact: TelemetryArtifactAttachment,
+      ): Promise<TelemetryArtifactReference> | TelemetryArtifactReference => args.telemetry.attachArtifact(artifact),
+      end: (endArgs?: TelemetrySpanEnd) => args.telemetry.end(endArgs),
+      startChildSpan: (spanArgs: TelemetryChildSpanStart): TelemetrySpanScope =>
+        this.decorateTelemetrySpanScope({
+          scope: args.telemetry.startChildSpan(spanArgs),
+          costTracking: args.costTracking,
+        }),
+      forNode: (nodeArgs: Readonly<{ nodeId: NodeId; activationId: NodeActivationId }>): NodeExecutionTelemetry => {
+        const nodeTelemetry = args.telemetry.forNode(nodeArgs);
+        return this.decorateNodeExecutionTelemetry({
+          telemetry: nodeTelemetry,
+          costTracking: args.costTracking.forScope(nodeTelemetry),
+        });
+      },
+    };
+  }
+
+  private decorateTelemetrySpanScope(args: {
+    scope: TelemetrySpanScope;
+    costTracking: CostTrackingTelemetry;
+  }): TelemetrySpanScope {
+    return {
+      traceId: args.scope.traceId,
+      spanId: args.scope.spanId,
+      costTracking: args.costTracking.forScope(args.scope),
+      addSpanEvent: (event: TelemetrySpanEventRecord) => args.scope.addSpanEvent(event),
+      recordMetric: (metric: TelemetryMetricRecord) => args.scope.recordMetric(metric),
+      attachArtifact: (
+        artifact: TelemetryArtifactAttachment,
+      ): Promise<TelemetryArtifactReference> | TelemetryArtifactReference => args.scope.attachArtifact(artifact),
+      end: (endArgs?: TelemetrySpanEnd) => args.scope.end(endArgs),
+    };
+  }
+}

package/src/execution/NodeActivationRequestComposer.ts

@@ -142,6 +142,7 @@ export class NodeActivationRequestComposer {
       nodeId: definition.id,
       activationId,
       config: definition.config,
+      telemetry: args.base.telemetry.forNode({ nodeId: definition.id, activationId }),
       binary: args.base.binary.forNode({ nodeId: definition.id, activationId }),
       getCredential: this.credentialResolverFactory.create(args.workflowId, definition.id, definition.config),
     };