@datalayer/agent-runtimes 1.0.2 → 1.0.3

package/README.md

@@ -14,7 +14,7 @@
 [![Netlify Status](https://api.netlify.com/api/v1/badges/f7f9e08a-884f-4f76-b20d-666d5873716c/deploy-status)](https://app.netlify.com/projects/agent-runtimes/deploys)
 [![PyPI - Version](https://img.shields.io/pypi/v/agent-runtimes)](https://pypi.org/project/agent-runtimes)
 
-**Agent Runtimes** is a unified platform for deploying, managing, and interacting with AI agents across multiple protocols and frameworks. It provides both a Python server for hosting agents and React components for seamless integration into web and desktop applications.
+**Agent Runtimes** is a unified library for deploying, managing, and interacting with AI agents across multiple protocols and frameworks. It provides both a Python server for hosting agents and React components for seamless integration into web and desktop applications.
 
 ## What is Agent Runtimes?
 

package/lib/Agent.js

@@ -26,7 +26,7 @@ import { useEffect, useState } from 'react';
 import { Text, Spinner } from '@primer/react';
 import { AlertIcon } from '@primer/octicons-react';
 import { Box, DatalayerThemeProvider, setupPrimerPortals, } from '@datalayer/primer-addons';
-import { Chat } from './components/chat';
+import { Chat } from './chat';
 import { DEFAULT_MODEL } from './specs';
 import '../style/primer-primitives.css';
 setupPrimerPortals();
@@ -116,7 +116,7 @@ export const Agent = () => {
                 }, children: [_jsx(AlertIcon, { size: 48 }), _jsx(Text, { sx: { color: 'danger.fg', fontSize: 2 }, children: "Failed to connect to agent" }), _jsx(Text, { sx: { color: 'fg.muted', fontSize: 1 }, children: error })] }) }));
     }
     // Agent is ready — render the Chat component
