@zaip-ai/cli 1.0.7 → 1.3.0

package/templates/.agents/dashboard/apps/frontend/src/dashboard-api.ts

@@ -1,6 +1,9 @@
 import { type ApiErrorPayload, dashboardApiPaths } from "@zaip-ai/dashboard-contracts";
 import type { CostMonitorProjection } from "@zaip-ai/dashboard-cost-monitor/contracts";
 import type {
+  ChangeProjection,
+  DashboardTaskProjection,
+  MacroProjection,
   OperationsProjection,
   PrdDetailProjection,
   SpecDetailProjection,
@@ -12,6 +15,195 @@ export interface ReconciliationBlockedItem {
   id: string;
   reason: string | null;
 }
+export type SqliteViewName =
+  | "cost_monitor_daily"
+  | "cost_monitor_monthly"
+  | "cost_monitor_annual"
+  | "cost_monitor_overview_view"
+  | "cost_monitor_executions"
+  | "cost_monitor_agent_invocations"
+  | "cost_monitor_zaip_agents"
+  | "cost_monitor_models"
+  | "cost_monitor_providers"
+  | "cost_monitor_tasks"
+  | "cost_monitor_specs"
+  | "cost_monitor_prds"
+  | "cost_monitor_conversations"
+  | "operations_work_list"
+  | "operations_work_kanban"
+  | "operations_executions"
+  | "operations_agent_invocations"
+  | "operations_conversations"
+  | "operations_decisions"
+  | "operations_changes"
+  | "operations_daily"
+  | "operations_monthly"
+  | "operations_annual"
+  | "first_fold_overview"
+  | "first_fold_task_status"
+  | "first_fold_task_risk"
+  | "first_fold_top_tasks"
+  | "first_fold_task"
+  | "first_fold_spec"
+  | "first_fold_prd";
+export interface SqliteViewPage {
+  data_source: "sqlite_read_model";
+  view: SqliteViewName;
+  offset: number;
+  limit: number;
+  total_count: number;
+  has_more: boolean;
+  totals?: Record<string, unknown>;
+  rows: Array<Record<string, unknown>>;
+}
+
+export type OperationsScope = "quick" | "overview" | "detail";
+export type WorkBoardStage =
+  | "definition"
+  | "planning"
+  | "ready"
+  | "executing"
+  | "verifying"
+  | "completed"
+  | "blocked"
+  | "cancelled"
+  | "failed";
+
+export interface OperationsBoardPage {
+  stage: WorkBoardStage;
+  offset: number;
+  total: number;
+  totals_by_kind: {
+    all: number;
+    task: number;
+    "standalone-task": number;
+    prd: number;
+    spec: number;
+  };
+  prds: MacroProjection[];
+  specs: MacroProjection[];
+  tasks: DashboardTaskProjection[];
+  changes: ChangeProjection[];
+  overview_metrics?: OperationsProjection["summary"]["overview_metrics"];
+}
+
+export type OperationsEntityPageKind = "runs" | "conversations" | "executions";
+export interface OperationsPageFilters {
+  query: string;
+  status: string;
+  risk: string;
+  origin?: string;
+  kind?: string;
+}
+export interface OperationsEntityPage {
+  kind: OperationsEntityPageKind;
+  offset: number;
+  limit: number;
+  total: number;
+  aggregation?: "canonical_entity" | "page_partial";
+  aggregate_complete?: boolean;
+  rows: Array<{
+    id: string;
+    started_at: string;
+    finished_at: string | null;
+    task_id: string | null;
+    execution_id: string | null;
+    conversation_id: string | null;
+    parent_run_id: string | null;
+    run_kind: "run" | "subrun" | null;
+    run_purpose?: string | null;
+    phase: string | null;
+    status: string | null;
+    agent?: string | null;
+    agent_persona?: string | null;
+    agent_job?: string | null;
+    client?: string | null;
+    provider?: string | null;
+    model?: string | null;
+    reasoning_effort?: string | null;
+    service_tier?: string | null;
+    duration_ms: number | null;
+    source_duration_ms?: number | null;
+    duration_provenance?: string | null;
+    lifecycle_elapsed_ms?: number | null;
+    llm_call_count?: number | null;
+    input_tokens?: number | null;
+    cached_input_tokens?: number | null;
+    uncached_input_tokens?: number | null;
+    output_tokens?: number | null;
+    reasoning_tokens?: number | null;
+    visible_output_tokens?: number | null;
+    total_tokens: number | null;
+    input_rate_usd_per_million?: number | null;
+    cached_input_rate_usd_per_million?: number | null;
+    output_rate_usd_per_million?: number | null;
+    reasoning_rate_usd_per_million?: number | null;
+    context_input_multiplier?: number | null;
+    context_output_multiplier?: number | null;
+    speed_cost_multiplier?: number | null;
+    pricing_scenario?: string | null;
+    standard_cost_usd?: number | null;
+    speed_uplift_usd?: number | null;
+    input_cost_usd?: number | null;
+    cached_input_cost_usd?: number | null;
+    output_cost_usd?: number | null;
+    reasoning_cost_usd?: number | null;
+    calculated_cost_usd?: number | null;
+    recorded_cost_usd?: number | null;
+    cost_variance_usd?: number | null;
+    cost_usd?: number | null;
+    fx_rate?: number | null;
+    pricing_segment_count?: number | null;
+    pricing_mixed?: boolean;
+    pricing_model?: string | null;
+    pricing_source?: string | null;
+    cost: number | null;
+    currency: string | null;
+  }>;
+}
+
+export type OperationsLifecyclePageKind = "changes" | "decisions";
+export interface OperationsLifecyclePage {
+  kind: OperationsLifecyclePageKind;
+  offset: number;
+  limit: number;
+  total: number;
+  rows: ChangeProjection[] | import("@zaip-ai/dashboard-operations/contracts").DecisionProjection[];
+}
+
+export type OperationsReadModelKind = "tasks" | "specs" | "prds" | "executions" | "conversations";
+export interface OperationsReadModelPage {
+  data_source: "lifecycle_daily_read_models";
+  snapshot_id: string | null;
+  source_latest_at: string | null;
+  kind: OperationsReadModelKind;
+  offset: number;
+  limit: number;
+  total: number;
+  has_more: boolean;
+  next_cursor: string | null;
+  rows: Array<{
+    id: string;
+    title: string;
+    kind: "task" | "spec" | "prd" | "execution" | "conversation";
+    status: string | null;
+    risk: string | null;
+    occurred_at: string;
+    parent_id: string | null;
+    run_count: number;
+    cost_currency: string | null;
+    metrics: {
+      duration: { known_sum: number; unknown: number; complete: boolean; coverage_ratio: number };
+      total_tokens: {
+        known_sum: number;
+        unknown: number;
+        complete: boolean;
+        coverage_ratio: number;
+      };
+      cost: { known_sum: number; unknown: number; complete: boolean; coverage_ratio: number };
+    };
+  }>;
+}
 
 export interface ReconciliationResult {
   reconciled_ids: string[];
@@ -19,24 +211,194 @@ export interface ReconciliationResult {
   not_reconciled: ReconciliationBlockedItem[];
 }
 
+export interface CostMonitorFilters {
+  provider?: string | undefined;
+  phase?: string | undefined;
+  agent?: string | undefined;
+  model?: string | undefined;
+  status?: string | undefined;
+}
+
 export class DashboardApiClient {
   constructor(private readonly token: string) {}
 
+  ready(): Promise<{ snapshot_state?: "current" | "updating" }> {
+    return this.get("/api/v2/ready");
+  }
+
   operations(
     period?: { from: string | null; to: string | null },
-    overviewOnly = false,
+    scope: OperationsScope = "detail",
+    signal?: AbortSignal,
+    fresh = false,
   ): Promise<OperationsProjection> {
-    const path = overviewOnly
-      ? `${dashboardApiPaths.operations}?scope=overview`
-      : dashboardApiPaths.operations;
-    return this.get(withPeriod(path, period));
+    const path = `${dashboardApiPaths.operations}?scope=${scope}${fresh ? "&fresh=1" : ""}`;
+    return this.get(withPeriod(path, period), signal);
+  }
+
+  sqliteViewPage(
+    view: SqliteViewName,
+    period?: { from: string | null; to: string | null },
+    options: {
+      offset?: number;
+      limit?: number;
+      query?: string;
+      status?: string;
+      risk?: string;
+      provider?: string;
+      model?: string;
+      agent?: string;
+      phase?: string;
+      origin?: string;
+      workType?: string;
+      priority?: string;
+    } = {},
+    signal?: AbortSignal,
+  ): Promise<SqliteViewPage> {
+    const query = new URLSearchParams({ view, offset: String(options.offset ?? 0) });
+    if (options.limit !== undefined) query.set("limit", String(options.limit));
+    if (options.query) query.set("query", options.query);
+    if (options.status) query.set("status", options.status);
+    if (options.risk) query.set("risk", options.risk);
+    if (options.provider) query.set("provider", options.provider);
+    if (options.model) query.set("model", options.model);
+    if (options.agent) query.set("agent", options.agent);
+    if (options.phase) query.set("phase", options.phase);
+    if (options.origin) query.set("origin", options.origin);
+    if (options.workType) query.set("workType", options.workType);
+    if (options.priority) query.set("priority", options.priority);
+    return this.get(withPeriod(`/api/v2/sqlite-views?${query.toString()}`, period), signal);
+  }
+
+  operationsBoard(
+    period: { from: string | null; to: string | null } | undefined,
+    stage: WorkBoardStage,
+    offset = 0,
+    filters?: Partial<OperationsPageFilters>,
+    signal?: AbortSignal,
+    limit = 4,
+  ): Promise<OperationsBoardPage> {
+    const params = new URLSearchParams({
+      scope: "board",
+      stage,
+      offset: String(offset),
+      limit: String(limit),
+    });
+    if (filters?.query) params.set("query", filters.query);
+    if (filters?.status) params.set("status", filters.status);
+    if (filters?.risk) params.set("risk", filters.risk);
+    if (filters?.origin) params.set("origin", filters.origin);
+    if (filters?.kind) params.set("kind", filters.kind);
+    return this.get(
+      withPeriod(`${dashboardApiPaths.operations}?${params.toString()}`, period),
+      signal,
+    );
+  }
+
+  operationsClassification(
+    period: { from: string | null; to: string | null } | undefined,
+    kind: "task" | "spec" | "prd",
+    classification: "lite" | "standard" | "critical" | "empty" | "structured" | "rework",
+    offset = 0,
+    signal?: AbortSignal,
+    limit = 50,
+  ): Promise<OperationsBoardPage> {
+    const params = new URLSearchParams({
+      scope: "classification",
+      kind,
+      classification,
+      offset: String(offset),
+      limit: String(limit),
+    });
+    return this.get(
+      withPeriod(`${dashboardApiPaths.operations}?${params.toString()}`, period),
+      signal,
+    );
+  }
+
+  operationsEntityPage(
+    period: { from: string | null; to: string | null } | undefined,
+    kind: OperationsEntityPageKind,
+    offset = 0,
+    filters?: Partial<OperationsPageFilters>,
+    signal?: AbortSignal,
+  ): Promise<OperationsEntityPage> {
+    const params = operationsPageParams(kind, offset, filters);
+    return this.get(withPeriod(`${dashboardApiPaths.operations}/runs?${params}`, period), signal);
+  }
+
+  operationsLifecyclePage(
+    period: { from: string | null; to: string | null } | undefined,
+    kind: OperationsLifecyclePageKind,
+    offset = 0,
+    filters?: Partial<OperationsPageFilters>,
+    signal?: AbortSignal,
+  ): Promise<OperationsLifecyclePage> {
+    const params = operationsPageParams(kind, offset, filters);
+    return this.get(
+      withPeriod(`${dashboardApiPaths.operations}/entities?${params}`, period),
+      signal,
+    );
+  }
+
+  operationsReadModelPage(
+    period: { from: string | null; to: string | null } | undefined,
+    kind: OperationsReadModelKind,
+    offset = 0,
+    limit = 50,
+    query = "",
+    signal?: AbortSignal,
+  ): Promise<OperationsReadModelPage> {
+    const params = new URLSearchParams({ kind, offset: String(offset), limit: String(limit) });
+    if (query) params.set("query", query);
+    return this.get(
+      withPeriod(`${dashboardApiPaths.operations}/read-models?${params.toString()}`, period),
+      signal,
+    );
   }
 
   costMonitor(
     currency: "BRL" | "USD" = "BRL",
     period?: { from: string | null; to: string | null },
+    scope: "summary" | "detail" = "detail",
+    signal?: AbortSignal,
+    filters?: CostMonitorFilters,
+    fresh = false,
   ): Promise<CostMonitorProjection> {
-    return this.get(withPeriod(`${dashboardApiPaths.costMonitor}?currency=${currency}`, period));
+    const query = new URLSearchParams({ currency, scope });
+    if (fresh) query.set("fresh", "1");
+    for (const [key, value] of Object.entries(filters ?? {})) {
+      if (!value) continue;
+      query.set(key, value);
+    }
+    return this.get(
+      withPeriod(`${dashboardApiPaths.costMonitor}?${query.toString()}`, period),
+      signal,
+    );
+  }
+
+  costMonitorRuns(
+    currency: "BRL" | "USD" = "BRL",
+    period: { from: string | null; to: string | null } | undefined,
+    offset: number,
+    limit = 100,
+    signal?: AbortSignal,
+    filters?: CostMonitorFilters,
+  ): Promise<CostMonitorProjection> {
+    const query = new URLSearchParams({
+      currency,
+      scope: "runs",
+      offset: String(offset),
+      limit: String(limit),
+    });
+    for (const [key, value] of Object.entries(filters ?? {})) {
+      if (!value) continue;
+      query.set(key, value);
+    }
+    return this.get(
+      withPeriod(`${dashboardApiPaths.costMonitor}?${query.toString()}`, period),
+      signal,
+    );
   }
 
   snapshot(
@@ -67,6 +429,21 @@ export class DashboardApiClient {
     );
   }
 
+  refreshProjection(
+    currency: "BRL" | "USD" = "BRL",
+    period?: { from: string | null; to: string | null },
+  ): Promise<{
+    operations: OperationsProjection;
+    costs: CostMonitorProjection;
+    dashboard?: { title: string; repository_name: string };
+    projection: { source_latest_at: string | null; served_at: string };
+  }> {
+    return this.post(
+      withPeriod(`${dashboardApiPaths.refreshProjection}?currency=${currency}`, period),
+      reconciliationRequestTimeoutMs,
+    );
+  }
+
   task(taskId: string): Promise<TaskDetailProjection> {
     return this.get(dashboardApiPaths.task(taskId));
   }
@@ -113,6 +490,20 @@ export class DashboardApiClient {
     return this.get(dashboardApiPaths.projectSettings);
   }
 
+  projectOverview(): Promise<ProjectOverview> {
+    return this.get(`${dashboardApiPaths.projectSettings}/overview`);
+  }
+
+  async saveWorkPriority(itemIds: readonly string[]): Promise<{ item_ids: string[] }> {
+    const response = await fetch(dashboardApiPaths.workPriority, {
+      method: "PUT",
+      headers: { "content-type": "application/json", "x-zaip-session": this.token },
+      body: JSON.stringify({ item_ids: itemIds }),
+    });
+    if (!response.ok) throw new Error(`Work priority update failed with HTTP ${response.status}`);
+    return (await response.json()) as { item_ids: string[] };
+  }
+
   async saveProjectSettings(config: ProjectConfigSettings): Promise<ProjectConfigSettings> {
     const response = await fetch(dashboardApiPaths.projectSettings, {
       method: "PUT",
@@ -152,11 +543,16 @@ export class DashboardApiClient {
     return (await response.json()) as FxRate;
   }
 
-  private async get<Response>(path: string): Promise<Response> {
-    const response = await fetchWithTimeout(path, {
-      cache: "no-store",
-      headers: { "x-zaip-session": this.token },
-    });
+  private async get<Response>(path: string, signal?: AbortSignal): Promise<Response> {
+    const response = await fetchWithTimeout(
+      path,
+      {
+        cache: "no-cache",
+        headers: { "x-zaip-session": this.token },
+      },
+      dashboardRequestTimeoutMs,
+      signal,
+    );
     if (!response.ok) {
       const payload = (await response.json().catch(() => null)) as ApiErrorPayload | null;
       throw new Error(payload?.error ?? `Dashboard API failed with HTTP ${response.status}`);
@@ -184,7 +580,19 @@ export class DashboardApiClient {
   }
 }
 
-export const dashboardRequestTimeoutMs = 30_000;
+function operationsPageParams(
+  kind: OperationsEntityPageKind | OperationsLifecyclePageKind,
+  offset: number,
+  filters?: Partial<OperationsPageFilters>,
+): string {
+  const params = new URLSearchParams({ kind, offset: String(offset), limit: "100" });
+  if (filters?.query) params.set("query", filters.query);
+  if (filters?.status) params.set("status", filters.status);
+  if (filters?.risk) params.set("risk", filters.risk);
+  return params.toString();
+}
+
+export const dashboardRequestTimeoutMs = 60_000;
 // The local runtime permits reconciliation for up to two minutes. Keep a small
 // transport margin so the browser never cancels a valid server-side operation.
 export const reconciliationRequestTimeoutMs = 125_000;
@@ -193,8 +601,12 @@ export async function fetchWithTimeout(
   path: string,
   init: RequestInit,
   timeoutMs = dashboardRequestTimeoutMs,
+  externalSignal?: AbortSignal,
 ): Promise<Response> {
   const controller = new AbortController();
+  const abort = () => controller.abort();
+  externalSignal?.addEventListener("abort", abort, { once: true });
+  if (externalSignal?.aborted) controller.abort();
   const timeout = window.setTimeout(() => controller.abort(), timeoutMs);
   try {
     return await fetch(path, { ...init, signal: controller.signal });
@@ -207,6 +619,7 @@ export async function fetchWithTimeout(
     throw cause;
   } finally {
     window.clearTimeout(timeout);
+    externalSignal?.removeEventListener("abort", abort);
   }
 }
 
@@ -307,7 +720,7 @@ export interface ProjectConfigSettings {
     timezone: string;
   };
   stack: {
-    profile: string;
+    id: string;
     overrides: Record<string, unknown>;
   };
   clients: {
@@ -372,3 +785,30 @@ export interface ProjectConfigSettings {
       }
     | undefined;
 }
+
+export interface ProjectOverview {
+  framework_version: string | null;
+  metrics: Array<{
+    id: "agents" | "squads" | "skills" | "rules" | "hooks" | "database";
+    label: string;
+    value: number | string;
+  }>;
+  stack_components: Array<{
+    name: string;
+    version: string | null;
+    source: string | null;
+    verification: "exact" | "constraint" | "unavailable";
+  }>;
+  areas: Array<{
+    id:
+      | "brandbook"
+      | "design_system"
+      | "software_architecture"
+      | "growth_strategy"
+      | "marketing_strategy"
+      | "sales_playbook";
+    label: string;
+    artifact: string;
+    available: boolean;
+  }>;
+}

package/templates/.agents/dashboard/apps/frontend/src/dashboard-localization.ts

@@ -102,7 +102,7 @@ Use a Task for a small, independent delivery with a clear result.
 Use a SPEC when delivery requires multiple Tasks or dependency ordering.
 
 1. Turn the desired result into verifiable capabilities.
-2. Resolve the project stack from \`stack.profile\` and \`stack.overrides\`.
+2. Resolve the project stack from \`stack.id\` and \`stack.overrides\`.
 3. Record the stack profile, overrides, concise description, exact versions, and workspace-verifiable sources.
 4. Split delivery into small Tasks with their own acceptance.
 5. Model dependencies as a DAG and avoid artificial sequences.

package/templates/.agents/dashboard/apps/frontend/src/main.tsx

@@ -3,6 +3,7 @@ import { createRoot } from "react-dom/client";
 import { App } from "./App.js";
 import "./styles.css";
 import "./pricing-settings-dialog.css";
+import "./cost-calculation-guide.css";
 
 const root = document.getElementById("root");
 

package/templates/.agents/dashboard/apps/frontend/src/operations-detail-hydration.test.ts

@@ -0,0 +1,55 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  operationsDetailStartDelayMs,
+  scheduleOperationsDetail,
+  shouldHydrateOperationsDetails,
+} from "./operations-detail-hydration.js";
+
+const timerTarget = {
+  setTimeout: (callback: () => void, delay?: number) =>
+    globalThis.setTimeout(callback, delay) as unknown as number,
+  clearTimeout: (handle: number) => globalThis.clearTimeout(handle),
+};
+
+describe("scheduleOperationsDetail", () => {
+  afterEach(() => vi.useRealTimers());
+
+  it("starts on the next task without waiting for browser idle time", async () => {
+    vi.useFakeTimers();
+    const work = vi.fn(async () => undefined);
+    scheduleOperationsDetail(work, timerTarget);
+    expect(work).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(operationsDetailStartDelayMs);
+    expect(work).toHaveBeenCalledTimes(1);
+  });
+
+  it("cancels pending or active detail on a period change or unmount", async () => {
+    vi.useFakeTimers();
+    let captured: AbortSignal | undefined;
+    const cancel = scheduleOperationsDetail(async (signal) => {
+      captured = signal;
+    }, timerTarget);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(captured?.aborted).toBe(false);
+    cancel();
+    expect(captured?.aborted).toBe(true);
+  });
+
+  it("does not start work cancelled before the next task", async () => {
+    vi.useFakeTimers();
+    const work = vi.fn(async () => undefined);
+    const cancel = scheduleOperationsDetail(work, timerTarget);
+    cancel();
+    await vi.advanceTimersByTimeAsync(operationsDetailStartDelayMs);
+    expect(work).not.toHaveBeenCalled();
+  });
+});
+
+describe("shouldHydrateOperationsDetails", () => {
+  it("does not hydrate detail on the initial or Operations overview", () => {
+    expect(shouldHydrateOperationsDetails(null, true)).toBe(false);
+    expect(shouldHydrateOperationsDetails("operations", true)).toBe(false);
+    expect(shouldHydrateOperationsDetails("operations", false)).toBe(false);
+    expect(shouldHydrateOperationsDetails("cost-monitor", true)).toBe(false);
+  });
+});

package/templates/.agents/dashboard/apps/frontend/src/operations-detail-hydration.ts

@@ -0,0 +1,36 @@
+export const operationsDetailStartDelayMs = 0;
+
+export function shouldHydrateOperationsDetails(
+  view: "operations" | "cost-monitor" | "traceability" | null,
+  overviewIsPartial: boolean,
+): boolean {
+  // Overview and board are deliberately page-first. Detail is requested by
+  // detail-dependent Operations views or Traceability, never by first paint.
+  void view;
+  void overviewIsPartial;
+  return false;
+}
+
+type TimerWindow = Pick<Window, "setTimeout" | "clearTimeout">;
+
+export function scheduleOperationsDetail(
+  work: (signal: AbortSignal) => Promise<void>,
+  target: TimerWindow = window,
+  delayMs = operationsDetailStartDelayMs,
+): () => void {
+  let cancelled = false;
+  let started = false;
+  const controller = new AbortController();
+  const start = () => {
+    if (cancelled || started) return;
+    started = true;
+    void work(controller.signal);
+  };
+  const handle = target.setTimeout(start, delayMs);
+  return () => {
+    if (cancelled) return;
+    cancelled = true;
+    controller.abort();
+    target.clearTimeout(handle);
+  };
+}