@zaip-ai/cli 1.0.4 → 1.0.7

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

@@ -0,0 +1,77 @@
+import type { CostRunRow } from "../contracts.js";
+import type { CostLocale } from "./cost-monitor-copy.js";
+
+export function formatApiSpeedScenario(value: string | null, locale: CostLocale): string {
+  if (value === "fast")
+    return locale === "pt-BR" ? "Priority (derivado de Fast)" : "Priority (derived from Fast)";
+  if (value === "priority") return "Priority (API)";
+  if (value === "default") return "Standard (API)";
+  return "-";
+}
+
+export function agentRunModelPresentation(
+  row: Pick<CostRunRow, "model" | "provider" | "requested_model">,
+): {
+  primary: string;
+  detail: string;
+} {
+  return {
+    primary: row.model,
+    detail: row.provider === null || row.provider === "unknown" ? "-" : row.provider,
+  };
+}
+
+export function isDisplayableModel(model: string): boolean {
+  const normalized = model.trim().toLowerCase();
+  return normalized.length > 0 && !["unknown", "manual", "gpt-5"].includes(normalized);
+}
+
+export function hasCollectedUsage(row: CostRunRow): boolean {
+  return [
+    row.input_tokens,
+    row.cached_input_tokens,
+    row.output_tokens,
+    row.reasoning_tokens,
+    row.total_tokens,
+    row.estimated_usd,
+    row.estimated_brl,
+  ].some((value) => value !== null && value > 0);
+}
+
+export function contextUpliftUsd(row: CostRunRow): number | null {
+  const inputMultiplier = row.context_input_multiplier;
+  const outputMultiplier = row.context_output_multiplier;
+  if (inputMultiplier === null || outputMultiplier === null) return null;
+  if (inputMultiplier === 1 && outputMultiplier === 1) return 0;
+
+  const uplift = (costs: readonly (number | null)[], multiplier: number) => {
+    if (multiplier === 1) return 0;
+    if (multiplier <= 0 || costs.some((cost) => cost === null)) return null;
+    const effective = costs.reduce<number>((sum, cost) => sum + (cost ?? 0), 0);
+    return effective - effective / multiplier;
+  };
+  const inputUplift = uplift([row.input_cost_usd, row.cached_input_cost_usd], inputMultiplier);
+  const outputUplift = uplift([row.output_cost_usd, row.reasoning_cost_usd], outputMultiplier);
+  return inputUplift === null || outputUplift === null ? null : inputUplift + outputUplift;
+}
+
+export function localizedDescription(locale: CostLocale, pt: string, en: string): string {
+  return locale === "pt-BR" ? pt : en;
+}
+
+export function sumNumbers(values: readonly unknown[]): number | null {
+  const present = values.filter((value): value is number => typeof value === "number");
+  return present.length === 0 ? null : present.reduce((sum, value) => sum + value, 0);
+}
+
+export function ratio(numerator: number | null, denominator: number | null): number | null {
+  return numerator === null || denominator === null || denominator <= 0
+    ? null
+    : numerator / denominator;
+}
+
+export function scenario(rows: readonly CostRunRow[], locale: CostLocale): string {
+  const tiers = new Set(rows.map((row) => row.service_tier ?? "unknown"));
+  if (tiers.size !== 1) return locale === "pt-BR" ? "Misto" : "Mixed";
+  return formatApiSpeedScenario(rows[0]?.service_tier ?? null, locale);
+}

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

@@ -0,0 +1,2 @@
+export * from "./CostMonitorPage.js";
+export type { CostCurrency, CostLocale } from "./cost-monitor-copy.js";

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

