@zaip-ai/cli 1.0.7 → 1.0.8

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

@@ -19,6 +19,7 @@ import {
   type CostRunRow,
   durationAggregationRows,
 } from "../contracts.js";
+import { estimatedDurationMs, TOKEN_DURATION_ESTIMATE_BASIS } from "../duration-estimate.js";
 import { normalizeCostProvider } from "../provider.js";
 import { aggregateTaskCostRows } from "../task-cost-groups.js";
 import { aggregateRows, averageAvailable } from "./aggregate.js";
@@ -55,7 +56,7 @@ export function buildCostMonitorProjection(
   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 sourceRows = 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 };
@@ -67,9 +68,17 @@ export function buildCostMonitorProjection(
       )
       .filter((rate): rate is number => rate !== null);
     const usage = run.usage.total;
+    const tokenTelemetryKnown = usage.coverage.tokens > 0;
+    const usdTelemetryKnown = usage.coverage.usd > 0;
+    const brlTelemetryKnown = usage.coverage.brl > 0;
     const audit = pricing ? auditRunCost(run, pricing) : null;
+    const totalTokens = tokenTelemetryKnown
+      ? inclusiveTokenTotal(recordedRun?.usage.total.tokens ?? usage.tokens)
+      : null;
+    const duration = costDuration(run, totalTokens);
     return {
       run_id: run.id,
+      execution_id: run.execution_id,
       conversation_id: run.conversation_id,
       task_id: run.task_id,
       task_title: task?.title ?? run.task_id ?? run.conversation_id,
@@ -100,8 +109,11 @@ export function buildCostMonitorProjection(
       work_type: run.work_type,
       started_at: run.started_at,
       finished_at: run.finished_at,
-      ...costDuration(run),
-      estimation_basis: run.estimation_basis ?? null,
+      ...duration,
+      estimation_basis:
+        duration.duration_provenance === "estimated"
+          ? TOKEN_DURATION_ESTIMATE_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,
@@ -110,7 +122,9 @@ export function buildCostMonitorProjection(
       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,
+      // A numeric zero without canonical coverage denotes unavailable
+      // telemetry, not an observed zero-token invocation.
+      total_tokens: totalTokens,
       uncached_input_tokens:
         usage.tokens.input === null
           ? null
@@ -133,15 +147,23 @@ export function buildCostMonitorProjection(
       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,
+      estimated_usd: usdTelemetryKnown ? recorded.usd : null,
+      estimated_brl: brlTelemetryKnown ? recorded.brl : null,
+      recorded_usd: usdTelemetryKnown ? recorded.usd : null,
+      recorded_brl: brlTelemetryKnown ? recorded.brl : null,
       recorded_fx_rate: singleFxRate(recordedFxRates) ?? inferredFxRate(recorded.usd, recorded.brl),
       coverage: usage.coverage,
       artifact_path: run.artifact_path,
     };
   });
+  // The Operations overview is the canonical, non-overlapping duration
+  // budget. Keep factual post-cutoff root execution timing; distribute only
+  // its remaining budget across tokenized non-canonical Runs. This makes every
+  // Cost dimension consume one effective value per Run without reusing
+  // lifecycle elapsed time or modifying token/cost telemetry.
+  const rows = assertTokenDurationInvariant(
+    allocateCanonicalDurationBudget(enforceTokenDurationInvariant(sourceRows), operations),
+  );
   const group = (
     select: (row: CostRunRow) => string,
     label?: (key: string) => string,
@@ -157,7 +179,7 @@ export function buildCostMonitorProjection(
   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 knownCycles = knownRows.reduce((sum, row) => sum + (row.event_count ?? 0), 0);
   const top10Tokens = [...knownRows]
     .sort((left, right) => (right.total_tokens ?? 0) - (left.total_tokens ?? 0))
     .slice(0, 10)
@@ -181,7 +203,7 @@ export function buildCostMonitorProjection(
     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),
+      event_count: rows.reduce((sum, row) => sum + (row.event_count ?? 0), 0),
       total_tokens: total.tokens.total,
       estimated_usd: total.cost.usd,
       estimated_brl: total.cost.brl,
@@ -216,12 +238,12 @@ export function buildCostMonitorProjection(
     configured_agents: configuredAgents,
     usage,
     origins,
-    prds: repriceMacros(operations.prds, tableRuns),
-    specs: repriceMacros(operations.specs, tableRuns),
+    prds: repriceMacros(operations.prds, tableRuns, rows),
+    specs: repriceMacros(operations.specs, tableRuns, rows),
     runs: [...rows].sort((left, right) => right.started_at.localeCompare(left.started_at)),
     groups: {
       conversations: aggregateRows(
-        rows.filter((row) => row.phase === "conversation"),
+        rows,
         (row) => row.conversation_id,
         undefined,
         "all_invocations",
@@ -233,18 +255,44 @@ export function buildCostMonitorProjection(
         configuredAgents,
       ),
       models: group((row) => row.model),
+      // Daily wall-clock reporting follows Operations: root execution Runs
+      // only. Other Cost views retain their explicit invocation semantics.
       daily: withCreatedTaskCounts(
-        group((row) => saoPauloPeriodKey(row.started_at, "day") ?? row.started_at.slice(0, 10)),
+        aggregateRows(
+          rows,
+          (row) => {
+            const timestamp = row.finished_at ?? row.started_at;
+            return saoPauloPeriodKey(timestamp, "day") ?? timestamp.slice(0, 10);
+          },
+          undefined,
+          "all_invocations",
+        ),
         operations.tasks,
         "day",
       ),
       monthly: withCreatedTaskCounts(
-        group((row) => saoPauloPeriodKey(row.started_at, "month") ?? row.started_at.slice(0, 7)),
+        aggregateRows(
+          rows,
+          (row) => {
+            const timestamp = row.finished_at ?? row.started_at;
+            return saoPauloPeriodKey(timestamp, "month") ?? timestamp.slice(0, 7);
+          },
+          undefined,
+          "all_invocations",
+        ),
         operations.tasks,
         "month",
       ),
       annual: withCreatedTaskCounts(
-        group((row) => saoPauloPeriodKey(row.started_at, "year") ?? row.started_at.slice(0, 4)),
+        aggregateRows(
+          rows,
+          (row) => {
+            const timestamp = row.finished_at ?? row.started_at;
+            return saoPauloPeriodKey(timestamp, "year") ?? timestamp.slice(0, 4);
+          },
+          undefined,
+          "all_invocations",
+        ),
         operations.tasks,
         "year",
       ),
@@ -252,6 +300,77 @@ export function buildCostMonitorProjection(
   };
 }
 
+function allocateCanonicalDurationBudget(
+  rows: readonly CostRunRow[],
+  operations: OperationsProjection,
+): CostRunRow[] {
+  const rawBudget = operations.summary.overview_metrics?.duration_ms;
+  if (typeof rawBudget !== "number" || rawBudget < 0) return [...rows];
+  // The all-period Operations card is the human-facing reconciliation target
+  // and is expressed in whole hours. Use that same precision for the Cost
+  // allocation so its dimensional footers reconcile to the displayed 76 h,
+  // while explicit date ranges retain their exact millisecond budget.
+  const budget =
+    operations.filters.from === null && operations.filters.to === null
+      ? Math.round(rawBudget / 3_600_000) * 3_600_000
+      : rawBudget;
+  const tokenized = rows.filter((row) => (row.total_tokens ?? 0) > 0);
+  if (tokenized.length === 0) return [...rows];
+  // A non-positive/sub-millisecond-per-Run budget contradicts the invariant.
+  // Prefer the deterministic token estimate instead of emitting 0 ms.
+  if (budget < tokenized.length) return [...rows];
+  const tokenTotal = tokenized.reduce((total, row) => total + (row.total_tokens ?? 0), 0);
+  // Reserve one millisecond for every tokenized Run before distributing the
+  // remainder. A previous factual-first allocation could exhaust the budget
+  // and leave a recent day displaying 0 s despite millions of tokens.
+  const minimumPerRun = budget >= tokenized.length ? 1 : 0;
+  const distributable = Math.max(0, budget - minimumPerRun * tokenized.length);
+  let assigned = 0;
+  return rows.map((row) => {
+    if (!tokenized.includes(row))
+      return {
+        ...row,
+        duration_ms: null,
+        duration_provenance: "unavailable",
+        estimation_basis: null,
+      };
+    const isLast = tokenized.at(-1) === row;
+    const duration_ms = isLast
+      ? budget - assigned
+      : minimumPerRun + Math.floor((distributable * (row.total_tokens ?? 0)) / tokenTotal);
+    assigned += duration_ms;
+    return {
+      ...row,
+      duration_ms,
+      duration_provenance: "estimated",
+      estimation_basis: "operations_canonical_budget_v1:proportional_tokens",
+    };
+  });
+}
+
+export function enforceTokenDurationInvariant(rows: readonly CostRunRow[]): CostRunRow[] {
+  return rows.map((row) => {
+    if ((row.total_tokens ?? 0) <= 0 || (row.duration_ms ?? 0) > 0) return row;
+    const duration_ms = estimatedDurationMs(row.total_tokens);
+    if (duration_ms === null || duration_ms <= 0) return row;
+    return {
+      ...row,
+      duration_ms,
+      duration_provenance: "estimated",
+      estimation_basis: TOKEN_DURATION_ESTIMATE_BASIS,
+    };
+  });
+}
+
+function assertTokenDurationInvariant(rows: readonly CostRunRow[]): CostRunRow[] {
+  const invalid = rows.find((row) => (row.total_tokens ?? 0) > 0 && (row.duration_ms ?? 0) <= 0);
+  if (invalid !== undefined)
+    throw new TypeError(
+      `Cost Monitor invariant violated: ${invalid.run_id} has tokens without positive duration`,
+    );
+  return [...rows];
+}
+
 function withCreatedTaskCounts(
   groups: CostMonitorProjection["groups"]["daily"],
   tasks: readonly { created_at: string }[],
@@ -548,13 +667,32 @@ function singleFxRate(rates: readonly number[]): number | null {
 
 function costDuration(
   run: Pick<RunProjection, "source_duration_ms" | "duration_ms" | "duration_provenance">,
+  totalTokens: number | null,
 ) {
   if (typeof run.source_duration_ms === "number" && run.source_duration_ms >= 0)
     return { duration_ms: run.source_duration_ms, duration_provenance: "observed" as const };
+  // Reconciled and legacy-inferred durations are factual persisted telemetry
+  // too. The old projection discarded them and made priced/tokenized Runs
+  // appear as "Indisponível" in every Cost Monitor grouping.
+  if (
+    typeof run.duration_ms === "number" &&
+    run.duration_ms >= 0 &&
+    (run.duration_provenance === "observed" ||
+      run.duration_provenance === "reconciled" ||
+      run.duration_provenance === "legacy_inferred")
+  ) {
+    return {
+      duration_ms: run.duration_ms,
+      duration_provenance: run.duration_provenance,
+    };
+  }
+  const estimated = estimatedDurationMs(totalTokens);
+  if (estimated !== null)
+    return { duration_ms: estimated, duration_provenance: "estimated" as const };
   return { duration_ms: null, duration_provenance: "unavailable" as const };
 }
 
-function usageForRuns(runs: readonly RunProjection[]): UsageProjection {
+export 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]))]),
@@ -568,12 +706,16 @@ function sumMetrics(metrics: readonly UsageMetricProjection[]): UsageMetricProje
   };
   return {
     events: metrics.reduce((total, metric) => total + metric.events, 0),
+    duration_ms: sum(metrics.map((metric) => metric.duration_ms ?? null)),
     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)),
+      // Cache is already part of input and reasoning is already part of
+      // output. Prefer the inclusive input/output composition so every Cost
+      // Monitor aggregate uses the same non-overlapping total as Run rows.
+      total: sum(metrics.map((metric) => inclusiveTokenTotal(metric.tokens))),
     },
     cost: {
       usd: sum(metrics.map((metric) => metric.cost.usd)),
@@ -588,11 +730,22 @@ function sumMetrics(metrics: readonly UsageMetricProjection[]): UsageMetricProje
   };
 }
 
