@stigmer/react 1.0.3 → 2.0.0

package/src/workflow/execution-comparison/derive-execution-comparison.ts

@@ -0,0 +1,146 @@
+import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import type { WorkflowTask } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { WorkflowTaskStatus } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { deriveExecutionRow } from "../execution-history/derive-execution-row";
+import type { TaskComparison, ExecutionComparison } from "./types";
+
+const BIGINT_ZERO = BigInt(0);
+
+function parseIsoMs(iso: string | undefined): number | null {
+  if (!iso) return null;
+  const t = new Date(iso).getTime();
+  return Number.isNaN(t) ? null : t;
+}
+
+function taskDurationMs(task: WorkflowTask): number | null {
+  const start = parseIsoMs(task.startedAt);
+  const end = parseIsoMs(task.completedAt);
+  if (start == null || end == null) return null;
+  return end - start;
+}
+
+function taskKindLabel(task: WorkflowTask): string {
+  return task.taskType != null ? String(task.taskType) : "";
+}
+
+function indexTasksByName(
+  tasks: readonly WorkflowTask[],
+): ReadonlyMap<string, WorkflowTask> {
+  const map = new Map<string, WorkflowTask>();
+  for (const t of tasks) {
+    if (t.taskName) {
+      map.set(t.taskName, t);
+    }
+  }
+  return map;
+}
+
+/**
+ * Derives a structural comparison between two workflow executions.
+ *
+ * Pure function with zero side effects. Aligns tasks by `taskName`
+ * (stable within the same workflow version) and computes deltas for
+ * duration, cost, tokens, and status across all matched tasks.
+ *
+ * When workflow definitions differ between runs, unmatched tasks are
+ * reported in `tasksOnlyInBase` and `tasksOnlyInCompare`.
+ */
+export function deriveExecutionComparison(
+  base: WorkflowExecution,
+  compare: WorkflowExecution,
+): ExecutionComparison {
+  const baseRow = deriveExecutionRow(base);
+  const compareRow = deriveExecutionRow(compare);
+
+  const baseTasks = base.status?.tasks ?? [];
+  const compareTasks = compare.status?.tasks ?? [];
+
+  const baseByName = indexTasksByName(baseTasks);
+  const compareByName = indexTasksByName(compareTasks);
+
+  const allNames = new Set<string>();
+  baseByName.forEach((_v, name) => allNames.add(name));
+  compareByName.forEach((_v, name) => allNames.add(name));
+
+  const tasks: TaskComparison[] = [];
+  const tasksOnlyInBase: string[] = [];
+  const tasksOnlyInCompare: string[] = [];
+  let divergencePoint: string | null = null;
+
+  const orderedNames = Array.from(allNames).sort((a, b) => {
+    const aIdx = baseTasks.findIndex((t) => t.taskName === a);
+    const bIdx = baseTasks.findIndex((t) => t.taskName === b);
+    const aOrder = aIdx >= 0 ? aIdx : compareTasks.findIndex((t) => t.taskName === a);
+    const bOrder = bIdx >= 0 ? bIdx : compareTasks.findIndex((t) => t.taskName === b);
+    return aOrder - bOrder;
+  });
+
+  for (const name of orderedNames) {
+    const baseTask = baseByName.get(name);
+    const compareTask = compareByName.get(name);
+
+    if (baseTask && !compareTask) {
+      tasksOnlyInBase.push(name);
+      continue;
+    }
+    if (!baseTask && compareTask) {
+      tasksOnlyInCompare.push(name);
+      continue;
+    }
+    if (!baseTask || !compareTask) continue;
+
+    const baseStatus = baseTask.status ?? WorkflowTaskStatus.WORKFLOW_TASK_STATUS_UNSPECIFIED;
+    const compareStatus = compareTask.status ?? WorkflowTaskStatus.WORKFLOW_TASK_STATUS_UNSPECIFIED;
+    const statusChanged = baseStatus !== compareStatus;
+
+    const baseDurationMs = taskDurationMs(baseTask);
+    const compareDurationMs = taskDurationMs(compareTask);
+    const durationDeltaMs =
+      baseDurationMs != null && compareDurationMs != null
+        ? baseDurationMs - compareDurationMs
+        : null;
+
+    const baseCostMicros = BigInt(baseTask.costMicros ?? 0);
+    const compareCostMicros = BigInt(compareTask.costMicros ?? 0);
+    const baseTokens = BigInt(baseTask.inputTokens ?? 0) + BigInt(baseTask.outputTokens ?? 0);
+    const compareTokens = BigInt(compareTask.inputTokens ?? 0) + BigInt(compareTask.outputTokens ?? 0);
+
+    if (statusChanged && divergencePoint === null) {
+      divergencePoint = name;
+    }
+
+    tasks.push({
+      taskName: name,
+      taskKind: taskKindLabel(baseTask),
+      baseStatus,
+      compareStatus,
+      statusChanged,
+      baseDurationMs,
+      compareDurationMs,
+      durationDeltaMs,
+      baseCostMicros,
+      compareCostMicros,
+      baseTokens,
+      compareTokens,
+      baseError: baseTask.error || null,
+      compareError: compareTask.error || null,
+    });
+  }
+
+  const durationDeltaMs =
+    baseRow.durationMs != null && compareRow.durationMs != null
+      ? baseRow.durationMs - compareRow.durationMs
+      : null;
+
+  return {
+    baseRow,
+    compareRow,
+    durationDeltaMs,
+    costDeltaMicros: baseRow.costMicros - compareRow.costMicros,
+    tokensDelta: baseRow.totalTokens - compareRow.totalTokens,
+    tasks,
+    tasksOnlyInBase,
+    tasksOnlyInCompare,
+    divergencePoint,
+  };
+}

