@datalayer/agent-runtimes 0.0.2

package/lib/hooks/useChat.d.ts

@@ -0,0 +1,62 @@
+import type { ChatMessage } from '../components/chat/types/message';
+import type { InferenceRequestOptions } from '../components/chat/types/inference';
+/**
+ * Return type for useChat hook
+ */
+export interface UseChatReturn {
+    /** All messages in the conversation */
+    messages: ChatMessage[];
+    /** Whether a request is in progress */
+    isLoading: boolean;
+    /** Whether currently streaming a response */
+    isStreaming: boolean;
+    /** Current error, if any */
+    error: Error | null;
+    /** Send a user message */
+    sendMessage: (content: string, options?: InferenceRequestOptions) => Promise<void>;
+    /** Append a message directly (useful for tool results) */
+    appendMessage: (message: ChatMessage) => void;
+    /** Update an existing message */
+    updateMessage: (messageId: string, updates: Partial<ChatMessage>) => void;
+    /** Delete a message */
+    deleteMessage: (messageId: string) => void;
+    /** Clear all messages */
+    clearMessages: () => void;
+    /** Stop current generation */
+    stopGeneration: () => void;
+    /** Reload/regenerate from a specific message */
+    reloadMessages: (fromMessageId: string) => Promise<void>;
+    /** Check if chat is available (provider configured) */
+    isAvailable: boolean;
+    /** Current suggestions */
+    suggestions: string[];
+    /** Set suggestions */
+    setSuggestions: (suggestions: string[]) => void;
+}
+/**
+ * Main hook for chat functionality
+ *
+ * @example
+ * ```tsx
+ * function ChatUI() {
+ *   const {
+ *     messages,
+ *     sendMessage,
+ *     isLoading,
+ *     isStreaming
+ *   } = useChat();
+ *
+ *   const handleSubmit = async (text: string) => {
+ *     await sendMessage(text);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       {messages.map(msg => <Message key={msg.id} message={msg} />)}
+ *       <Input onSubmit={handleSubmit} disabled={isLoading} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useChat(): UseChatReturn;

package/lib/hooks/useChat.js

@@ -0,0 +1,363 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Main chat hook for chat component.
+ * Provides chat state, message sending, and streaming functionality.
+ *
+ * @module components/chat/hooks/useChat
+ */
+import { useCallback, useMemo } from 'react';
+import { useChatStore } from '../components/chat/store';
+import { createUserMessage, createAssistantMessage, generateMessageId, } from '../components/chat/types/message';
+/**
+ * Main hook for chat functionality
+ *
+ * @example
+ * ```tsx
+ * function ChatUI() {
+ *   const {
+ *     messages,
+ *     sendMessage,
+ *     isLoading,
+ *     isStreaming
+ *   } = useChat();
+ *
+ *   const handleSubmit = async (text: string) => {
+ *     await sendMessage(text);
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       {messages.map(msg => <Message key={msg.id} message={msg} />)}
+ *       <Input onSubmit={handleSubmit} disabled={isLoading} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useChat() {
+    // Get instances from store (set via useChatStore.getState().setInferenceProvider())
+    const inferenceProvider = useChatStore(state => state.inferenceProvider);
+    const protocolAdapter = useChatStore(state => state.protocolAdapter);
+    const toolExecutor = useChatStore(state => state.toolExecutor);
+    // Get state from store
+    const messages = useChatStore(state => state.messages);
+    const isLoading = useChatStore(state => state.isLoading);
+    const isStreaming = useChatStore(state => state.isStreaming);
+    const error = useChatStore(state => state.error);
+    const suggestions = useChatStore(state => state.suggestions);
+    // Get actions from store
+    const addMessage = useChatStore(state => state.addMessage);
+    const updateMessage = useChatStore(state => state.updateMessage);
+    const deleteMessage = useChatStore(state => state.deleteMessage);
+    const clearMessages = useChatStore(state => state.clearMessages);
+    const setLoading = useChatStore(state => state.setLoading);
+    const setError = useChatStore(state => state.setError);
+    const startStreaming = useChatStore(state => state.startStreaming);
+    const appendToStream = useChatStore(state => state.appendToStream);
+    const stopStreaming = useChatStore(state => state.stopStreaming);
+    const setSuggestions = useChatStore(state => state.setSuggestions);
+    const getTools = useChatStore(state => state.getTools);
+    /**
+     * Send a user message and get AI response
+     */
+    const sendMessage = useCallback(async (content, options) => {
+        // Check if we have a way to send messages
+        if (!inferenceProvider && !protocolAdapter) {
+            setError(new Error('No inference provider or protocol adapter configured.'));
+            return;
+        }
+        // Create and add user message
+        const userMessage = createUserMessage(content);
+        addMessage(userMessage);
+        // Clear error and set loading
+        setError(null);
+        setLoading(true);
+        try {
+            // Get registered tools
+            const tools = getTools();
+            // Merge options
+            const requestOptions = {
+                ...options,
+                tools: tools.length > 0 ? tools : undefined,
+            };
+            // Get all messages for context
+            const allMessages = [...messages, userMessage];
+            // Create placeholder for assistant message
+            const assistantMessageId = generateMessageId();
+            const assistantMessage = createAssistantMessage('');
+            assistantMessage.id = assistantMessageId;
+            addMessage(assistantMessage);
+            // Stream the response
+            startStreaming(assistantMessageId);
+            // Use protocol adapter if available (for ag-ui, a2a, acp)
+            // Otherwise fall back to inference provider (for vercel-ai, OpenAI-compatible)
+            if (protocolAdapter) {
+                // Track pending tool calls for this run
+                const pendingToolCalls = new Map();
+                let currentAssistantContent = '';
+                // Subscribe to adapter events
+                const unsubscribe = protocolAdapter.subscribe(event => {
+                    switch (event.type) {
+                        case 'message':
+                            // AG-UI sends incremental messages with accumulating content
+                            if (event.message) {
+                                currentAssistantContent =
+                                    typeof event.message.content === 'string'
+                                        ? event.message.content
+                                        : '';
+                                // Update the assistant message with the current content
+                                updateMessage(assistantMessageId, {
+                                    content: currentAssistantContent,
+                                    toolCalls: event.message.toolCalls,
+                                });
+                            }
+                            break;
+                        case 'tool-call':
+                            // Track tool call for execution after stream completes
+                            if (event.toolCall) {
+                                console.log('[useChat] Tool call received:', event.toolCall.toolCallId, event.toolCall.toolName);
+                                pendingToolCalls.set(event.toolCall.toolCallId, {
+                                    toolName: event.toolCall.toolName,
+                                    args: event.toolCall.args,
+                                });
+                            }
+                            break;
+                        case 'error':
+                            if (event.error) {
+                                setError(event.error);
+                            }
+                            break;
+                    }
+                });
+                try {
+                    // Send the initial message
+                    await protocolAdapter.sendMessage(userMessage, {
+                        tools: requestOptions.tools,
+                        messages: allMessages,
+                    });
+                    // After stream completes, execute any pending tool calls
+                    if (pendingToolCalls.size > 0 && toolExecutor) {
+                        console.log('[useChat] Executing', pendingToolCalls.size, 'tool calls');
+                        // Execute tool calls and collect results
+                        const toolResults = [];
+                        for (const [toolCallId, { toolName, args }] of pendingToolCalls) {
+                            console.log('[useChat] Executing tool:', toolName, 'with args:', args);
+                            const result = await toolExecutor.execute({
+                                toolCallId,
+                                toolName,
+                                args,
+                            });
+                            console.log('[useChat] Tool result:', result);
+                            toolResults.push({
+                                toolCallId,
+                                toolName,
+                                result: result.result,
+                                isError: !result.success,
+                            });
+                        }
+                        // Build messages array with tool results for continuation
+                        // Include the assistant message with tool calls
+                        const assistantWithToolCalls = {
+                            id: assistantMessageId,
+                            role: 'assistant',
+                            content: currentAssistantContent,
+                            createdAt: new Date(),
+                            toolCalls: Array.from(pendingToolCalls.entries()).map(([toolCallId, { toolName, args }]) => ({
+                                type: 'tool-call',
+                                toolCallId,
+                                toolName,
+                                args,
+                                status: 'completed',
+                            })),
+                        };
+                        // Create tool result messages
+                        const toolResultMessages = toolResults.map(tr => ({
+                            id: generateMessageId(),
+                            role: 'tool',
+                            content: JSON.stringify(tr.result),
+                            createdAt: new Date(),
+                            metadata: {
+                                toolCallId: tr.toolCallId,
+                                toolName: tr.toolName,
+                                isError: tr.isError,
+                            },
+                        }));
+                        // Update stored messages
+                        updateMessage(assistantMessageId, assistantWithToolCalls);
+                        toolResultMessages.forEach(msg => addMessage(msg));
+                        // Create new assistant message for the continuation
+                        const continuationAssistantId = generateMessageId();
+                        const continuationMessage = createAssistantMessage('');
+                        continuationMessage.id = continuationAssistantId;
+                        addMessage(continuationMessage);
+                        startStreaming(continuationAssistantId);
+                        // Subscribe to continuation events
+                        const unsubscribeContinuation = protocolAdapter.subscribe(event => {
+                            if (event.type === 'message' && event.message) {
+                                const content = typeof event.message.content === 'string'
+                                    ? event.message.content
+                                    : '';
+                                updateMessage(continuationAssistantId, {
+                                    content,
+                                    toolCalls: event.message.toolCalls,
+                                });
+                            }
+                            else if (event.type === 'error' && event.error) {
+                                setError(event.error);
+                            }
+                        });
+                        try {
+                            // Build the full message history for continuation
+                            const continuationMessages = [
+                                ...allMessages,
+                                assistantWithToolCalls,
+                                ...toolResultMessages,
+                            ];
+                            // Send continuation request with tool results
+                            // AG-UI expects tool results as messages with role: "tool"
+                            await protocolAdapter.sendMessage(toolResultMessages[toolResultMessages.length - 1], {
+                                tools: requestOptions.tools,
+                                messages: continuationMessages,
+                            });
+                        }
+                        finally {
+                            unsubscribeContinuation();
+                        }
+                    }
+                }
+                finally {
+                    unsubscribe();
+                }
+            }
+            else if (inferenceProvider) {
+                const response = await inferenceProvider.streamMessage(allMessages, requestOptions, event => {
+                    switch (event.type) {
+                        case 'content-delta':
+                            if (event.delta?.delta.content) {
+                                appendToStream(assistantMessageId, event.delta.delta.content);
+                            }
+                            break;
+                        case 'tool-call-start':
+                            // Handle tool call UI update
+                            if (event.toolCall) {
+                                // Tool calls are handled by the tool executor
+                                console.log('[useChat] Tool call started:', event.toolCall);
+                            }
+                            break;
+                        case 'error':
+                            if (event.error) {
+                                setError(event.error);
+                            }
+                            break;
+                    }
+                });
+                // Update final message with complete content and tool calls
+                updateMessage(assistantMessageId, {
+                    content: response.message.content,
+                    toolCalls: response.message.toolCalls,
+                });
+                // Handle tool calls if present
+                if (response.message.toolCalls &&
+                    response.message.toolCalls.length > 0) {
+                    // Tool calls are executed by the tool executor if configured
+                    if (toolExecutor) {
+                        for (const toolCall of response.message.toolCalls) {
+                            await toolExecutor.execute({
+                                toolCallId: toolCall.toolCallId,
+                                toolName: toolCall.toolName,
+                                args: toolCall.args,
+                            });
+                        }
+                    }
+                }
+            }
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setLoading(false);
+            stopStreaming();
+        }
+    }, [
+        inferenceProvider,
+        protocolAdapter,
+        toolExecutor,
+        messages,
+        addMessage,
+        updateMessage,
+        setLoading,
+        setError,
+        startStreaming,
+        appendToStream,
+        stopStreaming,
+        getTools,
+    ]);
+    /**
+     * Append a message directly
+     */
+    const appendMessage = useCallback((message) => {
+        addMessage(message);
+    }, [addMessage]);
+    /**
+     * Stop current generation
+     */
+    const stopGeneration = useCallback(() => {
+        inferenceProvider?.cancelRequest();
+        protocolAdapter?.disconnect?.();
+        stopStreaming();
+        setLoading(false);
+    }, [inferenceProvider, protocolAdapter, stopStreaming, setLoading]);
+    /**
+     * Reload/regenerate from a specific message
+     */
+    const reloadMessages = useCallback(async (fromMessageId) => {
+        // Find the message index
+        const messageIndex = messages.findIndex(m => m.id === fromMessageId);
+        if (messageIndex === -1)
+            return;
+        // Find the last user message before this point
+        let lastUserMessageIndex = messageIndex;
+        for (let i = messageIndex; i >= 0; i--) {
+            if (messages[i].role === 'user') {
+                lastUserMessageIndex = i;
+                break;
+            }
+        }
+        // Get the user message content
+        const userMessage = messages[lastUserMessageIndex];
+        const userContent = typeof userMessage.content === 'string'
+            ? userMessage.content
+            : 'Regenerate response';
+        // Remove messages from the found index onwards
+        const previousMessages = messages.slice(0, lastUserMessageIndex);
+        // Clear and restore messages
+        clearMessages();
+        previousMessages.forEach(msg => addMessage(msg));
+        // Resend the user message
+        await sendMessage(userContent);
+    }, [messages, clearMessages, addMessage, sendMessage]);
+    /**
+     * Check if chat is available
+     */
+    const isAvailable = useMemo(() => (inferenceProvider?.isAvailable() ?? false) || protocolAdapter !== null, [inferenceProvider, protocolAdapter]);
+    return {
+        messages,
+        isLoading,
+        isStreaming,
+        error,
+        sendMessage,
+        appendMessage,
+        updateMessage,
+        deleteMessage,
+        clearMessages,
+        stopGeneration,
+        reloadMessages,
+        isAvailable,
+        suggestions,
+        setSuggestions,
+    };
+}

