@stigmer/react 0.5.1 → 1.0.0

package/src/workflow/useWorkflowCount.ts

@@ -0,0 +1,66 @@
+"use client";
+
+import { useCallback } from "react";
+import { useStigmer } from "../hooks";
+import { useResourceCount, type ResourceListScope } from "../search";
+
+/** Options for {@link useWorkflowCount}. */
+export interface UseWorkflowCountOptions {
+  /** Text query to filter workflows before counting. */
+  readonly query?: string;
+  /**
+   * Controls which workflows are counted.
+   *
+   * - `"org"` — only workflows owned by the given organization.
+   * - `"all"` — includes public/platform workflows.
+   *
+   * @default "org"
+   */
+  readonly scope?: ResourceListScope;
+}
+
+/** Return value of {@link useWorkflowCount}. */
+export interface UseWorkflowCountReturn {
+  /**
+   * Total number of workflows matching the current filters. `undefined`
+   * until the first successful fetch completes.
+   */
+  readonly count: number | undefined;
+  /** `true` while the count fetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error message from the last failed fetch, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Re-fetch the count with the same parameters. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches the total count of workflows.
+ *
+ * Issues a minimal `stigmer.workflow.list()` call to retrieve only the
+ * total count — no workflow entries are returned or stored. Useful for
+ * summary cards, badges, and dashboard widgets.
+ *
+ * For the full paginated workflow list, use {@link useWorkflowList} instead.
+ *
+ * Pass `null` as `org` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { count, isLoading } = useWorkflowCount("acme");
+ * ```
+ */
+export function useWorkflowCount(
+  org: string | null,
+  options?: UseWorkflowCountOptions,
+): UseWorkflowCountReturn {
+  const stigmer = useStigmer();
+
+  const listFn = useCallback(
+    (params: Parameters<typeof stigmer.workflow.list>[0]) =>
+      stigmer.workflow.list(params),
+    [stigmer],
+  );
+
+  return useResourceCount(listFn, org, options);
+}

package/src/workflow/useWorkflowDashboardSummary.ts

@@ -0,0 +1,71 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import type { ExecutionSummary } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import {
+  GetExecutionSummaryRequestSchema,
+  SummaryTimeWindow,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+export type { SummaryTimeWindow };
+
+export interface UseWorkflowDashboardSummaryOptions {
+  /** Organization slug. When empty, the hook does not fetch. */
+  readonly org: string | null | undefined;
+  /** Time window for aggregation. @default SUMMARY_TIME_WINDOW_LAST_7D */
+  readonly timeWindow?: SummaryTimeWindow;
+  /** Refetch interval in milliseconds. `0` or `false` disables. @default 0 */
+  readonly refetchInterval?: number | false;
+}
+
+export interface UseWorkflowDashboardSummaryReturn {
+  readonly summary: ExecutionSummary | null;
+  readonly isLoading: boolean;
+  readonly isRefetching: boolean;
+  readonly error: Error | null;
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches aggregated execution statistics for an organization.
+ *
+ * Returns phase counts, cost totals, average duration, top failing workflows,
+ * and per-workflow cost breakdowns — scoped to a configurable time window.
+ *
+ * @example
+ * ```tsx
+ * const { summary, isLoading } = useWorkflowDashboardSummary({
+ *   org: "acme",
+ *   timeWindow: SummaryTimeWindow.SUMMARY_TIME_WINDOW_LAST_7D,
+ * });
+ * ```
+ */
+export function useWorkflowDashboardSummary(
+  options: UseWorkflowDashboardSummaryOptions,
+): UseWorkflowDashboardSummaryReturn {
+  const stigmer = useStigmer();
+  const org = options.org ?? "";
+  const timeWindow =
+    options.timeWindow ?? SummaryTimeWindow.LAST_7D;
+  const refetchInterval = options.refetchInterval ?? 0;
+
+  const fetchFn = org
+    ? async () => {
+        return await stigmer.workflowExecution.getExecutionSummary(
+          create(GetExecutionSummaryRequestSchema, { org, timeWindow }),
+        );
+      }
+    : null;
+
+  const { data, isLoading, isRefetching, error, refetch } =
+    useFetch<ExecutionSummary | null>(
+      fetchFn,
+      [stigmer, org, timeWindow],
+      null,
+      { refetchInterval: refetchInterval || false },
+    );
+
+  return { summary: data, isLoading, isRefetching, error, refetch };
+}

package/src/workflow/useWorkflowEditor.ts

@@ -0,0 +1,106 @@
+"use client";
+
+import { useCallback, useMemo, useRef, useState } from "react";
+import type { Diagnostic } from "@codemirror/lint";
+import { useWorkflowValidation } from "./useWorkflowValidation";
+import { useWorkflowTopology } from "./useWorkflowTopology";
+import { useWorkflowSave } from "./useWorkflowSave";
+import { useTaskKindRegistryContext } from "./TaskKindRegistryContext";
+import { useTaskKindRegistry } from "./useTaskKindRegistry";
+
+/** Options for {@link useWorkflowEditor}. */
+export interface UseWorkflowEditorOptions {
+  /** Organization slug for the save path. */
+  readonly org: string;
+}
+
+/** Return value of {@link useWorkflowEditor}. */
+export interface UseWorkflowEditorReturn {
+  /** Current YAML content in the editor. */
+  readonly yaml: string;
+  /** Update the YAML content (called by the editor on change). */
+  readonly setYaml: (value: string) => void;
+  /** CodeMirror-compatible diagnostics from the validation pipeline. */
+  readonly diagnostics: readonly Diagnostic[];
+  /** `true` when the editor content differs from the initial value. */
+  readonly isDirty: boolean;
+  /** `true` while a save request is in flight. */
+  readonly isSaving: boolean;
+  /** Error from the last failed save, or `null` on success. */
+  readonly saveError: Error | null;
+  /** Persist the current YAML to the server. Returns `true` on success. */
+  readonly save: () => Promise<boolean>;
+  /** Reset the editor to the initial YAML (discards changes). */
+  readonly reset: () => void;
+  /** Topology data for the graph preview. */
+  readonly topology: ReturnType<typeof useWorkflowTopology>;
+  /** Count of error-level diagnostics. */
+  readonly errorCount: number;
+  /** Count of warning-level diagnostics. */
+  readonly warningCount: number;
+}
+
+/**
+ * Behavior hook that orchestrates the workflow YAML editor experience.
+ *
+ * Composes the validation pipeline, topology computation, and save logic
+ * into a single return value that the `WorkflowEditorView` renders.
+ *
+ * @param initialYaml - The YAML string to initialize the editor with.
+ * @param options - Editor configuration (organization slug).
+ *
+ * @since T10 (YAML Editor with Graph Preview)
+ */
+export function useWorkflowEditor(
+  initialYaml: string,
+  options: UseWorkflowEditorOptions,
+): UseWorkflowEditorReturn {
+  const [yaml, setYaml] = useState(initialYaml);
+  const initialRef = useRef(initialYaml);
+
+  const registry = useTaskKindRegistry();
+  const { diagnostics } = useWorkflowValidation(yaml, registry);
+  const topology = useWorkflowTopology(yaml);
+  const { save: applySave, isSaving, error: saveError } = useWorkflowSave(options.org);
+
+  const isDirty = yaml !== initialRef.current;
+
+  const save = useCallback(async (): Promise<boolean> => {
+    const success = await applySave(yaml);
+    if (success) {
+      initialRef.current = yaml;
+    }
+    return success;
+  }, [applySave, yaml]);
+
+  const reset = useCallback(() => {
+    setYaml(initialRef.current);
+  }, []);
+
+  const errorCount = useMemo(
+    () => diagnostics.filter((d) => d.severity === "error").length,
+    [diagnostics],
+  );
+
+  const warningCount = useMemo(
+    () => diagnostics.filter((d) => d.severity === "warning").length,
+    [diagnostics],
+  );
+
+  return useMemo(
+    () => ({
+      yaml,
+      setYaml,
+      diagnostics,
+      isDirty,
+      isSaving,
+      saveError,
+      save,
+      reset,
+      topology,
+      errorCount,
+      warningCount,
+    }),
+    [yaml, setYaml, diagnostics, isDirty, isSaving, saveError, save, reset, topology, errorCount, warningCount],
+  );
+}

package/src/workflow/useWorkflowExecution.ts

@@ -0,0 +1,67 @@
+"use client";
+
+import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import { isNotFound } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Return value of {@link useWorkflowExecution}. */
+export interface UseWorkflowExecutionReturn {
+  /** The resolved execution, or `null` while loading, on error, or when not found. */
+  readonly execution: WorkflowExecution | null;
+  /** `true` while the initial fetch 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;
+}
+
+/**
+ * Data hook that fetches a single WorkflowExecution by ID.
+ *
+ * Pass `null` for `executionId` to skip fetching (stable no-op).
+ * When the ID changes, the previous request is discarded and a
+ * fresh fetch begins.
+ *
+ * If the API returns NOT_FOUND, `execution` is set to `null`
+ * without raising an error.
+ *
+ * @example
+ * ```tsx
+ * function ExecutionHeader({ id }: { id: string }) {
+ *   const { execution, isLoading, error } = useWorkflowExecution(id);
+ *   if (isLoading) return <Skeleton />;
+ *   if (error) return <ErrorMessage error={error} />;
+ *   if (!execution) return <NotFound />;
+ *   return <h2>{execution.metadata?.name}</h2>;
+ * }
+ * ```
+ */
+export function useWorkflowExecution(
+  executionId: string | null,
+): UseWorkflowExecutionReturn {
+  const stigmer = useStigmer();
+
+  const fetchFn = executionId
+    ? async () => {
+        try {
+          return await stigmer.workflowExecution.get(executionId);
+        } catch (err) {
+          if (isNotFound(err)) return null;
+          throw err;
+        }
+      }
+    : null;
+
+  const { data: execution, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [executionId, stigmer],
+    null,
+    { cacheKey: executionId ? `workflow-execution:${executionId}` : undefined },
+  );
+
+  return { execution, isLoading, isRefetching, error, refetch };
+}

package/src/workflow/useWorkflowExecutionActions.ts

@@ -0,0 +1,179 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import type { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { create } from "@bufbuild/protobuf";
+import {
+  CancelWorkflowExecutionInputSchema,
+  TerminateWorkflowExecutionInputSchema,
+  PauseWorkflowExecutionInputSchema,
+  ResumeWorkflowExecutionInputSchema,
+  RecoverWorkflowExecutionInputSchema,
+  SubmitWorkflowApprovalInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Return value of {@link useWorkflowExecutionActions}. */
+export interface UseWorkflowExecutionActionsReturn {
+  /** Cancel a running execution gracefully. */
+  readonly cancel: (reason?: string) => Promise<WorkflowExecution | null>;
+  /** Terminate a running execution immediately. */
+  readonly terminate: (reason?: string) => Promise<WorkflowExecution | null>;
+  /** Pause a running execution. */
+  readonly pause: (reason?: string) => Promise<WorkflowExecution | null>;
+  /** Resume a paused execution. */
+  readonly resume: () => Promise<WorkflowExecution | null>;
+  /** Recover a failed execution from its last checkpoint. */
+  readonly recover: (reason?: string) => Promise<WorkflowExecution | null>;
+  /** Submit an approval decision for a child agent's tool execution. */
+  readonly submitApproval: (
+    toolCallId: string,
+    action: ApprovalAction,
+    comment?: string,
+  ) => Promise<WorkflowExecution | null>;
+  /** `true` while any action is in flight. */
+  readonly isSubmitting: boolean;
+  /** Error from the last failed action, or `null`. */
+  readonly error: Error | null;
+}
+
+/**
+ * Behavior hook that encapsulates workflow execution lifecycle actions.
+ *
+ * Each action calls the corresponding RPC and returns the updated
+ * execution, or `null` on failure (with `error` populated).
+ *
+ * Pass `null` for `executionId` to disable all actions (they become
+ * no-ops that return `null`).
+ *
+ * @example
+ * ```tsx
+ * const actions = useWorkflowExecutionActions(executionId);
+ *
+ * <button onClick={() => actions.cancel("No longer needed")} disabled={actions.isSubmitting}>
+ *   Cancel
+ * </button>
+ * ```
+ */
+export function useWorkflowExecutionActions(
+  executionId: string | null,
+): UseWorkflowExecutionActionsReturn {
+  const stigmer = useStigmer();
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const executionIdRef = useRef(executionId);
+  executionIdRef.current = executionId;
+  const stigmerRef = useRef(stigmer);
+  stigmerRef.current = stigmer;
+
+  const wrap = useCallback(
+    async (fn: () => Promise<WorkflowExecution>): Promise<WorkflowExecution | null> => {
+      if (!executionIdRef.current) return null;
+      setIsSubmitting(true);
+      setError(null);
+      try {
+        const result = await fn();
+        return result;
+      } catch (err) {
+        setError(toError(err));
+        return null;
+      } finally {
+        setIsSubmitting(false);
+      }
+    },
+    [],
+  );
+
+  const cancel = useCallback(
+    (reason?: string) =>
+      wrap(() =>
+        stigmerRef.current.workflowExecution.cancel(
+          create(CancelWorkflowExecutionInputSchema, {
+            id: executionIdRef.current!,
+            reason: reason ?? "",
+          }),
+        ),
+      ),
+    [wrap],
+  );
+
+  const terminate = useCallback(
+    (reason?: string) =>
+      wrap(() =>
+        stigmerRef.current.workflowExecution.terminate(
+          create(TerminateWorkflowExecutionInputSchema, {
+            id: executionIdRef.current!,
+            reason: reason ?? "",
+          }),
+        ),
+      ),
+    [wrap],
+  );
+
+  const pause = useCallback(
+    (reason?: string) =>
+      wrap(() =>
+        stigmerRef.current.workflowExecution.pause(
+          create(PauseWorkflowExecutionInputSchema, {
+            id: executionIdRef.current!,
+            reason: reason ?? "",
+          }),
+        ),
+      ),
+    [wrap],
+  );
+
+  const resume = useCallback(
+    () =>
+      wrap(() =>
+        stigmerRef.current.workflowExecution.resume(
+          create(ResumeWorkflowExecutionInputSchema, {
+            id: executionIdRef.current!,
+          }),
+        ),
+      ),
+    [wrap],
+  );
+
+  const recover = useCallback(
+    (reason?: string) =>
+      wrap(() =>
+        stigmerRef.current.workflowExecution.recover(
+          create(RecoverWorkflowExecutionInputSchema, {
+            id: executionIdRef.current!,
+            reason: reason ?? "",
+          }),
+        ),
+      ),
+    [wrap],
+  );
+
+  const submitApproval = useCallback(
+    (toolCallId: string, action: ApprovalAction, comment?: string) =>
+      wrap(() =>
+        stigmerRef.current.workflowExecution.submitApproval(
+          create(SubmitWorkflowApprovalInputSchema, {
+            executionId: executionIdRef.current!,
+            toolCallId,
+            action,
+            comment: comment ?? "",
+          }),
+        ),
+      ),
+    [wrap],
+  );
+
+  return {
+    cancel,
+    terminate,
+    pause,
+    resume,
+    recover,
+    submitApproval,
+    isSubmitting,
+    error,
+  };
+}

package/src/workflow/useWorkflowExecutionArtifacts.ts

@@ -0,0 +1,57 @@
+"use client";
+
+import type { Artifact } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/api_pb";
+import { create } from "@bufbuild/protobuf";
+import { ListArtifactsByExecutionRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/artifact/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Return value of {@link useWorkflowExecutionArtifacts}. */
+export interface UseWorkflowExecutionArtifactsReturn {
+  /** Artifacts produced by this execution. */
+  readonly artifacts: readonly Artifact[];
+  /** `true` while the initial fetch 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;
+}
+
+/**
+ * Data hook that fetches artifacts produced by a workflow execution.
+ *
+ * Pass `null` for `executionId` to skip fetching.
+ *
+ * @example
+ * ```tsx
+ * const { artifacts, isLoading } = useWorkflowExecutionArtifacts(executionId);
+ * ```
+ */
+export function useWorkflowExecutionArtifacts(
+  executionId: string | null,
+): UseWorkflowExecutionArtifactsReturn {
+  const stigmer = useStigmer();
+
+  const fetchFn = executionId
+    ? async () => {
+        const resp = await stigmer.artifact.listByExecution(
+          create(ListArtifactsByExecutionRequestSchema, {
+            workflowExecutionId: executionId,
+          }),
+        );
+        return [...resp.entries];
+      }
+    : null;
+
+  const { data: artifacts, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [executionId, stigmer],
+    [] as readonly Artifact[],
+    { cacheKey: executionId ? `workflow-execution-artifacts:${executionId}` : undefined },
+  );
+
+  return { artifacts, isLoading, isRefetching, error, refetch };
+}

package/src/workflow/useWorkflowExecutionEventLog.ts

@@ -0,0 +1,111 @@
+"use client";
+
+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 } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Options for {@link useWorkflowExecutionEventLog}. */
+export interface UseWorkflowExecutionEventLogOptions {
+  /** Maximum events per page. @default 100 */
+  readonly pageSize?: number;
+  /** Cursor: return events with sequence_number > this value. @default 0 */
+  readonly afterSequence?: bigint;
+  /** Filter to specific event types. When empty, all types are returned. */
+  readonly eventTypes?: readonly WorkflowEventType[];
+  /** Filter to events for a specific task name. */
+  readonly taskName?: string;
+}
+
+/** Return value of {@link useWorkflowExecutionEventLog}. */
+export interface UseWorkflowExecutionEventLogReturn {
+  /** Events in the current page, ordered by sequence_number ascending. */
+  readonly events: readonly WorkflowExecutionEvent[];
+  /** Whether more events exist after the last event in this response. */
+  readonly hasMore: boolean;
+  /** Highest sequence_number returned, for cursor-based pagination. */
+  readonly latestSequence: bigint;
+  /** `true` while the initial fetch 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 EventLogData {
+  events: readonly WorkflowExecutionEvent[];
+  hasMore: boolean;
+  latestSequence: bigint;
+}
+
+const INITIAL_DATA: EventLogData = {
+  events: [],
+  hasMore: false,
+  latestSequence: BigInt(0),
+};
+
+/**
+ * Data hook that fetches the paginated event log for a workflow execution.
+ *
+ * Pass `null` for `executionId` to skip fetching. Supports cursor-based
+ * pagination via `afterSequence` and optional filters by event type or
+ * task name.
+ *
+ * @example
+ * ```tsx
+ * const { events, hasMore, latestSequence } = useWorkflowExecutionEventLog(
+ *   executionId,
+ *   { pageSize: 50 },
+ * );
+ * ```
+ */
+export function useWorkflowExecutionEventLog(
+  executionId: string | null,
+  options?: UseWorkflowExecutionEventLogOptions,
+): UseWorkflowExecutionEventLogReturn {
+  const stigmer = useStigmer();
+  const pageSize = options?.pageSize ?? 100;
+  const afterSequence = options?.afterSequence ?? BigInt(0);
+  const eventTypes = options?.eventTypes ?? [];
+  const taskName = options?.taskName ?? "";
+
+  const fetchFn = executionId
+    ? async () => {
+        const resp = await stigmer.workflowExecution.getEventLog(
+          create(GetEventLogRequestSchema, {
+            executionId,
+            afterSequence,
+            eventTypes: [...eventTypes],
+            taskName,
+            pageSize,
+          }),
+        );
+        return {
+          events: [...resp.events],
+          hasMore: resp.hasMore,
+          latestSequence: resp.latestSequence,
+        };
+      }
+    : null;
+
+  const { data, isLoading, isRefetching, error, refetch } = useFetch<EventLogData>(
+    fetchFn,
+    [executionId, stigmer, pageSize, afterSequence, taskName, ...eventTypes],
+    INITIAL_DATA,
+  );
+
+  return {
+    events: data.events,
+    hasMore: data.hasMore,
+    latestSequence: data.latestSequence,
+    isLoading,
+    isRefetching,
+    error,
+    refetch,
+  };
+}