@datalayer/agent-runtimes 0.0.2

package/lib/components/chat/store/chatStore.js

@@ -0,0 +1,313 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Zustand store for chat state management.
+ * Provides centralized state for messages, tools, config, and instances.
+ * This is the primary state management - NO React Context/Provider needed.
+ *
+ * @module components/chat/store/chatStore
+ */
+import { create } from 'zustand';
+import { devtools, subscribeWithSelector } from 'zustand/middleware';
+/**
+ * Default configuration
+ */
+export const defaultChatConfig = {
+    defaultProvider: 'datalayer',
+    defaultProtocol: 'ag-ui',
+    enableStreaming: true,
+    requireToolApproval: false,
+    debug: false,
+    persistToLocalStorage: false,
+};
+/**
+ * Initial state
+ */
+const initialState = {
+    config: defaultChatConfig,
+    ready: true, // Ready by default - no provider initialization needed
+    inferenceProvider: null,
+    protocolAdapter: null,
+    toolExecutor: null,
+    middlewarePipeline: null,
+    extensionRegistry: null,
+    messages: [],
+    isLoading: false,
+    isStreaming: false,
+    streamingMessageId: null,
+    currentThreadId: null,
+    threads: new Map(),
+    tools: new Map(),
+    pendingToolCalls: new Map(),
+    extensions: new Map(),
+    middlewares: [],
+    isOpen: false,
+    error: null,
+    suggestions: [],
+};
+/**
+ * Create the chat store
+ */
+export const useChatStore = create()(devtools(subscribeWithSelector(
+// Note: persist middleware removed for now to avoid serialization issues with Map
+// Can be added back with custom serialization if needed
+(set, get) => ({
+    ...initialState,
+    // === Configuration actions ===
+    setConfig: config => {
+        set(state => ({
+            config: { ...state.config, ...config },
+        }), false, 'setConfig');
+    },
+    setReady: ready => {
+        set({ ready }, false, 'setReady');
+    },
+    // === Instance actions ===
+    setInferenceProvider: provider => {
+        set({ inferenceProvider: provider }, false, 'setInferenceProvider');
+    },
+    setProtocolAdapter: adapter => {
+        set({ protocolAdapter: adapter }, false, 'setProtocolAdapter');
+    },
+    setToolExecutor: executor => {
+        set({ toolExecutor: executor }, false, 'setToolExecutor');
+    },
+    setMiddlewarePipeline: pipeline => {
+        set({ middlewarePipeline: pipeline }, false, 'setMiddlewarePipeline');
+    },
+    setExtensionRegistry: registry => {
+        set({ extensionRegistry: registry }, false, 'setExtensionRegistry');
+    },
+    // === Message actions ===
+    addMessage: message => {
+        set(state => ({
+            messages: [...state.messages, message],
+        }), false, 'addMessage');
+    },
+    updateMessage: (messageId, updates) => {
+        set(state => ({
+            messages: state.messages.map(msg => msg.id === messageId ? { ...msg, ...updates } : msg),
+        }), false, 'updateMessage');
+    },
+    deleteMessage: messageId => {
+        set(state => ({
+            messages: state.messages.filter(msg => msg.id !== messageId),
+        }), false, 'deleteMessage');
+    },
+    setMessages: messages => {
+        set({ messages }, false, 'setMessages');
+    },
+    clearMessages: () => {
+        set({ messages: [] }, false, 'clearMessages');
+    },
+    // === Streaming actions ===
+    startStreaming: messageId => {
+        set({ isStreaming: true, streamingMessageId: messageId }, false, 'startStreaming');
+    },
+    appendToStream: (messageId, content) => {
+        set(state => ({
+            messages: state.messages.map(msg => msg.id === messageId
+                ? {
+                    ...msg,
+                    content: typeof msg.content === 'string'
+                        ? msg.content + content
+                        : msg.content,
+                }
+                : msg),
+        }), false, 'appendToStream');
+    },
+    stopStreaming: () => {
+        set({ isStreaming: false, streamingMessageId: null }, false, 'stopStreaming');
+    },
+    // === Loading state ===
+    setLoading: loading => {
+        set({ isLoading: loading }, false, 'setLoading');
+    },
+    setError: error => {
+        set({ error }, false, 'setError');
+    },
+    // === Thread actions ===
+    setCurrentThread: threadId => {
+        set({ currentThreadId: threadId }, false, 'setCurrentThread');
+    },
+    createThread: title => {
+        const threadId = `thread_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`;
+        const thread = {
+            id: threadId,
+            title: title || 'New Chat',
+            createdAt: new Date(),
+            updatedAt: new Date(),
+        };
+        set(state => {
+            const newThreads = new Map(state.threads);
+            newThreads.set(threadId, thread);
+            return { threads: newThreads, currentThreadId: threadId };
+        }, false, 'createThread');
+        return threadId;
+    },
+    deleteThread: threadId => {
+        set(state => {
+            const newThreads = new Map(state.threads);
+            newThreads.delete(threadId);
+            return {
+                threads: newThreads,
+                currentThreadId: state.currentThreadId === threadId
+                    ? null
+                    : state.currentThreadId,
+            };
+        }, false, 'deleteThread');
+    },
+    // === Tool registry actions ===
+    registerTool: definition => {
+        set(state => {
+            const newTools = new Map(state.tools);
+            newTools.set(definition.name, {
+                definition,
+                registeredAt: new Date(),
+            });
+            return { tools: newTools };
+        }, false, 'registerTool');
+    },
+    unregisterTool: name => {
+        set(state => {
+            const newTools = new Map(state.tools);
+            newTools.delete(name);
+            return { tools: newTools };
+        }, false, 'unregisterTool');
+    },
+    getTool: name => {
+        return get().tools.get(name);
+    },
+    getTools: () => {
+        return Array.from(get().tools.values()).map(entry => entry.definition);
+    },
+    // === Tool call tracking ===
+    startToolCall: (toolCallId, toolName, args) => {
+        set(state => {
+            const newPending = new Map(state.pendingToolCalls);
+            newPending.set(toolCallId, {
+                toolCallId,
+                toolName,
+                args,
+                status: 'pending',
+                startedAt: new Date(),
+            });
+            return { pendingToolCalls: newPending };
+        }, false, 'startToolCall');
+    },
+    updateToolCallStatus: (toolCallId, status, result, error) => {
+        set(state => {
+            const newPending = new Map(state.pendingToolCalls);
+            const existing = newPending.get(toolCallId);
+            if (existing) {
+                newPending.set(toolCallId, {
+                    ...existing,
+                    status,
+                    result,
+                    error,
+                    completedAt: status === 'completed' || status === 'failed'
+                        ? new Date()
+                        : undefined,
+                });
+            }
+            return { pendingToolCalls: newPending };
+        }, false, 'updateToolCallStatus');
+    },
+    getPendingToolCalls: () => {
+        return Array.from(get().pendingToolCalls.values()).filter(tc => tc.status === 'pending' || tc.status === 'executing');
+    },
+    // === Extension registry actions ===
+    registerExtension: (extension, options) => {
+        set(state => {
+            const newExtensions = new Map(state.extensions);
+            newExtensions.set(extension.name, {
+                extension,
+                enabled: options?.enabled ?? true,
+                registeredAt: new Date(),
+            });
+            return { extensions: newExtensions };
+        }, false, 'registerExtension');
+    },
+    unregisterExtension: name => {
+        set(state => {
+            const newExtensions = new Map(state.extensions);
+            newExtensions.delete(name);
+            return { extensions: newExtensions };
+        }, false, 'unregisterExtension');
+    },
+    enableExtension: name => {
+        set(state => {
+            const newExtensions = new Map(state.extensions);
+            const entry = newExtensions.get(name);
+            if (entry) {
+                newExtensions.set(name, { ...entry, enabled: true });
+            }
+            return { extensions: newExtensions };
+        }, false, 'enableExtension');
+    },
+    disableExtension: name => {
+        set(state => {
+            const newExtensions = new Map(state.extensions);
+            const entry = newExtensions.get(name);
+            if (entry) {
+                newExtensions.set(name, { ...entry, enabled: false });
+            }
+            return { extensions: newExtensions };
+        }, false, 'disableExtension');
+    },
+    getExtensions: (type) => {
+        const extensions = Array.from(get().extensions.values())
+            .filter(entry => entry.enabled)
+            .map(entry => entry.extension);
+        if (type) {
+            return extensions.filter(ext => ext.type === type);
+        }
+        return extensions;
+    },
+    // === Middleware actions ===
+    addMiddleware: middleware => {
+        set(state => ({
+            middlewares: [...state.middlewares, middleware].sort((a, b) => (a.priority ?? 100) - (b.priority ?? 100)),
+        }), false, 'addMiddleware');
+    },
+    removeMiddleware: name => {
+        set(state => ({
+            middlewares: state.middlewares.filter(m => m.name !== name),
+        }), false, 'removeMiddleware');
+    },
+    getMiddlewares: () => {
+        return get().middlewares;
+    },
+    // === UI actions ===
+    setOpen: open => {
+        set({ isOpen: open }, false, 'setOpen');
+    },
+    toggleOpen: () => {
+        set(state => ({ isOpen: !state.isOpen }), false, 'toggleOpen');
+    },
+    setSuggestions: suggestions => {
+        set({ suggestions }, false, 'setSuggestions');
+    },
+    // === Reset ===
+    reset: () => {
+        set(initialState, false, 'reset');
+    },
+})), { name: 'chat-store' }));
+/**
+ * Selector hooks for specific state slices
+ */
+export const useChatMessages = () => useChatStore(state => state.messages);
+export const useChatLoading = () => useChatStore(state => state.isLoading);
+export const useChatStreaming = () => useChatStore(state => ({
+    isStreaming: state.isStreaming,
+    streamingMessageId: state.streamingMessageId,
+}));
+export const useChatError = () => useChatStore(state => state.error);
+export const useChatTools = () => useChatStore(state => state.getTools());
+export const useChatOpen = () => useChatStore(state => state.isOpen);
+export const useChatConfig = () => useChatStore(state => state.config);
+export const useChatReady = () => useChatStore(state => state.ready);
+export const useChatInferenceProvider = () => useChatStore(state => state.inferenceProvider);
+export const useChatExtensionRegistry = () => useChatStore(state => state.extensionRegistry);

