@datalayer/agent-runtimes 1.0.1 → 1.0.3

package/lib/{components/chat/components/base/ChatBase.d.ts → types/chat.d.ts}

@@ -1,10 +1,16 @@
-import React, { type ReactNode } from 'react';
-import { type PoweredByTagProps } from '../elements/PoweredByTag';
-import type { ChatMessage } from '../../types/message';
-import type { TransportType } from '../../types/protocol';
-import type { McpServerSelection } from '../../types/inference';
-import type { FrontendToolDefinition } from '../../types/tool';
-import type { BuiltinTool as BuiltinToolType } from '../../../../types/Types';
+/**
+ * Type definitions for the ChatBase component and its sub-components.
+ *
+ * @module types/chat
+ */
+import type { ReactNode } from 'react';
+import type { ChatMessage, MessageHandler } from './messages';
+import type { Protocol, ProtocolConfig } from './protocol';
+import type { McpServerSelection } from './inference';
+import type { MCPServerTool } from './mcp';
+import type { AgentRuntimeConfig } from './config';
+import type { FrontendToolDefinition } from './tools';
+import type { PoweredByTagProps } from '../chat/display/PoweredByTag';
 /**
  * View mode for the chat component.
  * - 'floating': Full-height floating panel (pinned to the right edge with offset)
@@ -15,20 +21,11 @@ export type ChatViewMode = 'floating' | 'floating-small' | 'sidebar';
 /**
  * Tool call status for tool rendering
  */
-export type ToolCallStatus = 'inProgress' | 'executing' | 'complete' | 'error';
+export type DisplayToolCallStatus = 'inProgress' | 'executing' | 'complete' | 'error';
 /**
  * Response callback type for human-in-the-loop interactions
  */
 export type RespondCallback = (result: unknown) => void;
-/**
- * Suggestion item for quick actions
- */
-export interface Suggestion {
-    /** Display title for the suggestion */
-    title: string;
-    /** Message to send when clicked */
-    message: string;
-}
 /**
  * Tool call render context passed to renderToolResult
  */
