@datalayer/agent-runtimes 0.0.5 → 0.0.8

package/lib/runtime/runtimeStore.js

@@ -0,0 +1,184 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Zustand store for runtime management.
+ *
+ * Provides a global store for managing cloud runtimes and agent connections.
+ *
+ * @module runtime/runtimeStore
+ */
+import { create } from 'zustand';
+const initialState = {
+    runtime: null,
+    agent: null,
+    status: 'idle',
+    error: null,
+    isLaunching: false,
+};
+/**
+ * Create an agent on a runtime.
+ */
+async function createAgentOnRuntime(agentBaseUrl, agentId, config = {}) {
+    const response = await fetch(`${agentBaseUrl}/api/v1/agents`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+            name: config.name || agentId,
+            description: config.description || 'AI assistant',
+            agent_library: config.agentLibrary || 'pydantic-ai',
+            transport: config.transport || 'ag-ui',
+            model: config.model || 'anthropic:claude-sonnet-4-5',
+            system_prompt: config.systemPrompt || 'You are a helpful AI assistant.',
+        }),
+    });
+    if (response.ok || response.status === 400) {
+        // 400 means agent already exists, which is fine
+        const endpoint = `${agentBaseUrl}/api/v1/ag-ui/${agentId}/`;
+        return {
+            agentId,
+            endpoint,
+            isReady: true,
+        };
+    }
+    const errorData = await response.json().catch(() => ({}));
+    throw new Error(errorData.detail || `Failed to create agent: ${response.status}`);
+}
+/**
+ * Zustand store for runtime management.
+ *
+ * @example
+ * ```typescript
+ * import { useRuntimeStore } from '@datalayer/agent-runtimes/lib/runtime';
+ *
+ * // In a component
+ * const { runtime, launchRuntime, status } = useRuntimeStore();
+ *
+ * // Launch a runtime
+ * await launchRuntime({ environmentName: 'python-simple', creditsLimit: 100 });
+ *
+ * // Access runtime info
+ * console.log(runtime?.agentBaseUrl);
+ * ```
+ */
+export const useRuntimeStore = create((set, get) => ({
+    ...initialState,
+    connectToRuntime: connection => {
+        const baseUrl = connection.serviceManager.serverSettings.baseUrl;
+        const agentBaseUrl = baseUrl.replace('/jupyter/server/', '/agent-runtimes/');
+        const fullConnection = {
+            podName: connection.podName,
+            environmentName: connection.environmentName,
+            jupyterBaseUrl: baseUrl,
+            agentBaseUrl,
+            serviceManager: connection.serviceManager,
+            status: 'ready',
+            kernelId: connection.kernelId,
+        };
+        set({
+            runtime: fullConnection,
+            status: 'ready',
+            error: null,
+        });
+    },
+    launchRuntime: async (config) => {
+        set({ status: 'launching', error: null, isLaunching: true });
+        try {
+            // Import @datalayer/core dynamically to avoid circular dependencies
+            const { createRuntime, makeDatalayerSettings } = await import('@datalayer/core/lib/api');
+            const { ServiceManager } = await import('@jupyterlab/services');
+            // Create the runtime using IRuntimeOptions from @datalayer/core
+            const runtimePod = await createRuntime({
+                environmentName: config.environmentName,
+                creditsLimit: config.creditsLimit,
+                type: config.type || 'notebook',
+                givenName: config.givenName,
+                capabilities: config.capabilities,
+                snapshot: config.snapshot,
+            });
+            set({ status: 'connecting' });
+            // Create service manager for the runtime
+            const serverSettings = makeDatalayerSettings(runtimePod.ingress, runtimePod.token);
+            const serviceManager = new ServiceManager({ serverSettings });
+            // Wait for the service manager to be ready
+            await serviceManager.ready;
+            // Construct URLs
+            const jupyterBaseUrl = serverSettings.baseUrl;
+            const agentBaseUrl = jupyterBaseUrl.replace('/jupyter/server/', '/agent-runtimes/');
+            const connection = {
+                podName: runtimePod.pod_name,
+                environmentName: runtimePod.environment_name,
+                jupyterBaseUrl,
+                agentBaseUrl,
+                serviceManager,
+                status: 'ready',
+            };
+            set({
+                runtime: connection,
+                status: 'ready',
+                isLaunching: false,
+            });
+            return connection;
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : 'Failed to launch runtime';
+            set({
+                status: 'error',
+                error: errorMessage,
+                isLaunching: false,
+            });
+            throw err;
+        }
+    },
+    createAgent: async (config = {}) => {
+        const { runtime } = get();
+        if (!runtime) {
+            throw new Error('No runtime connected. Launch or connect to a runtime first.');
+        }
+        try {
+            const agentId = config.name || runtime.podName;
+            const agentConnection = await createAgentOnRuntime(runtime.agentBaseUrl, agentId, config);
+            set({ agent: agentConnection });
+            return agentConnection;
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : 'Failed to create agent';
+            set({ error: errorMessage });
+            throw err;
+        }
+    },
+    disconnect: () => {
+        set({
+            runtime: null,
+            agent: null,
+            status: 'disconnected',
+            error: null,
+        });
+    },
+    clearError: () => {
+        set({ error: null });
+    },
+    setError: error => {
+        set({ error, status: 'error' });
+    },
+    reset: () => {
+        set(initialState);
+    },
+}));
+/**
+ * Selector hooks for common use cases.
+ */
+export const useRuntime = () => useRuntimeStore(state => state.runtime);
+export const useAgent = () => useRuntimeStore(state => state.agent);
+export const useRuntimeStatus = () => useRuntimeStore(state => state.status);
+export const useRuntimeError = () => useRuntimeStore(state => state.error);
+export const useIsLaunching = () => useRuntimeStore(state => state.isLaunching);
+/**
+ * Get runtime store state without React (for use outside components).
+ */
+export const getRuntimeState = () => useRuntimeStore.getState();
+/**
+ * Subscribe to runtime store changes (for use outside React).
+ */
+export const subscribeToRuntime = useRuntimeStore.subscribe;

