Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
perf(client): persist NodeSpec catalogue + slice-subscription useNodeSpec + stable nodeTypes (Phase 1)
trohitge1eef1e80f27
diff --git a/client/package.json b/client/package.jsonindex 6b892898..74d1fce0 100644--- a/client/package.json+++ b/client/package.json@@ -24,7 +24,9 @@"@radix-ui/react-dialog": "^1.1.15","@radix-ui/react-slot": "^1.2.4","@tailwindcss/typography": "^0.5.19",- "@tanstack/react-query": "^5",+ "@tanstack/query-sync-storage-persister": "^5.100.2",+ "@tanstack/react-query": "^5.100.2",+ "@tanstack/react-query-persist-client": "^5.100.2","@types/google.maps": "^3.58.1","@types/node": "^24.3.1","@types/prismjs": "^1.26.5",@@ -79,7 +81,7 @@},"devDependencies": {"@tailwindcss/vite": "^4.2.2",- "@tanstack/react-query-devtools": "^5.99.0",+ "@tanstack/react-query-devtools": "^5.100.2","@testing-library/jest-dom": "^6.9.1","@testing-library/react": "^16.3.2","@testing-library/user-event": "^14.5.2",diff --git a/client/src/Dashboard.tsx b/client/src/Dashboard.tsxindex baa35834..29f8076e 100644--- a/client/src/Dashboard.tsx+++ b/client/src/Dashboard.tsx@@ -101,10 +101,12 @@ const createNodeTypes = (): Record<string, React.ComponentType<any>> => {return types;};-// Create node types once at module load time-const moduleNodeTypes = createNodeTypes();--// Edge types configuration - enables conditional edge rendering+// Edge types configuration - enables conditional edge rendering.+// nodeTypes is built inside the component (see useMemo below) so the+// build runs after PersistQueryClientProvider has hydrated the cache+// from localStorage. A module-scope build runs at import time when+// the cache is always empty, which forces React Flow to remount every+// canvas node when prefetch lands (the "canvas-wide snap" symptom).const moduleEdgeTypes = {conditional: ConditionalEdge,};@@ -267,7 +269,7 @@ const DashboardContent: React.FC = () => {} = useWorkflowManagement();const { collapsedSections, searchQuery, setSearchQuery, toggleSection } = useComponentPalette();- const { saveNodeParameters, getAllNodeParameters, executeWorkflow, deployWorkflow, cancelDeployment, nodeStatuses, deploymentStatus, workflowLock, isConnected, sendRequest } = useWebSocket();+ const { saveNodeParameters, getAllNodeParameters, executeWorkflow, deployWorkflow, cancelDeployment, nodeStatuses, deploymentStatus, workflowLock, isConnected, isReady, sendRequest } = useWebSocket();const applyUIDefaults = useAppStore((state) => state.applyUIDefaults);// Workflows list: server-owned data, cached by TanStack Query.@@ -392,9 +394,14 @@ const DashboardContent: React.FC = () => {// completes, bumping `specsReady` flips the React Flow nodeTypes ref// so spec.componentKind dispatch becomes effective (Wave 10.D step 2).const hasPrefetchedSpecs = React.useRef(false);- const [specsReady, setSpecsReady] = React.useState(false);+ // Seed from the persisted cache. With PersistQueryClientProvider in+ // place the cache is hydrated from localStorage before the first+ // render, so a warm start can skip the cold→warm remount entirely.+ const [specsReady, setSpecsReady] = React.useState(+ () => listCachedNodeSpecs().length > 0,+ );React.useEffect(() => {- if (!isConnected || hasPrefetchedSpecs.current) return;+ if (!isReady || hasPrefetchedSpecs.current) return;if (!featureFlags.nodeSpecBackend) {// When the backend is disabled, mark ready so the legacy fallback// dispatch runs without waiting on a never-completing prefetch.@@ -403,7 +410,7 @@ const DashboardContent: React.FC = () => {}hasPrefetchedSpecs.current = true;void prefetchAllNodeSpecs(sendRequest).finally(() => setSpecsReady(true));- }, [isConnected, sendRequest]);+ }, [isReady, sendRequest]);// Update nodes with execution status classesconst styledNodes = React.useMemo(() => {@@ -542,19 +549,12 @@ const DashboardContent: React.FC = () => {const proOptions = React.useMemo(() => ({ hideAttribution: true }), []);- // Wave 10.D step 2: nodeTypes dispatch map. Cold cache uses the- // module-scope fallback (agents/skills/teamMonitor already correct via- // hardcoded guards in createNodeTypes); post-prefetch we rebuild and- // only swap the reference if any mapping genuinely differs, so React- // Flow doesn't remount every canvas node for a no-op rebuild.- const nodeTypes = React.useMemo(() => {- if (!specsReady) return moduleNodeTypes;- const fresh = createNodeTypes();- for (const key of Object.keys(fresh)) {- if (fresh[key] !== moduleNodeTypes[key]) return fresh;- }- return moduleNodeTypes;- }, [specsReady]);+ // Wave 10.D step 2: nodeTypes dispatch map. Built once per hydration+ // pass — `specsReady` is seeded from the persisted cache, so warm+ // starts get a populated map on the first render and no canvas-wide+ // remount when prefetch lands. Cold first-ever visit still rebuilds+ // when prefetch finishes (one-time cost per browser).+ const nodeTypes = React.useMemo(() => createNodeTypes(), [specsReady]);const edgeTypes = moduleEdgeTypes;// Execute entire workflow from start node to enddiff --git a/client/src/lib/nodeSpec.ts b/client/src/lib/nodeSpec.tsindex 28a00574..6dedbe36 100644--- a/client/src/lib/nodeSpec.ts+++ b/client/src/lib/nodeSpec.ts@@ -12,7 +12,8 @@* See C:\\Users\\Tgroh\\.claude\\plans\\typed-splashing-crown.md.*/-import { useQuery, type UseQueryResult } from '@tanstack/react-query';+import { useEffect, useSyncExternalStore } from 'react';+import { hashKey, useQuery, type UseQueryResult } from '@tanstack/react-query';import { nodeSpecToDescription, type NodeSpec } from '../adapters/nodeSpecToDescription';import type { INodeTypeDescription } from '../types/INodeProperties';import { featureFlags } from './featureFlags';@@ -73,37 +74,45 @@ export function getCachedNodeSpec(nodeType: string): NodeSpec | null {}/**- * Reactive spec subscription — tRPC `wsLink` / TanStack-Query+WS pattern.+ * Reactive spec subscription via the QueryCache as an external store.*- * The `queryFn` sends a WS request whose Promise resolves via the- * correlated response. TanStack auto-fires on mount, so cold-cache- * renders are self-healing — no dependency on `prefetchAllNodeSpecs`- * running first. When the prefetch does run (same queryKey), it warms- * the cache and this hook reads from it instantly.+ * Previous implementation opened a `useQuery` observer per call site;+ * with ~80 palette items + N canvas nodes that produced 80+N observers,+ * each woken up on every cache write. The slice-subscription pattern+ * here re-renders only consumers of the *specific* spec key that+ * changed — observer count drops to zero. Pattern documented at+ * https://react.dev/reference/react/useSyncExternalStore and called+ * out by TanStack's docs as the canonical escape hatch from useQuery.*- * References:- * - TkDodo: https://tkdodo.eu/blog/using-web-sockets-with-react-query- * - tRPC wsLink: https://trpc.io/docs/client/links/wsLink+ * Cache population is owned by `prefetchAllNodeSpecs` (boot once) and+ * the persisted localStorage hydration set up in lib/queryPersist.ts;+ * a missing key triggers a one-shot lazy fetch via useEffect rather+ * than a long-lived observer.*/export function useNodeSpec(nodeType: string | undefined | null): NodeSpec | null {- const { sendRequest, isConnected } = useWebSocket();- const { data } = useQuery<NodeSpec | null>({- queryKey: nodeSpecQueryKey(nodeType ?? '__none__'),- queryFn: async () => {- if (!nodeType) return null;- try {- const response = await sendRequest('get_node_spec', { node_type: nodeType });- return (response?.spec ?? null) as NodeSpec | null;- } catch {- return null;- }- },- enabled: !!nodeType && isConnected,- // Node specs only change with a backend deploy; dev restarts are- // covered by the WS reconnect handler which invalidates ['nodeSpec'].- staleTime: STALE_TIME.FOREVER,- });- return data ?? null;+ const { sendRequest, isReady } = useWebSocket();+ const key = nodeSpecQueryKey(nodeType ?? '__none__');++ const targetHash = hashKey(key);+ const subscribe = (onChange: () => void) => {+ const unsub = queryClient.getQueryCache().subscribe((event) => {+ if (event.query.queryHash === targetHash) onChange();+ });+ return unsub;+ };++ const getSnapshot = () =>+ queryClient.getQueryData<NodeSpec | null>(key) ?? null;++ const data = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);++ useEffect(() => {+ if (!nodeType || !isReady) return;+ if (queryClient.getQueryData(key) !== undefined) return;+ void fetchNodeSpec(nodeType, sendRequest);+ }, [nodeType, isReady, sendRequest]);++ return data;}/**@@ -114,14 +123,14 @@ export function useNodeSpec(nodeType: string | undefined | null): NodeSpec | nul* status-check pattern: check data first, error second, loading last.*/export function useNodeGroups(): UseQueryResult<Record<string, NodeGroupEntry>> {- const { sendRequest, isConnected } = useWebSocket();+ const { sendRequest, isReady } = useWebSocket();return useQuery<Record<string, NodeGroupEntry>>({queryKey: nodeGroupsQueryKey,queryFn: async () => {const response = await sendRequest('get_node_groups', {});return (response?.groups ?? {}) as Record<string, NodeGroupEntry>;},- enabled: isConnected,+ enabled: isReady,staleTime: STALE_TIME.FOREVER,});}diff --git a/client/src/lib/queryPersist.ts b/client/src/lib/queryPersist.tsnew file mode 100644index 00000000..2f806e21--- /dev/null+++ b/client/src/lib/queryPersist.ts@@ -0,0 +1,71 @@+/**+ * TanStack Query persistence wiring.+ *+ * Persists the in-memory query cache to localStorage so that on hard+ * refresh the editor paints node specs / catalogues from last session+ * instead of waiting for the WebSocket handshake + bulk fetch.+ *+ * Buster: tied to root package.json version via Vite's __APP_VERSION__+ * compile-time constant (see vite.config.js). Bumping the version+ * automatically purges stale persisted entries on next load.+ *+ * Filter: only queries declaring staleTime: STALE_TIME.FOREVER are+ * persisted. Those carry data that only changes with a backend deploy+ * (NodeSpec catalogue, node groups). High-frequency / per-session+ * queries (status, parameters) are not persisted.+ *+ * References:+ * https://tanstack.com/query/latest/docs/framework/react/plugins/persistQueryClient+ * https://datatracker.ietf.org/doc/html/rfc5861 (stale-while-revalidate)+ */++import { createSyncStoragePersister } from '@tanstack/query-sync-storage-persister';+import type { Query } from '@tanstack/react-query';++declare const __APP_VERSION__: string;++const APP_VERSION =+ typeof __APP_VERSION__ !== 'undefined' ? __APP_VERSION__ : '0.0.0';++const STORAGE_KEY = 'machina-query-cache';++export const queryPersister = createSyncStoragePersister({+ storage: typeof window !== 'undefined' ? window.localStorage : undefined,+ key: STORAGE_KEY,+ // Throttle persistence writes so high-frequency cache mutations do+ // not thrash localStorage. Default is 1000ms which is fine.+});++/**+ * Buster string. Persisted cache from a different version is purged on+ * load. Use the package.json version so a release bump implicitly+ * invalidates everything.+ */+export const queryBuster = APP_VERSION;++/**+ * Persisted entries are valid for 24h. After that the cache is+ * discarded on hydrate and refetched fresh. RFC 5861 SWR window.+ */+export const queryPersistMaxAge = 24 * 60 * 60 * 1000;++/**+ * Filter predicate: only persist queries that declare+ * `staleTime: Infinity`. That is our project-wide marker for+ * "data only changes with a backend deploy" (catalogues, node specs,+ * node groups). High-frequency or per-session data stays in memory.+ *+ * The key is a defensive string-prefix match in addition to staleTime+ * so a future regression to the staleTime config does not silently+ * start persisting noisy keys.+ */+const PERSISTED_KEY_PREFIXES = ['nodeSpec', 'nodeGroups', 'pluginCatalogue'];++export function shouldPersistQuery(query: Query): boolean {+ const key = query.queryKey;+ if (!Array.isArray(key) || typeof key[0] !== 'string') return false;+ if (!PERSISTED_KEY_PREFIXES.includes(key[0])) return false;+ // Only persist successfully resolved queries; do not write error or+ // pending state to disk.+ return query.state.status === 'success';+}diff --git a/client/src/main.tsx b/client/src/main.tsxindex def1e44d..959ba2c2 100644--- a/client/src/main.tsx+++ b/client/src/main.tsx@@ -1,6 +1,6 @@import { StrictMode } from 'react'import { createRoot } from 'react-dom/client'-import { QueryClientProvider } from '@tanstack/react-query'+import { PersistQueryClientProvider } from '@tanstack/react-query-persist-client'import { ReactQueryDevtools } from '@tanstack/react-query-devtools'import './index.css'import App from './App'@@ -8,10 +8,24 @@ import { ThemeProvider } from './contexts/ThemeContext'import { AuthProvider } from './contexts/AuthContext'import { WebSocketProvider } from './contexts/WebSocketContext'import { queryClient } from './lib/queryClient'+import {+ queryPersister,+ queryBuster,+ queryPersistMaxAge,+ shouldPersistQuery,+} from './lib/queryPersist'createRoot(document.getElementById('root')!).render(<StrictMode>- <QueryClientProvider client={queryClient}>+ <PersistQueryClientProvider+ client={queryClient}+ persistOptions={{+ persister: queryPersister,+ buster: queryBuster,+ maxAge: queryPersistMaxAge,+ dehydrateOptions: { shouldDehydrateQuery: shouldPersistQuery },+ }}+ ><ThemeProvider><AuthProvider><WebSocketProvider>@@ -22,6 +36,6 @@ createRoot(document.getElementById('root')!).render({import.meta.env.DEV && (<ReactQueryDevtools initialIsOpen={false} buttonPosition="bottom-right" />)}- </QueryClientProvider>+ </PersistQueryClientProvider></StrictMode>,)diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex e356ab2e..557f7ee9 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -10,7 +10,7 @@ importers:dependencies:agent-browser:specifier: latest- version: 0.25.5+ version: 0.26.0concurrently:specifier: ^9.2.1version: 9.2.1@@ -43,7 +43,7 @@ importers:version: 2.45.0(@babel/[email protected])(@types/[email protected])(@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]([email protected]))([email protected]))([email protected](@emotion/[email protected])([email protected]([email protected]))([email protected]))([email protected])([email protected])([email protected]([email protected]))([email protected])'@lukemorales/query-key-factory':specifier: ^1.3.4'@radix-ui/react-collapsible':specifier: ^1.1.12version: 1.1.12(@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected])@@ -56,9 +56,15 @@ importers:'@tailwindcss/typography':specifier: ^0.5.19version: 0.5.19([email protected])+ '@tanstack/query-sync-storage-persister':+ specifier: ^5.100.2+ version: 5.100.2'@tanstack/react-query':- specifier: ^5- version: 5.99.0([email protected])+ specifier: ^5.100.2+ version: 5.100.2([email protected])+ '@tanstack/react-query-persist-client':+ specifier: ^5.100.2'@types/google.maps':specifier: ^3.58.1version: 3.58.1@@ -190,8 +196,8 @@ importers:specifier: ^4.2.2version: 4.2.2([email protected](@types/[email protected])([email protected])([email protected])([email protected]))'@tanstack/react-query-devtools':- specifier: ^5.99.0+ specifier: ^5.100.2'@testing-library/jest-dom':specifier: ^6.9.1version: 6.9.1@@ -2400,20 +2406,32 @@ packages:peerDependencies:vite: ^5.2.0 || ^6 || ^7 || ^8- '@tanstack/[email protected]':- resolution: {integrity: sha512-3Jv3WQG0BCcH7G+7lf/bP8QyBfJOXeY+T08Rin3GZ1bshvwlbPt7NrDHMEzGdKIOmOzvIQmxjk28YEQX60k7pQ==}+ '@tanstack/[email protected]':+ resolution: {integrity: sha512-HzzOC7xgSfGGzZ1gTsFZqYz6rxGg3tYF77nTPctin+wEYYLNMP7LjwPVFALEGNdjxkHvcewh1EM5ywixeukS4w==}- '@tanstack/[email protected]':- resolution: {integrity: sha512-m4ufXaJ8FjWXw7xDtyzE/6fkZAyQFg9WrbMrUpt8ZecRJx58jiFOZ2lxZMphZdIpAnIeto/S8stbwLKLusyckQ==}+ '@tanstack/[email protected]':+ resolution: {integrity: sha512-0vAp4Y9RyywcZ3gb+wFoiR+pEViDT2ZG/ZaUhn7zXHuUbxuAdeEKuhlh9SDW2vjsPdm9F2AWqplr/QxhOeoqEQ==}- '@tanstack/[email protected]':- resolution: {integrity: sha512-CqqX7LCU9yOfCY/vBURSx2YSD83ryfX+QkfkaKionTfg1s2Hdm572Ro99gW3QPoJjzvsj1HM4pnN4nbDy3MXKA==}+ '@tanstack/[email protected]':+ resolution: {integrity: sha512-YbKwdY5FpBvPbsLPcp+Wc8+Q0xvAxyeExAy/4226nYcITw5paKoGb+gglRDiZxyOih19nOPKeOCoX5ZTCOoBFg==}++ '@tanstack/[email protected]':+ resolution: {integrity: sha512-/rK8WkiW+9+7Kbu22aS7RNMma/i/xo++uTr4+OrXx1NH/ksQqyTyZA5Km1od7L9sVSFykiXAzZKKRmdgWFKa7g==}++ '@tanstack/[email protected]':+ resolution: {integrity: sha512-PE5Pgotl8GKv4Mi0s4YiwTcA+evvb2fHMMWexJDx0D3EsBjtf3MbhYuv9kt+oBnbbsjQj4LJTza2PG2vw2pdOQ==}+ peerDependencies:+ '@tanstack/react-query': ^5.100.2+ react: ^18 || ^19++ '@tanstack/[email protected]':+ resolution: {integrity: sha512-uV6M79Dw8SO7u/Wa3oXunOE8P/ktu3LTYjVu9N5NS9kdha7RfMfPecGjq87BzYO2ihq4Y8uSDBk+YisW6+znIA==}peerDependencies:- '@tanstack/react-query': ^5.99.0+ '@tanstack/react-query': ^5.100.2react: ^18 || ^19- '@tanstack/[email protected]':- resolution: {integrity: sha512-OY2bCqPemT1LlqJ8Y2CUau4KELnIhhG9Ol3ZndPbdnB095pRbPo1cHuXTndg8iIwtoHTgwZjyaDnQ0xD0mYwAw==}+ '@tanstack/[email protected]':+ resolution: {integrity: sha512-MvvzPcurtzVh4EcbsTfI1BL5GOfdi1S0dk/qhigEghW07MvcHUl/dhfc1FT8hPEquuMtUC+IIAxC0bdmSp/7kA==}peerDependencies:react: ^18 || ^19@@ -2798,8 +2816,8 @@ packages:resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}engines: {node: '>= 14'}- resolution: {integrity: sha512-i7ZHsnB0nZIfZoQj9xavTJNX9nckTVVcaaiWFAaOiEQgvGytzVjftA3PIdq0WiuGba8vsxsYH2XMHxs+9bJkIw==}+ resolution: {integrity: sha512-pdqSfjwbFSp+qnwlb2g23e9wXveIOfMi19xpPA9xZUbzEAUp6W4YBZj6Ybj8z4M7WkcbGDDYc+oDIHDt9R3EDQ==}hasBin: true@@ -7806,10 +7824,10 @@ snapshots:- supports-color- vue- '@lukemorales/[email protected](@tanstack/[email protected])(@tanstack/[email protected]([email protected]))':+ '@lukemorales/[email protected](@tanstack/[email protected])(@tanstack/[email protected]([email protected]))':dependencies:- '@tanstack/query-core': 5.99.0- '@tanstack/react-query': 5.99.0([email protected])+ '@tanstack/query-core': 5.100.2+ '@tanstack/react-query': 5.100.2([email protected])'@mdx-js/[email protected]':dependencies:@@ -9011,19 +9029,34 @@ snapshots:tailwindcss: 4.2.2- '@tanstack/[email protected]': {}+ '@tanstack/[email protected]': {}++ '@tanstack/[email protected]': {}- '@tanstack/[email protected]': {}+ '@tanstack/[email protected]':+ dependencies:+ '@tanstack/query-core': 5.100.2++ '@tanstack/[email protected]':+ dependencies:+ '@tanstack/query-core': 5.100.2+ '@tanstack/query-persist-client-core': 5.100.2++ dependencies:+ '@tanstack/query-devtools': 5.100.2+ '@tanstack/react-query': 5.100.2([email protected])+ react: 19.2.1dependencies:- '@tanstack/query-devtools': 5.99.0- '@tanstack/react-query': 5.99.0([email protected])+ '@tanstack/query-persist-client-core': 5.100.2+ '@tanstack/react-query': 5.100.2([email protected])react: 19.2.1- '@tanstack/[email protected]([email protected])':+ '@tanstack/[email protected]([email protected])':dependencies:- '@tanstack/query-core': 5.99.0+ '@tanstack/query-core': 5.100.2react: 19.2.1'@testing-library/[email protected]':@@ -9501,7 +9534,7 @@ snapshots:- [email protected]: {}+ [email protected]: {}dependencies: