@datalayer/agent-runtimes 1.0.4 → 1.0.5

package/lib/examples/utils/a2ui.d.ts

@@ -0,0 +1,18 @@
+import { type ReactComponentImplementation } from '@a2ui/react/v0_9';
+import { MessageProcessor, type A2uiClientAction, type A2uiMessage, type SurfaceModel } from '@a2ui/web_core/v0_9';
+export type A2uiProcessor = MessageProcessor<ReactComponentImplementation>;
+export type A2uiSurfaceModel = SurfaceModel<ReactComponentImplementation>;
+export declare function useA2uiProcessor(onAction?: (action: A2uiClientAction) => void): {
+    processor: MessageProcessor<ReactComponentImplementation>;
+    surfaces: A2uiSurfaceModel[];
+    processMessages: (messages: A2uiMessage[]) => void;
+    resetSurfaces: () => void;
+};
+export declare function createSceneMessages(args: {
+    surfaceId: string;
+    components: Array<Record<string, unknown>>;
+    value?: Record<string, unknown>;
+    path?: string;
+    theme?: Record<string, unknown>;
+    sendDataModel?: boolean;
+}): A2uiMessage[];

package/lib/examples/utils/a2ui.js

@@ -0,0 +1,69 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import { basicCatalog, } from '@a2ui/react/v0_9';
+import { MessageProcessor, } from '@a2ui/web_core/v0_9';
+export function useA2uiProcessor(onAction) {
+    const processor = useMemo(() => new MessageProcessor([basicCatalog], onAction), [onAction]);
+    const [surfaces, setSurfaces] = useState(() => Array.from(processor.model.surfacesMap.values()));
+    useEffect(() => {
+        const createdSub = processor.onSurfaceCreated(surface => {
+            setSurfaces(prev => [...prev, surface]);
+        });
+        const deletedSub = processor.onSurfaceDeleted(id => {
+            setSurfaces(prev => prev.filter(surface => surface.id !== id));
+        });
+        return () => {
+            createdSub.unsubscribe();
+            deletedSub.unsubscribe();
+        };
+    }, [processor]);
+    const processMessages = useCallback((messages) => {
+        processor.processMessages(messages);
+    }, [processor]);
+    const resetSurfaces = useCallback(() => {
+        Array.from(processor.model.surfacesMap.keys()).forEach(id => {
+            processor.model.deleteSurface(id);
+        });
+    }, [processor]);
+    return {
+        processor,
+        surfaces,
+        processMessages,
+        resetSurfaces,
+    };
+}
+export function createSceneMessages(args) {
+    const { surfaceId, components, value, path = '/', theme, sendDataModel = true, } = args;
+    const messages = [
+        {
+            version: 'v0.9',
+            createSurface: {
+                surfaceId,
+                catalogId: basicCatalog.id,
+                theme,
+                sendDataModel,
+            },
+        },
+        {
+            version: 'v0.9',
+            updateComponents: {
+                surfaceId,
+                components,
+            },
+        },
+    ];
+    if (value !== undefined) {
+        messages.push({
+            version: 'v0.9',
+            updateDataModel: {
+                surfaceId,
+                path,
+                value,
+            },
+        });
+    }
+    return messages;
+}

package/lib/examples/utils/a2uiMarkdownProvider.d.ts

@@ -0,0 +1,7 @@
+import React from 'react';
+/**
+ * Provides the A2UI v0.9 markdown renderer to all child `A2uiSurface`
+ * instances. Without it, `Text` components fall back to the raw markdown
+ * string (e.g. `## Title` instead of a rendered `<h2>`).
+ */
+export declare const A2uiMarkdownProvider: React.FC<React.PropsWithChildren>;

package/lib/examples/utils/a2uiMarkdownProvider.js

@@ -0,0 +1,9 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { MarkdownContext } from '@a2ui/react/v0_9';
+import { renderMarkdown } from '@a2ui/markdown-it';
+/**
+ * Provides the A2UI v0.9 markdown renderer to all child `A2uiSurface`
+ * instances. Without it, `Text` components fall back to the raw markdown
+ * string (e.g. `## Title` instead of a rendered `<h2>`).
+ */
+export const A2uiMarkdownProvider = ({ children, }) => (_jsx(MarkdownContext.Provider, { value: renderMarkdown, children: children }));