@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import type { CostGroupRow } from "../contracts.js";
+import { enrichPeriodCostGroups, summarizeCostPeriodAverages } from "./period-cost-groups.js";
+
+const runGroups: CostGroupRow[] = [
+  {
+    key: "2026-07-16",
+    label: "2026-07-16",
+    latest_started_at: "2026-07-16T12:00:00.000Z",
+    run_count: 2,
+    task_count: 1,
+    event_count: 3,
+    total_tokens: 100,
+    estimated_usd: 1,
+    estimated_brl: 5,
+    duration_ms: 60_000,
+    duration: { known_sum: 60_000, unknown: 0, complete: true, coverage_ratio: 1 },
+    coverage: { events: 3, tokens: 2, usd: 2, brl: 2 },
+    prd_count: 0,
+    spec_count: 0,
+    evidence_count: 0,
+    test_count: 0,
+  },
+];
+
+const entities = {
+  prds: [{ created_at: "2026-07-16T09:00:00.000Z" }, { created_at: "2026-07-15T09:00:00.000Z" }],
+  specs: [{ created_at: "2026-07-16T09:00:00.000Z" }],
+  tasks: [
+    {
+      created_at: "2026-07-16T09:00:00.000Z",
+      result: { evidence_ids: ["EVD-1", "EVD-2"] },
+      test_count: 2,
+    },
+    {
+      created_at: "2026-07-16T10:00:00.000Z",
+      result: { evidence_ids: ["EVD-2", "EVD-3"] },
+      test_count: 1,
+    },
+  ],
+};
+
+describe("enrichPeriodCostGroups", () => {
+  it("adds lifecycle counts and keeps periods without runs", () => {
+    expect(
+      enrichPeriodCostGroups(runGroups, entities, "daily").map((row) => ({
+        key: row.key,
+        runs: row.run_count,
+        prds: row.prd_count,
+        specs: row.spec_count,
+        evidences: row.evidence_count,
+        tests: row.test_count,
+      })),
+    ).toEqual([
+      { key: "2026-07-16", runs: 2, prds: 1, specs: 1, evidences: 3, tests: 3 },
+      { key: "2026-07-15", runs: 0, prds: 1, specs: 0, evidences: 0, tests: 0 },
+    ]);
+  });
+
+  it("rolls the same counts up by month and year", () => {
+    const monthly = enrichPeriodCostGroups([], entities, "monthly");
+    const annual = enrichPeriodCostGroups([], entities, "annual");
+    expect(monthly[0]).toMatchObject({
+      key: "2026-07",
+      prd_count: 2,
+      spec_count: 1,
+      evidence_count: 3,
+      test_count: 3,
+    });
+    expect(annual[0]).toMatchObject({
+      key: "2026",
+      prd_count: 2,
+      spec_count: 1,
+      evidence_count: 3,
+      test_count: 3,
+    });
+  });
+
+  it("divides total duration by every day in the period", () => {
+    const rows = [
+      runGroups[0] as CostGroupRow,
+      {
+        ...(runGroups[0] as CostGroupRow),
+        key: "2026-07-15",
+        task_count: 3,
+        spec_count: 2,
+        prd_count: 1,
+        duration_ms: null,
+        total_tokens: null,
+        estimated_brl: null,
+        estimated_usd: null,
+      },
+    ];
+    expect(summarizeCostPeriodAverages(rows, "BRL")).toEqual({
+      tasks: 2,
+      specs: 1,
+      prds: 0.5,
+      durationMs: 30_000,
+      tokens: 100,
+      cost: 5,
+    });
+    expect(summarizeCostPeriodAverages([], "USD")).toEqual({
+      tasks: null,
+      specs: null,
+      prds: null,
+      durationMs: null,
+      tokens: null,
+      cost: null,
+    });
+  });
+});

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

