@stigmer/react 0.5.1 → 1.0.0

package/src/workflow/useTaskKindRegistry.ts

@@ -0,0 +1,135 @@
+"use client";
+
+import { useMemo } from "react";
+import type { TaskKindDescriptor, TaskKindCategory } from "./types";
+import { useTaskKindRegistryContext } from "./TaskKindRegistryContext";
+
+/** Return value of {@link useTaskKindRegistry}. */
+export interface UseTaskKindRegistryReturn {
+  /** All registered task kind descriptors, one per WorkflowTaskKind. */
+  readonly descriptors: readonly TaskKindDescriptor[];
+
+  /**
+   * Look up a single descriptor by its kind identifier.
+   *
+   * @example
+   * ```ts
+   * const llm = getByKind("llm_call");
+   * // llm?.displayName === "LLM Call"
+   * ```
+   */
+  readonly getByKind: (kind: string) => TaskKindDescriptor | undefined;
+
+  /**
+   * Retrieve the JSON Schema for a task kind's configuration.
+   *
+   * Returns the parsed JSON Schema object suitable for Monaco editor
+   * validation or React JSON Schema Form (RJSF) rendering.
+   *
+   * @example
+   * ```ts
+   * const schema = getJsonSchema("llm_call");
+   * // Pass to Monaco: monaco.languages.json.jsonDefaults.setDiagnosticsOptions(...)
+   * ```
+   */
+  readonly getJsonSchema: (kind: string) => Record<string, unknown> | undefined;
+
+  /**
+   * Descriptors grouped by their functional category.
+   *
+   * Useful for rendering a categorized task palette where tasks are
+   * organized into sections like "AI", "Control Flow", "Data", etc.
+   *
+   * @example
+   * ```tsx
+   * for (const [category, tasks] of categories) {
+   *   // Render category header + task cards
+   * }
+   * ```
+   */
+  readonly categories: ReadonlyMap<TaskKindCategory, readonly TaskKindDescriptor[]>;
+
+  /** `true` while the task kind registry is being fetched from the API. */
+  readonly isLoading: boolean;
+
+  /** Non-null if the API fetch failed. Descriptors will be empty in this case. */
+  readonly error: Error | null;
+
+  /** Retry fetching the registry. No-op while a fetch is in flight. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that exposes the task kind registry with lookup and grouping helpers.
+ *
+ * Pure data layer — no rendering, no side effects. Platform builders
+ * who want full control over rendering import this hook and build
+ * their own UI (task palettes, form generators, validation).
+ *
+ * The registry data is fetched from the task kind registry API by
+ * {@link StigmerProvider} and cached in context. During loading,
+ * `isLoading` is `true` and `descriptors` is empty.
+ *
+ * @example
+ * ```tsx
+ * function TaskPalette() {
+ *   const { categories, isLoading, error } = useTaskKindRegistry();
+ *
+ *   if (isLoading) return <Skeleton />;
+ *   if (error) return <ErrorMessage error={error} />;
+ *
+ *   return (
+ *     <div>
+ *       {Array.from(categories).map(([category, tasks]) => (
+ *         <CategorySection key={category} label={category}>
+ *           {tasks.map(task => (
+ *             <TaskCard key={task.kind} descriptor={task} />
+ *           ))}
+ *         </CategorySection>
+ *       ))}
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // YAML editor integration
+ * function WorkflowEditor({ taskKind }: { taskKind: string }) {
+ *   const { getJsonSchema } = useTaskKindRegistry();
+ *   const schema = getJsonSchema(taskKind);
+ *   // Pass schema to Monaco for autocomplete + validation
+ * }
+ * ```
+ *
+ * @since T04 (Task Schema Registry)
+ */
+export function useTaskKindRegistry(): UseTaskKindRegistryReturn {
+  const { descriptors, isLoading, error, refetch } = useTaskKindRegistryContext();
+
+  return useMemo(() => {
+    const byKind = new Map<string, TaskKindDescriptor>();
+    const byCategory = new Map<TaskKindCategory, TaskKindDescriptor[]>();
+
+    for (const descriptor of descriptors) {
+      byKind.set(descriptor.kind, descriptor);
+
+      const group = byCategory.get(descriptor.category);
+      if (group) {
+        group.push(descriptor);
+      } else {
+        byCategory.set(descriptor.category, [descriptor]);
+      }
+    }
+
+    return {
+      descriptors,
+      getByKind: (kind: string) => byKind.get(kind),
+      getJsonSchema: (kind: string) => byKind.get(kind)?.configJsonSchema,
+      categories: byCategory as ReadonlyMap<TaskKindCategory, readonly TaskKindDescriptor[]>,
+      isLoading,
+      error,
+      refetch,
+    };
+  }, [descriptors, isLoading, error, refetch]);
+}

package/src/workflow/useWorkflow.ts

@@ -0,0 +1,78 @@
+"use client";
+
+import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { isNotFound } from "@stigmer/sdk";
+import { useStigmer } from "../hooks";
+import { useFetch } from "../internal/useFetch";
+
+/** Return value of {@link useWorkflow}. */
+export interface UseWorkflowReturn {
+  /** The resolved Workflow, or `null` while loading, on error, or when not found. */
+  readonly workflow: Workflow | null;
+  /** `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 the workflow from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches a single Workflow blueprint by organization and slug.
+ *
+ * Wraps `stigmer.workflow.getByReference()` with loading, error, and
+ * not-found state management. When the `org` or `slug` parameters
+ * change, the previous in-flight request is discarded and a fresh
+ * fetch begins.
+ *
+ * Pass `null` for either `org` or `slug` to skip fetching (stable
+ * no-op). This is useful when the slug is not yet available — for
+ * example, while a parent component is still resolving route params.
+ *
+ * **Not-found handling:** If the API returns a 404 (NOT_FOUND), the
+ * hook sets `workflow` to `null` without raising an error. Consumers
+ * distinguish "not found" from "loading" by checking all three fields:
+ * `workflow === null && !isLoading && !error` means the resource does
+ * not exist.
+ *
+ * @example
+ * ```tsx
+ * function WorkflowDetail({ org, slug }: { org: string; slug: string }) {
+ *   const { workflow, isLoading, error } = useWorkflow(org, slug);
+ *
+ *   if (isLoading) return <Skeleton />;
+ *   if (error) return <ErrorMessage error={error} />;
+ *   if (!workflow) return <NotFound />;
+ *
+ *   return <h1>{workflow.metadata?.name}</h1>;
+ * }
+ * ```
+ */
+export function useWorkflow(
+  org: string | null,
+  slug: string | null,
+): UseWorkflowReturn {
+  const stigmer = useStigmer();
+
+  const fetchFn =
+    org && slug
+      ? async () => {
+          try {
+            return await stigmer.workflow.getByReference({ org, slug });
+          } catch (err) {
+            if (isNotFound(err)) return null;
+            throw err;
+          }
+        }
+      : null;
+
+  const { data: workflow, isLoading, isRefetching, error, refetch } = useFetch(
+    fetchFn,
+    [org, slug, stigmer],
+    null,
+  );
+
+  return { workflow, isLoading, isRefetching, error, refetch };
+}

package/src/workflow/useWorkflowArchitectFlow.ts

@@ -0,0 +1,303 @@
+"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 { useStigmer } from "../hooks";
+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 { parseWorkflowYaml } from "./serialize-workflow-yaml";
+import {
+  extractWorkflowYaml,
+  type ExtractedWorkflowYaml,
+} from "./extract-workflow-yaml";
+
+/**
+ * Lifecycle phases for the Workflow Architect generate flow.
+ *
+ * - `idle` — waiting for user to submit a prompt
+ * - `starting` — creating session + execution
+ * - `streaming` — agent is working (tool calls, validation, generation)
+ * - `complete` — agent finished and YAML was extracted successfully
+ * - `extraction-failed` — agent finished but no YAML block was found
+ * - `applying` — creating the workflow from extracted YAML
+ * - `error` — a failure occurred (RPC, stream, or apply)
+ */
+export type ArchitectPhase =
+  | "idle"
+  | "starting"
+  | "streaming"
+  | "complete"
+  | "extraction-failed"
+  | "applying"
+  | "error";
+
+/** Options for {@link useWorkflowArchitectFlow}. */
+export interface UseWorkflowArchitectFlowOptions {
+  /** Organization slug — used for session, execution, and workflow creation. */
+  readonly org: string;
+  /**
+   * Called after the workflow is created successfully.
+   * Receives the org slug and workflow slug for navigation.
+   */
+  readonly onSuccess: (org: string, slug: string) => void;
+  /**
+   * Called when any step fails. Receives a human-readable message.
+   * Errors are also available via {@link UseWorkflowArchitectFlowReturn.error}.
+   */
+  readonly onError?: (message: string) => void;
+}
+
+/** Return value of {@link useWorkflowArchitectFlow}. */
+export interface UseWorkflowArchitectFlowReturn {
+  /** Current prompt value. */
+  readonly prompt: string;
+  /** Update the prompt. */
+  readonly setPrompt: (value: string) => void;
+
+  /** Current lifecycle phase. */
+  readonly phase: ArchitectPhase;
+
+  /**
+   * Latest execution snapshot from the agent stream.
+   *
+   * Non-null during `streaming`, `complete`, and `extraction-failed`
+   * phases. Pass to `MessageThread` for rendering agent messages.
+   */
+  readonly execution: AgentExecution | null;
+  /** `true` while the agent execution is actively streaming. */
+  readonly isStreaming: boolean;
+
+  /** Extracted YAML when phase is `complete`, otherwise `null`. */
+  readonly extractedYaml: string | null;
+  /** Agent's explanation prose when phase is `complete`, otherwise `null`. */
+  readonly explanation: string | null;
+
+  /** Human-readable error message, or `null` when healthy. */
+  readonly error: string | null;
+
+  /**
+   * Validate the prompt and launch the Workflow Architect agent.
+   *
+   * Creates a session with the `workflow-architect` system agent,
+   * starts an execution with the user's prompt, and begins streaming.
+   * The stream phase transitions automatically when the agent finishes.
+   */
+  readonly generate: () => Promise<void>;
+
+  /**
+   * Create a workflow from the extracted YAML via `workflow.apply()`.
+   *
+   * Only callable when phase is `complete`. Calls `onSuccess` with
+   * the org and slug on completion.
+   */
+  readonly createWorkflow: () => Promise<void>;
+
+  /** Reset all state to initial values. Does not delete the session. */
+  readonly reset: () => void;
+}
+
+const AGENT_REF = { org: "", slug: "workflow-architect" } as const;
+const MIN_PROMPT_LENGTH = 10;
+
+/**
+ * Behavior hook that orchestrates the agent-powered "generate a workflow"
+ * flow using the built-in Workflow Architect system agent.
+ *
+ * Composes existing infrastructure:
+ * - {@link useCreateSession} to create a session with the agent
+ * - {@link useCreateAgentExecution} to start the generation execution
+ * - {@link useExecutionStream} + `ConversationStore` for real-time streaming
+ * - {@link extractWorkflowYaml} to parse YAML from agent messages
+ * - `workflow.apply()` to persist the generated workflow
+ *
+ * The hook is framework-agnostic (DD-004) and returns referentially
+ * stable values (DD-010).
+ *
+ * @example
+ * ```tsx
+ * const flow = useWorkflowArchitectFlow({
+ *   org: "acme",
+ *   onSuccess: (org, slug) => router.push(`/library/workflows/${org}/${slug}`),
+ *   onError: (msg) => toast.error(msg),
+ * });
+ *
+ * <WorkflowArchitectDialog {...flow} />
+ * ```
+ */
+export function useWorkflowArchitectFlow(
+  options: UseWorkflowArchitectFlowOptions,
+): UseWorkflowArchitectFlowReturn {
+  const { org, onSuccess, onError } = options;
+  const stigmer = useStigmer();
+
+  const [prompt, setPrompt] = useState("");
+  const [phase, setPhase] = useState<ArchitectPhase>("idle");
+  const [executionId, setExecutionId] = useState<string | null>(null);
+  const [sessionId, setSessionId] = useState<string | null>(null);
+  const [extracted, setExtracted] = useState<ExtractedWorkflowYaml | null>(
+    null,
+  );
+  const [error, setError] = useState<string | null>(null);
+
+  const orgRef = useRef(org);
+  orgRef.current = org;
+  const onSuccessRef = useRef(onSuccess);
+  onSuccessRef.current = onSuccess;
+  const onErrorRef = useRef(onError);
+  onErrorRef.current = onError;
+
+  const { create: createSession } = useCreateSession();
+  const { create: createExecution } = useCreateAgentExecution();
+  const conversationStore = useConversationStoreRef();
+  const stream = useExecutionStream(executionId, {
+    store: conversationStore,
+  });
+
+  // Detect when the stream reaches a terminal phase and extract YAML
+  const prevTerminalRef = useRef(false);
+  useEffect(() => {
+    if (phase !== "streaming") return;
+
+    const isTerminal =
+      stream.phase !== ExecutionPhase.EXECUTION_PHASE_UNSPECIFIED &&
+      isTerminalPhase(stream.phase);
+
+    if (isTerminal && !prevTerminalRef.current) {
+      prevTerminalRef.current = true;
+
+      const result = extractWorkflowYaml(stream.execution);
+      if (result) {
+        setExtracted(result);
+        setPhase("complete");
+      } else {
+        setPhase("extraction-failed");
+        setError(
+          "The agent completed but did not produce a YAML workflow definition. " +
+            "Try again with a more specific prompt.",
+        );
+      }
+    }
+  }, [phase, stream.phase, stream.execution]);
+
+  // Surface stream errors
+  useEffect(() => {
+    if (stream.error && phase === "streaming") {
+      setPhase("error");
+      setError(getUserMessage(stream.error, "Agent stream interrupted"));
+      onErrorRef.current?.(
+        getUserMessage(stream.error, "Agent stream interrupted"),
+      );
+    }
+  }, [stream.error, phase]);
+
+  const generate = useCallback(async () => {
+    if (phase !== "idle" && phase !== "error" && phase !== "extraction-failed")
+      return;
+
+    const trimmed = prompt.trim();
+    if (trimmed.length < MIN_PROMPT_LENGTH) {
+      setError(`Prompt must be at least ${MIN_PROMPT_LENGTH} characters`);
+      return;
+    }
+
+    setPhase("starting");
+    setError(null);
+    setExtracted(null);
+    prevTerminalRef.current = false;
+
+    try {
+      const { sessionId: newSessionId } = await createSession({
+        org: orgRef.current,
+        agentRef: { ...AGENT_REF, org: orgRef.current },
+      });
+      setSessionId(newSessionId);
+
+      const { executionId: newExecutionId } = await createExecution({
+        org: orgRef.current,
+        sessionId: newSessionId,
+        message: trimmed,
+      });
+      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, prompt, createSession, createExecution]);
+
+  const createWorkflow = useCallback(async () => {
+    if (phase !== "complete" || !extracted) return;
+
+    setPhase("applying");
+    setError(null);
+
+    try {
+      const input = parseWorkflowYaml(extracted.yaml, orgRef.current);
+      const workflow = await stigmer.workflow.apply(input);
+
+      const slug = workflow.metadata?.slug;
+      const workflowOrg = workflow.metadata?.org || orgRef.current;
+
+      if (!slug) {
+        throw new Error(
+          "Workflow was created but no slug was returned. Check the workflows list.",
+        );
+      }
+
+      onSuccessRef.current(workflowOrg, slug);
+    } catch (err) {
+      const msg = getUserMessage(err, "Failed to create workflow");
+      setPhase("error");
+      setError(msg);
+      onErrorRef.current?.(msg);
+    }
+  }, [phase, extracted, stigmer]);
+
+  const reset = useCallback(() => {
+    setPrompt("");
+    setPhase("idle");
+    setExecutionId(null);
+    setSessionId(null);
+    setExtracted(null);
+    setError(null);
+    prevTerminalRef.current = false;
+  }, []);
+
+  return useMemo(
+    () => ({
+      prompt,
+      setPrompt,
+      phase,
+      execution: stream.execution,
+      isStreaming: stream.isStreaming || stream.isConnecting,
+      extractedYaml: extracted?.yaml ?? null,
+      explanation: extracted?.explanation ?? null,
+      error,
+      generate,
+      createWorkflow,
+      reset,
+    }),
+    [
+      prompt,
+      phase,
+      stream.execution,
+      stream.isStreaming,
+      stream.isConnecting,
+      extracted,
+      error,
+      generate,
+      createWorkflow,
+      reset,
+    ],
+  );
+}