package/src/workflow/execution-comparison/index.ts

@@ -0,0 +1,23 @@
+export type { TaskComparison, ExecutionComparison } from "./types";
+export { deriveExecutionComparison } from "./derive-execution-comparison";
+export {
+  useExecutionComparison,
+  type UseExecutionComparisonOptions,
+  type UseExecutionComparisonReturn,
+} from "./useExecutionComparison";
+export {
+  ExecutionComparisonPicker,
+  type ExecutionComparisonPickerProps,
+} from "./ExecutionComparisonPicker";
+export {
+  ComparisonSummaryCards,
+  type ComparisonSummaryCardsProps,
+} from "./ComparisonSummaryCards";
+export {
+  TaskComparisonTable,
+  type TaskComparisonTableProps,
+} from "./TaskComparisonTable";
+export {
+  ExecutionComparisonView,
+  type ExecutionComparisonViewProps,
+} from "./ExecutionComparisonView";

package/src/workflow/execution-comparison/types.ts

@@ -0,0 +1,57 @@
+import type { WorkflowTaskStatus } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import type { ExecutionRow } from "../execution-history/derive-execution-row";
+
+/**
+ * Per-task comparison entry aligning the same task across two executions.
+ *
+ * Tasks are matched by `taskName` (stable across runs of the same workflow
+ * version). When the workflow definition changed between runs, unmatched
+ * tasks appear in {@link ExecutionComparison.tasksOnlyInBase} or
+ * {@link ExecutionComparison.tasksOnlyInCompare}.
+ */
+export interface TaskComparison {
+  readonly taskName: string;
+  readonly taskKind: string;
+  readonly baseStatus: WorkflowTaskStatus;
+  readonly compareStatus: WorkflowTaskStatus;
+  readonly statusChanged: boolean;
+  readonly baseDurationMs: number | null;
+  readonly compareDurationMs: number | null;
+  /** Positive = base was slower, negative = compare was slower. */
+  readonly durationDeltaMs: number | null;
+  readonly baseCostMicros: bigint;
+  readonly compareCostMicros: bigint;
+  readonly baseTokens: bigint;
+  readonly compareTokens: bigint;
+  readonly baseError: string | null;
+  readonly compareError: string | null;
+}
+
+/**
+ * Complete comparison result between two workflow executions.
+ *
+ * Produced by {@link deriveExecutionComparison} — a pure function with
+ * zero side effects that aligns tasks by name and computes deltas for
+ * all numeric dimensions.
+ */
+export interface ExecutionComparison {
+  readonly baseRow: ExecutionRow;
+  readonly compareRow: ExecutionRow;
+  /** Positive = base was slower. `null` when either duration is unavailable. */
+  readonly durationDeltaMs: number | null;
+  /** Positive = base cost more. */
+  readonly costDeltaMicros: bigint;
+  /** Positive = base used more tokens. */
+  readonly tokensDelta: bigint;
+  /** Per-task aligned comparison entries (matched by task_name). */
+  readonly tasks: readonly TaskComparison[];
+  /** Task names present in base but absent in compare (workflow version drift). */
+  readonly tasksOnlyInBase: readonly string[];
+  /** Task names present in compare but absent in base (workflow version drift). */
+  readonly tasksOnlyInCompare: readonly string[];
+  /**
+   * Name of the first task (in execution order) where status diverges
+   * between the two runs. `null` when all matched tasks have identical statuses.
+   */
+  readonly divergencePoint: string | null;
+}

package/src/workflow/execution-comparison/useExecutionComparison.ts

@@ -0,0 +1,87 @@
+"use client";
+
+import { useMemo } from "react";
+import { useWorkflowExecution } from "../useWorkflowExecution";
+import { deriveExecutionComparison } from "./derive-execution-comparison";
+import type { ExecutionComparison } from "./types";
+
+/** Options for {@link useExecutionComparison}. */
+export interface UseExecutionComparisonOptions {
+  /** The "baseline" execution ID (typically the run being viewed). */
+  readonly baseId: string | null;
+  /** The "compare" execution ID (typically a recent successful run). */
+  readonly compareId: string | null;
+}
+
+/** Return value of {@link useExecutionComparison}. */
+export interface UseExecutionComparisonReturn {
+  /** Derived comparison result, or `null` while loading or on error. */
+  readonly comparison: ExecutionComparison | null;
+  /** `true` while either execution is being fetched. */
+  readonly isLoading: boolean;
+  /** First error from either fetch, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Re-fetch both executions. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Behavior hook that fetches two workflow executions and derives
+ * a structural comparison between them.
+ *
+ * Pass `null` for either ID to skip that fetch (e.g., while the
+ * user is selecting a comparison target). The comparison result
+ * is only produced when both executions are loaded.
+ *
+ * Returns referentially stable objects when inputs haven't changed
+ * (DD-010 compliance).
+ *
+ * @example
+ * ```tsx
+ * const { comparison, isLoading } = useExecutionComparison({
+ *   baseId: "wfx_failed_123",
+ *   compareId: "wfx_success_456",
+ * });
+ * if (comparison) {
+ *   console.log(comparison.divergencePoint);
+ * }
+ * ```
+ */
+export function useExecutionComparison({
+  baseId,
+  compareId,
+}: UseExecutionComparisonOptions): UseExecutionComparisonReturn {
+  const {
+    execution: baseExecution,
+    isLoading: baseLoading,
+    error: baseError,
+    refetch: baseRefetch,
+  } = useWorkflowExecution(baseId);
+
+  const {
+    execution: compareExecution,
+    isLoading: compareLoading,
+    error: compareError,
+    refetch: compareRefetch,
+  } = useWorkflowExecution(compareId);
+
+  const comparison = useMemo(() => {
+    if (!baseExecution || !compareExecution) return null;
+    return deriveExecutionComparison(baseExecution, compareExecution);
+  }, [baseExecution, compareExecution]);
+
+  const refetch = useMemo(
+    () => () => {
+      baseRefetch();
+      compareRefetch();
+    },
+    [baseRefetch, compareRefetch],
+  );
+
+  return {
+    comparison,
+    isLoading: baseLoading || compareLoading,
+    error: baseError ?? compareError ?? null,
+    refetch,
+  };
+}

package/src/workflow/execution-history/ExecutionFilterBar.tsx

@@ -0,0 +1,298 @@
+"use client";
+
+import { memo, useCallback, useMemo, useState } from "react";
+import { cn } from "@stigmer/theme";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import type { ExecutionClientFilters } from "./derive-execution-row";
+
+// ---------------------------------------------------------------------------
+// Phase chip config
+// ---------------------------------------------------------------------------
+
+const PHASE_CHIPS: ReadonlyArray<{ phase: ExecutionPhase; label: string }> = [
+  { phase: ExecutionPhase.EXECUTION_COMPLETED, label: "Completed" },
+  { phase: ExecutionPhase.EXECUTION_FAILED, label: "Failed" },
+  { phase: ExecutionPhase.EXECUTION_IN_PROGRESS, label: "Running" },
+  { phase: ExecutionPhase.EXECUTION_PENDING, label: "Pending" },
+  { phase: ExecutionPhase.EXECUTION_CANCELLED, label: "Cancelled" },
+  { phase: ExecutionPhase.EXECUTION_PAUSED, label: "Paused" },
+];
+
+// ---------------------------------------------------------------------------
+// Duration preset config
+// ---------------------------------------------------------------------------
+
+interface DurationPreset {
+  readonly label: string;
+  readonly minMs?: number;
+  readonly maxMs?: number;
+}
+
+const DURATION_PRESETS: readonly DurationPreset[] = [
+  { label: "< 1s", maxMs: 1_000 },
+  { label: "< 10s", maxMs: 10_000 },
+  { label: "< 1m", maxMs: 60_000 },
+  { label: "< 10m", maxMs: 600_000 },
+  { label: "> 10m", minMs: 600_000 },
+];
+
+// ---------------------------------------------------------------------------
+// Cost preset config
+// ---------------------------------------------------------------------------
+
+interface CostPreset {
+  readonly label: string;
+  readonly minMicros?: bigint;
+  readonly maxMicros?: bigint;
+}
+
+const COST_PRESETS: readonly CostPreset[] = [
+  { label: "Free", maxMicros: BigInt(0) },
+  { label: "< $0.10", maxMicros: BigInt(100_000) },
+  { label: "< $1", maxMicros: BigInt(1_000_000) },
+  { label: "< $10", maxMicros: BigInt(10_000_000) },
+  { label: "> $10", minMicros: BigInt(10_000_000) },
+];
+
+// ---------------------------------------------------------------------------
+// Props
+// ---------------------------------------------------------------------------
+
+/** Props for {@link ExecutionFilterBar}. */
+export interface ExecutionFilterBarProps {
+  /** Current active filters (controlled). */
+  readonly filters: ExecutionClientFilters;
+  /** Called when any filter changes. */
+  readonly onFiltersChange: (filters: ExecutionClientFilters) => void;
+  /** Additional CSS classes for the root container. */
+  readonly className?: string;
+}
+
+/**
+ * Horizontal filter bar for the execution history table.
+ *
+ * Renders phase chips, duration presets, cost presets, a "has retries"
+ * toggle, and a clear-all button. Each filter maps to an
+ * {@link ExecutionClientFilters} field.
+ *
+ * Fully controlled: the parent owns the filter state.
+ *
+ * @example
+ * ```tsx
+ * const [filters, setFilters] = useState<ExecutionClientFilters>({});
+ * <ExecutionFilterBar filters={filters} onFiltersChange={setFilters} />
+ * ```
+ */
+export const ExecutionFilterBar = memo(function ExecutionFilterBar({
+  filters,
+  onFiltersChange,
+  className,
+}: ExecutionFilterBarProps) {
+  const [showMore, setShowMore] = useState(false);
+
+  const activePhases = useMemo(
+    () => new Set(filters.phases ?? []),
+    [filters.phases],
+  );
+
+  const togglePhase = useCallback(
+    (phase: ExecutionPhase) => {
+      const next = new Set(activePhases);
+      if (next.has(phase)) {
+        next.delete(phase);
+      } else {
+        next.add(phase);
+      }
+      onFiltersChange({
+        ...filters,
+        phases: next.size > 0 ? [...next] : undefined,
+      });
+    },
+    [activePhases, filters, onFiltersChange],
+  );
+
+  const activeDurationIdx = useMemo(() => {
+    return DURATION_PRESETS.findIndex(
+      (p) =>
+        p.minMs === filters.minDurationMs && p.maxMs === filters.maxDurationMs,
+    );
+  }, [filters.minDurationMs, filters.maxDurationMs]);
+
+  const setDuration = useCallback(
+    (idx: number) => {
+      if (idx === activeDurationIdx) {
+        onFiltersChange({ ...filters, minDurationMs: undefined, maxDurationMs: undefined });
+      } else {
+        const preset = DURATION_PRESETS[idx];
+        onFiltersChange({
+          ...filters,
+          minDurationMs: preset.minMs,
+          maxDurationMs: preset.maxMs,
+        });
+      }
+    },
+    [activeDurationIdx, filters, onFiltersChange],
+  );
+
+  const activeCostIdx = useMemo(() => {
+    return COST_PRESETS.findIndex(
+      (p) =>
+        p.minMicros === filters.minCostMicros && p.maxMicros === filters.maxCostMicros,
+    );
+  }, [filters.minCostMicros, filters.maxCostMicros]);
+
+  const setCost = useCallback(
+    (idx: number) => {
+      if (idx === activeCostIdx) {
+        onFiltersChange({ ...filters, minCostMicros: undefined, maxCostMicros: undefined });
+      } else {
+        const preset = COST_PRESETS[idx];
+        onFiltersChange({
+          ...filters,
+          minCostMicros: preset.minMicros,
+          maxCostMicros: preset.maxMicros,
+        });
+      }
+    },
+    [activeCostIdx, filters, onFiltersChange],
+  );
+
+  const toggleRetries = useCallback(() => {
+    onFiltersChange({ ...filters, hasRetries: filters.hasRetries ? undefined : true });
+  }, [filters, onFiltersChange]);
+
+  const clearAll = useCallback(() => {
+    onFiltersChange({});
+  }, [onFiltersChange]);
+
+  const activeCount =
+    (activePhases.size > 0 ? 1 : 0) +
+    (activeDurationIdx >= 0 ? 1 : 0) +
+    (activeCostIdx >= 0 ? 1 : 0) +
+    (filters.hasRetries ? 1 : 0) +
+    (filters.failedTaskName ? 1 : 0);
+
+  return (
+    <div
+      role="toolbar"
+      aria-label="Execution filters"
+      className={cn("flex flex-col gap-2", className)}
+    >
+      {/* Row 1: Phase chips */}
+      <div className="flex flex-wrap items-center gap-1.5">
+        <span className="mr-1 text-[11px] font-medium text-[var(--stgm-muted-foreground,#737373)]">
+          Status
+        </span>
+        {PHASE_CHIPS.map(({ phase, label }) => (
+          <FilterChip
+            key={phase}
+            label={label}
+            isActive={activePhases.has(phase)}
+            onClick={() => togglePhase(phase)}
+          />
+        ))}
+
+        {!showMore && (
+          <button
+            type="button"
+            onClick={() => setShowMore(true)}
+            className="ml-2 text-[11px] font-medium text-[var(--stgm-primary,#6366f1)] hover:underline"
+          >
+            More filters
+          </button>
+        )}
+
+        {activeCount > 0 && (
+          <button
+            type="button"
+            onClick={clearAll}
+            className="ml-auto text-[11px] font-medium text-[var(--stgm-muted-foreground,#737373)] hover:text-[var(--stgm-foreground,#1a1a2e)]"
+          >
+            Clear all ({activeCount})
+          </button>
+        )}
+      </div>
+
+      {/* Row 2: Additional filters (shown on "More filters") */}
+      {showMore && (
+        <div className="flex flex-wrap items-center gap-x-4 gap-y-2">
+          <FilterGroup label="Duration">
+            {DURATION_PRESETS.map((preset, idx) => (
+              <FilterChip
+                key={preset.label}
+                label={preset.label}
+                isActive={idx === activeDurationIdx}
+                onClick={() => setDuration(idx)}
+              />
+            ))}
+          </FilterGroup>
+
+          <FilterGroup label="Cost">
+            {COST_PRESETS.map((preset, idx) => (
+              <FilterChip
+                key={preset.label}
+                label={preset.label}
+                isActive={idx === activeCostIdx}
+                onClick={() => setCost(idx)}
+              />
+            ))}
+          </FilterGroup>
+
+          <FilterChip
+            label="Has retries"
+            isActive={!!filters.hasRetries}
+            onClick={toggleRetries}
+          />
+        </div>
+      )}
+    </div>
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Sub-components
+// ---------------------------------------------------------------------------
+
+function FilterChip({
+  label,
+  isActive,
+  onClick,
+}: {
+  readonly label: string;
+  readonly isActive: boolean;
+  readonly onClick: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-pressed={isActive}
+      className={cn(
+        "rounded-full px-2.5 py-0.5 text-[11px] font-medium transition-colors",
+        "border focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-[var(--stgm-ring,#6366f1)]",
+        isActive
+          ? "border-transparent bg-[var(--stgm-primary,#6366f1)] text-[var(--stgm-primary-foreground,#fff)]"
+          : "border-[var(--stgm-border,#d4d4d8)] bg-[var(--stgm-background,#fff)] text-[var(--stgm-foreground,#1a1a2e)] hover:bg-[var(--stgm-accent,#f5f5f5)]",
+      )}
+    >
+      {label}
+    </button>
+  );
+}
+
+function FilterGroup({
+  label,
+  children,
+}: {
+  readonly label: string;
+  readonly children: React.ReactNode;
+}) {
+  return (
+    <div className="flex items-center gap-1.5">
+      <span className="mr-0.5 text-[11px] font-medium text-[var(--stgm-muted-foreground,#737373)]">
+        {label}
+      </span>
+      {children}
+    </div>
+  );
+}