@datalayer/agent-runtimes 1.0.1 → 1.0.3

package/lib/{components/chat/store → stores}/conversationStore.js

@@ -3,15 +3,15 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * Zustand store for conversation history per runtime/agent space.
+ * Zustand store for conversation history per agent runtime.
  * Stores messages per runtime ID in memory during the session.
  *
  * Key features:
- * - Messages are stored per runtime ID (agent space) in memory
+ * - Messages are stored per runtime ID in memory
  * - On page reload, messages are fetched from the server API
  * - No browser storage persistence - server is the source of truth
  *
- * @module components/chat/store/conversationStore
+ * @module store/conversationStore
  */
 import { create } from 'zustand';
 import { devtools, subscribeWithSelector } from 'zustand/middleware';

package/lib/{components/chat/store → stores}/index.d.ts

@@ -1,7 +1,8 @@
 /**
- * Store exports for chat component.
+ * Store exports for agent runtime and chat.
  *
- * @module components/chat/store
+ * @module store
  */
+export { useAgentStore, useAgentRuntime, useAgentFromStore, useAgentStatus, useAgentError, useIsLaunching, getAgentState, subscribeToAgent, agentStore, type AgentRegistryEntry, type agentsStoreState, type agentsStoreActions, type agentsStore, type AgentRegistryState, type AgentState, } from './agentsStore';
 export { useChatStore, useChatMessages, useChatLoading, useChatStreaming, useChatError, useChatTools, useChatOpen, useChatConfig, useChatReady, useChatInferenceProvider, useChatExtensionRegistry, defaultChatConfig, type ChatStore, type ChatState, type ChatActions, type ChatConfig, type ToolCallState, } from './chatStore';
 export { useConversationStore, useConversationMessages, useNeedsFetch, useIsFetching, type ConversationStore, type ConversationData, } from './conversationStore';

package/lib/{components/chat/store → stores}/index.js

@@ -3,9 +3,10 @@
  * Distributed under the terms of the Modified BSD License.
  */
 /**
- * Store exports for chat component.
+ * Store exports for agent runtime and chat.
  *
- * @module components/chat/store
+ * @module store
  */
+export { useAgentStore, useAgentRuntime, useAgentFromStore, useAgentStatus, useAgentError, useIsLaunching, getAgentState, subscribeToAgent, agentStore, } from './agentsStore';
 export { useChatStore, useChatMessages, useChatLoading, useChatStreaming, useChatError, useChatTools, useChatOpen, useChatConfig, useChatReady, useChatInferenceProvider, useChatExtensionRegistry, defaultChatConfig, } from './chatStore';
 export { useConversationStore, useConversationMessages, useNeedsFetch, useIsFetching, } from './conversationStore';

package/lib/{components/chat/tools → tools}/ToolExecutor.d.ts

@@ -2,9 +2,9 @@
  * Tool executor for hybrid tool execution (frontend + backend).
  * Handles routing tool calls to appropriate execution location.
  *
- * @module components/chat/tools/ToolExecutor
+ * @module chat/tools/ToolExecutor
  */
-import type { ToolDefinition, FrontendToolDefinition, ToolCallRequest, ToolExecutionResult, ToolRenderStatus } from '../types/tool';
+import type { ToolDefinition, FrontendToolDefinition, ToolCallRequest, ToolExecutionResult, ToolRenderStatus } from '../types/tools';
 import type { InferenceProvider } from '../types/inference';
 /**
  * Execution context for tool calls

package/lib/{components/chat/tools → tools}/ToolExecutor.js

@@ -2,7 +2,7 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import { hasHitlRender } from '../types/tool';
+import { hasHitlRender } from '../types/tools';
 /**
  * Tool executor handles routing and executing tool calls
  */

package/lib/tools/adapters/agent-runtimes/AgentRuntimesToolAdapter.d.ts

@@ -8,7 +8,7 @@
  * @module tools/adapters/agent-runtimes/AgentRuntimesToolAdapter
  */
 import type { ToolDefinition, ToolOperation, ToolExecutionContext } from '@datalayer/jupyter-react';
-import type { FrontendToolDefinition } from '../../../components/chat/types/tool';
+import type { FrontendToolDefinition } from '../../../types/tools';
 /**
  * Converts unified tool definition to FrontendToolDefinition format
  *

package/lib/tools/adapters/agent-runtimes/lexicalHooks.d.ts

@@ -1,14 +1,20 @@
-/**
- * React hooks for agent-runtimes lexical tool registration.
- * Provides: useLexicalTools hook for ChatFloating integration.
- *
- * @module tools/adapters/agent-runtimes/lexicalHooks
- */
 import type { ToolExecutionContext } from '@datalayer/jupyter-react';
-import type { FrontendToolDefinition } from '../../../components/chat/types/tool';
+import type { FrontendToolDefinition } from '../../../types/tools';
 /**
  * Hook that creates agent-runtimes tools for lexical operations.
- * Returns stable tools array that won't cause re-renders.
+ * Returns a **stable** tools array — only recreated when documentId changes.
+ *
+ * IMPORTANT: Uses `lexicalStore.getState()` (a plain snapshot) instead of the
+ * reactive `useLexicalStore()` hook.  The reactive hook subscribes to every
+ * Zustand state change (block insertions, cursor moves, etc.), which would
+ * cause this hook — and therefore the parent component — to re-render on
+ * every editor mutation.  That re-render creates a new tools array, which
+ * previously caused `LexicalToolsPlugin` → `handleToolsReady` → `toolsKey++`
+ * → ChatFloating remount → `isLoading` reset.
+ *
+ * The notebook hook (`useNotebookTools`) already uses this stable pattern
+ * via `notebookStore.getState()` and `useMemo`, which is why the notebook
+ * example never had this bug.
  *
  * @param documentId - Document ID (lexical document identifier)
  * @param contextOverrides - Optional context overrides (format, extras, etc.)
@@ -16,10 +22,8 @@ import type { FrontendToolDefinition } from '../../../components/chat/types/tool
  *
  * @example
  * ```typescript
- * // Default context (toon format for AI)
  * const frontendTools = useLexicalTools("doc-123");
  *
- * // Use with ChatFloating
  * <ChatFloating
  *   endpoint="http://localhost:8765/api/v1/ag-ui/agent/"
  *   frontendTools={frontendTools}

package/lib/tools/adapters/agent-runtimes/lexicalHooks.js

@@ -2,11 +2,30 @@
  * Copyright (c) 2025-2026 Datalayer, Inc.
  * Distributed under the terms of the Modified BSD License.
  */
-import { useLexicalStore, DefaultExecutor as LexicalDefaultExecutor, lexicalToolDefinitions, lexicalToolOperations, } from '@datalayer/jupyter-lexical';
+/**
+ * React hooks for agent-runtimes lexical tool registration.
+ * Provides: useLexicalTools hook for ChatFloating integration.
+ *
+ * @module tools/adapters/agent-runtimes/lexicalHooks
+ */
+import { useMemo } from 'react';
+import { lexicalStore, DefaultExecutor as LexicalDefaultExecutor, lexicalToolDefinitions, lexicalToolOperations, } from '@datalayer/jupyter-lexical';
 import { createAllAgentRuntimesTools } from './AgentRuntimesToolAdapter';
 /**
  * Hook that creates agent-runtimes tools for lexical operations.
- * Returns stable tools array that won't cause re-renders.
+ * Returns a **stable** tools array — only recreated when documentId changes.
+ *
+ * IMPORTANT: Uses `lexicalStore.getState()` (a plain snapshot) instead of the
+ * reactive `useLexicalStore()` hook.  The reactive hook subscribes to every
+ * Zustand state change (block insertions, cursor moves, etc.), which would
+ * cause this hook — and therefore the parent component — to re-render on
+ * every editor mutation.  That re-render creates a new tools array, which
+ * previously caused `LexicalToolsPlugin` → `handleToolsReady` → `toolsKey++`
+ * → ChatFloating remount → `isLoading` reset.
+ *
+ * The notebook hook (`useNotebookTools`) already uses this stable pattern
+ * via `notebookStore.getState()` and `useMemo`, which is why the notebook
+ * example never had this bug.
  *
  * @param documentId - Document ID (lexical document identifier)
  * @param contextOverrides - Optional context overrides (format, extras, etc.)
@@ -14,10 +33,8 @@ import { createAllAgentRuntimesTools } from './AgentRuntimesToolAdapter';
  *
  * @example
  * ```typescript
- * // Default context (toon format for AI)
  * const frontendTools = useLexicalTools("doc-123");
  *
- * // Use with ChatFloating
  * <ChatFloating
  *   endpoint="http://localhost:8765/api/v1/ag-ui/agent/"
  *   frontendTools={frontendTools}
@@ -25,25 +42,18 @@ import { createAllAgentRuntimesTools } from './AgentRuntimesToolAdapter';
  * ```
  */
 export function useLexicalTools(documentId, contextOverrides) {
-    console.log('[useLexicalTools] 🎣 Hook called with documentId:', documentId);
-    // Get fresh store state every render - NO MEMOIZATION
-    // This ensures we always use the latest patched methods after hot reload
-    const lexicalStoreState = useLexicalStore();
-    console.log('[useLexicalTools] 📦 Store state obtained:', !!lexicalStoreState);
-    // Create new executor every render - NO MEMOIZATION
-    console.log('[useLexicalTools] 🔧 Creating new executor for documentId:', documentId);
-    const executor = new LexicalDefaultExecutor(documentId, lexicalStoreState);
-    // Create new context every render - NO MEMOIZATION
-    console.log('[useLexicalTools] 📝 Creating context');
-    const context = {
+    // Create DefaultExecutor — stable reference, only recreate when documentId changes.
+    // lexicalStore is a module-level Zustand store singleton; getState() returns
+    // the current state snapshot.  The executor's methods access store methods
+    // which internally read the latest state, so we don't need reactivity here.
+    const executor = useMemo(() => new LexicalDefaultExecutor(documentId, lexicalStore.getState()), [documentId]);
+    // Create stable context object with useMemo
+    const context = useMemo(() => ({
         documentId,
         executor,
         format: 'toon',
         ...contextOverrides,
-    };
-    // Create new tools array every render - NO MEMOIZATION
-    console.log('[useLexicalTools] 🛠️ Creating tools array');
-    const tools = createAllAgentRuntimesTools(lexicalToolDefinitions, lexicalToolOperations, context);
-    console.log('[useLexicalTools] ✅ Created', tools.length, 'tools');
-    return tools;
+    }), [documentId, executor, contextOverrides]);
+    // Create and return tools (stable reference)
+    return useMemo(() => createAllAgentRuntimesTools(lexicalToolDefinitions, lexicalToolOperations, context), [context]);
 }

package/lib/tools/adapters/agent-runtimes/notebookHooks.d.ts

@@ -1,5 +1,5 @@
 import type { ToolExecutionContext } from '@datalayer/jupyter-react';
-import type { FrontendToolDefinition } from '../../../components/chat/types/tool';
+import type { FrontendToolDefinition } from '../../../types/tools';
 /**
  * Hook that creates agent-runtimes tools for notebook operations.
  * Returns stable tools array that won't cause re-renders.

package/lib/tools/index.d.ts

@@ -4,3 +4,6 @@
  * @module tools
  */
 export * from './adapters/copilotkit';
+export { ToolExecutor, createToolExecutor, type ToolExecutionContext, } from './ToolExecutor';
+export type { ToolDefinition, FrontendToolDefinition, BackendToolDefinition, ToolLocation, ToolParameter, ToolRenderStatus, ToolRenderProps, ToolRenderAndWaitProps, ToolCallRequest, ToolExecutionResult, ToolRegistryEntry, } from '../types/tools';
+export { isFrontendTool, isBackendTool, hasHitlRender } from '../types/tools';

package/lib/tools/index.js

@@ -9,10 +9,6 @@
  */
 // Export adapters
 export * from './adapters/copilotkit';
-// TODO: Re-export tool types from jupyter-react when available
-// export type {
-//   ToolDefinition,
-//   ToolConfig,
-//   ToolOperation,
-//   ToolExecutionContext,
-// } from '@datalayer/jupyter-react';
+// Tool executor
+export { ToolExecutor, createToolExecutor, } from './ToolExecutor';
+export { isFrontendTool, isBackendTool, hasHitlRender } from '../types/tools';

package/lib/types/a2a.d.ts

@@ -0,0 +1,39 @@
+import { ChatMessage } from './messages';
+/**
+ * Agent card for A2A protocol
+ */
+export interface AgentCard {
+    name: string;
+    description?: string;
+    url: string;
+    version?: string;
+    capabilities?: {
+        streaming?: boolean;
+        extensions?: string[];
+    };
+    skills?: Array<{
+        id: string;
+        name: string;
+        description?: string;
+        examples?: string[];
+    }>;
+}
+/**
+ * A2A specific types
+ */
+export declare namespace A2A {
+    interface Task {
+        id: string;
+        status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled';
+        messages: ChatMessage[];
+        result?: unknown;
+    }
+    interface Message {
+        role: string;
+        parts: Array<{
+            type: string;
+            text?: string;
+            data?: unknown;
+        }>;
+    }
+}

package/lib/types/acp.d.ts

@@ -0,0 +1,21 @@
+/**
+ * ACP specific types (WebSocket-based)
+ */
+export declare namespace ACP {
+    interface JsonRpcRequest {
+        jsonrpc: '2.0';
+        method: string;
+        params?: unknown;
+        id: string | number;
+    }
+    interface JsonRpcResponse {
+        jsonrpc: '2.0';
+        result?: unknown;
+        error?: {
+            code: number;
+            message: string;
+            data?: unknown;
+        };
+        id: string | number;
+    }
+}

package/lib/types/ag-ui.d.ts

@@ -0,0 +1,25 @@
+import { ChatMessage } from './messages';
+import { ToolDefinition } from './tools';
+/**
+ * AG-UI specific types
+ */
+export declare namespace AGUI {
+    interface RunAgentInput {
+        threadId: string;
+        runId: string;
+        messages: ChatMessage[];
+        state: Record<string, unknown> | null;
+        tools: ToolDefinition[];
+        context: Array<{
+            type: string;
+            content: string;
+        }>;
+        forwardedProps: Record<string, unknown> | null;
+        /** Optional model override for per-request model selection */
+        model?: string;
+    }
+    interface Event {
+        type: string;
+        data?: unknown;
+    }
+}

package/lib/types/agents-lifecycle.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Types for agent lifecycle management — runtime creation/connection
+ * and the local pause/resume UI state store.
+ *
+ * @module types/agents-lifecycle
+ */
+import type { AgentRuntimeData } from './agents';
+/** Request payload for creating a new agent runtime. */
+export type CreateAgentRuntimeRequest = {
+    environmentName?: string;
+    givenName?: string;
+    creditsLimit?: number;
+    type?: string;
+    /** 'none', 'notebook', or 'document' */
+    editorVariant?: string;
+    enableCodemode?: boolean;
+    /** ID of the agent spec used to create this runtime */
+    agentSpecId?: string;
+    /** Full agent spec payload to propagate to backend services */
+    agentSpec?: Record<string, any>;
+};
+export type CreateRuntimeApiResponse = {
+    success?: boolean;
+    runtime?: AgentRuntimeData;
+};
+export type AgentLifecycleRecord = {
+    resumePending: boolean;
+    pauseLockedForResumed: boolean;
+};
+export type AgentLifecycleState = {
+    byRuntimeKey: Record<string, AgentLifecycleRecord>;
+    markResumePending: (runtimeKey: string) => void;
+    markResumeFailed: (runtimeKey: string) => void;
+    markResumeSettled: (runtimeKey: string) => void;
+    clearRuntimeLifecycle: (runtimeKey: string) => void;
+};

