@zaip-ai/cli 1.0.7 → 1.0.8

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

@@ -0,0 +1,398 @@
+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 };
+}

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("")).toEqual(["prd", "spec", "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,37 @@
+export type WorkListKind = "prd" | "spec" | "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]
+    : ["prd", "spec", "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;
+  }
+}