@zaip-ai/cli 1.0.7 → 1.3.0

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

@@ -0,0 +1,141 @@
+import type {
+  ChangeProjection,
+  MacroProjection,
+  OperationsProjection,
+  PrdDetailProjection,
+  SpecDetailProjection,
+} from "@zaip-ai/dashboard-operations/contracts";
+import type { TaskTrace } from "@zaip-ai/dashboard-traceability/contracts";
+import { type Dispatch, type SetStateAction, useRef, useState } from "react";
+import type { LoadingArea } from "./AppLoadingPanels.js";
+import type { DashboardApiClient } from "./dashboard-api.js";
+
+export function useAppTraceDocuments({
+  api,
+  operations,
+  setError,
+  setFailedArea,
+  setLoadingArea,
+}: {
+  api: DashboardApiClient;
+  operations: OperationsProjection | null;
+  setError: Dispatch<SetStateAction<string | null>>;
+  setFailedArea: Dispatch<SetStateAction<LoadingArea | null>>;
+  setLoadingArea: Dispatch<SetStateAction<LoadingArea | null>>;
+}) {
+  const [trace, setTrace] = useState<TaskTrace | null>(null);
+  const [traceTasks, setTraceTasks] = useState<OperationsProjection["tasks"]>([]);
+  const [documentDetail, setDocumentDetail] = useState<{
+    kind: "prd" | "spec";
+    label: "PRD" | "SPEC";
+    preview: Pick<MacroProjection, "id" | "title" | "artifact_path">;
+    detail?: PrdDetailProjection | SpecDetailProjection;
+    error?: string;
+  } | null>(null);
+  const [traceLink, setTraceLink] = useState<
+    | { kind: "change"; row: ChangeProjection }
+    | { kind: "macro"; label: "PRD" | "SPEC"; row: MacroProjection }
+    | null
+  >(null);
+  const documentRequestId = useRef(0);
+  const traceRequestId = useRef(0);
+  const [traceLoadingTaskId, setTraceLoadingTaskId] = useState<string | null>(null);
+  const [selectedTraceTaskId, setSelectedTraceTaskId] = useState("");
+
+  async function openTrace(taskId: string) {
+    const requestId = ++traceRequestId.current;
+    setError(null);
+    setFailedArea(null);
+    setTrace(null);
+    setTraceLoadingTaskId(taskId);
+    setLoadingArea("traceability");
+    await new Promise<void>((resolveFrame) => window.requestAnimationFrame(() => resolveFrame()));
+    try {
+      const loadedTrace = await api.taskTrace(taskId);
+      if (traceRequestId.current !== requestId) return false;
+      const cardTask =
+        traceTasks.find((task) => task.id === taskId) ??
+        operations?.tasks.find((task) => task.id === taskId);
+      setTrace({
+        ...loadedTrace,
+        task_title: cardTask?.title || loadedTrace.task_title || taskId,
+        task_risk: cardTask?.risk || loadedTrace.task_risk || null,
+        task_created_at: cardTask?.created_at || loadedTrace.task_created_at || null,
+        task_progress: cardTask?.progress ?? loadedTrace.task_progress ?? 0,
+      });
+      return true;
+    } catch (cause) {
+      if (traceRequestId.current !== requestId) return false;
+      setError(cause instanceof Error ? cause.message : String(cause));
+      setFailedArea("traceability");
+      return false;
+    } finally {
+      if (traceRequestId.current === requestId) {
+        setTraceLoadingTaskId(null);
+        setLoadingArea((current) => (current === "traceability" ? null : current));
+      }
+    }
+  }
+
+  function openTraceChange(changeId: string) {
+    const row = operations?.changes.find((change) => change.id === changeId);
+    if (row === undefined) return;
+    setTrace(null);
+    setTraceLink({ kind: "change", row });
+  }
+
+  function openTraceMacro(label: "PRD" | "SPEC", id: string) {
+    const rows = label === "PRD" ? operations?.prds : operations?.specs;
+    const row = rows?.find((macro) => macro.id === id);
+    if (row === undefined) return;
+    setTrace(null);
+    setTraceLink({ kind: "macro", label, row });
+  }
+
+  async function openDocument(kind: "prd" | "spec", id: string) {
+    const preview = (kind === "prd" ? operations?.prds : operations?.specs)?.find(
+      (macro) => macro.id === id,
+    );
+    if (!preview) return;
+    const requestId = ++documentRequestId.current;
+    const label = kind === "prd" ? "PRD" : "SPEC";
+    setDocumentDetail({ kind, label, preview });
+    try {
+      const detail = kind === "prd" ? await api.prd(id) : await api.spec(id);
+      if (documentRequestId.current !== requestId) return;
+      setDocumentDetail({ kind, label, preview, detail });
+    } catch (cause) {
+      if (documentRequestId.current !== requestId) return;
+      setDocumentDetail({
+        kind,
+        label,
+        preview,
+        error: cause instanceof Error ? cause.message : String(cause),
+      });
+    }
+  }
+
+  function closeDocument() {
+    documentRequestId.current += 1;
+    setDocumentDetail(null);
+  }
+
+  return {
+    closeDocument,
+    documentDetail,
+    openDocument,
+    openTrace,
+    openTraceChange,
+    openTraceMacro,
+    selectedTraceTaskId,
+    setSelectedTraceTaskId,
+    setTrace,
+    setTraceLink,
+    setTraceLoadingTaskId,
+    setTraceTasks,
+    trace,
+    traceLink,
+    traceLoadingTaskId,
+    traceTasks,
+  };
+}

