@zaip-ai/cli 1.0.4 → 1.0.7

package/templates/.agents/dashboard/modules/cost-monitor/src/server/build-cost-monitor-projection.ts

@@ -0,0 +1,622 @@
+import {
+  estimateUsageCost,
+  type FxRate,
+  type PersistedTokenUsage,
+  type PricingCatalog,
+  type PricingModel,
+} from "@zaip-ai/costs";
+import type {
+  MacroProjection,
+  OperationsProjection,
+  RunProjection,
+  UsageMetricProjection,
+  UsageProjection,
+} from "@zaip-ai/dashboard-operations/contracts";
+import { LEGACY_EFFORT_SNAPSHOT, saoPauloPeriodKey } from "@zaip-ai/dashboard-operations/contracts";
+import { includeConfiguredAgentGroups } from "../agent-groups.js";
+import {
+  type CostMonitorProjection,
+  type CostRunRow,
+  durationAggregationRows,
+} from "../contracts.js";
+import { normalizeCostProvider } from "../provider.js";
+import { aggregateTaskCostRows } from "../task-cost-groups.js";
+import { aggregateRows, averageAvailable } from "./aggregate.js";
+
+export interface CostMonitorPricingOptions {
+  catalog: PricingCatalog;
+  fxRate: FxRate | null;
+  currency?: "BRL" | "USD";
+}
+
+export interface CostMonitorCatalogOptions {
+  agentNames?: readonly string[];
+  agentNamesById?: Readonly<Record<string, string>>;
+  agentNamesByRole?: Readonly<Record<string, string>>;
+}
+
+export function buildCostMonitorProjection(
+  operations: OperationsProjection,
+  pricing?: CostMonitorPricingOptions,
+  catalog?: CostMonitorCatalogOptions,
+): CostMonitorProjection {
+  if (operations.schema_version !== 2) {
+    throw new TypeError("Cost Monitor accepts only OperationsProjection V2");
+  }
+  const currency = pricing?.currency ?? "BRL";
+  const configuredAgents = unique(catalog?.agentNames ?? []);
+  // Cost is the financial view of the same canonical Operations population.
+  // Missing telemetry remains null on a row; it must not remove the Run.
+  const completeTelemetryRuns = operations.runs;
+  const recordedRunsById = new Map(operations.runs.map((run) => [run.id, run] as const));
+  // The Cost table is a presentation of Operations metrics, not a second
+  // calculator for them. Pricing remains available as audit detail below, but
+  // must never replace an observed or recorded Operations token/cost value.
+  const tableRuns = completeTelemetryRuns;
+  const runs = tableRuns;
+  const tasksById = new Map(operations.tasks.map((task) => [task.id, task] as const));
+  const rows = runs.map((run): CostRunRow => {
+    const task = run.task_id === null ? undefined : tasksById.get(run.task_id);
+    const recordedRun = recordedRunsById.get(run.id);
+    const recorded = recordedRun?.usage.total.cost ?? { usd: null, brl: null };
+    const recordedFxRates = (recordedRun?.pricing_segments ?? [])
+      .map(
+        (segment) =>
+          segment.recorded_fx_rate ??
+          inferredFxRate(segment.recorded_usd ?? null, segment.recorded_brl ?? null),
+      )
+      .filter((rate): rate is number => rate !== null);
+    const usage = run.usage.total;
+    const audit = pricing ? auditRunCost(run, pricing) : null;
+    return {
+      run_id: run.id,
+      conversation_id: run.conversation_id,
+      task_id: run.task_id,
+      task_title: task?.title ?? run.task_id ?? run.conversation_id,
+      task_status: task?.status ?? run.status,
+      priority: task?.priority ?? "none",
+      risk: task?.risk ?? "none",
+      spec_id: run.spec_id,
+      prd_id: run.prd_id,
+      change_id: run.change_id,
+      parent_run_id: run.parent_run_id,
+      run_role: run.run_role,
+      run_kind: run.run_kind,
+      run_purpose: run.run_purpose,
+      requires_finalizer: run.requires_finalizer,
+      client: run.client,
+      agent: run.agent,
+      agent_name: resolveCatalogAgentName(run, catalog),
+      provider: normalizeCostProvider(run.provider),
+      model: run.effective_model ?? run.model,
+      requested_model: run.model,
+      reasoning_effort: run.reasoning_effort ?? null,
+      effective_reasoning_effort: run.effective_reasoning_effort,
+      service_tier: run.service_tier ?? null,
+      call_count: run.call_count,
+      status: run.status,
+      phase: effectiveCostRunPhase(run),
+      origin: run.entrypoint,
+      work_type: run.work_type,
+      started_at: run.started_at,
+      finished_at: run.finished_at,
+      ...costDuration(run),
+      estimation_basis: run.estimation_basis ?? null,
+      source_started_at: run.source_started_at ?? null,
+      source_finished_at: run.source_finished_at ?? null,
+      capture_lag_ms: run.capture_lag_ms ?? null,
+      event_count: usage.events,
+      input_tokens: usage.tokens.input,
+      cached_input_tokens: usage.tokens.cached_input,
+      output_tokens: usage.tokens.output,
+      reasoning_tokens: usage.tokens.reasoning,
+      total_tokens: recordedRun?.usage.total.tokens.total ?? null,
+      uncached_input_tokens:
+        usage.tokens.input === null
+          ? null
+          : Math.max(usage.tokens.input - (usage.tokens.cached_input ?? 0), 0),
+      visible_output_tokens:
+        usage.tokens.output === null
+          ? null
+          : Math.max(usage.tokens.output - (usage.tokens.reasoning ?? 0), 0),
+      input_rate_usd_per_million: audit?.rates.input ?? null,
+      cached_input_rate_usd_per_million: audit?.rates.cached ?? null,
+      output_rate_usd_per_million: audit?.rates.output ?? null,
+      reasoning_rate_usd_per_million: audit?.rates.reasoning ?? null,
+      context_input_multiplier: audit?.context.input ?? null,
+      context_output_multiplier: audit?.context.output ?? null,
+      speed_cost_multiplier: audit?.speedMultiplier ?? null,
+      standard_cost_usd: audit?.standardUsd ?? null,
+      speed_uplift_usd: audit?.upliftUsd ?? null,
+      input_cost_usd: audit?.components.input ?? null,
+      cached_input_cost_usd: audit?.components.cached ?? null,
+      output_cost_usd: audit?.components.output ?? null,
+      reasoning_cost_usd: audit?.components.reasoning ?? null,
+      fx_rate: currency === "BRL" ? (pricing?.fxRate?.rate ?? null) : null,
+      estimated_usd: recorded.usd,
+      estimated_brl: recorded.brl,
+      recorded_usd: recorded.usd,
+      recorded_brl: recorded.brl,
+      recorded_fx_rate: singleFxRate(recordedFxRates) ?? inferredFxRate(recorded.usd, recorded.brl),
+      coverage: usage.coverage,
+      artifact_path: run.artifact_path,
+    };
+  });
+  const group = (
+    select: (row: CostRunRow) => string,
+    label?: (key: string) => string,
+    durationScope?: "root_execution" | "all_execution" | "all_invocations",
+  ) => aggregateRows(rows, select, label, durationScope);
+  const usage = usageForRuns(tableRuns);
+  const origins = {
+    conversation: usageForRuns(tableRuns.filter((run) => run.entrypoint === "conversation")),
+    task: usageForRuns(tableRuns.filter((run) => run.entrypoint === "task")),
+    spec: usageForRuns(tableRuns.filter((run) => run.entrypoint === "spec")),
+    prd: usageForRuns(tableRuns.filter((run) => run.entrypoint === "prd")),
+  };
+  const total = usage.total;
+  const knownRows = rows.filter((row) => row.total_tokens !== null);
+  const knownTokenTotal = knownRows.reduce((sum, row) => sum + (row.total_tokens ?? 0), 0);
+  const knownCycles = knownRows.reduce((sum, row) => sum + row.event_count, 0);
+  const top10Tokens = [...knownRows]
+    .sort((left, right) => (right.total_tokens ?? 0) - (left.total_tokens ?? 0))
+    .slice(0, 10)
+    .reduce((sum, row) => sum + (row.total_tokens ?? 0), 0);
+  return {
+    schema_version: 2,
+    layout_version: 2,
+    readonly: true,
+    legacy_effort_baseline: {
+      cutoff: LEGACY_EFFORT_SNAPSHOT.cutoff,
+      duration_ms: LEGACY_EFFORT_SNAPSHOT.durationMs,
+    },
+    source: operations.source,
+    currency,
+    pricing: {
+      catalog_updated_at: pricing?.catalog.updated_at ?? null,
+      fx_rate: currency === "BRL" ? (pricing?.fxRate?.rate ?? null) : null,
+      conversion_applied: pricing !== undefined && currency === "BRL" && pricing.fxRate !== null,
+    },
+    filters: operations.filters,
+    overview: {
+      task_count: new Set(rows.flatMap((row) => (row.task_id === null ? [] : [row.task_id]))).size,
+      run_count: rows.length,
+      event_count: rows.reduce((sum, row) => sum + row.event_count, 0),
+      total_tokens: total.tokens.total,
+      estimated_usd: total.cost.usd,
+      estimated_brl: total.cost.brl,
+      // Keep the provider-recorded values distinct from the current catalog
+      // estimate, while restricting both totals to the displayed cost rows.
+      recorded_usd: availableCurrencySum(
+        tableRuns.map((run) => recordedRunsById.get(run.id)?.usage.total.cost.usd ?? null),
+      ),
+      recorded_brl: availableCurrencySum(
+        tableRuns.map((run) => recordedRunsById.get(run.id)?.usage.total.cost.brl ?? null),
+      ),
+      average_run_cost_usd: averageAvailable(rows.map((row) => row.estimated_usd)),
+      average_run_cost_brl: averageAvailable(rows.map((row) => row.estimated_brl)),
+      average_run_duration_ms: averageAvailable(
+        durationAggregationRows(rows).map((row) => row.duration_ms),
+      ),
+      known_tokens_per_cycle: knownCycles === 0 ? null : knownTokenTotal / knownCycles,
+      top_10_token_share: knownTokenTotal === 0 ? null : top10Tokens / knownTokenTotal,
+      coverage: total.coverage,
+    },
+    filters_available: {
+      providers: unique(rows.map((row) => normalizeCostProvider(row.provider))),
+      agents: unique(rows.map((row) => row.agent_name)),
+      models: unique(rows.map((row) => row.model)),
+      statuses: unique(rows.map((row) => row.task_status)),
+      priorities: unique(rows.map((row) => row.priority)),
+      risks: unique(rows.map((row) => row.risk)),
+      phases: unique(rows.map((row) => row.phase)),
+      origins: unique(rows.map((row) => row.origin)),
+      work_types: unique(rows.map((row) => row.work_type)),
+    },
+    configured_agents: configuredAgents,
+    usage,
+    origins,
+    prds: repriceMacros(operations.prds, tableRuns),
+    specs: repriceMacros(operations.specs, tableRuns),
+    runs: [...rows].sort((left, right) => right.started_at.localeCompare(left.started_at)),
+    groups: {
+      conversations: aggregateRows(
+        rows.filter((row) => row.phase === "conversation"),
+        (row) => row.conversation_id,
+        undefined,
+        "all_invocations",
+      ),
+      tasks: aggregateTaskCostRows(operations.tasks, rows),
+      providers: group((row) => normalizeCostProvider(row.provider)),
+      agents: includeConfiguredAgentGroups(
+        group((row) => row.agent_name),
+        configuredAgents,
+      ),
+      models: group((row) => row.model),
+      daily: withCreatedTaskCounts(
+        group((row) => saoPauloPeriodKey(row.started_at, "day") ?? row.started_at.slice(0, 10)),
+        operations.tasks,
+        "day",
+      ),
+      monthly: withCreatedTaskCounts(
+        group((row) => saoPauloPeriodKey(row.started_at, "month") ?? row.started_at.slice(0, 7)),
+        operations.tasks,
+        "month",
+      ),
+      annual: withCreatedTaskCounts(
+        group((row) => saoPauloPeriodKey(row.started_at, "year") ?? row.started_at.slice(0, 4)),
+        operations.tasks,
+        "year",
+      ),
+    },
+  };
+}
+
+function withCreatedTaskCounts(
+  groups: CostMonitorProjection["groups"]["daily"],
+  tasks: readonly { created_at: string }[],
+  granularity: "day" | "month" | "year",
+): CostMonitorProjection["groups"]["daily"] {
+  const byKey = new Map(
+    groups.map((group) => [
+      group.key,
+      {
+        ...group,
+        tasksActive: group.tasksActive ?? group.task_count,
+        taskDaysActive: group.tasksActive ?? group.task_count,
+        tasksCreated: 0,
+      },
+    ]),
+  );
+  for (const task of tasks) {
+    const key = saoPauloPeriodKey(task.created_at, granularity);
+    if (key === null) continue;
+    const group = byKey.get(key);
+    if (group !== undefined) group.tasksCreated = (group.tasksCreated ?? 0) + 1;
+  }
+  return [...byKey.values()];
+}
+
+export function effectiveCostRunPhase(
+  run: Pick<RunProjection, "entrypoint" | "phase">,
+): RunProjection["phase"] {
+  // Older task captures were stored as conversation before the Task was
+  // materialized. Keep their cost visible, but classify them as planning;
+  // execution remains a separate orchestrator agent call.
+  return run.entrypoint === "task" && run.phase === "conversation" ? "planning" : run.phase;
+}
+
+function resolveCatalogAgentName(
+  run: RunProjection,
+  catalog: CostMonitorCatalogOptions | undefined,
+): string {
+  if (run.agent === "codex") return "codex";
+  const catalogAgent = catalog?.agentNamesById?.[run.agent];
+  if (catalogAgent !== undefined) return catalogAgent;
+  // The root Run uses this internal identity even when the catalog projection
+  // is unavailable. It is not a legacy generic Codex call.
+  if (run.agent === "agent-orchestrator") {
+    return catalog?.agentNamesByRole?.orchestrator ?? "zaip-agent-orchestrator";
+  }
+  // Older orchestrator captures can retain their internal id as agent_name.
+  // Resolve those roots through the catalog role without overwriting either
+  // legacy Codex calls or specialised Sub-Runs, which are resolved by id.
+  if (run.agent_name.trim() === run.agent) {
+    const catalogRole = catalog?.agentNamesByRole?.[run.run_role];
+    if (catalogRole !== undefined) return catalogRole;
+  }
+  if (run.agent_name !== "codex") return run.agent_name;
+  return run.agent_name;
+}
+
+function auditRunCost(run: RunProjection, pricing: CostMonitorPricingOptions) {
+  const segments = run.pricing_segments ?? [];
+  const inputs =
+    segments.length > 0
+      ? segments.map((segment) => ({
+          provider: segment.provider,
+          model: segment.model ?? run.effective_model ?? run.model,
+          serviceTier: segment.service_tier ?? run.service_tier ?? "default",
+          usage: segmentUsage(segment),
+        }))
+      : [
+          {
+            provider: run.provider,
+            model: run.effective_model ?? run.model,
+            serviceTier: run.service_tier ?? "default",
+            usage: metricUsage(run.usage.total),
+          },
+        ];
+  const actual = inputs.map((entry) =>
+    estimateUsageCost({
+      provider:
+        entry.provider === "openai" || entry.provider === "anthropic" ? entry.provider : null,
+      model: entry.model,
+      serviceTier: entry.serviceTier,
+      usage: entry.usage,
+      catalog: pricing.catalog,
+      fxRate: null,
+    }),
+  );
+  const standard = inputs.map((entry) =>
+    estimateUsageCost({
+      provider:
+        entry.provider === "openai" || entry.provider === "anthropic" ? entry.provider : null,
+      model: entry.model,
+      serviceTier: "default",
+      usage: entry.usage,
+      catalog: pricing.catalog,
+      fxRate: null,
+    }),
+  );
+  const calculatedActualUsd = completeCurrencySum(actual.map((cost) => cost.estimated_usd));
+  const standardUsd = completeCurrencySum(standard.map((cost) => cost.estimated_usd));
+  const actualUsd = calculatedActualUsd;
+  const componentUsesStandard = actualUsd === null && standardUsd !== null;
+  const components = aggregateAuditComponents(inputs, pricing.catalog);
+  const model = pricingModelForInputs(
+    pricing.catalog,
+    inputs.map((entry) => entry.model),
+  );
+  const priority = inputs.some(
+    (entry) => entry.serviceTier === "priority" || entry.serviceTier === "fast",
+  );
+  const rate = (standardRate: number | null, priorityRate: number | null) =>
+    priority && !componentUsesStandard ? priorityRate : standardRate;
+  const longContext = inputs.some(
+    (entry) =>
+      model?.long_context_threshold_tokens !== null &&
+      model?.long_context_threshold_tokens !== undefined &&
+      (entry.usage.input ?? 0) > model.long_context_threshold_tokens,
+  );
+  return {
+    rates: {
+      input: model
+        ? rate(model.input_per_million_usd, model.priority_input_per_million_usd ?? null)
+        : null,
+      cached: model
+        ? rate(
+            model.cached_input_per_million_usd,
+            model.priority_cached_input_per_million_usd ?? null,
+          )
+        : null,
+      output: model
+        ? rate(model.output_per_million_usd, model.priority_output_per_million_usd ?? null)
+        : null,
+      reasoning: model
+        ? rate(
+            model.reasoning_per_million_usd ?? model.output_per_million_usd,
+            model.priority_reasoning_per_million_usd ??
+              model.priority_output_per_million_usd ??
+              null,
+          )
+        : null,
+    },
+    context: {
+      input: model ? (longContext ? model.long_context_input_multiplier : 1) : null,
+      output: model ? (longContext ? model.long_context_output_multiplier : 1) : null,
+    },
+    speedMultiplier:
+      actualUsd !== null && standardUsd !== null && standardUsd > 0
+        ? Math.round((actualUsd / standardUsd) * 1000) / 1000
+        : null,
+    standardUsd,
+    upliftUsd:
+      actualUsd !== null && standardUsd !== null ? roundCurrency(actualUsd - standardUsd) : null,
+    components: {
+      input: components?.input ?? null,
+      cached: components?.cached ?? null,
+      output: components?.output ?? null,
+      reasoning: components?.reasoning ?? null,
+    },
+  };
+}
+
+function aggregateAuditComponents(
+  inputs: readonly {
+    provider: string | null;
+    model: string;
+    serviceTier: string;
+    usage: PersistedTokenUsage;
+  }[],
+  catalog: PricingCatalog,
+): { input: number; cached: number; output: number; reasoning: number } | null {
+  let inputUsd = 0;
+  let cachedUsd = 0;
+  let outputUsd = 0;
+  for (const input of inputs) {
+    const model = pricingModelFor(catalog, input.model);
+    if (
+      model === null ||
+      (input.provider !== null && input.provider !== model.provider) ||
+      input.usage.input === null ||
+      input.usage.cached_input === null ||
+      input.usage.output === null
+    ) {
+      return null;
+    }
+    const longContext =
+      model.long_context_threshold_tokens !== null &&
+      input.usage.input > model.long_context_threshold_tokens;
+    const priority = input.serviceTier === "priority" || input.serviceTier === "fast";
+    const priorityInputRate = model.priority_input_per_million_usd;
+    const priorityOutputRate = model.priority_output_per_million_usd;
+    const priorityAvailable =
+      priority &&
+      !longContext &&
+      priorityInputRate !== null &&
+      priorityInputRate !== undefined &&
+      priorityOutputRate !== null &&
+      priorityOutputRate !== undefined;
+    const inputRate =
+      priorityAvailable && priorityInputRate !== null && priorityInputRate !== undefined
+        ? priorityInputRate
+        : model.input_per_million_usd;
+    const cachedRate = priorityAvailable
+      ? (model.priority_cached_input_per_million_usd ?? 0)
+      : (model.cached_input_per_million_usd ?? 0);
+    const outputRate =
+      priorityAvailable && priorityOutputRate !== null && priorityOutputRate !== undefined
+        ? priorityOutputRate
+        : model.output_per_million_usd;
+    const inputMultiplier = longContext ? model.long_context_input_multiplier : 1;
+    const outputMultiplier = longContext ? model.long_context_output_multiplier : 1;
+    const uncachedInput = Math.max(input.usage.input - input.usage.cached_input, 0);
+    inputUsd += (uncachedInput / 1_000_000) * inputRate * inputMultiplier;
+    cachedUsd += (input.usage.cached_input / 1_000_000) * cachedRate * inputMultiplier;
+    outputUsd += (input.usage.output / 1_000_000) * outputRate * outputMultiplier;
+  }
+  return {
+    input: inputUsd,
+    cached: cachedUsd,
+    output: outputUsd,
+    reasoning: 0,
+  };
+}
+
+function pricingModelFor(catalog: PricingCatalog, model: string): PricingModel | null {
+  const normalized = model.toLowerCase();
+  return (
+    catalog.models.find(
+      (entry) =>
+        entry.id.toLowerCase() === normalized ||
+        entry.aliases.some((alias) => alias.toLowerCase() === normalized),
+    ) ?? null
+  );
+}
+
+function pricingModelForInputs(
+  catalog: PricingCatalog,
+  models: readonly string[],
+): PricingModel | null {
+  const resolved = models.map((model) => pricingModelFor(catalog, model));
+  if (resolved.some((model) => model === null)) return null;
+  const first = resolved[0];
+  if (!first || resolved.some((model) => model?.id !== first.id)) return null;
+  return first;
+}
+
+function segmentUsage(
+  segment: NonNullable<RunProjection["pricing_segments"]>[number],
+): PersistedTokenUsage {
+  return {
+    input: segment.input_tokens,
+    cached_input: segment.cached_input_tokens,
+    output: segment.output_tokens,
+    reasoning: segment.reasoning_tokens,
+    total: segment.total_tokens,
+    source: "provider_reported",
+  };
+}
+
+function metricUsage(metric: UsageMetricProjection): PersistedTokenUsage {
+  return {
+    input: metric.tokens.input,
+    cached_input: metric.tokens.cached_input,
+    output: metric.tokens.output,
+    reasoning: metric.tokens.reasoning,
+    total: metric.tokens.total,
+    source: "provider_reported",
+  };
+}
+
+function completeCurrencySum(values: readonly (number | null)[]): number | null {
+  if (values.length === 0 || values.some((value) => value === null)) return null;
+  return roundCurrency(values.reduce<number>((total, value) => total + (value as number), 0));
+}
+
+function availableCurrencySum(values: readonly (number | null)[]): number | null {
+  const available = values.filter((value): value is number => value !== null);
+  return available.length === 0
+    ? null
+    : roundCurrency(available.reduce((total, value) => total + value, 0));
+}
+
+function roundCurrency(value: number): number {
+  return Math.round(value * 1_000_000) / 1_000_000;
+}
+
+function inferredFxRate(usd: number | null, brl: number | null): number | null {
+  return usd !== null && usd > 0 && brl !== null ? roundCurrency(brl / usd) : null;
+}
+
+function singleFxRate(rates: readonly number[]): number | null {
+  if (rates.length === 0) return null;
+  const first = rates[0] ?? null;
+  return rates.every((rate) => rate === first) ? first : null;
+}
+
+function costDuration(
+  run: Pick<RunProjection, "source_duration_ms" | "duration_ms" | "duration_provenance">,
+) {
+  if (typeof run.source_duration_ms === "number" && run.source_duration_ms >= 0)
+    return { duration_ms: run.source_duration_ms, duration_provenance: "observed" as const };
+  return { duration_ms: null, duration_provenance: "unavailable" as const };
+}
+
+function usageForRuns(runs: readonly RunProjection[]): UsageProjection {
+  const keys = ["conversation", "planning", "execution", "total", "new_work", "rework"] as const;
+  return Object.fromEntries(
+    keys.map((key) => [key, sumMetrics(runs.map((run) => run.usage[key]))]),
+  ) as unknown as UsageProjection;
+}
+
+function sumMetrics(metrics: readonly UsageMetricProjection[]): UsageMetricProjection {
+  const sum = (values: readonly (number | null)[]) => {
+    const known = values.filter((value): value is number => value !== null);
+    return known.length === 0 ? null : known.reduce((total, value) => total + value, 0);
+  };
+  return {
+    events: metrics.reduce((total, metric) => total + metric.events, 0),
+    tokens: {
+      input: sum(metrics.map((metric) => metric.tokens.input)),
+      cached_input: sum(metrics.map((metric) => metric.tokens.cached_input)),
+      output: sum(metrics.map((metric) => metric.tokens.output)),
+      reasoning: sum(metrics.map((metric) => metric.tokens.reasoning)),
+      total: sum(metrics.map((metric) => metric.tokens.total)),
+    },
+    cost: {
+      usd: sum(metrics.map((metric) => metric.cost.usd)),
+      brl: sum(metrics.map((metric) => metric.cost.brl)),
+    },
+    coverage: {
+      events: metrics.reduce((total, metric) => total + metric.coverage.events, 0),
+      tokens: metrics.reduce((total, metric) => total + metric.coverage.tokens, 0),
+      usd: metrics.reduce((total, metric) => total + metric.coverage.usd, 0),
+      brl: metrics.reduce((total, metric) => total + metric.coverage.brl, 0),
+    },
+  };
+}
+
+function repriceMacros(
+  macros: readonly MacroProjection[],
+  runs: readonly RunProjection[],
+): MacroProjection[] {
+  return macros.map((macro) => {
+    const declaredRunIds = new Set(macro.run_ids);
+    const relatedRuns = runs.filter(
+      (run) =>
+        declaredRunIds.has(run.id) ||
+        (macro.kind === "prd" && run.prd_id === macro.id) ||
+        (macro.kind === "spec" && run.spec_id === macro.id),
+    );
+    const relatedRunIds = new Set(relatedRuns.map((run) => run.id));
+    const rootFinancialRuns = relatedRuns.filter(
+      (run) => run.parent_run_id === null || !relatedRunIds.has(run.parent_run_id),
+    );
+    const durations = rootFinancialRuns.map((run) => costDuration(run).duration_ms);
+    const knownDurations = durations.filter((duration): duration is number => duration !== null);
+    return {
+      ...macro,
+      duration_ms:
+        rootFinancialRuns.length === 0 || knownDurations.length !== rootFinancialRuns.length
+          ? null
+          : knownDurations.reduce((sum, duration) => sum + duration, 0),
+      usage: usageForRuns(relatedRuns),
+    };
+  });
+}
+
+function unique(values: readonly string[]): string[] {
+  return [...new Set(values)].sort();
+}