package/lib/runtime/types.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Type definitions for runtime management.
+ *
+ * Re-exports relevant types from @datalayer/core and defines
+ * agent-runtimes specific types for AI agent management.
+ *
+ * @module runtime/types
+ */
+import type { ServiceManager } from '@jupyterlab/services';
+export type { IRuntimeLocation, IRuntimeType, IRuntimeCapabilities, IRuntimePod, IRuntimeDesc, } from '@datalayer/core/lib/models';
+export type { IRuntimeOptions } from '@datalayer/core/lib/stateful/runtimes/apis';
+/**
+ * Runtime connection status for the agent-runtimes store.
+ */
+export type AgentRuntimeStatus = 'idle' | 'launching' | 'connecting' | 'ready' | 'error' | 'disconnected';
+/**
+ * Information about a connected runtime with agent-runtimes server.
+ * Extends the basic runtime info with URLs for both Jupyter and agent services.
+ */
+export interface RuntimeConnection {
+    /** Runtime pod name (unique identifier) */
+    podName: string;
+    /** Environment name */
+    environmentName: string;
+    /** Base URL for the Jupyter server */
+    jupyterBaseUrl: string;
+    /** Base URL for the agent-runtimes server */
+    agentBaseUrl: string;
+    /** JupyterLab ServiceManager for the runtime */
+    serviceManager: ServiceManager.IManager;
+    /** Runtime status */
+    status: AgentRuntimeStatus;
+    /** Kernel ID if connected */
+    kernelId?: string;
+}
+/**
+ * Configuration for creating an agent on a runtime.
+ */
+export interface AgentConfig {
+    /** Agent name/ID (defaults to runtime pod name) */
+    name?: string;
+    /** Agent description */
+    description?: string;
+    /** AI model to use (e.g., 'anthropic:claude-sonnet-4-5') */
+    model?: string;
+    /** System prompt for the agent */
+    systemPrompt?: string;
+    /** Agent library (defaults to 'pydantic-ai') */
+    agentLibrary?: 'pydantic-ai' | 'langchain' | 'openai';
+    /** Transport protocol (defaults to 'ag-ui') */
+    transport?: 'ag-ui' | 'vercel-ai' | 'acp' | 'a2a';
+}
+/**
+ * Information about a connected agent.
+ */
+export interface AgentConnection {
+    /** Agent ID */
+    agentId: string;
+    /** Full endpoint URL for the agent */
+    endpoint: string;
+    /** Whether the agent is ready to use */
+    isReady: boolean;
+}
+/**
+ * Complete state for an agent runtime in the Zustand store.
+ */
+export interface AgentRuntimeState {
+    /** Runtime connection (null if not connected) */
+    runtime: RuntimeConnection | null;
+    /** Agent connection (null if not created) */
+    agent: AgentConnection | null;
+    /** Current status */
+    status: AgentRuntimeStatus;
+    /** Error message if any */
+    error: string | null;
+    /** Whether the runtime is launching */
+    isLaunching: boolean;
+    /** Whether the agent is ready */
+    isReady: boolean;
+}
+/**
+ * Default agent configuration values.
+ */
+export declare const DEFAULT_AGENT_CONFIG: Required<AgentConfig>;

