@stigmer/react 0.5.1 → 1.0.1

package/workflow/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * TypeScript representation of a TaskKindDescriptor from the task kind registry.
+ *
+ * Each descriptor provides complete metadata for a single workflow task kind,
+ * enabling UI form generation, YAML editor autocomplete, task palette
+ * rendering, and client-side pre-validation.
+ *
+ * @since T04 (Task Schema Registry)
+ */
+export interface TaskKindDescriptor {
+    /** Workflow task kind identifier (e.g., "llm_call", "human_input"). */
+    readonly kind: string;
+    /** Human-readable display name (e.g., "LLM Call", "Human Input"). */
+    readonly displayName: string;
+    /** One-line description of what this task kind does. */
+    readonly description: string;
+    /** Functional category for palette grouping and filtering. */
+    readonly category: TaskKindCategory;
+    /** Lucide icon name for UI rendering. */
+    readonly icon: string;
+    /** Fully-qualified proto message type for the task config. */
+    readonly configProtoType: string;
+    /** Ordered field descriptors for form rendering. */
+    readonly fields: readonly TaskFieldDescriptor[];
+    /** Logical field groups for form section rendering. */
+    readonly fieldGroups: readonly TaskFieldGroup[];
+    /** JSON Schema (draft 2020-12) for the task_config payload. */
+    readonly configJsonSchema: Record<string, unknown>;
+    /** JSON Schema describing the task's output shape. */
+    readonly outputJsonSchema?: Record<string, unknown>;
+    /** YAML code examples demonstrating common usage patterns. */
+    readonly yamlExamples?: readonly string[];
+    /** Documentation URL path (relative to docs root). */
+    readonly documentationUrl: string;
+    /** Whether this task kind invokes AI models. */
+    readonly isAiNative: boolean;
+    /** Whether this task kind requires external service connectivity. */
+    readonly requiresExternalService: boolean;
+}
+/** Functional category for grouping task kinds in the UI. */
+export type TaskKindCategory = "control_flow" | "invocation" | "ai" | "data" | "governance" | "event" | "unspecified";
+/** Describes a single field in a task configuration message. */
+export interface TaskFieldDescriptor {
+    /** Proto field name (snake_case). */
+    readonly name: string;
+    /** Human-readable label for form rendering. */
+    readonly displayName: string;
+    /** Field description from proto comments. */
+    readonly description: string;
+    /** Data type for rendering the appropriate form control. */
+    readonly type: TaskFieldType;
+    /** Whether the field is required. */
+    readonly required: boolean;
+    /** Whether the field accepts ${ } expression interpolation. */
+    readonly isExpression?: boolean;
+    /** Default value as a JSON-encoded string. */
+    readonly defaultValue?: string;
+    /** Valid enum values when type is "enum". */
+    readonly enumValues?: readonly string[];
+    /** Group this field belongs to for form section rendering. */
+    readonly groupId?: string;
+    /** Proto field number for stable identification. */
+    readonly fieldNumber: number;
+    /** For repeated: the element type. For message: the nested type name. */
+    readonly elementType?: string;
+    /** Human-readable validation constraint descriptions. */
+    readonly validationHints?: readonly string[];
+}
+/** Data type of a task configuration field. */
+export type TaskFieldType = "string" | "int32" | "float" | "bool" | "enum" | "struct" | "repeated" | "map" | "message";
+/** Logical grouping of fields for form section rendering. */
+export interface TaskFieldGroup {
+    /** Group identifier. */
+    readonly id: string;
+    /** Human-readable label for the group section header. */
+    readonly displayName: string;
+    /** Optional description shown below the group header. */
+    readonly description?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/workflow/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/workflow/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wDAAwD;IACxD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,yCAAyC;IACzC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;IAChD,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;IAChD,+DAA+D;IAC/D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnD,sDAAsD;IACtD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpD,8DAA8D;IAC9D,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1C,sDAAsD;IACtD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,gDAAgD;IAChD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,qEAAqE;IACrE,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;CAC3C;AAED,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GACxB,cAAc,GACd,YAAY,GACZ,IAAI,GACJ,MAAM,GACN,YAAY,GACZ,OAAO,GACP,aAAa,CAAC;AAElB,gEAAgE;AAChE,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,8DAA8D;IAC9D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC9C;AAED,+CAA+C;AAC/C,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,OAAO,GACP,OAAO,GACP,MAAM,GACN,MAAM,GACN,QAAQ,GACR,UAAU,GACV,KAAK,GACL,SAAS,CAAC;AAEd,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,wBAAwB;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B"}

package/workflow/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/workflow/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/workflow/types.ts"],"names":[],"mappings":""}

package/workflow/useCanvasKeyboardShortcuts.d.ts

@@ -0,0 +1,34 @@
+import type { RefObject } from "react";
+import type { CanvasSelection } from "./useWorkflowCanvas";
+/** Options for {@link useCanvasKeyboardShortcuts}. */
+export interface UseCanvasKeyboardShortcutsOptions {
+    readonly containerRef: RefObject<HTMLDivElement | null>;
+    readonly selection: CanvasSelection | null;
+    readonly duplicateNode: (nodeId: string) => void;
+    readonly selectAll: () => void;
+    readonly clearSelection: () => void;
+    readonly onRequestTaskPicker: (position: {
+        x: number;
+        y: number;
+    }, sourceNodeId?: string) => void;
+    readonly onDismiss: () => void;
+}
+/**
+ * Canvas-scoped keyboard shortcuts for the workflow editor.
+ *
+ * Binds shortcuts that are only active when focus is inside the canvas
+ * container, using the same capture-phase listener pattern as
+ * {@link useGraphHistory} (undo/redo). Bare-key shortcuts (N, Escape)
+ * are suppressed when a text input has focus.
+ *
+ * | Shortcut          | Action                                |
+ * |-------------------|---------------------------------------|
+ * | `Ctrl/Cmd+D`      | Duplicate selected node               |
+ * | `Ctrl/Cmd+A`      | Select all non-sentinel nodes         |
+ * | `N` (bare key)    | Open task picker                      |
+ * | `Escape`          | Clear selection / close open overlays |
+ *
+ * @internal Not exported from the SDK barrel.
+ */
+export declare function useCanvasKeyboardShortcuts({ containerRef, selection, duplicateNode, selectAll, clearSelection, onRequestTaskPicker, onDismiss, }: UseCanvasKeyboardShortcutsOptions): void;
+//# sourceMappingURL=useCanvasKeyboardShortcuts.d.ts.map

package/workflow/useCanvasKeyboardShortcuts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCanvasKeyboardShortcuts.d.ts","sourceRoot":"","sources":["../../src/workflow/useCanvasKeyboardShortcuts.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,sDAAsD;AACtD,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,eAAe,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,IAAI,CAAC;IACpC,QAAQ,CAAC,mBAAmB,EAAE,CAC5B,QAAQ,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,EAClC,YAAY,CAAC,EAAE,MAAM,KAClB,IAAI,CAAC;IACV,QAAQ,CAAC,SAAS,EAAE,MAAM,IAAI,CAAC;CAChC;AAgBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,EACzC,YAAY,EACZ,SAAS,EACT,aAAa,EACb,SAAS,EACT,cAAc,EACd,mBAAmB,EACnB,SAAS,GACV,EAAE,iCAAiC,GAAG,IAAI,CA0E1C"}

package/workflow/useCanvasKeyboardShortcuts.js

@@ -0,0 +1,108 @@
+"use client";
+import { useEffect } from "react";
+function isTextInput(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    const tag = target.tagName;
+    if (tag === "INPUT" || tag === "TEXTAREA" || tag === "SELECT")
+        return true;
+    if (target.isContentEditable)
+        return true;
+    if (target.getAttribute("role") === "textbox")
+        return true;
+    return false;
+}
+function isFocusInsideContainer(container) {
+    const active = document.activeElement;
+    return active === container || container.contains(active);
+}
+/**
+ * Canvas-scoped keyboard shortcuts for the workflow editor.
+ *
+ * Binds shortcuts that are only active when focus is inside the canvas
+ * container, using the same capture-phase listener pattern as
+ * {@link useGraphHistory} (undo/redo). Bare-key shortcuts (N, Escape)
+ * are suppressed when a text input has focus.
+ *
+ * | Shortcut          | Action                                |
+ * |-------------------|---------------------------------------|
+ * | `Ctrl/Cmd+D`      | Duplicate selected node               |
+ * | `Ctrl/Cmd+A`      | Select all non-sentinel nodes         |
+ * | `N` (bare key)    | Open task picker                      |
+ * | `Escape`          | Clear selection / close open overlays |
+ *
+ * @internal Not exported from the SDK barrel.
+ */
+export function useCanvasKeyboardShortcuts({ containerRef, selection, duplicateNode, selectAll, clearSelection, onRequestTaskPicker, onDismiss, }) {
+    useEffect(() => {
+        const container = containerRef.current;
+        if (!container)
+            return;
+        function handleKeyDown(e) {
+            if (!container || !isFocusInsideContainer(container))
+                return;
+            const isMod = e.metaKey || e.ctrlKey;
+            // Ctrl/Cmd+D — duplicate selected node
+            if (isMod && !e.shiftKey && !e.altKey && e.key.toLowerCase() === "d") {
+                e.preventDefault();
+                e.stopPropagation();
+                if (selection?.type === "node") {
+                    duplicateNode(selection.id);
+                }
+                return;
+            }
+            // Ctrl/Cmd+A — select all
+            if (isMod && !e.shiftKey && !e.altKey && e.key.toLowerCase() === "a") {
+                if (isTextInput(e.target))
+                    return;
+                e.preventDefault();
+                e.stopPropagation();
+                selectAll();
+                return;
+            }
+            // Bare-key shortcuts — skip when typing in a text field
+            if (isMod || e.altKey)
+                return;
+            // Escape — clear selection, close menus/pickers
+            if (e.key === "Escape") {
+                e.preventDefault();
+                e.stopPropagation();
+                onDismiss();
+                clearSelection();
+                return;
+            }
+            // N — open task picker
+            if (!e.shiftKey && e.key.toLowerCase() === "n") {
+                if (isTextInput(e.target))
+                    return;
+                e.preventDefault();
+                e.stopPropagation();
+                if (selection?.type === "node") {
+                    // Position below the selected node — the editor resolves
+                    // the actual screen coordinates from the node's React Flow position.
+                    onRequestTaskPicker({ x: 0, y: 0 }, selection.id);
+                }
+                else {
+                    // Viewport center
+                    const rect = container.getBoundingClientRect();
+                    onRequestTaskPicker({
+                        x: rect.left + rect.width / 2,
+                        y: rect.top + rect.height / 2,
+                    });
+                }
+                return;
+            }
+        }
+        document.addEventListener("keydown", handleKeyDown, true);
+        return () => document.removeEventListener("keydown", handleKeyDown, true);
+    }, [
+        containerRef,
+        selection,
+        duplicateNode,
+        selectAll,
+        clearSelection,
+        onRequestTaskPicker,
+        onDismiss,
+    ]);
+}
+//# sourceMappingURL=useCanvasKeyboardShortcuts.js.map

package/workflow/useCanvasKeyboardShortcuts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCanvasKeyboardShortcuts.js","sourceRoot":"","sources":["../../src/workflow/useCanvasKeyboardShortcuts.ts"],"names":[],"mappings":"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"}

package/workflow/useDiagnoseExecutionFlow.d.ts

@@ -0,0 +1,87 @@
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+/**
+ * Lifecycle phases for the workflow execution diagnosis flow.
+ *
+ * - `idle` — mounted, waiting for auto-start or manual trigger
+ * - `starting` — creating session + execution
+ * - `streaming` — agent is analyzing (tool calls, reasoning visible)
+ * - `complete` — agent finished, YAML fix extracted (diff available)
+ * - `ready` — agent finished without YAML (runtime error explanation),
+ *   or user accepted/discarded a fix; follow-up available
+ * - `error` — a failure occurred (RPC, stream)
+ */
+export type DiagnosePhase = "idle" | "starting" | "streaming" | "complete" | "ready" | "error";
+/** Options for {@link useDiagnoseExecutionFlow}. */
+export interface UseDiagnoseExecutionFlowOptions {
+    /** ID of the failed workflow execution to diagnose. */
+    readonly executionId: string;
+    /** Organization slug for session and execution creation. */
+    readonly org: string;
+    /** Current workflow YAML for diff computation (optional). */
+    readonly currentWorkflowYaml?: string;
+    /**
+     * Whether to start diagnosis automatically on mount.
+     * @default true
+     */
+    readonly autoStart?: boolean;
+    /** Called when any step fails. Also available via the `error` return. */
+    readonly onError?: (message: string) => void;
+}
+/** Return value of {@link useDiagnoseExecutionFlow}. */
+export interface UseDiagnoseExecutionFlowReturn {
+    /** Current lifecycle phase. */
+    readonly phase: DiagnosePhase;
+    /** 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 fix 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;
+    /** Start or restart the diagnosis. Callable from `idle` or `error` phases. */
+    readonly diagnose: () => Promise<void>;
+    /** Send a follow-up question within the same session. */
+    readonly sendFollowUp: (message: string) => Promise<void>;
+    /** Accept the extracted YAML fix. Returns the YAML string. Transitions to `ready`. */
+    readonly acceptFix: () => string | null;
+    /** Discard the extracted YAML without applying. Transitions to `ready`. */
+    readonly discardFix: () => void;
+    /** Reset all state to initial values. Does not delete the server-side session. */
+    readonly reset: () => void;
+}
+/**
+ * Behavior hook that orchestrates agent-powered workflow execution
+ * diagnosis using the built-in Workflow Architect system agent.
+ *
+ * Manages a multi-turn conversation within a single Session:
+ * - First turn creates a Session + AgentExecution with diagnosis context
+ * - Subsequent turns reuse the Session (conversational context)
+ * - Each turn streams agent messages via {@link useExecutionStream}
+ * - YAML is extracted from agent responses via {@link extractWorkflowYaml}
+ *   — presence of YAML indicates a definition fix; absence indicates a
+ *   runtime error with explanation only
+ *
+ * Auto-starts diagnosis on mount by default (AD-B5-002). The agent uses
+ * `get_workflow_execution` and `get_workflow_execution_events` MCP tools
+ * to inspect the failure autonomously.
+ *
+ * Framework-agnostic (DD-004), referentially stable returns (DD-010).
+ *
+ * @example
+ * ```tsx
+ * const flow = useDiagnoseExecutionFlow({
+ *   executionId: "wex_abc123",
+ *   org: "acme",
+ *   onError: (msg) => toast.error(msg),
+ * });
+ *
+ * <WorkflowRepairCard flow={flow} onApplyFix={...} onClose={...} />
+ * ```
+ */
+export declare function useDiagnoseExecutionFlow(options: UseDiagnoseExecutionFlowOptions): UseDiagnoseExecutionFlowReturn;
+//# sourceMappingURL=useDiagnoseExecutionFlow.d.ts.map

package/workflow/useDiagnoseExecutionFlow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDiagnoseExecutionFlow.d.ts","sourceRoot":"","sources":["../../src/workflow/useDiagnoseExecutionFlow.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6DAA6D,CAAC;AAalG;;;;;;;;;;GAUG;AACH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,UAAU,GACV,WAAW,GACX,UAAU,GACV,OAAO,GACP,OAAO,CAAC;AAEZ,oDAAoD;AACpD,MAAM,WAAW,+BAA+B;IAC9C,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,4DAA4D;IAC5D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AAED,wDAAwD;AACxD,MAAM,WAAW,8BAA8B;IAC7C,+BAA+B;IAC/B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,mBAAmB,EAAE,SAAS,cAAc,EAAE,CAAC;IACxD,sEAAsE;IACtE,QAAQ,CAAC,eAAe,EAAE,cAAc,GAAG,IAAI,CAAC;IAChD,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,iFAAiF;IACjF,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC,sDAAsD;IACtD,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC,yDAAyD;IACzD,QAAQ,CAAC,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,sFAAsF;IACtF,QAAQ,CAAC,SAAS,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACxC,2EAA2E;IAC3E,QAAQ,CAAC,UAAU,EAAE,MAAM,IAAI,CAAC;IAChC,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;CAC5B;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,+BAA+B,GACvC,8BAA8B,CAuQhC"}

package/workflow/useDiagnoseExecutionFlow.js

@@ -0,0 +1,257 @@
+"use client";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+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, } from "./extract-workflow-yaml";
+const AGENT_REF = { org: "", slug: "workflow-architect" };
+const MIN_FOLLOWUP_LENGTH = 5;
+/**
+ * Behavior hook that orchestrates agent-powered workflow execution
+ * diagnosis using the built-in Workflow Architect system agent.
+ *
+ * Manages a multi-turn conversation within a single Session:
+ * - First turn creates a Session + AgentExecution with diagnosis context
+ * - Subsequent turns reuse the Session (conversational context)
+ * - Each turn streams agent messages via {@link useExecutionStream}
+ * - YAML is extracted from agent responses via {@link extractWorkflowYaml}
+ *   — presence of YAML indicates a definition fix; absence indicates a
+ *   runtime error with explanation only
+ *
+ * Auto-starts diagnosis on mount by default (AD-B5-002). The agent uses
+ * `get_workflow_execution` and `get_workflow_execution_events` MCP tools
+ * to inspect the failure autonomously.
+ *
+ * Framework-agnostic (DD-004), referentially stable returns (DD-010).
+ *
+ * @example
+ * ```tsx
+ * const flow = useDiagnoseExecutionFlow({
+ *   executionId: "wex_abc123",
+ *   org: "acme",
+ *   onError: (msg) => toast.error(msg),
+ * });
+ *
+ * <WorkflowRepairCard flow={flow} onApplyFix={...} onClose={...} />
+ * ```
+ */
+export function useDiagnoseExecutionFlow(options) {
+    const { executionId, org, autoStart = true, onError } = options;
+    const [phase, setPhase] = useState("idle");
+    const [activeExecutionId, setActiveExecutionId] = useState(null);
+    const [completedExecutions, setCompletedExecutions] = useState([]);
+    const [extracted, setExtracted] = useState(null);
+    const [error, setError] = useState(null);
+    const orgRef = useRef(org);
+    orgRef.current = org;
+    const executionIdRef = useRef(executionId);
+    executionIdRef.current = executionId;
+    const onErrorRef = useRef(onError);
+    onErrorRef.current = onError;
+    const sessionIdRef = useRef(null);
+    const prevTerminalRef = useRef(false);
+    const autoStartedRef = useRef(false);
+    const { create: createSession } = useCreateSession();
+    const { create: createExecution } = useCreateAgentExecution();
+    const conversationStore = useConversationStoreRef();
+    const stream = useExecutionStream(activeExecutionId, {
+        store: conversationStore,
+    });
+    // ---------------------------------------------------------------------------
+    // Build the initial diagnosis message
+    // ---------------------------------------------------------------------------
+    const buildDiagnosisMessage = useCallback(() => {
+        return (`Diagnose the failed workflow execution \`${executionIdRef.current}\`.\n\n` +
+            "Analyze the failure root cause using the execution status and event log.\n" +
+            "If this is a workflow definition error, generate a validated fix.\n" +
+            "If this is a runtime error, explain the root cause and suggest operational remediation.");
+    }, []);
+    // ---------------------------------------------------------------------------
+    // 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");
+            }
+            setActiveExecutionId(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]);
+    // ---------------------------------------------------------------------------
+    // Start diagnosis (initial turn)
+    // ---------------------------------------------------------------------------
+    const diagnose = useCallback(async () => {
+        if (phase !== "idle" && 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 = buildDiagnosisMessage();
+            const { executionId: newExecutionId } = await createExecution({
+                org: orgRef.current,
+                sessionId: activeSessionId,
+                message,
+            });
+            setActiveExecutionId(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, buildDiagnosisMessage]);
+    // ---------------------------------------------------------------------------
+    // Send a follow-up question
+    // ---------------------------------------------------------------------------
+    const sendFollowUp = useCallback(async (message) => {
+        const trimmed = message.trim();
+        if (trimmed.length < MIN_FOLLOWUP_LENGTH) {
+            setError(`Follow-up must be at least ${MIN_FOLLOWUP_LENGTH} characters`);
+            return;
+        }
+        if (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 { executionId: newExecutionId } = await createExecution({
+                org: orgRef.current,
+                sessionId: activeSessionId,
+                message: trimmed,
+            });
+            setActiveExecutionId(newExecutionId);
+            setPhase("streaming");
+        }
+        catch (err) {
+            const msg = getUserMessage(err, "Failed to send follow-up to the Workflow Architect agent");
+            setPhase("error");
+            setError(msg);
+            onErrorRef.current?.(msg);
+        }
+    }, [phase, createSession, createExecution]);
+    // ---------------------------------------------------------------------------
+    // Accept / discard extracted YAML fix
+    // ---------------------------------------------------------------------------
+    const acceptFix = useCallback(() => {
+        if (phase !== "complete" || !extracted)
+            return null;
+        const yaml = extracted.yaml;
+        setExtracted(null);
+        setPhase("ready");
+        return yaml;
+    }, [phase, extracted]);
+    const discardFix = useCallback(() => {
+        if (phase !== "complete")
+            return;
+        setExtracted(null);
+        setPhase("ready");
+    }, [phase]);
+    // ---------------------------------------------------------------------------
+    // Reset all state
+    // ---------------------------------------------------------------------------
+    const reset = useCallback(() => {
+        setPhase("idle");
+        setActiveExecutionId(null);
+        setCompletedExecutions([]);
+        setExtracted(null);
+        setError(null);
+        sessionIdRef.current = null;
+        prevTerminalRef.current = false;
+        autoStartedRef.current = false;
+    }, []);
+    // ---------------------------------------------------------------------------
+    // Auto-start on mount (AD-B5-002)
+    // ---------------------------------------------------------------------------
+    useEffect(() => {
+        if (autoStart && phase === "idle" && !autoStartedRef.current) {
+            autoStartedRef.current = true;
+            diagnose();
+        }
+    }, [autoStart, phase, diagnose]);
+    // ---------------------------------------------------------------------------
+    // 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,
+        diagnose,
+        sendFollowUp,
+        acceptFix,
+        discardFix,
+        reset,
+    }), [
+        phase,
+        completedExecutions,
+        stream.execution,
+        stream.isStreaming,
+        stream.isConnecting,
+        extracted,
+        error,
+        diagnose,
+        sendFollowUp,
+        acceptFix,
+        discardFix,
+        reset,
+    ]);
+}
+//# sourceMappingURL=useDiagnoseExecutionFlow.js.map