package/lib/components/chat/store/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Store exports for chat component.
+ *
+ * @module components/chat/store
+ */
+export { useChatStore, useChatMessages, useChatLoading, useChatStreaming, useChatError, useChatTools, useChatOpen, useChatConfig, useChatReady, useChatInferenceProvider, useChatExtensionRegistry, defaultChatConfig, type ChatStore, type ChatConfig, type ToolCallState, } from './chatStore';

package/lib/components/chat/store/index.js

@@ -0,0 +1,10 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Store exports for chat component.
+ *
+ * @module components/chat/store
+ */
+export { useChatStore, useChatMessages, useChatLoading, useChatStreaming, useChatError, useChatTools, useChatOpen, useChatConfig, useChatReady, useChatInferenceProvider, useChatExtensionRegistry, defaultChatConfig, } from './chatStore';

package/lib/components/chat/tools/ToolExecutor.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tool executor for hybrid tool execution (frontend + backend).
+ * Handles routing tool calls to appropriate execution location.
+ *
+ * @module components/chat/tools/ToolExecutor
+ */
+import type { ToolDefinition, FrontendToolDefinition, ToolCallRequest, ToolExecutionResult, ToolRenderStatus } from '../types/tool';
+import type { InferenceProvider } from '../types/inference';
+/**
+ * Execution context for tool calls
+ */
+export interface ToolExecutionContext {
+    /** Tool registry for looking up definitions */
+    getToolDefinition: (name: string) => ToolDefinition | undefined;
+    /** Inference provider for backend tool execution */
+    inferenceProvider?: InferenceProvider;
+    /** Callback for HITL approval (returns approved result or null if rejected) */
+    onHitlRequired?: (toolCall: ToolCallRequest, definition: FrontendToolDefinition) => Promise<unknown | null>;
+    /** Callback for status updates */
+    onStatusChange?: (toolCallId: string, status: ToolRenderStatus, result?: unknown, error?: string) => void;
+}
+/**
+ * Tool executor handles routing and executing tool calls
+ */
+export declare class ToolExecutor {
+    private context;
+    constructor(context: ToolExecutionContext);
+    /**
+     * Execute a tool call
+     * Routes to frontend or backend based on tool definition
+     */
+    execute(toolCall: ToolCallRequest): Promise<ToolExecutionResult>;
+    /**
+     * Execute a frontend tool
+     */
+    private executeFrontend;
+    /**
+     * Execute a backend tool
+     */
+    private executeBackend;
+    /**
+     * Execute multiple tool calls in parallel
+     */
+    executeMultiple(toolCalls: ToolCallRequest[]): Promise<Map<string, ToolExecutionResult>>;
+}
+/**
+ * Create a tool executor with the given context
+ */
+export declare function createToolExecutor(context: ToolExecutionContext): ToolExecutor;

