@zaip-ai/cli 1.0.8 → 1.3.0

package/templates/.agents/dashboard/packages/local-runtime/src/server.ts

@@ -24,14 +24,11 @@ import {
   classifyTraceDocument,
   timestampsFromContent,
 } from "@zaip-ai/dashboard-traceability/server";
-import type {
-  TaskTrace,
-  TraceDocument,
-} from "../../../modules/traceability/src/contracts.js";
 import { type CompactRunMetric, LifecycleManifestStore } from "@zaip-ai/lifecycle-manifests";
 import { type Context, Hono } from "hono";
 import { getCookie, setCookie } from "hono/cookie";
 import type { ContentfulStatusCode } from "hono/utils/http-status";
+import type { TaskTrace, TraceDocument } from "../../../modules/traceability/src/contracts.js";
 import { runAgentAdapterSync } from "./agent-adapter-sync.js";
 import {
   type AgentAdapterSyncResult,
@@ -39,7 +36,11 @@ import {
   persistAgentCatalogUpdate,
   readAgentCatalogSettings,
 } from "./agent-catalog-settings.js";
-import { persistProjectSettings, readProjectOverview, readProjectSettings } from "./project-settings.js";
+import {
+  persistProjectSettings,
+  readProjectOverview,
+  readProjectSettings,
+} from "./project-settings.js";
 import {
   type BoardClassification,
   boardFilters,
@@ -264,7 +265,7 @@ async function buildFirstFoldQuickProjection(
   const aggregate =
     filter.from === null && filter.to === null
       ? filesystem.firstFoldViewportAllTime().aggregate
-      : cachedMonthlyQuick?.aggregate ?? filesystem.firstFoldAggregate(filter);
+      : (cachedMonthlyQuick?.aggregate ?? filesystem.firstFoldAggregate(filter));
   return {
     ...projection,
     summary: {
@@ -314,10 +315,12 @@ function buildSqliteOperationsProjection(
   const tasks = includeEntities ? page("task") : [];
   const specs = includeEntities ? page("spec") : [];
   const prds = includeEntities ? page("prd") : [];
-  const aggregate = allTime?.aggregate ?? cachedMonthlyQuick?.aggregate ?? filesystem.firstFoldAggregate(filter);
+  const aggregate =
+    allTime?.aggregate ?? cachedMonthlyQuick?.aggregate ?? filesystem.firstFoldAggregate(filter);
   const taskCount = allTime?.aggregate.task_count ?? tasks.length;
   const allTimeTopTasks =
-    filter.from === null && filter.to === null &&
+    filter.from === null &&
+    filter.to === null &&
     (fullAllTime !== null || options.includeTopTasks === true)
       ? (fullAllTime?.top_tasks ?? filesystem.firstFoldTopTasksAllTime())
       : null;
@@ -334,7 +337,7 @@ function buildSqliteOperationsProjection(
   const macroMetrics =
     fullAllTime === null
       ? undefined
-      : Object.fromEntries(
+      : (Object.fromEntries(
           (["specs", "prds"] as const).map((kind) => {
             const metric = fullAllTime.macro_metrics[kind];
             return [
@@ -368,7 +371,7 @@ function buildSqliteOperationsProjection(
           }),
         ) as NonNullable<
           NonNullable<OperationsProjection["summary"]["overview_metrics"]>["macro_metrics"]
-        >;
+        >);
   const statuses: Record<string, number> = allTime?.task_status_counts ?? {};
   const risks: Record<string, number> = allTime?.task_risk_counts ?? {};
   if (allTime === null) {
@@ -535,8 +538,7 @@ function buildSqliteOperationsProjection(
         task_completion_rate:
           taskCount === 0
             ? 0
-            : (allTime?.aggregate.completed_task_count ?? statuses.completed ?? 0) /
-              taskCount,
+            : (allTime?.aggregate.completed_task_count ?? statuses.completed ?? 0) / taskCount,
         terminal_runs: 0,
         successful_runs: 0,
         terminal_success_rate: 0,
@@ -647,7 +649,8 @@ function buildSqliteTaskTrace(
 ): TaskTrace {
   const initial = filesystem.canonicalTraceFiles([taskId]);
   const taskFile = initial.find(
-    (row) => row.path.includes("/.agents/records/tasks/") || row.path.includes(".agents/records/tasks/"),
+    (row) =>
+      row.path.includes("/.agents/records/tasks/") || row.path.includes(".agents/records/tasks/"),
   );
   if (taskFile === undefined) throw new Error(`Canonical Task ${taskId} was not found`);
   const scalar = (key: string): string | null => {
@@ -667,8 +670,7 @@ function buildSqliteTaskTrace(
   const documents = filesystem
     .canonicalTraceFiles(markers)
     .filter(
-      (row) =>
-        /\.(?:md|json|jsonl|txt|log)$/i.test(row.path) && row.content.length <= 250_000,
+      (row) => /\.(?:md|json|jsonl|txt|log)$/i.test(row.path) && row.content.length <= 250_000,
     )
     .map((row) => {
       const classification = classifyTraceDocument(row.path);
@@ -677,9 +679,7 @@ function buildSqliteTaskTrace(
         id: createHash("sha256").update(row.path).digest("hex").slice(0, 16),
         path: row.path,
         title:
-          row.content.match(/^#\s+(.+)$/m)?.[1]?.trim() ??
-          row.path.split("/").at(-1) ??
-          row.path,
+          row.content.match(/^#\s+(.+)$/m)?.[1]?.trim() ?? row.path.split("/").at(-1) ?? row.path,
         ...classification,
         content: row.content,
         ...timestamps,
@@ -742,10 +742,17 @@ export function createDashboardApp(
   const snapshotState = options.snapshotState ?? "current";
   const canonicalFilesystem = options.canonicalFilesystem ?? new WorkspaceFileSystem(workspaceRoot);
   const reconcileOpen = options.reconcileOpenWork ?? reconcileOpenWork;
-  const refreshReadModel = options.refreshReadModel ?? (async () => {
-    if (!isSqliteSnapshot) return;
-    await filesystem.rebuildAndRefresh(() => rebuildSqliteReadModel(workspaceRoot));
-  });
+  const refreshReadModel =
+    options.refreshReadModel ??
+    (async () => {
+      if (!isSqliteSnapshot) return;
+      // Explicit user refreshes must replace the immutable generation with the
+      // current canonical records. Keep stale-seed fallback exclusively for
+      // startup warmth, never for this visible convergence request.
+      await filesystem.rebuildAndRefresh(() =>
+        rebuildSqliteReadModel(workspaceRoot, { forceCanonical: true }),
+      );
+    });
   const workspaceKey = dashboardWorkspaceKey(workspaceRoot);
   const syncAgentAdapters = options.syncAgentAdapters ?? (() => runAgentAdapterSync(workspaceRoot));
   let catalogWriteTail = Promise.resolve();
@@ -764,7 +771,8 @@ export function createDashboardApp(
     // so retain their expensive board projection until an explicit refresh
     // clears this map rather than expiring it on the short snapshot TTL.
     if (
-      !fresh && cached !== undefined &&
+      !fresh &&
+      cached !== undefined &&
       (key.startsWith("operations:board:") || Date.now() - cached.cachedAt < SNAPSHOT_CACHE_TTL_MS)
     )
       return cached.payload as T;
@@ -794,6 +802,16 @@ export function createDashboardApp(
     aggregatePayloads.clear();
     aggregateInFlight.clear();
   };
+  let projectionRefreshInFlight: Promise<void> | null = null;
+  const rebuildProjection = async () => {
+    if (projectionRefreshInFlight !== null) return projectionRefreshInFlight;
+    projectionRefreshInFlight = refreshReadModel()
+      .then(() => clearSnapshotCache())
+      .finally(() => {
+        projectionRefreshInFlight = null;
+      });
+    return projectionRefreshInFlight;
+  };
   const readSnapshot = (context: Context) => {
     const key = snapshotKey(context);
     const cached = cachedSnapshots.get(key);
@@ -807,7 +825,8 @@ export function createDashboardApp(
       return pending;
     }
     context.header("X-ZAIP-Snapshot-Cache", "miss");
-    const inFlight = readLayout().then((layout) => dashboardSnapshot(filesystem, workspaceRoot, context, layout))
+    const inFlight = readLayout()
+      .then((layout) => dashboardSnapshot(filesystem, workspaceRoot, context, layout))
       .then((snapshot) => {
         cachedSnapshots.set(key, { snapshot, cachedAt: Date.now() });
         return snapshot;
@@ -850,13 +869,15 @@ export function createDashboardApp(
     // CLI. It does not mutate the disposable SQLite read model, so it remains
     // available while the dashboard serves a read-only snapshot.
     const reconcileWrite =
-      context.req.method === "POST" &&
-      context.req.path === `${API_PREFIX}/reconcile-open-work`;
+      context.req.method === "POST" && context.req.path === `${API_PREFIX}/reconcile-open-work`;
+    const projectionRefreshWrite =
+      context.req.method === "POST" && context.req.path === `${API_PREFIX}/refresh-projection`;
     if (
       context.req.method !== "GET" &&
       context.req.method !== "HEAD" &&
       !settingsWrite &&
-      !reconcileWrite
+      !reconcileWrite &&
+      !projectionRefreshWrite
     ) {
       context.header(
         "Allow",
@@ -868,7 +889,9 @@ export function createDashboardApp(
           ? "GET, HEAD, PUT"
           : context.req.path === `${API_PREFIX}/reconcile-open-work`
             ? "POST"
-            : "GET, HEAD",
+            : context.req.path === `${API_PREFIX}/refresh-projection`
+              ? "POST"
+              : "GET, HEAD",
       );
       return context.json({ error: "Dashboard API is read-only" }, 405);
     }
@@ -976,7 +999,13 @@ export function createDashboardApp(
     try {
       const requestStartedAt = performance.now();
       const scope = context.req.query("scope");
-      if (scope !== "overview" && scope !== "quick" && scope !== "detail" && scope !== "board" && scope !== "classification")
+      if (
+        scope !== "overview" &&
+        scope !== "quick" &&
+        scope !== "detail" &&
+        scope !== "board" &&
+        scope !== "classification"
+      )
         return headOrJson(context, (await readSnapshot(context)).operations);
       const layout = await readLayout();
       const layoutMs = performance.now() - requestStartedAt;
@@ -988,52 +1017,80 @@ export function createDashboardApp(
           50,
           Math.max(1, Number.parseInt(context.req.query("limit") ?? "10", 10) || 10),
         );
-        const board = await readAggregate(`operations:board:${from ?? ""}:${to ?? ""}`, async () => {
-          const projection = await buildFirstFoldQuickProjection(
-            filesystem,
-            layout,
-            { from, to },
-            { includeBoardTasks: true },
-          );
-          return {
-            projection,
-            priority: await readWorkPriority(canonicalFilesystem, knownWorkIds(projection)),
-          };
-        });
+        const board = await readAggregate(
+          `operations:board:${from ?? ""}:${to ?? ""}`,
+          async () => {
+            const projection = await buildFirstFoldQuickProjection(
+              filesystem,
+              layout,
+              { from, to },
+              { includeBoardTasks: true },
+            );
+            return {
+              projection,
+              priority: await readWorkPriority(canonicalFilesystem, knownWorkIds(projection)),
+            };
+          },
+        );
         const filters = boardFilters(context);
         const pageKey = JSON.stringify({ from, to, stage, offset, limit, ...filters });
         const page = await readAggregate(`operations:board-page:${pageKey}`, async () =>
           boardPage(board.projection, stage, offset, limit, board.priority.item_ids, filters),
         );
-        return headOrJson(
-          context,
-          page,
-          200,
-          true,
-        );
+        return headOrJson(context, page, 200, true);
       }
       if (scope === "classification") {
         const kind = context.req.query("kind");
         const classification = context.req.query("classification");
         if (kind !== "task" && kind !== "spec" && kind !== "prd")
           return headOrJson(context, { error: "A valid work kind is required" }, 400);
-        if (!['lite', 'standard', 'critical', 'empty', 'structured', 'rework'].includes(classification ?? ''))
+        if (
+          !["lite", "standard", "critical", "empty", "structured", "rework"].includes(
+            classification ?? "",
+          )
+        )
           return headOrJson(context, { error: "A valid classification is required" }, 400);
         const offset = Math.max(0, Number.parseInt(context.req.query("offset") ?? "0", 10) || 0);
-        const limit = Math.min(50, Math.max(1, Number.parseInt(context.req.query("limit") ?? "50", 10) || 50));
-        const projection = await readAggregate(`operations:classification:${from ?? ""}:${to ?? ""}`, () =>
-          buildFirstFoldQuickProjection(filesystem, layout, { from, to }, { includeBoardTasks: true }),
+        const limit = Math.min(
+          50,
+          Math.max(1, Number.parseInt(context.req.query("limit") ?? "50", 10) || 50),
+        );
+        const projection = await readAggregate(
+          `operations:classification:${from ?? ""}:${to ?? ""}`,
+          () =>
+            buildFirstFoldQuickProjection(
+              filesystem,
+              layout,
+              { from, to },
+              { includeBoardTasks: true },
+            ),
+        );
+        return headOrJson(
+          context,
+          classificationPage(
+            projection,
+            kind,
+            classification as BoardClassification,
+            offset,
+            limit,
+          ),
+          200,
+          true,
         );
-        return headOrJson(context, classificationPage(projection, kind, classification as BoardClassification, offset, limit), 200, true);
       }
       if (scope === "quick") {
         const projectionStartedAt = performance.now();
         const quick = await readAggregate(
           `operations:quick:${from ?? ""}:${to ?? ""}`,
           () =>
-            buildFirstFoldQuickProjection(filesystem, layout, { from, to }, {
-              includeTopTasks: from === null && to === null,
-            }),
+            buildFirstFoldQuickProjection(
+              filesystem,
+              layout,
+              { from, to },
+              {
+                includeTopTasks: from === null && to === null,
+              },
+            ),
           context.req.query("fresh") === "1",
         );
         if (
@@ -1046,8 +1103,7 @@ export function createDashboardApp(
             [
               `layout;dur=${Math.round(layoutMs * 10) / 10}`,
               `projection;dur=${Math.round((performance.now() - projectionStartedAt) * 10) / 10}`,
-              ...Object.entries(timings)
-              .map(([name, duration]) => `${name};dur=${duration}`)
+              ...Object.entries(timings).map(([name, duration]) => `${name};dur=${duration}`),
             ].join(", "),
           );
         }
@@ -1242,8 +1298,7 @@ export function createDashboardApp(
       // canonical records, then atomically rebuild and reopen the snapshot
       // before the response exposes fresh projections.
       const reconciledIds = await reconcileOpen(canonicalFilesystem, workspaceRoot);
-      await refreshReadModel();
-      clearSnapshotCache();
+      await rebuildProjection();
       return context.json({
         ...(await readSnapshot(context)),
         reconciliation: reconciledIds,
@@ -1254,6 +1309,17 @@ export function createDashboardApp(
     }
   });
 
+  app.post(`${API_PREFIX}/refresh-projection`, async (context) => {
+    try {
+      await readLayout();
+      await rebuildProjection();
+      return context.json(await readSnapshot(context));
+    } catch (error) {
+      if (error instanceof V2WorkspaceRequiredError) throw error;
+      return context.json({ error: error instanceof Error ? error.message : String(error) }, 400);
+    }
+  });
+
   app.on(["GET", "HEAD"], `${API_PREFIX}/cost-monitor`, async (context) => {
     try {
       const scope = context.req.query("scope") ?? "summary";
@@ -1535,7 +1601,7 @@ async function dashboardSnapshot(
   context: Context,
   cachedLayout?: WorkspaceLayout,
 ) {
-  const layout = cachedLayout ?? await requireV2Layout(filesystem);
+  const layout = cachedLayout ?? (await requireV2Layout(filesystem));
   const { from, to } = projectionPeriodFilter(context);
   const currency = selectedCurrency(context);
   const operations =

package/templates/.agents/dashboard/packages/local-runtime/src/sqlite-metric-contract.ts

@@ -110,7 +110,14 @@ export const SQLITE_VIEW_CONTRACTS = [
   ],
   ["cost_monitor_zaip_agents", "cost-monitor", canonicalRunMetrics, "agent totals", "offset", xlsx],
   ["cost_monitor_models", "cost-monitor", canonicalRunMetrics, "model totals", "offset", xlsx],
-  ["cost_monitor_providers", "cost-monitor", canonicalRunMetrics, "provider totals", "offset", xlsx],
+  [
+    "cost_monitor_providers",
+    "cost-monitor",
+    canonicalRunMetrics,
+    "provider totals",
+    "offset",
+    xlsx,
+  ],
   ["cost_monitor_tasks", "cost-monitor", canonicalRunMetrics, "task totals", "offset", xlsx],
   ["cost_monitor_specs", "cost-monitor", canonicalRunMetrics, "SPEC totals", "offset", xlsx],
   ["cost_monitor_prds", "cost-monitor", canonicalRunMetrics, "PRD totals", "offset", xlsx],
@@ -171,7 +178,14 @@ export const SQLITE_VIEW_CONTRACTS = [
     "offset",
     xlsx,
   ],
-  ["operations_daily", "operations", canonicalRunMetrics, "daily operations totals", "offset", xlsx],
+  [
+    "operations_daily",
+    "operations",
+    canonicalRunMetrics,
+    "daily operations totals",
+    "offset",
+    xlsx,
+  ],
   [
     "operations_monthly",
     "operations",