package/templates/.agents/dashboard/apps/frontend/src/use-idle-cost-prefetch.ts

@@ -0,0 +1,45 @@
+import type { CostCurrency } from "@zaip-ai/dashboard-cost-monitor/react";
+import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
+import { type MutableRefObject, useEffect } from "react";
+import type { DashboardApiClient } from "./dashboard-api.js";
+
+type Prefetch = { key: string; promise: ReturnType<DashboardApiClient["snapshot"]> } | null;
+
+export function useIdleCostPrefetch({
+  api,
+  currency,
+  key,
+  operations,
+  period,
+  prefetch,
+}: {
+  api: DashboardApiClient;
+  currency: CostCurrency;
+  key: string;
+  operations: OperationsProjection | null;
+  period: { from: string | null; to: string | null };
+  prefetch: MutableRefObject<Prefetch>;
+}) {
+  useEffect(() => {
+    if (operations === null || operations.runs.length === 0 || prefetch.current?.key === key)
+      return;
+    let cancelled = false;
+    const load = () => {
+      if (cancelled) return;
+      const promise = api.snapshot(currency, period);
+      prefetch.current = { key, promise };
+      void promise.catch(() => {
+        if (prefetch.current?.promise === promise) prefetch.current = null;
+      });
+    };
+    const handle =
+      typeof window.requestIdleCallback === "function"
+        ? { kind: "idle" as const, id: window.requestIdleCallback(load) }
+        : { kind: "timeout" as const, id: window.setTimeout(load, 0) };
+    return () => {
+      cancelled = true;
+      if (handle.kind === "idle") window.cancelIdleCallback(handle.id);
+      else window.clearTimeout(handle.id);
+    };
+  }, [api, currency, key, operations, period, prefetch]);
+}