@@ -44,7 +41,7 @@ export interface ToolCallRenderContext {
     /** Tool result (only available when status is 'complete') */
     result?: unknown;
     /** Tool call status */
-    status: ToolCallStatus;
+    status: DisplayToolCallStatus;
     /** Error message if status is 'error' */
     error?: string;
     /**
@@ -58,6 +55,42 @@ export interface ToolCallRenderContext {
  * Render function for tool results
  */
 export type RenderToolResult = (context: ToolCallRenderContext) => ReactNode;
+/**
+ * Internal type for tracking tool calls in messages
+ */
+export interface ToolCallMessage {
+    id: string;
+    type: 'tool-call';
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    result?: unknown;
+    status: DisplayToolCallStatus;
+    error?: string;
+    /** Infrastructure/execution error message */
+    executionError?: string;
+    /** Code error details (Python exception) */
+    codeError?: {
+        name: string;
+        value: string;
+        traceback?: string;
+    };
+    /** Exit code when code called sys.exit() */
+    exitCode?: number | null;
+}
+/**
+ * Union type for all displayable items in the chat
+ */
+export type DisplayItem = ChatMessage | ToolCallMessage;
+/**
+ * Suggestion item for quick actions
+ */
+export interface Suggestion {
+    /** Display title for the suggestion */
+    title: string;
+    /** Message to send when clicked */
+    message: string;
+}
 /**
  * Avatar configuration
  */
@@ -107,25 +140,6 @@ export interface EmptyStateConfig {
     /** Custom empty state renderer */
     render?: () => ReactNode;
 }
-/**
- * Streaming options for custom message handler.
- * Enables streaming response support with chunk callbacks.
- */
-export interface StreamingMessageOptions {
-    /** Callback for each chunk of streamed content */
-    onChunk?: (chunk: string) => void;
-    /** Callback when streaming is complete */
-    onComplete?: (fullResponse: string) => void;
-    /** Callback on error */
-    onError?: (error: Error) => void;
-    /** Abort signal for cancellation */
-    signal?: AbortSignal;
-}
-/**
- * Custom message handler type for props-based mode.
- * Supports both simple and streaming response patterns.
- */
-export type MessageHandler = (message: string, messages: ChatMessage[], options?: StreamingMessageOptions) => Promise<string | void>;
 /**
  * Model configuration
  */
@@ -135,19 +149,6 @@ export interface ModelConfig {
     builtinTools?: string[];
     isAvailable?: boolean;
 }
-/**
- * Builtin tool configuration (re-exported from types.ts)
- */
-export type BuiltinTool = BuiltinToolType;
-/**
- * MCP Server Tool configuration
- */
-export interface MCPServerTool {
-    name: string;
-    description: string;
-    enabled: boolean;
-    inputSchema?: Record<string, unknown>;
-}
 /**
  * MCP Server configuration from backend
  */
@@ -166,48 +167,6 @@ export interface MCPServerConfig {
     isConfig?: boolean;
     isRunning?: boolean;
 }
-/**
- * Remote configuration from server
- */
-export interface RemoteConfig {
-    models: ModelConfig[];
-    defaultModel?: string;
-    builtinTools: BuiltinTool[];
-    mcpServers?: MCPServerConfig[];
-}
-/**
- * Protocol configuration for ChatBase
- */
-export interface ProtocolConfig {
-    /** Protocol/transport type */
-    type: TransportType;
-    /** Endpoint URL */
-    endpoint: string;
-    /** Authentication token */
-    authToken?: string;
-    /** Agent ID */
-    agentId?: string;
-    /** Enable config query for models and tools */
-    enableConfigQuery?: boolean;
-    /** Config endpoint URL for non-Jupyter protocols (if not set, uses Jupyter requestAPI) */
-    configEndpoint?: string;
-    /** Additional protocol options */
-    options?: Record<string, unknown>;
-}
-/**
- * Simplified configuration for connecting to an agent runtime server.
- * This is a convenience wrapper over the more detailed ProtocolConfig.
- */
-export interface AgentRuntimeConfig {
-    /** URL of the agent runtime server (e.g., 'http://localhost:8765') */
-    url: string;
-    /** Optional agent ID to connect to */
-    agentId?: string;
-    /** Optional authentication token */
-    authToken?: string;
-    /** Protocol type to use (defaults to 'ag-ui') */
-    protocol?: TransportType;
-}
 /**
  * ChatBase props
  */
@@ -274,8 +233,15 @@ export interface ChatBaseProps {
     /**
      * Protocol configuration for connecting to backend.
      * When provided and useStore is false, enables protocol mode.
+     *
+     * Accepts either a full `ProtocolConfig` object or a simple `Protocol` string
+     * (e.g. `'vercel-ai'`). When a string is provided, it is used as the protocol
+     * type and combined with other props (endpoint, agentRuntimeConfig) to build
+     * the full configuration.
+     *
+     * @default 'vercel-ai'
      */
-    protocol?: ProtocolConfig;
+    protocol?: Protocol | ProtocolConfig;
     /**
      * Simplified agent runtime configuration.
      * A convenience wrapper that creates a ProtocolConfig internally.
@@ -427,7 +393,7 @@ export interface ChatBaseProps {
     /**
      * Runtime ID for conversation persistence.
      * When provided, messages are fetched from the server API on page reload
-     * and prevents message mixing between different agent spaces.
+     * and prevents message mixing between different agent runtimes.
      */
     runtimeId?: string;
     /**
@@ -448,9 +414,3 @@ export interface ChatBaseProps {
      */
     pendingPrompt?: string;
 }
-/**
- * ChatBase component - Universal chat panel supporting store, protocol, and custom modes
- */
-export declare function ChatBase({ title, showHeader, showTokenUsage, showLoadingIndicator, showErrors, showInput, showModelSelector, showToolsMenu, showSkillsMenu, codemodeEnabled, initialModel, availableModels, mcpServers, initialSkills, className, loadingState, headerActions, chatViewMode, onChatViewModeChange, useStore: useStoreMode, protocol: protocolProp, agentRuntimeConfig, onSendMessage, enableStreaming, brandIcon, avatarConfig, headerButtons, showPoweredBy, poweredByProps, emptyState, renderToolResult, footerContent, showInformation, onInformationClick, headerContent, children, borderRadius, backgroundColor, border, boxShadow, compact, placeholder, description, onStateUpdate, onNewChat, onClear, onMessagesChange, autoFocus, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, focusTrigger, frontendTools, onAuthorizationRequired, connectedIdentities, runtimeId, historyEndpoint, historyAuthToken, pendingPrompt, }: ChatBaseProps): import("react/jsx-runtime").JSX.Element;
-export type { PoweredByTagProps };
-export default ChatBase;

package/lib/types/checkpoints.d.ts

@@ -0,0 +1,32 @@
+export type CheckpointMode = 'criu' | 'light';
+/**
+ * A persisted checkpoint record returned from the runtimes API.
+ */
+export interface CheckpointRecord {
+    id: string;
+    name: string;
+    description: string;
+    runtime_uid: string;
+    agent_spec_id: string;
+    agentspec: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    checkpoint_mode?: CheckpointMode;
+    messages?: string[];
+    status: string;
+    status_message?: string;
+    updated_at: string;
+}
+export interface ConversationCheckpoint {
+    /** Unique checkpoint ID */
+    id: string;
+    /** Human-readable label */
+    label: string;
+    /** Turn number when checkpointed */
+    turn: number;
+    /** Number of messages at checkpoint time */
+    messageCount: number;
+    /** When the checkpoint was created */
+    createdAt: string;
+    /** Additional metadata */
+    metadata: Record<string, unknown>;
+}

package/lib/types/checkpoints.js

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

package/lib/types/config.d.ts

@@ -0,0 +1,67 @@
+import { AgentLibrary } from './agents';
+import { MCPServerConfig, ModelConfig } from './chat';
+import type { Protocol } from './protocol';
+import type { AgentValidationConfig } from './execution';
+import { BuiltinTool } from './models';
+/**
+ * Default agent configuration values.
+ */
+export declare const DEFAULT_AGENT_CONFIG: Required<AgentConfig>;
+/**
+ * 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. */
+    model?: string;
+    /** System prompt for the agent. */
+    systemPrompt?: string;
+    /** Agent library (defaults to `pydantic-ai`). */
+    agentLibrary?: AgentLibrary;
+    /** Transport protocol (defaults to `ag-ui`). */
+    protocol?: Protocol;
+}
+/**
+ * Remote configuration from server
+ */
+export interface RemoteConfig {
+    models: ModelConfig[];
+    defaultModel?: string;
+    builtinTools: BuiltinTool[];
+    mcpServers?: MCPServerConfig[];
+}
+/**
+ * Configuration for connecting to an agent runtime.
+ */
+export interface AgentRuntimeConfig {
+    /** URL of the agent runtime server */
+    url: string;
+    /** Optional agent ID to connect to */
+    agentId?: string;
+    /** Optional authentication token */
+    authToken?: string;
+    /** Optional protocol type (defaults handled by consumers) */
+    protocol?: Protocol;
+}
+/**
+ * Codemode configuration for an agent spec.
+ */
+export interface AgentCodemodeConfig {
+    enabled?: boolean;
+    token_reduction?: string;
+    speedup?: string;
+    [key: string]: string | number | boolean | undefined;
+}
+/**
+ * Advanced configuration for an agent spec.
+ */
+export interface AgentAdvancedConfig {
+    cost_limit?: string;
+    time_limit?: string;
+    max_iterations?: number;
+    validation?: AgentValidationConfig | string;
+    [key: string]: unknown;
+}