-    return (_jsx(DatalayerThemeProvider, { children: _jsx(Chat, { transport: "ag-ui", baseUrl: BASE_URL, agentId: agentId, title: "Agent", placeholder: "Send a message...", description: "Chat with the agent", showHeader: true, height: '100vh', showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, autoFocus: true, runtimeId: agentId, historyEndpoint: `${BASE_URL}/api/v1/history`, suggestions: [
+    return (_jsx(DatalayerThemeProvider, { children: _jsx(Chat, { protocol: "ag-ui", baseUrl: BASE_URL, agentId: agentId, title: "Agent", placeholder: "Send a message...", description: "Chat with the agent", showHeader: true, height: '100vh', showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, autoFocus: true, runtimeId: agentId, historyEndpoint: `${BASE_URL}/api/v1/history`, suggestions: [
                 {
                     title: 'Hello',
                     message: 'Hello, what can you do?',

package/lib/AgentLexical.d.ts

@@ -13,18 +13,7 @@
  *   - jupyterBaseUrl: base URL for the Jupyter server (optional, falls back to jupyter-config-data)
  *   - jupyterToken: token for the Jupyter server (optional, falls back to jupyter-config-data)
  */
-import 'prismjs';
-import 'prismjs/components/prism-clike';
-import 'prismjs/components/prism-javascript';
-import 'prismjs/components/prism-markup';
-import 'prismjs/components/prism-markdown';
-import 'prismjs/components/prism-c';
-import 'prismjs/components/prism-css';
-import 'prismjs/components/prism-objectivec';
-import 'prismjs/components/prism-sql';
-import 'prismjs/components/prism-python';
-import 'prismjs/components/prism-rust';
-import 'prismjs/components/prism-swift';
+import '@datalayer/jupyter-react/lib/css/PrismCss';
 import React from 'react';
 import '@datalayer/jupyter-lexical/style/index.css';
 import './examples/lexical/lexical-theme.css';

package/lib/AgentLexical.js

@@ -18,18 +18,7 @@ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-run
  *   - jupyterBaseUrl: base URL for the Jupyter server (optional, falls back to jupyter-config-data)
  *   - jupyterToken: token for the Jupyter server (optional, falls back to jupyter-config-data)
  */
-import 'prismjs';
-import 'prismjs/components/prism-clike';
-import 'prismjs/components/prism-javascript';
-import 'prismjs/components/prism-markup';
-import 'prismjs/components/prism-markdown';
-import 'prismjs/components/prism-c';
-import 'prismjs/components/prism-css';
-import 'prismjs/components/prism-objectivec';
-import 'prismjs/components/prism-sql';
-import 'prismjs/components/prism-python';
-import 'prismjs/components/prism-rust';
-import 'prismjs/components/prism-swift';
+import '@datalayer/jupyter-react/lib/css/PrismCss';
 import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { $getRoot, $createParagraphNode } from 'lexical';
 import { LexicalComposer } from '@lexical/react/LexicalComposer';
@@ -52,7 +41,7 @@ import { Box, DatalayerThemeProvider, setupPrimerPortals, } from '@datalayer/pri
 import { JupyterReactTheme, loadJupyterConfig, createServerSettings, getJupyterServerUrl, getJupyterServerToken, setJupyterServerUrl, setJupyterServerToken, useJupyter, } from '@datalayer/jupyter-react';
 import { ComponentPickerMenuPlugin, JupyterCellPlugin, JupyterInputOutputPlugin, DraggableBlockPlugin, ImagesPlugin, HorizontalRulePlugin, EquationsPlugin, YouTubePlugin, ExcalidrawPlugin, CollapsiblePlugin, AutoLinkPlugin, AutoEmbedPlugin, LexicalConfigProvider, LexicalStatePlugin, FloatingTextFormatToolbarPlugin, CodeActionMenuPlugin, ListMaxIndentLevelPlugin, TableCellResizerPlugin, TablePlugin, } from '@datalayer/jupyter-lexical';
 import { ServiceManager } from '@jupyterlab/services';
-import { Chat } from './components/chat';
+import { Chat } from './chat';
 import { ChatInlinePlugin } from './lexical/ChatInlinePlugin';
 import { useChatInlineToolbarItems } from './lexical/useChatInlineToolbarItems';
 import { useLexicalTools } from './tools/adapters/agent-runtimes/lexicalHooks';
@@ -187,7 +176,7 @@ const ChatPanel = ({ agentId, tools }) => {
             display: 'flex',
             flexDirection: 'column',
             overflow: 'hidden',
-        }, children: _jsx(Chat, { transport: "ag-ui", baseUrl: BASE_URL, agentId: agentId, title: "Agent Lexical", placeholder: "Ask about the document...", description: "Chat with the agent to manipulate the document", showHeader: true, height: "100vh", showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, frontendTools: tools, autoFocus: true, runtimeId: agentId, historyEndpoint: `${BASE_URL}/api/v1/history`, suggestions: [
+        }, children: _jsx(Chat, { protocol: "ag-ui", baseUrl: BASE_URL, agentId: agentId, title: "Agent Lexical", placeholder: "Ask about the document...", description: "Chat with the agent to manipulate the document", showHeader: true, height: "100vh", showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, frontendTools: tools, autoFocus: true, runtimeId: agentId, historyEndpoint: `${BASE_URL}/api/v1/history`, suggestions: [
                 {
                     title: 'Insert heading',
                     message: 'Insert a heading that says "Welcome"',

package/lib/AgentNotebook.js

@@ -24,10 +24,10 @@ import { AlertIcon } from '@primer/octicons-react';
 import { Box, DatalayerThemeProvider, setupPrimerPortals, } from '@datalayer/primer-addons';
 import { Notebook, JupyterReactTheme, loadJupyterConfig, createServerSettings, getJupyterServerUrl, getJupyterServerToken, setJupyterServerUrl, setJupyterServerToken, } from '@datalayer/jupyter-react';
 import { ServiceManager } from '@jupyterlab/services';
-import { Chat } from './components/chat';
+import { Chat } from './chat';
 import { useNotebookTools } from './tools/adapters/agent-runtimes/notebookHooks';
 import { DEFAULT_MODEL } from './specs';
-import MatplotlibNotebook from './examples/stores/notebooks/Matplotlib.ipynb.json';
+import MatplotlibNotebook from './examples/utils/notebooks/Matplotlib.ipynb.json';
 import '../style/primer-primitives.css';
 setupPrimerPortals();
 const BASE_URL = window.location.origin;
@@ -88,7 +88,7 @@ const ChatPanel = ({ agentId }) => {
             display: 'flex',
             flexDirection: 'column',
             overflow: 'hidden',
-        }, children: _jsx(Chat, { transport: "ag-ui", baseUrl: BASE_URL, agentId: agentId, title: "Agent Notebook", placeholder: "Ask about the notebook...", description: "Chat with the agent to manipulate the notebook", showHeader: true, height: "100vh", showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, frontendTools: notebookTools, autoFocus: true, runtimeId: agentId, historyEndpoint: `${BASE_URL}/api/v1/history`, suggestions: [
+        }, children: _jsx(Chat, { protocol: "ag-ui", baseUrl: BASE_URL, agentId: agentId, title: "Agent Notebook", placeholder: "Ask about the notebook...", description: "Chat with the agent to manipulate the notebook", showHeader: true, height: "100vh", showModelSelector: true, showToolsMenu: true, showSkillsMenu: true, showTokenUsage: true, showInformation: true, frontendTools: notebookTools, autoFocus: true, runtimeId: agentId, historyEndpoint: `${BASE_URL}/api/v1/history`, suggestions: [
                 {
                     title: 'Add a cell',
                     message: 'Insert a new code cell into the notebook',

package/lib/App.js

@@ -4,8 +4,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * Distributed under the terms of the Modified BSD License.
  */
 import { useJupyter, JupyterReactTheme } from '@datalayer/jupyter-react';
-import { JupyterCellExample } from './examples/JupyterCellExample';
-import { JupyterNotebookExample } from './examples/JupyterNotebookExample';
+import { JupyterCellExample } from './examples/CellSimpleExample';
+import { JupyterNotebookExample } from './examples/NotebookSimpleExample';
 import './App.css';
 export function App() {
     const { serviceManager } = useJupyter({

package/lib/{components/chat/components → agents}/AgentDetails.d.ts

@@ -1,7 +1,16 @@
-import type { OAuthProvider, OAuthProviderConfig, Identity } from '../../../identity';
+/**
+ * AgentDetails component - Shows detailed information about the agent
+ * including name, protocol, URL, message count, and context details.
+ */
+import type { ReactNode } from 'react';
+import type { OAuthProvider, OAuthProviderConfig, Identity } from '../identity';
 export interface AgentDetailsProps {
     /** Agent name/title */
     name?: string;
+    /** Custom icon node (e.g. an Octicon component) shown instead of the default icon */
+    icon?: ReactNode;
+    /** Emoji from the agent spec (displayed instead of the default icon) */
+    emoji?: string;
     /** Protocol being used */
     protocol: string;
     /** Endpoint URL */
@@ -28,9 +37,11 @@ export interface AgentDetailsProps {
     onBack: () => void;
     /** Whether to show the header with back button (default: true) */
     showBackHeader?: boolean;
+    /** Whether to show context usage/history and context snapshot sections (default: true) */
+    showUsage?: boolean;
 }
 /**
  * AgentDetails component displays comprehensive information about the agent.
  */
-export declare function AgentDetails({ name, protocol, url, messageCount, agentId, apiBase, identityProviders, onIdentityConnect, onIdentityDisconnect, onBack, showBackHeader, }: AgentDetailsProps): import("react/jsx-runtime").JSX.Element;
+export declare function AgentDetails({ name, icon, emoji, protocol, url, messageCount, agentId, apiBase, identityProviders, onIdentityConnect, onIdentityDisconnect, onBack, showBackHeader, showUsage, }: AgentDetailsProps): import("react/jsx-runtime").JSX.Element;
 export default AgentDetails;

package/lib/{components/chat/components → agents}/AgentDetails.js

@@ -1,18 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-// Copyright (c) 2025-2026 Datalayer, Inc.
-// Distributed under the terms of the Modified BSD License.
-/**
- * AgentDetails component - Shows detailed information about the agent
- * including name, protocol, URL, message count, and context details.
- */
 import { ArrowLeftIcon, CheckCircleIcon, XCircleIcon, CodeIcon, BriefcaseIcon, DownloadIcon, NoteIcon, ServerIcon, } from '@primer/octicons-react';
 import { Button, Heading, IconButton, Text, Label, Spinner, ToggleSwitch, } from '@primer/react';
 import { Box } from '@datalayer/primer-addons';
 import { AiAgentIcon } from '@datalayer/icons-react';
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
-import { ContextPanel } from './ContextPanel';
-import { ContextInspector } from './ContextInspector';
-import { AgentIdentity } from './AgentIdentity';
+import { ContextPanel } from '../context/ContextPanel';
+import { ContextInspector, } from '../context/ContextInspector';
+import { AgentIdentity } from '../identity/AgentIdentity';
 /**
  * Get the API base URL for fetching data.
  * If apiBase prop is provided, use it.
@@ -171,7 +165,7 @@ async function downloadContextSnapshotAsCSV(agentId, apiBase) {
 /**
  * AgentDetails component displays comprehensive information about the agent.
  */
-export function AgentDetails({ name = 'AI Agent', protocol, url, messageCount, agentId, apiBase, identityProviders, onIdentityConnect, onIdentityDisconnect, onBack, showBackHeader = true, }) {
+export function AgentDetails({ name = 'AI Agent', icon, emoji, protocol, url, messageCount, agentId, apiBase, identityProviders, onIdentityConnect, onIdentityDisconnect, onBack, showBackHeader = true, showUsage = true, }) {
     const queryClient = useQueryClient();
     // Fetch MCP toolsets status
     const { data: mcpStatus, isLoading: mcpLoading } = useQuery({
@@ -259,7 +253,7 @@ export function AgentDetails({ name = 'AI Agent', protocol, url, messageCount, a
                                     p: 2,
                                     bg: 'accent.subtle',
                                     borderRadius: 2,
-                                }, children: _jsx(AiAgentIcon, { colored: true, size: 32 }) }), _jsxs(Box, { sx: { flex: 1 }, children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, fontWeight: 'semibold', mb: 1 }, children: name }), agentId && (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: ["ID: ", agentId] }))] })] }), _jsxs(Box, { children: [_jsx(Heading, { as: "h4", sx: {
+                                }, children: icon ? (_jsx(Box, { sx: { display: 'inline-flex', color: 'accent.fg' }, children: icon })) : emoji ? (_jsx(Text, { sx: { fontSize: 5, lineHeight: 1 }, children: emoji })) : (_jsx(AiAgentIcon, { colored: true, size: 32 })) }), _jsxs(Box, { sx: { flex: 1 }, children: [_jsx(Heading, { as: "h3", sx: { fontSize: 2, fontWeight: 'semibold', mb: 1 }, children: name }), agentId && (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: ["ID: ", agentId] }))] })] }), _jsxs(Box, { children: [_jsx(Heading, { as: "h4", sx: {
                                     fontSize: 1,
                                     fontWeight: 'semibold',
                                     mb: 2,
@@ -579,7 +573,7 @@ export function AgentDetails({ name = 'AI Agent', protocol, url, messageCount, a
                                                         gap: 1,
                                                         flexWrap: 'wrap',
                                                         mt: 1,
-                                                    }, children: codemodeStatus.available_skills.map(skill => (_jsx(Label, { variant: "secondary", size: "small", children: skill.name }, skill.name))) })] })), codemodeStatus.available_skills.length === 0 && (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "No skills available. Add skills to the skills/ directory." }))] })) : (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Failed to load Codemode status" })) })] }), agentId && (_jsx(ContextPanel, { agentId: agentId, apiBase: apiBase, messageCount: messageCount, chartHeight: "200px" })), agentId && (_jsxs(Box, { sx: { mt: 3 }, children: [_jsxs(Box, { sx: {
+                                                    }, children: codemodeStatus.available_skills.map(skill => (_jsx(Label, { variant: "secondary", size: "small", children: skill.name }, skill.name))) })] })), codemodeStatus.available_skills.length === 0 && (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: "No skills available. Add skills to the skills/ directory." }))] })) : (_jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Failed to load Codemode status" })) })] }), showUsage && agentId && (_jsx(ContextPanel, { agentId: agentId, apiBase: apiBase, messageCount: messageCount, chartHeight: "200px" })), showUsage && agentId && (_jsxs(Box, { sx: { mt: 3 }, children: [_jsxs(Box, { sx: {
                                     display: 'flex',
                                     alignItems: 'center',
                                     justifyContent: 'space-between',

package/lib/api/agents.d.ts

@@ -0,0 +1,47 @@
+import type { RunningAgent, AgentUsageSummary, ConversationCheckpoint } from '../types';
+/**
+ * List all running agents across runtimes.
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the AI Agents API
+ * @returns Promise resolving to list of running agents
+ */
+export declare const getRunningAgents: (token: string, baseUrl?: string) => Promise<RunningAgent[]>;
+/**
+ * Get detailed status for a specific agent.
+ * @param token - Authentication token
+ * @param podName - Pod name hosting the agent
+ * @param agentId - Agent ID within the pod (optional, defaults to primary)
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to agent status
+ */
+export declare const getAgentStatus: (token: string, podName: string, agentId?: string, baseUrl?: string) => Promise<RunningAgent>;
+/**
+ * Pause a running agent (light checkpoint by default, CRIU optional).
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param baseUrl - Base URL
+ */
+export declare const pauseAgent: (token: string, podName: string, baseUrl?: string) => Promise<void>;
+/**
+ * Resume a paused/checkpointed agent.
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param baseUrl - Base URL
+ */
+export declare const resumeAgent: (token: string, podName: string, baseUrl?: string) => Promise<void>;
+/**
+ * Get conversation checkpoints for an agent.
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ */
+export declare const getAgentCheckpoints: (token: string, podName: string, agentId?: string, baseUrl?: string) => Promise<ConversationCheckpoint[]>;
+/**
+ * Get usage summary for an agent.
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ */
+export declare const getAgentUsage: (token: string, podName: string, agentId?: string, baseUrl?: string) => Promise<AgentUsageSummary>;

package/lib/api/agents.js

@@ -0,0 +1,106 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Running agents API functions.
+ *
+ * Provides functions for listing, inspecting, pausing, and resuming
+ * durable agents across runtimes.
+ *
+ * @module api/agents
+ */
+import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
+import { validateToken } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * List all running agents across runtimes.
+ * @param token - Authentication token
+ * @param baseUrl - Base URL for the AI Agents API
+ * @returns Promise resolving to list of running agents
+ */
+export const getRunningAgents = async (token, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Get detailed status for a specific agent.
+ * @param token - Authentication token
+ * @param podName - Pod name hosting the agent
+ * @param agentId - Agent ID within the pod (optional, defaults to primary)
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to agent status
+ */
+export const getAgentStatus = async (token, podName, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    const query = agentId ? `?agent_id=${encodeURIComponent(agentId)}` : '';
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}${query}`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Pause a running agent (light checkpoint by default, CRIU optional).
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param baseUrl - Base URL
+ */
+export const pauseAgent = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}/pause`,
+        method: 'POST',
+        token,
+    });
+};
+/**
+ * Resume a paused/checkpointed agent.
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param baseUrl - Base URL
+ */
+export const resumeAgent = async (token, podName, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}/resume`,
+        method: 'POST',
+        token,
+    });
+};
+/**
+ * Get conversation checkpoints for an agent.
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ */
+export const getAgentCheckpoints = async (token, podName, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    const query = agentId ? `?agent_id=${encodeURIComponent(agentId)}` : '';
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}/checkpoints${query}`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Get usage summary for an agent.
+ * @param token - Authentication token
+ * @param podName - Pod name
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ */
+export const getAgentUsage = async (token, podName, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    const query = agentId ? `?agent_id=${encodeURIComponent(agentId)}` : '';
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(podName)}/usage${query}`,
+        method: 'GET',
+        token,
+    });
+};

package/lib/api/context.d.ts

@@ -0,0 +1,17 @@
+import type { ContextUsage, CostUsage } from '../types';
+/**
+ * Get current context window usage for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to context usage data
+ */
+export declare const getContextUsage: (token: string, agentId: string, baseUrl?: string) => Promise<ContextUsage>;
+/**
+ * Get cost/usage tracking data for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to cost usage data
+ */
+export declare const getCostUsage: (token: string, agentId: string, baseUrl?: string) => Promise<CostUsage>;

package/lib/api/context.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Context usage API functions.
+ *
+ * Provides functions for retrieving real-time context window
+ * usage and cost tracking data for agents.
+ *
+ * @module api/context
+ */
+import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
+import { validateToken } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * Get current context window usage for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to context usage data
+ */
+export const getContextUsage = async (token, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(agentId)}/context-usage`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Get cost/usage tracking data for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to cost usage data
+ */
+export const getCostUsage = async (token, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(agentId)}/cost-usage`,
+        method: 'GET',
+        token,
+    });
+};

package/lib/api/evals.d.ts

@@ -0,0 +1,27 @@
+import type { EvalReport, RunEvalsRequest } from '../types';
+/**
+ * Trigger an evaluation run for the specified agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param request - Eval run request body
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to the eval report
+ */
+export declare const runEvals: (token: string, agentId: string, request: RunEvalsRequest, baseUrl?: string) => Promise<EvalReport>;
+/**
+ * List past evaluation runs for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to list of eval reports
+ */
+export declare const listEvals: (token: string, agentId: string, baseUrl?: string) => Promise<EvalReport[]>;
+/**
+ * Get a specific evaluation report.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param evalId - Eval run ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to the eval report
+ */
+export declare const getEval: (token: string, agentId: string, evalId: string, baseUrl?: string) => Promise<EvalReport>;

package/lib/api/evals.js

@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Evaluation runs API functions.
+ *
+ * Provides functions for triggering, listing, and retrieving
+ * evaluation reports for agents.
+ *
+ * @module api/evals
+ */
+import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
+import { validateToken } from '@datalayer/core/lib/api/utils/validation';
+/**
+ * Trigger an evaluation run for the specified agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param request - Eval run request body
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to the eval report
+ */
+export const runEvals = async (token, agentId, request, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(agentId)}/evals/run`,
+        method: 'POST',
+        token,
+        body: request,
+    });
+};
+/**
+ * List past evaluation runs for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to list of eval reports
+ */
+export const listEvals = async (token, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(agentId)}/evals`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Get a specific evaluation report.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param evalId - Eval run ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to the eval report
+ */
+export const getEval = async (token, agentId, evalId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(agentId)}/evals/${encodeURIComponent(evalId)}`,
+        method: 'GET',
+        token,
+    });
+};

