@zaip-ai/cli 1.0.7 → 1.3.0

package/templates/.agents/dashboard/modules/cost-monitor/src/react/CostCharts.tsx

@@ -1,3 +1,4 @@
+import type { UsageProjection } from "@zaip-ai/dashboard-operations/contracts";
 import { formatCompactNumber, formatCurrency, formatDurationMs } from "@zaip-ai/dashboard-ui";
 import type { CostGroupRow, CostRunRow } from "../contracts.js";
 import type { CostCurrency, CostLocale } from "./cost-monitor-copy.js";
@@ -8,30 +9,32 @@ export function CostCharts({
   rows,
   daily,
   models,
+  summaryUsage,
   currency,
   locale,
 }: {
   rows: readonly CostRunRow[];
   daily: readonly CostGroupRow[];
   models: readonly CostGroupRow[];
+  /**
+   * The summary route intentionally omits historical Run rows, but retains
+   * complete usage totals by phase. Prefer those aggregates when supplied so
+   * an aggregate-only overview never presents them as empty data.
+   */
+  summaryUsage?: Pick<UsageProjection, "conversation" | "planning" | "execution" | "total">;
   currency: CostCurrency;
   locale: CostLocale;
 }) {
   const copy = costChartsCopy(locale);
-  const tokenMix = [
-    [copy.input, observed(rows.map((row) => row.input_tokens))],
-    [copy.cache, observed(rows.map((row) => row.cached_input_tokens))],
-    [copy.output, observed(rows.map((row) => row.output_tokens))],
-    [copy.reasoning, observed(rows.map((row) => row.reasoning_tokens))],
-  ] as const;
+  const tokenMix = chartTokenMix(rows, summaryUsage, copy);
   const availableModels = modelsWithObservedCost(models, currency);
   const maxModel = Math.max(1, ...availableModels.map((row) => cost(row, currency) ?? 0));
   const sevenDays = lastSevenDays(daily, currency);
-  const maxDaily = Math.max(1, ...sevenDays.map((day) => day.value));
+  const maxDaily = Math.max(1, ...sevenDays.map((day) => day.value ?? 0));
   const trendPoints = sevenDays.map((day, index) => ({
     ...day,
     x: (index / (sevenDays.length - 1)) * 100,
-    y: 82 - (day.value / maxDaily) * 58,
+    y: 82 - ((day.value ?? 0) / maxDaily) * 58,
   }));
   const points = trendPoints.map((point) => `${point.x},${point.y}`).join(" ");
   return (
@@ -73,7 +76,7 @@ export function CostCharts({
               key={point.key}
               style={{ left: `${point.x}%`, top: `${point.y}%` }}
             >
-              {formatCurrency(point.value, currency, locale)}
+              {formatNullableCurrency(point.value, currency, locale)}
             </span>
           ))}
         </div>
@@ -102,7 +105,7 @@ export function CostCharts({
                   }}
                 />
               </i>
-              <strong>{formatCurrency(cost(row, currency), currency, locale)}</strong>
+              <strong>{formatNullableCurrency(cost(row, currency), currency, locale)}</strong>
             </div>
           ))}
         </div>
@@ -119,7 +122,7 @@ export function CostCharts({
             <div key={label}>
               <i style={{ background: colors[index] }} />
               <span>{label}</span>
-              <strong>{formatCompactNumber(value, locale)}</strong>
+              <strong>{formatNullableNumber(value, locale)}</strong>
             </div>
           ))}
         </div>