package/lib/hooks/useKeyboardShortcuts.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Keyboard shortcut configuration
+ */
+export interface KeyboardShortcut {
+    /** Key to press (e.g., 'k', 'Escape') */
+    key: string;
+    /** Whether Ctrl (or Cmd on Mac) is required */
+    ctrlOrCmd?: boolean;
+    /** Whether Shift is required */
+    shift?: boolean;
+    /** Whether Alt is required */
+    alt?: boolean;
+    /** Callback when shortcut is triggered */
+    handler: () => void;
+    /** Description for accessibility */
+    description?: string;
+    /** Whether shortcut works in input fields */
+    allowInInput?: boolean;
+}
+/**
+ * Hook options
+ */
+export interface UseKeyboardShortcutsOptions {
+    /** Whether shortcuts are enabled */
+    enabled?: boolean;
+    /** Shortcuts to register */
+    shortcuts: KeyboardShortcut[];
+}
+/**
+ * Hook to handle keyboard shortcuts
+ */
+export declare function useKeyboardShortcuts({ enabled, shortcuts, }: UseKeyboardShortcutsOptions): void;
+/**
+ * Default chat shortcuts
+ */
+export declare function useChatKeyboardShortcuts({ onToggle, onNewChat, onClear, onFocusInput, enabled, }: {
+    onToggle?: () => void;
+    onNewChat?: () => void;
+    onClear?: () => void;
+    onFocusInput?: () => void;
+    enabled?: boolean;
+}): void;
+/**
+ * Get shortcut display string
+ */
+export declare function getShortcutDisplay(shortcut: KeyboardShortcut): string;
+export default useKeyboardShortcuts;

