@datalayer/agent-runtimes 1.0.1 → 1.0.3

package/lib/api/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * API client functions for the agents backend.
+ *
+ * Provides functions to create, list, and manage agents
+ * via the agent-runtimes REST API.
+ *
+ * @module api
+ */
+export * as agents from './agents';
+export * as context from './context';
+export * as evals from './evals';
+export * as events from './events';
+export * as notifications from './notifications';
+export * as output from './output';
+export * as toolApprovals from './tool-approvals';

package/lib/api/index.js

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * API client functions for the agents backend.
+ *
+ * Provides functions to create, list, and manage agents
+ * via the agent-runtimes REST API.
+ *
+ * @module api
+ */
+// Agents Service API (agents, tool-approvals, notifications, etc.)
+export * as agents from './agents';
+export * as context from './context';
+export * as evals from './evals';
+export * as events from './events';
+export * as notifications from './notifications';
+export * as output from './output';
+export * as toolApprovals from './tool-approvals';

package/lib/api/notifications.d.ts

@@ -0,0 +1,39 @@
+import type { AgentNotification, NotificationFilters } from '../types';
+/**
+ * List agent notifications with optional filters.
+ * @param token - Authentication token
+ * @param filters - Optional filters (agentId, level, unreadOnly, category, limit, offset)
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to list of notifications
+ */
+export declare const getNotifications: (token: string, filters?: NotificationFilters, baseUrl?: string) => Promise<AgentNotification[]>;
+/**
+ * Get a specific notification by ID.
+ * @param token - Authentication token
+ * @param id - Notification ID
+ * @param baseUrl - Base URL
+ */
+export declare const getNotification: (token: string, id: string, baseUrl?: string) => Promise<AgentNotification>;
+/**
+ * Mark a notification as read.
+ * @param token - Authentication token
+ * @param id - Notification ID
+ * @param baseUrl - Base URL
+ */
+export declare const markNotificationRead: (token: string, id: string, baseUrl?: string) => Promise<void>;
+/**
+ * Mark all notifications as read.
+ * @param token - Authentication token
+ * @param agentId - Optional: only for a specific agent
+ * @param baseUrl - Base URL
+ */
+export declare const markAllRead: (token: string, agentId?: string, baseUrl?: string) => Promise<void>;
+/**
+ * Get count of unread notifications.
+ * @param token - Authentication token
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to unread count
+ */
+export declare const getUnreadCount: (token: string, baseUrl?: string) => Promise<{
+    count: number;
+}>;

package/lib/api/notifications.js