package/lib/runtime/types.js

@@ -0,0 +1,15 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Default agent configuration values.
+ */
+export const DEFAULT_AGENT_CONFIG = {
+    name: 'ai-agent',
+    description: 'AI Assistant',
+    model: 'anthropic:claude-sonnet-4-5',
+    systemPrompt: 'You are a helpful AI assistant.',
+    agentLibrary: 'pydantic-ai',
+    transport: 'ag-ui',
+};

package/lib/runtime/useAgentConnection.d.ts

@@ -0,0 +1,46 @@
+import type { AgentConfig, AgentConnection } from './types';
+interface UseAgentConnectionOptions {
+    /** Agent configuration */
+    config?: AgentConfig;
+    /** Auto-create agent when runtime is ready */
+    autoCreate?: boolean;
+}
+interface UseAgentConnectionReturn {
+    /** Current agent connection */
+    agent: AgentConnection | null;
+    /** Whether the agent is ready */
+    isReady: boolean;
+    /** Whether agent creation is in progress */
+    isCreating: boolean;
+    /** Error message if any */
+    error: string | null;
+    /** Create an agent on the runtime */
+    create: (config?: AgentConfig) => Promise<AgentConnection>;
+}
+/**
+ * Hook for creating and managing agent connections.
+ * Uses the Zustand store for runtime state.
+ *
+ * @param options - Configuration options
+ * @returns Agent state and control functions
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { runtime } = useRuntimeStore();
+ *   const { agent, isReady } = useAgentConnection({
+ *     autoCreate: true,
+ *     config: {
+ *       model: 'anthropic:claude-sonnet-4-5',
+ *       systemPrompt: 'You are a helpful assistant.',
+ *     },
+ *   });
+ *
+ *   if (!isReady) return <div>Creating agent...</div>;
+ *
+ *   return <ChatFloating endpoint={agent.endpoint} />;
+ * }
+ * ```
+ */
+export declare function useAgentConnection(options?: UseAgentConnectionOptions): UseAgentConnectionReturn;
+export {};

package/lib/runtime/useAgentConnection.js