package/lib/hooks/useKeyboardShortcuts.js

@@ -0,0 +1,153 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Keyboard shortcuts hook for Chat.
+ * Provides keyboard shortcut handling for the chat interface.
+ *
+ * @module components/chat/hooks/useKeyboardShortcuts
+ */
+import { useEffect, useCallback } from 'react';
+/**
+ * Platform detection - check if running on macOS
+ */
+function isMacOS() {
+    if (typeof navigator === 'undefined')
+        return false;
+    return /Mac|iPod|iPhone|iPad/.test(navigator.platform);
+}
+/**
+ * Hook to handle keyboard shortcuts
+ */
+export function useKeyboardShortcuts({ enabled = true, shortcuts, }) {
+    const handleKeyDown = useCallback((event) => {
+        if (!enabled)
+            return;
+        const target = event.target;
+        const isInInput = target.tagName === 'INPUT' ||
+            target.tagName === 'SELECT' ||
+            target.tagName === 'TEXTAREA' ||
+            target.isContentEditable;
+        for (const shortcut of shortcuts) {
+            // Skip if in input and not allowed
+            if (isInInput && !shortcut.allowInInput) {
+                // Exception: always allow Escape
+                if (shortcut.key !== 'Escape') {
+                    continue;
+                }
+            }
+            // Check key match
+            if (event.key.toLowerCase() !== shortcut.key.toLowerCase()) {
+                continue;
+            }
+            // Check modifiers
+            const ctrlOrCmdPressed = isMacOS() ? event.metaKey : event.ctrlKey;
+            if (shortcut.ctrlOrCmd && !ctrlOrCmdPressed) {
+                continue;
+            }
+            if (!shortcut.ctrlOrCmd &&
+                ctrlOrCmdPressed &&
+                shortcut.key !== 'Escape') {
+                continue;
+            }
+            if (shortcut.shift && !event.shiftKey) {
+                continue;
+            }
+            if (shortcut.alt && !event.altKey) {
+                continue;
+            }
+            // Prevent default and execute handler
+            event.preventDefault();
+            event.stopPropagation();
+            shortcut.handler();
+            break;
+        }
+    }, [enabled, shortcuts]);
+    useEffect(() => {
+        if (!enabled)
+            return;
+        document.addEventListener('keydown', handleKeyDown);
+        return () => {
+            document.removeEventListener('keydown', handleKeyDown);
+        };
+    }, [enabled, handleKeyDown]);
+}
+/**
+ * Default chat shortcuts
+ */
+export function useChatKeyboardShortcuts({ onToggle, onNewChat, onClear, onFocusInput, enabled = true, }) {
+    const shortcuts = [];
+    // Toggle chat: Ctrl/Cmd + K
+    if (onToggle) {
+        shortcuts.push({
+            key: 'k',
+            ctrlOrCmd: true,
+            handler: onToggle,
+            description: 'Toggle chat sidebar',
+        });
+    }
+    // New chat: Ctrl/Cmd + Shift + N
+    if (onNewChat) {
+        shortcuts.push({
+            key: 'n',
+            ctrlOrCmd: true,
+            shift: true,
+            handler: onNewChat,
+            description: 'Start new chat',
+        });
+    }
+    // Clear: Ctrl/Cmd + Shift + Delete
+    if (onClear) {
+        shortcuts.push({
+            key: 'Backspace',
+            ctrlOrCmd: true,
+            shift: true,
+            handler: onClear,
+            description: 'Clear chat messages',
+        });
+    }
+    // Focus input: /
+    if (onFocusInput) {
+        shortcuts.push({
+            key: '/',
+            handler: onFocusInput,
+            description: 'Focus chat input',
+        });
+    }
+    // Close on Escape
+    if (onToggle) {
+        shortcuts.push({
+            key: 'Escape',
+            handler: onToggle,
+            description: 'Close chat sidebar',
+            allowInInput: true,
+        });
+    }
+    useKeyboardShortcuts({ enabled, shortcuts });
+}
+/**
+ * Get shortcut display string
+ */
+export function getShortcutDisplay(shortcut) {
+    const parts = [];
+    const isMac = isMacOS();
+    if (shortcut.ctrlOrCmd) {
+        parts.push(isMac ? '⌘' : 'Ctrl');
+    }
+    if (shortcut.shift) {
+        parts.push(isMac ? '⇧' : 'Shift');
+    }
+    if (shortcut.alt) {
+        parts.push(isMac ? '⌥' : 'Alt');
+    }
+    // Format key name
+    let keyDisplay = shortcut.key.toUpperCase();
+    if (shortcut.key === 'Escape')
+        keyDisplay = 'Esc';
+    if (shortcut.key === 'Backspace')
+        keyDisplay = isMac ? '⌫' : 'Del';
+    parts.push(keyDisplay);
+    return parts.join(isMac ? '' : '+');
+}
+export default useKeyboardShortcuts;

package/lib/hooks/useMobile.d.ts

@@ -0,0 +1 @@
+export declare function useIsMobile(): boolean;

package/lib/hooks/useMobile.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import * as React from 'react';
+const MOBILE_BREAKPOINT = 768;
+export function useIsMobile() {
+    const [isMobile, setIsMobile] = React.useState(undefined);
+    React.useEffect(() => {
+        const mql = window.matchMedia(`(max-width: ${MOBILE_BREAKPOINT - 1}px)`);
+        const onChange = () => {
+            setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+        };
+        mql.addEventListener('change', onChange);
+        setIsMobile(window.innerWidth < MOBILE_BREAKPOINT);
+        return () => mql.removeEventListener('change', onChange);
+    }, []);
+    return !!isMobile;
+}

package/lib/hooks/useNotebookAIAgent.d.ts

@@ -0,0 +1,8 @@
+import type { IAIAgent } from '../models';
+/**
+ * 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 declare function useNotebookAIAgent(notebookId: string): IAIAgent | undefined;
+export default useNotebookAIAgent;