@datalayer/agent-runtimes 1.0.1 → 1.0.3

package/lib/extensions/A2UIExtension.js

@@ -0,0 +1,202 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A2UI extension for chat component.
+ * Renders A2UI protocol messages from A2A agents using @a2ui/react v0.8.
+ *
+ * @module components/extensions/A2UIExtension
+ */
+import React from 'react';
+import { A2UIViewer, initializeDefaultCatalog } from '@a2ui/react';
+initializeDefaultCatalog();
+function valueMapToObject(valueMap) {
+    const result = {};
+    for (const item of valueMap) {
+        if (item.valueString !== undefined) {
+            result[item.key] = item.valueString;
+            continue;
+        }
+        if (item.valueNumber !== undefined) {
+            result[item.key] = item.valueNumber;
+            continue;
+        }
+        if (item.valueBoolean !== undefined) {
+            result[item.key] = item.valueBoolean;
+            continue;
+        }
+        if (item.valueMap !== undefined) {
+            result[item.key] = valueMapToObject(item.valueMap);
+            continue;
+        }
+        result[item.key] = null;
+    }
+    return result;
+}
+function setNestedValue(obj, path, value) {
+    let current = obj;
+    for (let i = 0; i < path.length - 1; i++) {
+        const key = path[i];
+        const next = current[key];
+        if (!next || typeof next !== 'object' || Array.isArray(next)) {
+            current[key] = {};
+        }
+        current = current[key];
+    }
+    if (path.length > 0) {
+        current[path[path.length - 1]] = value;
+    }
+}
+function processA2UIMessage(context, message) {
+    if (message.beginRendering) {
+        context.surfaces.set(message.beginRendering.surfaceId, {
+            surfaceId: message.beginRendering.surfaceId,
+            root: message.beginRendering.root,
+            mimeType: message.beginRendering.mimeType,
+            components: [],
+            data: {},
+            finished: false,
+        });
+    }
+    if (message.surfaceUpdate) {
+        const surface = context.surfaces.get(message.surfaceUpdate.surfaceId);
+        if (surface) {
+            surface.components = message.surfaceUpdate.components;
+        }
+    }
+    if (message.dataModelUpdate) {
+        const surface = context.surfaces.get(message.dataModelUpdate.surfaceId);
+        const nextData = valueMapToObject(message.dataModelUpdate.contents);
+        if (surface) {
+            if (message.dataModelUpdate.path &&
+                message.dataModelUpdate.path !== '/') {
+                const pathParts = message.dataModelUpdate.path
+                    .split('/')
+                    .filter(Boolean);
+                setNestedValue(surface.data, pathParts, nextData);
+            }
+            else {
+                surface.data = {
+                    ...surface.data,
+                    ...nextData,
+                };
+            }
+            context.dataModels.set(message.dataModelUpdate.surfaceId, surface.data);
+        }
+        else {
+            context.dataModels.set(message.dataModelUpdate.surfaceId, nextData);
+        }
+    }
+    if (message.finishRendering) {
+        const surface = context.surfaces.get(message.finishRendering.surfaceId);
+        if (surface) {
+            surface.finished = true;
+        }
+    }
+}
+function renderSurfaceContent(surface) {
+    const { components, mimeType } = surface;
+    if (components.length === 0) {
+        return null;
+    }
+    switch (mimeType) {
+        case 'text/plain':
+            return React.createElement('pre', null, JSON.stringify(components, null, 2));
+        case 'application/json':
+            return React.createElement('pre', { className: 'json' }, JSON.stringify(components, null, 2));
+        default:
+            return React.createElement('pre', null, JSON.stringify(components, null, 2));
+    }
+}
+function renderSurfaces(context) {
+    const surfacesToRender = Array.from(context.surfaces.values());
+    return React.createElement('div', { className: 'chat-a2ui-container' }, surfacesToRender.map(surface => {
+        if (surface.components.length > 0) {
+            return React.createElement(A2UIViewer, {
+                key: surface.surfaceId,
+                root: surface.root,
+                components: surface.components,
+                data: surface.data,
+                onAction: action => {
+                    console.log('A2UI chat action:', action);
+                },
+            });
+        }
+        return React.createElement('div', {
+            key: surface.surfaceId,
+            className: `chat-a2ui-surface chat-a2ui-surface--${surface.mimeType?.replace('/', '-') || 'unknown'}`,
+        }, renderSurfaceContent(surface));
+    }));
+}
+/**
+ * Create A2UI activity renderer.
+ */
+export function createA2UIRenderer(_customRenderers) {
+    const contexts = new Map();
+    const getContext = (sessionId) => {
+        if (!contexts.has(sessionId)) {
+            contexts.set(sessionId, {
+                surfaces: new Map(),
+                dataModels: new Map(),
+            });
+        }
+        return contexts.get(sessionId);
+    };
+    return {
+        name: 'a2ui-renderer',
+        type: 'activity-renderer',
+        activityTypes: ['a2ui'],
+        render: ({ data }) => {
+            const sessionId = 'default';
+            const context = getContext(sessionId);
+            processA2UIMessage(context, data);
+            return renderSurfaces(context);
+        },
+        priority: 10,
+    };
+}
+/**
+ * A2UI Extension implementation class.
+ */
+export class A2UIExtensionImpl {
+    name = 'a2ui';
+    type = 'activity-renderer';
+    activityTypes = ['a2ui'];
+    priority = 10;
+    contexts = new Map();
+    getSurfaces(sessionId) {
+        const context = this.contexts.get(sessionId);
+        if (!context)
+            return new Map();
+        const result = new Map();
+        for (const [key, surface] of context.surfaces) {
+            result.set(key, surface.components);
+        }
+        return result;
+    }
+    getDataModels(sessionId) {
+        return this.contexts.get(sessionId)?.dataModels || new Map();
+    }
+    processMessage(sessionId, message) {
+        if (!this.contexts.has(sessionId)) {
+            this.contexts.set(sessionId, {
+                surfaces: new Map(),
+                dataModels: new Map(),
+            });
+        }
+        const context = this.contexts.get(sessionId);
+        processA2UIMessage(context, message);
+    }
+    clearSession(sessionId) {
+        this.contexts.delete(sessionId);
+    }
+    render = ({ activityType: _activityType, data, message: _message, }) => {
+        const sessionId = 'default';
+        this.processMessage(sessionId, data);
+        const ctx = this.contexts.get(sessionId);
+        if (!ctx)
+            return null;
+        return renderSurfaces(ctx);
+    };
+}