package/lib/types/agents.d.ts

@@ -0,0 +1,80 @@
+/**
+ * AI Agent model
+ */
+import type { AgentSpec } from './agentspecs';
+import type { AgentConnection } from './connection';
+export type AgentLibrary = 'pydantic-ai' | 'langchain' | 'google-adk';
+/**
+ * Unified agent status covering runtime lifecycle and UI lifecycle.
+ */
+export type AgentStatus = 'idle' | 'initializing' | 'launching' | 'connecting' | 'starting' | 'ready' | 'running' | 'paused' | 'pausing' | 'resumed' | 'resuming' | 'terminated' | 'archived' | 'error' | 'disconnected';
+/** Shared Primer Label variants for agent statuses. */
+export type AgentStatusColorVariant = 'secondary' | 'attention' | 'success' | 'severe' | 'accent' | 'danger';
+/** Shared Label variants for agent lifecycle statuses. */
+export declare const AGENT_STATUS_COLORS: Record<AgentStatus, AgentStatusColorVariant>;
+/**
+ * Complete state for an agent runtime in the Zustand store.
+ */
+export interface AgentRuntimeState {
+    /** Runtime connection including agent info (null if not connected). */
+    runtime: AgentConnection | null;
+    /** Current status. */
+    status: AgentStatus;
+    /** Error message if any. */
+    error: string | null;
+    /** Whether the runtime is launching. */
+    isLaunching: boolean;
+    /** Whether the agent is ready. */
+    isReady: boolean;
+}
+/**
+ * Agent Runtime data type (mapped from runtimes service).
+ *
+ * Backend RuntimePod fields: pod_name, environment_name, environment_title, uid,
+ * type, given_name, token, ingress, reservation_id, started_at, expired_at, burning_rate.
+ *
+ * We map `ingress` to `url` for consistency with the UI.
+ */
+export type AgentRuntimeData = {
+    pod_name: string;
+    id: string;
+    name: string;
+    environment_name: string;
+    environment_title?: string;
+    given_name: string;
+    type: string;
+    started_at?: string;
+    expired_at?: string;
+    burning_rate?: number;
+    status: AgentStatus;
+    messageCount: number;
+    ingress?: string;
+    url?: string;
+    token?: string;
+    agentSpec?: AgentSpec;
+    agent_spec_id?: string;
+};
+export interface RunningAgent {
+    /** Unique agent ID within the runtime */
+    agentId: string;
+    /** Pod name in Kubernetes */
+    podName: string;
+    /** Agent display name */
+    name: string;
+    /** AgentSpec ID used to create the agent */
+    specId?: string;
+    /** Current agent status */
+    status: AgentStatus;
+    /** Model being used */
+    model: string;
+    /** When the agent was created */
+    createdAt: string;
+    /** Number of completed turns */
+    turnCount: number;
+    /** Total tokens consumed */
+    totalTokens: number;
+    /** Estimated cost in USD */
+    totalCostUsd: number;
+    /** Whether DBOS durability is enabled */
+    durableEnabled: boolean;
+}

package/lib/types/agents.js

@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/** Shared Label variants for agent lifecycle statuses. */
+export const AGENT_STATUS_COLORS = {
+    idle: 'secondary',
+    initializing: 'attention',
+    launching: 'attention',
+    connecting: 'attention',
+    starting: 'attention',
+    ready: 'success',
+    running: 'success',
+    pausing: 'attention',
+    paused: 'severe',
+    resumed: 'accent',
+    resuming: 'accent',
+    terminated: 'danger',
+    archived: 'secondary',
+    error: 'danger',
+    disconnected: 'secondary',
+};