package/templates/.agents/dashboard/modules/cost-monitor/src/server/index.ts

@@ -0,0 +1,2 @@
+export * from "./build-cost-monitor-projection.js";
+export * from "./run-telemetry.js";

package/templates/.agents/dashboard/modules/cost-monitor/src/server/run-telemetry.test.ts

@@ -0,0 +1,36 @@
+import type { RunTelemetryRecord } from "@zaip-ai/costs";
+import { describe, expect, it } from "vitest";
+import { projectRunTelemetry } from "./run-telemetry.js";
+
+const record: RunTelemetryRecord = {
+  run_id: "RUN-UNKNOWN",
+  started_at: "2026-07-15T12:00:00-03:00",
+  tokens: { value: null, provenance: "unavailable", source: null },
+  duration_ms: { value: null, provenance: "unavailable", source: null },
+  counterfactual_api_cost: {
+    amount: null,
+    currency: null,
+    provenance: "unavailable",
+    pricing_snapshot: null,
+    label: "counterfactual_api_estimate_not_account_charge",
+  },
+};
+
+describe("Cost Monitor Run telemetry", () => {
+  it("uses the same counterfactual and coverage contract as the CLI", () => {
+    expect(
+      projectRunTelemetry([record], {
+        effective_from: "2026-07-15T00:00:00-03:00",
+        minimum_ratio: 0.95,
+      }),
+    ).toMatchObject({
+      readonly: true,
+      kind: "counterfactual_api_cost",
+      summary: {
+        label: "counterfactual_api_estimate_not_account_charge",
+        tokens_total: null,
+        coverage: { passed: false, unavailable_runs: ["RUN-UNKNOWN"] },
+      },
+    });
+  });
+});

package/templates/.agents/dashboard/modules/cost-monitor/src/server/run-telemetry.ts

@@ -0,0 +1,22 @@
+import {
+  type CoverageRatchetPolicy,
+  type RunTelemetryRecord,
+  summarizeRunTelemetry,
+} from "@zaip-ai/costs";
+
+export interface CostMonitorTelemetryProjection {
+  readonly: true;
+  kind: "counterfactual_api_cost";
+  summary: ReturnType<typeof summarizeRunTelemetry>;
+}
+
+export function projectRunTelemetry(
+  records: readonly RunTelemetryRecord[],
+  policy: CoverageRatchetPolicy,
+): CostMonitorTelemetryProjection {
+  return {
+    readonly: true,
+    kind: "counterfactual_api_cost",
+    summary: summarizeRunTelemetry(records, policy),
+  };
+}