package/lib/{components/chat/extensions → extensions}/ExtensionRegistry.d.ts

@@ -2,9 +2,9 @@
  * Extension registry for chat component.
  * Manages custom renderers and extension points.
  *
- * @module components/chat/extensions/ExtensionRegistry
+ * @module components/extensions/ExtensionRegistry
  */
-import type { ChatExtension, MessageRendererExtension, ActivityRendererExtension, ToolUIExtension, ProtocolEventExtension, PanelExtension } from '../types/extension';
+import type { ChatExtension, MessageRendererExtension, ActivityRendererExtension, ToolUIExtension, ProtocolEventExtension, PanelExtension } from '../types/extensions';
 /** Internal extension type for registry organization */
 export type InternalExtensionType = 'message-renderer' | 'activity-renderer' | 'tool-ui' | 'protocol-event' | 'panel';
 /**
@@ -63,4 +63,3 @@ export declare class ExtensionRegistry {
      */
     clear(): void;
 }
-export { createMessageRenderer, createActivityRenderer, } from '../types/extension';

package/lib/{components/chat/extensions → extensions}/ExtensionRegistry.js

@@ -124,5 +124,3 @@ export class ExtensionRegistry {
         }
     }
 }
-// Re-export the helper functions from types/extension
-export { createMessageRenderer, createActivityRenderer, } from '../types/extension';

package/lib/{components/chat/extensions → extensions}/MCPUIExtension.d.ts

@@ -2,10 +2,10 @@
  * MCP-UI extension for chat component.
  * Renders MCP UI protocol messages and resources.
  *
- * @module components/chat/extensions/MCPUIExtension
+ * @module components/extensions/MCPUIExtension
  */
 import React from 'react';
-import type { ActivityRendererExtension } from '../types/extension';
+import type { ActivityRendererExtension } from '../types/extensions';
 /**
  * MCP-UI resource types
  */

package/lib/{components/chat/extensions → extensions}/MCPUIExtension.js

@@ -7,7 +7,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * MCP-UI extension for chat component.
  * Renders MCP UI protocol messages and resources.
  *
