machinaos 0.0.76 → 0.0.78

package/client/src/hooks/useCatalogueQuery.ts

@@ -22,7 +22,7 @@
  */
 
 import { useCallback, useEffect, useMemo, useRef } from 'react';
-import { useQuery, useQueryClient, type UseQueryResult } from '@tanstack/react-query';
+import { useQuery, useQueryClient, type QueryClient, type UseQueryResult } from '@tanstack/react-query';
 import { get as idbGet, set as idbSet } from 'idb-keyval';
 
 import { useWebSocket } from '../contexts/WebSocketContext';
@@ -45,7 +45,17 @@ export interface ServerFieldDef {
   type?: 'string' | 'password';
   secret?: boolean;
   placeholder?: string;
+  /** Initial value pre-populated when the user has nothing stored yet
+      (e.g. canonical local-LLM Base URL — http://localhost:1234/v1).
+      Distinct from `placeholder`: placeholder is a UI ghost-text hint;
+      default actually fills the field so the user can click Fetch
+      without typing. */
+  default?: string;
   required?: boolean;
+  /** Multi-line description shown under the input (e.g. why this field
+      exists, where to find the value). Different from `placeholder` —
+      this is always visible. */
+  help?: string;
 }
 
 /** Raw status-row descriptor — uses a string `ok_field` instead of a callable. */
