@zaip-ai/cli 1.3.7 → 1.4.1

package/templates/.agents/dashboard/apps/frontend/src/use-app-effects.ts

@@ -17,6 +17,68 @@ import {
 } from "./operations-detail-hydration.js";
 
 export const projectionRefreshDebounceMs = 5_000;
+export const snapshotReadyPollMs = 2_000;
+export const snapshotReadyPollAttempts = 90;
+export const snapshotRevisionVisiblePollMs = 5_000;
+export const snapshotRevisionHiddenPollMs = 10_000;
+export const snapshotRevisionHiddenFailurePollMs = 30_000;
+export const snapshotReadyPollExhaustedMessage =
+  "A atualização do snapshot não foi concluída. Os dados exibidos podem estar desatualizados.";
+
+export function shouldPollSnapshotReady(snapshotUpdating: boolean, attempts: number): boolean {
+  return snapshotUpdating && attempts < snapshotReadyPollAttempts;
+}
+
+export function snapshotRevisionPollDelay(
+  visibilityState: DocumentVisibilityState,
+  consecutiveFailures: number,
+): number {
+  if (visibilityState === "visible") return snapshotRevisionVisiblePollMs;
+  return consecutiveFailures > 0
+    ? snapshotRevisionHiddenFailurePollMs
+    : snapshotRevisionHiddenPollMs;
+}
+
+export function shouldRefreshForSnapshotRevision(
+  previousRevision: string | null,
+  nextRevision: string | undefined,
+): boolean {
+  return (
+    previousRevision !== null &&
+    typeof nextRevision === "string" &&
+    nextRevision.length > 0 &&
+    previousRevision !== nextRevision
+  );
+}
+
+export function isCommittedSnapshotRevision(
+  snapshotState: "current" | "updating" | undefined,
+  snapshotRevision: string | undefined,
+): snapshotRevision is string {
+  return (
+    (snapshotState === "current" || snapshotState === "updating") &&
+    typeof snapshotRevision === "string" &&
+    snapshotRevision.length > 0
+  );
+}
+
+export function settleSnapshotRevisionRefresh({
+  observedRevision,
+  pendingRevision,
+  requestedRevision,
+  succeeded,
+}: {
+  observedRevision: string | null;
+  pendingRevision: string | null;
+  requestedRevision: string;
+  succeeded: boolean;
+}): { observedRevision: string | null; pendingRevision: string | null } {
+  if (!succeeded) return { observedRevision, pendingRevision };
+  return {
+    observedRevision: requestedRevision,
+    pendingRevision: pendingRevision === requestedRevision ? null : pendingRevision,
+  };
+}
 
 export function shouldRefreshVisibleProjection({
   inFlight,
@@ -48,6 +110,8 @@ export function useAppEffects({
   pricing,
   refresh,
   refreshVersion,
+  snapshotUpdating,
+  setSnapshotUpdating,
   setError,
   setFxRate,
   setPathname,
@@ -68,8 +132,11 @@ export function useAppEffects({
     visible?: boolean,
     reconcileOpenWork?: boolean,
     refreshProjection?: boolean,
-  ) => Promise<void>;
+    reloadCostSummary?: boolean,
+  ) => Promise<boolean>;
   refreshVersion: MutableRefObject<number>;
+  snapshotUpdating: boolean;
+  setSnapshotUpdating: Dispatch<SetStateAction<boolean>>;
   setError: Dispatch<SetStateAction<string | null>>;
   setFxRate: Dispatch<SetStateAction<Awaited<ReturnType<DashboardApiClient["fxRate"]>> | null>>;
   setPathname: Dispatch<SetStateAction<string>>;
@@ -77,6 +144,9 @@ export function useAppEffects({
 }) {
   const projectionRefreshInFlight = useRef(false);
   const lastProjectionRefreshAt = useRef(0);
+  const observedSnapshotRevision = useRef<string | null>(null);
+  const snapshotRevisionRefreshInFlight = useRef(false);
+  const pendingSnapshotRevisionRefresh = useRef<string | null>(null);
   useEffect(() => {
     void refresh();
     return () => {
@@ -124,6 +194,115 @@ export function useAppEffects({
     };
   }, [refresh]);
 
+  useEffect(() => {
+    if (!snapshotUpdating) return;
+    let cancelled = false;
+    let attempts = 0;
+    let timeout: number | null = null;
+    const pollReady = async () => {
+      if (cancelled || !shouldPollSnapshotReady(true, attempts)) return;
+      attempts += 1;
+      try {
+        const ready = await api.ready();
+        if (cancelled) return;
+        if (ready.snapshot_state === "current") {
+          setSnapshotUpdating(false);
+          // Promotion produced a new immutable SQLite generation. Reload its
+          // Operations and Cost Monitor summaries by GET; never rebuild or
+          // reconcile as part of the readiness poll.
+          await refresh(false, false, false, true);
+          return;
+        }
+      } catch {
+        // Keep the validated stale seed visible within the bounded poll window.
+      }
+      if (cancelled) return;
+      if (shouldPollSnapshotReady(true, attempts)) {
+        timeout = window.setTimeout(() => void pollReady(), snapshotReadyPollMs);
+        return;
+      }
+      // Stop the progress indicator after the bounded window, while retaining
+      // an explicit visible warning that the stale snapshot remains on screen.
+      setSnapshotUpdating(false);
+      setError(snapshotReadyPollExhaustedMessage);
+    };
+    void pollReady();
+    return () => {
+      cancelled = true;
+      if (timeout !== null) window.clearTimeout(timeout);
+    };
+  }, [api, refresh, setError, setSnapshotUpdating, snapshotUpdating]);
+
+  useEffect(() => {
+    let cancelled = false;
+    let consecutiveFailures = 0;
+    let timeout: number | null = null;
+
+    const refreshChangedRevision = () => {
+      if (cancelled || snapshotRevisionRefreshInFlight.current) return;
+      const requestedRevision = pendingSnapshotRevisionRefresh.current;
+      if (requestedRevision === null) return;
+      snapshotRevisionRefreshInFlight.current = true;
+      // A committed revision is discovered by GET /ready. Its data reload
+      // remains GET-only: it must never start a projection rebuild or
+      // lifecycle reconciliation from a tab that happened to stay open.
+      void refresh(false, false, false, true)
+        .then((succeeded) => {
+          const settled = settleSnapshotRevisionRefresh({
+            observedRevision: observedSnapshotRevision.current,
+            pendingRevision: pendingSnapshotRevisionRefresh.current,
+            requestedRevision,
+            succeeded,
+          });
+          // A failed GET leaves the exact revision pending. The following
+          // passive readiness poll retries it without changing the UI state.
+          observedSnapshotRevision.current = settled.observedRevision;
+          pendingSnapshotRevisionRefresh.current = settled.pendingRevision;
+        })
+        .finally(() => {
+          snapshotRevisionRefreshInFlight.current = false;
+          // A newer committed revision that arrived while this GET was in
+          // flight can run immediately; retrying the same rejected revision
+          // waits for the normal passive polling cadence.
+          if (pendingSnapshotRevisionRefresh.current !== requestedRevision) {
+            refreshChangedRevision();
+          }
+        });
+    };
+
+    const pollRevision = async () => {
+      try {
+        const ready = await api.ready();
+        if (cancelled) return;
+        consecutiveFailures = 0;
+        const previousRevision = observedSnapshotRevision.current;
+        if (isCommittedSnapshotRevision(ready.snapshot_state, ready.snapshot_revision)) {
+          if (previousRevision === null) {
+            observedSnapshotRevision.current = ready.snapshot_revision;
+          }
+          if (shouldRefreshForSnapshotRevision(previousRevision, ready.snapshot_revision)) {
+            pendingSnapshotRevisionRefresh.current = ready.snapshot_revision;
+            refreshChangedRevision();
+          }
+        }
+      } catch {
+        consecutiveFailures += 1;
+      }
+      if (!cancelled) {
+        timeout = window.setTimeout(
+          () => void pollRevision(),
+          snapshotRevisionPollDelay(document.visibilityState, consecutiveFailures),
+        );
+      }
+    };
+
+    void pollRevision();
+    return () => {
+      cancelled = true;
+      if (timeout !== null) window.clearTimeout(timeout);
+    };
+  }, [api, refresh]);
+
   useEffect(() => {
     if (
       !shouldHydrateOperationsDetails(

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

@@ -135,6 +135,8 @@ export interface CostGroupRow {
   run_count: number;
   /** Null when a paged source does not provide a factual task attribution. */
   task_count: number | null;
+  /** Distinct factual conversation memberships for the displayed model. */
+  conversation_count?: number | null;
   /** Canonical export fields; task_count remains the active-task alias. */
   tasksCreated?: number;
   tasksActive?: number | null;
@@ -143,10 +145,11 @@ export interface CostGroupRow {
   /** Stable ZAIP identity details for the Agent aggregation only. */
   persona?: string | null;
   job?: string | null;
-  prd_count: number;
-  spec_count: number;
-  evidence_count: number;
-  test_count: number;
+  /** Creation-run attribution is unavailable when canonical linkage is absent. */
+  prd_count: number | null;
+  spec_count: number | null;
+  evidence_count: number | null;
+  test_count: number | null;
   event_count: number;
   total_tokens: number | null;
   estimated_usd: number | null;

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

@@ -290,16 +290,22 @@ export function CostMonitorContent({
               locale={locale}
               loading={groupPageLoading}
               rows={groups[key]}
-              {...(key === "models" || key === "providers"
-                ? { totals: summaryTotals }
-                : groupPage?.totals === undefined
+              {...(key === "models"
+                ? groupPage?.totals === undefined
                   ? {}
-                  : { totals: groupPage.totals })}
+                  : { totals: groupPage.totals }
+                : key === "providers"
+                  ? { totals: summaryTotals }
+                  : groupPage?.totals === undefined
+                    ? {}
+                    : { totals: groupPage.totals })}
               {...(key === "agents"
                 ? { showDateTime: false, showAgentIdentity: true }
-                : key === "models" || key === "providers"
-                  ? { showDateTime: false, showInvocationTasks: true }
-                  : {})}
+                : key === "models"
+                  ? { showDateTime: false, showModelLifecycleDetails: true }
+                  : key === "providers"
+                    ? { showDateTime: false, showInvocationTasks: true }
+                    : {})}
             />
             {groupPager}
           </>

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

@@ -204,6 +204,17 @@ export function CostMonitorPage({
   const [detailLoading, setDetailLoading] = useState(false);
   const [detailError, setDetailError] = useState<string | null>(null);
   const [detailAttempt, setDetailAttempt] = useState(0);
+  // The summary object is replaced only when the host receives a newer
+  // snapshot. Keep this revision separate from tabs and filters so the active
+  // remote table is reloaded without remounting the Cost Monitor surface.
+  const dataRevisionRef = useRef({ data, revision: 0 });
+  if (dataRevisionRef.current.data !== data) {
+    dataRevisionRef.current = {
+      data,
+      revision: dataRevisionRef.current.revision + 1,
+    };
+  }
+  const dataRevision = dataRevisionRef.current.revision;
   const loadDetailRef = useRef(loadDetail);
   loadDetailRef.current = loadDetail;
   const text = costCopy[locale];
@@ -267,6 +278,7 @@ export function CostMonitorPage({
     globalQuery: globalFilters?.query ?? "",
     filters,
     limit: groupPageLimit,
+    revision: dataRevision,
     ...(groupView === null ? {} : { load: loadGroupPage }),
   });
   const displayedGroupPage = groupPageState.page ?? groupPageState.stalePage;
@@ -285,6 +297,7 @@ export function CostMonitorPage({
     range: compactPageRange,
     query: globalFilters?.query,
     filters,
+    revision: dataRevision,
   });
   // Server pagination is safe only when every active Run filter is part of the
   // endpoint contract. Unsupported local text/metadata filters retain the
@@ -309,6 +322,7 @@ export function CostMonitorPage({
     // must not silently add a date range and bypass the fast all-time page.
     range: groupPageRange,
     refresh: lastUpdatedAt,
+    revision: dataRevision,
     load: loadRunPage,
   });
   useEffect(

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

@@ -0,0 +1,211 @@
+import { formatCompactNumber, formatCurrency, formatDurationMs } from "@zaip-ai/dashboard-ui";
+import type { CostRunRow, DurationCoverage } from "../contracts.js";
+import type { CostCurrency, CostLocale } from "./cost-monitor-copy.js";
+import {
+  formatBrlRate,
+  formatMultiplierPair,
+  formatRate,
+  formatUsd,
+} from "./cost-table-presentation.js";
+
+export function displayCostGroupLabel(label: string, locale: CostLocale): string {
+  const normalized = label.trim().toLowerCase();
+  return normalized.length === 0 || normalized === "unknown"
+    ? locale === "pt-BR"
+      ? "Sem modelo/provedor atribuído"
+      : "No model/provider assigned"
+    : label;
+}
+
+export function formatAuditableNumber(value: number | null, locale: CostLocale): string {
+  return new Intl.NumberFormat(locale, { maximumFractionDigits: 0 }).format(value ?? 0);
+}
+
+export function formatFactualCount(value: number | null, locale: CostLocale): string {
+  return value === null
+    ? locale === "pt-BR"
+      ? "Indisponível"
+      : "Unavailable"
+    : formatAuditableNumber(value, locale);
+}
+
+export function formatAuditableCompactNumber(value: number | null, locale: CostLocale): string {
+  return formatCompactNumber(value ?? 0, locale);
+}
+
+export function formatAuditableCurrency(
+  value: number | null,
+  currency: CostCurrency,
+  locale: CostLocale,
+): string {
+  if (value === null) return locale === "pt-BR" ? "Indisponível" : "Unavailable";
+  return formatCurrency(value, currency, locale);
+}
+
+export function formatAuditableDuration(value: number | null, locale: CostLocale): string {
+  if (value === null) return locale === "pt-BR" ? "Indisponível" : "Unavailable";
+  return value === 0 ? "0" : formatDurationMs(value, locale);
+}
+
+export const formatInvocationNumber = (value: number | null, locale: CostLocale) =>
+  formatAuditableNumber(value, locale);
+export const formatInvocationCurrency = (
+  value: number | null,
+  currency: CostCurrency,
+  locale: CostLocale,
+) => formatAuditableCurrency(value, currency, locale);
+export const formatInvocationDuration = (value: number | null, locale: CostLocale) =>
+  formatAuditableDuration(value, locale);
+export const formatInvocationRate = (value: number | null, locale: CostLocale) =>
+  formatRate(value, locale);
+export const formatInvocationUsd = (value: number | null, locale: CostLocale) =>
+  formatUsd(value, locale);
+export const formatInvocationBrlRate = (value: number | null, locale: CostLocale) =>
+  formatBrlRate(value, locale);
+export const formatInvocationMultiplierPair = (
+  input: number | null,
+  output: number | null,
+  locale: CostLocale,
+) => formatMultiplierPair(input, output, locale);
+
+export function invocationMetricDescription(locale: CostLocale, metric: string): string {
+  const source =
+    locale === "pt-BR"
+      ? "Valor da projeção SQLite/API desta Invocação de Agente. Fato canônico nulo permanece indisponível e não é convertido em zero."
+      : "Value from this Agent Invocation's SQLite/API projection. A null canonical fact remains unavailable and is not converted to zero.";
+  const details: Record<string, readonly [string, string]> = {
+    duration: [
+      "Tempo factual da invocação, quando capturado ou reconciliado.",
+      "Factual invocation duration, when captured or reconciled.",
+    ],
+    inputTokens: [
+      "Input total informado pela fonte; inclui a parcela de cache.",
+      "Source-reported total input; includes the cached portion.",
+    ],
+    cachedInputTokens: [
+      "Parcela de cache já incluída no input total.",
+      "Cached portion already included in total input.",
+    ],
+    outputTokens: [
+      "Output total informado pela fonte; inclui a parcela de raciocínio.",
+      "Source-reported total output; includes the reasoning portion.",
+    ],
+    reasoningTokens: [
+      "Parcela de raciocínio já incluída no output total.",
+      "Reasoning portion already included in total output.",
+    ],
+    totalTokens: [
+      "Soma de entrada e saída quando ambas são conhecidas; caso contrário, total informado pela fonte.",
+      "Input plus output when both are known; otherwise the source-reported total.",
+    ],
+    inputRate: [
+      "Tarifa efetiva de entrada em USD por milhão de tokens.",
+      "Effective input rate in USD per million tokens.",
+    ],
+    cacheRate: [
+      "Tarifa efetiva de entrada em cache em USD por milhão de tokens.",
+      "Effective cached-input rate in USD per million tokens.",
+    ],
+    outputRate: [
+      "Tarifa efetiva de saída em USD por milhão de tokens.",
+      "Effective output rate in USD per million tokens.",
+    ],
+    reasoningRate: [
+      "Tarifa efetiva de raciocínio em USD por milhão de tokens.",
+      "Effective reasoning rate in USD per million tokens.",
+    ],
+    contextMultiplier: [
+      "Multiplicadores de contexto de entrada/saída aplicados aos segmentos internos.",
+      "Input/output context multipliers applied to internal segments.",
+    ],
+    inputCost: [
+      "Custo USD de entrada calculado com tokens e tarifa efetiva.",
+      "Input USD cost calculated from tokens and the effective rate.",
+    ],
+    cacheCost: [
+      "Custo USD da entrada em cache calculado com tokens e tarifa efetiva.",
+      "Cached-input USD cost calculated with tokens and the effective rate.",
+    ],
+    outputCost: [
+      "Custo USD de saída calculado com tokens e tarifa efetiva.",
+      "Output USD cost calculated with tokens and the effective rate.",
+    ],
+    reasoningCost: [
+      "Custo USD de raciocínio calculado com tokens e tarifa efetiva.",
+      "Reasoning USD cost calculated with tokens and the effective rate.",
+    ],
+    standardCost: [
+      "Custo USD no cenário Standard, antes do acréscimo de velocidade.",
+      "USD cost in the Standard scenario, before the speed uplift.",
+    ],
+    speedUplift: [
+      "Acréscimo USD do cenário Priority/Fast, já incluído no custo efetivo.",
+      "USD uplift from the Priority/Fast scenario, already included in the effective cost.",
+    ],
+    finalUsd: [
+      "Custo final estimado da API em USD, somando os componentes de custo desta invocação.",
+      "Estimated final API cost in USD, summing this invocation's cost components.",
+    ],
+    fxRate: [
+      "Câmbio BRL/USD atual aplicado para converter o custo final atual.",
+      "Current BRL/USD exchange rate used to convert the current final cost.",
+    ],
+    recordedFxRate: [
+      "Câmbio BRL/USD registrado no período da atividade.",
+      "BRL/USD exchange rate recorded for the activity period.",
+    ],
+    recordedBrl: [
+      "Custo final BRL registrado no período, preservado para auditoria histórica.",
+      "Final BRL cost recorded in the period, retained for historical audit.",
+    ],
+    cost: [
+      "Custo final atual: USD estimado ou sua conversão BRL pelo câmbio atual selecionado.",
+      "Current final cost: estimated USD or its BRL conversion at the selected current exchange rate.",
+    ],
+  };
+  const detail = details[metric] ?? [
+    "Métrica numérica desta invocação.",
+    "Numeric metric for this invocation.",
+  ];
+  return `${detail[locale === "pt-BR" ? 0 : 1]} ${source}`;
+}
+
+export function formatDurationCoverage(value: DurationCoverage, locale: CostLocale): string {
+  if (value.known_sum <= 0 && !value.complete)
+    return locale === "pt-BR" ? "Indisponível" : "Unavailable";
+  return value.known_sum <= 0 ? "0" : formatDurationMs(value.known_sum, locale);
+}
+
+export function hasKnownDuration(value: DurationCoverage): boolean {
+  return value.known_sum > 0 || value.coverage_ratio > 0;
+}
+
+export function formatTokenBackedDuration(
+  value: DurationCoverage,
+  _totalTokens: number | null,
+  locale: CostLocale,
+): string {
+  return formatDurationCoverage(value, locale);
+}
+
+export function costRunsFooterLabel(locale: CostLocale, pageOnly: boolean): string {
+  if (!pageOnly) return "Total";
+  return locale === "pt-BR" ? "Subtotal da página" : "Page subtotal";
+}
+
+export function sortCostValue(
+  currency: CostCurrency,
+  brl: number | null,
+  usd: number | null,
+): number | null {
+  return currency === "BRL" ? brl : usd;
+}
+
+export function runOriginBadge(row: Pick<CostRunRow, "prd_id" | "spec_id" | "task_id">): {
+  label: "PRD" | "SPEC" | "Tarefa avulsa";
+  tone: "prd" | "spec" | "task";
+} {
+  if (row.prd_id !== null) return { label: "PRD", tone: "prd" };
+  if (row.spec_id !== null) return { label: "SPEC", tone: "spec" };
+  return { label: "Tarefa avulsa", tone: "task" };
+}