@@ -0,0 +1,140 @@
+import { saoPauloPeriodKey } from "@zaip-ai/dashboard-operations/contracts";
+import type { CostGroupRow } from "../contracts.js";
+
+export type CostPeriodGranularity = "daily" | "monthly" | "annual";
+
+export interface CostPeriodAverages {
+  tasks: number | null;
+  specs: number | null;
+  prds: number | null;
+  durationMs: number | null;
+  tokens: number | null;
+  cost: number | null;
+}
+
+interface PeriodEntities {
+  prds: readonly { created_at: string | null }[];
+  specs: readonly { created_at: string | null }[];
+  tasks: readonly {
+    created_at: string;
+    result: { evidence_ids: string[] } | null;
+    test_count?: number;
+  }[];
+}
+
+export function enrichPeriodCostGroups(
+  runGroups: readonly CostGroupRow[],
+  entities: PeriodEntities,
+  granularity: CostPeriodGranularity,
+): CostGroupRow[] {
+  const rows = new Map<string, CostGroupRow>(
+    runGroups.map((row) => [
+      row.key,
+      {
+        ...row,
+        tasksActive: row.tasksActive ?? row.task_count,
+        taskDaysActive: row.tasksActive ?? row.task_count,
+        tasksCreated: 0,
+      },
+    ]),
+  );
+  const evidenceIds = new Map<string, Set<string>>();
+
+  const bucketFor = (value: string | null): CostGroupRow | null => {
+    const key = periodKey(value, granularity);
+    if (key === null) return null;
+    const existing = rows.get(key);
+    if (existing !== undefined) return existing;
+    const created: CostGroupRow = {
+      key,
+      label: key,
+      latest_started_at: periodTimestamp(key, granularity),
+      run_count: 0,
+      task_count: 0,
+      tasksCreated: 0,
+      tasksActive: 0,
+      taskDaysActive: 0,
+      event_count: 0,
+      total_tokens: null,
+      estimated_usd: null,
+      estimated_brl: null,
+      duration_ms: null,
+      duration: { known_sum: 0, unknown: 0, complete: true, coverage_ratio: 1 },
+      coverage: { events: 0, tokens: 0, usd: 0, brl: 0 },
+      prd_count: 0,
+      spec_count: 0,
+      evidence_count: 0,
+      test_count: 0,
+    };
+    rows.set(key, created);
+    return created;
+  };
+
+  for (const prd of entities.prds) {
+    const bucket = bucketFor(prd.created_at);
+    if (bucket !== null) bucket.prd_count += 1;
+  }
+  for (const spec of entities.specs) {
+    const bucket = bucketFor(spec.created_at);
+    if (bucket !== null) bucket.spec_count += 1;
+  }
+  for (const task of entities.tasks) {
+    const bucket = bucketFor(task.created_at);
+    if (bucket === null) continue;
+    bucket.tasksCreated = (bucket.tasksCreated ?? 0) + 1;
+    bucket.test_count += task.test_count ?? 0;
+    const ids = evidenceIds.get(bucket.key) ?? new Set<string>();
+    for (const evidenceId of task.result?.evidence_ids ?? []) ids.add(evidenceId);
+    evidenceIds.set(bucket.key, ids);
+  }
+  for (const [key, ids] of evidenceIds) {
+    const bucket = rows.get(key);
+    if (bucket !== undefined) bucket.evidence_count = ids.size;
+  }
+  return [...rows.values()].sort((left, right) => right.key.localeCompare(left.key));
+}
+
+export function summarizeCostPeriodAverages(
+  rows: readonly CostGroupRow[],
+  currency: "BRL" | "USD",
+): CostPeriodAverages {
+  const divisor = rows.length;
+  return {
+    tasks: divisor === 0 ? null : rows.reduce((sum, row) => sum + row.task_count, 0) / divisor,
+    specs: divisor === 0 ? null : rows.reduce((sum, row) => sum + row.spec_count, 0) / divisor,
+    prds: divisor === 0 ? null : rows.reduce((sum, row) => sum + row.prd_count, 0) / divisor,
+    durationMs: averagePerPeriod(
+      rows.map((row) => row.duration_ms),
+      divisor,
+    ),
+    tokens: averageObserved(rows.map((row) => row.total_tokens)),
+    cost: averageObserved(
+      rows.map((row) => (currency === "BRL" ? row.estimated_brl : row.estimated_usd)),
+    ),
+  };
+}
+
+function averageObserved(values: readonly (number | null)[]): number | null {
+  const present = values.filter((value): value is number => value !== null);
+  return present.length === 0
+    ? null
+    : present.reduce((sum, value) => sum + value, 0) / present.length;
+}
+
+function averagePerPeriod(values: readonly (number | null)[], periodCount: number): number | null {
+  if (periodCount === 0) return null;
+  return values.reduce<number>((sum, value) => sum + (value ?? 0), 0) / periodCount;
+}
+
+function periodKey(value: string | null, granularity: CostPeriodGranularity): string | null {
+  return saoPauloPeriodKey(
+    value,
+    granularity === "daily" ? "day" : granularity === "monthly" ? "month" : "year",
+  );
+}
+
+function periodTimestamp(key: string, granularity: CostPeriodGranularity): string {
+  if (granularity === "annual") return `${key}-01-01T00:00:00.000Z`;
+  if (granularity === "monthly") return `${key}-01T00:00:00.000Z`;
+  return `${key}T00:00:00.000Z`;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Fields that identify a Cost run in its displayed and grouped population.
+ * Keep runtime filtering aligned with the projection rather than raw records.
+ */
+export function displayedCostRunModel(
+  effectiveModel: string | null | undefined,
+  model: string,
+): string {
+  return effectiveModel ?? model;
+}

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

@@ -0,0 +1,213 @@
+import { describe, expect, it } from "vitest";
+import type { CostRunRow } from "../contracts.js";
+import { aggregateRows } from "./aggregate.js";
+
+describe("aggregateRows", () => {
+  it("orders every group by its most recent Run", () => {
+    const rows = [
+      run("older-expensive", "2026-07-12T10:00:00.000Z", 100),
+      run("newest", "2026-07-15T10:00:00.000Z", null),
+      run("middle", "2026-07-14T10:00:00.000Z", 10),
+    ];
+
+    expect(aggregateRows(rows, (row) => row.run_id).map((row) => row.key)).toEqual([
+      "newest",
+      "middle",
+      "older-expensive",
+    ]);
+  });
+
+  it("uses every invocation effort in grouped analytical totals", () => {
+    const rows = [
+      {
+        ...run("RUN-PLAN", "2026-07-15T10:00:00.000Z", null),
+        phase: "planning",
+        duration_ms: 6_000,
+      },
+      {
+        ...run("RUN-EXEC", "2026-07-15T11:00:00.000Z", null),
+        phase: "execution",
+        parent_run_id: null,
+        duration_ms: 2_000,
+      },
+      {
+        ...run("RUN-SUB", "2026-07-15T11:30:00.000Z", null),
+        phase: "execution",
+        parent_run_id: "RUN-EXEC",
+        duration_ms: 1_000,
+      },
+    ];
+
+    expect(aggregateRows(rows, () => "2026-07-15")[0]).toMatchObject({
+      duration_ms: 9_000,
+      duration: { known_sum: 9_000, unknown: 0, complete: true, coverage_ratio: 1 },
+    });
+  });
+
+  it("keeps invocation effort with the invocation period", () => {
+    const rows = [
+      {
+        ...run("RUN-ROOT", "2026-07-15T23:59:00.000Z", null),
+        duration_ms: 2_000,
+      },
+      {
+        ...run("RUN-CHILD", "2026-07-16T00:01:00.000Z", null),
+        parent_run_id: "RUN-ROOT",
+        duration_ms: 1_000,
+      },
+    ];
+
+    const groups = aggregateRows(rows, (row) => row.started_at.slice(0, 10));
+
+    expect(groups.find((row) => row.key === "2026-07-15")).toMatchObject({
+      duration_ms: 2_000,
+      duration: { known_sum: 2_000, unknown: 0, complete: true, coverage_ratio: 1 },
+    });
+    expect(groups.find((row) => row.key === "2026-07-16")).toMatchObject({
+      duration_ms: 1_000,
+      duration: { known_sum: 1_000, unknown: 0, complete: true, coverage_ratio: 1 },
+    });
+  });
+
+  it("keeps an observed priced child when its unpriced parent is absent", () => {
+    const rows = [
+      {
+        ...run("RUN-PRICED-CHILD", "2026-07-15T11:00:00.000Z", null),
+        parent_run_id: "RUN-UNPRICED-ORCHESTRATOR",
+        duration_ms: 2_000,
+      },
+    ];
+
+    expect(aggregateRows(rows, () => "TASK-1")[0]).toMatchObject({
+      duration_ms: 2_000,
+      duration: { known_sum: 2_000, unknown: 0, complete: true, coverage_ratio: 1 },
+    });
+  });
+
+  it("keeps unavailable duration null for a visible cost-tree root", () => {
+    const rows = [
+      {
+        ...run("RUN-PRICED-CHILD", "2026-07-15T11:00:00.000Z", null),
+        parent_run_id: "RUN-UNPRICED-ORCHESTRATOR",
+        duration_ms: null,
+      },
+    ];
+
+    expect(aggregateRows(rows, () => "TASK-1")[0]).toMatchObject({
+      duration_ms: null,
+      duration: { known_sum: 0, unknown: 1, complete: false, coverage_ratio: 0 },
+    });
+  });
+
+  it("keeps an observed zero distinct from unavailable duration", () => {
+    const rows = [
+      {
+        ...run("RUN-PRICED-CHILD", "2026-07-15T11:00:00.000Z", null),
+        parent_run_id: "RUN-UNPRICED-ORCHESTRATOR",
+        duration_ms: 0,
+      },
+    ];
+
+    expect(aggregateRows(rows, () => "TASK-1")[0]).toMatchObject({
+      duration_ms: 0,
+      duration: { known_sum: 0, unknown: 0, complete: true, coverage_ratio: 1 },
+    });
+  });
+
+  it("sums every invocation duration for provider totals", () => {
+    const rows = [
+      { ...run("RUN-ROOT", "2026-07-15T10:00:00.000Z", null), duration_ms: 2_000 },
+      {
+        ...run("RUN-SUB", "2026-07-15T10:01:00.000Z", null),
+        parent_run_id: "RUN-ROOT",
+        duration_ms: 1_000,
+      },
+    ];
+
+    expect(aggregateRows(rows, () => "openai", undefined, "all_invocations")[0]).toMatchObject({
+      duration_ms: 3_000,
+      duration: { known_sum: 3_000, unknown: 0, complete: true, coverage_ratio: 1 },
+    });
+  });
+
+  it("sums every invocation duration for conversation totals", () => {
+    const rows = [
+      {
+        ...run("RUN-CONVERSATION-1", "2026-07-15T10:00:00.000Z", null),
+        phase: "conversation",
+        duration_ms: 2_000,
+      },
+      {
+        ...run("RUN-CONVERSATION-2", "2026-07-15T10:01:00.000Z", null),
+        phase: "conversation",
+        duration_ms: 1_000,
+      },
+    ];
+
+    expect(aggregateRows(rows, () => "CONV-1", undefined, "all_invocations")[0]).toMatchObject({
+      duration_ms: 3_000,
+      duration: { known_sum: 3_000, unknown: 0, complete: true, coverage_ratio: 1 },
+    });
+  });
+
+  it("uses every distinct execution Run but excludes conversation duration for period totals", () => {
+    const rows = [
+      {
+        ...run("RUN-DAY-1", "2026-07-15T10:00:00.000Z", 1),
+        duration_ms: 2_000,
+        total_tokens: 10,
+        estimated_brl: 1,
+      },
+      {
+        ...run("RUN-DAY-2", "2026-07-15T10:01:00.000Z", 2),
+        parent_run_id: "RUN-DAY-1",
+        duration_ms: 1_000,
+        total_tokens: 20,
+        estimated_brl: 2,
+      },
+      {
+        ...run("RUN-CONVERSATION", "2026-07-15T10:02:00.000Z", 3),
+        phase: "conversation",
+        duration_ms: 9_000,
+        total_tokens: 30,
+        estimated_brl: 3,
+      },
+    ];
+
+    expect(aggregateRows(rows, () => "2026-07-15", undefined, "all_execution")[0]).toMatchObject({
+      duration_ms: 3_000,
+      duration: { known_sum: 3_000, unknown: 0, complete: true, coverage_ratio: 1 },
+      total_tokens: 60,
+      estimated_usd: 6,
+      estimated_brl: 6,
+    });
+  });
+
+  it("preserves an unmeasured root duration and exposes its coverage", () => {
+    const rows = [
+      { ...run("RUN-KNOWN", "2026-07-15T11:00:00.000Z", null), duration_ms: 2_000 },
+      { ...run("RUN-UNKNOWN", "2026-07-15T12:00:00.000Z", null), duration_ms: null },
+    ];
+
+    expect(aggregateRows(rows, () => "2026-07-15")[0]).toMatchObject({
+      duration_ms: null,
+      duration: { known_sum: 2_000, unknown: 1, complete: false, coverage_ratio: 0.5 },
+    });
+  });
+});
+
+function run(run_id: string, started_at: string, estimated_usd: number | null): CostRunRow {
+  return {
+    run_id,
+    started_at,
+    estimated_usd,
+    task_id: null,
+    phase: "execution",
+    parent_run_id: null,
+    event_count: 1,
+    total_tokens: null,
+    estimated_brl: null,
+    duration_ms: null,
+    coverage: { events: 1, tokens: 0, usd: estimated_usd === null ? 0 : 1, brl: 0 },
+  } as CostRunRow;
+}

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

@@ -0,0 +1,86 @@
+import {
+  aggregateDurationCoverage,
+  type CostCoverage,
+  type CostGroupRow,
+  type CostRunRow,
+  type DurationAggregationScope,
+  durationAggregationRows,
+  sumKnown,
+} from "../contracts.js";
+
+export function aggregateRows(
+  rows: readonly CostRunRow[],
+  select: (row: CostRunRow) => string,
+  label: (key: string) => string = (key) => key,
+  durationScope: DurationAggregationScope = "all_invocations",
+): CostGroupRow[] {
+  const keys = [...new Set(rows.map(select))];
+  const durationContributorIds = new Set(
+    durationAggregationRows(rows, durationScope).map((row) => row.run_id),
+  );
+  return keys
+    .map((key) => {
+      const group = rows.filter((row) => select(row) === key);
+      // Select roots against the complete filtered population before grouping.
+      // Otherwise a child whose parent belongs to another day/model/provider
+      // incorrectly becomes a second visible root inside its local group.
+      const duration = aggregateDurationCoverage(
+        group.filter((row) => durationContributorIds.has(row.run_id)),
+        durationScope === "all_execution" ? "all_execution" : "all_invocations",
+      );
+      return {
+        key,
+        label: label(key),
+        latest_started_at: group.reduce(
+          (latest, row) => (row.started_at > latest ? row.started_at : latest),
+          group[0]?.started_at ?? "",
+        ),
+        run_count: group.length,
+        task_count: new Set(group.flatMap((row) => (row.task_id === null ? [] : [row.task_id])))
+          .size,
+        tasksActive: new Set(group.flatMap((row) => (row.task_id === null ? [] : [row.task_id])))
+          .size,
+        taskDaysActive: new Set(group.flatMap((row) => (row.task_id === null ? [] : [row.task_id])))
+          .size,
+        prd_count: 0,
+        spec_count: 0,
+        evidence_count: 0,
+        test_count: 0,
+        event_count: group.reduce((total, row) => total + row.event_count, 0),
+        total_tokens: completeSum(group.map((row) => row.total_tokens)),
+        estimated_usd: completeSum(group.map((row) => row.estimated_usd)),
+        estimated_brl: completeSum(group.map((row) => row.estimated_brl)),
+        duration_ms: duration.complete ? duration.known_sum : null,
+        duration,
+        coverage: mergeCoverage(group),
+      };
+    })
+    .sort(compareRows);
+}
+
+export function completeSum(values: readonly (number | null)[]): number | null {
+  return sumKnown(values);
+}
+
+export function averageAvailable(values: readonly (number | null)[]): number | null {
+  const available = values.filter((value): value is number => value !== null);
+  return available.length === 0
+    ? null
+    : available.reduce((total, value) => total + value, 0) / available.length;
+}
+
+function mergeCoverage(rows: readonly CostRunRow[]): CostCoverage {
+  return rows.reduce<CostCoverage>(
+    (total, row) => ({
+      events: total.events + row.coverage.events,
+      tokens: total.tokens + row.coverage.tokens,
+      usd: total.usd + row.coverage.usd,
+      brl: total.brl + row.coverage.brl,
+    }),
+    { events: 0, tokens: 0, usd: 0, brl: 0 },
+  );
+}
+
+function compareRows(left: CostGroupRow, right: CostGroupRow): number {
+  return right.latest_started_at.localeCompare(left.latest_started_at);
+}