@zaip-ai/cli 1.3.8 → 1.4.1

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" };
+}

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

@@ -1,6 +1,5 @@
-import { createHash } from "node:crypto";
-import { queryInvocationManifestPeriod } from "@zaip-ai/costs";
 import { describe, expect, it } from "vitest";
+import type { CostGroupRow } from "../contracts.js";
 import { displayModelName, isModelAuditRow, sumModelDurationMs } from "./CostModelsAuditTable.js";
 import {
   agentRunModelPresentation,
@@ -140,10 +139,10 @@ describe("monetary formatting", () => {
     expect(ratio(106.73, 19.583444)).toBeCloseTo(5.45, 2);
     expect(ratio(100, 0)).toBeNull();
   });
-  it("renders unavailable numeric metrics as zero", () => {
+  it("keeps unavailable cost metrics distinct from zero", () => {
     expect(formatRate(null, "pt-BR")).toBe("0,00");
     expect(formatUsd(null, "en-US")).toContain("0.00");
-    expect(formatAuditableCurrency(null, "BRL", "pt-BR")).toContain("0,00");
+    expect(formatAuditableCurrency(null, "BRL", "pt-BR")).toBe("Indisponível");
     expect(formatAuditableDuration(null, "pt-BR")).toBe("Indisponível");
     expect(formatAuditableCompactNumber(null, "pt-BR")).toBe("0");
   });
@@ -384,11 +383,11 @@ describe("grouped cost availability", () => {
     expect(table.props.scrollLabel).toBe(costGroupsScrollLabel("pt-BR"));
     expect(column("duration")?.render(unavailableGroup)).toBe("Indisponível");
     expect(column("tokens")?.render(unavailableGroup)).toBe("0");
-    expect(column("cost")?.render(unavailableGroup)).toContain("0,00");
+    expect(column("cost")?.render(unavailableGroup)).toBe("Indisponível");
     expect(column("duration")?.sortValue?.(unavailableGroup)).toBeNull();
     expect(column("tokens")?.sortValue?.(unavailableGroup)).toBeNull();
     expect(column("cost")?.sortValue?.(unavailableGroup)).toBeNull();
-    const totalSummary = "Total geral — Tempo: Indisponível; Tokens: 0; BRL: R$ 0,00";
+    const totalSummary = "Total geral — Tempo: Indisponível; Tokens: 0; BRL: Indisponível";
     const footerLabel = (key: string) => {
       const footer = column(key)?.footer as { props?: { "aria-label"?: string } } | undefined;
       return footer?.props?.["aria-label"];
@@ -462,9 +461,36 @@ describe("grouped cost availability", () => {
     expect(columns.find((column) => column.key === "job")?.render?.({ job: "Builder" })).toBe(
       "Builder",
     );
-    expect(columns.find((column) => column.key === "tasks")).toBeUndefined();
+    expect(columns.find((column) => column.key === "tasks")?.label).toBe("Tarefas");
     expect(table.props.defaultSort).toEqual({ key: "cost", direction: "desc" });
   });
+
+  it("renders missing Agent numeric metrics as zero, keeping model rendering independent", () => {
+    const missing: CostGroupRow = {
+      ...unavailableGroup,
+      task_count: null,
+      prd_count: null,
+      spec_count: null,
+      test_count: null,
+      evidence_count: null,
+    };
+    const table = CostGroupsTable({
+      rows: [missing],
+      currency: "BRL",
+      locale: "pt-BR",
+      showAgentIdentity: true,
+    });
+    const columns = table.props.columns as Array<{
+      key: string;
+      render?: (row: CostGroupRow) => unknown;
+      footer?: unknown;
+    }>;
+    for (const key of ["tasks", "prds", "specs", "tests", "evidences", "duration", "tokens"]) {
+      expect(columns.find((c) => c.key === key)?.render?.(missing)).toBe("0");
+    }
+    expect(columns.find((c) => c.key === "cost")?.render?.(missing)).not.toContain("Indisponível");
+  });
+
   it("keeps legacy codex identity fields blank and uses the complete paged aggregate in its footer", () => {
     const table = CostGroupsTable({
       rows: [
@@ -518,6 +544,123 @@ describe("grouped cost availability", () => {
     expect(columns.find((column) => column.key === "latestStartedAt")?.hidden).toBe(true);
     expect(columns.find((column) => column.key === "tasks")?.label).toBe("Tarefas com invocação");
   });
+  it("renders the requested model-analysis columns with explicit numeric zeroes", () => {
+    const model: CostGroupRow = {
+      ...unavailableGroup,
+      key: "gpt-6-astra",
+      label: "gpt-6-astra",
+      prd_count: 2,
+      spec_count: 3,
+      task_count: null,
+      run_count: 8,
+      test_count: null,
+      evidence_count: 1,
+      conversation_count: 0,
+    };
+    const table = CostGroupsTable({
+      rows: [model],
+      currency: "BRL",
+      locale: "pt-BR",
+      showDateTime: false,
+      showModelLifecycleDetails: true,
+      totals: {
+        ...model,
+        prd_count: 2,
+        spec_count: 3,
+        task_count: null,
+        test_count: null,
+        evidence_count: 1,
+      },
+    });
+    const columns = table.props.columns as Array<{
+      key: string;
+      label: string;
+      render?: (row: typeof model) => unknown;
+      sortValue?: (row: typeof model) => unknown;
+      description?: string;
+    }>;
+    expect(columns.map((column) => column.key).filter((key) => key !== "latestStartedAt")).toEqual([
+      "label",
+      "prds",
+      "specs",
+      "tasks",
+      "conversations",
+      "runs",
+      "tests",
+      "evidences",
+      "duration",
+      "tokens",
+      "cost",
+    ]);
+    expect(columns.find((column) => column.key === "tasks")?.label).toBe("Tasks");
+    expect(columns.find((column) => column.key === "tasks")?.render?.(model)).toBe("0");
+    expect(columns.find((column) => column.key === "conversations")?.render?.(model)).toBe("0");
+    expect(columns.find((column) => column.key === "conversations")?.description).toContain(
+      "unassisted",
+    );
+    expect(columns.find((column) => column.key === "tasks")?.description).toContain(
+      "creation_run_id",
+    );
+    expect(columns.find((column) => column.key === "runs")?.description).toContain(
+      "sem distribuir",
+    );
+    for (const key of ["prds", "specs", "tasks", "conversations", "runs", "tests", "evidences"])
+      expect(columns.find((column) => column.key === key)?.sortValue).toBeDefined();
+    expect(columns.find((column) => column.key === "cost")?.label).toBe("Custos");
+    expect(
+      columns.find((column) => column.key === "tokens")?.render?.({ ...model, total_tokens: null }),
+    ).toBe("0");
+    expect(
+      columns.find((column) => column.key === "prds")?.render?.({ ...model, prd_count: null }),
+    ).toBe("0");
+    expect(
+      columns.find((column) => column.key === "specs")?.render?.({ ...model, spec_count: null }),
+    ).toBe("0");
+    expect(
+      columns.find((column) => column.key === "tests")?.render?.({ ...model, test_count: null }),
+    ).toBe("0");
+    expect(
+      columns
+        .find((column) => column.key === "evidences")
+        ?.render?.({ ...model, evidence_count: null }),
+    ).toBe("0");
+    expect(columns.find((column) => column.key === "conversations")?.sortValue?.(model)).toBe(0);
+    expect(columns.find((column) => column.key === "tests")?.description).toContain(
+      "Run registradora",
+    );
+    expect(columns.find((column) => column.key === "evidences")?.description).toContain(
+      "Run registradora",
+    );
+    expect(
+      columns
+        .find((column) => column.key === "duration")
+        ?.render?.({
+          ...model,
+          duration: { known_sum: 0, unknown: 1, complete: false, coverage_ratio: 0 },
+        }),
+    ).toBe("0");
+    expect(
+      columns.find((column) => column.key === "cost")?.render?.({ ...model, estimated_brl: null }),
+    ).toContain("0,00");
+    expect(
+      columns
+        .find((column) => column.key === "tokens")
+        ?.sortValue?.({ ...model, total_tokens: null }),
+    ).toBe(0);
+    expect(
+      columns
+        .find((column) => column.key === "duration")
+        ?.sortValue?.({
+          ...model,
+          duration: { known_sum: 0, unknown: 1, complete: false, coverage_ratio: 0 },
+        }),
+    ).toBe(0);
+    expect(
+      columns
+        .find((column) => column.key === "cost")
+        ?.sortValue?.({ ...model, estimated_brl: null }),
+    ).toBe(0);
+  });
   it("keeps a complete observed zero visible without a partial coverage label", () => {
     const observedZeroGroup = {
       ...unavailableGroup,
@@ -649,8 +792,8 @@ describe("grouped cost availability", () => {
     expect(column("contextMultiplier")?.render?.(unavailableRun)).toBe("Indisponível");
     expect(column("inputCost")?.render?.(unavailableRun)).toContain("0,00");
     expect(column("fxRate")?.render?.(unavailableRun)).toBe("R$ 0,00");
-    expect(column("recordedBrl")?.render?.(unavailableRun)).toContain("0,00");
-    expect(column("cost")?.render?.(unavailableRun)).toContain("0,00");
+    expect(column("recordedBrl")?.render?.(unavailableRun)).toBe("Indisponível");
+    expect(column("cost")?.render?.(unavailableRun)).toBe("Indisponível");
   });
   it("provides a clear scroll label for the detailed Runs table", () => {
     expect(costRunsScrollLabel("pt-BR")).toBe(
@@ -727,154 +870,6 @@ describe("grouped cost availability", () => {
     expect(pager.props.pagination.onRetry).toEqual(expect.any(Function));
   });
 });
-describe("manifest-first invocation query", () => {
-  it("opens only intersecting monthly manifests and candidate chunks", async () => {
-    const inRange = signedSummary({
-      agent_invocation_id: "RUN-JULY-OPENAI",
-      occurred_at: "2026-07-10T12:00:00.000Z",
-      provider: "openai",
-    });
-    const outOfRange = signedSummary({
-      agent_invocation_id: "RUN-JULY-ANTHROPIC",
-      occurred_at: "2026-07-20T12:00:00.000Z",
-      provider: "anthropic",
-    });
-    const firstChunk = `${JSON.stringify(inRange)}\n`;
-    const secondChunk = `${JSON.stringify(outOfRange)}\n`;
-    const manifest = signedManifest({
-      period: { year: 2026, month: 7 },
-      from: "2026-07-10T12:00:00.000Z",
-      to: "2026-07-20T12:00:00.000Z",
-      chunks: [
-        {
-          path: ".agents/records/telemetry/2026/07/chunk-openai.jsonl",
-          content_sha256: digest(firstChunk),
-          summary_count: 1,
-          from: inRange.occurred_at,
-          to: inRange.occurred_at,
-          summary_hashes: [inRange.summary_hash],
-          dimensions: dimensions({ providers: ["openai"] }),
-        },
-        {
-          path: ".agents/records/telemetry/2026/07/chunk-anthropic.jsonl",
-          content_sha256: digest(secondChunk),
-          summary_count: 1,
-          from: outOfRange.occurred_at,
-          to: outOfRange.occurred_at,
-          summary_hashes: [outOfRange.summary_hash],
-          dimensions: dimensions({ providers: ["anthropic"] }),
-        },
-      ],
-    });
-    const reads: string[] = [];
-    const openaiChunkPath = manifest.chunks[0]?.path;
-    const anthropicChunkPath = manifest.chunks[1]?.path;
-    if (openaiChunkPath === undefined || anthropicChunkPath === undefined) {
-      throw new Error("Expected two manifest chunks");
-    }
-    const files = new Map<string, string>([
-      [".agents/records/telemetry/2026/07/manifest.json", JSON.stringify(manifest)],
-      [openaiChunkPath, firstChunk],
-      [anthropicChunkPath, secondChunk],
-    ]);
-    const result = await queryInvocationManifestPeriod(
-      {
-        exists: async (path) => files.has(path),
-        readText: async (path) => {
-          reads.push(path);
-          const value = files.get(path);
-          if (value === undefined) throw new Error(`Missing fixture: ${path}`);
-          return value;
-        },
-      },
-      {
-        from: "2026-07-09",
-        to: "2026-07-11",
-        filters: { providers: ["openai"] },
-      },
-    );
-    expect(result.summaries.map((summary) => summary.agent_invocation_id)).toEqual([
-      "RUN-JULY-OPENAI",
-    ]);
-    expect(result.manifest_count).toBe(1);
-    expect(result.chunk_count).toBe(1);
-    expect(result.source_latest_at).toBe("2026-07-20T12:00:00.000Z");
-    expect(result.lag_ms).toBe(10);
-    expect(reads).toEqual([
-      ".agents/records/telemetry/2026/07/manifest.json",
-      ".agents/records/telemetry/2026/07/chunk-openai.jsonl",
-    ]);
-  });
-});
-function digest(value: string): string {
-  return createHash("sha256").update(value).digest("hex");
-}
-function dimensions(overrides: Partial<Record<string, readonly string[]>> = {}) {
-  return {
-    providers: [],
-    models: [],
-    zaip_agents: [],
-    phases: [],
-    purposes: [],
-    statuses: [],
-    executions: [],
-    tasks: [],
-    specs: [],
-    prds: [],
-    changes: [],
-    ...overrides,
-  };
-}
-function signedSummary(input: {
-  agent_invocation_id: string;
-  occurred_at: string;
-  provider: string;
-}) {
-  const unsigned = {
-    schema_version: 1,
-    agent_invocation_id: input.agent_invocation_id,
-    occurred_at: input.occurred_at,
-    coverage: "complete",
-    usage_segments: [{ provider: input.provider, model: "gpt-5.6-terra" }],
-  };
-  return { ...unsigned, summary_hash: digest(JSON.stringify(unsigned)) };
-}
-function signedManifest(input: {
-  period: { year: number; month: number };
-  from: string;
-  to: string;
-  chunks: Array<{
-    path: string;
-    content_sha256: string;
-    summary_count: number;
-    from: string;
-    to: string;
-    summary_hashes: string[];
-    dimensions: ReturnType<typeof dimensions>;
-  }>;
-}) {
-  const unsigned = {
-    schema_version: 1,
-    period: input.period,
-    summary_count: input.chunks.reduce((sum, chunk) => sum + chunk.summary_count, 0),
-    chunk_count: input.chunks.length,
-    from: input.from,
-    to: input.to,
-    source_latest_at: input.to,
-    lag_ms: 10,
-    coverage: { complete: 2, partial: 0, unavailable: 0 },
-    chunks: input.chunks,
-    dimensions: dimensions(),
-    aggregates: { daily: {}, monthly: {}, annual: {} },
-    integrity: {
-      status: "verified",
-      algorithm: "sha256",
-      chunk_count: input.chunks.length,
-      summary_count: input.chunks.reduce((sum, chunk) => sum + chunk.summary_count, 0),
-    },
-  };
-  return { ...unsigned, manifest_hash: digest(JSON.stringify(unsigned)) };
-}
 describe("cost sorting", () => {
   it("orders the raw BRL values rather than their localized currency labels", () => {
     const rows = [143.72, 127.78, 21457.76, 1370.63];