@datalayer/agent-runtimes 0.0.2

package/lib/hooks/useNotebookAIAgent.js

@@ -0,0 +1,56 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useEffect } from 'react';
+import { useAIAgentStore } from '../state';
+import { useAIAgents } from './useAgents';
+/**
+ * Get the document AI Agent if any.
+ *
+ * It handles checking the AI Agent is alive so it should only be use once per document.
+ */
+export function useNotebookAIAgent(notebookId) {
+    const { getAIAgent } = useAIAgents();
+    const { aiAgents, addAIAgent, deleteAIAgent, updateAIAgent } = useAIAgentStore();
+    // Check AI Agent is alive.
+    useEffect(() => {
+        let abortController;
+        const refreshAIAgent = async () => {
+            abortController = new AbortController();
+            try {
+                const response = await getAIAgent(notebookId, {
+                    signal: abortController.signal,
+                });
+                if (!response.success) {
+                    deleteAIAgent(notebookId);
+                    return;
+                }
+                const currentAgent = aiAgents.find(agent => agent.documentId === notebookId);
+                const runtimeId = response.agent.runtime?.id;
+                if (currentAgent) {
+                    if (currentAgent.runtimeId !== runtimeId) {
+                        updateAIAgent(notebookId, runtimeId);
+                    }
+                }
+                else {
+                    addAIAgent({
+                        documentId: notebookId,
+                        runtimeId,
+                    });
+                }
+            }
+            catch (r) {
+                deleteAIAgent(notebookId);
+            }
+        };
+        const refreshInterval = setInterval(refreshAIAgent, 60_000);
+        return () => {
+            abortController?.abort('Component unmounted');
+            clearInterval(refreshInterval);
+        };
+    }, [aiAgents, notebookId]);
+    const aiAgent = aiAgents.find(aiAgent => aiAgent.documentId === notebookId);
+    return aiAgent;
+}
+export default useNotebookAIAgent;

package/lib/hooks/useToast.d.ts

@@ -0,0 +1,44 @@
+import * as React from 'react';
+import type { ToastActionElement, ToastProps } from '@/components/ui/toast';
+type ToasterToast = ToastProps & {
+    id: string;
+    title?: React.ReactNode;
+    description?: React.ReactNode;
+    action?: ToastActionElement;
+};
+declare const actionTypes: {
+    readonly ADD_TOAST: "ADD_TOAST";
+    readonly UPDATE_TOAST: "UPDATE_TOAST";
+    readonly DISMISS_TOAST: "DISMISS_TOAST";
+    readonly REMOVE_TOAST: "REMOVE_TOAST";
+};
+type ActionType = typeof actionTypes;
+type Action = {
+    type: ActionType['ADD_TOAST'];
+    toast: ToasterToast;
+} | {
+    type: ActionType['UPDATE_TOAST'];
+    toast: Partial<ToasterToast>;
+} | {
+    type: ActionType['DISMISS_TOAST'];
+    toastId?: ToasterToast['id'];
+} | {
+    type: ActionType['REMOVE_TOAST'];
+    toastId?: ToasterToast['id'];
+};
+interface State {
+    toasts: ToasterToast[];
+}
+export declare const reducer: (state: State, action: Action) => State;
+type Toast = Omit<ToasterToast, 'id'>;
+declare function toast({ ...props }: Toast): {
+    id: string;
+    dismiss: () => void;
+    update: (props: ToasterToast) => void;
+};
+declare function useToast(): {
+    toast: typeof toast;
+    dismiss: (toastId?: string) => void;
+    toasts: ToasterToast[];
+};
+export { useToast, toast };

package/lib/hooks/useToast.js

