@datalayer/agent-runtimes 0.0.8 → 0.0.10

package/lib/components/chat/components/ContextPanel.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Distribution child item for treemap
+ */
+interface DistributionChild {
+    name: string;
+    value: number;
+    children?: DistributionChild[];
+}
+/**
+ * Distribution data for treemap
+ */
+interface Distribution {
+    name: string;
+    value: number;
+    children: DistributionChild[];
+}
+/**
+ * Request usage snapshot - historic per-request data
+ */
+interface RequestUsageSnapshot {
+    requestNum: number;
+    inputTokens: number;
+    outputTokens: number;
+    toolNames: string[];
+    timestamp: string | null;
+    turnId: string | null;
+    durationMs: number;
+}
+/**
+ * Tool snapshot
+ */
+interface ToolSnapshot {
+    name: string;
+    description: string | null;
+    parametersTokens: number;
+    totalTokens: number;
+}
+/**
+ * Turn usage
+ */
+interface TurnUsage {
+    inputTokens: number;
+    outputTokens: number;
+    requests: number;
+    toolCalls: number;
+    toolNames: string[];
+    durationSeconds: number;
+}
+/**
+ * Session usage
+ */
+interface SessionUsage {
+    inputTokens: number;
+    outputTokens: number;
+    requests: number;
+    toolCalls: number;
+    turns: number;
+    durationSeconds: number;
+}
+/**
+ * Context snapshot response from API
+ */
+export interface ContextSnapshotResponse {
+    agentId: string;
+    systemPrompts: string[];
+    systemPromptTokens: number;
+    tools: ToolSnapshot[];
+    toolTokens: number;
+    historyToolCallTokens: number;
+    historyToolReturnTokens: number;
+    currentToolCallTokens: number;
+    currentToolReturnTokens: number;
+    toolCallTokens: number;
+    toolReturnTokens: number;
+    historyUserTokens: number;
+    historyAssistantTokens: number;
+    currentUserTokens: number;
+    currentAssistantTokens: number;
+    historyTokens: number;
+    currentMessageTokens: number;
+    userMessageTokens: number;
+    assistantMessageTokens: number;
+    totalTokens: number;
+    modelInputTokens: number | null;
+    modelOutputTokens: number | null;
+    sumResponseInputTokens: number;
+    sumResponseOutputTokens: number;
+    perRequestUsage: RequestUsageSnapshot[];
+    contextWindow: number;
+    turnUsage: TurnUsage | null;
+    sessionUsage: SessionUsage | null;
+    distribution: Distribution;
+    error?: string;
+}
+type ViewMode = 'overview' | 'distribution' | 'history';
+export interface ContextPanelProps {
+    /** Agent ID for fetching context details (required) */
+    agentId: string;
+    /** API base URL for fetching context data */
+    apiBase?: string;
+    /** Number of messages in conversation (from chat store) */
+    messageCount?: number;
+    /** Default view mode */
+    defaultView?: ViewMode;
+    /** Height for charts */
+    chartHeight?: string;
+}
+/**
+ * ContextPanel component - unified context usage display.
+ */
+export declare function ContextPanel({ agentId, apiBase, messageCount, defaultView, chartHeight, }: ContextPanelProps): import("react/jsx-runtime").JSX.Element;
+export default ContextPanel;

package/lib/components/chat/components/ContextPanel.js