@@ -0,0 +1,103 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Agent notifications API functions.
+ *
+ * Provides CRUD operations for agent-generated notifications.
+ * Agents emit notifications for guardrail events, budget warnings,
+ * task completions, and other notable events.
+ *
+ * @module api/notifications
+ */
+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 agent notifications with optional filters.
+ * @param token - Authentication token
+ * @param filters - Optional filters (agentId, level, unreadOnly, category, limit, offset)
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to list of notifications
+ */
+export const getNotifications = async (token, filters, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    const params = new URLSearchParams();
+    if (filters?.agentId)
+        params.set('agent_id', filters.agentId);
+    if (filters?.level)
+        params.set('level', filters.level);
+    if (filters?.unreadOnly)
+        params.set('unread_only', 'true');
+    if (filters?.category)
+        params.set('category', filters.category);
+    if (filters?.limit)
+        params.set('limit', String(filters.limit));
+    if (filters?.offset)
+        params.set('offset', String(filters.offset));
+    const query = params.toString() ? `?${params.toString()}` : '';
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/notifications${query}`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Get a specific notification by ID.
+ * @param token - Authentication token
+ * @param id - Notification ID
+ * @param baseUrl - Base URL
+ */
+export const getNotification = async (token, id, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/notifications/${encodeURIComponent(id)}`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Mark a notification as read.
+ * @param token - Authentication token
+ * @param id - Notification ID
+ * @param baseUrl - Base URL
+ */
+export const markNotificationRead = async (token, id, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/notifications/${encodeURIComponent(id)}/read`,
+        method: 'POST',
+        token,
+    });
+};
+/**
+ * Mark all notifications as read.
+ * @param token - Authentication token
+ * @param agentId - Optional: only for a specific agent
+ * @param baseUrl - Base URL
+ */
+export const markAllRead = async (token, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    const body = agentId ? { agent_id: agentId } : {};
+    await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/notifications/read-all`,
+        method: 'POST',
+        body,
+        token,
+    });
+};
+/**
+ * Get count of unread notifications.
+ * @param token - Authentication token
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to unread count
+ */
+export const getUnreadCount = async (token, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/notifications/unread/count`,
+        method: 'GET',
+        token,
+    });
+};

package/lib/api/output.d.ts

@@ -0,0 +1,28 @@
+import type { OutputArtifact } from '../types';
+/**
+ * List output artifacts for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to list of output artifacts
+ */
+export declare const getAgentOutputs: (token: string, agentId: string, baseUrl?: string) => Promise<OutputArtifact[]>;
+/**
+ * Get a specific output artifact.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param artifactId - Artifact ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to artifact details
+ */
+export declare const getAgentOutput: (token: string, agentId: string, artifactId: string, baseUrl?: string) => Promise<OutputArtifact>;
+/**
+ * Generate a new output artifact for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param format - Output format (e.g. 'pdf')
+ * @param options - Additional generation options
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to the generated artifact
+ */
+export declare const generateAgentOutput: (token: string, agentId: string, format?: string, options?: Record<string, unknown>, baseUrl?: string) => Promise<OutputArtifact>;

package/lib/api/output.js

@@ -0,0 +1,64 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Output artifacts API functions.
+ *
+ * Provides functions for listing and downloading agent-generated
+ * output artifacts (PDFs, reports, etc.).
+ *
+ * @module api/output
+ */
+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 output artifacts for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to list of output artifacts
+ */
+export const getAgentOutputs = async (token, agentId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(agentId)}/output`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Get a specific output artifact.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param artifactId - Artifact ID
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to artifact details
+ */
+export const getAgentOutput = async (token, agentId, artifactId, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(agentId)}/output/${encodeURIComponent(artifactId)}`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Generate a new output artifact for an agent.
+ * @param token - Authentication token
+ * @param agentId - Agent ID
+ * @param format - Output format (e.g. 'pdf')
+ * @param options - Additional generation options
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to the generated artifact
+ */
+export const generateAgentOutput = async (token, agentId, format = 'pdf', options, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/agents/${encodeURIComponent(agentId)}/output/generate`,
+        method: 'POST',
+        token,
+        body: { format, ...options },
+    });
+};

package/lib/api/tool-approvals.d.ts

@@ -0,0 +1,62 @@
+import type { ToolApproval, ToolApprovalFilters } from '../types';
+/**
+ * List tool approvals with optional filters.
+ * @param token - Authentication token
+ * @param filters - Optional filters (agentId, status, toolName, limit, offset)
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to list of tool approvals
+ */
+export declare const getToolApprovals: (token: string, filters?: ToolApprovalFilters, baseUrl?: string) => Promise<ToolApproval[]>;
+/**
+ * Get a specific tool approval by ID.
+ * @param token - Authentication token
+ * @param id - Tool approval ID
+ * @param baseUrl - Base URL
+ */
+export declare const getToolApproval: (token: string, id: string, baseUrl?: string) => Promise<ToolApproval>;
+/**
+ * Approve a pending tool request.
+ * @param token - Authentication token
+ * @param id - Tool approval ID
+ * @param note - Optional note explaining the approval
+ * @param baseUrl - Base URL
+ */
+export declare const approveToolRequest: (token: string, id: string, note?: string, baseUrl?: string) => Promise<void>;
+/**
+ * Reject a pending tool request.
+ * @param token - Authentication token
+ * @param id - Tool approval ID
+ * @param note - Optional note explaining the rejection
+ * @param baseUrl - Base URL
+ */
+export declare const rejectToolRequest: (token: string, id: string, note?: string, baseUrl?: string) => Promise<void>;
+/**
+ * Mark a tool approval as read.
+ * @param token - Authentication token
+ * @param id - Tool approval ID
+ * @param baseUrl - Base URL
+ */
+export declare const markToolApprovalRead: (token: string, id: string, baseUrl?: string) => Promise<void>;
+/**
+ * Mark a tool approval as unread.
+ * @param token - Authentication token
+ * @param id - Tool approval ID
+ * @param baseUrl - Base URL
+ */
+export declare const markToolApprovalUnread: (token: string, id: string, baseUrl?: string) => Promise<void>;
+/**
+ * Delete a tool approval.
+ * @param token - Authentication token
+ * @param id - Tool approval ID
+ * @param baseUrl - Base URL
+ */
+export declare const deleteToolApproval: (token: string, id: string, baseUrl?: string) => Promise<void>;
+/**
+ * Get count of pending tool approvals.
+ * @param token - Authentication token
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to pending count
+ */
+export declare const getPendingApprovalCount: (token: string, baseUrl?: string) => Promise<{
+    count: number;
+}>;