package/lib/{runtime/types.js → types/config.js}

@@ -8,8 +8,8 @@
 export const DEFAULT_AGENT_CONFIG = {
     name: 'ai-agent',
     description: 'AI Assistant',
-    model: 'anthropic:claude-sonnet-4-5',
+    model: '',
     systemPrompt: 'You are a helpful AI assistant.',
     agentLibrary: 'pydantic-ai',
-    transport: 'ag-ui',
+    protocol: 'vercel-ai',
 };

package/lib/types/connection.d.ts

@@ -0,0 +1,31 @@
+import type { ServiceManager } from '@jupyterlab/services';
+import type { AgentStatus } from './agents';
+/**
+ * Connection state enumeration
+ */
+export type ConnectionState = 'connected' | 'connecting' | 'disconnected' | 'error';
+/**
+ * Information about a connected agent runtime.
+ */
+export interface AgentConnection {
+    /** 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: AgentStatus;
+    /** Kernel ID if connected. */
+    kernelId?: string;
+    /** Agent ID. */
+    agentId?: string;
+    /** Full endpoint URL for the agent. */
+    endpoint?: string;
+    /** Whether the agent is ready to use. */
+    isReady?: boolean;
+}

package/lib/types/connection.js

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

package/lib/types/context.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Context-related type definitions used by chat hooks and usage components.
+ *
+ * @module types/context
+ */
+/**
+ * Distribution child entry for context snapshot pie chart.
+ */
+export interface DistributionChild {
+    name: string;
+    value: number;
+}
+/**
+ * Distribution entry for context snapshot pie chart.
+ */
+export interface Distribution {
+    name: string;
+    value: number;
+    children: DistributionChild[];
+}
+/**
+ * Response from the context-snapshot API.
+ * Contains cumulative token usage tracked by the agent server.
+ */
+export interface ContextSnapshotData {
+    totalTokens: number;
+    contextWindow: number;
+    sumResponseInputTokens: number;
+    sumResponseOutputTokens: number;
+    systemPromptTokens: number;
+    userMessageTokens: number;
+    assistantMessageTokens: number;
+    toolTokens: number;
+    toolCallTokens: number;
+    toolReturnTokens: number;
+    historyToolCallTokens: number;
+    historyToolReturnTokens: number;
+    currentToolCallTokens: number;
+    currentToolReturnTokens: number;
+    distribution?: Distribution;
+    turnUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+        requests: number;
+        toolCalls: number;
+        toolNames: string[];
+        durationSeconds: number;
+    } | null;
+    sessionUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+        requests: number;
+        toolCalls: number;
+        turns: number;
+        durationSeconds: number;
+    } | null;
+    error?: string;
+}
+/**
+ * Sandbox status from the backend.
+ */
+export interface SandboxStatusData {
+    available: boolean;
+    sandbox_running?: boolean;
+    is_executing?: boolean;
+    variant?: string;
+}

