@zaip-ai/cli 1.0.4 → 1.0.7

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

@@ -0,0 +1,775 @@
+import {
+  type OperationsProjection,
+  type RunProjection,
+  saoPauloPeriodKey,
+} from "@zaip-ai/dashboard-operations/contracts";
+import {
+  EntityDetailsDialog,
+  ExcelExportAction,
+  ExecutionTable,
+} from "@zaip-ai/dashboard-operations/react";
+import { DashboardHeader } from "@zaip-ai/dashboard-ui";
+import { type ReactNode, useEffect, useMemo, useState } from "react";
+import { includeConfiguredAgentGroups } from "../agent-groups.js";
+import {
+  aggregateDurationCoverage,
+  type CostGroupRow,
+  type CostMonitorProjection,
+  type CostRunRow,
+  sumKnown,
+} from "../contracts.js";
+import { normalizeCostProvider } from "../provider.js";
+import { aggregateTaskCostRows } from "../task-cost-groups.js";
+import { CostCharts } from "./CostCharts.js";
+import {
+  type CostFilterState,
+  CostFilters,
+  type CostPeriod,
+  defaultCostPeriod,
+  emptyCostFilters,
+  loadCostMonitorPeriod,
+  useCostMonitorPeriod,
+} from "./CostFilters.js";
+import { ChevronDownIcon, ListFilterIcon, LocaleFlag, SettingsIcon } from "./CostMonitorIcons.js";
+import { CostPeriodAverageCards } from "./CostPeriodAverageCards.js";
+import { CostSummary } from "./CostSummary.js";
+import { CostGroupsTable, CostModelsAuditTable, CostRunsTable } from "./CostTables.js";
+import { durationContributors } from "./cost-duration.js";
+import {
+  type CostCurrency,
+  type CostLocale,
+  costCopy,
+  localeCurrency,
+} from "./cost-monitor-copy.js";
+import { applyLegacyPeriodGroups, summarizeCostRows } from "./cost-monitor-summary.js";
+import { MacroCostTable } from "./MacroCostTable.js";
+import { enrichPeriodCostGroups } from "./period-cost-groups.js";
+import "./cost-monitor.css";
+import "./cost-monitor-responsive.css";
+import "./cost-run-origin.css";
+import "./cost-monitor-embedded.css";
+
+const zaipLogoUrl = new URL("../../../../../config/src/logo_novo_azul.png", import.meta.url).href;
+
+export type CostView =
+  | "overview"
+  | "agentCalls"
+  | "executions"
+  | "conversations"
+  | "tasks"
+  | "prds"
+  | "specs"
+  | "providers"
+  | "agents"
+  | "models"
+  | "daily"
+  | "monthly"
+  | "annual";
+export const DEFAULT_COST_VIEW: CostView = "daily";
+export const COST_VIEW_ORDER: readonly CostView[] = [
+  "overview",
+  "executions",
+  "agentCalls",
+  "agents",
+  "models",
+  "providers",
+  "tasks",
+  "specs",
+  "prds",
+  "conversations",
+  "daily",
+  "monthly",
+  "annual",
+];
+type AgentCallKind = "all" | "run" | "subrun";
+export function findRunDetails<T extends { id: string }>(
+  runs: readonly T[],
+  runId: string,
+): T | null {
+  return runs.find((run) => run.id === runId) ?? null;
+}
+export function CostMonitorPage({
+  capabilityNavigation,
+  data,
+  dashboardTitle = "Dashboard Zaip AIOS",
+  embedded = false,
+  globalFilters,
+  lastUpdatedAt,
+  locale,
+  loading,
+  onLocaleChange,
+  onOpenTrace,
+  onActiveDataChange,
+  onRefresh,
+  loadPeriod = loadCostMonitorPeriod,
+  operations,
+  repositoryName,
+  currency: controlledCurrency,
+  onCurrencyChange,
+}: {
+  capabilityNavigation?: ReactNode;
+  data: CostMonitorProjection;
+  dashboardTitle?: string;
+  embedded?: boolean;
+  globalFilters?: {
+    query: string;
+    datePreset: string;
+    dateRange?: { start: string; end: string };
+  };
+  lastUpdatedAt: string | null;
+  locale: CostLocale;
+  loading: boolean;
+  onLocaleChange: (locale: CostLocale) => void;
+  onOpenTrace: (taskId: string) => void;
+  onActiveDataChange?: (data: CostMonitorProjection) => void;
+  onRefresh: () => void;
+  loadPeriod?: typeof loadCostMonitorPeriod;
+  operations?: Pick<OperationsProjection, "runs" | "specs" | "tasks" | "executions">;
+  repositoryName?: string;
+  currency?: CostCurrency;
+  onCurrencyChange?: (currency: CostCurrency) => void;
+}) {
+  const [view, setView] = useState<CostView>(DEFAULT_COST_VIEW);
+  const [agentCallKind, setAgentCallKind] = useState<AgentCallKind>("all");
+  const [filters, setFilters] = useState<CostFilterState>(emptyCostFilters);
+  const [localCurrency, setLocalCurrency] = useState<CostCurrency>("BRL");
+  const currency = controlledCurrency ?? localCurrency;
+  const setCurrency = (next: CostCurrency) => {
+    setLocalCurrency(next);
+    onCurrencyChange?.(next);
+  };
+  const [period, setPeriod] = useState<CostPeriod>(defaultCostPeriod);
+  const [filtersOpen, setFiltersOpen] = useState(false);
+  const [localeOpen, setLocaleOpen] = useState(false);
+  const [settingsOpen, setSettingsOpen] = useState(false);
+  const [selectedRun, setSelectedRun] = useState<RunProjection | null>(null);
+  const text = costCopy[locale];
+  const { activeData, periodError, periodLoading } = useCostMonitorPeriod({
+    currency,
+    data,
+    ...(globalFilters === undefined ? {} : { dateRange: globalFilters.dateRange }),
+    filters,
+    lastUpdatedAt,
+    loadPeriod,
+    period,
+    snapshotBacked: embedded,
+  });
+  const hasLocalCostFilters = Object.values(filters).some((value) => value !== "");
+  useEffect(() => {
+    if (!hasLocalCostFilters) onActiveDataChange?.(activeData);
+  }, [activeData, hasLocalCostFilters, onActiveDataChange]);
+  const updatedLabel =
+    lastUpdatedAt === null
+      ? locale === "pt-BR"
+        ? "Aguardando atualização"
+        : "Waiting for refresh"
+      : `${locale === "pt-BR" ? "Atualizado" : "Updated"} ${new Intl.DateTimeFormat(locale, { dateStyle: "short", timeStyle: "medium" }).format(new Date(lastUpdatedAt))}`;
+  const rows = useMemo(() => {
+    return activeData.runs
+      .filter((row) => matches(row, filters) && matchesGlobalFilters(row, globalFilters))
+      .sort((left, right) => right.started_at.localeCompare(left.started_at));
+  }, [activeData.runs, filters, globalFilters]);
+  const macroDetails = useMemo(() => {
+    if (operations === undefined) return undefined;
+    const visibleRunIds = new Set(rows.map((row) => row.run_id));
+    return {
+      ...operations,
+      runs: operations.runs.filter((run) => visibleRunIds.has(run.id)),
+    };
+  }, [operations, rows]);
+  const visiblePrds = useMemo(
+    () => activeData.prds.filter((prd) => matchesPeriodEntity(prd, globalFilters)),
+    [activeData.prds, globalFilters],
+  );
+  const visibleSpecs = useMemo(
+    () => activeData.specs.filter((spec) => matchesPeriodEntity(spec, globalFilters)),
+    [activeData.specs, globalFilters],
+  );
+  const groups = useMemo(() => {
+    const legacy =
+      !hasLocalCostFilters &&
+      (globalFilters === undefined ||
+        (globalFilters.query === "" && globalFilters.datePreset === "all"))
+        ? (activeData.legacy_effort_baseline ?? null)
+        : null;
+    const periodEntities = {
+      prds: activeData.prds.filter((prd) => matchesPeriodEntity(prd, globalFilters)),
+      specs: activeData.specs.filter((spec) => matchesPeriodEntity(spec, globalFilters)),
+      tasks: (operations?.tasks ?? []).filter((task) => matchesPeriodEntity(task, globalFilters)),
+    };
+    return {
+      conversations: groupRows(
+        rows.filter((row) => row.phase === "conversation"),
+        (row) => row.conversation_id ?? row.task_title ?? row.run_id,
+        undefined,
+        "all_invocations",
+      ),
+      tasks: aggregateTaskCostRows(periodEntities.tasks, rows),
+      providers: groupRows(
+        rows,
+        (row) => normalizeCostProvider(row.provider),
+        undefined,
+        "all_invocations",
+      ),
+      agents: includeConfiguredAgentGroups(
+        groupRows(rows, (row) => row.agent_name),
+        activeData.configured_agents,
+      ),
+      models: groupRows(rows, (row) => row.model),
+      daily: applyLegacyPeriodGroups(
+        enrichPeriodCostGroups(
+          groupRows(
+            rows,
+            (row) => saoPauloPeriodKey(row.started_at, "day") ?? row.started_at.slice(0, 10),
+          ),
+          periodEntities,
+          "daily",
+        ),
+        rows,
+        "day",
+        legacy,
+      ),
+      monthly: applyLegacyPeriodGroups(
+        enrichPeriodCostGroups(
+          groupRows(
+            rows,
+            (row) => saoPauloPeriodKey(row.started_at, "month") ?? row.started_at.slice(0, 7),
+          ),
+          periodEntities,
+          "monthly",
+        ),
+        rows,
+        "month",
+        legacy,
+      ),
+      annual: applyLegacyPeriodGroups(
+        enrichPeriodCostGroups(
+          groupRows(
+            rows,
+            (row) => saoPauloPeriodKey(row.started_at, "year") ?? row.started_at.slice(0, 4),
+          ),
+          periodEntities,
+          "annual",
+        ),
+        rows,
+        "year",
+        legacy,
+      ),
+    };
+  }, [
+    activeData.configured_agents,
+    activeData.prds,
+    activeData.specs,
+    globalFilters,
+    operations?.tasks,
+    rows,
+    hasLocalCostFilters,
+    activeData.legacy_effort_baseline,
+  ]);
+  const overview = summarizeCostRows(rows, activeData.overview);
+  const exportRows = useMemo(() => {
+    if (view === "executions") return operations?.executions ?? [];
+    if (view === "conversations") return groups.conversations;
+    if (view === "tasks") return groups.tasks;
+    if (view === "prds") return visiblePrds;
+    if (view === "specs") return visibleSpecs;
+    if (view === "providers" || view === "agents") return groups[view];
+    if (view === "daily" || view === "monthly" || view === "annual") return groups[view];
+    return view === "agentCalls" && agentCallKind !== "all"
+      ? rows.filter((row) => row.run_kind === agentCallKind)
+      : rows;
+  }, [agentCallKind, groups, operations?.executions, rows, view, visiblePrds, visibleSpecs]);
+  const changeLocale = (next: CostLocale) => {
+    onLocaleChange(next);
+    setCurrency(localeCurrency(next));
+  };
+  const openRunDetails = (runId: string) => {
+    const run = findRunDetails(operations?.runs ?? [], runId);
+    if (run) setSelectedRun(run);
+  };
+  const Root = embedded ? "section" : "main";
+  return (
+    <Root className={embedded ? "cost-page cost-page-embedded" : "cost-page"}>
+      {embedded ? null : (
+        <DashboardHeader
+          filters={
+            <CostFilters
+              available={data.filters_available}
+              hideQuery={embedded}
+              locale={locale}
+              onChange={setFilters}
+              value={filters}
+            />
+          }
+          filtersActive={Object.values(filters).some(Boolean)}
+          lastUpdatedAt={lastUpdatedAt}
+          loading={loading || periodLoading}
+          locale={locale}
+          onLocaleChange={changeLocale}
+          onRefresh={onRefresh}
+          settings={
+            <label>
+              <span>{text.currency}</span>
+              <select
+                onChange={(event) => setCurrency(event.target.value as CostCurrency)}
+                value={currency}
+              >
+                <option value="BRL">BRL · R$</option>
+                <option value="USD">USD · $</option>
+              </select>
+            </label>
+          }
+          {...(repositoryName === undefined ? {} : { repositoryName })}
+          title={dashboardTitle}
+        />
+      )}
+      {periodError ? (
+        <p className="cost-period-error" role="status">
+          {locale === "pt-BR"
+            ? `Não foi possível carregar o período selecionado: ${periodError}`
+            : `Could not load the selected period: ${periodError}`}
+        </p>
+      ) : null}
+      {embedded ? null : (
+        <>
+          <nav aria-label="Navegação do Cost Monitor" className="cost-monitor-nav">
+            <div className="cost-monitor-brand">
+              <strong className="cost-monitor-title">{text.title}</strong>
+              <small className="cost-last-updated">{updatedLabel}</small>
+            </div>
+            <img alt="ZAIP" className="cost-monitor-logo" src={zaipLogoUrl} />
+            <div className="cost-nav-actions">
+              <button
+                aria-label={text.refresh}
+                className="cost-nav-icon cost-refresh-action"
+                disabled={loading}
+                onClick={onRefresh}
+                type="button"
+              >
+                ↻
+              </button>
+              <div className="cost-nav-popup-anchor cost-filter-action">
+                <button
+                  className={filtersOpen ? "cost-nav-button is-active" : "cost-nav-button"}
+                  onClick={() => {
+                    setFiltersOpen((open) => !open);
+                    setLocaleOpen(false);
+                    setSettingsOpen(false);
+                  }}
+                  type="button"
+                >
+                  <ListFilterIcon /> {text.filters}
+                </button>
+                {filtersOpen ? (
+                  <div className="cost-nav-popup cost-nav-filter-popup">
+                    <CostFilters
+                      available={data.filters_available}
+                      hideQuery={embedded}
+                      locale={locale}
+                      onChange={setFilters}
+                      value={filters}
+                    />
+                  </div>
+                ) : null}
+              </div>
+              <div className="cost-nav-popup-anchor cost-locale-action">
+                <button
+                  className={localeOpen ? "cost-nav-button is-active" : "cost-nav-button"}
+                  onClick={() => {
+                    setLocaleOpen((open) => !open);
+                    setFiltersOpen(false);
+                    setSettingsOpen(false);
+                  }}
+                  type="button"
+                >
+                  <LocaleFlag locale={locale} />
+                  {locale === "pt-BR" ? "PT-BR" : "EN-US"}
+                  <ChevronDownIcon />
+                </button>
+                {localeOpen ? (
+                  <div className="cost-nav-popup cost-nav-locale-popup">
+                    <button onClick={() => changeLocale("pt-BR")} type="button">
+                      <LocaleFlag locale="pt-BR" /> Português do Brasil{" "}
+                      {locale === "pt-BR" ? "✓" : ""}
+                    </button>
+                    <button onClick={() => changeLocale("en-US")} type="button">
+                      <LocaleFlag locale="en-US" /> English {locale === "en-US" ? "✓" : ""}
+                    </button>
+                  </div>
+                ) : null}
+              </div>
+              <div className="cost-nav-popup-anchor cost-settings-action">
+                <button
+                  aria-label={text.settings}
+                  className={settingsOpen ? "cost-nav-icon is-active" : "cost-nav-icon"}
+                  onClick={() => {
+                    setSettingsOpen((open) => !open);
+                    setFiltersOpen(false);
+                    setLocaleOpen(false);
+                  }}
+                  type="button"
+                >
+                  <SettingsIcon />
+                </button>
+                {settingsOpen ? (
+                  <div className="cost-nav-popup cost-nav-settings-popup">
+                    <div className="cost-mobile-settings">
+                      <small className="cost-mobile-updated">{updatedLabel}</small>
+                      <button disabled={loading} onClick={onRefresh} type="button">
+                        ↻{" "}
+                        {loading
+                          ? locale === "pt-BR"
+                            ? "Atualizando…"
+                            : "Refreshing…"
+                          : text.refresh}
+                      </button>
+                      <label>
+                        <span>{locale === "pt-BR" ? "Idioma" : "Language"}</span>
+                        <select
+                          onChange={(event) => changeLocale(event.target.value as CostLocale)}
+                          value={locale}
+                        >
+                          <option value="pt-BR">Português do Brasil</option>
+                          <option value="en-US">English</option>
+                        </select>
+                      </label>
+                      <div className="cost-mobile-filters">
+                        <strong>{text.filters}</strong>
+                        <CostFilters
+                          available={data.filters_available}
+                          hideQuery={embedded}
+                          locale={locale}
+                          onChange={setFilters}
+                          value={filters}
+                        />
+                      </div>
+                    </div>
+                    <label>
+                      <span>{text.currency}</span>
+                      <select
+                        onChange={(event) => setCurrency(event.target.value as CostCurrency)}
+                        value={currency}
+                      >
+                        <option value="BRL">BRL · R$</option>
+                        <option value="USD">USD · $</option>
+                      </select>
+                    </label>
+                  </div>
+                ) : null}
+              </div>
+            </div>
+          </nav>
+          <header className="cost-hero">
+            <p className="cost-hero-description">{text.subtitle}</p>
+            <label className="cost-period">
+              <span>{text.period}</span>
+              <select
+                onChange={(event) => setPeriod(event.target.value as CostPeriod)}
+                value={period}
+              >
+                <option value="all">{text.allTime}</option>
+                <option value="7">{text.last7}</option>
+                <option value="30">{text.last30}</option>
+                <option value="90">{text.last90}</option>
+                <option value="month">{text.thisMonth}</option>
+              </select>
+            </label>
+          </header>
+        </>
+      )}
+      {embedded ? null : (
+        <>
+          <CostSummary currency={currency} locale={locale} overview={overview} />
+          <div className="cost-coverage-note">
+            <span>.agents/records/lifecycle + telemetry manifests</span>
+            <strong>
+              {overview.coverage.tokens}/{overview.coverage.events} eventos com tokens ·{" "}
+              {overview.coverage.brl}/{overview.coverage.events} com custo
+            </strong>
+          </div>
+          {capabilityNavigation}
+        </>
+      )}
+      <nav aria-label="Visões de custo" className="cost-tabs">
+        {COST_VIEW_ORDER.map((key) => (
+          <button
+            className={view === key ? "is-active" : undefined}
+            key={key}
+            onClick={() => setView(key)}
+            type="button"
+          >
+            {text.tabs[key]}
+          </button>
+        ))}
+        <ExcelExportAction
+          filters={{ ...filters, ...globalFilters, period, agentCallKind }}
+          rows={exportRows as unknown as readonly Record<string, unknown>[]}
+          view={`cost-${view}`}
+        />
+      </nav>
+      <section
+        className={`cost-content cost-content-${view} ${view === "overview" ? "cost-content-overview" : ""}`}
+      >
+        {view === "overview" ? (
+          <CostCharts
+            currency={currency}
+            daily={groups.daily}
+            locale={locale}
+            models={groups.models}
+            rows={rows}
+          />
+        ) : null}
+        {view === "agentCalls" ? (
+          <>
+            <nav
+              aria-label={locale === "pt-BR" ? "Tipo de chamada de agente" : "Agent call type"}
+              className="cost-run-kind-toolbar"
+            >
+              {(["all", "run", "subrun"] as const).map((kind) => (
+                <button
+                  aria-pressed={agentCallKind === kind}
+                  className={agentCallKind === kind ? "is-active" : undefined}
+                  key={kind}
+                  onClick={() => setAgentCallKind(kind)}
+                  type="button"
+                >
+                  {kind === "all"
+                    ? locale === "pt-BR"
+                      ? "Todos"
+                      : "All"
+                    : kind === "run"
+                      ? locale === "pt-BR"
+                        ? "Invocações do orquestrador"
+                        : "Orchestrator invocations"
+                      : locale === "pt-BR"
+                        ? "Invocações delegadas"
+                        : "Delegated invocations"}
+                </button>
+              ))}
+            </nav>
+            <CostRunsTable
+              currency={currency}
+              locale={locale}
+              onOpenRun={openRunDetails}
+              rows={
+                agentCallKind === "all"
+                  ? rows
+                  : rows.filter((row) => row.run_kind === agentCallKind)
+              }
+            />
+          </>
+        ) : null}
+        {view === "executions" ? (
+          <ExecutionTable locale={locale} rows={operations?.executions ?? []} />
+        ) : null}
+        {view === "conversations" ? (
+          <CostGroupsTable
+            currency={currency}
+            labelHeading={locale === "pt-BR" ? "Conversa" : "Conversation"}
+            locale={locale}
+            rows={groups.conversations}
+          />
+        ) : null}
+        {view === "tasks" ? (
+          <CostGroupsTable
+            currency={currency}
+            dateHeading={locale === "pt-BR" ? "Criada em" : "Created at"}
+            labelHeading={locale === "pt-BR" ? "Tarefa" : "Task"}
+            locale={locale}
+            onOpenTrace={onOpenTrace}
+            rows={groups.tasks}
+          />
+        ) : null}
+        {view === "prds" ? (
+          <MacroCostTable
+            currency={currency}
+            locale={locale}
+            onOpenTrace={onOpenTrace}
+            rows={visiblePrds}
+            {...(macroDetails ? { details: macroDetails } : {})}
+          />
+        ) : null}
+        {view === "specs" ? (
+          <MacroCostTable
+            currency={currency}
+            locale={locale}
+            onOpenTrace={onOpenTrace}
+            rows={visibleSpecs}
+            {...(macroDetails ? { details: macroDetails } : {})}
+          />
+        ) : null}
+        {view === "models" ? <CostModelsAuditTable locale={locale} rows={rows} /> : null}
+        {(["providers", "agents"] as const).map((key) =>
+          view === key ? (
+            <CostGroupsTable
+              currency={currency}
+              key={key}
+              labelHeading={
+                key === "agents"
+                  ? locale === "pt-BR"
+                    ? "Zaip Agentes"
+                    : "ZAIP agents"
+                  : locale === "pt-BR"
+                    ? "Provedor"
+                    : "Providers"
+              }
+              locale={locale}
+              rows={groups[key]}
+            />
+          ) : null,
+        )}
+        {view === "daily" || view === "monthly" || view === "annual" ? (
+          <>
+            <CostPeriodAverageCards
+              currency={currency}
+              locale={locale}
+              period={view}
+              rows={groups[view]}
+            />
+            <CostGroupsTable
+              currency={currency}
+              locale={locale}
+              period={view}
+              rows={groups[view]}
+              showDateTime={false}
+            />
+          </>
+        ) : null}
+      </section>
+      {selectedRun ? (
+        <EntityDetailsDialog
+          details={{ kind: "run", row: selectedRun }}
+          locale={locale}
+          onClose={() => setSelectedRun(null)}
+        />
+      ) : null}
+    </Root>
+  );
+}
+
+function matches(row: CostRunRow, filter: CostFilterState): boolean {
+  const query = filter.query.trim().toLowerCase();
+  return (
+    (!query ||
+      [row.run_id, row.task_title, row.model, row.requested_model, row.agent, row.agent_name].some(
+        (value) => value.toLowerCase().includes(query),
+      )) &&
+    (!filter.provider || normalizeCostProvider(row.provider) === filter.provider) &&
+    (!filter.agent || row.agent_name === filter.agent) &&
+    (!filter.model || row.model === filter.model) &&
+    (!filter.status || row.task_status === filter.status) &&
+    (!filter.priority || row.priority === filter.priority) &&
+    (!filter.risk || row.risk === filter.risk) &&
+    (!filter.phase || row.phase === filter.phase) &&
+    (!filter.origin || row.origin === filter.origin) &&
+    (!filter.workType || row.work_type === filter.workType)
+  );
+}
+
+export function matchesGlobalFilters(
+  row: CostRunRow,
+  filters: { query: string; dateRange?: { start: string; end: string } } | undefined,
+): boolean {
+  if (!filters) return true;
+  const query = filters.query.trim().toLocaleLowerCase();
+  if (filters.dateRange === undefined) {
+    return (
+      !query ||
+      [
+        row.run_id,
+        row.task_id,
+        row.task_title,
+        row.provider,
+        row.agent,
+        row.agent_name,
+        row.model,
+        row.requested_model,
+        row.phase,
+      ].some((value) => value?.toLocaleLowerCase().includes(query))
+    );
+  }
+  const startedDate = saoPauloPeriodKey(row.started_at, "day") ?? row.started_at.slice(0, 10);
+  return (
+    startedDate >= filters.dateRange.start &&
+    startedDate <= filters.dateRange.end &&
+    (!query ||
+      [
+        row.run_id,
+        row.task_id,
+        row.task_title,
+        row.provider,
+        row.agent,
+        row.agent_name,
+        row.model,
+        row.requested_model,
+        row.phase,
+      ].some((value) => value?.toLocaleLowerCase().includes(query)))
+  );
+}
+
+export function groupRows(
+  rows: readonly CostRunRow[],
+  select: (row: CostRunRow) => string,
+  label: (row: CostRunRow) => string = select,
+  durationScope: "root_execution" | "all_execution" | "all_invocations" = "all_invocations",
+): CostGroupRow[] {
+  const contributors = durationContributors(rows, durationScope);
+  const groups = new Map<string, CostRunRow[]>();
+  for (const row of rows) groups.set(select(row), [...(groups.get(select(row)) ?? []), row]);
+  return [...groups]
+    .map(([key, items]) => ({
+      ...(() => {
+        const duration = aggregateDurationCoverage(
+          contributors.filter((candidate) => items.includes(candidate)),
+          durationScope === "all_execution" ? "all_execution" : "all_invocations",
+        );
+        return { duration_ms: duration.complete ? duration.known_sum : null, duration };
+      })(),
+      key,
+      label: label(items[0] as CostRunRow),
+      latest_started_at: items.reduce(
+        (latest, row) => (row.started_at > latest ? row.started_at : latest),
+        items[0]?.started_at ?? "",
+      ),
+      run_count: items.length,
+      task_count: new Set(items.flatMap((row) => (row.task_id ? [row.task_id] : []))).size,
+      tasksActive: new Set(items.flatMap((row) => (row.task_id ? [row.task_id] : []))).size,
+      taskDaysActive: new Set(items.flatMap((row) => (row.task_id ? [row.task_id] : []))).size,
+      prd_count: 0,
+      spec_count: 0,
+      evidence_count: 0,
+      test_count: 0,
+      event_count: items.reduce((sum, row) => sum + row.event_count, 0),
+      total_tokens: sumKnown(items.map((row) => row.total_tokens)),
+      estimated_usd: sumKnown(items.map((row) => row.estimated_usd)),
+      estimated_brl: sumKnown(items.map((row) => row.estimated_brl)),
+      coverage: items.reduce(
+        (sum, row) => ({
+          events: sum.events + row.coverage.events,
+          tokens: sum.tokens + row.coverage.tokens,
+          usd: sum.usd + row.coverage.usd,
+          brl: sum.brl + row.coverage.brl,
+        }),
+        { events: 0, tokens: 0, usd: 0, brl: 0 },
+      ),
+    }))
+    .sort((a, b) => b.latest_started_at.localeCompare(a.latest_started_at));
+}
+
+export function matchesPeriodEntity(
+  entity: { id?: string; title?: string; created_at: string | null },
+  filters: { query: string; dateRange?: { start: string; end: string } } | undefined,
+): boolean {
+  if (filters === undefined) return true;
+  const query = filters.query.trim().toLowerCase();
+  if (
+    query &&
+    ![entity.id ?? "", entity.title ?? ""].some((value) => value.toLowerCase().includes(query))
+  ) {
+    return false;
+  }
+  if (filters.dateRange === undefined) return true;
+  if (entity.created_at === null) return false;
+  const date = saoPauloPeriodKey(entity.created_at, "day") ?? entity.created_at.slice(0, 10);
+  return date >= filters.dateRange.start && date <= filters.dateRange.end;
+}