package/lib/api/events.d.ts

@@ -0,0 +1,17 @@
+import type { AgentEvent, CreateAgentEventRequest, GetAgentEventResponse, ListAgentEventsParams, ListAgentEventsResponse, UpdateAgentEventRequest } from '../types';
+export declare const createEvent: (token: string, data: CreateAgentEventRequest, baseUrl?: string) => Promise<{
+    success: boolean;
+    event: AgentEvent;
+}>;
+export declare const listEvents: (token: string, agentId: string, params?: Omit<ListAgentEventsParams, "agent_id">, baseUrl?: string) => Promise<ListAgentEventsResponse>;
+export declare const getEvent: (token: string, agentId: string, eventId: string, baseUrl?: string) => Promise<GetAgentEventResponse>;
+export declare const updateEvent: (token: string, agentId: string, eventId: string, data: UpdateAgentEventRequest, baseUrl?: string) => Promise<GetAgentEventResponse>;
+export declare const deleteEvent: (token: string, agentId: string, eventId: string, baseUrl?: string) => Promise<{
+    success: boolean;
+}>;
+export declare const markEventRead: (token: string, agentId: string, eventId: string, baseUrl?: string) => Promise<GetAgentEventResponse>;
+export declare const markEventUnread: (token: string, agentId: string, eventId: string, baseUrl?: string) => Promise<GetAgentEventResponse>;
+/**
+ * List events across all agents for the authenticated user.
+ */
+export declare const listAllEvents: (token: string, params?: Omit<ListAgentEventsParams, "agent_id">, baseUrl?: string) => Promise<ListAgentEventsResponse>;