package/lib/types/agentspecs.d.ts

@@ -0,0 +1,90 @@
+import type { SkillSpec } from './skills';
+import type { MCPServer, AgentMCPServerToolConfig } from './mcp';
+import type { ToolSpec, FrontendToolSpec } from './tools';
+import type { AgentTriggerConfig } from './triggers';
+import type { AgentModelConfig } from './models';
+import type { AgentOutputConfig } from './outputs';
+import type { GuardrailSpec } from './guardrails';
+import type { AgentEvalConfig } from './evals';
+import type { AgentNotificationConfig } from './notifications';
+import type { AgentCodemodeConfig, AgentAdvancedConfig } from './config';
+/**
+ * Specification for an AI agent.
+ *
+ * Defines the configuration for a reusable agent template that can be
+ * instantiated as an Agent Runtime.
+ */
+export interface AgentSpec {
+    /** Unique agent identifier */
+    id: string;
+    /** Version */
+    version?: string;
+    /** Display name for the agent */
+    name: string;
+    /** Agent description */
+    description: string;
+    /** System prompt for the agent */
+    systemPrompt?: string;
+    /** System prompt addons when codemode is enabled */
+    systemPromptCodemodeAddons?: string;
+    /** Tags for categorization */
+    tags: string[];
+    /** Whether the agent is enabled */
+    enabled: boolean;
+    /** AI model identifier to use for this agent */
+    model?: string;
+    /** MCP servers used by this agent */
+    mcpServers: MCPServer[];
+    /** Skills available to this agent */
+    skills: SkillSpec[];
+    /** Runtime tools available to this agent */
+    tools?: ToolSpec[];
+    /** Frontend tool sets available to this agent */
+    frontendTools?: FrontendToolSpec[];
+    /** Runtime environment name for this agent */
+    environmentName: string;
+    /** Icon identifier or URL for the agent */
+    icon?: string;
+    /** Emoji identifier for the agent */
+    emoji?: string;
+    /** Theme color for the agent (hex code) */
+    color?: string;
+    /** Chat suggestions to show users what this agent can do */
+    suggestions?: string[];
+    /** Welcome message shown when agent starts */
+    welcomeMessage?: string;
+    /** Path to Jupyter notebook to show on agent creation */
+    welcomeNotebook?: string;
+    /** Path to Lexical document to show on agent creation */
+    welcomeDocument?: string;
+    /** Sandbox variant to use for this agent ('local-eval', 'jupyter', 'local-jupyter') */
+    sandboxVariant?: string;
+    /** User-facing objective for the agent */
+    goal?: string;
+    /** Communication protocol (e.g., 'ag-ui', 'acp', 'a2a', 'vercel-ai') */
+    protocol?: string;
+    /** UI extension type (e.g., 'a2ui', 'mcp-apps') */
+    uiExtension?: string;
+    /** Trigger configuration (type, cron, event source, prompt) */
+    trigger?: AgentTriggerConfig;
+    /** Model configuration (temperature, max_tokens) */
+    modelConfig?: AgentModelConfig;
+    /** MCP server tool configurations with approval settings */
+    mcpServerTools?: AgentMCPServerToolConfig[];
+    /** Guardrail configurations */
+    guardrails?: GuardrailSpec[];
+    /** Evaluation configurations */
+    evals?: AgentEvalConfig[];
+    /** Codemode configuration (enabled, token_reduction, speedup) */
+    codemode?: AgentCodemodeConfig;
+    /** Output configuration (type/formats, template) */
+    output?: AgentOutputConfig;
+    /** Advanced settings (cost_limit, time_limit, max_iterations, validation) */
+    advanced?: AgentAdvancedConfig;
+    /** Authorization policy */
+    authorizationPolicy?: string;
+    /** Notification configuration (email, slack) */
+    notifications?: AgentNotificationConfig;
+    /** Memory backend identifier (e.g., 'ephemeral', 'mem0', 'memu', 'simplemem') */
+    memory?: string;
+}