@@ -0,0 +1,112 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Hook for creating and managing agent connections on a runtime.
+ *
+ * @module runtime/useAgentConnection
+ */
+import { useState, useCallback, useEffect, useRef } from 'react';
+import { useRuntimeStore } from './runtimeStore';
+const DEFAULT_AGENT_CONFIG = {
+    model: 'anthropic:claude-sonnet-4-5',
+    systemPrompt: 'You are a helpful AI assistant.',
+    agentLibrary: 'pydantic-ai',
+    transport: 'ag-ui',
+};
+/**
+ * Hook for creating and managing agent connections.
+ * Uses the Zustand store for runtime state.
+ *
+ * @param options - Configuration options
+ * @returns Agent state and control functions
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const { runtime } = useRuntimeStore();
+ *   const { agent, isReady } = useAgentConnection({
+ *     autoCreate: true,
+ *     config: {
+ *       model: 'anthropic:claude-sonnet-4-5',
+ *       systemPrompt: 'You are a helpful assistant.',
+ *     },
+ *   });
+ *
+ *   if (!isReady) return <div>Creating agent...</div>;
+ *
+ *   return <ChatFloating endpoint={agent.endpoint} />;
+ * }
+ * ```
+ */
+export function useAgentConnection(options = {}) {
+    const { config, autoCreate = false } = options;
+    const runtime = useRuntimeStore(state => state.runtime);
+    const storeAgent = useRuntimeStore(state => state.agent);
+    const createStoreAgent = useRuntimeStore(state => state.createAgent);
+    const [isCreating, setIsCreating] = useState(false);
+    const [error, setError] = useState(null);
+    const creatingRef = useRef(false);
+    const createdForRuntimeRef = useRef(null);
+    const create = useCallback(async (overrideConfig) => {
+        if (!runtime) {
+            throw new Error('No runtime connected. Launch or connect to a runtime first.');
+        }
+        if (creatingRef.current) {
+            throw new Error('Agent creation already in progress');
+        }
+        creatingRef.current = true;
+        setIsCreating(true);
+        setError(null);
+        try {
+            // Merge configs: defaults < options.config < overrideConfig
+            const mergedConfig = {
+                ...DEFAULT_AGENT_CONFIG,
+                ...config,
+                ...overrideConfig,
+                name: overrideConfig?.name || config?.name || runtime.podName,
+            };
+            const agentConnection = await createStoreAgent(mergedConfig);
+            createdForRuntimeRef.current = runtime.podName;
+            return agentConnection;
+        }
+        catch (err) {
+            const errorMessage = err instanceof Error ? err.message : 'Failed to create agent';
+            setError(errorMessage);
+            throw err;
+        }
+        finally {
+            creatingRef.current = false;
+            setIsCreating(false);
+        }
+    }, [runtime, config, createStoreAgent]);
+    // Auto-create agent when runtime is ready (and not already created for this runtime)
+    useEffect(() => {
+        if (autoCreate &&
+            runtime &&
+            runtime.status === 'ready' &&
+            !storeAgent &&
+            !creatingRef.current) {
+            // Only create if we haven't already created for this runtime
+            if (createdForRuntimeRef.current !== runtime.podName) {
+                create().catch(err => {
+                    console.error('[useAgentConnection] Auto-create failed:', err);
+                });
+            }
+        }
+    }, [autoCreate, runtime, storeAgent, create]);
+    // Reset created tracking when runtime changes
+    useEffect(() => {
+        if (!runtime) {
+            createdForRuntimeRef.current = null;
+        }
+    }, [runtime]);
+    return {
+        agent: storeAgent,
+        isReady: !!storeAgent?.isReady,
+        isCreating,
+        error,
+        create,
+    };
+}

package/lib/runtime/useAgentRuntime.d.ts

