@stigmer/react 0.5.1 → 1.0.0

package/src/dashboard/DashboardKPICards.tsx

@@ -0,0 +1,128 @@
+"use client";
+
+import { memo } from "react";
+import { cn } from "@stigmer/theme";
+import type { DashboardSummary } from "./types";
+
+export interface DashboardKPICardsProps {
+  readonly summary: DashboardSummary | null;
+  readonly isLoading: boolean;
+  readonly className?: string;
+}
+
+interface StatCardDef {
+  readonly label: string;
+  readonly valueClass: string;
+  readonly getValue: (s: DashboardSummary) => string;
+  readonly getBreakdown: (s: DashboardSummary) => string | null;
+}
+
+function formatCost(usd: number): string {
+  if (usd >= 1) return `$${usd.toFixed(2)}`;
+  if (usd >= 0.01) return `$${usd.toFixed(3)}`;
+  if (usd > 0) return `<$0.01`;
+  return "$0.00";
+}
+
+const STAT_CARDS: readonly StatCardDef[] = [
+  {
+    label: "Active",
+    valueClass: "text-foreground",
+    getValue: (s) => String(s.activeCount),
+    getBreakdown: (s) => {
+      const ag = s.agent?.activeCount ?? 0;
+      const wf = s.workflow?.activeCount ?? 0;
+      if (ag === 0 && wf === 0) return null;
+      return `${ag} agent, ${wf} workflow`;
+    },
+  },
+  {
+    label: "Completed",
+    valueClass: "text-success",
+    getValue: (s) => String(s.completedCount),
+    getBreakdown: (s) => {
+      const ag = s.agent?.phaseCounts[3] ?? 0;
+      const wf = s.workflow?.phaseCounts[3] ?? 0;
+      if (ag === 0 && wf === 0) return null;
+      return `${ag} agent, ${wf} workflow`;
+    },
+  },
+  {
+    label: "Failed",
+    valueClass: "text-destructive",
+    getValue: (s) => String(s.failedCount),
+    getBreakdown: (s) => {
+      const ag = s.agent?.phaseCounts[4] ?? 0;
+      const wf = s.workflow?.phaseCounts[4] ?? 0;
+      if (ag === 0 && wf === 0) return null;
+      return `${ag} agent, ${wf} workflow`;
+    },
+  },
+  {
+    label: "Total Cost",
+    valueClass: "text-foreground",
+    getValue: (s) => formatCost(s.totalCostUsd),
+    getBreakdown: () => null,
+  },
+];
+
+/**
+ * Unified stat cards showing combined agent + workflow execution KPIs.
+ *
+ * Each card shows the combined count with a breakdown tooltip showing
+ * per-source values (e.g., "2 agent, 1 workflow").
+ *
+ * Cost comes from the billing source of truth (getOrgUsageReport),
+ * not from summing per-domain costs. See AD-DASH-005.
+ *
+ * @since Unified Platform Dashboard
+ */
+export const DashboardKPICards = memo(function DashboardKPICards({
+  summary,
+  isLoading,
+  className,
+}: DashboardKPICardsProps) {
+  if (isLoading) {
+    return (
+      <div className={cn("space-y-3", className)} aria-busy="true">
+        <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-4">
+          {Array.from({ length: 4 }, (_, i) => (
+            <div
+              key={i}
+              className="h-[72px] animate-pulse rounded-lg border border-border bg-muted/50"
+            />
+          ))}
+        </div>
+      </div>
+    );
+  }
+
+  if (!summary) return null;
+
+  return (
+    <div className={cn("grid gap-3 sm:grid-cols-2 lg:grid-cols-4", className)}>
+      {STAT_CARDS.map((card) => {
+        const breakdown = card.getBreakdown(summary);
+        return (
+          <div
+            key={card.label}
+            className="rounded-lg border border-border bg-card px-4 py-3"
+            title={breakdown ?? undefined}
+          >
+            <p className="text-xs font-medium text-muted-foreground">
+              {card.label}
+            </p>
+            <p className={cn("mt-1 text-2xl font-semibold", card.valueClass)}>
+              {card.getValue(summary)}
+            </p>
+            {breakdown && (
+              <p className="mt-0.5 text-[10px] text-muted-foreground">
+                {breakdown}
+              </p>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+});

package/src/dashboard/OperationalDashboard.tsx

@@ -0,0 +1,96 @@
+"use client";
+
+import { memo, useCallback } from "react";
+import { cn } from "@stigmer/theme";
+import { usePendingApprovals } from "../workflow/usePendingApprovals";
+import { PendingApprovalsWidget } from "../workflow/PendingApprovalsWidget";
+import { useDashboardSummary, type UseDashboardSummaryOptions } from "./useDashboardSummary";
+import { useDashboardFailedRuns } from "./useDashboardFailedRuns";
+import { DashboardKPICards } from "./DashboardKPICards";
+import { DashboardFailedRuns } from "./DashboardFailedRuns";
+import type { DashboardFailedRun } from "./types";
+
+export interface OperationalDashboardProps {
+  /** Organization slug for execution summaries and pending approvals. */
+  readonly org: string | null | undefined;
+  /** Organization ID (metadata.id) for the usage report. */
+  readonly orgId: string | null | undefined;
+  /** Called when the user clicks "Review" on a pending approval. */
+  readonly onApprovalClick?: (executionId: string) => void;
+  /** Called when the user clicks "View" on a failed execution. */
+  readonly onFailedRunClick?: (id: string, type: DashboardFailedRun["type"]) => void;
+  readonly className?: string;
+}
+
+/**
+ * Composed dashboard widget that aggregates operational metrics from both
+ * agent and workflow domains into a unified platform view.
+ *
+ * Layout:
+ * - Row 1: KPI stat cards (Active | Completed | Failed | Total Cost)
+ * - Row 2: Pending Approvals | Recent Failures (2-column grid)
+ *
+ * Cost comes from the billing source of truth (`getOrgUsageReport`),
+ * not from summing agent + workflow costs. See AD-DASH-005.
+ *
+ * @example
+ * ```tsx
+ * <OperationalDashboard
+ *   org="acme"
+ *   orgId={activeOrg?.metadata?.id}
+ *   onApprovalClick={(id) => navigate(`/executions/${id}`)}
+ *   onFailedRunClick={(id, type) => navigate(`/executions/${id}`)}
+ * />
+ * ```
+ *
+ * @since Unified Platform Dashboard
+ */
+export const OperationalDashboard = memo(function OperationalDashboard({
+  org,
+  orgId,
+  onApprovalClick,
+  onFailedRunClick,
+  className,
+}: OperationalDashboardProps) {
+  const summaryOptions: UseDashboardSummaryOptions = {
+    org,
+    orgId,
+    refetchInterval: 60_000,
+  };
+  const { summary, isLoading: summaryLoading } = useDashboardSummary(summaryOptions);
+
+  const { approvals, totalCount: approvalCount, isLoading: approvalsLoading } =
+    usePendingApprovals({ org, refetchInterval: 30_000 });
+
+  const { failedRuns, isLoading: failedLoading } = useDashboardFailedRuns(org);
+
+  const handleFailedRunClick = useCallback(
+    (id: string, type: DashboardFailedRun["type"]) => {
+      onFailedRunClick?.(id, type);
+    },
+    [onFailedRunClick],
+  );
+
+  return (
+    <section
+      aria-label="Platform dashboard"
+      className={cn("space-y-6", className)}
+    >
+      <DashboardKPICards summary={summary} isLoading={summaryLoading} />
+
+      <div className="grid gap-6 lg:grid-cols-2">
+        <PendingApprovalsWidget
+          approvals={approvals}
+          totalCount={approvalCount}
+          isLoading={approvalsLoading}
+          onReviewClick={onApprovalClick}
+        />
+        <DashboardFailedRuns
+          failedRuns={failedRuns}
+          isLoading={failedLoading}
+          onViewClick={handleFailedRunClick}
+        />
+      </div>
+    </section>
+  );
+});

package/src/dashboard/index.ts

@@ -0,0 +1,37 @@
+// ─── Types ──────────────────────────────────────────────────────────────────
+export type { DashboardSummary, DashboardFailedRun } from "./types";
+
+// ─── Data Hooks ─────────────────────────────────────────────────────────────
+export {
+  useAgentExecutionSummary,
+  AgentExecutionSummaryTimeWindow,
+  type UseAgentExecutionSummaryOptions,
+  type UseAgentExecutionSummaryReturn,
+} from "./useAgentExecutionSummary";
+
+export {
+  useDashboardSummary,
+  type UseDashboardSummaryOptions,
+  type UseDashboardSummaryReturn,
+} from "./useDashboardSummary";
+
+export {
+  useDashboardFailedRuns,
+  type UseDashboardFailedRunsReturn,
+} from "./useDashboardFailedRuns";
+
+// ─── Styled Components ─────────────────────────────────────────────────────
+export {
+  DashboardKPICards,
+  type DashboardKPICardsProps,
+} from "./DashboardKPICards";
+
+export {
+  DashboardFailedRuns,
+  type DashboardFailedRunsProps,
+} from "./DashboardFailedRuns";
+
+export {
+  OperationalDashboard,
+  type OperationalDashboardProps,
+} from "./OperationalDashboard";

package/src/dashboard/types.ts

@@ -0,0 +1,50 @@
+import type { AgentExecutionSummary } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import type { GetOrgUsageReportOutput } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import type { ExecutionSummary } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+
+/**
+ * Unified dashboard summary combining operational metrics from both
+ * agent and workflow execution domains.
+ *
+ * Execution counts (active, completed, failed) are safe to add because
+ * agent executions and workflow executions are distinct resources.
+ *
+ * Cost comes from {@link GetOrgUsageReportOutput} (billing source of truth),
+ * NOT from summing agent + workflow costs. This prevents double-counting
+ * when workflows delegate to agents. See AD-DASH-005.
+ */
+export interface DashboardSummary {
+  /** Combined agent + workflow active execution count. */
+  readonly activeCount: number;
+  /** Combined agent + workflow completed count. */
+  readonly completedCount: number;
+  /** Combined agent + workflow failed count. */
+  readonly failedCount: number;
+  /**
+   * Total platform cost in USD from the billing source of truth.
+   * Sourced from `getOrgUsageReport.total_billable_cost_micros`.
+   */
+  readonly totalCostUsd: number;
+  /** Agent-side execution summary for per-source breakdown in tooltips. */
+  readonly agent: AgentExecutionSummary | null;
+  /** Workflow-side execution summary for per-source breakdown in tooltips. */
+  readonly workflow: ExecutionSummary | null;
+  /** Org-level usage report for cost details. */
+  readonly orgUsage: GetOrgUsageReportOutput | null;
+}
+
+/** A normalized entry representing a failed execution from either domain. */
+export interface DashboardFailedRun {
+  /** Execution ID (`aex_*` or `wex_*`). */
+  readonly id: string;
+  /** Discriminator for routing navigation. */
+  readonly type: "agent_execution" | "workflow_execution";
+  /** Execution name or subject. */
+  readonly name: string;
+  /** Error message from the failed execution. */
+  readonly error: string;
+  /** When the execution failed. */
+  readonly failedAt: Date;
+  /** The agent or workflow name associated with this execution. */
+  readonly resourceName: string;
+}

package/src/dashboard/useAgentExecutionSummary.ts

@@ -0,0 +1,71 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import type { AgentExecutionSummary } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import {
+  AgentExecutionSummaryTimeWindow,
+  GetAgentExecutionSummaryRequestSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+export { AgentExecutionSummaryTimeWindow };
+
+/** Options for {@link useAgentExecutionSummary}. */
+export interface UseAgentExecutionSummaryOptions {
+  /** Organization slug. When empty/null, the hook does not fetch. */
+  readonly org: string | null | undefined;
+  /** Time window for aggregation. @default LAST_7D */
+  readonly timeWindow?: AgentExecutionSummaryTimeWindow;
+  /** Refetch interval in milliseconds. `0` or `false` disables. @default 0 */
+  readonly refetchInterval?: number | false;
+}
+
+/** Return value of {@link useAgentExecutionSummary}. */
+export interface UseAgentExecutionSummaryReturn {
+  readonly summary: AgentExecutionSummary | null;
+  readonly isLoading: boolean;
+  readonly isRefetching: boolean;
+  readonly error: Error | null;
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches aggregated agent execution statistics for an
+ * organization. Returns phase counts, active count, average duration,
+ * and top failing agents.
+ *
+ * Cost is intentionally excluded from this response — the dashboard
+ * sources cost from `useOrgUsageReport` (billing source of truth) to
+ * prevent double-counting. See AD-DASH-005.
+ *
+ * @since Unified Platform Dashboard
+ */
+export function useAgentExecutionSummary(
+  options: UseAgentExecutionSummaryOptions,
+): UseAgentExecutionSummaryReturn {
+  const stigmer = useStigmer();
+  const org = options.org ?? "";
+  const timeWindow =
+    options.timeWindow ??
+    AgentExecutionSummaryTimeWindow.LAST_7D;
+  const refetchInterval = options.refetchInterval ?? 0;
+
+  const fetchFn = org
+    ? async () => {
+        return await stigmer.agentExecution.getExecutionSummary(
+          create(GetAgentExecutionSummaryRequestSchema, { org, timeWindow }),
+        );
+      }
+    : null;
+
+  const { data, isLoading, isRefetching, error, refetch } =
+    useFetch<AgentExecutionSummary | null>(
+      fetchFn,
+      [stigmer, org, timeWindow],
+      null,
+      { refetchInterval: refetchInterval || false },
+    );
+
+  return { summary: data, isLoading, isRefetching, error, refetch };
+}

package/src/dashboard/useDashboardFailedRuns.ts

@@ -0,0 +1,122 @@
+"use client";
+
+import { useMemo } from "react";
+import { create } from "@bufbuild/protobuf";
+import { timestampDate } from "@bufbuild/protobuf/wkt";
+import { ExecutionPhase as AgentPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ExecutionPhase as WorkflowPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { ListAgentExecutionsRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/io_pb";
+import { ListWorkflowExecutionsRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+import type { DashboardFailedRun } from "./types";
+
+const EPOCH = new Date(0);
+const EMPTY: readonly DashboardFailedRun[] = [];
+const MAX_TOTAL = 5;
+const PAGE_SIZE = 5;
+
+/** Return value of {@link useDashboardFailedRuns}. */
+export interface UseDashboardFailedRunsReturn {
+  readonly failedRuns: readonly DashboardFailedRun[];
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+}
+
+/**
+ * Composition hook that fetches recent failed executions from both
+ * agent and workflow domains, normalizes them into {@link DashboardFailedRun}
+ * entries, and interleaves them by timestamp (newest first).
+ *
+ * Returns at most 5 total entries to keep the widget compact.
+ *
+ * @since Unified Platform Dashboard
+ */
+export function useDashboardFailedRuns(
+  org: string | null | undefined,
+): UseDashboardFailedRunsReturn {
+  const stigmer = useStigmer();
+  const orgVal = org ?? "";
+
+  const agentFetchFn = useMemo(
+    () =>
+      orgVal
+        ? async () => {
+            const resp = await stigmer.agentExecution.list(
+              create(ListAgentExecutionsRequestSchema, {
+                pageSize: PAGE_SIZE,
+                phase: AgentPhase.EXECUTION_FAILED,
+              }),
+            );
+            return [...resp.entries] as readonly AgentExecution[];
+          }
+        : null,
+    [stigmer, orgVal],
+  );
+
+  const workflowFetchFn = useMemo(
+    () =>
+      orgVal
+        ? async () => {
+            const resp = await stigmer.workflowExecution.list(
+              create(ListWorkflowExecutionsRequestSchema, {
+                pageSize: PAGE_SIZE,
+                phase: WorkflowPhase.EXECUTION_FAILED,
+              }),
+            );
+            return [...resp.entries] as readonly WorkflowExecution[];
+          }
+        : null,
+    [stigmer, orgVal],
+  );
+
+  const { data: agentFailed, isLoading: agLoading, error: agError } =
+    useFetch<readonly AgentExecution[]>(agentFetchFn, [stigmer, orgVal], [], {
+      refetchInterval: 60_000,
+    });
+
+  const { data: workflowFailed, isLoading: wfLoading, error: wfError } =
+    useFetch<readonly WorkflowExecution[]>(workflowFetchFn, [stigmer, orgVal], [], {
+      refetchInterval: 60_000,
+    });
+
+  const failedRuns = useMemo(() => {
+    if (!agentFailed.length && !workflowFailed.length) return EMPTY;
+
+    const agentEntries: DashboardFailedRun[] = agentFailed.map((exec) => {
+      const ts = exec.status?.audit?.specAudit?.createdAt;
+      return {
+        id: exec.metadata?.id ?? "",
+        type: "agent_execution" as const,
+        name: exec.metadata?.name || "Untitled execution",
+        error: exec.status?.error ?? "",
+        failedAt: ts ? timestampDate(ts) : EPOCH,
+        resourceName: exec.spec?.agentId ?? "",
+      };
+    });
+
+    const workflowEntries: DashboardFailedRun[] = workflowFailed.map((exec) => {
+      const ts = exec.status?.audit?.specAudit?.createdAt;
+      return {
+        id: exec.metadata?.id ?? "",
+        type: "workflow_execution" as const,
+        name: exec.metadata?.name || "Untitled execution",
+        error: exec.status?.error ?? "",
+        failedAt: ts ? timestampDate(ts) : EPOCH,
+        resourceName: exec.metadata?.slug ?? "",
+      };
+    });
+
+    const merged = [...agentEntries, ...workflowEntries];
+    merged.sort((a, b) => b.failedAt.getTime() - a.failedAt.getTime());
+    return merged.slice(0, MAX_TOTAL);
+  }, [agentFailed, workflowFailed]);
+
+  return {
+    failedRuns,
+    isLoading: agLoading || wfLoading,
+    error: agError ?? wfError,
+  };
+}

package/src/dashboard/useDashboardSummary.ts

@@ -0,0 +1,109 @@
+"use client";
+
+import { useMemo } from "react";
+import { ExecutionPhase as WorkflowPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { ExecutionPhase as AgentPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import {
+  useWorkflowDashboardSummary,
+  type UseWorkflowDashboardSummaryOptions,
+} from "../workflow/useWorkflowDashboardSummary";
+import { useOrgUsageReport } from "../usage/useOrgUsageReport";
+import { dateRangeFromPreset } from "../usage/date-range";
+import {
+  useAgentExecutionSummary,
+  AgentExecutionSummaryTimeWindow,
+} from "./useAgentExecutionSummary";
+import type { DashboardSummary } from "./types";
+
+/** Options for {@link useDashboardSummary}. */
+export interface UseDashboardSummaryOptions {
+  /** Organization slug for execution summaries. */
+  readonly org: string | null | undefined;
+  /** Organization ID (metadata.id) for the usage report. */
+  readonly orgId: string | null | undefined;
+  /** Refetch interval in milliseconds. @default 60_000 */
+  readonly refetchInterval?: number;
+}
+
+/** Return value of {@link useDashboardSummary}. */
+export interface UseDashboardSummaryReturn {
+  readonly summary: DashboardSummary | null;
+  readonly isLoading: boolean;
+  readonly error: Error | null;
+  readonly refetch: () => void;
+}
+
+/**
+ * Composition hook that merges agent execution summary, workflow execution
+ * summary, and org usage report into a single {@link DashboardSummary}.
+ *
+ * - Execution counts (active, completed, failed) are added across both
+ *   domains — safe because agent and workflow executions are distinct resources.
+ * - Cost comes from `getOrgUsageReport` (billing source of truth). NOT from
+ *   summing agent + workflow costs. See AD-DASH-005.
+ *
+ * Follows the same client-side merge pattern as `useRecentActivity`.
+ *
+ * @since Unified Platform Dashboard
+ */
+export function useDashboardSummary(
+  options: UseDashboardSummaryOptions,
+): UseDashboardSummaryReturn {
+  const refetchInterval = options.refetchInterval ?? 60_000;
+
+  const { summary: workflowSummary, isLoading: wfLoading, error: wfError, refetch: wfRefetch } =
+    useWorkflowDashboardSummary({
+      org: options.org,
+      refetchInterval,
+    } satisfies UseWorkflowDashboardSummaryOptions);
+
+  const { summary: agentSummary, isLoading: agLoading, error: agError, refetch: agRefetch } =
+    useAgentExecutionSummary({
+      org: options.org,
+      timeWindow: AgentExecutionSummaryTimeWindow.LAST_7D,
+      refetchInterval,
+    });
+
+  const dateRange = useMemo(() => dateRangeFromPreset("7d"), []);
+  const { report: orgUsage, isLoading: usageLoading, error: usageError, refetch: usageRefetch } =
+    useOrgUsageReport(options.orgId ?? null, dateRange);
+
+  const isLoading = wfLoading || agLoading || usageLoading;
+  const error = wfError ?? agError ?? usageError;
+
+  const summary = useMemo<DashboardSummary | null>(() => {
+    if (isLoading && !workflowSummary && !agentSummary) return null;
+
+    const wfActive = workflowSummary?.activeCount ?? 0;
+    const agActive = agentSummary?.activeCount ?? 0;
+
+    const wfCompleted = workflowSummary?.phaseCounts[WorkflowPhase.EXECUTION_COMPLETED] ?? 0;
+    const agCompleted = agentSummary?.phaseCounts[AgentPhase.EXECUTION_COMPLETED] ?? 0;
+
+    const wfFailed = workflowSummary?.phaseCounts[WorkflowPhase.EXECUTION_FAILED] ?? 0;
+    const agFailed = agentSummary?.phaseCounts[AgentPhase.EXECUTION_FAILED] ?? 0;
+
+    const totalCostMicros = Number(orgUsage?.totalBillableCostMicros ?? BigInt(0));
+    const totalCostUsd = totalCostMicros / 1_000_000;
+
+    return {
+      activeCount: wfActive + agActive,
+      completedCount: wfCompleted + agCompleted,
+      failedCount: wfFailed + agFailed,
+      totalCostUsd,
+      agent: agentSummary,
+      workflow: workflowSummary,
+      orgUsage: orgUsage,
+    };
+  }, [workflowSummary, agentSummary, orgUsage, isLoading]);
+
+  const refetch = useMemo(() => {
+    return () => {
+      wfRefetch();
+      agRefetch();
+      usageRefetch();
+    };
+  }, [wfRefetch, agRefetch, usageRefetch]);
+
+  return { summary, isLoading, error, refetch };
+}