@@ -0,0 +1,128 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import * as React from 'react';
+const TOAST_LIMIT = 1;
+const TOAST_REMOVE_DELAY = 1000000;
+const actionTypes = {
+    ADD_TOAST: 'ADD_TOAST',
+    UPDATE_TOAST: 'UPDATE_TOAST',
+    DISMISS_TOAST: 'DISMISS_TOAST',
+    REMOVE_TOAST: 'REMOVE_TOAST',
+};
+let count = 0;
+function genId() {
+    count = (count + 1) % Number.MAX_SAFE_INTEGER;
+    return count.toString();
+}
+const toastTimeouts = new Map();
+const addToRemoveQueue = (toastId) => {
+    if (toastTimeouts.has(toastId)) {
+        return;
+    }
+    const timeout = setTimeout(() => {
+        toastTimeouts.delete(toastId);
+        dispatch({
+            type: 'REMOVE_TOAST',
+            toastId: toastId,
+        });
+    }, TOAST_REMOVE_DELAY);
+    toastTimeouts.set(toastId, timeout);
+};
+export const reducer = (state, action) => {
+    switch (action.type) {
+        case 'ADD_TOAST':
+            return {
+                ...state,
+                toasts: [action.toast, ...state.toasts].slice(0, TOAST_LIMIT),
+            };
+        case 'UPDATE_TOAST':
+            return {
+                ...state,
+                toasts: state.toasts.map(t => t.id === action.toast.id ? { ...t, ...action.toast } : t),
+            };
+        case 'DISMISS_TOAST': {
+            const { toastId } = action;
+            if (toastId) {
+                addToRemoveQueue(toastId);
+            }
+            else {
+                state.toasts.forEach(toast => {
+                    addToRemoveQueue(toast.id);
+                });
+            }
+            return {
+                ...state,
+                toasts: state.toasts.map(t => t.id === toastId || toastId === undefined
+                    ? {
+                        ...t,
+                        open: false,
+                    }
+                    : t),
+            };
+        }
+        case 'REMOVE_TOAST':
+            if (action.toastId === undefined) {
+                return {
+                    ...state,
+                    toasts: [],
+                };
+            }
+            return {
+                ...state,
+                toasts: state.toasts.filter(t => t.id !== action.toastId),
+            };
+    }
+};
+const listeners = [];
+let memoryState = { toasts: [] };
+function dispatch(action) {
+    memoryState = reducer(memoryState, action);
+    listeners.forEach(listener => {
+        listener(memoryState);
+    });
+}
+function toast({ ...props }) {
+    const id = genId();
+    const update = (props) => dispatch({
+        type: 'UPDATE_TOAST',
+        toast: { ...props, id },
+    });
+    const dismiss = () => dispatch({ type: 'DISMISS_TOAST', toastId: id });
+    dispatch({
+        type: 'ADD_TOAST',
+        toast: {
+            ...props,
+            id,
+            open: true,
+            onOpenChange: open => {
+                if (!open)
+                    dismiss();
+            },
+        },
+    });
+    return {
+        id: id,
+        dismiss,
+        update,
+    };
+}
+function useToast() {
+    const [state, setState] = React.useState(memoryState);
+    React.useEffect(() => {
+        listeners.push(setState);
+        return () => {
+            const index = listeners.indexOf(setState);
+            if (index > -1) {
+                listeners.splice(index, 1);
+            }
+        };
+    }, [state]);
+    return {
+        ...state,
+        toast,
+        dismiss: (toastId) => dispatch({ type: 'DISMISS_TOAST', toastId }),
+    };
+}
+export { useToast, toast };

package/lib/hooks/useTools.d.ts