package/lib/components/chat/tools/ToolExecutor.js

@@ -0,0 +1,151 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { hasHitlRender } from '../types/tool';
+/**
+ * Tool executor handles routing and executing tool calls
+ */
+export class ToolExecutor {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    /**
+     * Execute a tool call
+     * Routes to frontend or backend based on tool definition
+     */
+    async execute(toolCall) {
+        const { toolCallId, toolName } = toolCall;
+        const definition = this.context.getToolDefinition(toolName);
+        if (!definition) {
+            return {
+                success: false,
+                error: `Tool "${toolName}" not found in registry`,
+            };
+        }
+        // Determine execution location (default to frontend if not specified)
+        const location = definition.location || 'frontend';
+        this.context.onStatusChange?.(toolCallId, 'executing');
+        try {
+            let result;
+            if (location === 'backend') {
+                result = await this.executeBackend(toolCall, definition);
+            }
+            else {
+                result = await this.executeFrontend(toolCall, definition);
+            }
+            this.context.onStatusChange?.(toolCallId, result.success ? 'complete' : 'failed', result.result, result.error);
+            return result;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.context.onStatusChange?.(toolCallId, 'failed', undefined, errorMessage);
+            return {
+                success: false,
+                error: errorMessage,
+            };
+        }
+    }
+    /**
+     * Execute a frontend tool
+     */
+    async executeFrontend(toolCall, definition) {
+        const { args } = toolCall;
+        const startTime = Date.now();
+        // Check for HITL (Human-in-the-Loop) requirement
+        if (hasHitlRender(definition) && this.context.onHitlRequired) {
+            const hitlResult = await this.context.onHitlRequired(toolCall, definition);
+            if (hitlResult === null) {
+                return {
+                    success: false,
+                    error: 'Tool call was rejected by user',
+                };
+            }
+            return {
+                success: true,
+                result: hitlResult,
+                executionTime: Date.now() - startTime,
+            };
+        }
+        // Check if handler is defined
+        if (!definition.handler) {
+            return {
+                success: false,
+                error: `Frontend tool "${definition.name}" has no handler defined`,
+            };
+        }
+        // Execute the handler
+        try {
+            const result = await definition.handler(args);
+            return {
+                success: true,
+                result,
+                executionTime: Date.now() - startTime,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+                executionTime: Date.now() - startTime,
+            };
+        }
+    }
+    /**
+     * Execute a backend tool
+     */
+    async executeBackend(toolCall, _definition) {
+        const { toolName, args } = toolCall;
+        if (!this.context.inferenceProvider) {
+            return {
+                success: false,
+                error: 'No inference provider configured for backend tool execution',
+            };
+        }
+        if (!this.context.inferenceProvider.executeBackendTool) {
+            return {
+                success: false,
+                error: `Inference provider "${this.context.inferenceProvider.name}" does not support backend tool execution`,
+            };
+        }
+        return this.context.inferenceProvider.executeBackendTool(toolName, args);
+    }
+    /**
+     * Execute multiple tool calls in parallel
+     */
+    async executeMultiple(toolCalls) {
+        const results = new Map();
+        // Group by execution location for optimization
+        const frontendCalls = [];
+        const backendCalls = [];
+        for (const toolCall of toolCalls) {
+            const definition = this.context.getToolDefinition(toolCall.toolName);
+            const location = definition?.location || 'frontend';
+            if (location === 'backend') {
+                backendCalls.push(toolCall);
+            }
+            else {
+                frontendCalls.push(toolCall);
+            }
+        }
+        // Execute frontend calls in parallel
+        const frontendPromises = frontendCalls.map(async (tc) => {
+            const result = await this.execute(tc);
+            results.set(tc.toolCallId, result);
+        });
+        // Execute backend calls (could be batched in future)
+        const backendPromises = backendCalls.map(async (tc) => {
+            const result = await this.execute(tc);
+            results.set(tc.toolCallId, result);
+        });
+        await Promise.all([...frontendPromises, ...backendPromises]);
+        return results;
+    }
+}
+/**
+ * Create a tool executor with the given context
+ */
+export function createToolExecutor(context) {
+    return new ToolExecutor(context);
+}

package/lib/components/chat/tools/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Tool exports for chat component.
+ *
+ * @module components/chat/tools
+ */
+export { ToolExecutor, createToolExecutor, type ToolExecutionContext, } from './ToolExecutor';
+export type { ToolDefinition, FrontendToolDefinition, BackendToolDefinition, ToolLocation, ToolParameter, ToolRenderStatus, ToolRenderProps, ToolRenderAndWaitProps, ToolCallRequest, ToolExecutionResult, ToolRegistryEntry, } from '../types/tool';
+export { isFrontendTool, isBackendTool, hasHitlRender } from '../types/tool';

package/lib/components/chat/tools/index.js

@@ -0,0 +1,11 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Tool exports for chat component.
+ *
+ * @module components/chat/tools
+ */
+export { ToolExecutor, createToolExecutor, } from './ToolExecutor';
+export { isFrontendTool, isBackendTool, hasHitlRender } from '../types/tool';