package/lib/types/context.js

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

package/lib/types/cost.d.ts

@@ -0,0 +1,42 @@
+export interface ContextUsage {
+    /** Agent ID */
+    agentId: string;
+    /** Current token count in the context window */
+    currentTokens: number;
+    /** Maximum tokens in the context window */
+    maxTokens: number;
+    /** Usage percentage (0-100) */
+    usagePercent: number;
+    /** Number of messages in context */
+    messageCount: number;
+    /** Number of archived/evicted messages */
+    archivedCount: number;
+    /** Number of auto-summarizations performed */
+    summarizationCount: number;
+}
+export interface CostUsage {
+    /** Current run cost in USD */
+    currentRunCostUsd: number;
+    /** Cumulative cost in USD */
+    cumulativeCostUsd: number;
+    /** Budget limit per run (from agentspec) */
+    budgetLimitPerRunUsd: number | null;
+    /** Total budget limit */
+    budgetLimitTotalUsd: number | null;
+    /** Number of model requests */
+    requestCount: number;
+    /** Total tokens used */
+    totalTokensUsed: number;
+    /** Breakdown by model */
+    modelBreakdown: ModelCostBreakdown[];
+}
+export interface ModelCostBreakdown {
+    /** Model name */
+    model: string;
+    /** Requests for this model */
+    requests: number;
+    /** Tokens for this model */
+    tokens: number;
+    /** Cost for this model */
+    costUsd: number;
+}