- * @module components/chat/extensions/MCPUIExtension
+ * @module components/extensions/MCPUIExtension
  */
 import React from 'react';
 /**

package/lib/extensions/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Extension exports for chat component.
+ *
+ * @module components/extensions
+ */
+export { ExtensionRegistry } from './ExtensionRegistry';
+export type { InternalExtensionType } from './ExtensionRegistry';
+export { createA2UIRenderer, A2UIExtensionImpl, type A2UIMessage, } from './A2UIExtension';
+export { createMCPUIRenderer, MCPUIExtensionImpl, type MCPUIMessage, type MCPUIResource, } from './MCPUIExtension';

package/lib/{components/chat/extensions → extensions}/index.js

@@ -5,8 +5,8 @@
 /**
  * Extension exports for chat component.
  *
- * @module components/chat/extensions
+ * @module components/extensions
  */
-export { ExtensionRegistry, createMessageRenderer, createActivityRenderer, } from './ExtensionRegistry';
+export { ExtensionRegistry } from './ExtensionRegistry';
 export { createA2UIRenderer, A2UIExtensionImpl, } from './A2UIExtension';
 export { createMCPUIRenderer, MCPUIExtensionImpl, } from './MCPUIExtension';

package/lib/hooks/index.d.ts

@@ -9,22 +9,21 @@
  *
  * - `useChat` - Main chat hook for messages, streaming, and state
  * - `useFrontendTool`, `useBackendTool` - Tool registration hooks
- * - `useKeyboardShortcuts` - Keyboard shortcut handling
  *
  * ## Transport-Specific Hooks
  * These hooks provide direct protocol access without the chat component system.
  * Use these for custom implementations or when you need fine-grained control.
  *