@@ -0,0 +1,373 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Copyright (c) 2025-2026 Datalayer, Inc.
+// Distributed under the terms of the Modified BSD License.
+/**
+ * ContextPanel component - Unified context usage display with:
+ * - Cumulative usage with progress bar
+ * - Token distribution treemap
+ * - Historic usage time-series chart
+ */
+import { CommentDiscussionIcon, DatabaseIcon, FileIcon, ToolsIcon, ClockIcon, GraphIcon, ListUnorderedIcon, } from '@primer/octicons-react';
+import { Heading, Text, ProgressBar, Spinner, Button, SegmentedControl, } from '@primer/react';
+import { Box } from '@datalayer/primer-addons';
+import { useQuery } from '@tanstack/react-query';
+import ReactECharts from 'echarts-for-react';
+import { useState, useMemo } from 'react';
+/**
+ * Format token count for display
+ */
+function formatTokens(tokens) {
+    if (tokens >= 1000000) {
+        return `${(tokens / 1000000).toFixed(1)}M`;
+    }
+    if (tokens >= 1000) {
+        return `${(tokens / 1000).toFixed(1)}K`;
+    }
+    return tokens.toString();
+}
+/**
+ * Format duration
+ */
+function formatDuration(seconds) {
+    if (seconds < 1) {
+        return `${Math.round(seconds * 1000)}ms`;
+    }
+    if (seconds < 60) {
+        return `${seconds.toFixed(1)}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    const secs = Math.round(seconds % 60);
+    return `${minutes}m ${secs}s`;
+}
+/**
+ * Get icon for context category
+ */
+function getCategoryIcon(name) {
+    switch (name.toLowerCase()) {
+        case 'messages':
+        case 'history':
+            return CommentDiscussionIcon;
+        case 'tools':
+        case 'tool definitions':
+            return ToolsIcon;
+        case 'system':
+        case 'system prompts':
+            return FileIcon;
+        case 'cache':
+            return DatabaseIcon;
+        default:
+            return ClockIcon;
+    }
+}
+/**
+ * Get the API base URL for fetching context data.
+ * If apiBase prop is provided, use it.
+ * Otherwise, fall back to localhost for local development.
+ */
+function getApiBase(apiBase) {
+    if (apiBase) {
+        return apiBase;
+    }
+    if (typeof window === 'undefined') {
+        return '';
+    }
+    const host = window.location.hostname;
+    return host === 'localhost' || host === '127.0.0.1'
+        ? 'http://127.0.0.1:8765'
+        : '';
+}
+/**
+ * ContextPanel component - unified context usage display.
+ */
+export function ContextPanel({ agentId, apiBase, messageCount = 0, defaultView = 'overview', chartHeight = '200px', }) {
+    const [viewMode, setViewMode] = useState(defaultView);
+    const [showDetails, setShowDetails] = useState(false);
+    const { data: snapshotData, isLoading, error, } = useQuery({
+        queryKey: ['context-snapshot', agentId, apiBase],
+        queryFn: async () => {
+            const base = getApiBase(apiBase);
+            const response = await fetch(`${base}/api/v1/configure/agents/${encodeURIComponent(agentId)}/context-snapshot`);
+            if (!response.ok) {
+                throw new Error('Failed to fetch context snapshot');
+            }
+            return response.json();
+        },
+        refetchInterval: 5000,
+        refetchOnMount: 'always',
+        staleTime: 0,
+    });
+    // Build historic usage chart data from perRequestUsage
+    const historyChartOption = useMemo(() => {
+        if (!snapshotData?.perRequestUsage ||
+            snapshotData.perRequestUsage.length === 0) {
+            return null;
+        }
+        const requests = snapshotData.perRequestUsage;
+        // Calculate cumulative tokens over time
+        let cumulativeInput = 0;
+        let cumulativeOutput = 0;
+        const xAxisData = [];
+        const inputData = [];
+        const outputData = [];
+        const totalData = [];
+        requests.forEach(req => {
+            cumulativeInput += req.inputTokens;
+            cumulativeOutput += req.outputTokens;
+            xAxisData.push(`#${req.requestNum}`);
+            inputData.push(cumulativeInput);
+            outputData.push(cumulativeOutput);
+            totalData.push(cumulativeInput + cumulativeOutput);
+        });
+        return {
+            tooltip: {
+                trigger: 'axis',
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                formatter: (params) => {
+                    const reqNum = params[0]?.axisValue || '';
+                    let result = `<strong>${reqNum}</strong><br/>`;
+                    params.forEach(p => {
+                        result += `${p.marker} ${p.seriesName}: ${formatTokens(p.value)}<br/>`;
+                    });
+                    return result;
+                },
+            },
+            legend: {
+                data: ['Input', 'Output', 'Total'],
+                bottom: 0,
+                textStyle: { fontSize: 10 },
+            },
+            grid: {
+                left: 45,
+                right: 15,
+                top: 10,
+                bottom: 35,
+            },
+            xAxis: {
+                type: 'category',
+                data: xAxisData,
+                axisLabel: { fontSize: 10 },
+            },
+            yAxis: {
+                type: 'value',
+                axisLabel: {
+                    fontSize: 10,
+                    formatter: (value) => formatTokens(value),
+                },
+            },
+            series: [
+                {
+                    name: 'Input',
+                    type: 'line',
+                    data: inputData,
+                    smooth: true,
+                    lineStyle: { width: 2 },
+                    areaStyle: { opacity: 0.2 },
+                    itemStyle: { color: '#3B82F6' },
+                },
+                {
+                    name: 'Output',
+                    type: 'line',
+                    data: outputData,
+                    smooth: true,
+                    lineStyle: { width: 2 },
+                    areaStyle: { opacity: 0.2 },
+                    itemStyle: { color: '#10B981' },
+                },
+                {
+                    name: 'Total',
+                    type: 'line',
+                    data: totalData,
+                    smooth: true,
+                    lineStyle: { width: 2, type: 'dashed' },
+                    itemStyle: { color: '#8B5CF6' },
+                },
+            ],
+        };
+    }, [snapshotData?.perRequestUsage]);
+    // Build treemap chart option
+    const treemapOption = useMemo(() => {
+        if (!snapshotData?.distribution)
+            return null;
+        const { distribution } = snapshotData;
+        const hasData = distribution.children && distribution.children.length > 0;
+        return {
+            tooltip: {
+                formatter: (info) => {
+                    return `${info.name}: ${formatTokens(info.value)} tokens`;
+                },
+            },
+            series: [
+                {
+                    type: 'treemap',
+                    data: hasData
+                        ? distribution.children
+                        : [{ name: 'No data', value: 1 }],
+                    roam: false,
+                    breadcrumb: { show: false },
+                    label: {
+                        show: true,
+                        formatter: '{b}',
+                        fontSize: 11,
+                    },
+                    itemStyle: {
+                        borderColor: '#fff',
+                        borderWidth: 2,
+                    },
+                    levels: [
+                        {
+                            itemStyle: {
+                                borderColor: '#777',
+                                borderWidth: 0,
+                                gapWidth: 1,
+                            },
+                        },
+                        {
+                            itemStyle: {
+                                borderColor: '#555',
+                                borderWidth: 5,
+                                gapWidth: 1,
+                            },
+                            colorSaturation: [0.35, 0.5],
+                        },
+                        {
+                            colorSaturation: [0.35, 0.5],
+                        },
+                    ],
+                },
+            ],
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [snapshotData?.distribution]);
+    if (isLoading) {
+        return (_jsxs(Box, { children: [_jsx(Heading, { as: "h4", sx: {
+                        fontSize: 1,
+                        fontWeight: 'semibold',
+                        mb: 2,
+                        color: 'fg.muted',
+                    }, children: "Context Usage" }), _jsxs(Box, { sx: {
+                        p: 3,
+                        bg: 'canvas.subtle',
+                        borderRadius: 2,
+                        border: '1px solid',
+                        borderColor: 'border.default',
+                        display: 'flex',
+                        alignItems: 'center',
+                        gap: 2,
+                    }, children: [_jsx(Spinner, { size: "small" }), _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Loading context details..." })] })] }));
+    }
+    if (error || !snapshotData) {
+        return (_jsxs(Box, { children: [_jsx(Heading, { as: "h4", sx: {
+                        fontSize: 1,
+                        fontWeight: 'semibold',
+                        mb: 2,
+                        color: 'fg.muted',
+                    }, children: "Context Usage" }), _jsx(Box, { sx: {
+                        p: 3,
+                        bg: 'canvas.subtle',
+                        borderRadius: 2,
+                        border: '1px solid',
+                        borderColor: 'border.default',
+                    }, children: _jsx(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: "Failed to load context details. Make sure the agent is running." }) })] }));
+    }
+    const { totalTokens, contextWindow, sessionUsage, turnUsage, distribution } = snapshotData;
+    const contextUsagePercent = (totalTokens / contextWindow) * 100;
+    const hasDistributionData = distribution?.children && distribution.children.length > 0;
+    const hasHistoryData = snapshotData.perRequestUsage && snapshotData.perRequestUsage.length > 0;
+    return (_jsxs(Box, { children: [_jsxs(Box, { sx: {
+                    display: 'flex',
+                    justifyContent: 'space-between',
+                    alignItems: 'center',
+                    mb: 2,
+                }, children: [_jsx(Heading, { as: "h4", sx: {
+                            fontSize: 1,
+                            fontWeight: 'semibold',
+                            color: 'fg.muted',
+                        }, children: "Context Usage" }), messageCount > 0 && (_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: [messageCount, " ", messageCount === 1 ? 'message' : 'messages'] }))] }), _jsxs(Box, { sx: {
+                    p: 3,
+                    bg: 'canvas.subtle',
+                    borderRadius: 2,
+                    border: '1px solid',
+                    borderColor: 'border.default',
+                }, children: [_jsxs(Box, { sx: { mb: 3 }, children: [_jsxs(Box, { sx: {
+                                    display: 'flex',
+                                    justifyContent: 'space-between',
+                                    mb: 1,
+                                }, children: [_jsxs(Text, { sx: { fontSize: 1, fontWeight: 'semibold' }, children: [formatTokens(totalTokens), " / ", formatTokens(contextWindow), " tokens"] }), _jsxs(Text, { sx: { fontSize: 1, color: 'fg.muted' }, children: [contextUsagePercent.toFixed(1), "%"] })] }), _jsx(ProgressBar, { progress: Math.min(contextUsagePercent, 100), sx: { height: 8 }, bg: contextUsagePercent > 80 ? 'danger.emphasis' : 'accent.emphasis' })] }), (sessionUsage || turnUsage) && (_jsxs(Box, { sx: {
+                            display: 'flex',
+                            gap: 3,
+                            mb: 3,
+                            flexWrap: 'wrap',
+                        }, children: [sessionUsage && (_jsxs(Box, { sx: {
+                                    flex: 1,
+                                    minWidth: 120,
+                                    p: 2,
+                                    bg: 'canvas.default',
+                                    borderRadius: 2,
+                                    border: '1px solid',
+                                    borderColor: 'border.muted',
+                                }, children: [_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', display: 'block' }, children: ["Session (", sessionUsage.turns, " turns)"] }), _jsx(Text, { sx: { fontSize: 1, fontWeight: 'semibold' }, children: formatTokens(sessionUsage.inputTokens + sessionUsage.outputTokens) }), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: [' ', "in ", formatDuration(sessionUsage.durationSeconds)] })] })), turnUsage && (_jsxs(Box, { sx: {
+                                    flex: 1,
+                                    minWidth: 120,
+                                    p: 2,
+                                    bg: 'canvas.default',
+                                    borderRadius: 2,
+                                    border: '1px solid',
+                                    borderColor: 'border.muted',
+                                }, children: [_jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted', display: 'block' }, children: ["Last Turn (", turnUsage.requests, " reqs)"] }), _jsx(Text, { sx: { fontSize: 1, fontWeight: 'semibold' }, children: formatTokens(turnUsage.inputTokens + turnUsage.outputTokens) }), _jsxs(Text, { sx: { fontSize: 0, color: 'fg.muted' }, children: [' ', "in ", formatDuration(turnUsage.durationSeconds)] })] }))] })), _jsxs(Box, { sx: {
+                            display: 'flex',
+                            justifyContent: 'space-between',
+                            alignItems: 'center',
+                            mb: 2,
+                        }, children: [_jsxs(SegmentedControl, { "aria-label": "View mode", size: "small", onChange: index => {
+                                    const modes = ['overview', 'distribution', 'history'];
+                                    setViewMode(modes[index]);
+                                }, children: [_jsx(SegmentedControl.Button, { selected: viewMode === 'overview', leadingIcon: ListUnorderedIcon, children: "Overview" }), _jsx(SegmentedControl.Button, { selected: viewMode === 'distribution', leadingIcon: GraphIcon, disabled: !hasDistributionData, children: "Distribution" }), _jsx(SegmentedControl.Button, { selected: viewMode === 'history', leadingIcon: ClockIcon, disabled: !hasHistoryData, children: "History" })] }), viewMode === 'overview' && (_jsx(Button, { size: "small", variant: "invisible", onClick: () => setShowDetails(!showDetails), children: showDetails ? 'Less' : 'More' }))] }), viewMode === 'overview' && (_jsxs(Box, { children: [_jsxs(Box, { sx: { display: 'flex', flexDirection: 'column', gap: 2 }, children: [hasDistributionData &&
+                                        distribution.children.map(category => {
+                                            const CategoryIcon = getCategoryIcon(category.name);
+                                            const categoryPercent = (category.value / contextWindow) * 100;
+                                            return (_jsxs(Box, { sx: {
+                                                    display: 'flex',
+                                                    alignItems: 'center',
+                                                    gap: 2,
+                                                }, children: [_jsx(Box, { sx: { color: 'fg.muted', width: 20 }, children: _jsx(CategoryIcon, { size: 16 }) }), _jsx(Text, { sx: { fontSize: 1, flex: 1 }, children: category.name }), _jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', minWidth: 60 }, children: formatTokens(category.value) }), _jsx(Box, { sx: { width: 80 }, children: _jsx(ProgressBar, { progress: categoryPercent, sx: { height: 4 } }) })] }, category.name));
+                                        }), !hasDistributionData && (_jsx(Text, { sx: {
+                                            color: 'fg.muted',
+                                            fontSize: 1,
+                                            textAlign: 'center',
+                                            py: 2,
+                                        }, children: "No context data yet. Start a conversation to see usage." }))] }), showDetails && hasDistributionData && (_jsxs(Box, { sx: {
+                                    mt: 3,
+                                    p: 2,
+                                    bg: 'canvas.default',
+                                    borderRadius: 2,
+                                    border: '1px solid',
+                                    borderColor: 'border.muted',
+                                    fontSize: 0,
+                                }, children: [snapshotData.systemPromptTokens > 0 && (_jsxs(Box, { sx: { mb: 2 }, children: [_jsxs(Text, { sx: { fontWeight: 'semibold' }, children: ["System Prompts:", ' ', formatTokens(snapshotData.systemPromptTokens), " tokens"] }), snapshotData.systemPrompts
+                                                .slice(0, 2)
+                                                .map((prompt, idx) => (_jsxs(Text, { sx: {
+                                                    display: 'block',
+                                                    ml: 2,
+                                                    mt: 1,
+                                                    color: 'fg.muted',
+                                                }, children: ["\u2022", ' ', prompt.length > 80
+                                                        ? prompt.slice(0, 80) + '...'
+                                                        : prompt] }, idx)))] })), snapshotData.toolTokens > 0 && (_jsxs(Box, { sx: { mb: 2 }, children: [_jsxs(Text, { sx: { fontWeight: 'semibold' }, children: ["Tools: ", formatTokens(snapshotData.toolTokens), " tokens (", snapshotData.tools.length, " tools)"] }), _jsxs(Box, { sx: { ml: 2, mt: 1 }, children: [snapshotData.tools.slice(0, 4).map((tool, idx) => (_jsxs(Text, { sx: { display: 'block', color: 'fg.muted' }, children: ["\u2022 ", tool.name, ": ", formatTokens(tool.totalTokens)] }, idx))), snapshotData.tools.length > 4 && (_jsxs(Text, { sx: { color: 'fg.muted', fontStyle: 'italic' }, children: ["...and ", snapshotData.tools.length - 4, " more"] }))] })] })), (snapshotData.userMessageTokens > 0 ||
+                                        snapshotData.assistantMessageTokens > 0) && (_jsxs(Box, { sx: { mb: 2 }, children: [_jsxs(Text, { sx: { fontWeight: 'semibold' }, children: ["Messages:", ' ', formatTokens(snapshotData.userMessageTokens +
+                                                        snapshotData.assistantMessageTokens), ' ', "tokens"] }), _jsxs(Box, { sx: { ml: 2, mt: 1 }, children: [_jsxs(Text, { sx: { display: 'block', color: 'fg.muted' }, children: ["\u2022 User: ", formatTokens(snapshotData.userMessageTokens)] }), _jsxs(Text, { sx: { display: 'block', color: 'fg.muted' }, children: ["\u2022 Assistant:", ' ', formatTokens(snapshotData.assistantMessageTokens)] }), snapshotData.toolCallTokens > 0 && (_jsxs(Text, { sx: { display: 'block', color: 'fg.muted' }, children: ["\u2022 Tool calls:", ' ', formatTokens(snapshotData.toolCallTokens)] }))] })] }))] }))] })), viewMode === 'distribution' && treemapOption && (_jsx(ReactECharts, { option: treemapOption, style: { height: chartHeight }, opts: { renderer: 'svg' } })), viewMode === 'history' && historyChartOption && (_jsxs(Box, { children: [_jsx(ReactECharts, { option: historyChartOption, style: { height: chartHeight }, opts: { renderer: 'svg' } }), showDetails && snapshotData.perRequestUsage.length > 0 && (_jsx(Box, { sx: {
+                                    mt: 2,
+                                    maxHeight: '150px',
+                                    overflowY: 'auto',
+                                    fontSize: 0,
+                                }, children: snapshotData.perRequestUsage
+                                    .slice(-10)
+                                    .reverse()
+                                    .map((req, idx) => (_jsxs(Box, { sx: {
+                                        display: 'flex',
+                                        gap: 2,
+                                        py: 1,
+                                        borderBottom: idx < 9 ? '1px solid' : 'none',
+                                        borderColor: 'border.muted',
+                                    }, children: [_jsxs(Text, { sx: { fontWeight: 'semibold', minWidth: 30 }, children: ["#", req.requestNum] }), _jsxs(Text, { sx: { color: '#3B82F6' }, children: ["\u2193", formatTokens(req.inputTokens)] }), _jsxs(Text, { sx: { color: '#10B981' }, children: ["\u2191", formatTokens(req.outputTokens)] }), req.toolNames.length > 0 && (_jsxs(Text, { sx: { color: 'fg.muted' }, children: ["\uD83D\uDD27 ", req.toolNames.join(', ')] }))] }, req.requestNum))) }))] }))] })] }));
+}
+export default ContextPanel;

package/lib/components/chat/components/base/ChatBase.d.ts

@@ -2,7 +2,10 @@ 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';
+import type { MCPServerConfig as MCPServerConfigType } from '../../../AgentConfiguration';
 /**
  * Tool call status for tool rendering
  */
@@ -127,12 +130,9 @@ export interface ModelConfig {
     isAvailable?: boolean;
 }
 /**
- * Builtin tool configuration
+ * Builtin tool configuration (re-exported from types.ts)
  */
-export interface BuiltinTool {
-    name: string;
-    id: string;
-}
+export type BuiltinTool = BuiltinToolType;
 /**
  * MCP Server Tool configuration
  */
@@ -145,17 +145,10 @@ export interface MCPServerTool {
 /**
  * MCP Server configuration from backend
  */
-export interface MCPServerConfig {
-    id: string;
-    name: string;
-    url?: string;
-    enabled: boolean;
-    tools: MCPServerTool[];
-    command?: string;
-    args?: string[];
-    isAvailable?: boolean;
-    transport?: string;
-}
+/**
+ * MCP Server configuration (re-exported from AgentConfiguration)
+ */
+export type MCPServerConfig = MCPServerConfigType;
 /**
  * Remote configuration from server
  */
@@ -183,6 +176,20 @@ export interface ProtocolConfig {
     /** 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
  */
@@ -191,6 +198,13 @@ export interface ChatBaseProps {
     title?: string;
     /** Show header */
     showHeader?: boolean;
+    /**
+     * Show token usage bar (input/output token counts from the backend).
+     * Rendered independently of showHeader, so usage is visible even without a title bar.
+     * Requires the protocol to have enableConfigQuery=true and an agentId.
+     * @default true
+     */
+    showTokenUsage?: boolean;
     /** Show loading indicator */
     showLoadingIndicator?: boolean;
     /** Show error messages */
@@ -207,8 +221,14 @@ export interface ChatBaseProps {
     codemodeEnabled?: boolean;
     /** Initial model ID to select (e.g., 'openai:gpt-4o-mini') */
     initialModel?: string;
-    /** Initial MCP server IDs to enable (others will be disabled) */
-    initialMcpServers?: string[];
+    /**
+     * Override the list of available models.
+     * When provided, this list replaces the models returned by the config endpoint.
+     * Use this to restrict the model selector to a specific subset of models.
+     */
+    availableModels?: ModelConfig[];
+    /** MCP servers to enable (others will be disabled) */
+    mcpServers?: McpServerSelection[];
     /** Initial skill IDs to enable */
     initialSkills?: string[];
     /** Custom class name */
@@ -228,6 +248,23 @@ export interface ChatBaseProps {
      * When provided and useStore is false, enables protocol mode.
      */
     protocol?: ProtocolConfig;
+    /**
+     * Simplified agent runtime configuration.
+     * A convenience wrapper that creates a ProtocolConfig internally.
+     * When provided, will automatically set useStore=false and configure protocol mode.
+     *
+     * @example
+     * ```tsx
+     * <ChatBase
+     *   agentRuntimeConfig={{
+     *     url: 'http://localhost:8765',
+     *     agentId: 'my-agent',
+     *     authToken: 'my-token',
+     *   }}
+     * />
+     * ```
+     */
+    agentRuntimeConfig?: AgentRuntimeConfig;
     /**
      * Custom message handler (for props-based mode).
      * When provided, uses custom handler instead of store or protocol.
@@ -351,10 +388,28 @@ export interface ChatBaseProps {
         userId?: string;
         accessToken?: string;
     }>;
+    /**
+     * 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.
+     */
+    runtimeId?: string;
+    /**
+     * Endpoint URL for fetching conversation history.
+     * When runtimeId is provided, this endpoint is called to fetch
+     * the conversation history on mount.
+     * If not provided, defaults to `{protocol.endpoint}/history`.
+     */
+    historyEndpoint?: string;
+    /**
+     * Auth token for the history endpoint.
+     * If not provided, uses the protocol's authToken.
+     */
+    historyAuthToken?: string;
 }
 /**
  * ChatBase component - Universal chat panel supporting store, protocol, and custom modes
  */
-export declare function ChatBase({ title, showHeader, showLoadingIndicator, showErrors, showInput, showModelSelector, showToolsMenu, showSkillsMenu, codemodeEnabled, initialModel, initialMcpServers, initialSkills, className, loadingState, headerActions, useStore: useStoreMode, protocol, onSendMessage, enableStreaming, brandIcon, avatarConfig, headerButtons, showPoweredBy, poweredByProps, emptyState, renderToolResult, footerContent, headerContent, children, borderRadius, backgroundColor, border, boxShadow, compact, placeholder, description, onStateUpdate, onNewChat, onClear, onMessagesChange, autoFocus, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, focusTrigger, frontendTools, onAuthorizationRequired, connectedIdentities, }: ChatBaseProps): import("react/jsx-runtime").JSX.Element;
+export declare function ChatBase({ title, showHeader, showTokenUsage, showLoadingIndicator, showErrors, showInput, showModelSelector, showToolsMenu, showSkillsMenu, codemodeEnabled, initialModel, availableModels, mcpServers, initialSkills, className, loadingState, headerActions, useStore: useStoreMode, protocol: protocolProp, agentRuntimeConfig, onSendMessage, enableStreaming, brandIcon, avatarConfig, headerButtons, showPoweredBy, poweredByProps, emptyState, renderToolResult, footerContent, headerContent, children, borderRadius, backgroundColor, border, boxShadow, compact, placeholder, description, onStateUpdate, onNewChat, onClear, onMessagesChange, autoFocus, suggestions, submitOnSuggestionClick, hideMessagesAfterToolUI, focusTrigger, frontendTools, onAuthorizationRequired, connectedIdentities, runtimeId, historyEndpoint, historyAuthToken, }: ChatBaseProps): import("react/jsx-runtime").JSX.Element;
 export type { PoweredByTagProps };
 export default ChatBase;