@stigmer/react 0.5.0 → 1.0.0

package/src/workflow/usePendingApprovals.ts

@@ -0,0 +1,89 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { ListPendingApprovalsRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+export interface UsePendingApprovalsOptions {
+  /** Organization slug. When empty, the hook does not fetch. */
+  readonly org: string | null | undefined;
+  /** Maximum results per page. @default 20 */
+  readonly pageSize?: number;
+  /** Refetch interval in milliseconds. `0` or `false` disables. @default 30000 */
+  readonly refetchInterval?: number | false;
+}
+
+export interface UsePendingApprovalsReturn {
+  readonly approvals: readonly PendingApproval[];
+  readonly totalCount: number;
+  readonly isLoading: boolean;
+  readonly isRefetching: boolean;
+  readonly error: Error | null;
+  readonly refetch: () => void;
+}
+
+interface PendingApprovalsData {
+  approvals: readonly PendingApproval[];
+  totalCount: number;
+}
+
+const INITIAL_DATA: PendingApprovalsData = {
+  approvals: [],
+  totalCount: 0,
+};
+
+/**
+ * Data hook that fetches pending human_input approvals for an organization.
+ *
+ * Returns workflow executions with active human_input tasks awaiting
+ * reviewer decisions. Includes task name, requester, and timeout info.
+ *
+ * Auto-refreshes every 30 seconds by default since pending approvals
+ * are time-sensitive.
+ *
+ * @example
+ * ```tsx
+ * const { approvals, totalCount, isLoading } = usePendingApprovals({
+ *   org: "acme",
+ * });
+ * ```
+ */
+export function usePendingApprovals(
+  options: UsePendingApprovalsOptions,
+): UsePendingApprovalsReturn {
+  const stigmer = useStigmer();
+  const org = options.org ?? "";
+  const pageSize = options.pageSize ?? 20;
+  const refetchInterval = options.refetchInterval ?? 30_000;
+
+  const fetchFn = org
+    ? async () => {
+        const resp = await stigmer.workflowExecution.listPendingApprovals(
+          create(ListPendingApprovalsRequestSchema, { org, pageSize }),
+        );
+        return {
+          approvals: [...resp.entries],
+          totalCount: resp.totalCount,
+        };
+      }
+    : null;
+
+  const { data, isLoading, isRefetching, error, refetch } =
+    useFetch<PendingApprovalsData>(
+      fetchFn,
+      [stigmer, org, pageSize],
+      INITIAL_DATA,
+      { refetchInterval: refetchInterval || false },
+    );
+
+  return {
+    approvals: data.approvals,
+    totalCount: data.totalCount,
+    isLoading,
+    isRefetching,
+    error,
+    refetch,
+  };
+}

package/src/workflow/useRefineWorkflowFlow.ts

@@ -0,0 +1,321 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { getUserMessage } from "@stigmer/sdk";
+import { useCreateSession } from "../session/useCreateSession";
+import { useCreateAgentExecution } from "../execution/useCreateAgentExecution";
+import { useExecutionStream } from "../execution/useExecutionStream";
+import { isTerminalPhase } from "../execution/execution-phases";
+import { useConversationStoreRef } from "../internal/store";
+import {
+  extractWorkflowYaml,
+  type ExtractedWorkflowYaml,
+} from "./extract-workflow-yaml";
+
+/**
+ * Lifecycle phases for the workflow refinement flow.
+ *
+ * - `idle` — panel open, no conversation yet
+ * - `starting` — creating session (first turn) + execution
+ * - `streaming` — agent is working (tool calls, validation, refinement)
+ * - `complete` — agent finished, YAML was extracted (diff showing)
+ * - `ready` — agent finished without YAML (clarifying question / explanation),
+ *   or user accepted/discarded a previous result
+ * - `error` — a failure occurred (RPC, stream)
+ */
+export type RefinePhase =
+  | "idle"
+  | "starting"
+  | "streaming"
+  | "complete"
+  | "ready"
+  | "error";
+
+/** Options for {@link useRefineWorkflowFlow}. */
+export interface UseRefineWorkflowFlowOptions {
+  /** Organization slug for session and execution creation. */
+  readonly org: string;
+  /** Live YAML from the editor. Captured via ref at send-time, not reactively. */
+  readonly currentYaml: string;
+  /** Called when any step fails. Also available via the `error` return. */
+  readonly onError?: (message: string) => void;
+}
+
+/** Return value of {@link useRefineWorkflowFlow}. */
+export interface UseRefineWorkflowFlowReturn {
+  /** Current lifecycle phase. */
+  readonly phase: RefinePhase;
+  /** Completed execution snapshots for MessageThread (chronological). */
+  readonly completedExecutions: readonly AgentExecution[];
+  /** Currently streaming execution, or null when idle/between turns. */
+  readonly activeExecution: AgentExecution | null;
+  /** `true` while the agent execution is actively streaming. */
+  readonly isStreaming: boolean;
+  /** Extracted YAML from the latest turn (null unless phase is `complete`). */
+  readonly extractedYaml: string | null;
+  /** Agent's explanation prose from the latest turn. */
+  readonly explanation: string | null;
+  /** Human-readable error message, or `null` when healthy. */
+  readonly error: string | null;
+  /** Send a refinement instruction. Creates session on first call. */
+  readonly sendInstruction: (instruction: string) => Promise<void>;
+  /** Accept the extracted YAML. Returns the YAML string. Transitions to `ready`. */
+  readonly acceptResult: () => string | null;
+  /** Discard the extracted YAML without applying. Transitions to `ready`. */
+  readonly discardResult: () => void;
+  /** Reset all state to initial values. Does not delete the server-side session. */
+  readonly reset: () => void;
+}
+
+const AGENT_REF = { org: "", slug: "workflow-architect" } as const;
+const MIN_INSTRUCTION_LENGTH = 5;
+
+/**
+ * Behavior hook that orchestrates agent-powered workflow refinement
+ * using the built-in Workflow Architect system agent.
+ *
+ * Manages a multi-turn conversation within a single Session:
+ * - First turn creates a Session + AgentExecution
+ * - Subsequent turns reuse the Session (conversational context)
+ * - Each turn streams agent messages via {@link useExecutionStream}
+ * - YAML is extracted from agent responses via {@link extractWorkflowYaml}
+ *
+ * The `currentYaml` prop is captured at send-time (ref-based, not reactive)
+ * and included in the message only when it differs from the last-sent version.
+ *
+ * Framework-agnostic (DD-004), referentially stable returns (DD-010).
+ *
+ * @example
+ * ```tsx
+ * const flow = useRefineWorkflowFlow({
+ *   org: "acme",
+ *   currentYaml: editor.yaml,
+ *   onError: (msg) => toast.error(msg),
+ * });
+ *
+ * <WorkflowRefinePanel flow={flow} onAccept={...} onClose={...} />
+ * ```
+ */
+export function useRefineWorkflowFlow(
+  options: UseRefineWorkflowFlowOptions,
+): UseRefineWorkflowFlowReturn {
+  const { org, currentYaml, onError } = options;
+
+  const [phase, setPhase] = useState<RefinePhase>("idle");
+  const [executionId, setExecutionId] = useState<string | null>(null);
+  const [completedExecutions, setCompletedExecutions] = useState<
+    AgentExecution[]
+  >([]);
+  const [extracted, setExtracted] = useState<ExtractedWorkflowYaml | null>(
+    null,
+  );
+  const [error, setError] = useState<string | null>(null);
+
+  const orgRef = useRef(org);
+  orgRef.current = org;
+  const yamlRef = useRef(currentYaml);
+  yamlRef.current = currentYaml;
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+
+  const sessionIdRef = useRef<string | null>(null);
+  const lastSentYamlRef = useRef<string | null>(null);
+  const prevTerminalRef = useRef(false);
+
+  const { create: createSession } = useCreateSession();
+  const { create: createExecution } = useCreateAgentExecution();
+  const conversationStore = useConversationStoreRef();
+  const stream = useExecutionStream(executionId, {
+    store: conversationStore,
+  });
+
+  // -------------------------------------------------------------------------
+  // Terminal phase detection — extract YAML or transition to ready
+  // -------------------------------------------------------------------------
+  useEffect(() => {
+    if (phase !== "streaming") return;
+
+    const isTerminal =
+      stream.phase !== ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED &&
+      isTerminalPhase(stream.phase);
+
+    if (isTerminal && !prevTerminalRef.current) {
+      prevTerminalRef.current = true;
+
+      if (stream.execution) {
+        setCompletedExecutions((prev) => [...prev, stream.execution!]);
+      }
+
+      const result = extractWorkflowYaml(stream.execution);
+      if (result) {
+        setExtracted(result);
+        setPhase("complete");
+      } else {
+        setPhase("ready");
+      }
+
+      setExecutionId(null);
+    }
+  }, [phase, stream.phase, stream.execution]);
+
+  // -------------------------------------------------------------------------
+  // Stream error surfacing
+  // -------------------------------------------------------------------------
+  useEffect(() => {
+    if (stream.error && phase === "streaming") {
+      const msg = getUserMessage(stream.error, "Agent stream interrupted");
+      setPhase("error");
+      setError(msg);
+      onErrorRef.current?.(msg);
+    }
+  }, [stream.error, phase]);
+
+  // -------------------------------------------------------------------------
+  // Build the message with optional YAML context
+  // -------------------------------------------------------------------------
+  const buildMessage = useCallback((instruction: string): string => {
+    const capturedYaml = yamlRef.current;
+    const yamlChanged = capturedYaml !== lastSentYamlRef.current;
+
+    lastSentYamlRef.current = capturedYaml;
+
+    if (yamlChanged && capturedYaml) {
+      return (
+        "Here is the current workflow YAML:\n\n" +
+        "```yaml\n" +
+        capturedYaml +
+        "\n```\n\n" +
+        instruction
+      );
+    }
+
+    return instruction;
+  }, []);
+
+  // -------------------------------------------------------------------------
+  // Send a refinement instruction
+  // -------------------------------------------------------------------------
+  const sendInstruction = useCallback(
+    async (instruction: string) => {
+      const trimmed = instruction.trim();
+      if (trimmed.length < MIN_INSTRUCTION_LENGTH) {
+        setError(
+          `Instruction must be at least ${MIN_INSTRUCTION_LENGTH} characters`,
+        );
+        return;
+      }
+
+      if (
+        phase !== "idle" &&
+        phase !== "ready" &&
+        phase !== "complete" &&
+        phase !== "error"
+      ) {
+        return;
+      }
+
+      setPhase("starting");
+      setError(null);
+      setExtracted(null);
+      prevTerminalRef.current = false;
+
+      try {
+        let activeSessionId = sessionIdRef.current;
+
+        if (!activeSessionId) {
+          const { sessionId: newSessionId } = await createSession({
+            org: orgRef.current,
+            agentRef: { ...AGENT_REF, org: orgRef.current },
+          });
+          sessionIdRef.current = newSessionId;
+          activeSessionId = newSessionId;
+        }
+
+        const message = buildMessage(trimmed);
+
+        const { executionId: newExecutionId } = await createExecution({
+          org: orgRef.current,
+          sessionId: activeSessionId,
+          message,
+        });
+
+        setExecutionId(newExecutionId);
+        setPhase("streaming");
+      } catch (err) {
+        const msg = getUserMessage(
+          err,
+          "Failed to start the Workflow Architect agent",
+        );
+        setPhase("error");
+        setError(msg);
+        onErrorRef.current?.(msg);
+      }
+    },
+    [phase, createSession, createExecution, buildMessage],
+  );
+
+  // -------------------------------------------------------------------------
+  // Accept / discard extracted YAML
+  // -------------------------------------------------------------------------
+  const acceptResult = useCallback((): string | null => {
+    if (phase !== "complete" || !extracted) return null;
+    const yaml = extracted.yaml;
+    setExtracted(null);
+    setPhase("ready");
+    return yaml;
+  }, [phase, extracted]);
+
+  const discardResult = useCallback(() => {
+    if (phase !== "complete") return;
+    setExtracted(null);
+    setPhase("ready");
+  }, [phase]);
+
+  // -------------------------------------------------------------------------
+  // Reset all state
+  // -------------------------------------------------------------------------
+  const reset = useCallback(() => {
+    setPhase("idle");
+    setExecutionId(null);
+    setCompletedExecutions([]);
+    setExtracted(null);
+    setError(null);
+    sessionIdRef.current = null;
+    lastSentYamlRef.current = null;
+    prevTerminalRef.current = false;
+  }, []);
+
+  // -------------------------------------------------------------------------
+  // Referentially stable return (DD-010)
+  // -------------------------------------------------------------------------
+  return useMemo(
+    () => ({
+      phase,
+      completedExecutions,
+      activeExecution: stream.execution,
+      isStreaming: stream.isStreaming || stream.isConnecting,
+      extractedYaml: extracted?.yaml ?? null,
+      explanation: extracted?.explanation ?? null,
+      error,
+      sendInstruction,
+      acceptResult,
+      discardResult,
+      reset,
+    }),
+    [
+      phase,
+      completedExecutions,
+      stream.execution,
+      stream.isStreaming,
+      stream.isConnecting,
+      extracted,
+      error,
+      sendInstruction,
+      acceptResult,
+      discardResult,
+      reset,
+    ],
+  );
+}

package/src/workflow/useResolveAgentExecutionSession.ts

@@ -0,0 +1,57 @@
+"use client";
+
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Return value of {@link useResolveAgentExecutionSession}. */
+export interface UseResolveAgentExecutionSessionReturn {
+  /** The resolved session ID, or `null` while loading or on error. */
+  readonly sessionId: string | null;
+  /** `true` while the fetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+}
+
+/**
+ * Resolves an AgentExecution ID (`aex_*`) to its parent Session ID.
+ *
+ * This hook fetches the AgentExecution resource and extracts
+ * `spec.sessionId`. Use it when navigating from a workflow execution
+ * context (which knows the child agent execution ID) to the session
+ * page (which requires the session ID).
+ *
+ * Pass `null` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * function DrillDown({ agentExecutionId }: { agentExecutionId: string }) {
+ *   const { sessionId, isLoading } = useResolveAgentExecutionSession(agentExecutionId);
+ *   useEffect(() => {
+ *     if (sessionId) navigateToSession(sessionId);
+ *   }, [sessionId]);
+ *   if (isLoading) return <Spinner />;
+ *   return null;
+ * }
+ * ```
+ */
+export function useResolveAgentExecutionSession(
+  agentExecutionId: string | null,
+): UseResolveAgentExecutionSessionReturn {
+  const stigmer = useStigmer();
+
+  const fetchFn = agentExecutionId
+    ? async () => {
+        const execution = await stigmer.agentExecution.get(agentExecutionId);
+        return execution.spec?.sessionId ?? null;
+      }
+    : null;
+
+  const { data: sessionId, isLoading, error } = useFetch(
+    fetchFn,
+    [agentExecutionId, stigmer],
+    null,
+  );
+
+  return { sessionId, isLoading, error };
+}

package/src/workflow/useRunWorkflowFlow.ts

@@ -0,0 +1,235 @@
+"use client";
+
+import { useCallback, useMemo, useRef, useState } from "react";
+import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import type { WorkflowInstance } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
+import type { WorkflowExecution } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
+import type { EnvVarDeclaration } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import { getUserMessage } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { toError } from "../internal/toError";
+
+/** Field-level validation errors keyed by field name. */
+export type RunWorkflowFieldErrors = Record<string, string>;
+
+/** Options for {@link useRunWorkflowFlow}. */
+export interface UseRunWorkflowFlowOptions {
+  /** Organization slug that owns the workflow. */
+  readonly org: string;
+  /** Workflow resource (must include metadata and spec). */
+  readonly workflow: Workflow;
+  /** Available workflow instances (for instance selector). */
+  readonly instances: readonly WorkflowInstance[];
+  /**
+   * Called after the execution is created successfully.
+   * Receives the execution ID for navigation.
+   */
+  readonly onSuccess: (executionId: string) => void;
+  /**
+   * Called when submission fails. Receives a human-readable message.
+   * Errors are also available via {@link UseRunWorkflowFlowReturn.error}.
+   */
+  readonly onError?: (message: string) => void;
+}
+
+/** Return value of {@link useRunWorkflowFlow}. */
+export interface UseRunWorkflowFlowReturn {
+  /** Current trigger message value. */
+  readonly triggerMessage: string;
+  /** Update the trigger message. */
+  readonly setTriggerMessage: (value: string) => void;
+
+  /** Current runtime environment variable overrides (keyed by var name). */
+  readonly runtimeEnv: Record<string, string>;
+  /** Update a single env var value. */
+  readonly setEnvVar: (key: string, value: string) => void;
+
+  /** Selected instance ID, or `null` for server-resolved default. */
+  readonly selectedInstanceId: string | null;
+  /** Update the selected instance. */
+  readonly setSelectedInstanceId: (id: string | null) => void;
+
+  /** Declared environment variables from the workflow spec. */
+  readonly envDeclarations: Record<string, EnvVarDeclaration>;
+
+  /** Field-level validation errors (empty when valid). */
+  readonly fieldErrors: RunWorkflowFieldErrors;
+
+  /** `true` while the create execution RPC is in flight. */
+  readonly isSubmitting: boolean;
+  /** Error from the last failed submission, or `null`. */
+  readonly error: string | null;
+
+  /** Validate form fields. Returns `true` if valid. */
+  readonly validate: () => boolean;
+  /** Validate, then create the workflow execution. */
+  readonly submit: () => Promise<void>;
+  /** Reset all form state to initial values. */
+  readonly reset: () => void;
+}
+
+/**
+ * Behavior hook that orchestrates the "run a workflow" flow.
+ *
+ * Manages form state (trigger message, runtime env overrides, instance
+ * selection), validates required fields, and calls
+ * `WorkflowExecutionClient.create()` on submission. On success, the
+ * consumer-provided `onSuccess` callback receives the execution ID for
+ * navigation or further action.
+ *
+ * This hook is framework-agnostic — it works identically in Next.js,
+ * Vite, Tauri, or any React environment. Navigation and toast feedback
+ * are the consumer's responsibility.
+ *
+ * @example
+ * ```tsx
+ * const flow = useRunWorkflowFlow({
+ *   org: "acme",
+ *   workflow,
+ *   instances,
+ *   onSuccess: (id) => router.push(`/workflows/executions/${id}`),
+ *   onError: (msg) => toast.error(msg),
+ * });
+ *
+ * <input value={flow.triggerMessage} onChange={e => flow.setTriggerMessage(e.target.value)} />
+ * <button onClick={flow.submit} disabled={flow.isSubmitting}>Run</button>
+ * ```
+ */
+export function useRunWorkflowFlow(
+  options: UseRunWorkflowFlowOptions,
+): UseRunWorkflowFlowReturn {
+  const { org, workflow, instances, onSuccess, onError } = options;
+  const stigmer = useStigmer();
+
+  const [triggerMessage, setTriggerMessage] = useState("");
+  const [runtimeEnv, setRuntimeEnv] = useState<Record<string, string>>({});
+  const [selectedInstanceId, setSelectedInstanceId] = useState<string | null>(
+    null,
+  );
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [fieldErrors, setFieldErrors] = useState<RunWorkflowFieldErrors>({});
+
+  const stigmerRef = useRef(stigmer);
+  stigmerRef.current = stigmer;
+  const onSuccessRef = useRef(onSuccess);
+  onSuccessRef.current = onSuccess;
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+
+  const envDeclarations = useMemo<Record<string, EnvVarDeclaration>>(
+    () => (workflow.spec?.env ? { ...workflow.spec.env } : {}),
+    [workflow.spec?.env],
+  );
+
+  const setEnvVar = useCallback((key: string, value: string) => {
+    setRuntimeEnv((prev) => ({ ...prev, [key]: value }));
+    setFieldErrors((prev) => {
+      if (!prev[key]) return prev;
+      const next = { ...prev };
+      delete next[key];
+      return next;
+    });
+  }, []);
+
+  const validate = useCallback((): boolean => {
+    const errors: RunWorkflowFieldErrors = {};
+    for (const [key, decl] of Object.entries(envDeclarations)) {
+      if (!decl.optional && !runtimeEnv[key]?.trim()) {
+        errors[key] = `${key} is required`;
+      }
+    }
+    setFieldErrors(errors);
+    return Object.keys(errors).length === 0;
+  }, [envDeclarations, runtimeEnv]);
+
+  const submit = useCallback(async () => {
+    if (isSubmitting) return;
+    if (!validate()) return;
+
+    setIsSubmitting(true);
+    setError(null);
+
+    try {
+      const workflowName =
+        workflow.metadata?.name || workflow.metadata?.slug || "Workflow";
+
+      const envInput: Record<string, { value: string; isSecret?: boolean }> =
+        {};
+      for (const [key, value] of Object.entries(runtimeEnv)) {
+        if (value.trim()) {
+          const isSecret = envDeclarations[key]?.isSecret ?? false;
+          envInput[key] = { value, isSecret };
+        }
+      }
+
+      const execution: WorkflowExecution =
+        await stigmerRef.current.workflowExecution.create({
+          name: `${workflowName} execution`,
+          org,
+          workflowId: selectedInstanceId
+            ? undefined
+            : workflow.metadata?.id,
+          workflowInstanceId: selectedInstanceId ?? undefined,
+          triggerMessage: triggerMessage || undefined,
+          triggerMetadata: {
+            source: "ui",
+            timestamp: new Date().toISOString(),
+          },
+          runtimeEnv:
+            Object.keys(envInput).length > 0 ? envInput : undefined,
+        });
+
+      const executionId = execution.metadata?.id;
+      if (!executionId) {
+        throw new Error(
+          "Execution was created but no ID was returned. Please check the executions list.",
+        );
+      }
+
+      onSuccessRef.current(executionId);
+    } catch (err) {
+      const message = getUserMessage(
+        err,
+        "Failed to start workflow execution",
+      );
+      setError(message);
+      onErrorRef.current?.(message);
+    } finally {
+      setIsSubmitting(false);
+    }
+  }, [
+    isSubmitting,
+    validate,
+    workflow.metadata,
+    org,
+    selectedInstanceId,
+    triggerMessage,
+    runtimeEnv,
+    envDeclarations,
+  ]);
+
+  const reset = useCallback(() => {
+    setTriggerMessage("");
+    setRuntimeEnv({});
+    setSelectedInstanceId(null);
+    setError(null);
+    setFieldErrors({});
+  }, []);
+
+  return {
+    triggerMessage,
+    setTriggerMessage,
+    runtimeEnv,
+    setEnvVar,
+    selectedInstanceId,
+    setSelectedInstanceId,
+    envDeclarations,
+    fieldErrors,
+    isSubmitting,
+    error,
+    validate,
+    submit,
+    reset,
+  };
+}