- * - `useAGUI` - AG-UI protocol (Pydantic AI's native protocol)
+ * - `useAgUi` - AG-UI protocol (Pydantic AI's native protocol)
  * - `useA2A` - A2A protocol (Agent-to-Agent with JSON-RPC)
  * - `useAcp` - ACP protocol (Agent Client Protocol via WebSocket)
- * - `useVercelChat` - Vercel AI SDK chat protocol
+ * - `useVercelAI` - Vercel AI SDK chat protocol
  *
  * ## Datalayer-Specific Hooks
  * Hooks for Datalayer platform integration.
  *
- * - `useAIAgents` - Datalayer AI Agents REST API
- * - `useNotebookAIAgent` - Notebook-specific agent management
+ * - `useAgentsService` - Datalayer AI Agents REST API
+ * - `useNotebookAgents` - Notebook-specific agent management
  *
  * @module hooks
  */
@@ -38,14 +37,17 @@ export { useChat, type UseChatReturn } from './useChat';
  */
 export { useFrontendTool, useBackendTool, useRegisteredTools, useTool, usePendingToolCalls, ActionRegistrar, type UseFrontendToolFn, } from './useTools';
 /**
- * Keyboard shortcut hooks for chat UI.
+ * ChatBase infrastructure hooks.
  */
-export { useKeyboardShortcuts, useChatKeyboardShortcuts, getShortcutDisplay, type KeyboardShortcut, type UseKeyboardShortcutsOptions, } from './useKeyboardShortcuts';
+export { useConfig } from './useConfig';
+export { useSkills } from './useSkills';
+export { useContextSnapshot } from './useContextSnapshot';
+export { useSandbox } from './useSandbox';
 /**
  * AG-UI protocol hook - Pydantic AI's native protocol.
  * Use for direct AG-UI communication without the chat component system.
  */
-export { useAGUI } from './useAGUI';
+export { useAgUi } from './useAgUi';
 /**
  * A2A protocol hook - Agent-to-Agent with JSON-RPC 2.0.
  * Use for direct A2A communication without the chat component system.
@@ -60,9 +62,32 @@ export * from './useAcp';
  * Vercel AI SDK chat hook - HTTP/SSE streaming.
  * Use for direct Vercel AI communication without the chat component system.
  */
-export { useVercelChat } from './useVercelChat';
+export { useVercelAI } from './useVercelAI';
 /**
- * Datalayer AI Agents REST API hook.
+ * Unified hook for managing agents — both ephemeral and durable.
  */
-export * from './useAgents';
-export * from './useNotebookAIAgent';
+export { useAgents } from './useAgents';
+/**
+ * Runtime query and mutation hooks.
+ */
+export { useAgentsRuntimes, useAgentRuntimes, useAgentRuntimeByPodName, useCreateAgentRuntime, useDeleteAgentRuntime, useRefreshAgentRuntimes, agentQueryKeys, AGENT_QUERY_OPTIONS, useAgentLifecycleStore, getAgentLifecycleKey, } from './useAgents';
+/**
+ * Agent catalog store, AI Agents REST API, and registry hooks.
+ */
+export { useAgentCatalogStore, type AgentCatalogStoreState, } from './useAgentsCatalog';
+/**
+ * Agent registry hook.
+ */
+export { useAgentRegistry } from './useAgentsRegistry';
+/**
+ * Agents Service REST API (deprecated).
+ */
+export { useAgentsService, useNotebookAgents } from './useAgentsService';
+/**
+ * Focused hooks split by responsibility.
+ */
+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 { useOtelTotalTokens, fetchOtelTotalTokens, fetchOtelMetricTotal, fetchOtelMetricRows, toMetricValue, } from './useMonitoring';

package/lib/hooks/index.js

@@ -13,22 +13,21 @@
  *
  * - `useChat` - Main chat hook for messages, streaming, and state
  * - `useFrontendTool`, `useBackendTool` - Tool registration hooks
- * - `useKeyboardShortcuts` - Keyboard shortcut handling
  *
  * ## Transport-Specific Hooks
  * These hooks provide direct protocol access without the chat component system.
  * Use these for custom implementations or when you need fine-grained control.
  *
- * - `useAGUI` - AG-UI protocol (Pydantic AI's native protocol)
+ * - `useAgUi` - AG-UI protocol (Pydantic AI's native protocol)
  * - `useA2A` - A2A protocol (Agent-to-Agent with JSON-RPC)
  * - `useAcp` - ACP protocol (Agent Client Protocol via WebSocket)
- * - `useVercelChat` - Vercel AI SDK chat protocol
+ * - `useVercelAI` - Vercel AI SDK chat protocol
  *
  * ## Datalayer-Specific Hooks
  * Hooks for Datalayer platform integration.
  *
- * - `useAIAgents` - Datalayer AI Agents REST API
- * - `useNotebookAIAgent` - Notebook-specific agent management
+ * - `useAgentsService` - Datalayer AI Agents REST API
+ * - `useNotebookAgents` - Notebook-specific agent management
  *
  * @module hooks
  */
@@ -45,9 +44,12 @@ export { useChat } from './useChat';
  */
 export { useFrontendTool, useBackendTool, useRegisteredTools, useTool, usePendingToolCalls, ActionRegistrar, } from './useTools';
 /**
- * Keyboard shortcut hooks for chat UI.
+ * ChatBase infrastructure hooks.
  */
-export { useKeyboardShortcuts, useChatKeyboardShortcuts, getShortcutDisplay, } from './useKeyboardShortcuts';
+export { useConfig } from './useConfig';
+export { useSkills } from './useSkills';
+export { useContextSnapshot } from './useContextSnapshot';
+export { useSandbox } from './useSandbox';
 // =============================================================================
 // Transport-Specific Hooks (Direct Protocol Access)
 // =============================================================================
@@ -55,7 +57,7 @@ export { useKeyboardShortcuts, useChatKeyboardShortcuts, getShortcutDisplay, } f
  * AG-UI protocol hook - Pydantic AI's native protocol.
  * Use for direct AG-UI communication without the chat component system.
  */
-export { useAGUI } from './useAGUI';
+export { useAgUi } from './useAgUi';
 /**
  * A2A protocol hook - Agent-to-Agent with JSON-RPC 2.0.
  * Use for direct A2A communication without the chat component system.
@@ -70,12 +72,35 @@ export * from './useAcp';
  * Vercel AI SDK chat hook - HTTP/SSE streaming.
  * Use for direct Vercel AI communication without the chat component system.
  */
-export { useVercelChat } from './useVercelChat';
+export { useVercelAI } from './useVercelAI';
 // =============================================================================
 // Datalayer Platform Hooks
 // =============================================================================
 /**
- * Datalayer AI Agents REST API hook.
+ * Unified hook for managing agents — both ephemeral and durable.
  */
-export * from './useAgents';
-export * from './useNotebookAIAgent';
+export { useAgents } from './useAgents';
+/**
+ * Runtime query and mutation hooks.
+ */
+export { useAgentsRuntimes, useAgentRuntimes, useAgentRuntimeByPodName, useCreateAgentRuntime, useDeleteAgentRuntime, useRefreshAgentRuntimes, agentQueryKeys, AGENT_QUERY_OPTIONS, useAgentLifecycleStore, getAgentLifecycleKey, } from './useAgents';
+/**
+ * Agent catalog store, AI Agents REST API, and registry hooks.
+ */
+export { useAgentCatalogStore, } from './useAgentsCatalog';
+/**
+ * Agent registry hook.
+ */
+export { useAgentRegistry } from './useAgentsRegistry';
+/**
+ * Agents Service REST API (deprecated).
+ */
+export { useAgentsService, useNotebookAgents } from './useAgentsService';
+/**
+ * Focused hooks split by responsibility.
+ */
+export { useCheckpoints, useCheckpointsQuery, useRefreshCheckpoints, useDeletePausedAgentRuntime, useResumePausedAgentRuntime, usePauseAgent, useResumeAgent, useCheckpointAgent, useTerminateAgent, useAgentLifecycle, } 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, } from './useAIAgentsWebSocket';
+export { useOtelTotalTokens, fetchOtelTotalTokens, fetchOtelMetricTotal, fetchOtelMetricRows, toMetricValue, } from './useMonitoring';

package/lib/hooks/useAIAgentsWebSocket.d.ts

@@ -0,0 +1,29 @@
+/** A message pushed by the server. */
+interface WSMessage {
+    channel: string;
+    event: string;
+    data: Record<string, unknown>;
+}
+/** Options for the WebSocket hook. */
+export interface UseAIAgentsWebSocketOptions {
+    /** Additional channels to subscribe to beyond the auto-subscribed user channel. */
+    channels?: string[];
+    /** Called for every incoming message (optional). */
+    onMessage?: (msg: WSMessage) => void;
+}
+/**
+ * Connect to the AI Agents generic WebSocket.
+ *
+ * The hook automatically:
+ * - subscribes to the user's own channel (done server-side)
+ * - subscribes to any extra channels passed via `options.channels`
+ * - invalidates the matching React Query keys when events arrive
+ * - reconnects on unexpected disconnects
+ *
+ * @example
+ * ```tsx
+ * useAIAgentsWebSocket({ channels: [`agent:${agentId}`] });
+ * ```
+ */
+export declare function useAIAgentsWebSocket(options?: UseAIAgentsWebSocketOptions): void;
+export {};

package/lib/hooks/useAIAgentsWebSocket.js

@@ -0,0 +1,136 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Generic WebSocket hook for the AI Agents service.
+ *
+ * Connects to the single `/ws` endpoint and subscribes to channels.
+ * When the server pushes a message on a subscribed channel the
+ * corresponding React Query cache is automatically invalidated so
+ * the UI refreshes with fresh data from the server.
+ *
+ * @module hooks/useAIAgentsWebSocket
+ */
+import { useEffect, useRef } 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';
+// ─── Auth / URL helpers ──────────────────────────────────────────────
+function useAuthToken() {
+    const token = useIAMStore((s) => s.token);
+    return token ?? '';
+}
+function useBaseUrl() {
+    const config = useCoreStore((s) => s.configuration);
+    return config?.aiagentsRunUrl ?? DEFAULT_SERVICE_URLS.AI_AGENTS;
+}
+// ─── Hook ────────────────────────────────────────────────────────────
+const RECONNECT_DELAY_MS = 3_000;
+/**
+ * Connect to the AI Agents generic WebSocket.
+ *
+ * The hook automatically:
+ * - subscribes to the user's own channel (done server-side)
+ * - subscribes to any extra channels passed via `options.channels`
+ * - invalidates the matching React Query keys when events arrive
+ * - reconnects on unexpected disconnects
+ *
+ * @example
+ * ```tsx
+ * useAIAgentsWebSocket({ channels: [`agent:${agentId}`] });
+ * ```
+ */
+export function useAIAgentsWebSocket(options) {
+    const token = useAuthToken();
+    const baseUrl = useBaseUrl();
+    const queryClient = useQueryClient();
+    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 onMessageRef = useRef(options?.onMessage);
+    onMessageRef.current = options?.onMessage;
+    useEffect(() => {
+        if (!token)
+            return;
+        let disposed = false;
+        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 ws = new WebSocket(wsUrl);
+            wsRef.current = ws;
+            ws.onopen = () => {
+                // Subscribe to extra channels.
+                const channels = channelsRef.current;
+                if (channels.length > 0) {
+                    ws.send(JSON.stringify({ subscribe: { channels } }));
+                }
+            };
+            ws.onmessage = ev => {
+                let msg;
+                try {
+                    msg = JSON.parse(ev.data);
+                }
+                catch {
+                    return;
+                }
+                // Fire optional callback.
+                onMessageRef.current?.(msg);
+                // Invalidate React Query caches based on the event type.
+                const { event } = msg;
+                if (event.startsWith('event_')) {
+                    queryClient.invalidateQueries({ queryKey: ['agent-events'] });
+                }
+                if (event.startsWith('tool_approval_')) {
+                    queryClient.invalidateQueries({ queryKey: ['tool-approvals'] });
+                }
+                if (event.startsWith('notification_')) {
+                    queryClient.invalidateQueries({ queryKey: ['agent-notifications'] });
+                }
+            };
+            ws.onclose = () => {
+                wsRef.current = null;
+                if (!disposed) {
+                    reconnectTimer.current = setTimeout(connect, RECONNECT_DELAY_MS);
+                }
+            };
+            ws.onerror = () => {
+                // onclose will fire after onerror; reconnect happens there.
+                ws.close();
+            };
+        }
+        connect();
+        return () => {
+            disposed = true;
+            if (reconnectTimer.current) {
+                clearTimeout(reconnectTimer.current);
+            }
+            wsRef.current?.close();
+            wsRef.current = null;
+        };
+    }, [token, baseUrl, queryClient]);
+    // When the channel list changes, send subscribe/unsubscribe diffs.
+    const prevChannelsRef = useRef([]);
+    useEffect(() => {
+        const ws = wsRef.current;
+        if (!ws || ws.readyState !== WebSocket.OPEN)
+            return;
+        const prev = new Set(prevChannelsRef.current);
+        const next = new Set(channelsRef.current);
+        const toSubscribe = channelsRef.current.filter(ch => !prev.has(ch));
+        const toUnsubscribe = prevChannelsRef.current.filter(ch => !next.has(ch));
+        if (toSubscribe.length > 0) {
+            ws.send(JSON.stringify({ subscribe: { channels: toSubscribe } }));
+        }
+        if (toUnsubscribe.length > 0) {
+            ws.send(JSON.stringify({ unsubscribe: { channels: toUnsubscribe } }));
+        }
+        prevChannelsRef.current = [...channelsRef.current];
+    }, [options?.channels]);
+}

package/lib/hooks/{useAGUI.d.ts → useAgUi.d.ts}

@@ -44,7 +44,7 @@ export interface UseAGUIOptions {
  *
  * Example:
  * ```tsx
- * const { messages, sendMessage, isConnected } = useAGUI({
+ * const { messages, sendMessage, isConnected } = useAgUi({
  *   baseUrl: 'http://localhost:8765',
  *   agentId: 'demo-agent',
  * });
@@ -52,7 +52,7 @@ export interface UseAGUIOptions {
  * await sendMessage('Hello!');
  * ```
  */
-export declare function useAGUI(options?: UseAGUIOptions): {
+export declare function useAgUi(options?: UseAGUIOptions): {
     messages: Message[];
     isConnected: boolean;
     isSending: boolean;

package/lib/hooks/{useAGUI.js → useAgUi.js}

@@ -18,7 +18,7 @@ import { useCallback, useEffect, useState } from 'react';
  *
  * Example:
  * ```tsx
- * const { messages, sendMessage, isConnected } = useAGUI({
+ * const { messages, sendMessage, isConnected } = useAgUi({
  *   baseUrl: 'http://localhost:8765',
  *   agentId: 'demo-agent',
  * });
@@ -26,7 +26,7 @@ import { useCallback, useEffect, useState } from 'react';
  * await sendMessage('Hello!');
  * ```
  */
-export function useAGUI(options = {}) {
+export function useAgUi(options = {}) {
     const { baseUrl = 'http://localhost:8765', agentId = 'demo-agent', autoConnect = true, onMessageSent, onMessageReceived, onError, } = options;
     const [messages, setMessages] = useState([]);
     const [isConnected, setIsConnected] = useState(false);