package/lib/api/tool-approvals.js

@@ -0,0 +1,145 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Tool approvals API functions.
+ *
+ * Provides CRUD operations for agent tool approval requests.
+ * When an agent encounters a tool that requires human approval,
+ * a ToolApproval record is created that the user can approve or reject.
+ *
+ * @module api/tool-approvals
+ */
+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 tool approvals with optional filters.
+ * @param token - Authentication token
+ * @param filters - Optional filters (agentId, status, toolName, limit, offset)
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to list of tool approvals
+ */
+export const getToolApprovals = async (token, filters, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    const params = new URLSearchParams();
+    if (filters?.agentId)
+        params.set('agent_id', filters.agentId);
+    if (filters?.status)
+        params.set('status', filters.status);
+    if (filters?.toolName)
+        params.set('tool_name', filters.toolName);
+    if (filters?.limit)
+        params.set('limit', String(filters.limit));
+    if (filters?.offset)
+        params.set('offset', String(filters.offset));
+    const query = params.toString() ? `?${params.toString()}` : '';
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/tool-approvals${query}`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Get a specific tool approval by ID.
+ * @param token - Authentication token
+ * @param id - Tool approval ID
+ * @param baseUrl - Base URL
+ */
+export const getToolApproval = async (token, id, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/tool-approvals/${encodeURIComponent(id)}`,
+        method: 'GET',
+        token,
+    });
+};
+/**
+ * Approve a pending tool request.
+ * @param token - Authentication token
+ * @param id - Tool approval ID
+ * @param note - Optional note explaining the approval
+ * @param baseUrl - Base URL
+ */
+export const approveToolRequest = async (token, id, note, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/tool-approvals/${encodeURIComponent(id)}/approve`,
+        method: 'POST',
+        body: { note },
+        token,
+    });
+};
+/**
+ * Reject a pending tool request.
+ * @param token - Authentication token
+ * @param id - Tool approval ID
+ * @param note - Optional note explaining the rejection
+ * @param baseUrl - Base URL
+ */
+export const rejectToolRequest = async (token, id, note, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/tool-approvals/${encodeURIComponent(id)}/reject`,
+        method: 'POST',
+        body: { note },
+        token,
+    });
+};
+/**
+ * Mark a tool approval as read.
+ * @param token - Authentication token
+ * @param id - Tool approval ID
+ * @param baseUrl - Base URL
+ */
+export const markToolApprovalRead = async (token, id, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/tool-approvals/${encodeURIComponent(id)}/mark-read`,
+        method: 'POST',
+        token,
+    });
+};
+/**
+ * Mark a tool approval as unread.
+ * @param token - Authentication token
+ * @param id - Tool approval ID
+ * @param baseUrl - Base URL
+ */
+export const markToolApprovalUnread = async (token, id, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/tool-approvals/${encodeURIComponent(id)}/mark-unread`,
+        method: 'POST',
+        token,
+    });
+};
+/**
+ * Delete a tool approval.
+ * @param token - Authentication token
+ * @param id - Tool approval ID
+ * @param baseUrl - Base URL
+ */
+export const deleteToolApproval = async (token, id, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    await requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/tool-approvals/${encodeURIComponent(id)}`,
+        method: 'DELETE',
+        token,
+    });
+};
+/**
+ * Get count of pending tool approvals.
+ * @param token - Authentication token
+ * @param baseUrl - Base URL
+ * @returns Promise resolving to pending count
+ */
+export const getPendingApprovalCount = async (token, baseUrl = DEFAULT_SERVICE_URLS.AI_AGENTS) => {
+    validateToken(token);
+    return requestDatalayerAPI({
+        url: `${baseUrl}${API_BASE_PATHS.AI_AGENTS}/tool-approvals/pending/count`,
+        method: 'GET',
+        token,
+    });
+};

package/lib/{components/chat/components → chat}/Chat.d.ts

@@ -1,22 +1,12 @@
-import { type Suggestion } from './base/ChatBase';
-import type { ModelConfig, ChatViewMode } from './base/ChatBase';
-import type { FrontendToolDefinition } from '../types/tool';
-import type { McpServerSelection } from '../types';
-import type { OAuthProvider, OAuthProviderConfig, Identity } from '../../../identity';
-/**
- * Supported transports (communication transports)
- */
-export type Transport = 'ag-ui' | 'a2a' | 'acp' | 'vercel-ai' | 'vercel-ai-jupyter';
-/**
- * Extension type for chat features
- */
-export type Extension = 'mcp-ui' | 'a2ui';
+import type { ReactNode } from 'react';
+import type { OAuthProvider, OAuthProviderConfig, Identity } from '../identity';
+import type { Extension, FrontendToolDefinition, McpServerSelection, Protocol, ChatViewMode, ModelConfig, RenderToolResult, Suggestion } from '../types';
 /**
  * Chat props
  */
 export interface ChatProps {
     /** Transport to use */
-    transport: Transport;
+    protocol: Protocol;
     /** Extensions for chat features */
     extensions?: Extension[];
     /** Base URL of the server (for HTTP-based protocols) */
@@ -25,10 +15,14 @@ export interface ChatProps {
     wsUrl?: string;
     /** Agent ID */
     agentId?: string;
+    /** Authentication token (JWT) to send as Authorization Bearer header */
+    authToken?: string;
     /** Custom placeholder text */
     placeholder?: string;
     /** Custom title */
     title?: string;
+    /** Brand icon shown in chat header/empty state and details title */
+    brandIcon?: ReactNode;
     /** Whether to auto-connect on mount */
     autoConnect?: boolean;
     /** Whether to use streaming (for protocols that support it) */
@@ -49,6 +43,10 @@ export interface ChatProps {
     height?: string | number;
     /** Show header with connection status */
     showHeader?: boolean;
+    /** Show the new chat (+) button in the header */
+    showNewChatButton?: boolean;
+    /** Show the clear chat button in the header */
+    showClearButton?: boolean;
     /** Show model selector (fetched from /configure endpoint) */
     showModelSelector?: boolean;
     /** Show tools menu (fetched from /configure endpoint) */
@@ -82,6 +80,10 @@ export interface ChatProps {
     submitOnSuggestionClick?: boolean;
     /** Description shown in empty state */
     description?: string;
+    /** Custom content to render in the chat header title row (left side). */
+    headerContent?: ReactNode;
+    /** Custom actions to render in the chat header title row (right side). */
+    headerActions?: ReactNode;
     /** Auto-focus the input on mount */
     autoFocus?: boolean;
     /** Identity providers configuration for OAuth */
@@ -99,7 +101,7 @@ export interface ChatProps {
     /**
      * 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;
     /**
@@ -142,6 +144,13 @@ export interface ChatProps {
      * Pass an empty array to explicitly disable all frontend tools.
      */
     frontendTools?: FrontendToolDefinition[];
+    /** Optional custom renderer for tool-call message cards. */
+    renderToolResult?: RenderToolResult;
+    /**
+     * Hide assistant messages that follow a rendered tool call UI.
+     * Useful to suppress raw tool-call/continuation text and show only tool cards.
+     */
+    hideMessagesAfterToolUI?: boolean;
 }
 /**
  * Chat Component
@@ -184,5 +193,5 @@ export interface ChatProps {
  * />
  * ```
  */
-export declare function Chat({ transport, extensions: _extensions, baseUrl, wsUrl, agentId, placeholder, title, autoConnect: _autoConnect, streaming: _streaming, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height, showHeader, showModelSelector, showToolsMenu, showSkillsMenu, codemodeEnabled, showTokenUsage, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount, suggestions, submitOnSuggestionClick, description, autoFocus, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation, chatViewMode, onChatViewModeChange, frontendTools, }: ChatProps): import("react/jsx-runtime").JSX.Element;
+export declare function Chat({ protocol: transport, extensions: _extensions, baseUrl, wsUrl, agentId, authToken: authTokenProp, placeholder, title, brandIcon, autoConnect: _autoConnect, streaming: _streaming, onMessageSent: _onMessageSent, onMessageReceived: _onMessageReceived, onDisconnect, onLogout: _onLogout, onCollapsePanel: _onCollapsePanel, className, height, showHeader, showNewChatButton, showClearButton, showModelSelector, showToolsMenu, showSkillsMenu, codemodeEnabled, showTokenUsage, initialModel, availableModels, mcpServers, initialSkills, clearOnMount: _clearOnMount, suggestions, submitOnSuggestionClick, description, headerContent, headerActions, autoFocus, identityProviders, onIdentityConnect, onIdentityDisconnect, runtimeId, historyEndpoint, pendingPrompt, errorBanner, showInformation, chatViewMode, onChatViewModeChange, frontendTools, renderToolResult, hideMessagesAfterToolUI, }: ChatProps): import("react/jsx-runtime").JSX.Element;
 export default Chat;