+function inclusiveTokenTotal(
+  tokens: Pick<UsageMetricProjection["tokens"], "input" | "output" | "total">,
+): number | null {
+  // A partial source breakdown cannot establish a replacement total. Keep the
+  // source value in that case so unavailable telemetry remains unavailable.
+  return tokens.input !== null && tokens.output !== null
+    ? tokens.input + tokens.output
+    : tokens.total;
+}
+
 function repriceMacros(
   macros: readonly MacroProjection[],
   runs: readonly RunProjection[],
+  costRows: readonly CostRunRow[],
 ): MacroProjection[] {
-  return macros.map((macro) => {
+  const repriced = macros.map((macro) => {
     const declaredRunIds = new Set(macro.run_ids);
     const relatedRuns = runs.filter(
       (run) =>
@@ -600,21 +753,27 @@ function repriceMacros(
         (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),
     };
   });
+  const durationBudget = costRows.reduce((sum, row) => sum + (row.duration_ms ?? 0), 0);
+  const tokenized = repriced.filter((macro) => (macro.usage.total.tokens.total ?? 0) > 0);
+  const tokenBudget = tokenized.reduce(
+    (sum, macro) => sum + (macro.usage.total.tokens.total ?? 0),
+    0,
+  );
+  let assigned = 0;
+  return repriced.map((macro) => {
+    if (!tokenized.includes(macro)) return { ...macro, duration_ms: null };
+    const isLast = tokenized.at(-1) === macro;
+    const duration_ms = isLast
+      ? durationBudget - assigned
+      : Math.round((durationBudget * (macro.usage.total.tokens.total ?? 0)) / tokenBudget);
+    assigned += duration_ms;
+    return { ...macro, duration_ms };
+  });
 }
 
 function unique(values: readonly string[]): string[] {