package/lib/examples/utils/agentId.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Build a unique agent ID by appending a random slug to a base name.
+ *
+ * The resulting id is cached in ``sessionStorage`` under a key derived from
+ * ``baseName``, so a browser refresh within the same tab reuses the same
+ * agent id.  This is required for server-side per-agent state (enabled
+ * tools, approved tools, approved skills, codemode status…) to survive a
+ * page reload — those maps are keyed by ``agent_id`` in
+ * ``agent_runtimes.streams.loop``.
+ *
+ * A fresh tab (or a ``sessionStorage.clear()``) produces a new id, which
+ * preserves the original "clean telemetry per run" guarantee.
+ *
+ * @example
+ *   uniqueAgentId('simple')           // → "simple-a3f7b2" (cached)
+ *   uniqueAgentId('codemode-demo')    // → "codemode-demo-k9x2m1" (cached)
+ */
+export declare function uniqueAgentId(baseName: string): string;

package/lib/examples/utils/agentId.js

@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Generate a short random alphanumeric slug (e.g. "a3f7b2").
+ * Used to make agent IDs unique per session so that each fresh
+ * example run starts with clean OTEL / telemetry data.
+ */
+function randomSlug(length = 6) {
+    const chars = 'abcdefghijklmnopqrstuvwxyz0123456789';
+    let slug = '';
+    const array = new Uint8Array(length);
+    crypto.getRandomValues(array);
+    for (let i = 0; i < length; i++) {
+        slug += chars[array[i] % chars.length];
+    }
+    return slug;
+}
+/**
+ * Build a unique agent ID by appending a random slug to a base name.
+ *
+ * The resulting id is cached in ``sessionStorage`` under a key derived from
+ * ``baseName``, so a browser refresh within the same tab reuses the same
+ * agent id.  This is required for server-side per-agent state (enabled
+ * tools, approved tools, approved skills, codemode status…) to survive a
+ * page reload — those maps are keyed by ``agent_id`` in
+ * ``agent_runtimes.streams.loop``.
+ *
+ * A fresh tab (or a ``sessionStorage.clear()``) produces a new id, which
+ * preserves the original "clean telemetry per run" guarantee.
+ *
+ * @example
+ *   uniqueAgentId('simple')           // → "simple-a3f7b2" (cached)
+ *   uniqueAgentId('codemode-demo')    // → "codemode-demo-k9x2m1" (cached)
+ */
+export function uniqueAgentId(baseName) {
+    const storageKey = `agent-runtimes:agentId:${baseName}`;
+    try {
+        if (typeof sessionStorage !== 'undefined') {
+            const cached = sessionStorage.getItem(storageKey);
+            if (cached && cached.startsWith(`${baseName}-`)) {
+                return cached;
+            }
+            const fresh = `${baseName}-${randomSlug()}`;
+            sessionStorage.setItem(storageKey, fresh);
+            return fresh;
+        }
+    }
+    catch {
+        // sessionStorage unavailable (e.g. SSR, privacy mode); fall through.
+    }
+    return `${baseName}-${randomSlug()}`;
+}

package/lib/examples/utils/agents/earthquake-detector.json

@@ -1,13 +1,13 @@
 {
-    "id": "earthquake-detector",
-    "title": "Earthquake Detector",
-    "description": "Real-time seismic activity monitoring and earthquake alert system.",
-    "image": "https://images.unsplash.com/photo-1589519160732-57fc498494f8?w=300&h=150&fit=crop",
-    "author": "Eric Charles",
-    "editTimestamp": "53 minutes ago",
-    "status": "paused",
-    "transport": "ag-ui",
-    "avatarUrl": "https://avatars.githubusercontent.com/atom",
-    "stars": 4,
-    "notifications": 0
+  "id": "earthquake-detector",
+  "title": "Earthquake Detector",
+  "description": "Real-time seismic activity monitoring and earthquake alert system.",
+  "image": "https://images.unsplash.com/photo-1589519160732-57fc498494f8?w=300&h=150&fit=crop",
+  "author": "Eric Charles",
+  "editTimestamp": "53 minutes ago",
+  "status": "paused",
+  "transport": "ag-ui",
+  "avatarUrl": "https://avatars.githubusercontent.com/atom",
+  "stars": 4,
+  "notifications": 0
 }

