@zaip-ai/cli 1.0.7 → 1.3.0

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

@@ -0,0 +1,175 @@
+import type { CostCurrency, CostLocale } from "@zaip-ai/dashboard-cost-monitor/react";
+import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
+import {
+  type Dispatch,
+  type MutableRefObject,
+  type SetStateAction,
+  useEffect,
+  useRef,
+} from "react";
+import { pricingSetupPath, projectSetupPath } from "./AppSetupRoutes.js";
+import { currencyKey, localeKey } from "./app-preferences.js";
+import type { DashboardView } from "./DashboardCapabilityNav.js";
+import type { DashboardApiClient, PricingCatalog } from "./dashboard-api.js";
+import {
+  scheduleOperationsDetail,
+  shouldHydrateOperationsDetails,
+} from "./operations-detail-hydration.js";
+
+export const projectionRefreshDebounceMs = 5_000;
+
+export function shouldRefreshVisibleProjection({
+  inFlight,
+  lastRefreshAt,
+  now,
+  visibilityState,
+}: {
+  inFlight: boolean;
+  lastRefreshAt: number;
+  now: number;
+  visibilityState: DocumentVisibilityState;
+}): boolean {
+  return (
+    visibilityState === "visible" && !inFlight && now - lastRefreshAt >= projectionRefreshDebounceMs
+  );
+}
+
+export function useAppEffects({
+  api,
+  costLocale,
+  currency,
+  dashboardView,
+  loadOperationsDetails,
+  operations,
+  operationsDetailAbortRef,
+  operationsDetailCancelRef,
+  operationsPageAbortRef,
+  pathname,
+  pricing,
+  refresh,
+  refreshVersion,
+  setError,
+  setFxRate,
+  setPathname,
+  setPricing,
+}: {
+  api: DashboardApiClient;
+  costLocale: CostLocale;
+  currency: CostCurrency;
+  dashboardView: DashboardView | null;
+  loadOperationsDetails: (signal?: AbortSignal) => Promise<OperationsProjection | null>;
+  operations: OperationsProjection | null;
+  operationsDetailAbortRef: MutableRefObject<AbortController | null>;
+  operationsDetailCancelRef: MutableRefObject<(() => void) | null>;
+  operationsPageAbortRef: MutableRefObject<AbortController | null>;
+  pathname: string;
+  pricing: PricingCatalog | null;
+  refresh: (
+    visible?: boolean,
+    reconcileOpenWork?: boolean,
+    refreshProjection?: boolean,
+  ) => Promise<void>;
+  refreshVersion: MutableRefObject<number>;
+  setError: Dispatch<SetStateAction<string | null>>;
+  setFxRate: Dispatch<SetStateAction<Awaited<ReturnType<DashboardApiClient["fxRate"]>> | null>>;
+  setPathname: Dispatch<SetStateAction<string>>;
+  setPricing: Dispatch<SetStateAction<PricingCatalog | null>>;
+}) {
+  const projectionRefreshInFlight = useRef(false);
+  const lastProjectionRefreshAt = useRef(0);
+  useEffect(() => {
+    void refresh();
+    return () => {
+      operationsDetailCancelRef.current?.();
+      operationsDetailCancelRef.current = null;
+      operationsDetailAbortRef.current?.abort();
+      operationsDetailAbortRef.current = null;
+      operationsPageAbortRef.current?.abort();
+      operationsPageAbortRef.current = null;
+      ++refreshVersion.current;
+    };
+  }, [
+    operationsDetailAbortRef,
+    operationsDetailCancelRef,
+    operationsPageAbortRef,
+    refresh,
+    refreshVersion,
+  ]);
+
+  useEffect(() => {
+    const refreshVisibleProjection = () => {
+      const now = Date.now();
+      // Focus and visibilitychange commonly arrive together. Coalesce them
+      // rather than polling or rebuilding during ordinary navigation.
+      if (
+        !shouldRefreshVisibleProjection({
+          inFlight: projectionRefreshInFlight.current,
+          lastRefreshAt: lastProjectionRefreshAt.current,
+          now,
+          visibilityState: document.visibilityState,
+        })
+      )
+        return;
+      lastProjectionRefreshAt.current = now;
+      projectionRefreshInFlight.current = true;
+      void refresh(false, false, true).finally(() => {
+        projectionRefreshInFlight.current = false;
+      });
+    };
+    window.addEventListener("focus", refreshVisibleProjection);
+    document.addEventListener("visibilitychange", refreshVisibleProjection);
+    return () => {
+      window.removeEventListener("focus", refreshVisibleProjection);
+      document.removeEventListener("visibilitychange", refreshVisibleProjection);
+    };
+  }, [refresh]);
+
+  useEffect(() => {
+    if (
+      !shouldHydrateOperationsDetails(
+        dashboardView,
+        operations?.summary.overview_metrics?.partial === true,
+      )
+    )
+      return;
+    const cancel = scheduleOperationsDetail(async (signal) => {
+      await loadOperationsDetails(signal);
+    });
+    operationsDetailCancelRef.current = cancel;
+    return () => {
+      if (operationsDetailCancelRef.current === cancel) operationsDetailCancelRef.current = null;
+      cancel();
+    };
+  }, [
+    dashboardView,
+    loadOperationsDetails,
+    operations?.summary.overview_metrics?.partial,
+    operationsDetailCancelRef,
+  ]);
+
+  useEffect(() => window.localStorage.setItem(localeKey, costLocale), [costLocale]);
+  useEffect(() => window.localStorage.setItem(currencyKey, currency), [currency]);
+
+  useEffect(() => {
+    if (!["/", pricingSetupPath, projectSetupPath].includes(window.location.pathname)) {
+      window.history.replaceState(null, "", `/${window.location.search}${window.location.hash}`);
+      setPathname("/");
+    }
+  }, [setPathname]);
+
+  useEffect(() => {
+    const syncPathname = () => setPathname(window.location.pathname);
+    window.addEventListener("popstate", syncPathname);
+    return () => window.removeEventListener("popstate", syncPathname);
+  }, [setPathname]);
+
+  useEffect(() => {
+    if (pathname !== pricingSetupPath || pricing !== null) return;
+    void Promise.all([api.pricing(), api.fxRate()])
+      .then(([catalog, rate]) => {
+        setPricing(catalog);
+        setFxRate(rate);
+      })
+      .catch((cause) => setError(String(cause)));
+  }, [api, pathname, pricing, setError, setFxRate, setPricing]);
+}