package/lib/api/events.js

@@ -0,0 +1,93 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Agent events API functions.
+ *
+ * Provides CRUD operations for agent event records.
+ *
+ * @module api/events
+ */
+import { requestDatalayerAPI } from '@datalayer/core/lib/api/DatalayerApi';
+import { API_BASE_PATHS, DEFAULT_SERVICE_URLS, } from '@datalayer/core/lib/api/constants';
+import { validateToken, validateRequiredString, } from '@datalayer/core/lib/api/utils/validation';
+const toQueryString = (params) => {
+    const searchParams = new URLSearchParams();
+    Object.entries(params).forEach(([k, v]) => {
+        if (v !== undefined && v !== null && v !== '') {
+            searchParams.append(k, String(v));
+        }
+    });
+    const query = searchParams.toString();
+    return query ? `?${query}` : '';
+};
+const agentEventsPath = (agentId) => `${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(agentId)}/events`;
+export const createEvent = async (token, data, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    validateRequiredString(data.agent_id, 'agent_id');
+    validateRequiredString(data.title, 'title');
+    return requestDatalayerAPI({
+        url: `${baseUrl}${agentEventsPath(data.agent_id)}`,
+        method: 'POST',
+        token,
+        body: data,
+    });
+};
+export const listEvents = async (token, agentId, params = {}, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    validateRequiredString(agentId, 'agentId');
+    return requestDatalayerAPI({
+        url: `${baseUrl}${agentEventsPath(agentId)}${toQueryString(params)}`,
+        method: 'GET',
+        token,
+    });
+};
+export const getEvent = async (token, agentId, eventId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    validateRequiredString(agentId, 'agentId');
+    validateRequiredString(eventId, 'eventId');
+    return requestDatalayerAPI({
+        url: `${baseUrl}${agentEventsPath(agentId)}/${encodeURIComponent(eventId)}`,
+        method: 'GET',
+        token,
+    });
+};
+export const updateEvent = async (token, agentId, eventId, data, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    validateRequiredString(agentId, 'agentId');
+    validateRequiredString(eventId, 'eventId');
+    return requestDatalayerAPI({
+        url: `${baseUrl}${agentEventsPath(agentId)}/${encodeURIComponent(eventId)}`,
+        method: 'PATCH',
+        token,
+        body: data,
+    });
+};
+export const deleteEvent = async (token, agentId, eventId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    validateRequiredString(agentId, 'agentId');
+    validateRequiredString(eventId, 'eventId');
+    return requestDatalayerAPI({
+        url: `${baseUrl}${agentEventsPath(agentId)}/${encodeURIComponent(eventId)}`,
+        method: 'DELETE',
+        token,
+    });
+};
+export const markEventRead = async (token, agentId, eventId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    return updateEvent(token, agentId, eventId, { read: true }, baseUrl);
+};
+export const markEventUnread = async (token, agentId, eventId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    return updateEvent(token, agentId, eventId, { read: false }, baseUrl);
+};
+/**
+ * List events across all agents for the authenticated user.
+ */
+export const listAllEvents = async (token, params = {}, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/events${toQueryString(params)}`,
+        method: 'GET',
+        token,
+    });
+};

package/lib/{components/chat → api}/handler.js

@@ -6,7 +6,7 @@
  * Simple API request handler.
  * Helper function to make API requests to the Simple server.
  *
- * @module components/chat/handler
+ * @module api/handler
  */
 import { URLExt } from '@jupyterlab/coreutils';
 import { ServerConnection } from '@jupyterlab/services';