@@ -0,0 +1,107 @@
+import { type ToolCallState } from '../components/chat/store';
+import type { ToolParameter, ToolRenderProps, ToolRenderAndWaitProps, ToolLocation } from '../components/chat/types/tool';
+/**
+ * Type signature for useFrontendTool hook
+ * Compatible with CopilotKit's interface
+ */
+export type UseFrontendToolFn = <TArgs = Record<string, unknown>, TResult = unknown>(tool: {
+    name: string;
+    description: string;
+    parameters: ToolParameter[];
+    handler?: (args: TArgs) => Promise<TResult>;
+    render?: (props: ToolRenderProps<TArgs, TResult>) => React.ReactNode;
+    renderAndWaitForResponse?: (props: ToolRenderAndWaitProps<TArgs, TResult>) => React.ReactNode;
+    location?: ToolLocation;
+}, dependencies?: unknown[]) => void;
+/**
+ * Hook to register a frontend tool
+ * Compatible with CopilotKit's useFrontendTool
+ *
+ * @example
+ * ```tsx
+ * useFrontendTool({
+ *   name: 'insert_heading',
+ *   description: 'Insert a heading into the document',
+ *   parameters: [
+ *     { name: 'text', type: 'string', description: 'Heading text', required: true },
+ *     { name: 'level', type: 'number', description: 'Heading level 1-6' }
+ *   ],
+ *   handler: async ({ text, level }) => {
+ *     // Execute the tool
+ *     return `Inserted heading: ${text}`;
+ *   }
+ * }, []);
+ * ```
+ */
+export declare function useFrontendTool<TArgs = Record<string, unknown>, TResult = unknown>(tool: {
+    name: string;
+    description: string;
+    parameters: ToolParameter[];
+    handler?: (args: TArgs) => Promise<TResult>;
+    render?: (props: ToolRenderProps<TArgs, TResult>) => React.ReactNode;
+    renderAndWaitForResponse?: (props: ToolRenderAndWaitProps<TArgs, TResult>) => React.ReactNode;
+    location?: ToolLocation;
+}, dependencies?: unknown[]): void;
+/**
+ * Hook to register a backend tool
+ * Backend tools are executed server-side via the inference provider
+ *
+ * @example
+ * ```tsx
+ * useBackendTool({
+ *   name: 'search_database',
+ *   description: 'Search the database for records',
+ *   parameters: [
+ *     { name: 'query', type: 'string', required: true }
+ *   ],
+ *   render: ({ status, result }) => (
+ *     <SearchResults status={status} results={result} />
+ *   )
+ * }, []);
+ * ```
+ */
+export declare function useBackendTool(tool: {
+    name: string;
+    description: string;
+    parameters: ToolParameter[];
+    render?: (props: ToolRenderProps) => React.ReactNode;
+}, dependencies?: unknown[]): void;
+/**
+ * Hook to get registered tools
+ */
+export declare function useRegisteredTools(): import("..").ToolDefinition[];
+/**
+ * Hook to get a specific tool by name
+ */
+export declare function useTool(name: string): import("..").ToolRegistryEntry | undefined;
+/**
+ * Hook to get pending tool calls
+ */
+export declare function usePendingToolCalls(): ToolCallState[];
+/**
+ * Component to register a single action/tool
+ * Used with useFrontendTool for compatibility with existing patterns
+ *
+ * @example
+ * ```tsx
+ * {actions.map((action, i) => (
+ *   <ActionRegistrar
+ *     key={action.name || i}
+ *     action={action}
+ *     useFrontendTool={useFrontendTool}
+ *   />
+ * ))}
+ * ```
+ */
+export declare function ActionRegistrar<TArgs = Record<string, unknown>, TResult = unknown>({ action, useFrontendTool: useToolFn, }: {
+    action: {
+        name: string;
+        description: string;
+        parameters: ToolParameter[];
+        handler?: (args: TArgs) => Promise<TResult>;
+        render?: (props: ToolRenderProps<TArgs, TResult>) => React.ReactNode;
+        renderAndWaitForResponse?: (props: ToolRenderAndWaitProps<TArgs, TResult>) => React.ReactNode;
+        location?: ToolLocation;
+    };
+    useFrontendTool: UseFrontendToolFn;
+}): null;

package/lib/hooks/useTools.js