package/templates/.agents/dashboard/apps/frontend/src/use-app-operations-pages.ts

@@ -0,0 +1,395 @@
+import type { OperationsProjection } from "@zaip-ai/dashboard-operations/contracts";
+import { type Dispatch, type MutableRefObject, type SetStateAction, useCallback } from "react";
+import {
+  isAbortError,
+  isCurrentOperationsPageRequest,
+  isCurrentOperationsPeriodRequest,
+} from "./AppRequestGuards.js";
+import type {
+  DashboardApiClient,
+  OperationsEntityPage,
+  OperationsEntityPageKind,
+  OperationsLifecyclePageKind,
+  OperationsPageFilters,
+} from "./dashboard-api.js";
+import { projectEntityPage } from "./operations-entity-page-projection.js";
+import { type OperationsPeriodState, requestPeriodForOperations } from "./operations-period.js";
+
+function jsonStringArray(value: unknown): string[] {
+  if (typeof value !== "string") return [];
+  try {
+    const parsed = JSON.parse(value);
+    return Array.isArray(parsed)
+      ? parsed.filter((item): item is string => typeof item === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+export interface OperationsEntityPageState {
+  offset: number;
+  total: number | null;
+  loading: boolean;
+  error: string | null;
+  aggregation?: "canonical_entity" | "page_partial" | undefined;
+}
+
+export function useAppOperationsPages({
+  api,
+  entityFiltersRef,
+  operationsPageAbortRef,
+  operationsPageRequestVersionRef,
+  operationsPeriod,
+  operationsPeriodRef,
+  refreshVersion,
+  setEntityPage,
+  setEntityPageKind,
+  setOperations,
+}: {
+  api: DashboardApiClient;
+  entityFiltersRef: MutableRefObject<OperationsPageFilters>;
+  operationsPageAbortRef: MutableRefObject<AbortController | null>;
+  operationsPageRequestVersionRef: MutableRefObject<number>;
+  operationsPeriod: OperationsPeriodState;
+  operationsPeriodRef: MutableRefObject<OperationsPeriodState>;
+  refreshVersion: MutableRefObject<number>;
+  setEntityPage: Dispatch<SetStateAction<OperationsEntityPageState>>;
+  setEntityPageKind: Dispatch<
+    SetStateAction<OperationsEntityPageKind | OperationsLifecyclePageKind>
+  >;
+  setOperations: Dispatch<SetStateAction<OperationsProjection | null>>;
+}) {
+  const loadOperationsEntityPage = useCallback(
+    async (kind: OperationsEntityPageKind, offset = 0, filters = entityFiltersRef.current) => {
+      operationsPageAbortRef.current?.abort();
+      const controller = new AbortController();
+      operationsPageAbortRef.current = controller;
+      const requestVersion = ++operationsPageRequestVersionRef.current;
+      const dashboardRequestVersion = refreshVersion.current;
+      const period = requestPeriodForOperations(operationsPeriod);
+      const isCurrentRequest = () =>
+        isCurrentOperationsPageRequest(
+          requestVersion,
+          operationsPageRequestVersionRef.current,
+          controller.signal,
+        ) &&
+        isCurrentOperationsPeriodRequest(
+          dashboardRequestVersion,
+          refreshVersion.current,
+          period,
+          requestPeriodForOperations(operationsPeriodRef.current),
+        );
+      setEntityPageKind(kind);
+      setEntityPage({ offset, total: null, loading: true, error: null });
+      try {
+        const view = (
+          {
+            runs: "operations_agent_invocations",
+            executions: "operations_executions",
+            conversations: "operations_conversations",
+          } as const
+        )[kind];
+        const sql = await api.sqliteViewPage(
+          view,
+          period,
+          {
+            offset,
+            limit: 100,
+            ...(filters.query ? { query: filters.query } : {}),
+            ...(filters.status ? { status: filters.status } : {}),
+            ...(filters.risk ? { risk: filters.risk } : {}),
+          },
+          controller.signal,
+        );
+        const page: OperationsEntityPage = {
+          kind,
+          offset: sql.offset,
+          limit: sql.limit,
+          total: sql.total_count,
+          // The result is paginated, but every row is a complete canonical
+          // entity. `page_partial` means an aggregate assembled from raw page
+          // fragments and intentionally triggers the loading placeholder.
+          aggregation: "canonical_entity" as const,
+          rows: sql.rows.map((row) => ({
+            id: String(
+              row.agent_invocation_id ?? row.execution_id ?? row.conversation_id ?? row.id,
+            ),
+            started_at: String(row.occurred_at ?? row.started_at ?? "1970-01-01T00:00:00.000Z"),
+            finished_at: typeof row.finished_at === "string" ? row.finished_at : null,
+            task_id: typeof row.task_id === "string" ? row.task_id : null,
+            execution_id: typeof row.execution_id === "string" ? row.execution_id : null,
+            conversation_id: typeof row.conversation_id === "string" ? row.conversation_id : null,
+            parent_run_id:
+              typeof row.parent_agent_invocation_id === "string"
+                ? row.parent_agent_invocation_id
+                : null,
+            run_kind:
+              row.invocation_kind === "delegated" || row.invocation_kind === "subagent"
+                ? "subrun"
+                : row.invocation_kind === "orchestrator"
+                  ? "run"
+                  : null,
+            run_purpose: typeof row.purpose === "string" ? row.purpose : null,
+            phase: typeof row.phase === "string" ? row.phase : null,
+            status: typeof row.status === "string" ? row.status : null,
+            agent: typeof row.zaip_agent === "string" ? row.zaip_agent : null,
+            agent_persona:
+              typeof row.zaip_agent_persona === "string" ? row.zaip_agent_persona : null,
+            agent_job: typeof row.zaip_agent_job === "string" ? row.zaip_agent_job : null,
+            client: typeof row.client === "string" ? row.client : null,
+            provider: typeof row.provider === "string" ? row.provider : null,
+            model: typeof row.model === "string" ? row.model : null,
+            reasoning_effort:
+              typeof row.reasoning_effort === "string" ? row.reasoning_effort : null,
+            service_tier: typeof row.service_tier === "string" ? row.service_tier : null,
+            duration_ms:
+              typeof row.duration_ms === "number"
+                ? row.duration_ms
+                : typeof row.total_duration === "number"
+                  ? row.total_duration
+                  : null,
+            source_duration_ms:
+              typeof row.source_duration_ms === "number" ? row.source_duration_ms : null,
+            duration_provenance:
+              typeof row.duration_provenance === "string" ? row.duration_provenance : null,
+            llm_call_count: typeof row.llm_call_count === "number" ? row.llm_call_count : null,
+            input_tokens: typeof row.input_tokens === "number" ? row.input_tokens : null,
+            cached_input_tokens:
+              typeof row.cached_input_tokens === "number" ? row.cached_input_tokens : null,
+            uncached_input_tokens:
+              typeof row.uncached_input_tokens === "number" ? row.uncached_input_tokens : null,
+            output_tokens: typeof row.output_tokens === "number" ? row.output_tokens : null,
+            reasoning_tokens:
+              typeof row.reasoning_tokens === "number" ? row.reasoning_tokens : null,
+            visible_output_tokens:
+              typeof row.visible_output_tokens === "number" ? row.visible_output_tokens : null,
+            total_tokens: typeof row.total_tokens === "number" ? row.total_tokens : null,
+            input_rate_usd_per_million:
+              typeof row.input_rate_usd_per_million === "number"
+                ? row.input_rate_usd_per_million
+                : null,
+            cached_input_rate_usd_per_million:
+              typeof row.cached_input_rate_usd_per_million === "number"
+                ? row.cached_input_rate_usd_per_million
+                : null,
+            output_rate_usd_per_million:
+              typeof row.output_rate_usd_per_million === "number"
+                ? row.output_rate_usd_per_million
+                : null,
+            reasoning_rate_usd_per_million:
+              typeof row.reasoning_rate_usd_per_million === "number"
+                ? row.reasoning_rate_usd_per_million
+                : null,
+            context_input_multiplier:
+              typeof row.context_input_multiplier === "number"
+                ? row.context_input_multiplier
+                : null,
+            context_output_multiplier:
+              typeof row.context_output_multiplier === "number"
+                ? row.context_output_multiplier
+                : null,
+            speed_cost_multiplier:
+              typeof row.speed_cost_multiplier === "number" ? row.speed_cost_multiplier : null,
+            pricing_scenario:
+              typeof row.pricing_scenario === "string" ? row.pricing_scenario : null,
+            standard_cost_usd:
+              typeof row.standard_cost_usd === "number" ? row.standard_cost_usd : null,
+            speed_uplift_usd:
+              typeof row.speed_uplift_usd === "number" ? row.speed_uplift_usd : null,
+            input_cost_usd: typeof row.input_cost_usd === "number" ? row.input_cost_usd : null,
+            cached_input_cost_usd:
+              typeof row.cached_input_cost_usd === "number" ? row.cached_input_cost_usd : null,
+            output_cost_usd: typeof row.output_cost_usd === "number" ? row.output_cost_usd : null,
+            reasoning_cost_usd:
+              typeof row.reasoning_cost_usd === "number" ? row.reasoning_cost_usd : null,
+            calculated_cost_usd:
+              typeof row.calculated_cost_usd === "number" ? row.calculated_cost_usd : null,
+            recorded_cost_usd:
+              typeof row.recorded_cost_usd === "number" ? row.recorded_cost_usd : null,
+            cost_variance_usd:
+              typeof row.cost_variance_usd === "number" ? row.cost_variance_usd : null,
+            cost_usd: typeof row.cost_usd === "number" ? row.cost_usd : null,
+            fx_rate: typeof row.fx_rate === "number" ? row.fx_rate : null,
+            pricing_segment_count:
+              typeof row.pricing_segment_count === "number" ? row.pricing_segment_count : null,
+            pricing_mixed: row.pricing_mixed === 1 || row.pricing_mixed === true,
+            pricing_model:
+              typeof row.audit_pricing_model === "string"
+                ? row.audit_pricing_model
+                : typeof row.pricing_model === "string"
+                  ? row.pricing_model
+                  : null,
+            pricing_source:
+              typeof row.audit_pricing_source === "string"
+                ? row.audit_pricing_source
+                : typeof row.pricing_source === "string"
+                  ? row.pricing_source
+                  : null,
+            cost:
+              typeof row.total_cost_brl === "number"
+                ? row.total_cost_brl
+                : typeof row.cost_brl === "number"
+                  ? row.cost_brl
+                  : null,
+            currency: "BRL",
+          })),
+        };
+        if (!isCurrentRequest()) return;
+        setOperations((current) =>
+          current === null ? current : projectEntityPage(current, kind, page),
+        );
+        setEntityPage({
+          offset: page.offset,
+          total: page.total,
+          loading: false,
+          error: null,
+          aggregation: page.aggregation,
+        });
+      } catch (cause) {
+        if (!isCurrentRequest() || isAbortError(cause)) return;
+        setEntityPage({
+          offset,
+          total: null,
+          loading: false,
+          error: cause instanceof Error ? cause.message : String(cause),
+        });
+      } finally {
+        if (operationsPageAbortRef.current === controller) operationsPageAbortRef.current = null;
+      }
+    },
+    [
+      api,
+      entityFiltersRef,
+      operationsPageAbortRef,
+      operationsPageRequestVersionRef,
+      operationsPeriod,
+      operationsPeriodRef,
+      refreshVersion,
+      setEntityPage,
+      setEntityPageKind,
+      setOperations,
+    ],
+  );
+
+  const loadOperationsLifecyclePage = useCallback(
+    async (kind: OperationsLifecyclePageKind, offset = 0, filters = entityFiltersRef.current) => {
+      operationsPageAbortRef.current?.abort();
+      const controller = new AbortController();
+      operationsPageAbortRef.current = controller;
+      const requestVersion = ++operationsPageRequestVersionRef.current;
+      const dashboardRequestVersion = refreshVersion.current;
+      const period = requestPeriodForOperations(operationsPeriod);
+      const isCurrentRequest = () =>
+        isCurrentOperationsPageRequest(
+          requestVersion,
+          operationsPageRequestVersionRef.current,
+          controller.signal,
+        ) &&
+        isCurrentOperationsPeriodRequest(
+          dashboardRequestVersion,
+          refreshVersion.current,
+          period,
+          requestPeriodForOperations(operationsPeriodRef.current),
+        );
+      setEntityPageKind(kind);
+      setEntityPage({ offset, total: null, loading: true, error: null });
+      try {
+        const sql = await api.sqliteViewPage(
+          kind === "changes" ? "operations_changes" : "operations_decisions",
+          period,
+          {
+            offset,
+            limit: 100,
+            ...(filters.query ? { query: filters.query } : {}),
+            ...(filters.status ? { status: filters.status } : {}),
+            ...(filters.risk ? { risk: filters.risk } : {}),
+          },
+          controller.signal,
+        );
+        const rows =
+          kind === "changes"
+            ? sql.rows.map((row) => {
+                const sourceType = String(row.source_type);
+                const sourceId = String(row.source_id);
+                return {
+                  id: String(row.id),
+                  title: typeof row.title === "string" ? row.title : String(row.id),
+                  created_at: typeof row.occurred_at === "string" ? row.occurred_at : null,
+                  status: typeof row.status === "string" ? row.status : "unclassified",
+                  risk: typeof row.risk === "string" ? row.risk : "unclassified",
+                  source:
+                    sourceType === "spec"
+                      ? ({ type: "spec", spec_id: sourceId } as const)
+                      : sourceType === "prd"
+                        ? ({ type: "prd", prd_id: sourceId, spec_id: null } as const)
+                        : ({ type: "task", task_id: sourceId } as const),
+                  requirement_ids: jsonStringArray(row.requirement_ids_json),
+                  acceptance_ids: jsonStringArray(row.acceptance_ids_json),
+                  task_ids: jsonStringArray(row.task_ids_json),
+                  result: typeof row.result === "string" ? row.result : null,
+                  artifact_path:
+                    typeof row.source_path === "string" ? row.source_path : String(row.id),
+                };
+              })
+            : sql.rows.map((row) => ({
+                id: String(row.id),
+                title: typeof row.title === "string" ? row.title : String(row.id),
+                origin: row.origin === "human" ? ("human" as const) : ("agent" as const),
+                scope_type:
+                  row.scope_type === "execution" ? ("execution" as const) : ("change" as const),
+                scope_id: String(row.scope_id),
+                artifact_path:
+                  typeof row.source_path === "string" ? row.source_path : String(row.id),
+                created_at:
+                  typeof row.occurred_at === "string"
+                    ? row.occurred_at
+                    : "1970-01-01T00:00:00.000Z",
+              }));
+        const page = {
+          kind,
+          offset: sql.offset,
+          limit: sql.limit,
+          total: sql.total_count,
+          rows,
+        };
+        if (!isCurrentRequest()) return;
+        setOperations((current) =>
+          current === null
+            ? current
+            : {
+                ...current,
+                ...(kind === "changes"
+                  ? { changes: page.rows as OperationsProjection["changes"] }
+                  : { decisions: page.rows as OperationsProjection["decisions"] }),
+              },
+        );
+        setEntityPage({ offset: page.offset, total: page.total, loading: false, error: null });
+      } catch (cause) {
+        if (!isCurrentRequest() || isAbortError(cause)) return;
+        setEntityPage({
+          offset,
+          total: null,
+          loading: false,
+          error: cause instanceof Error ? cause.message : String(cause),
+        });
+      } finally {
+        if (operationsPageAbortRef.current === controller) operationsPageAbortRef.current = null;
+      }
+    },
+    [
+      api,
+      entityFiltersRef,
+      operationsPageAbortRef,
+      operationsPageRequestVersionRef,
+      operationsPeriod,
+      operationsPeriodRef,
+      refreshVersion,
+      setEntityPage,
+      setEntityPageKind,
+      setOperations,
+    ],
+  );
+
+  return { loadOperationsEntityPage, loadOperationsLifecyclePage };
+}