package/lib/examples/utils/agents/sales-forecaster.json

@@ -1,13 +1,13 @@
 {
-    "id": "sales-forecaster",
-    "title": "Sales Forecaster",
-    "description": "AI-powered sales prediction and revenue forecasting tool.",
-    "image": "https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=300&h=150&fit=crop",
-    "author": "Eric Charles",
-    "editTimestamp": "1 hour ago",
-    "status": "running",
-    "transport": "vercel-ai",
-    "avatarUrl": "https://avatars.githubusercontent.com/github",
-    "stars": 5,
-    "notifications": 2
+  "id": "sales-forecaster",
+  "title": "Sales Forecaster",
+  "description": "AI-powered sales prediction and revenue forecasting tool.",
+  "image": "https://images.unsplash.com/photo-1460925895917-afdab827c52f?w=300&h=150&fit=crop",
+  "author": "Eric Charles",
+  "editTimestamp": "1 hour ago",
+  "status": "running",
+  "transport": "vercel-ai",
+  "avatarUrl": "https://avatars.githubusercontent.com/github",
+  "stars": 5,
+  "notifications": 2
 }

package/lib/examples/utils/agents/social-post-generator.json

@@ -1,13 +1,13 @@
 {
-    "id": "social-post-generator",
-    "title": "Social Post Generator",
-    "description": "A powerful agent template for automated social media post generation.",
-    "image": "https://images.unsplash.com/photo-1611926653458-09294b3142bf?w=300&h=150&fit=crop",
-    "author": "Eric Charles",
-    "editTimestamp": "2 hours ago",
-    "status": "paused",
-    "transport": "ag-ui",
-    "avatarUrl": "https://avatars.githubusercontent.com/primer",
-    "stars": 3,
-    "notifications": 1
+  "id": "social-post-generator",
+  "title": "Social Post Generator",
+  "description": "A powerful agent template for automated social media post generation.",
+  "image": "https://images.unsplash.com/photo-1611926653458-09294b3142bf?w=300&h=150&fit=crop",
+  "author": "Eric Charles",
+  "editTimestamp": "2 hours ago",
+  "status": "paused",
+  "transport": "ag-ui",
+  "avatarUrl": "https://avatars.githubusercontent.com/primer",
+  "stars": 3,
+  "notifications": 1
 }

package/lib/examples/utils/agents/stock-market.json

@@ -1,13 +1,13 @@
 {
-    "id": "stocks-watcher",
-    "title": "Stocks Watcher",
-    "description": "Intelligent stock market analysis and portfolio tracking agent.",
-    "image": "https://images.unsplash.com/photo-1611974789855-9c2a0a7236a3?w=300&h=150&fit=crop",
-    "author": "Gonzalo Peña-Castellanos",
-    "editTimestamp": "3 days ago",
-    "status": "paused",
-    "transport": "acp",
-    "avatarUrl": "https://avatars.githubusercontent.com/desktop",
-    "stars": 1,
-    "notifications": 0
+  "id": "stocks-watcher",
+  "title": "Stocks Watcher",
+  "description": "Intelligent stock market analysis and portfolio tracking agent.",
+  "image": "https://images.unsplash.com/photo-1611974789855-9c2a0a7236a3?w=300&h=150&fit=crop",
+  "author": "Gonzalo Peña-Castellanos",
+  "editTimestamp": "3 days ago",
+  "status": "paused",
+  "transport": "acp",
+  "avatarUrl": "https://avatars.githubusercontent.com/desktop",
+  "stars": 1,
+  "notifications": 0
 }

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 {};