package/templates/.agents/dashboard/apps/frontend/src/work-list-pagination.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  collectWorkListPages,
+  normalizeWorkListFilters,
+  selectedWorkListKinds,
+} from "./work-list-pagination.js";
+
+describe("Trabalho (Lista) canonical pagination", () => {
+  it("keeps a server-selected PRD/SPEC kind instead of refetching every kind", () => {
+    expect(selectedWorkListKinds("spec")).toEqual(["spec"]);
+    expect(selectedWorkListKinds("prd")).toEqual(["prd"]);
+    expect(selectedWorkListKinds("standalone-task")).toEqual(["standalone-task"]);
+    expect(selectedWorkListKinds("")).toEqual(["prd", "spec", "task", "standalone-task"]);
+  });
+
+  it("retains the List type through search/status changes without mutating the Kanban snapshot", () => {
+    const kanban = { query: "kanban", status: "ready", risk: "", kind: "" };
+    const listSpec = normalizeWorkListFilters(
+      { query: "", status: "", risk: "", kind: "spec" },
+      { query: "", status: "", risk: "" },
+    );
+    const searched = normalizeWorkListFilters(
+      { query: "telemetria", status: "executing", risk: "standard" },
+      listSpec,
+    );
+
+    expect(searched).toMatchObject({
+      query: "telemetria",
+      status: "executing",
+      risk: "standard",
+      kind: "spec",
+    });
+    expect(kanban).toEqual({ query: "kanban", status: "ready", risk: "", kind: "" });
+  });
+
+  it("continues from the returned offset until the canonical total is complete", async () => {
+    const loadPage = vi
+      .fn()
+      .mockResolvedValueOnce({ total: 59, received: 50, value: "first" })
+      .mockResolvedValueOnce({ total: 59, received: 9, value: "second" });
+
+    await expect(collectWorkListPages(loadPage)).resolves.toEqual(["first", "second"]);
+    expect(loadPage).toHaveBeenNthCalledWith(1, 0);
+    expect(loadPage).toHaveBeenNthCalledWith(2, 50);
+  });
+});

package/templates/.agents/dashboard/apps/frontend/src/work-list-pagination.ts

@@ -0,0 +1,36 @@
+export type WorkListKind = "prd" | "spec" | "task" | "standalone-task";
+
+export type WorkListFilters = {
+  query: string;
+  status: string;
+  risk: string;
+  origin?: string;
+  kind?: string;
+};
+
+/** Keep the List snapshot independent of Kanban while retaining its selected type. */
+export function normalizeWorkListFilters(
+  filters: WorkListFilters,
+  previous: WorkListFilters,
+): WorkListFilters {
+  return { ...filters, kind: filters.kind ?? previous.kind ?? "" };
+}
+
+export function selectedWorkListKinds(kind: string | undefined): readonly WorkListKind[] {
+  return kind === "prd" || kind === "spec" || kind === "task" || kind === "standalone-task"
+    ? [kind]
+    : ["prd", "spec", "task", "standalone-task"];
+}
+
+export async function collectWorkListPages<T>(
+  loadPage: (offset: number) => Promise<{ total: number; received: number; value: T }>,
+): Promise<T[]> {
+  const pages: T[] = [];
+  let offset = 0;
+  for (;;) {
+    const page = await loadPage(offset);
+    pages.push(page.value);
+    offset += page.received;
+    if (page.received === 0 || offset >= page.total) return pages;
+  }
+}

package/templates/.agents/dashboard/apps/frontend/vite.config.ts

@@ -1,22 +1,75 @@
 import react from "@vitejs/plugin-react";
 import { defineConfig } from "vite";
 
-const apiPort = Number.parseInt(process.env.ZAIP_DASHBOARD_API_PORT ?? "4317", 10);
+const apiPort = Number.parseInt(process.env.ZAIP_DASHBOARD_API_PORT ?? "4417", 10);
+const sourcePath = (relativePath: string): string =>
+  new URL(relativePath, import.meta.url).pathname.replace(/^\/([A-Za-z]:\/)/, "$1");
 
 export default defineConfig({
-  cacheDir: "../../../../.cache/vite/dashboard-frontend",
+  cacheDir: "../../../../.cache/vite/dashboard-sqlite-frontend",
   plugins: [react()],
+  resolve: {
+    alias: {
+      react: sourcePath("../../../../node_modules/.pnpm/react@19.2.7/node_modules/react"),
+      "react-dom": sourcePath(
+        "../../../../node_modules/.pnpm/react-dom@19.2.7_react@19.2.7/node_modules/react-dom",
+      ),
+      zod: sourcePath("../../../../node_modules/.pnpm/zod@4.4.3/node_modules/zod"),
+      "lucide-react": sourcePath(
+        "../../../../node_modules/.pnpm/lucide-react@0.468.0_react@19.2.7/node_modules/lucide-react",
+      ),
+      "@zaip-ai/dashboard-contracts": sourcePath("../../packages/contracts/src/index.ts"),
+      "@zaip-ai/dashboard-ui": sourcePath("../../packages/ui/src/index.ts"),
+      "@zaip-ai/dashboard-operations/contracts": sourcePath(
+        "../../modules/operations/src/contracts.ts",
+      ),
+      "@zaip-ai/dashboard-operations/react": sourcePath(
+        "../../modules/operations/src/react/index.ts",
+      ),
+      "@zaip-ai/dashboard-cost-monitor/contracts": sourcePath(
+        "../../modules/cost-monitor/src/contracts.ts",
+      ),
+      "@zaip-ai/dashboard-cost-monitor/react": sourcePath(
+        "../../modules/cost-monitor/src/react/index.ts",
+      ),
+      "@zaip-ai/dashboard-traceability/contracts": sourcePath(
+        "../../modules/traceability/src/contracts.ts",
+      ),
+      "@zaip-ai/dashboard-traceability/react": sourcePath(
+        "../../modules/traceability/src/react/index.ts",
+      ),
+    },
+  },
   publicDir: "public",
   server: {
     host: "127.0.0.1",
-    port: 5173,
+    port: 5273,
     strictPort: true,
     proxy: {
       "/api": {
-        target: `http://127.0.0.1:${Number.isFinite(apiPort) ? apiPort : 4317}`,
+        target: `http://127.0.0.1:${Number.isFinite(apiPort) ? apiPort : 4417}`,
         changeOrigin: false,
       },
     },
   },
-  build: { outDir: "dist" },
+  build: {
+    outDir: "dist",
+    rollupOptions: {
+      output: {
+        manualChunks(id) {
+          const normalized = id.replaceAll("\\", "/");
+          if (normalized.includes("/modules/cost-monitor/")) return "cost-monitor";
+          if (normalized.includes("/modules/operations/")) return "operations";
+          if (normalized.includes("/modules/traceability/")) return "traceability";
+          if (
+            id.includes("node_modules/.pnpm/react@") ||
+            id.includes("node_modules/.pnpm/react-dom@")
+          )
+            return "react-vendor";
+          if (id.includes("node_modules/.pnpm/lucide-react@")) return "icons-vendor";
+          return undefined;
+        },
+      },
+    },
+  },
 });

