@datalayer/agent-runtimes 1.0.3 → 1.0.5

package/lib/examples/utils/examplesStore.js

@@ -4,34 +4,89 @@
  */
 import { createStore } from 'zustand/vanilla';
 import { useStore } from 'zustand';
-// Import agent examples data files.
-import earthquakeDetectorData from './agents/earthquake-detector.json';
-import stocksWatcherData from './agents/stock-market.json';
-import salesForecasterData from './agents/sales-forecaster.json';
-import socialPostGeneratorData from './agents/social-post-generator.json';
-// Helper function to transform JSON data to Agent format
-const transformAgentData = (data, notebookSuffix, lexicalSuffix) => ({
-    id: data.id,
-    name: data.title,
-    description: data.description,
-    author: data.author,
-    lastEdited: data.editTimestamp,
-    screenshot: data.image,
-    status: data.status,
-    protocol: data.transport,
-    avatarUrl: data.avatarUrl,
-    notebookFile: `${notebookSuffix}.ipynb.json`,
-    lexicalFile: `${lexicalSuffix}.lexical.json`,
-    stars: data.stars || 0,
-    notifications: data.notifications || 0,
+import { listPersonas } from '../../specs/personas';
+const DEFAULT_PRESENTATION = {
+    author: 'Datalayer',
+    lastEdited: 'just now',
+    screenshot: 'https://images.unsplash.com/photo-1531297484001-80022131f5a1?w=300&h=150&fit=crop',
+    status: 'paused',
+    protocol: 'vercel-ai',
+    avatarUrl: 'https://avatars.githubusercontent.com/datalayer',
+    notebookFile: '',
+    lexicalFile: '',
+    stars: 0,
+    notifications: 0,
+};
+const PERSONA_PRESENTATIONS = {
+    sentinel: {
+        author: 'Eric Charles',
+        lastEdited: '53 minutes ago',
+        screenshot: 'https://images.unsplash.com/photo-1589519160732-57fc498494f8?w=300&h=150&fit=crop',
+        status: 'paused',
+        protocol: 'ag-ui',
+        avatarUrl: 'https://avatars.githubusercontent.com/atom',
+        notebookFile: 'earthquake-detector.ipynb.json',
+        lexicalFile: 'earthquake-detector.lexical.json',
+        stars: 4,
+    },
+    trader: {
+        author: 'Gonzalo Peña-Castellanos',
+        lastEdited: '3 days ago',
+        screenshot: 'https://images.unsplash.com/photo-1611974789855-9c2a0a7236a3?w=300&h=150&fit=crop',
+        status: 'paused',
+        protocol: 'acp',
+        avatarUrl: 'https://avatars.githubusercontent.com/desktop',
+        notebookFile: 'stock-market.ipynb.json',
+        lexicalFile: 'stock-market.lexical.json',
+        stars: 1,
+    },
+    forecaster: {
+        author: 'Eric Charles',
+        lastEdited: '1 hour ago',
+        screenshot: 'https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=300&h=150&fit=crop',
+        status: 'running',
+        protocol: 'vercel-ai',
+        avatarUrl: 'https://avatars.githubusercontent.com/github',
+        notebookFile: 'sales-forecaster.ipynb.json',
+        lexicalFile: 'sales-forecaster.lexical.json',
+        stars: 5,
+        notifications: 2,
+    },
+    marketing: {
+        author: 'Eric Charles',
+        lastEdited: '2 hours ago',
+        screenshot: 'https://images.unsplash.com/photo-1611926653458-09294b3142bf?w=300&h=150&fit=crop',
+        status: 'paused',
+        protocol: 'ag-ui',
+        avatarUrl: 'https://avatars.githubusercontent.com/primer',
+        notebookFile: 'social-post-generator.ipynb.json',
+        lexicalFile: 'social-post-generator.lexical.json',
+        stars: 3,
+        notifications: 1,
+    },
+};
+// Build the agent list from the generated personas catalogue.
+const initialAgents = listPersonas().map(persona => {
+    const presentation = {
+        ...DEFAULT_PRESENTATION,
+        ...(PERSONA_PRESENTATIONS[persona.id] ?? {}),
+    };
+    return {
+        id: persona.id,
+        name: persona.name,
+        description: persona.description,
+        author: presentation.author,
+        lastEdited: presentation.lastEdited,
+        screenshot: presentation.screenshot,
+        status: presentation.status,
+        protocol: presentation.protocol,
+        avatarUrl: presentation.avatarUrl,
+        notebookFile: presentation.notebookFile,
+        lexicalFile: presentation.lexicalFile,
+        stars: presentation.stars,
+        notifications: presentation.notifications,
+    };
 });
-// Initialize agents from the agents folder
-const initialAgents = [
-    transformAgentData(earthquakeDetectorData, 'earthquake-detector', 'earthquake-detector'),
-    transformAgentData(stocksWatcherData, 'stock-market', 'stock-market'),
-    transformAgentData(salesForecasterData, 'sales-forecaster', 'sales-forecaster'),
-    transformAgentData(socialPostGeneratorData, 'social-post-generator', 'social-post-generator'),
-];
 export const agentsStore = createStore(set => ({
     agents: initialAgents,
     getAgentById: (id) => {

package/lib/hooks/index.d.ts

@@ -40,7 +40,7 @@ export { useFrontendTool, useBackendTool, useRegisteredTools, useTool, usePendin
  * ChatBase infrastructure hooks.
  */
 export { useConfig } from './useConfig';
-export { useSkills } from './useSkills';
+export { useSkills, useSkillActions, useAgentRuntimeLoadedSkills as useAgentLoadedSkills, } from './useSkills';
 export { useContextSnapshot } from './useContextSnapshot';
 export { useSandbox } from './useSandbox';
 /**
@@ -66,19 +66,19 @@ export { useVercelAI } from './useVercelAI';
 /**
  * Unified hook for managing agents — both ephemeral and durable.
  */
-export { useAgents } from './useAgents';
+export { useAgentRuntimes } from './useAgentRuntimes';
 /**
  * Runtime query and mutation hooks.
  */
-export { useAgentsRuntimes, useAgentRuntimes, useAgentRuntimeByPodName, useCreateAgentRuntime, useDeleteAgentRuntime, useRefreshAgentRuntimes, agentQueryKeys, AGENT_QUERY_OPTIONS, useAgentLifecycleStore, getAgentLifecycleKey, } from './useAgents';
+export { useAgentsRuntimes, useAgentRuntimesQuery, useAgentRuntimeByPodName, useCreateAgentRuntime, useDeleteAgentRuntime, useRefreshAgentRuntimes, agentQueryKeys, AGENT_QUERY_OPTIONS, useAgentLifecycleStore, getAgentLifecycleKey, } from './useAgentRuntimes';
 /**
- * Agent catalog store, AI Agents REST API, and registry hooks.
+ * Agent-runtime WebSocket stream hook.
  */
-export { useAgentCatalogStore, type AgentCatalogStoreState, } from './useAgentsCatalog';
+export { useAgentRuntimeWebSocket, type UseAgentRuntimeWebSocketOptions, } from './useAgentRuntimes';
 /**
- * Agent registry hook.
+ * Agent catalog store, AI Agents REST API, and registry hooks.
  */
-export { useAgentRegistry } from './useAgentsRegistry';
+export { useAgentCatalogStore, type AgentCatalogStoreState, } from './useAgentsCatalog';
 /**
  * Agents Service REST API (deprecated).
  */
@@ -89,5 +89,5 @@ export { useAgentsService, useNotebookAgents } from './useAgentsService';
 export { useCheckpoints, useCheckpointsQuery, useRefreshCheckpoints, useDeletePausedAgentRuntime, useResumePausedAgentRuntime, usePauseAgent, useResumeAgent, useCheckpointAgent, useTerminateAgent, useAgentLifecycle, type CheckpointData, type PauseAgentParams, type ResumeAgentParams, type CheckpointAgentParams, type TerminateAgentParams, type AgentLifecycleOptions, type AgentLifecycleReturn, } from './useCheckpoints';
 export { useToolApprovals, useToolApprovalsQuery, usePendingApprovalCount, useApproveToolRequest, useRejectToolRequest, } from './useToolApprovals';
 export { useNotifications, useFilteredNotifications, useUnreadNotificationCount, useMarkNotificationRead, useMarkAllNotificationsRead, useAllAgentEvents, useAgentEvents, useAgentEvent, useCreateAgentEvent, useUpdateAgentEvent, useDeleteAgentEvent, useMarkEventRead, useMarkEventUnread, } from './useNotifications';
-export { useAIAgentsWebSocket, type UseAIAgentsWebSocketOptions, } from './useAIAgentsWebSocket';
+export { useAIAgentsWebSocket, type UseAIAgentsWebSocketOptions, type UseAIAgentsWebSocketResult, type AIAgentsWebSocketCloseInfo, type AIAgentsWebSocketConnectionState, } from './useAIAgentsWebSocket';
 export { useOtelTotalTokens, fetchOtelTotalTokens, fetchOtelMetricTotal, fetchOtelMetricRows, toMetricValue, } from './useMonitoring';

package/lib/hooks/index.js

@@ -47,7 +47,7 @@ export { useFrontendTool, useBackendTool, useRegisteredTools, useTool, usePendin
  * ChatBase infrastructure hooks.
  */
 export { useConfig } from './useConfig';
-export { useSkills } from './useSkills';
+export { useSkills, useSkillActions, useAgentRuntimeLoadedSkills as useAgentLoadedSkills, } from './useSkills';
 export { useContextSnapshot } from './useContextSnapshot';
 export { useSandbox } from './useSandbox';
 // =============================================================================
@@ -79,19 +79,19 @@ export { useVercelAI } from './useVercelAI';
 /**
  * Unified hook for managing agents — both ephemeral and durable.
  */
-export { useAgents } from './useAgents';
+export { useAgentRuntimes } from './useAgentRuntimes';
 /**
  * Runtime query and mutation hooks.
  */
-export { useAgentsRuntimes, useAgentRuntimes, useAgentRuntimeByPodName, useCreateAgentRuntime, useDeleteAgentRuntime, useRefreshAgentRuntimes, agentQueryKeys, AGENT_QUERY_OPTIONS, useAgentLifecycleStore, getAgentLifecycleKey, } from './useAgents';
+export { useAgentsRuntimes, useAgentRuntimesQuery, useAgentRuntimeByPodName, useCreateAgentRuntime, useDeleteAgentRuntime, useRefreshAgentRuntimes, agentQueryKeys, AGENT_QUERY_OPTIONS, useAgentLifecycleStore, getAgentLifecycleKey, } from './useAgentRuntimes';
 /**
- * Agent catalog store, AI Agents REST API, and registry hooks.
+ * Agent-runtime WebSocket stream hook.
  */
-export { useAgentCatalogStore, } from './useAgentsCatalog';
+export { useAgentRuntimeWebSocket, } from './useAgentRuntimes';
 /**
- * Agent registry hook.
+ * Agent catalog store, AI Agents REST API, and registry hooks.
  */
-export { useAgentRegistry } from './useAgentsRegistry';
+export { useAgentCatalogStore, } from './useAgentsCatalog';
 /**
  * Agents Service REST API (deprecated).
  */

package/lib/hooks/useA2A.d.ts

@@ -1,5 +1,4 @@
-import type { AgentCard, Task, TaskState } from '@a2a-js/sdk';
-export type { AgentCard, Task, TaskState };
+import type { AgentCard, Task } from '@a2a-js/sdk';
 export interface Message {
     role: 'user' | 'assistant' | 'system';
     content: string;
@@ -9,7 +8,7 @@ export interface Message {
 }
 export interface UseA2AOptions {
     /**
-     * Base URL for the A2A endpoint (e.g., 'http://localhost:8000')
+     * Base URL for the A2A endpoint (e.g., `http://localhost:8000`).
      */
     baseUrl?: string;
     /**

package/lib/hooks/useAIAgentsWebSocket.d.ts

@@ -1,15 +1,54 @@
 /** A message pushed by the server. */
 interface WSMessage {
-    channel: string;
-    event: string;
-    data: Record<string, unknown>;
+    channel?: string;
+    event?: string;
+    data?: Record<string, unknown>;
+    type?: string;
+    payload?: unknown;
+    raw: unknown;
 }
+export interface AIAgentsWebSocketCloseInfo {
+    code: number;
+    reason: string;
+    wasClean: boolean;
+    detail: string;
+}
+export type AIAgentsWebSocketConnectionState = 'connecting' | 'connected' | 'closed';
 /** Options for the WebSocket hook. */
 export interface UseAIAgentsWebSocketOptions {
+    /** Enable/disable the socket lifecycle. */
+    enabled?: boolean;
+    /** Override the service base URL (defaults to aiagentsRunUrl). */
+    baseUrl?: string;
+    /** WebSocket path (or full http/https URL) for the stream endpoint. */
+    path?: string;
+    /** Query string parameters to append to the WebSocket URL. */
+    queryParams?: Record<string, string | number | boolean | null | undefined>;
+    /** Auto-reconnect on unexpected disconnects. */
+    autoReconnect?: boolean;
+    /** Max reconnect attempts before giving up (unbounded by default). */
+    maxReconnectAttempts?: number;
+    /** Reconnect delay strategy (ms) or static delay in ms. */
+    reconnectDelayMs?: number | ((attempt: number) => number);
     /** Additional channels to subscribe to beyond the auto-subscribed user channel. */
     channels?: string[];
+    /** Called when the socket opens. */
+    onOpen?: () => void;
     /** Called for every incoming message (optional). */
     onMessage?: (msg: WSMessage) => void;
+    /** Called when the socket closes. */
+    onClose?: (info: AIAgentsWebSocketCloseInfo) => void;
+}
+export interface UseAIAgentsWebSocketResult {
+    connectionState: AIAgentsWebSocketConnectionState;
+    lastClose: AIAgentsWebSocketCloseInfo | null;
+    reconnectAttempt: number;
+    /**
+     * Send a JSON payload on the underlying WebSocket.
+     * Returns `true` when the message was sent, `false` when the socket
+     * isn't open (the caller can retry once `connectionState === 'connected'`).
+     */
+    send: (payload: unknown) => boolean;
 }
 /**
  * Connect to the AI Agents generic WebSocket.
@@ -25,5 +64,5 @@ export interface UseAIAgentsWebSocketOptions {
  * useAIAgentsWebSocket({ channels: [`agent:${agentId}`] });
  * ```
  */
-export declare function useAIAgentsWebSocket(options?: UseAIAgentsWebSocketOptions): void;
+export declare function useAIAgentsWebSocket(options?: UseAIAgentsWebSocketOptions): UseAIAgentsWebSocketResult;
 export {};

package/lib/hooks/useAIAgentsWebSocket.js

@@ -12,7 +12,7 @@
  *
  * @module hooks/useAIAgentsWebSocket
  */
-import { useEffect, useRef } from 'react';
+import { useEffect, useRef, useState } from 'react';
 import { useQueryClient } from '@tanstack/react-query';
 import { useCoreStore, useIAMStore } from '@datalayer/core/lib/state';
 import { DEFAULT_SERVICE_URLS, API_BASE_PATHS, } from '@datalayer/core/lib/api/constants';
@@ -27,6 +27,8 @@ function useBaseUrl() {
 }
 // ─── Hook ────────────────────────────────────────────────────────────
 const RECONNECT_DELAY_MS = 3_000;
+const WS_DEFAULT_PATH = `${API_BASE_PATHS.AI_AGENTS}/ws`;
+const isObject = (value) => !!value && typeof value === 'object';
 /**
  * Connect to the AI Agents generic WebSocket.
  *
@@ -44,28 +46,68 @@ const RECONNECT_DELAY_MS = 3_000;
 export function useAIAgentsWebSocket(options) {
     const token = useAuthToken();
     const baseUrl = useBaseUrl();
+    const configuredBaseUrl = options?.baseUrl ?? baseUrl;
+    const enabled = options?.enabled ?? true;
+    const wsPath = options?.path ?? WS_DEFAULT_PATH;
+    const queryParamsKey = JSON.stringify(options?.queryParams ?? {});
     const queryClient = useQueryClient();
+    const [connectionState, setConnectionState] = useState('closed');
+    const [lastClose, setLastClose] = useState(null);
+    const [reconnectAttempt, setReconnectAttempt] = useState(0);
     const wsRef = useRef(null);
     const reconnectTimer = useRef(null);
     // Keep a ref of channels so we can re-subscribe on reconnect without
     // tearing down the socket when the array reference changes.
     const channelsRef = useRef(options?.channels ?? []);
     channelsRef.current = options?.channels ?? [];
+    const autoReconnectRef = useRef(options?.autoReconnect ?? true);
+    autoReconnectRef.current = options?.autoReconnect ?? true;
+    const maxReconnectAttemptsRef = useRef(options?.maxReconnectAttempts);
+    maxReconnectAttemptsRef.current = options?.maxReconnectAttempts;
+    const reconnectDelayRef = useRef(options?.reconnectDelayMs);
+    reconnectDelayRef.current = options?.reconnectDelayMs;
+    const onOpenRef = useRef(options?.onOpen);
+    onOpenRef.current = options?.onOpen;
     const onMessageRef = useRef(options?.onMessage);
     onMessageRef.current = options?.onMessage;
+    const onCloseRef = useRef(options?.onClose);
+    onCloseRef.current = options?.onClose;
     useEffect(() => {
-        if (!token)
+        if (!enabled || !token) {
+            setConnectionState('closed');
             return;
+        }
         let disposed = false;
+        let reconnectAttempts = 0;
+        const toWsUrl = () => {
+            const httpUrl = wsPath.startsWith('http://') || wsPath.startsWith('https://')
+                ? wsPath
+                : `${configuredBaseUrl}${wsPath.startsWith('/') ? '' : '/'}${wsPath}`;
+            const url = new URL(httpUrl.replace(/^http/, 'ws'));
+            url.searchParams.set('token', token);
+            const queryParams = JSON.parse(queryParamsKey);
+            Object.entries(queryParams).forEach(([key, value]) => {
+                if (value === null || value === undefined) {
+                    return;
+                }
+                url.searchParams.set(key, String(value));
+            });
+            return url.toString();
+        };
         function connect() {
             if (disposed)
                 return;
-            // Build the WebSocket URL.  Replace http(s) with ws(s).
-            const httpUrl = `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/ws`;
-            const wsUrl = httpUrl.replace(/^http/, 'ws') + `?token=${encodeURIComponent(token)}`;
+            const wsUrl = toWsUrl();
+            setConnectionState('connecting');
             const ws = new WebSocket(wsUrl);
             wsRef.current = ws;
             ws.onopen = () => {
+                reconnectAttempts = 0;
+                setReconnectAttempt(0);
+                setConnectionState('connected');
+                setLastClose(null);
+                console.debug('[ws:connect] url=%s', wsUrl);
+                onOpenRef.current?.();
                 // Subscribe to extra channels.
                 const channels = channelsRef.current;
                 if (channels.length > 0) {
@@ -73,17 +115,33 @@ export function useAIAgentsWebSocket(options) {
                 }
             };
             ws.onmessage = ev => {
-                let msg;
+                let raw;
                 try {
-                    msg = JSON.parse(ev.data);
+                    raw = JSON.parse(String(ev.data));
                 }
                 catch {
                     return;
                 }
+                const msg = isObject(raw)
+                    ? {
+                        channel: typeof raw.channel === 'string' ? raw.channel : undefined,
+                        event: typeof raw.event === 'string' ? raw.event : undefined,
+                        data: isObject(raw.data)
+                            ? raw.data
+                            : undefined,
+                        type: typeof raw.type === 'string' ? raw.type : undefined,
+                        payload: raw.payload,
+                        raw,
+                    }
+                    : { raw };
                 // Fire optional callback.
+                console.debug('[ws:recv] type=%s', msg.type ?? msg.event ?? 'unknown');
                 onMessageRef.current?.(msg);
                 // Invalidate React Query caches based on the event type.
                 const { event } = msg;
+                if (typeof event !== 'string') {
+                    return;
+                }
                 if (event.startsWith('event_')) {
                     queryClient.invalidateQueries({ queryKey: ['agent-events'] });
                 }
@@ -94,15 +152,43 @@ export function useAIAgentsWebSocket(options) {
                     queryClient.invalidateQueries({ queryKey: ['agent-notifications'] });
                 }
             };
-            ws.onclose = () => {
+            ws.onclose = event => {
                 wsRef.current = null;
-                if (!disposed) {
-                    reconnectTimer.current = setTimeout(connect, RECONNECT_DELAY_MS);
+                setConnectionState('closed');
+                const closeInfo = {
+                    code: event.code,
+                    reason: event.reason,
+                    wasClean: event.wasClean,
+                    detail: `code ${event.code}${event.reason ? `: ${event.reason}` : ''}${event.wasClean ? ' (clean)' : ' (unclean)'}`,
+                };
+                setLastClose(closeInfo);
+                console.debug('[ws:disconnect] code=%d reason=%s', event.code, event.reason || '(none)');
+                onCloseRef.current?.(closeInfo);
+                if (disposed || !autoReconnectRef.current) {
+                    return;
                 }
+                reconnectAttempts += 1;
+                setReconnectAttempt(reconnectAttempts);
+                const maxAttempts = maxReconnectAttemptsRef.current;
+                if (typeof maxAttempts === 'number' &&
+                    Number.isFinite(maxAttempts) &&
+                    reconnectAttempts > maxAttempts) {
+                    return;
+                }
+                const configuredDelay = reconnectDelayRef.current;
+                const delay = typeof configuredDelay === 'function'
+                    ? configuredDelay(reconnectAttempts)
+                    : typeof configuredDelay === 'number'
+                        ? configuredDelay
+                        : RECONNECT_DELAY_MS;
+                reconnectTimer.current = setTimeout(connect, Math.max(0, delay));
             };
             ws.onerror = () => {
                 // onclose will fire after onerror; reconnect happens there.
-                ws.close();
+                if (ws.readyState === WebSocket.CONNECTING ||
+                    ws.readyState === WebSocket.OPEN) {
+                    ws.close();
+                }
             };
         }
         connect();
@@ -110,11 +196,13 @@ export function useAIAgentsWebSocket(options) {
             disposed = true;
             if (reconnectTimer.current) {
                 clearTimeout(reconnectTimer.current);
+                reconnectTimer.current = null;
             }
             wsRef.current?.close();
             wsRef.current = null;
+            setConnectionState('closed');
         };
-    }, [token, baseUrl, queryClient]);
+    }, [token, configuredBaseUrl, wsPath, queryParamsKey, enabled, queryClient]);
     // When the channel list changes, send subscribe/unsubscribe diffs.
     const prevChannelsRef = useRef([]);
     useEffect(() => {
@@ -133,4 +221,22 @@ export function useAIAgentsWebSocket(options) {
         }
         prevChannelsRef.current = [...channelsRef.current];
     }, [options?.channels]);
+    return {
+        connectionState,
+        lastClose,
+        reconnectAttempt,
+        send: (payload) => {
+            const ws = wsRef.current;
+            if (!ws || ws.readyState !== WebSocket.OPEN) {
+                return false;
+            }
+            try {
+                ws.send(typeof payload === 'string' ? payload : JSON.stringify(payload));
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
 }

package/lib/hooks/useAcp.d.ts

@@ -1,5 +1,4 @@
-import { type StopReason, type SessionUpdate, type AgentCapabilities, type ClientCapabilities, type PermissionOption, type ToolCallUpdate } from '@agentclientprotocol/sdk';
-export type { StopReason, AgentCapabilities, ClientCapabilities, ToolCallUpdate, PermissionOption, };
+import { type StopReason, type SessionUpdate, type AgentCapabilities, type PermissionOption, type ToolCallUpdate } from '@agentclientprotocol/sdk';
 export type ConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error';
 export type SessionUpdateType = SessionUpdate extends {
     sessionUpdate: infer T;

package/lib/hooks/useAgUi.d.ts

@@ -5,7 +5,7 @@ export interface Message {
 }
 export interface UseAGUIOptions {
     /**
-     * Base URL for the AG-UI endpoint (e.g., 'http://localhost:8000')
+     * Base URL for the AG-UI endpoint (e.g., `http://localhost:8000`).
      */
     baseUrl?: string;
     /**

package/lib/hooks/{useAgents.d.ts → useAgentRuntimes.d.ts}

@@ -98,14 +98,14 @@ export declare const agentQueryKeys: {
  * });
  * ```
  */
-export declare function useAgents(options?: UseAgentOptions): UseAgentReturn;
+export declare function useAgentRuntimes(options?: UseAgentOptions): UseAgentReturn;
 /**
  * Hook to fetch user's agent runtimes (running agent instances).
  *
  * The backend returns active runtimes from the operator **plus** paused
  * runtimes synthesised from Solr checkpoint records (with ``status="paused"``).
  */
-export declare function useAgentRuntimes(): import("@tanstack/react-query").UseQueryResult<AgentRuntimeData[], Error>;
+export declare function useAgentRuntimesQuery(): import("@tanstack/react-query").UseQueryResult<AgentRuntimeData[], Error>;
 /**
  * Hook to fetch a single agent runtime by pod name.
  */
@@ -150,3 +150,40 @@ export interface UseAgentsRuntimesReturn {
  * Consolidated runtime list and mutations.
  */
 export declare function useAgentsRuntimes(): UseAgentsRuntimesReturn;
+export interface UseAgentRuntimeWebSocketOptions {
+    /** Enable/disable the connection. Defaults to `true`. */
+    enabled?: boolean;
+    /**
+     * Base URL of the agent-runtime server
+     * (e.g. `http://localhost:8765`). The WS path is appended automatically.
+     */
+    baseUrl: string;
+    /** Auth token passed as `?token=` query parameter. */
+    authToken?: string;
+    /** Optional `agent_id` query parameter to scope the stream. */
+    agentId?: string;
+    /** Auto-reconnect on unexpected disconnects. Defaults to `true`. */
+    autoReconnect?: boolean;
+    /** Delay between reconnection attempts (ms). Defaults to 3 000. */
+    reconnectDelayMs?: number | ((attempt: number) => number);
+    /** Maximum reconnect attempts. Unbounded by default. */
+    maxReconnectAttempts?: number;
+    /** Additional callback fired for every incoming WS message. */
+    onMessage?: (msg: {
+        type?: string;
+        payload?: unknown;
+        raw: unknown;
+    }) => void;
+}
+/**
+ * Connect to the agent-runtime monitoring WebSocket.
+ *
+ * The hook writes all incoming data into the `useAgentRuntimeStore` Zustand
+ * store. Components that need approvals, MCP status, context snapshots, or
+ * full-context data simply read from the store.
+ *
+ * Mount this hook **once** near the top of your component tree (e.g. in
+ * the example root or in `ChatBase`). All other components read from the
+ * store — no extra WebSocket connections needed.
+ */
+export declare function useAgentRuntimeWebSocket(options: UseAgentRuntimeWebSocketOptions): void;