@stigmer/react 0.5.0 → 1.0.0

package/src/workflow/useWorkflowExecutionEventStream.ts

@@ -0,0 +1,244 @@
+"use client";
+
+import {
+  startTransition,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
+import type { WorkflowExecutionEvent } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+import type { WorkflowEventType } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/event_pb";
+import { create } from "@bufbuild/protobuf";
+import {
+  GetEventLogRequestSchema,
+  SubscribeEventsRequestSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/enum_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+import {
+  WorkflowExecutionEventStore,
+  type WorkflowEventStreamState,
+  type DerivedTaskState,
+  type DerivedCostSummary,
+} from "../internal/store";
+
+/** Options for {@link useWorkflowExecutionEventStream}. */
+export interface UseWorkflowExecutionEventStreamOptions {
+  /** Filter to specific event types for the subscription. */
+  readonly eventTypes?: readonly WorkflowEventType[];
+  /**
+   * External store instance. When provided, the hook writes to this
+   * store instead of creating an internal one. Useful for sharing
+   * event state across multiple components.
+   */
+  readonly store?: WorkflowExecutionEventStore;
+  /**
+   * The current execution phase. When provided, the hook uses this to
+   * decide between live streaming (non-terminal) and batch loading
+   * (terminal). When omitted, defaults to live streaming.
+   */
+  readonly executionPhase?: ExecutionPhase;
+}
+
+/** Return value of {@link useWorkflowExecutionEventStream}. */
+export interface UseWorkflowExecutionEventStreamReturn {
+  /** All accumulated events, ordered by sequence_number ascending. */
+  readonly events: readonly WorkflowExecutionEvent[];
+  /** Derived task states from the event log. */
+  readonly taskStates: ReadonlyMap<string, DerivedTaskState>;
+  /** Derived cost/budget summary from the latest checkpoint or aggregation. */
+  readonly costSummary: DerivedCostSummary;
+  /** Stream lifecycle state. */
+  readonly streamState: WorkflowEventStreamState;
+  /** Total tasks declared in the execution_started event. */
+  readonly totalTasks: number;
+  /** `true` while receiving live events. */
+  readonly isStreaming: boolean;
+  /** `true` while connecting to the event stream. */
+  readonly isConnecting: boolean;
+  /** Error from the last failed stream attempt, or `null`. */
+  readonly error: Error | null;
+  /** Re-establish the stream subscription. */
+  readonly reconnect: () => void;
+}
+
+const TERMINAL_PHASES = new Set<ExecutionPhase>([
+  ExecutionPhase.EXECUTION_COMPLETED,
+  ExecutionPhase.EXECUTION_FAILED,
+  ExecutionPhase.EXECUTION_CANCELLED,
+  ExecutionPhase.EXECUTION_TERMINATED,
+]);
+
+/**
+ * Behavior hook that manages a live event stream subscription for a
+ * workflow execution, or batch-loads events for completed executions.
+ *
+ * Internally maintains a {@link WorkflowExecutionEventStore} and
+ * exposes its state via `useSyncExternalStore` for efficient React
+ * integration.
+ *
+ * For running executions: subscribes via `subscribeEvents` with
+ * replay+live-tail. On disconnect, reconnects from the last received
+ * sequence number.
+ *
+ * For terminal executions: loads the full event log via paginated
+ * `getEventLog` calls.
+ *
+ * Pass `null` for `executionId` to skip (stable no-op).
+ */
+export function useWorkflowExecutionEventStream(
+  executionId: string | null,
+  options?: UseWorkflowExecutionEventStreamOptions,
+): UseWorkflowExecutionEventStreamReturn {
+  const stigmer = useStigmer();
+
+  const internalStoreRef = useRef<WorkflowExecutionEventStore | null>(null);
+  if (!options?.store && !internalStoreRef.current) {
+    internalStoreRef.current = new WorkflowExecutionEventStore();
+  }
+  const store = options?.store ?? internalStoreRef.current!;
+
+  const [connectKey, setConnectKey] = useState(0);
+  const reconnect = useCallback(() => {
+    setConnectKey((k) => k + 1);
+  }, []);
+
+  const eventTypes = options?.eventTypes;
+  const executionPhase = options?.executionPhase;
+
+  // Stable ref for values that should not trigger re-subscription
+  const storeRef = useRef(store);
+  storeRef.current = store;
+
+  useEffect(() => {
+    if (!executionId) {
+      store.reset();
+      return;
+    }
+
+    const abortController = new AbortController();
+    const currentStore = storeRef.current;
+    const isTerminal = executionPhase !== undefined && TERMINAL_PHASES.has(executionPhase);
+
+    if (isTerminal) {
+      // Batch-load all events for completed executions
+      currentStore.setStreamState({ stage: "connecting", executionId });
+
+      (async () => {
+        try {
+          let afterSequence = BigInt(0);
+          let hasMore = true;
+
+          while (hasMore && !abortController.signal.aborted) {
+            const resp = await stigmer.workflowExecution.getEventLog(
+              create(GetEventLogRequestSchema, {
+                executionId,
+                afterSequence,
+                eventTypes: eventTypes ? [...eventTypes] : [],
+                pageSize: 500,
+              }),
+            );
+
+            if (abortController.signal.aborted) return;
+
+            startTransition(() => {
+              currentStore.appendEvents(resp.events);
+            });
+
+            hasMore = resp.hasMore;
+            afterSequence = resp.latestSequence;
+          }
+
+          if (!abortController.signal.aborted) {
+            currentStore.setStreamState({ stage: "complete", executionId });
+          }
+        } catch (err) {
+          if (abortController.signal.aborted) return;
+          currentStore.setStreamState({
+            stage: "error",
+            executionId,
+            error: toError(err),
+          });
+        }
+      })();
+    } else {
+      // Live-stream events for running executions
+      currentStore.setStreamState({ stage: "connecting", executionId });
+
+      (async () => {
+        try {
+          const afterSequence = currentStore.getLatestSequence();
+
+          for await (const event of stigmer.workflowExecution.subscribeEvents(
+            create(SubscribeEventsRequestSchema, {
+              executionId,
+              afterSequence,
+              eventTypes: eventTypes ? [...eventTypes] : [],
+            }),
+            abortController.signal,
+          )) {
+            if (abortController.signal.aborted) return;
+
+            startTransition(() => {
+              currentStore.appendEvents([event]);
+              if (currentStore.getStreamState().stage === "connecting") {
+                currentStore.setStreamState({ stage: "streaming", executionId });
+              }
+            });
+          }
+
+          if (!abortController.signal.aborted) {
+            currentStore.setStreamState({ stage: "complete", executionId });
+          }
+        } catch (err) {
+          if (abortController.signal.aborted) return;
+
+          const error = toError(err);
+          const isUnimplemented =
+            error.message.includes("UNIMPLEMENTED") ||
+            error.message.includes("unimplemented");
+
+          if (isUnimplemented) {
+            currentStore.setStreamState({ stage: "unsupported", executionId });
+          } else {
+            currentStore.setStreamState({
+              stage: "error",
+              executionId,
+              error,
+            });
+          }
+        }
+      })();
+    }
+
+    return () => {
+      abortController.abort();
+    };
+  }, [executionId, stigmer, connectKey, executionPhase]);
+
+  // Read from store via useSyncExternalStore
+  const events = useSyncExternalStore(store.subscribe, store.getEvents);
+  const taskStates = useSyncExternalStore(store.subscribe, store.getTaskStates);
+  const costSummary = useSyncExternalStore(store.subscribe, store.getCostSummary);
+  const streamState = useSyncExternalStore(store.subscribe, store.getStreamState);
+  const totalTasks = useSyncExternalStore(store.subscribe, store.getTotalTasks);
+
+  const isStreaming = streamState.stage === "streaming";
+  const isConnecting = streamState.stage === "connecting";
+  const error = streamState.stage === "error" ? streamState.error : null;
+
+  return {
+    events,
+    taskStates,
+    costSummary,
+    streamState,
+    totalTasks,
+    isStreaming,
+    isConnecting,
+    error,
+    reconnect,
+  };
+}

package/src/workflow/useWorkflowExecutionList.ts

@@ -0,0 +1,121 @@
+"use client";
+
+import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { create } from "@bufbuild/protobuf";
+import {
+  ListWorkflowExecutionsRequestSchema,
+  ListWorkflowExecutionsByWorkflowRequestSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Options for {@link useWorkflowExecutionList}. */
+export interface UseWorkflowExecutionListOptions {
+  /** Maximum executions per page. @default 20 */
+  readonly pageSize?: number;
+  /** Opaque page token for cursor-based pagination. */
+  readonly pageToken?: string;
+  /**
+   * Workflow or WorkflowInstance ID to scope executions.
+   * When omitted, lists all executions across all workflows.
+   */
+  readonly workflowId?: string | null;
+}
+
+/** Return value of {@link useWorkflowExecutionList}. */
+export interface UseWorkflowExecutionListReturn {
+  /** Execution entries for the current page. */
+  readonly executions: readonly WorkflowExecution[];
+  /** Total pages available at the current page size. */
+  readonly totalPages: number;
+  /** `true` while the initial fetch or a refetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch from the server. */
+  readonly refetch: () => void;
+}
+
+interface ExecutionListData {
+  executions: readonly WorkflowExecution[];
+  totalPages: number;
+}
+
+const INITIAL_DATA: ExecutionListData = {
+  executions: [],
+  totalPages: 0,
+};
+
+/**
+ * Data hook that fetches a paginated list of workflow executions.
+ *
+ * When `workflowId` is provided, fetches executions for that specific
+ * workflow via `listByWorkflow()`. When omitted, fetches all executions
+ * across all workflows via `list()`.
+ *
+ * @example
+ * ```tsx
+ * // All executions
+ * const { executions, isLoading } = useWorkflowExecutionList();
+ *
+ * // Executions for a specific workflow
+ * const { executions } = useWorkflowExecutionList({
+ *   workflowId: workflow.metadata?.id,
+ *   pageSize: 10,
+ * });
+ * ```
+ */
+export function useWorkflowExecutionList(
+  options?: UseWorkflowExecutionListOptions,
+): UseWorkflowExecutionListReturn {
+  const stigmer = useStigmer();
+  const pageSize = options?.pageSize ?? 20;
+  const pageToken = options?.pageToken ?? "";
+  const workflowId = options?.workflowId ?? null;
+
+  const fetchFn = async () => {
+    if (workflowId) {
+      const resp = await stigmer.workflowExecution.listByWorkflow(
+        create(ListWorkflowExecutionsByWorkflowRequestSchema, {
+          workflowId,
+          pageSize,
+          pageToken,
+        }),
+      );
+      return {
+        executions: [...resp.entries],
+        totalPages: resp.totalPages,
+      };
+    }
+
+    const resp = await stigmer.workflowExecution.list(
+      create(ListWorkflowExecutionsRequestSchema, {
+        pageSize,
+        pageToken,
+      }),
+    );
+    return {
+      executions: [...resp.entries],
+      totalPages: resp.totalPages,
+    };
+  };
+
+  const {
+    data,
+    isLoading,
+    isRefetching,
+    error,
+    refetch,
+  } = useFetch<ExecutionListData>(fetchFn, [stigmer, workflowId, pageSize, pageToken], INITIAL_DATA);
+
+  return {
+    executions: data.executions,
+    totalPages: data.totalPages,
+    isLoading,
+    isRefetching,
+    error,
+    refetch,
+  };
+}

package/src/workflow/useWorkflowInstances.ts

@@ -0,0 +1,62 @@
+"use client";
+
+import type { WorkflowInstance } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
+import { create } from "@bufbuild/protobuf";
+import { GetWorkflowInstancesByWorkflowRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Return value of {@link useWorkflowInstances}. */
+export interface UseWorkflowInstancesReturn {
+  /** Instances for the given workflow, or empty array while loading. */
+  readonly instances: readonly WorkflowInstance[];
+  /** `true` while the initial fetch or a refetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight and stale data is shown. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch instances from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches all instances for a specific workflow.
+ *
+ * Wraps `stigmer.workflowInstance.getByWorkflow()` with loading
+ * and error state management. Used on the Workflow detail page
+ * "Instances" tab to show environment-bound deployments.
+ *
+ * Pass `null` as `workflowId` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { instances, isLoading } = useWorkflowInstances(workflow.metadata?.id);
+ * ```
+ */
+export function useWorkflowInstances(
+  workflowId: string | null | undefined,
+): UseWorkflowInstancesReturn {
+  const stigmer = useStigmer();
+
+  const fetchFn = workflowId
+    ? async () => {
+        const resp = await stigmer.workflowInstance.getByWorkflow(
+          create(GetWorkflowInstancesByWorkflowRequestSchema, {
+            workflowId,
+          }),
+        );
+        return resp.entries ? [...resp.entries] : [];
+      }
+    : null;
+
+  const {
+    data: instances,
+    isLoading,
+    isRefetching,
+    error,
+    refetch,
+  } = useFetch<readonly WorkflowInstance[]>(fetchFn, [workflowId, stigmer], []);
+
+  return { instances, isLoading, isRefetching, error, refetch };
+}

package/src/workflow/useWorkflowList.ts

@@ -0,0 +1,79 @@
+"use client";
+
+import { useCallback } from "react";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useResourceList, type ResourceListScope } from "../search";
+
+/** Options for {@link useWorkflowList}. */
+export interface UseWorkflowListOptions {
+  /** Maximum workflows per page. @default 20 */
+  readonly pageSize?: number;
+  /** Page number (1-indexed). @default 1 */
+  readonly page?: number;
+  /** Text query to filter workflows by name, description, or tags. */
+  readonly query?: string;
+  /**
+   * Controls which workflows are visible.
+   *
+   * - `"org"` — only workflows owned by the given organization.
+   * - `"all"` — includes public/platform workflows.
+   *
+   * @default "org"
+   */
+  readonly scope?: ResourceListScope;
+}
+
+/** Return value of {@link useWorkflowList}. */
+export interface UseWorkflowListReturn {
+  /** Paginated workflow entries for the current page. */
+  readonly workflows: readonly SearchResult[];
+  /** Total number of workflows matching the current filters. */
+  readonly totalCount: number;
+  /** Total pages available at the current page size. */
+  readonly totalPages: number;
+  /** The current page number (mirrors the `page` option). */
+  readonly currentPage: number;
+  /** `true` while the initial fetch or a refetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch the current page from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches a paginated list of workflows for the Workflows section.
+ *
+ * Wraps `stigmer.workflow.list()` with pagination, scope filtering,
+ * and text search. All parameters are externally controlled — the
+ * consumer manages page state, query debouncing, and scope toggling.
+ *
+ * Pass `null` as `org` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { workflows, totalCount, isLoading } = useWorkflowList("acme", {
+ *   page: 1,
+ *   pageSize: 20,
+ *   scope: "org",
+ * });
+ * ```
+ */
+export function useWorkflowList(
+  org: string | null,
+  options?: UseWorkflowListOptions,
+): UseWorkflowListReturn {
+  const stigmer = useStigmer();
+
+  const listFn = useCallback(
+    (params: Parameters<typeof stigmer.workflow.list>[0]) =>
+      stigmer.workflow.list(params),
+    [stigmer],
+  );
+
+  const { entries, totalCount, totalPages, currentPage, isLoading, error, refetch } =
+    useResourceList(listFn, org, options);
+
+  return { workflows: entries, totalCount, totalPages, currentPage, isLoading, error, refetch };
+}

package/src/workflow/useWorkflowSave.ts

@@ -0,0 +1,84 @@
+"use client";
+
+import { useCallback, useMemo, useRef, useState } from "react";
+import { useStigmer } from "../hooks";
+import { parseWorkflowYaml } from "./serialize-workflow-yaml";
+
+/** Return value of {@link useWorkflowSave}. */
+export interface UseWorkflowSaveReturn {
+  /**
+   * Parse the YAML and call `workflow.apply()` on the server.
+   * Returns `true` on success, `false` on failure (check `error`).
+   */
+  readonly save: (yaml: string) => Promise<boolean>;
+  /** `true` while a save request is in flight. */
+  readonly isSaving: boolean;
+  /** Error from the last failed save, or `null` on success. */
+  readonly error: Error | null;
+}
+
+/**
+ * Behavior hook that persists workflow YAML to the server via `apply()`.
+ *
+ * Parses the YAML into a `WorkflowInput`, calls `stigmer.workflow.apply()`,
+ * and returns success/failure state. Handles UNIMPLEMENTED gracefully
+ * (backend not yet deployed) with a descriptive error message.
+ *
+ * @param org - Organization slug for the target workflow.
+ *
+ * @since T10 (YAML Editor with Graph Preview)
+ */
+export function useWorkflowSave(org: string): UseWorkflowSaveReturn {
+  const stigmer = useStigmer();
+  const [isSaving, setIsSaving] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const orgRef = useRef(org);
+  orgRef.current = org;
+
+  const save = useCallback(
+    async (yaml: string): Promise<boolean> => {
+      setIsSaving(true);
+      setError(null);
+
+      try {
+        const input = parseWorkflowYaml(yaml, orgRef.current);
+        await stigmer.workflow.apply(input);
+        return true;
+      } catch (err) {
+        const wrapped =
+          err instanceof Error ? err : new Error(String(err));
+
+        if (isUnimplementedError(err)) {
+          setError(
+            new Error(
+              "Workflow save is not yet available on this server. " +
+                "The workflow was validated locally but could not be persisted.",
+            ),
+          );
+        } else {
+          setError(wrapped);
+        }
+        return false;
+      } finally {
+        setIsSaving(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return useMemo(() => ({ save, isSaving, error }), [save, isSaving, error]);
+}
+
+/**
+ * Detect gRPC UNIMPLEMENTED (code 12) from a Connect error or
+ * a StigmerError wrapping one. The SDK's CODE_MAP doesn't include
+ * Unimplemented so it surfaces as "unknown" — check connectCode.
+ */
+function isUnimplementedError(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  if ("connectCode" in err && (err as { connectCode: number }).connectCode === 12) {
+    return true;
+  }
+  const msg = (err as { message?: string }).message ?? "";
+  return msg.includes("[unimplemented]") || msg.includes("UNIMPLEMENTED");
+}