@@ -104,6 +114,8 @@ export interface ServerProviderConfig {
   usage_service?: string;
   /** Server-resolved: whether a key/token is stored in the credentials DB. */
   stored?: boolean;
+  /** Connected account identifier (email or display name) for OAuth providers. */
+  account_label?: string | null;
 }
 
 export interface CatalogueResponse {
@@ -134,6 +146,33 @@ function isUnchanged(response: WsResponse): response is UnchangedResponse {
 
 export const CATALOGUE_QUERY_KEY = ['credentialCatalogue'] as const;
 
+// ============================================================================
+// Debounced invalidation
+//
+// 8 broadcast handlers in WebSocketContext (api_key_status, whatsapp_status,
+// twitter_oauth_complete, google_oauth_complete, google_status,
+// telegram_status, credential_catalogue_updated, initial_status) all want to
+// refetch the catalogue. During init-burst or multi-service reconnect, those
+// fire within the same tick and would trigger N back-to-back roundtrips.
+// Coalesce them onto a single invalidate at the trailing edge of a 300ms
+// quiet window. Trailing-edge debounce so the freshest state always wins.
+// ============================================================================
+
+const CATALOGUE_INVALIDATE_DEBOUNCE_MS = 300;
+let _catalogueInvalidateTimer: ReturnType<typeof setTimeout> | null = null;
+
+/**
+ * Request a catalogue refetch, coalesced across rapid bursts of broadcasts.
+ * Replaces direct `queryClient.invalidateQueries({ queryKey: CATALOGUE_QUERY_KEY })`.
+ */
+export function invalidateCatalogue(queryClient: QueryClient): void {
+  if (_catalogueInvalidateTimer) clearTimeout(_catalogueInvalidateTimer);
+  _catalogueInvalidateTimer = setTimeout(() => {
+    _catalogueInvalidateTimer = null;
+    void queryClient.invalidateQueries({ queryKey: CATALOGUE_QUERY_KEY });
+  }, CATALOGUE_INVALIDATE_DEBOUNCE_MS);
+}
+
 /** IDB key — we only store the current version, overwritten on each update. */
 const IDB_STORAGE_KEY = 'credentials:catalogue:current';
 
@@ -312,3 +351,30 @@ export function useCatalogueQuery(): UseCatalogueQueryResult {
 
   return useMemo(() => ({ ...query, refresh }), [query, refresh]);
 }
+
+/**
+ * Single-provider "is stored?" selector derived from the catalogue.
+ *
+ * Replaces the retired ``apiKeyStatuses[id].hasKey`` duplication —
+ * `provider.stored` on the server-driven catalogue is the canonical
+ * answer (computed from `auth_service.has_valid_key` on every catalogue
+ * read). Consumers re-render only when this provider's `stored` flag
+ * actually flips, not on every credential mutation, because TanStack
+ * Query produces a new array reference per refetch and React's
+ * referential-equality short-circuits the boolean derivation.
+ */
+export function useProviderStored(providerId: string | null | undefined): boolean {
+  const { data } = useCatalogueQuery();
+  if (!providerId || !data?.providers) return false;
+  return Boolean(data.providers.find((p) => p.id === providerId)?.stored);
+}
+
+/**
+ * Count of providers with a stored credential (any kind — API key,
+ * OAuth, paired QR). Read from the catalogue's `stored` flag.
+ */
+export function useStoredProviderCount(): number {
+  const { data } = useCatalogueQuery();
+  if (!data?.providers) return 0;
+  return data.providers.filter((p) => p.stored).length;
+}

package/client/src/hooks/useDragVariable.ts

@@ -26,7 +26,7 @@ interface DragVariableHookReturn {
  * @param targetNodeId - The ID of the node receiving the drag (target of edge)
  */
 export const useDragVariable = (_targetNodeId: string): DragVariableHookReturn => {
-  const { currentWorkflow } = useAppStore();
+  const currentWorkflow = useAppStore((s) => s.currentWorkflow);
 
   /**
    * Get template variable name for a source node.

package/client/src/hooks/useNodeAllowlist.ts

@@ -4,15 +4,51 @@ import { useWebSocket } from '../contexts/WebSocketContext';
 interface NodeAllowlistResponse {
   show_all: boolean;
   enabled_nodes: string[];
+  /** Mode-independent blocklist by backend group (e.g. 'android' hides
+   *  every plugin in the android group + androidTool). Empty array if
+   *  the backend doesn't ship the field (older deployments). */
+  disabled_groups: string[];
+  /** Mode-independent blocklist by exact node type. Use for one-off
+   *  types whose group label doesn't match (e.g. 'android_agent' is in
+   *  the 'agent' group, not 'android'). */
+  disabled_nodes: string[];
+  /** Mode-independent blocklist for the Credentials Modal by category
+   *  key (matches `category` in server/config/credential_providers.json,
+   *  e.g. 'android' / 'ai' / 'social'). Empty array on older
+   *  deployments. */
+  disabled_credential_categories: string[];
+  /** Mode-independent blocklist for the Master Skill folder
+   *  dropdown — every entry hides the matching subfolder under
+   *  server/skills/. Empty array on older deployments. */
+  disabled_skill_folders: string[];
 }
 
 /**
- * Fetches the node allowlist from the backend and exposes a membership check
- * for the Component Palette.
+ * Fetches the node allowlist from the backend and exposes the membership
+ * checks every UI surface that lists nodes uses (Component Palette,
+ * dropdowns, AI tool selectors, master skill folder, etc.).
  *
- * The backend decides whether to filter (show_all flag); the frontend only
- * checks list membership. While the response is loading, all nodes are shown
- * to avoid a palette flash.
+ * Two independent checks:
+ *
+ *   `isBlocked(nodeType, groups?)` — absolute blocklist. Mode-independent.
+ *     Driven by `disabled_groups` + `disabled_nodes` from the JSON
+ *     config. Use to turn off entire groups (e.g. android) or specific
+ *     types (e.g. android_agent) so they're hidden in BOTH normal and
+ *     dev mode. Pass the node's group array so disabled_groups can
+ *     fire — without groups, only exact-type matches catch.
+ *
+ *   `isAllowed(nodeType)` — positive allowlist. Driven by `enabled_nodes`.
+ *     `show_all=true` (empty list) returns true for everything. Call
+ *     sites typically gate this on `!proMode` so dev mode bypasses
+ *     the allowlist.
+ *
+ *   `isVisible(nodeType, groups?)` — convenience: `!isBlocked && isAllowed`.
+ *     Use when proMode doesn't matter (every surface SHOULD respect
+ *     both layers).
+ *
+ * While the response is loading, all checks return permissively (no
+ * palette flash). Both blocklists default to empty when the backend
+ * doesn't ship the fields (older deployments).
  */
 export const useNodeAllowlist = () => {
   const { sendRequest, isConnected } = useWebSocket();
@@ -28,15 +64,44 @@ export const useNodeAllowlist = () => {
         setConfig({
           show_all: response?.show_all ?? true,
           enabled_nodes: response?.enabled_nodes ?? [],
+          disabled_groups: response?.disabled_groups ?? [],
+          disabled_nodes: response?.disabled_nodes ?? [],
+          disabled_credential_categories: response?.disabled_credential_categories ?? [],
+          disabled_skill_folders: response?.disabled_skill_folders ?? [],
         });
       })
       .catch((error) => {
         console.error('[NodeAllowlist] Failed to fetch:', error);
-        setConfig({ show_all: true, enabled_nodes: [] });
+        setConfig({
+          show_all: true,
+          enabled_nodes: [],
+          disabled_groups: [],
+          disabled_nodes: [],
+          disabled_credential_categories: [],
+          disabled_skill_folders: [],
+        });
       });
   }, [isConnected, sendRequest]);
 
-  const isVisible = useCallback(
+  /** Absolute blocklist check (mode-independent). False while loading
+   *  so UI doesn't pre-hide nodes during the fetch round-trip. */
+  const isBlocked = useCallback(
+    (nodeType: string, groups?: string[] | readonly string[]): boolean => {
+      if (!config) return false;
+      if (config.disabled_nodes.includes(nodeType)) return true;
+      if (groups && groups.length > 0) {
+        for (const g of groups) {
+          if (config.disabled_groups.includes(g)) return true;
+        }
+      }
+      return false;
+    },
+    [config]
+  );
+
+  /** Positive allowlist check. True while loading so UI doesn't hide
+   *  during the fetch. show_all=true returns true for every node. */
+  const isAllowed = useCallback(
     (nodeType: string): boolean => {
       if (!config) return true;
       if (config.show_all) return true;
@@ -45,5 +110,47 @@ export const useNodeAllowlist = () => {
     [config]
   );
 
-  return { isVisible };
+  /** Convenience: hidden if blocked OR not allowed. Honors both layers
+   *  unconditionally — call sites that want to bypass the allowlist
+   *  in dev mode should call isBlocked directly and short-circuit
+   *  the allowlist when proMode is true. */
+  const isVisible = useCallback(
+    (nodeType: string, groups?: string[] | readonly string[]): boolean => {
+      if (isBlocked(nodeType, groups)) return false;
+      return isAllowed(nodeType);
+    },
+    [isBlocked, isAllowed]
+  );
+
+  /** True if the credential category is in the absolute blocklist —
+   *  use to filter the Credentials Modal's category list (e.g. hide
+   *  the entire 'android' panel without removing it from the backend
+   *  catalogue). False while loading so the modal doesn't pre-hide. */
+  const isCredentialCategoryDisabled = useCallback(
+    (categoryKey: string): boolean => {
+      if (!config) return false;
+      return config.disabled_credential_categories.includes(categoryKey);
+    },
+    [config]
+  );
+
+  /** True if the skill folder is in the absolute blocklist — use to
+   *  filter the Master Skill folder dropdown (e.g. hide
+   *  'android_agent' when the android feature is disabled). False
+   *  while loading so the dropdown doesn't pre-hide. */
+  const isSkillFolderDisabled = useCallback(
+    (folderName: string): boolean => {
+      if (!config) return false;
+      return config.disabled_skill_folders.includes(folderName);
+    },
+    [config]
+  );
+
+  return {
+    isVisible,
+    isBlocked,
+    isAllowed,
+    isCredentialCategoryDisabled,
+    isSkillFolderDisabled,
+  };
 };

package/client/src/hooks/useOnboarding.ts

@@ -12,9 +12,21 @@ export interface OnboardingState {
   hasChecked: boolean;
 }
 
-const TOTAL_STEPS = 5;
+const DEFAULT_TOTAL_STEPS = 5;
 
-export const useOnboarding = (reopenTrigger?: number) => {
+/**
+ * Onboarding wizard state hook.
+ *
+ * @param reopenTrigger - bump from SettingsPanel to replay the wizard.
+ * @param totalSteps - number of steps the wizard will render. Caller
+ *   owns the step list (`STEPS.length` in OnboardingWizard); the hook
+ *   uses this only to detect last-step completion. Defaults to 5 for
+ *   backwards compatibility.
+ */
+export const useOnboarding = (
+  reopenTrigger?: number,
+  totalSteps: number = DEFAULT_TOTAL_STEPS,
+) => {
   const settingsQuery = useUserSettingsQuery();
   const saveSettings = useSaveUserSettingsMutation();
   const [state, setState] = useState<OnboardingState>({
@@ -77,14 +89,14 @@ export const useOnboarding = (reopenTrigger?: number) => {
   const nextStep = useCallback(() => {
     setState((prev) => {
       const next = prev.currentStep + 1;
-      if (next >= TOTAL_STEPS) {
-        saveProgress(TOTAL_STEPS, true);
+      if (next >= totalSteps) {
+        saveProgress(totalSteps, true);
         return { ...prev, currentStep: next, isCompleted: true, isVisible: false };
       }
       saveProgress(next, false);
       return { ...prev, currentStep: next };
     });
-  }, [saveProgress]);
+  }, [saveProgress, totalSteps]);
 
   const prevStep = useCallback(() => {
     setState((prev) => {
@@ -100,13 +112,13 @@ export const useOnboarding = (reopenTrigger?: number) => {
   }, [saveProgress, state.currentStep]);
 
   const complete = useCallback(() => {
-    saveProgress(TOTAL_STEPS, true);
+    saveProgress(totalSteps, true);
     setState((prev) => ({ ...prev, isVisible: false, isCompleted: true }));
-  }, [saveProgress]);
+  }, [saveProgress, totalSteps]);
 
   return {
     ...state,
-    totalSteps: TOTAL_STEPS,
+    totalSteps,
     nextStep,
     prevStep,
     skip,

package/client/src/hooks/useParameterPanel.ts

@@ -23,7 +23,8 @@ function defaultsForNodeType(nodeType: string): Record<string, any> {
 }
 
 export const useParameterPanel = () => {
-  const { selectedNode, setSelectedNode } = useAppStore();
+  const selectedNode = useAppStore((s) => s.selectedNode);
+  const setSelectedNode = useAppStore((s) => s.setSelectedNode);
   const { sendRequest, isConnected } = useWebSocket();
 
   const nodeId = selectedNode?.id;

package/client/src/hooks/useReactFlowNodes.ts

@@ -10,7 +10,8 @@ interface UseReactFlowNodesProps {
 }
 
 export const useReactFlowNodes = ({ setNodes, setEdges }: UseReactFlowNodesProps) => {
-  const { selectedNode, setSelectedNode } = useAppStore();
+  const selectedNode = useAppStore((s) => s.selectedNode);
+  const setSelectedNode = useAppStore((s) => s.setSelectedNode);
 
   // Helper function to get node inputs/outputs for both enhanced and legacy nodes
   const getNodeInputs = (nodeType: string): INodeInputDefinition[] => {

package/client/src/hooks/useSound.ts

@@ -0,0 +1,185 @@
+/**
+ * useSound — React glue for the per-theme WebAudio engine.
+ *
+ * `useSoundSync()` mounts once at the Dashboard root. It:
+ *   - mirrors the `soundEnabled` Zustand slice into `Sounds.setEnabled()`
+ *   - reads `--sound-pack` from `:root` after every theme change and
+ *     calls `Sounds.setPack(...)` so the active pack tracks the active
+ *     theme without per-component wiring
+ *   - installs a global mouseenter / touchstart delegate that fires
+ *     `play('hover')` for any element matching the design-handoff hover
+ *     selector list (`.btn`, `.action-btn`, `.row`, `.menu-pop-item`,
+ *     `.wf-card`, `.comp`, `.cmdk-item`, `[data-sound-hover]`).
+ *
+ * `useSound()` is the lightweight handle every event handler uses:
+ *
+ *     const play = useSound();
+ *     <button onClick={() => { play('click'); onSave(); }} />
+ *
+ * `withSound()` is the convenience wrap to spice an existing handler:
+ *
+ *     <Button onClick={withSound('click', onSave)} />
+ *
+ * Adding a new sound event: extend `SoundEvent` in lib/sound.ts, add
+ * an entry per pack, and fire `play('<event>')` from the relevant
+ * handler. No additional wiring here.
+ */
+
+import { useEffect } from 'react';
+import { toast } from 'sonner';
+import { useTheme } from '../contexts/ThemeContext';
+import { useAppStore } from '../store/useAppStore';
+import { Sounds, type SoundPackName, type SoundEvent } from '../lib/sound';
+
+const VALID_PACKS: ReadonlySet<SoundPackName> = new Set([
+  'none', 'parchment', 'marble', 'ink', 'clockwork', 'vibraphone',
+  'terminal', 'scrap', 'crypt', 'bell', 'telex',
+]);
+
+/** Selector for the global hover delegate. Mirrors the upstream
+ *  `app/sound.js` auto-capture list, modulo class additions from W15
+ *  (`.action-btn`, `.wf-card`, `.comp`, `.cmdk-item`). */
+const HOVER_SELECTOR =
+  '.btn, .action-btn, .row, .menu-pop-item, .wf-card, .comp, .cmdk-item, [data-sound-hover]';
+
+function readSoundPack(): SoundPackName {
+  if (typeof document === 'undefined') return 'none';
+  const raw = getComputedStyle(document.documentElement)
+    .getPropertyValue('--sound-pack')
+    .trim()
+    .replace(/['"]/g, '');
+  return VALID_PACKS.has(raw as SoundPackName) ? (raw as SoundPackName) : 'none';
+}
+
+/**
+ * One-shot monkey-patch of `toast.success` / `toast.error` so every
+ * call site fires the matching per-theme sound automatically. Sonner
+ * exports `toast` as a singleton object with mutable methods, so
+ * patching once at module load is safe. Guarded by a flag so React
+ * 18+ Strict-Mode double-invocation of useSoundSync doesn't double-
+ * wrap the methods.
+ */
+let toastPatched = false;
+function patchToast(): void {
+  if (toastPatched) return;
+  toastPatched = true;
+  const originalSuccess = toast.success;
+  const originalError = toast.error;
+  // `toast.success` / `toast.error` accept (message, options) and
+  // return the toast id. We preserve the return type by deferring to
+  // the original after firing the sound.
+  toast.success = ((...args: Parameters<typeof originalSuccess>) => {
+    Sounds.play('success');
+    return originalSuccess.apply(toast, args);
+  }) as typeof originalSuccess;
+  toast.error = ((...args: Parameters<typeof originalError>) => {
+    Sounds.play('error');
+    return originalError.apply(toast, args);
+  }) as typeof originalError;
+}
+
+/** Mount once at the Dashboard root. */
+export function useSoundSync(): void {
+  const { theme } = useTheme();
+  const enabled = useAppStore((s) => s.soundEnabled);
+
+  // Patch sonner's `toast.success` / `toast.error` so every call fires
+  // the matching sound. Idempotent — safe under React Strict Mode.
+  useEffect(() => {
+    patchToast();
+  }, []);
+
+  useEffect(() => {
+    Sounds.setEnabled(enabled);
+  }, [enabled]);
+
+  useEffect(() => {
+    Sounds.setPack(readSoundPack());
+  }, [theme]);
+
+  // Global hover delegate. Capture-phase listener so it picks up
+  // mouseenter on any matching surface without each component wiring
+  // its own onMouseEnter handler. touchstart mirrors the same selector
+  // list for mobile / hybrid devices.
+  useEffect(() => {
+    const handleHover = (event: Event) => {
+      const target = event.target as Element | null;
+      if (!target || typeof target.closest !== 'function') return;
+      if (target.closest(HOVER_SELECTOR)) {
+        Sounds.play('hover');
+      }
+    };
+    // mouseenter doesn't bubble, so we use the capture-phase approach
+    // via mouseover (which does bubble) plus a relatedTarget filter so
+    // a single hover only fires once per crossing-into-element.
+    const handleMouseOver = (event: MouseEvent) => {
+      const target = event.target as Element | null;
+      const related = event.relatedTarget as Element | null;
+      if (!target || typeof target.closest !== 'function') return;
+      const matched = target.closest(HOVER_SELECTOR);
+      if (!matched) return;
+      // Only fire on enter — if the previous mouse position was already
+      // inside the same matched element, skip.
+      if (related && matched.contains(related)) return;
+      Sounds.play('hover');
+    };
+    // Wave 33: PASSIVE listener so the handler can never block scroll /
+    // input dispatch. The handler doesn't call preventDefault, so passive
+    // is safe. Bare `true` (capture-only) registers an ACTIVE listener,
+    // which means the browser must wait for the handler to finish before
+    // dispatching the next input event — on tab return, when a burst of
+    // queued mouseover events fires while the mouse is over the canvas,
+    // the active handler's closest() DOM-walks blocked first-click input
+    // dispatch by 5-15ms. Passive removes that block.
+    //
+    // removeEventListener's options bag only consults `capture` for
+    // matching (W3C spec — passive isn't part of the listener identity),
+    // so the cleanup pair below uses the same shape but TypeScript's
+    // EventListenerOptions doesn't include `passive` — pass `true` for
+    // capture-only removal which matches both add registrations.
+    document.addEventListener('mouseover', handleMouseOver, { capture: true, passive: true });
+    document.addEventListener('touchstart', handleHover, { capture: true, passive: true });
+    return () => {
+      document.removeEventListener('mouseover', handleMouseOver, true);
+      document.removeEventListener('touchstart', handleHover, true);
+    };
+  }, []);
+
+  // One-shot AudioContext unlock on the first user gesture. Modern
+  // browsers (Chrome / Safari) keep the AudioContext suspended until a
+  // resume() call originates from a gesture handler — without this, the
+  // first play() can land microseconds after the gesture frame and the
+  // sound is silently dropped. `Sounds.unlock()` is idempotent so the
+  // `{ once: true }` listeners cover the lifetime fine.
+  useEffect(() => {
+    const handler = () => { Sounds.unlock(); };
+    const opts: AddEventListenerOptions = { once: true, capture: true, passive: true };
+    window.addEventListener('pointerdown', handler, opts);
+    window.addEventListener('keydown', handler, opts);
+    window.addEventListener('touchstart', handler, opts);
+    return () => {
+      window.removeEventListener('pointerdown', handler, opts);
+      window.removeEventListener('keydown', handler, opts);
+      window.removeEventListener('touchstart', handler, opts);
+    };
+  }, []);
+}
+
+/** Play handle. Returns the same `Sounds.play` reference each render. */
+export function useSound(): (event: SoundEvent) => void {
+  return Sounds.play;
+}
+
+/** Wrap an existing onClick / onChange handler so the matching sound
+ *  fires before the underlying handler runs. Sound events are non-
+ *  blocking (fire-and-forget OscillatorNode). When the engine is
+ *  disabled or the active pack is `none`, this is a no-op. */
+export function withSound<E extends ((...args: any[]) => any) | undefined>(
+  event: SoundEvent,
+  handler: E,
+): (...args: E extends (...args: infer P) => any ? P : never[]) => void {
+  return ((...args: any[]) => {
+    Sounds.play(event);
+    handler?.(...args);
+  }) as any;
+}

package/client/src/hooks/useWorkflowManagement.ts

@@ -3,14 +3,12 @@ import { useAppStore } from '../store/useAppStore';
 import { useWorkflowsQuery, type SavedWorkflow } from './useWorkflowsQuery';
 
 export const useWorkflowManagement = () => {
-  const {
-    currentWorkflow,
-    hasUnsavedChanges,
-    updateWorkflow,
-    saveWorkflow,
-    loadWorkflow,
-    createNewWorkflow,
-  } = useAppStore();
+  const currentWorkflow = useAppStore((s) => s.currentWorkflow);
+  const hasUnsavedChanges = useAppStore((s) => s.hasUnsavedChanges);
+  const updateWorkflow = useAppStore((s) => s.updateWorkflow);
+  const saveWorkflow = useAppStore((s) => s.saveWorkflow);
+  const loadWorkflow = useAppStore((s) => s.loadWorkflow);
+  const createNewWorkflow = useAppStore((s) => s.createNewWorkflow);
 
   const { data: savedWorkflows = [] } = useWorkflowsQuery();
 

package/client/src/hooks/useWorkflowOpsListener.ts

@@ -0,0 +1,90 @@
+/**
+ * Listens for backend-pushed `workflow_ops_apply` events and applies
+ * them to the live React Flow canvas via the standard
+ * `applyOperations` reconciler.
+ *
+ * Source of events: `services/status_broadcaster.send_custom_event`
+ * called by the Agent Builder's tool functions
+ * (`server/nodes/tool/agent_builder.py`) after a successful mutation.
+ *
+ * Filtering:
+ *   - Events whose `workflow_id` matches the current workflow apply
+ *     to the canvas in-place.
+ *   - Events for OTHER workflows (e.g. `create_workflow` returning a
+ *     fresh id) surface as a sonner toast with a Switch action so the
+ *     user can jump to the new workflow without losing their place.
+ *
+ * Mounted once in Dashboard.
+ */
+
+import { useEffect } from 'react';
+import type { Node, Edge } from 'reactflow';
+import { toast } from 'sonner';
+
+import { useWebSocket } from '../contexts/WebSocketContext';
+import { useAppStore } from '../store/useAppStore';
+import { applyOperations, type WorkflowOperation } from '../lib/workflowOps';
+
+interface WorkflowOpsApplyEvent {
+  workflow_id?: string | null;
+  caller_node_id?: string | null;
+  operations?: WorkflowOperation[];
+}
+
+interface UseWorkflowOpsListenerProps {
+  nodes: Node[];
+  edges: Edge[];
+  setNodes: (updater: (ns: Node[]) => Node[]) => void;
+  setEdges: (updater: (es: Edge[]) => Edge[]) => void;
+}
+
+export function useWorkflowOpsListener({
+  nodes,
+  edges,
+  setNodes,
+  setEdges,
+}: UseWorkflowOpsListenerProps) {
+  const { addEventListener, saveNodeParameters } = useWebSocket();
+  const currentWorkflowId = useAppStore(s => s.currentWorkflow?.id);
+  const loadWorkflow = useAppStore(s => s.loadWorkflow);
+
+  useEffect(() => {
+    const unsubscribe = addEventListener('workflow_ops_apply', (raw: WorkflowOpsApplyEvent) => {
+      const ops = raw?.operations ?? [];
+      if (ops.length === 0 && !raw?.workflow_id) return;
+
+      // Different workflow -- surface a toast with a switch action.
+      // Used by `create_workflow`, which persists a new workflow but
+      // doesn't try to mutate the canvas the user is currently on.
+      if (raw.workflow_id && raw.workflow_id !== currentWorkflowId) {
+        toast.message('New workflow created', {
+          description: `Workflow ${raw.workflow_id} is ready.`,
+          action: {
+            label: 'Switch',
+            onClick: () => loadWorkflow(raw.workflow_id!),
+          },
+        });
+        return;
+      }
+
+      if (ops.length === 0) return;
+
+      void applyOperations(ops, {
+        nodes,
+        edges,
+        setNodes,
+        setEdges,
+        saveNodeParameters,
+      }).then(result => {
+        if (result.errors.length > 0) {
+          console.warn('[workflow_ops_apply] some ops failed:', result.errors);
+        }
+      });
+    });
+
+    return unsubscribe;
+  }, [
+    addEventListener, currentWorkflowId, loadWorkflow,
+    nodes, edges, setNodes, setEdges, saveNodeParameters,
+  ]);
+}