@@ -0,0 +1,94 @@
+import type { ServiceManager } from '@jupyterlab/services';
+import type { IRuntimeOptions, AgentConfig, RuntimeConnection, AgentConnection, AgentRuntimeStatus } from './types';
+interface UseAgentRuntimeOptions {
+    /** Agent configuration */
+    agentConfig?: AgentConfig;
+    /** Auto-create agent when runtime connects */
+    autoCreateAgent?: boolean;
+}
+interface UseAgentRuntimeReturn {
+    /** Current runtime connection */
+    runtime: RuntimeConnection | null;
+    /** Current agent connection */
+    agent: AgentConnection | null;
+    /** Runtime status */
+    status: AgentRuntimeStatus;
+    /** Error message if any */
+    error: string | null;
+    /** Whether the runtime is launching */
+    isLaunching: boolean;
+    /** Whether everything is ready (runtime + agent) */
+    isReady: boolean;
+    /** Agent endpoint URL (shortcut) */
+    endpoint: string | null;
+    /** ServiceManager for the runtime */
+    serviceManager: ServiceManager.IManager | null;
+    /** Launch a new runtime */
+    launchRuntime: (options: IRuntimeOptions) => Promise<RuntimeConnection>;
+    /** Connect to an existing runtime */
+    connectToRuntime: (options: {
+        podName: string;
+        environmentName: string;
+        serviceManager: ServiceManager.IManager;
+        kernelId?: string;
+    }) => void;
+    /** Create an agent (if not auto-created) */
+    createAgent: (config?: AgentConfig) => Promise<AgentConnection>;
+    /** Disconnect from the runtime */
+    disconnect: () => void;
+}
+/**
+ * Combined hook for using a runtime with an AI agent.
+ *
+ * This hook provides everything needed to:
+ * 1. Connect to an existing runtime (or launch a new one)
+ * 2. Create an AI agent on the runtime
+ *
+ * Use this in conjunction with useNotebookTools or useLexicalTools
+ * for frontend tool execution.
+ *
+ * @param options - Configuration options
+ * @returns Complete agent runtime state and controls
+ *
+ * @example
+ * ```tsx
+ * // For notebooks
+ * import { useAgentRuntime } from '@datalayer/agent-runtimes/lib/runtime';
+ * import { useNotebookTools } from '@datalayer/agent-runtimes/lib/tools/adapters/agent-runtimes';
+ *
+ * function NotebookEditor({ notebookId }) {
+ *   const {
+ *     isReady,
+ *     endpoint,
+ *     error,
+ *     connectToRuntime,
+ *   } = useAgentRuntime({
+ *     autoCreateAgent: true,
+ *     agentConfig: {
+ *       model: 'anthropic:claude-sonnet-4-5',
+ *       systemPrompt: 'You help users with Jupyter notebooks.',
+ *     },
+ *   });
+ *
+ *   // Get tools separately
+ *   const tools = useNotebookTools(notebookId);
+ *
+ *   // Connect when user assigns a runtime
+ *   const onRuntimeAssigned = (serviceManager, podName, poolName) => {
+ *     connectToRuntime({ serviceManager, podName, jupyterpoolName: poolName });
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <Notebook />
+ *       {isReady && (
+ *         <ChatFloating endpoint={endpoint} tools={tools} />
+ *       )}
+ *       {error && <ErrorBanner>{error}</ErrorBanner>}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function useAgentRuntime(options?: UseAgentRuntimeOptions): UseAgentRuntimeReturn;
+export {};

package/lib/runtime/useAgentRuntime.js

@@ -0,0 +1,125 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Combined hook for using a runtime with an AI agent.
+ *
+ * This is the main entry point for consumers who want a simple,
+ * all-in-one solution for cloud runtime + agent management.
+ *
+ * @module runtime/useAgentRuntime
+ */
+import { useEffect, useRef, useCallback } from 'react';
+import { useRuntimeStore, useRuntime, useAgent, useRuntimeStatus, useRuntimeError, useIsLaunching, } from './runtimeStore';
+/**
+ * Combined hook for using a runtime with an AI agent.
+ *
+ * This hook provides everything needed to:
+ * 1. Connect to an existing runtime (or launch a new one)
+ * 2. Create an AI agent on the runtime
+ *
+ * Use this in conjunction with useNotebookTools or useLexicalTools
+ * for frontend tool execution.
+ *
+ * @param options - Configuration options
+ * @returns Complete agent runtime state and controls
+ *
+ * @example
+ * ```tsx
+ * // For notebooks
+ * import { useAgentRuntime } from '@datalayer/agent-runtimes/lib/runtime';
+ * import { useNotebookTools } from '@datalayer/agent-runtimes/lib/tools/adapters/agent-runtimes';
+ *
+ * function NotebookEditor({ notebookId }) {
+ *   const {
+ *     isReady,
+ *     endpoint,
+ *     error,
+ *     connectToRuntime,
+ *   } = useAgentRuntime({
+ *     autoCreateAgent: true,
+ *     agentConfig: {
+ *       model: 'anthropic:claude-sonnet-4-5',
+ *       systemPrompt: 'You help users with Jupyter notebooks.',
+ *     },
+ *   });
+ *
+ *   // Get tools separately
+ *   const tools = useNotebookTools(notebookId);
+ *
+ *   // Connect when user assigns a runtime
+ *   const onRuntimeAssigned = (serviceManager, podName, poolName) => {
+ *     connectToRuntime({ serviceManager, podName, jupyterpoolName: poolName });
+ *   };
+ *
+ *   return (
+ *     <>
+ *       <Notebook />
+ *       {isReady && (
+ *         <ChatFloating endpoint={endpoint} tools={tools} />
+ *       )}
+ *       {error && <ErrorBanner>{error}</ErrorBanner>}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function useAgentRuntime(options = {}) {
+    const { agentConfig, autoCreateAgent = true } = options;
+    // Get store state
+    const runtime = useRuntime();
+    const agent = useAgent();
+    const status = useRuntimeStatus();
+    const error = useRuntimeError();
+    const isLaunching = useIsLaunching();
+    // Get store actions
+    const launchRuntime = useRuntimeStore(state => state.launchRuntime);
+    const connectToRuntime = useRuntimeStore(state => state.connectToRuntime);
+    const disconnect = useRuntimeStore(state => state.disconnect);
+    const createAgentAction = useRuntimeStore(state => state.createAgent);
+    // Track if we've created the agent to prevent duplicates
+    const hasCreatedAgentRef = useRef(false);
+    const agentConfigRef = useRef(agentConfig);
+    agentConfigRef.current = agentConfig;
+    // Auto-create agent when runtime is ready
+    useEffect(() => {
+        if (autoCreateAgent &&
+            runtime &&
+            status === 'ready' &&
+            !agent &&
+            !hasCreatedAgentRef.current) {
+            hasCreatedAgentRef.current = true;
+            createAgentAction(agentConfigRef.current).catch(err => {
+                console.error('[useAgentRuntime] Failed to auto-create agent:', err);
+                hasCreatedAgentRef.current = false;
+            });
+        }
+    }, [autoCreateAgent, runtime, status, agent, createAgentAction]);
+    // Reset agent creation tracking on disconnect
+    useEffect(() => {
+        if (status === 'disconnected' || status === 'idle') {
+            hasCreatedAgentRef.current = false;
+        }
+    }, [status]);
+    // Memoized create agent function
+    const createAgent = useCallback((config) => createAgentAction(config || agentConfig), [createAgentAction, agentConfig]);
+    // Derived state
+    const isReady = status === 'ready' && !!agent?.isReady;
+    const endpoint = agent?.endpoint || null;
+    const serviceManager = runtime?.serviceManager || null;
+    return {
+        runtime,
+        agent,
+        status,
+        error,
+        isLaunching,
+        isReady,
+        endpoint,
+        serviceManager,
+        launchRuntime,
+        connectToRuntime,
+        createAgent,
+        disconnect,
+    };
+}

package/lib/test-setup.d.ts

@@ -1 +1 @@
-export {};
+import '@testing-library/jest-dom/vitest';

package/lib/test-setup.js

@@ -4,6 +4,7 @@
  */
 // Test setup for unit tests
 // Add any global test configuration here
+import '@testing-library/jest-dom/vitest';
 // Define webpack globals that are expected by some dependencies
 global.__webpack_public_path__ = '';
 // Native FormData and fetch should work in Node.js 20+