package/lib/types/cost.js

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

package/lib/types/envvars.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Specification for an environment variable.
+ */
+export interface EnvvarSpec {
+    /** Environment variable identifier */
+    id: string;
+    /** Version */
+    version: string;
+    /** Display name */
+    name: string;
+    /** Description */
+    description: string;
+    /** Registration URL or docs link */
+    registrationUrl?: string;
+    /** Tags for categorization */
+    tags: string[];
+    /** Icon identifier */
+    icon?: string;
+    /** Emoji identifier */
+    emoji?: string;
+}

package/lib/types/envvars.js

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

package/lib/types/evals.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Evaluation benchmark specification.
+ */
+export interface EvalSpec {
+    /** Unique eval identifier */
+    id: string;
+    /** Version */
+    version?: string;
+    /** Display name */
+    name: string;
+    /** Description of the evaluation */
+    description: string;
+    /** Category: Coding, Knowledge, Reasoning, Agentic, or Safety */
+    category: 'Coding' | 'Knowledge' | 'Reasoning' | 'Agentic' | 'Safety';
+    /** Number of tasks in the benchmark */
+    task_count: number;
+    /** Primary metric (e.g., 'pass@1', 'accuracy', 'success_rate') */
+    metric: string;
+    /** Source URL or repository */
+    source: string;
+    /** Difficulty level */
+    difficulty: 'easy' | 'medium' | 'hard' | 'expert';
+    /** Relevant languages */
+    languages: string[];
+}
+/**
+ * Eval configuration for an agent spec.
+ */
+export interface AgentEvalConfig {
+    id?: string;
+    name?: string;
+    description?: string;
+    category?: string;
+    task_count?: number;
+    metric?: string;
+    source?: string;
+    difficulty?: string;
+    languages?: string[];
+    [key: string]: unknown;
+}
+export interface EvalReport {
+    /** Unique eval run ID */
+    evalId: string;
+    /** Agent that was evaluated */
+    agentId: string;
+    /** Total number of test cases */
+    totalCases: number;
+    /** Number of passing cases */
+    passed: number;
+    /** Number of failing cases */
+    failed: number;
+    /** Average score (0-1) if applicable */
+    avgScore: number | null;
+    /** Total eval duration in milliseconds */
+    durationMs: number;
+    /** Path or URL to detailed report */
+    reportPath: string | null;
+}
+export interface RunEvalsRequest {
+    /** The evals config list from the agentspec */
+    evalSpec: Array<Record<string, unknown>>;
+    /** Agent system prompt for synthetic case generation */
+    agentSystemPrompt?: string;
+    /** Tool JSON schemas for grounding */
+    toolSchemas?: Array<Record<string, unknown>>;
+}

package/lib/types/evals.js

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

package/lib/types/events.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Agent event and notification timeline types.
+ *
+ * @module types/events
+ */
+export interface AgentEvent {
+    id: string;
+    agent_id: string;
+    title: string;
+    kind: string;
+    status: string;
+    read: boolean;
+    payload: Record<string, unknown>;
+    metadata: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+export interface CreateAgentEventRequest {
+    agent_id: string;
+    title: string;
+    kind?: string;
+    status?: string;
+    payload?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+export interface UpdateAgentEventRequest {
+    title?: string;
+    kind?: string;
+    status?: string;
+    read?: boolean;
+    payload?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+export interface ListAgentEventsParams {
+    agent_id?: string;
+    kind?: string;
+    status?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface GetAgentEventResponse {
+    success: boolean;
+    event: AgentEvent;
+}
+export interface ListAgentEventsResponse {
+    success: boolean;
+    total: number;
+    events: AgentEvent[];
+}

package/lib/types/events.js

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