Skip to content

Self-improving AI Employees for everyone

refactor(client): Phase 2 - wrap WebSocket request/response in Query hooks

trohitgb2b6fba88ed1
diff --git a/client/src/hooks/useNodeParamsQuery.ts b/client/src/hooks/useNodeParamsQuery.ts
new file mode 100644
index 00000000..60638230
--- /dev/null
+++ b/client/src/hooks/useNodeParamsQuery.ts
@@ -0,0 +1,66 @@
+/**
+ * Per-node parameter query + save mutation.
+ *
+ * Wraps the WebSocket get_node_parameters / save_node_parameters request
+ * pair in TanStack Query so:
+ * - sibling components reading the same nodeId share one network call
+ * - cache invalidation after save is automatic
+ * - loading / error states are first-class
+ *
+ * Replaces the hand-rolled useState+useEffect pattern in useParameterPanel.
+ */
+
+import {
+ useQuery,
+ useMutation,
+ useQueryClient,
+ type UseQueryResult,
+} from '@tanstack/react-query';
+import { useWebSocket, type NodeParameters } from '../contexts/WebSocketContext';
+
+export type NodeParametersResponse = NodeParameters;
+
+export const nodeParamsQueryKey = (nodeId: string) =>
+ ['nodeParams', nodeId] as const;
+
+export function useNodeParamsQuery(
+ nodeId: string | null | undefined,
+): UseQueryResult<NodeParametersResponse | null, Error> {
+ const { getNodeParameters, isConnected } = useWebSocket();
+ return useQuery<NodeParametersResponse | null, Error>({
+ queryKey: nodeId ? nodeParamsQueryKey(nodeId) : ['nodeParams', 'none'],
+ queryFn: () => (nodeId ? getNodeParameters(nodeId) : Promise.resolve(null)),
+ enabled: !!nodeId && isConnected,
+ staleTime: 60_000,
+ });
+}
+
+export interface SaveNodeParamsInput {
+ nodeId: string;
+ parameters: Record<string, any>;
+ version?: number;
+}
+
+export function useSaveNodeParamsMutation() {
+ const { saveNodeParameters } = useWebSocket();
+ const qc = useQueryClient();
+ return useMutation<boolean, Error, SaveNodeParamsInput>({
+ mutationFn: async ({ nodeId, parameters, version }) => {
+ const ok = await saveNodeParameters(nodeId, parameters, version);
+ if (!ok) throw new Error('Failed to save node parameters');
+ return ok;
+ },
+ onSuccess: (_ok, { nodeId, parameters }) => {
+ // Optimistic-ish update: stamp the new params into the query cache so
+ // dependents read the freshest value without an extra WS roundtrip.
+ qc.setQueryData<NodeParametersResponse | null>(
+ nodeParamsQueryKey(nodeId),
+ (prev) => ({
+ parameters,
+ version: (prev?.version ?? 0) + 1,
+ timestamp: Date.now(),
+ }),
+ );
+ },
+ });
+}
diff --git a/client/src/hooks/useOnboarding.ts b/client/src/hooks/useOnboarding.ts
index 7b7aac72..fa73f2b8 100644
--- a/client/src/hooks/useOnboarding.ts
+++ b/client/src/hooks/useOnboarding.ts
@@ -1,5 +1,8 @@
-import { useState, useCallback, useEffect, useRef } from 'react';
-import { useWebSocket } from '../contexts/WebSocketContext';
+import { useState, useCallback, useEffect } from 'react';
+import {
+ useUserSettingsQuery,
+ useSaveUserSettingsMutation,
+} from './useUserSettingsQuery';
export interface OnboardingState {
isVisible: boolean;
@@ -12,7 +15,8 @@ export interface OnboardingState {
const TOTAL_STEPS = 5;
export const useOnboarding = (reopenTrigger?: number) => {
- const { sendRequest, isConnected } = useWebSocket();
+ const settingsQuery = useUserSettingsQuery();
+ const saveSettings = useSaveUserSettingsMutation();
const [state, setState] = useState<OnboardingState>({
isVisible: false,
currentStep: 0,
@@ -20,41 +24,38 @@ export const useOnboarding = (reopenTrigger?: number) => {
isLoading: true,
hasChecked: false,
});
- const hasCheckedRef = useRef(false);
- // Check onboarding status on WebSocket connect (once)
+ // Hydrate UI state from query result.
useEffect(() => {
- if (!isConnected || hasCheckedRef.current) return;
- hasCheckedRef.current = true;
+ if (!settingsQuery.isSuccess) return;
+ const settings = settingsQuery.data;
+ const completed = settings?.onboarding_completed ?? false;
+ const step = settings?.onboarding_step ?? 0;
+ setState((prev) => ({
+ ...prev,
+ // Only flip visibility on first hydration; later renders shouldn't
+ // re-open the wizard if the user manually closed it.
+ isVisible: prev.hasChecked ? prev.isVisible : !completed,
+ currentStep: prev.hasChecked ? prev.currentStep : step,
+ isCompleted: completed,
+ isLoading: false,
+ hasChecked: true,
+ }));
+ }, [settingsQuery.isSuccess, settingsQuery.data]);
- const checkOnboarding = async () => {
- try {
- const response = await sendRequest<{ settings: any }>('get_user_settings', {});
- const settings = response?.settings;
- const completed = settings?.onboarding_completed ?? false;
- const step = settings?.onboarding_step ?? 0;
-
- setState({
- isVisible: !completed,
- currentStep: step,
- isCompleted: completed,
- isLoading: false,
- hasChecked: true,
- });
- } catch (error) {
- console.error('[Onboarding] Failed to check status:', error);
- setState(prev => ({ ...prev, isLoading: false, hasChecked: true }));
- }
- };
-
- checkOnboarding();
- }, [isConnected, sendRequest]);
+ // Surface query errors as a non-blocking "checked" state so the app
+ // continues even if the WS round-trip failed.
+ useEffect(() => {
+ if (settingsQuery.isError) {
+ console.error('[Onboarding] Failed to check status:', settingsQuery.error);
+ setState((prev) => ({ ...prev, isLoading: false, hasChecked: true }));
+ }
+ }, [settingsQuery.isError, settingsQuery.error]);
- // Handle reopen trigger from SettingsPanel
+ // Replay trigger from SettingsPanel.
useEffect(() => {
if (reopenTrigger && reopenTrigger > 0) {
- hasCheckedRef.current = false;
- setState(prev => ({
+ setState((prev) => ({
...prev,
isVisible: true,
currentStep: 0,
@@ -63,21 +64,18 @@ export const useOnboarding = (reopenTrigger?: number) => {
}
}, [reopenTrigger]);
- const saveProgress = useCallback(async (step: number, completed: boolean) => {
- try {
- await sendRequest('save_user_settings', {
- settings: {
- onboarding_step: step,
- onboarding_completed: completed,
- }
+ const saveProgress = useCallback(
+ (step: number, completed: boolean) => {
+ saveSettings.mutate({
+ onboarding_step: step,
+ onboarding_completed: completed,
});
- } catch (error) {
- console.error('[Onboarding] Failed to save progress:', error);
- }
- }, [sendRequest]);
+ },
+ [saveSettings],
+ );
const nextStep = useCallback(() => {
- setState(prev => {
+ setState((prev) => {
const next = prev.currentStep + 1;
if (next >= TOTAL_STEPS) {
saveProgress(TOTAL_STEPS, true);
@@ -89,7 +87,7 @@ export const useOnboarding = (reopenTrigger?: number) => {
}, [saveProgress]);
const prevStep = useCallback(() => {
- setState(prev => {
+ setState((prev) => {
const next = Math.max(0, prev.currentStep - 1);
saveProgress(next, false);
return { ...prev, currentStep: next };
@@ -98,12 +96,12 @@ export const useOnboarding = (reopenTrigger?: number) => {
const skip = useCallback(() => {
saveProgress(state.currentStep, true);
- setState(prev => ({ ...prev, isVisible: false, isCompleted: true }));
+ setState((prev) => ({ ...prev, isVisible: false, isCompleted: true }));
}, [saveProgress, state.currentStep]);
const complete = useCallback(() => {
saveProgress(TOTAL_STEPS, true);
- setState(prev => ({ ...prev, isVisible: false, isCompleted: true }));
+ setState((prev) => ({ ...prev, isVisible: false, isCompleted: true }));
}, [saveProgress]);
return {
diff --git a/client/src/hooks/useParameterPanel.ts b/client/src/hooks/useParameterPanel.ts
index ddf06ae0..8bd8a644 100644
--- a/client/src/hooks/useParameterPanel.ts
+++ b/client/src/hooks/useParameterPanel.ts
@@ -1,154 +1,168 @@
-import { useState, useEffect, useMemo, useCallback } from 'react';
+import { useState, useEffect, useMemo, useCallback, useRef } from 'react';
import { useAppStore } from '../store/useAppStore';
import { nodeDefinitions } from '../nodeDefinitions';
import { useWebSocket } from '../contexts/WebSocketContext';
import { SKILL_NODE_TYPES } from '../nodeDefinitions/skillNodes';
+import {
+ useNodeParamsQuery,
+ useSaveNodeParamsMutation,
+} from './useNodeParamsQuery';
+
+/**
+ * Build the default parameter map from a node definition's `properties`.
+ * Pure function so a single instance can be reused across renders without
+ * re-allocating per node type.
+ */
+function defaultsForNodeType(nodeType: string): Record<string, any> {
+ const def = nodeDefinitions[nodeType];
+ if (!def?.properties) return {};
+ const defaults: Record<string, any> = {};
+ for (const param of def.properties as any[]) {
+ defaults[param.name] = param.default !== undefined ? param.default : null;
+ }
+ return defaults;
+}
export const useParameterPanel = () => {
const { selectedNode, setSelectedNode } = useAppStore();
- const [parameters, setParameters] = useState<any>({});
- const [originalParameters, setOriginalParameters] = useState<any>({});
- const [isLoading, setIsLoading] = useState(false);
- const [isSaving, setIsSaving] = useState(false);
- const [error, setError] = useState<string | null>(null);
-
- // Use WebSocket for parameter operations
- const { getNodeParameters, saveNodeParameters, sendRequest, isConnected } = useWebSocket();
+ const { sendRequest, isConnected } = useWebSocket();
- // Use stable references to prevent multiple effect runs
const nodeId = selectedNode?.id;
const nodeType = selectedNode?.type;
+ // Server-cached read.
+ const paramsQuery = useNodeParamsQuery(nodeId);
+ const saveMutation = useSaveNodeParamsMutation();
+
+ // Local edit buffer. Initialized from defaults + saved params on the
+ // first successful query, then mutated by user edits until save.
+ const [editBuffer, setEditBuffer] = useState<Record<string, any>>({});
+ const [originalParameters, setOriginalParameters] = useState<Record<string, any>>({});
+ const [seedingSkill, setSeedingSkill] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+
+ // Initialize the edit buffer once per node selection. Identity of
+ // sendRequest / saveMutation / paramsQuery.data churns on every render,
+ // so we must NOT depend on them — that would trigger an infinite loop
+ // because the optimistic setQueryData on save mints a fresh data object.
+ // The ref guard keeps initialization bound to nodeId transitions only.
+ const initializedFor = useRef<string | null>(null);
+ // Stable refs to read-only deps the effect needs without listing them.
+ const sendRequestRef = useRef(sendRequest);
+ sendRequestRef.current = sendRequest;
+ const saveMutationRef = useRef(saveMutation);
+ saveMutationRef.current = saveMutation;
+ const queryDataRef = useRef(paramsQuery.data);
+ queryDataRef.current = paramsQuery.data;
+
useEffect(() => {
if (!nodeType || !nodeId) {
- setParameters({});
+ setEditBuffer({});
setOriginalParameters({});
setError(null);
+ initializedFor.current = null;
return;
}
-
- const loadParameters = async () => {
- const nodeDefinition = nodeDefinitions[nodeType];
- if (!nodeDefinition) return;
-
- const defaults: any = {};
-
- // Set parameter defaults
- if (nodeDefinition.properties) {
- nodeDefinition.properties.forEach((param: any) => {
- defaults[param.name] = param.default !== undefined ? param.default : null;
- });
- }
-
- setIsLoading(true);
- setError(null);
-
- try {
- // Load saved parameters via WebSocket
- const result = await getNodeParameters(nodeId);
- // Extract parameters from NodeParameters response
- const savedParams = result?.parameters || {};
- let initialParams = { ...defaults, ...savedParams };
-
- console.log('[useParameterPanel] Loading params for node:', nodeId, nodeType);
- console.log('[useParameterPanel] Defaults:', defaults);
- console.log('[useParameterPanel] Saved from backend:', savedParams);
-
- // For skill nodes, seed instructions from SKILL.md only if DB has none yet
- if (SKILL_NODE_TYPES.includes(nodeType) && nodeType !== 'customSkill' && nodeType !== 'masterSkill') {
- const skillName = initialParams.skillName;
- if (skillName && !initialParams.instructions) {
- try {
- console.log('[useParameterPanel] Seeding skill content from SKILL.md for:', skillName);
- const skillResult = await sendRequest('get_skill_content', { skill_name: skillName });
- if (skillResult?.success && skillResult?.instructions) {
- initialParams = {
- ...initialParams,
- instructions: skillResult.instructions
- };
- // Auto-save seeded instructions to DB so next load uses DB directly
- await saveNodeParameters(nodeId, initialParams);
- console.log('[useParameterPanel] Seeded and saved skill instructions for:', skillName);
- }
- } catch (skillErr) {
- console.error('[useParameterPanel] Failed to seed skill content:', skillErr);
- }
+ if (paramsQuery.isLoading) return;
+ if (initializedFor.current === nodeId) return;
+ initializedFor.current = nodeId;
+
+ const defaults = defaultsForNodeType(nodeType);
+ const saved = queryDataRef.current?.parameters ?? {};
+ let initial: Record<string, any> = { ...defaults, ...saved };
+
+ // Seed skill instructions from SKILL.md only the first time a skill
+ // node is opened (DB has no instructions yet). Persist the seeded
+ // value back so subsequent loads come from the DB directly.
+ const isSeedableSkill =
+ SKILL_NODE_TYPES.includes(nodeType) &&
+ nodeType !== 'customSkill' &&
+ nodeType !== 'masterSkill';
+
+ const skillName = initial.skillName as string | undefined;
+ if (isSeedableSkill && skillName && !initial.instructions) {
+ let cancelled = false;
+ setSeedingSkill(true);
+ (async () => {
+ try {
+ const skillResult = await sendRequestRef.current<any>(
+ 'get_skill_content',
+ { skill_name: skillName },
+ );
+ if (cancelled) return;
+ if (skillResult?.success && skillResult?.instructions) {
+ initial = { ...initial, instructions: skillResult.instructions };
+ await saveMutationRef.current.mutateAsync({
+ nodeId,
+ parameters: initial,
+ version: queryDataRef.current?.version,
+ });
+ }
+ } catch (err) {
+ console.error('[useParameterPanel] Failed to seed skill content:', err);
+ } finally {
+ if (!cancelled) {
+ setEditBuffer(initial);
+ setOriginalParameters(initial);
+ setSeedingSkill(false);
}
}
+ })();
+ return () => {
+ cancelled = true;
+ };
+ }
- console.log('[useParameterPanel] Merged initial:', initialParams);
-
- setParameters(initialParams);
- setOriginalParameters(initialParams);
- } catch (err) {
- console.error('Failed to load parameters via WebSocket:', err);
- // Use defaults if WebSocket fails
- setParameters(defaults);
- setOriginalParameters(defaults);
- setError('Failed to load saved parameters');
- } finally {
- setIsLoading(false);
- }
- };
+ setEditBuffer(initial);
+ setOriginalParameters(initial);
+ }, [nodeId, nodeType, paramsQuery.isLoading]);
- loadParameters();
- }, [nodeId, nodeType, getNodeParameters, sendRequest]);
+ // Surface query errors.
+ useEffect(() => {
+ setError(paramsQuery.isError ? 'Failed to load saved parameters' : null);
+ }, [paramsQuery.isError]);
const hasUnsavedChanges = useMemo(() => {
- return JSON.stringify(parameters) !== JSON.stringify(originalParameters);
- }, [parameters, originalParameters]);
+ return JSON.stringify(editBuffer) !== JSON.stringify(originalParameters);
+ }, [editBuffer, originalParameters]);
const handleParameterChange = useCallback((paramName: string, value: any) => {
- setParameters((prevParams: any) => ({
- ...prevParams,
- [paramName]: value
- }));
+ setEditBuffer((prev) => ({ ...prev, [paramName]: value }));
}, []);
const handleSave = useCallback(async () => {
- if (selectedNode) {
- setIsSaving(true);
+ if (!nodeId) return;
+ try {
+ await saveMutation.mutateAsync({
+ nodeId,
+ parameters: editBuffer,
+ version: paramsQuery.data?.version,
+ });
+ setOriginalParameters({ ...editBuffer });
setError(null);
-
- try {
- // Save parameters to database via WebSocket
- const success = await saveNodeParameters(selectedNode.id, parameters);
-
- if (success) {
- // DB is the source of truth for parameters.
- // node.data only stores UI-display fields (label, disabled).
- // Do NOT copy parameters to node.data to prevent data leaking into exports.
- setOriginalParameters({ ...parameters });
- } else {
- setError('Failed to save parameters');
- }
- } catch (err) {
- console.error('Failed to save parameters via WebSocket:', err);
- setError('Failed to save parameters');
- } finally {
- setIsSaving(false);
- }
+ } catch (err) {
+ console.error('Failed to save parameters via WebSocket:', err);
+ setError('Failed to save parameters');
}
- }, [selectedNode, parameters, saveNodeParameters]);
+ }, [nodeId, editBuffer, saveMutation, paramsQuery.data?.version]);
const handleCancel = useCallback(() => {
- setParameters({ ...originalParameters });
+ setEditBuffer({ ...originalParameters });
setSelectedNode(null);
}, [originalParameters, setSelectedNode]);
- const nodeDefinition = selectedNode?.type ? nodeDefinitions[selectedNode.type] : null;
+ const nodeDefinition = nodeType ? nodeDefinitions[nodeType] : null;
return {
selectedNode,
nodeDefinition,
- parameters,
+ parameters: editBuffer,
hasUnsavedChanges,
handleParameterChange,
handleSave,
handleCancel,
- // New state for loading/saving status
- isLoading,
- isSaving,
+ isLoading: paramsQuery.isLoading || seedingSkill,
+ isSaving: saveMutation.isPending,
error,
isConnected,
};
diff --git a/client/src/hooks/useUserSettingsQuery.ts b/client/src/hooks/useUserSettingsQuery.ts
new file mode 100644
index 00000000..370dbe2f
--- /dev/null
+++ b/client/src/hooks/useUserSettingsQuery.ts
@@ -0,0 +1,53 @@
+/**
+ * User settings query + save mutation.
+ *
+ * The `user_settings` row holds onboarding state, UI defaults, and a
+ * handful of other per-user prefs. Owning it in TanStack Query means
+ * onboarding, settings panel, and any future consumer share one cached
+ * read instead of duplicating useState+useEffect bootstraps.
+ */
+
+import {
+ useQuery,
+ useMutation,
+ useQueryClient,
+ type UseQueryResult,
+} from '@tanstack/react-query';
+import { useWebSocket } from '../contexts/WebSocketContext';
+
+export type UserSettings = Record<string, any>;
+
+export const USER_SETTINGS_QUERY_KEY = ['userSettings'] as const;
+
+export function useUserSettingsQuery(): UseQueryResult<UserSettings, Error> {
+ const { sendRequest, isConnected } = useWebSocket();
+ return useQuery<UserSettings, Error>({
+ queryKey: USER_SETTINGS_QUERY_KEY,
+ queryFn: async () => {
+ const response = await sendRequest<{ settings: UserSettings }>(
+ 'get_user_settings',
+ {},
+ );
+ return response?.settings ?? {};
+ },
+ enabled: isConnected,
+ staleTime: 60_000,
+ });
+}
+
+export function useSaveUserSettingsMutation() {
+ const { sendRequest } = useWebSocket();
+ const qc = useQueryClient();
+ return useMutation<UserSettings, Error, UserSettings>({
+ mutationFn: async (patch) => {
+ await sendRequest('save_user_settings', { settings: patch });
+ return patch;
+ },
+ onSuccess: (patch) => {
+ qc.setQueryData<UserSettings>(USER_SETTINGS_QUERY_KEY, (prev) => ({
+ ...(prev ?? {}),
+ ...patch,
+ }));
+ },
+ });
+}