package/workflow/useDiagnoseExecutionFlow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useDiagnoseExecutionFlow.js","sourceRoot":"","sources":["../../src/workflow/useDiagnoseExecutionFlow.ts"],"names":[],"mappings":"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"}

package/workflow/useGraphHistory.d.ts

@@ -0,0 +1,28 @@
+import type { RefObject } from "react";
+import type { WorkflowGraphModel } from "./workflow-graph-model";
+import type { GraphCommand } from "./graph-commands";
+/** Return value of {@link useGraphHistory}. */
+export interface UseGraphHistoryReturn {
+    readonly currentModel: WorkflowGraphModel;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    readonly dispatch: (command: GraphCommand) => WorkflowGraphModel;
+    readonly undo: () => void;
+    readonly redo: () => void;
+    readonly reset: (model: WorkflowGraphModel) => void;
+}
+/**
+ * React wrapper around {@link GraphHistory} providing undo/redo state
+ * management and keyboard shortcut binding.
+ *
+ * Keyboard shortcuts (Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z) are only active
+ * when the referenced container element contains the active focus target,
+ * preventing conflicts with other editors on the page.
+ *
+ * @param initialModel - The starting graph model (from YAML parse).
+ * @param containerRef - Ref to the DOM element that scopes keyboard shortcuts.
+ *
+ * @since T15 Batch 2 (Node Authoring)
+ */
+export declare function useGraphHistory(initialModel: WorkflowGraphModel | null, containerRef: RefObject<HTMLDivElement | null>): UseGraphHistoryReturn;
+//# sourceMappingURL=useGraphHistory.d.ts.map

package/workflow/useGraphHistory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGraphHistory.d.ts","sourceRoot":"","sources":["../../src/workflow/useGraphHistory.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGrD,+CAA+C;AAC/C,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,YAAY,EAAE,kBAAkB,CAAC;IAC1C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,YAAY,KAAK,kBAAkB,CAAC;IACjE,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,CAAC;CACrD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,kBAAkB,GAAG,IAAI,EACvC,YAAY,EAAE,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,GAC7C,qBAAqB,CAsGvB"}