package/templates/.agents/dashboard/modules/cost-monitor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zaip-ai/dashboard-cost-monitor",
-  "version": "1.0.0",
+  "version": "1.3.0",
   "private": true,
   "type": "module",
   "exports": {

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

@@ -29,8 +29,9 @@ export function sumKnown(values: readonly (number | null)[]): number | null {
 
 /**
  * Chooses the duration population independently from financial aggregation.
- * Canonical effort views align with Operations: every distinct invocation,
- * including conversation, planning, execution, roots, and Sub-Runs, contributes.
+ * Cost duration is an invocation metric: every distinct Run contributes,
+ * including conversation, planning, execution, roots, and Sub-Runs. This is
+ * deliberately different from Operations, which reports root execution time.
  */
 export function durationAggregationRows<
   T extends Pick<CostRunRow, "run_id" | "phase" | "parent_run_id">,
@@ -57,6 +58,8 @@ export function durationAggregationRows<
 
 export interface CostRunRow {
   run_id: string;
+  /** Lifecycle Execution that owns this Run, retained for the Executions tab period filter. */
+  execution_id: string | null;
   conversation_id: string;
   task_id: string | null;
   task_title: string;
@@ -93,7 +96,8 @@ export interface CostRunRow {
   source_started_at?: string | null;
   source_finished_at?: string | null;
   capture_lag_ms?: number | null;
-  event_count: number;
+  /** Source-event cardinality is unavailable when SQLite did not record it. */
+  event_count: number | null;
   input_tokens: number | null;
   cached_input_tokens: number | null;
   output_tokens: number | null;
@@ -129,12 +133,16 @@ export interface CostGroupRow {
   label: string;
   latest_started_at: string;
   run_count: number;
-  task_count: number;
+  /** Null when a paged source does not provide a factual task attribution. */
+  task_count: number | null;
   /** Canonical export fields; task_count remains the active-task alias. */
   tasksCreated?: number;
-  tasksActive?: number;
+  tasksActive?: number | null;
   /** Sum-safe active Task count across period rows (task-days). */
-  taskDaysActive?: number;
+  taskDaysActive?: number | null;
+  /** Stable ZAIP identity details for the Agent aggregation only. */
+  persona?: string | null;
+  job?: string | null;
   prd_count: number;
   spec_count: number;
   evidence_count: number;
@@ -146,6 +154,28 @@ export interface CostGroupRow {
   duration_ms: number | null;
   duration: DurationCoverage;
   coverage: CostCoverage;
+  /** Exact observed event cardinality; ratios without a population stay null. */
+  coverage_counts?: {
+    source: "run_rows" | "period_summary";
+    granularity: "event" | "unavailable";
+    events: number | null;
+    tokens: number | null;
+    usd: number | null;
+    brl: number | null;
+    metrics?: {
+      /** Root execution Run population used by observed wall-clock duration. */
+      duration?: CoverageRunPopulation;
+      tokens: CoverageRunPopulation;
+      usd: CoverageRunPopulation;
+      brl: CoverageRunPopulation;
+    };
+  };
+}
+
+export interface CoverageRunPopulation {
+  eligible_runs: number;
+  known_runs: number;
+  unknown_runs: number;
 }
 
 export function aggregateDurationCoverage(
@@ -166,6 +196,12 @@ export function aggregateDurationCoverage(
 }
 
 export interface CostMonitorProjection extends ReadonlyV2Projection {
+  /** Present only on the incremental Runs endpoint; aggregates remain complete. */
+  run_page?: { offset: number; limit: number; total: number | null; has_more: boolean };
+  aggregate_only?: boolean;
+  /** Incremental Run transport; aggregate fields are intentionally unavailable. */
+  page_only?: boolean;
+  data_source?: "lifecycle_manifest_summary" | "run_records";
   /** Aggregate-only baseline, eligible exclusively for global unfiltered period views. */
   legacy_effort_baseline?: { cutoff: string; duration_ms: number } | null;
   currency: "BRL" | "USD";
@@ -209,6 +245,11 @@ export interface CostMonitorProjection extends ReadonlyV2Projection {
   specs: MacroProjection[];
   runs: CostRunRow[];
   groups: {
+    /**
+     * Summary responses intentionally leave these high-cardinality dimensions
+     * empty. Their compact lifecycle endpoints own the paged transport when
+     * the corresponding Cost Monitor tab is opened.
+     */
     conversations: CostGroupRow[];
     tasks: CostGroupRow[];
     providers: CostGroupRow[];

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

@@ -0,0 +1,13 @@
+/**
+ * Auditable fallback for a tokenized Run whose processing duration was not
+ * captured.  It is deliberately a presentation estimate, never source
+ * telemetry: observed/reconciled values always win and tokens/cost are not
+ * changed.  Four million tokens per hour is the fixed v1 budget rate.
+ */
+export const TOKEN_DURATION_ESTIMATE_BASIS = "token_budget_v1:4_000_000_tokens_per_hour";
+const TOKENS_PER_HOUR = 4_000_000;
+
+export function estimatedDurationMs(totalTokens: number | null | undefined): number | null {
+  if (typeof totalTokens !== "number" || totalTokens <= 0) return null;
+  return Math.round((totalTokens * 3_600_000) / TOKENS_PER_HOUR);
+}

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

@@ -0,0 +1,134 @@
+import { describe, expect, it } from "vitest";
+import { CompactLifecycleCostTable } from "./CompactLifecycleCostTable.js";
+
+const known = (known_sum: number) => ({ known_sum, unknown: 0, complete: true, coverage_ratio: 1 });
+const unavailable = { known_sum: 0, unknown: 1, complete: false, coverage_ratio: 0 };
+
+describe("CompactLifecycleCostTable filtered subtotal", () => {
+  it("renders the server subtotal as the final DataTable row with all metrics", () => {
+    const view = CompactLifecycleCostTable({
+      locale: "pt-BR",
+      rows: [
+        {
+          id: "TASK-PAGE-50",
+          title: "Página 2",
+          kind: "task",
+          status: "active",
+          risk: null,
+          occurred_at: "2026-08-04T12:00:00.000Z",
+          parent_id: null,
+          run_count: 1,
+          cost_currency: "BRL",
+          metrics: { duration: known(1_000), total_tokens: known(2), cost: known(5) },
+        },
+      ],
+      subtotal: {
+        entity_count: 270,
+        run_count: known(270),
+        metrics: {
+          duration: known(270_000),
+          total_tokens: known(540),
+          cost_brl: known(1_350),
+          cost_usd: known(270),
+        },
+      },
+      pagination: {
+        offset: 50,
+        limit: 50,
+        total: 270,
+        has_more: true,
+        loading: false,
+        error: null,
+        onChange: () => undefined,
+        onRetry: () => undefined,
+      },
+    });
+    const [table] = view.props.children as readonly {
+      props: { columns: Array<{ key: string; footer?: unknown }> };
+    }[];
+    expect(table).toBeDefined();
+    const footer = (key: string) =>
+      table!.props.columns.find((column) => column.key === key)?.footer;
+    expect(footer("occurredAt")).toContain("Subtotal filtrado");
+    expect(footer("entity")).toBe("270");
+    expect(footer("runs")).toBe("270");
+    expect(footer("duration")).toBe("5 min");
+    expect(footer("tokens")).toBe("540");
+    expect(footer("cost")).toContain("R$");
+    expect(footer("cost")).not.toContain("US$");
+  });
+
+  it("renders unknown numeric subtotals as zero", () => {
+    const view = CompactLifecycleCostTable({
+      locale: "pt-BR",
+      rows: [],
+      subtotal: {
+        entity_count: 0,
+        run_count: known(0),
+        metrics: {
+          duration: unavailable,
+          total_tokens: known(0),
+          cost_brl: known(0),
+          cost_usd: unavailable,
+        },
+      },
+      pagination: {
+        offset: 0,
+        limit: 50,
+        total: 0,
+        has_more: false,
+        loading: false,
+        error: null,
+        onChange: () => undefined,
+        onRetry: () => undefined,
+      },
+    });
+    const [table] = view.props.children as readonly {
+      props: { columns: Array<{ key: string; footer?: unknown }> };
+    }[];
+    expect(table).toBeDefined();
+    const footer = (key: string) =>
+      table!.props.columns.find((column) => column.key === key)?.footer;
+    expect(footer("runs")).toBe("0");
+    expect(footer("tokens")).toBe("0");
+    expect(footer("duration")).toBe("0");
+  });
+
+  it("does not render a subtotal row when all lifecycle metrics are unavailable", () => {
+    const view = CompactLifecycleCostTable({
+      locale: "pt-BR",
+      rows: [],
+      subtotal: {
+        entity_count: 1,
+        run_count: unavailable,
+        metrics: {
+          duration: unavailable,
+          total_tokens: unavailable,
+          cost_brl: unavailable,
+          cost_usd: unavailable,
+        },
+      },
+      pagination: {
+        offset: 0,
+        limit: 50,
+        total: 0,
+        has_more: false,
+        loading: false,
+        error: null,
+        onChange: () => undefined,
+        onRetry: () => undefined,
+      },
+    });
+    const [table] = view.props.children as readonly {
+      props: { columns: Array<{ key: string; footer?: unknown }> };
+    }[];
+    const footer = (key: string) =>
+      table!.props.columns.find((column) => column.key === key)?.footer;
+    expect(footer("occurredAt")).toBeUndefined();
+    expect(footer("entity")).toBeUndefined();
+    expect(footer("runs")).toBeUndefined();
+    expect(footer("duration")).toBeUndefined();
+    expect(footer("tokens")).toBeUndefined();
+    expect(footer("cost")).toBeUndefined();
+  });
+});