@@ -133,12 +136,7 @@ export function CostCharts({
         </header>
         <div className="phase-strip">
           {(["conversation", "planning", "execution"] as const).map((phase, index) => {
-            const phaseRows = rows.filter((row) => row.phase === phase);
-            const duration = observed(phaseRows.map((row) => row.duration_ms));
-            const tokens = observed(phaseRows.map((row) => row.total_tokens));
-            const phaseCost = observed(
-              phaseRows.map((row) => (currency === "BRL" ? row.estimated_brl : row.estimated_usd)),
-            );
+            const metrics = chartPhaseMetrics(phase, rows, summaryUsage, currency);
             return (
               <div key={phase}>
                 <div className="phase-name">
@@ -148,15 +146,15 @@ export function CostCharts({
                 <dl className="phase-metrics">
                   <div>
                     <dt>{locale === "pt-BR" ? "Tempo" : "Time"}</dt>
-                    <dd>{formatDurationMs(duration, locale)}</dd>
+                    <dd>{formatNullableDuration(metrics.duration, locale)}</dd>
                   </div>
                   <div>
                     <dt>Tokens</dt>
-                    <dd>{formatCompactNumber(tokens, locale)}</dd>
+                    <dd>{formatNullableNumber(metrics.tokens, locale)}</dd>
                   </div>
                   <div>
                     <dt>{locale === "pt-BR" ? "Custo" : "Cost"}</dt>
-                    <dd>{formatCurrency(phaseCost, currency, locale)}</dd>
+                    <dd>{formatNullableCurrency(metrics.cost, currency, locale)}</dd>
                   </div>
                 </dl>
               </div>
@@ -168,6 +166,84 @@ export function CostCharts({
   );
 }
 
+export function chartTokenMix(
+  rows: readonly CostRunRow[],
+  summaryUsage: Pick<UsageProjection, "total"> | undefined,
+  copy: Pick<
+    ReturnType<typeof costChartsCopy>,
+    "inputWithoutCache" | "cachedInput" | "visibleOutput" | "reasoning" | "total"
+  >,
+) {
+  const tokens = summaryUsage?.total.tokens;
+  const input = tokens?.input ?? observed(rows.map((row) => row.input_tokens));
+  const cachedInput = subsetTokenTotal(
+    tokens?.cached_input ?? observed(rows.map((row) => row.cached_input_tokens)),
+    input,
+  );
+  const output = tokens?.output ?? observed(rows.map((row) => row.output_tokens));
+  const reasoning = subsetTokenTotal(
+    tokens?.reasoning ?? observed(rows.map((row) => row.reasoning_tokens)),
+    output,
+  );
+  const total = inclusiveTokenTotal(
+    input,
+    output,
+    tokens?.total ?? observed(rows.map((row) => row.total_tokens)),
+  );
+  return [
+    // Cache is inside Input and reasoning is inside Output. The chart must
+    // show mutually exclusive remainders rather than overlapping totals.
+    [copy.inputWithoutCache, exclusiveTokenRemainder(input, cachedInput)],
+    [copy.cachedInput, cachedInput],
+    [copy.visibleOutput, exclusiveTokenRemainder(output, reasoning)],
+    [copy.reasoning, reasoning],
+    [copy.total, total],
+  ] as const;
+}
+
+export function chartPhaseMetrics(
+  phase: "conversation" | "planning" | "execution",
+  rows: readonly CostRunRow[],
+  summaryUsage: Pick<UsageProjection, "conversation" | "planning" | "execution"> | undefined,
+  currency: CostCurrency,
+) {
+  const phaseRows = rows.filter((row) => row.phase === phase);
+  const usage = summaryUsage?.[phase];
+  return {
+    // Aggregate-only data carries observed invocation duration by phase. It
+    // remains distinct from the canonical root-Run wall-clock duration.
+    duration:
+      usage?.duration_ms ??
+      observed(
+        phaseRows.map((row) =>
+          row.duration_provenance === "observed" ||
+          row.duration_provenance === "reconciled" ||
+          row.duration_provenance === "legacy_inferred"
+            ? row.duration_ms
+            : null,
+        ),
+      ),
+    tokens: usage?.tokens.total ?? observed(phaseRows.map((row) => row.total_tokens)),
+    cost:
+      (currency === "BRL" ? usage?.cost.brl : usage?.cost.usd) ??
+      observed(
+        phaseRows.map((row) => (currency === "BRL" ? row.estimated_brl : row.estimated_usd)),
+      ),
+  };
+}
+
+function formatNullableDuration(value: number | null, locale: CostLocale) {
+  return value === null || value === 0 ? "0" : formatDurationMs(value, locale);
+}
+
+function formatNullableNumber(value: number | null, locale: CostLocale) {
+  return formatCompactNumber(value ?? 0, locale);
+}
+
+function formatNullableCurrency(value: number | null, currency: CostCurrency, locale: CostLocale) {
+  return formatCurrency(value ?? 0, currency, locale);
+}
+
 export function costChartsCopy(locale: CostLocale) {
   return locale === "pt-BR"
     ? {
@@ -182,10 +258,11 @@ export function costChartsCopy(locale: CostLocale) {
         tokenMix: "Mix de tokens",
         phases: "FASES",
         totalsByPhase: "Totais por fase",
-        input: "Entrada",
-        cache: "Cache",
-        output: "Saída",
+        inputWithoutCache: "Input sem cache",
+        cachedInput: "Cache",
+        visibleOutput: "Output visível",
         reasoning: "Raciocínio",
+        total: "Total (input + output)",
       }
     : {
         analyticsView: "Analytics overview",
@@ -199,10 +276,11 @@ export function costChartsCopy(locale: CostLocale) {
         tokenMix: "Token mix",
         phases: "PHASES",
         totalsByPhase: "Totals by phase",
-        input: "Input",
-        cache: "Cache",
-        output: "Output",
+        inputWithoutCache: "Uncached input",
+        cachedInput: "Cached input",
+        visibleOutput: "Visible output",
         reasoning: "Reasoning",
+        total: "Total (input + output)",
       };
 }
 
@@ -221,27 +299,40 @@ function cost(row: CostGroupRow, currency: CostCurrency) {
 }
 
 export function modelsWithObservedCost(models: readonly CostGroupRow[], currency: CostCurrency) {
-  return models.filter((row) => cost(row, currency) !== null);
+  return models
+    .filter((row) => cost(row, currency) !== null)
+    .sort((left, right) => {
+      const difference = (cost(right, currency) ?? 0) - (cost(left, currency) ?? 0);
+      return difference !== 0 ? difference : left.key.localeCompare(right.key);
+    });
 }
 
-export function lastSevenDays(
-  daily: readonly CostGroupRow[],
-  currency: CostCurrency,
-  now = new Date(),
-) {
-  const values = new Map(daily.map((row) => [row.key, cost(row, currency) ?? 0]));
-  return Array.from({ length: 7 }, (_, index) => {
-    const date = new Date(now.getFullYear(), now.getMonth(), now.getDate() - (6 - index));
-    const key = localDateKey(date);
-    return { date, key, value: values.get(key) ?? 0 };
-  });
+function subsetTokenTotal(subset: number | null, total: number | null): number | null {
+  if (subset === null || total === null || subset > total) return null;
+  return subset;
+}
+
+function exclusiveTokenRemainder(total: number | null, subset: number | null): number | null {
+  return total === null || subset === null ? null : total - subset;
 }
 
-function localDateKey(date: Date) {
-  const year = date.getFullYear();
-  const month = String(date.getMonth() + 1).padStart(2, "0");
-  const day = String(date.getDate()).padStart(2, "0");
-  return `${year}-${month}-${day}`;
+function inclusiveTokenTotal(
+  input: number | null,
+  output: number | null,
+  reportedTotal: number | null,
+): number | null {
+  return input !== null && output !== null ? input + output : reportedTotal;
+}
+
+export function lastSevenDays(daily: readonly CostGroupRow[], currency: CostCurrency) {
+  const values = new Map(daily.map((row) => [row.key, cost(row, currency)]));
+  const buckets = [...values.keys()].sort().slice(-7);
+  return buckets.map((key) => {
+    const date = new Date(`${key}T12:00:00`);
+    // A missing calendar bucket is a real zero; a present bucket with missing
+    // financial telemetry remains unavailable rather than being coerced to zero.
+    return { date, key, value: values.get(key)! };
+  });
 }
 
 function formatTrendDay(date: Date, locale: CostLocale) {

package/templates/.agents/dashboard/modules/cost-monitor/src/react/CostFilters.tsx

@@ -4,7 +4,8 @@ import type { CostMonitorProjection } from "../contracts.js";
 import type { CostCurrency, CostLocale } from "./cost-monitor-copy.js";
 
 export type CostPeriod = "all" | "7" | "30" | "90" | "month";
-export const defaultCostPeriod: CostPeriod = "all";
+/** Cost Monitor opens on the current Sao Paulo month, matching Operations. */
+export const defaultCostPeriod: CostPeriod = "month";
 
 export function costPeriodDateRange(
   period: CostPeriod,
@@ -38,6 +39,9 @@ export async function loadCostMonitorPeriod({
   fetcher?: typeof fetch;
 }): Promise<CostMonitorProjection> {
   const query = new URLSearchParams({ currency });
+  // Period and filter changes hydrate aggregate read models only. Entity
+  // detail is loaded through its dedicated bounded page route.
+  query.set("scope", "summary");
   if (from !== undefined) query.set("from", from);
   if (to !== undefined) query.set("to", to);
   if (filters) {
@@ -63,6 +67,123 @@ export async function loadCostMonitorPeriod({
   return (await response.json()) as CostMonitorProjection;
 }
 
+/** Exact dimensional projection, requested only after a dimensional tab opens. */
+export async function loadCostMonitorDetail({
+  currency,
+  filters,
+  from,
+  refresh,
+  to,
+  signal,
+  fetcher = fetch,
+}: {
+  currency: CostCurrency;
+  filters?: CostFilterState;
+  from?: string;
+  refresh?: string | null;
+  to?: string;
+  signal?: AbortSignal;
+  fetcher?: typeof fetch;
+}): Promise<CostMonitorProjection> {
+  const query = costMonitorQuery({
+    currency,
+    ...(filters === undefined ? {} : { filters }),
+    ...(from === undefined ? {} : { from }),
+    ...(refresh === undefined ? {} : { refresh }),
+    ...(to === undefined ? {} : { to }),
+  });
+  query.set("scope", "detail");
+  const response = await fetcher(`/api/v2/cost-monitor?${query.toString()}`, {
+    ...(signal === undefined ? {} : { signal }),
+  });
+  if (!response.ok)
+    throw new Error(
+      (await response.text()).trim() || `Cost Monitor detail request failed (${response.status})`,
+    );
+  return (await response.json()) as CostMonitorProjection;
+}
+
+export async function loadCostMonitorRunPage({
+  currency,
+  filters,
+  from,
+  offset,
+  refresh,
+  to,
+  signal,
+  fetcher = fetch,
+}: {
+  currency: CostCurrency;
+  filters?: CostFilterState;
+  from?: string;
+  offset: number;
+  refresh?: string | null;
+  to?: string;
+  signal?: AbortSignal;
+  fetcher?: typeof fetch;
+}): Promise<CostRunPage> {
+  const query = costMonitorQuery({
+    currency,
+    ...(filters === undefined ? {} : { filters }),
+    ...(from === undefined ? {} : { from }),
+    ...(refresh === undefined ? {} : { refresh }),
+    ...(to === undefined ? {} : { to }),
+  });
+  query.set("scope", "runs");
+  query.set("offset", String(Math.max(0, offset)));
+  query.set("limit", "100");
+  const response = await fetcher(`/api/v2/cost-monitor?${query.toString()}`, {
+    ...(signal === undefined ? {} : { signal }),
+  });
+  if (!response.ok) {
+    const detail = (await response.text()).trim();
+    throw new Error(detail || `Cost Monitor run page request failed (${response.status})`);
+  }
+  const payload = (await response.json()) as Pick<CostMonitorProjection, "runs" | "run_page">;
+  return {
+    page_only: true,
+    runs: payload.runs,
+    run_page: payload.run_page ?? { offset, limit: 100, total: null, has_more: false },
+  };
+}
+
+/** Complete contract for the incremental Run endpoint; it is not a summary projection. */
+export interface CostRunPage {
+  page_only: true;
+  runs: CostMonitorProjection["runs"];
+  run_page: { offset: number; limit: number; total: number | null; has_more: boolean };
+}
+
+function costMonitorQuery({
+  currency,
+  filters,
+  from,
+  refresh,
+  to,
+}: {
+  currency: CostCurrency;
+  filters?: CostFilterState;
+  from?: string;
+  refresh?: string | null;
+  to?: string;
+}): URLSearchParams {
+  const query = new URLSearchParams({ currency });
+  if (from !== undefined) query.set("from", from);
+  if (to !== undefined) query.set("to", to);
+  if (filters) {
+    const manifestFilters = [
+      ["provider", filters.provider],
+      ["phase", filters.phase],
+      ["agent", filters.agent],
+      ["model", filters.model],
+      ["status", filters.status],
+    ] as const;
+    for (const [key, value] of manifestFilters) if (value) query.set(key, value);
+  }
+  if (refresh) query.set("refresh", refresh);
+  return query;
+}
+
 export function useCostMonitorPeriod({
   currency,
   data,
@@ -91,10 +212,14 @@ export function useCostMonitorPeriod({
   const [periodLoading, setPeriodLoading] = useState(false);
   const [periodError, setPeriodError] = useState<string | null>(null);
   const initialDataRef = useRef(true);
+  const loadPeriodRef = useRef(loadPeriod);
+  loadPeriodRef.current = loadPeriod;
   const requestedRange =
     dateRange === undefined
       ? costPeriodDateRange(period)
       : { from: dateRange.start, to: dateRange.end };
+  const requestedFrom = requestedRange?.from;
+  const requestedTo = requestedRange?.to;
   const shouldFetch = shouldFetchCostPeriod({ filters, period, snapshotBacked });
   useEffect(() => {
     if (!shouldFetch) {
@@ -109,13 +234,16 @@ export function useCostMonitorPeriod({
     const controller = new AbortController();
     setPeriodLoading(true);
     setPeriodError(null);
-    void loadPeriod({
-      currency,
-      filters,
-      ...(requestedRange === undefined ? {} : { from: requestedRange.from, to: requestedRange.to }),
-      refresh: lastUpdatedAt,
-      signal: controller.signal,
-    })
+    void loadPeriodRef
+      .current({
+        currency,
+        filters,
+        ...(requestedFrom === undefined || requestedTo === undefined
+          ? {}
+          : { from: requestedFrom, to: requestedTo }),
+        refresh: lastUpdatedAt,
+        signal: controller.signal,
+      })
       .then((nextPeriodData) => {
         if (controller.signal.aborted) return;
         setPeriodDataBase(data);
@@ -130,17 +258,7 @@ export function useCostMonitorPeriod({
         if (!controller.signal.aborted) setPeriodLoading(false);
       });
     return () => controller.abort();
-  }, [
-    currency,
-    data,
-    filters,
-    lastUpdatedAt,
-    loadPeriod,
-    requestedRange?.from,
-    requestedRange?.to,
-    shouldFetch,
-    requestedRange,
-  ]);
+  }, [currency, data, filters, lastUpdatedAt, requestedFrom, requestedTo, shouldFetch]);
   return {
     activeData: activeCostPeriodData(data, periodData, periodDataBase),
     periodError,

package/templates/.agents/dashboard/modules/cost-monitor/src/react/CostModelsAuditTable.test.ts

@@ -46,6 +46,8 @@ describe("CostModelsAuditTable coverage", () => {
     expect(tables).not.toContain("Partial ·");
     expect(tables).not.toContain("durationCoverageDetail");
     expect(models).not.toContain("durationCoverageDetail");
+    expect(models).not.toContain("tempo observado");
+    expect(models).not.toContain("observed time");
     expect(models).toContain("aggregateDurationCoverage");
   });
 });

package/templates/.agents/dashboard/modules/cost-monitor/src/react/CostModelsAuditTable.tsx

@@ -4,8 +4,10 @@ import {
   contextUpliftUsd,
   formatAuditableNumber,
   formatDurationCoverage,
+  formatTokenBackedDuration,
   formatUsd,
   hasCollectedUsage,
+  hasKnownDuration,
   isDisplayableModel,
   localizedDescription,
   scenario,
@@ -45,6 +47,7 @@ export function CostModelsAuditTable({
       const estimatedUsd = sum("estimated_usd");
       const estimatedBrl = sum("estimated_brl");
       const contextUplift = sumNumbers(items.map(contextUpliftUsd));
+      const total = sum("total_tokens");
       const duration = aggregateDurationCoverage(
         items.filter((row) => durationRows.has(row)),
         "all_invocations",
@@ -53,12 +56,12 @@ export function CostModelsAuditTable({
         model,
         runs: items.length,
         duration,
-        durationMs: duration.complete ? duration.known_sum : null,
+        durationMs: hasKnownDuration(duration) ? duration.known_sum : null,
         input,
         cached,
         output,
         reasoning: sum("reasoning_tokens"),
-        total: sum("total_tokens"),
+        total,
         inputUsd,
         cacheUsd,
         outputUsd,
@@ -82,8 +85,8 @@ export function CostModelsAuditTable({
           footer: locale === "pt-BR" ? "Total" : "Total",
           description: localizedDescription(
             locale,
-            "Modelo efetivamente identificado nas invocações de agentes agregadas nesta linha. Invocações sem modelo identificável são agrupadas como Indefinido.",
-            "Model identified in the agent invocations aggregated in this row. Invocations without an identifiable model are grouped as Undefined.",
+            "Modelo efetivamente identificado nas invocações de agentes agregadas nesta linha. Invocações sem modelo identificável são agrupadas como Indisponível.",
+            "Model identified in the agent invocations aggregated in this row. Invocations without an identifiable model are grouped as Unavailable.",
           ),
         },
         {
@@ -108,13 +111,13 @@ export function CostModelsAuditTable({
         },
         {
           key: "durationMs",
-          label: locale === "pt-BR" ? "Tempo de processamento" : "Processing time",
-          render: (row) => formatDurationCoverage(row.duration, locale),
-          sortValue: (row) => (row.duration.coverage_ratio > 0 ? row.duration.known_sum : null),
+          label: locale === "pt-BR" ? "Tempo" : "Time",
+          render: (row) => formatTokenBackedDuration(row.duration, row.total, locale),
+          sortValue: (row) => row.durationMs,
           description: localizedDescription(
             locale,
-            "Soma do tempo observado de todas as Invocações de Agente financeiras elegíveis deste modelo. Cada ID de invocação entra uma vez; dados ausentes permanecem parciais e não são estimados.",
-            "Sum of observed time for all eligible financial Agent Invocations of this model. Each invocation ID is included once; missing data remains partial and is not estimated.",
+            "Soma do tempo de todas as Invocações de Agente financeiras elegíveis deste modelo. Cada ID de invocação entra uma vez; dados ausentes permanecem indisponíveis.",
+            "Sum of time for all eligible financial Agent Invocations of this model. Each invocation ID is included once; missing data remains unavailable.",
           ),
           align: "right",
           footer: formatDurationCoverage(
@@ -288,7 +291,7 @@ export function displayModelName(model: string, locale: CostLocale): string | nu
   if (isDisplayableModel(model)) return model;
   const normalized = model.trim().toLowerCase();
   if (normalized.length === 0 || normalized === "unknown") {
-    return locale === "pt-BR" ? "Indefinido" : "Undefined";
+    return locale === "pt-BR" ? "Indisponível" : "Unavailable";
   }
   return null;
 }