@@ -0,0 +1,130 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * React hooks for chat tool registration and usage.
+ * Compatible with CopilotKit's useFrontendTool pattern.
+ *
+ * @module components/chat/hooks/useTools
+ */
+import { useEffect, useMemo } from 'react';
+import { useChatStore } from '../components/chat/store';
+/**
+ * Hook to register a frontend tool
+ * Compatible with CopilotKit's useFrontendTool
+ *
+ * @example
+ * ```tsx
+ * useFrontendTool({
+ *   name: 'insert_heading',
+ *   description: 'Insert a heading into the document',
+ *   parameters: [
+ *     { name: 'text', type: 'string', description: 'Heading text', required: true },
+ *     { name: 'level', type: 'number', description: 'Heading level 1-6' }
+ *   ],
+ *   handler: async ({ text, level }) => {
+ *     // Execute the tool
+ *     return `Inserted heading: ${text}`;
+ *   }
+ * }, []);
+ * ```
+ */
+export function useFrontendTool(tool, dependencies = []) {
+    const registerTool = useChatStore(state => state.registerTool);
+    const unregisterTool = useChatStore(state => state.unregisterTool);
+    // Create stable tool definition
+    const toolDefinition = useMemo(() => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        location: tool.location || 'frontend',
+        handler: tool.handler,
+        render: tool.render,
+        renderAndWaitForResponse: tool.renderAndWaitForResponse,
+    }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [tool.name, ...dependencies]);
+    // Register on mount, unregister on unmount
+    useEffect(() => {
+        registerTool(toolDefinition);
+        return () => {
+            unregisterTool(tool.name);
+        };
+    }, [toolDefinition, registerTool, unregisterTool, tool.name]);
+}
+/**
+ * Hook to register a backend tool
+ * Backend tools are executed server-side via the inference provider
+ *
+ * @example
+ * ```tsx
+ * useBackendTool({
+ *   name: 'search_database',
+ *   description: 'Search the database for records',
+ *   parameters: [
+ *     { name: 'query', type: 'string', required: true }
+ *   ],
+ *   render: ({ status, result }) => (
+ *     <SearchResults status={status} results={result} />
+ *   )
+ * }, []);
+ * ```
+ */
+export function useBackendTool(tool, dependencies = []) {
+    const registerTool = useChatStore(state => state.registerTool);
+    const unregisterTool = useChatStore(state => state.unregisterTool);
+    const toolDefinition = useMemo(() => ({
+        name: tool.name,
+        description: tool.description,
+        parameters: tool.parameters,
+        location: 'backend',
+        render: tool.render,
+    }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [tool.name, ...dependencies]);
+    useEffect(() => {
+        registerTool(toolDefinition);
+        return () => {
+            unregisterTool(tool.name);
+        };
+    }, [toolDefinition, registerTool, unregisterTool, tool.name]);
+}
+/**
+ * Hook to get registered tools
+ */
+export function useRegisteredTools() {
+    return useChatStore(state => state.getTools());
+}
+/**
+ * Hook to get a specific tool by name
+ */
+export function useTool(name) {
+    const getTool = useChatStore(state => state.getTool);
+    return getTool(name);
+}
+/**
+ * Hook to get pending tool calls
+ */
+export function usePendingToolCalls() {
+    return useChatStore(state => state.getPendingToolCalls());
+}
+/**
+ * Component to register a single action/tool
+ * Used with useFrontendTool for compatibility with existing patterns
+ *
+ * @example
+ * ```tsx
+ * {actions.map((action, i) => (
+ *   <ActionRegistrar
+ *     key={action.name || i}
+ *     action={action}
+ *     useFrontendTool={useFrontendTool}
+ *   />
+ * ))}
+ * ```
+ */
+export function ActionRegistrar({ action, useFrontendTool: useToolFn, }) {
+    useToolFn(action, [action]);
+    return null;
+}

package/lib/hooks/useVercelChat.d.ts

@@ -0,0 +1,45 @@
+import { type UseChatHelpers, type UIMessage } from '@ai-sdk/react';
+export interface Message {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+}
+export interface UseVercelChatOptions {
+    /**
+     * Base URL for the Vercel AI endpoint (e.g., 'http://localhost:8000')
+     */
+    baseUrl?: string;
+    /**
+     * Agent ID to use (default: 'demo-agent')
+     */
+    agentId?: string;
+    /**
+     * Callback when a message is sent
+     */
+    onMessageSent?: (content: string) => void;
+    /**
+     * Callback when a message is received
+     */
+    onMessageReceived?: (message: Message) => void;
+}
+/**
+ * Hook to manage chat state with Vercel AI protocol.
+ *
+ * This hook wraps the Vercel AI's useChat to connect to the
+ * agent-runtimes Vercel AI endpoint at /api/v1/vercel-ai/chat.
+ *
+ * Features:
+ * - Streaming responses via SSE
+ * - Automatic message management
+ * - Error handling
+ * - Loading states
+ *
+ * Example:
+ * ```tsx
+ * const { messages, sendMessage, isLoading } = useVercelChat({
+ *   baseUrl: 'http://localhost:8888',
+ *   agentId: 'demo-agent',
+ * });
+ * ```
+ */
+export declare function useVercelChat(options?: UseVercelChatOptions): UseChatHelpers<UIMessage>;

package/lib/hooks/useVercelChat.js

@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { useCallback, useMemo } from 'react';
+import { useChat } from '@ai-sdk/react';
+import { DefaultChatTransport } from 'ai';
+/**
+ * Hook to manage chat state with Vercel AI protocol.
+ *
+ * This hook wraps the Vercel AI's useChat to connect to the
+ * agent-runtimes Vercel AI endpoint at /api/v1/vercel-ai/chat.
+ *
+ * Features:
+ * - Streaming responses via SSE
+ * - Automatic message management
+ * - Error handling
+ * - Loading states
+ *
+ * Example:
+ * ```tsx
+ * const { messages, sendMessage, isLoading } = useVercelChat({
+ *   baseUrl: 'http://localhost:8888',
+ *   agentId: 'demo-agent',
+ * });
+ * ```
+ */
+export function useVercelChat(options = {}) {
+    const { baseUrl = 'http://localhost:8888', agentId = 'demo-agent', onMessageSent, } = options;
+    // Construct the chat endpoint URL
+    const apiEndpoint = `${baseUrl}/api/v1/vercel-ai/chat`;
+    const chatResult = useChat({
+        id: `vercel-chat-${agentId}`,
+        transport: new DefaultChatTransport({
+            api: apiEndpoint,
+            body: {
+                agent_id: agentId,
+            },
+        }),
+    });
+    const { sendMessage, setMessages } = chatResult;
+    // Wrap original sendMessage to trigger callbacks
+    const originalSendMessage = sendMessage;
+    const wrappedSendMessage = useCallback(async (message, options) => {
+        if (typeof message === 'string' && message.trim()) {
+            onMessageSent?.(message);
+        }
+        else if (message?.parts?.[0]?.text) {
+            onMessageSent?.(message.parts[0].text);
+        }
+        return originalSendMessage(message, options);
+    }, [originalSendMessage, onMessageSent]);
+    // Clear chat history
+    const clearChat = useCallback(() => {
+        setMessages([]);
+    }, [setMessages]);
+    return useMemo(() => ({
+        ...chatResult,
+        sendMessage: wrappedSendMessage,
+        clearChat,
+    }), [chatResult, wrappedSendMessage, clearChat]);
+}

package/lib/index.css

@@ -0,0 +1,73 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+
+:root {
+  font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  color-scheme: light dark;
+  color: rgba(255, 255, 255, 0.87);
+  background-color: #242424;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+a {
+  font-weight: 500;
+  color: #646cff;
+  text-decoration: inherit;
+}
+a:hover {
+  color: #535bf2;
+}
+
+body {
+  margin: 0;
+  display: flex;
+  place-items: center;
+  min-width: 320px;
+  min-height: 100vh;
+}
+
+h1 {
+  font-size: 3.2em;
+  line-height: 1.1;
+}
+
+button {
+  border-radius: 8px;
+  border: 1px solid transparent;
+  padding: 0.6em 1.2em;
+  font-size: 1em;
+  font-weight: 500;
+  font-family: inherit;
+  background-color: #1a1a1a;
+  cursor: pointer;
+  transition: border-color 0.25s;
+}
+button:hover {
+  border-color: #646cff;
+}
+button:focus,
+button:focus-visible {
+  outline: 4px auto -webkit-focus-ring-color;
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    color: #213547;
+    background-color: #ffffff;
+  }
+  a:hover {
+    color: #747bff;
+  }
+  button {
+    background-color: #f9f9f9;
+  }
+}

package/lib/index.d.ts

@@ -0,0 +1 @@
+export * from './components';

package/lib/index.js

@@ -0,0 +1,5 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export * from './components';

package/lib/lexical/ChatInlinePlugin.d.ts

@@ -0,0 +1,21 @@
+import { type LexicalCommand } from 'lexical';
+import { type ChatInlineProtocolConfig } from '../components/chat/components/ChatInline';
+/**
+ * Lexical commands for selection preservation
+ */
+export declare const SAVE_SELECTION_COMMAND: LexicalCommand<null>;
+export declare const RESTORE_SELECTION_COMMAND: LexicalCommand<null>;
+/**
+ * Props for ChatInlinePlugin
+ */
+export interface ChatInlinePluginProps {
+    /** Protocol configuration for the AI agent */
+    protocol: ChatInlineProtocolConfig;
+    /** Optional: Container element for the portal (defaults to document.body) */
+    portalContainer?: HTMLElement;
+}
+/**
+ * ChatInlinePlugin - Floating AI toolbar for Lexical text selection.
+ */
+export declare function ChatInlinePlugin({ protocol, portalContainer, }: ChatInlinePluginProps): JSX.Element | null;
+export default ChatInlinePlugin;