Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Add agent session metrics (#532)

harshil-209684918439b043
diff --git a/.changeset/agent-metrics-tab.md b/.changeset/agent-metrics-tab.md
new file mode 100644
index 000000000..c393fb774
--- /dev/null
+++ b/.changeset/agent-metrics-tab.md
@@ -0,0 +1,6 @@
+---
+"@truefoundry/trueforge-ui": minor
+"@truefoundry/trueforge": minor
+---
+
+Add a slot-driven agent Metrics tab with aggregate cards, time-range filtering, and Harness-backed line charts.
diff --git a/packages/frontend/package.json b/packages/frontend/package.json
index 3437e7cb5..d250f424d 100644
--- a/packages/frontend/package.json
+++ b/packages/frontend/package.json
@@ -26,7 +26,7 @@
"@assistant-ui/core": "0.2.22",
"@assistant-ui/react": "0.14.27",
"@assistant-ui/store": "0.2.21",
- "@truefoundry/assistant-ui-runtime": "0.1.22",
+ "@truefoundry/assistant-ui-runtime": "0.1.23",
"@truefoundry/trueforge-sdk": "workspace:*",
"@truefoundry/trueforge-ui": "workspace:*",
"monaco-editor": "^0.52.0",
diff --git a/packages/frontend/vite.config.ts b/packages/frontend/vite.config.ts
index 241329872..4b6cab5fe 100644
--- a/packages/frontend/vite.config.ts
+++ b/packages/frontend/vite.config.ts
@@ -59,9 +59,10 @@ export default defineConfig({
port: PORT,
// Fail if FRONTEND_PORT is taken — never silently hop to 3001/3010/etc.
strictPort: true,
- // The Harness SDK already targets the server's /api routes.
+ // Proxy both public SDK routes and internal UI-only routes to the Harness.
proxy: {
'/api': apiProxy,
+ '/internal': apiProxy,
},
},
});
diff --git a/packages/trueforge-ui/README.md b/packages/trueforge-ui/README.md
index 838d6e169..322cb0d15 100644
--- a/packages/trueforge-ui/README.md
+++ b/packages/trueforge-ui/README.md
@@ -515,7 +515,7 @@ function MyBubble({ children, error, actionBar, className }: AssistantMessageBub
/>;
```
-Overridable slots include composer pieces (`ComposerShell`, `ComposerLeftSection`, `ComposerRightSection`, `ComposerSendButton`), messages (`AssistantMessageBubble`, `UserMessageBubble`, `UserMessageEdit`), `Markdown`, `WelcomeScreen`, thread-list atoms, and tool/prompt cards (`ToolCallCard`, `ToolApprovalBar`, `ToolGroupCard`, `SubAgentCard`, `SandboxToolCallCard`, `AgentStepsCard`, `ReasoningCard`, `AskUserPrompt`, `McpAuthPrompt`, and more).
+Overridable slots include composer pieces (`ComposerShell`, `ComposerLeftSection`, `ComposerRightSection`, `ComposerSendButton`), messages (`AssistantMessageBubble`, `UserMessageBubble`, `UserMessageEdit`), `Markdown`, `WelcomeScreen`, thread-list atoms, agent metrics (`AgentMetrics`, `AgentMetricsView`, `AgentMetricsTimeRangeFilter`, `AgentMetricCard`, `AgentMetricChart`), and tool/prompt cards (`ToolCallCard`, `ToolApprovalBar`, `ToolGroupCard`, `SubAgentCard`, `SandboxToolCallCard`, `AgentStepsCard`, `ReasoningCard`, `AskUserPrompt`, `McpAuthPrompt`, and more).
See [docs/customization.md](./docs/customization.md) for the full slot list.
@@ -543,13 +543,19 @@ type TrueForgeServerConfig =
}
| AgentUIServer;
-type AgentUIServer = AgentChatServer & AgentBuilderServer & { catalog?: CatalogServer };
+type AgentUIServer = AgentChatServer &
+ AgentBuilderServer & {
+ catalog?: CatalogServer;
+ sessions?: AgentSessionsServer;
+ metrics?: AgentMetricsServer;
+ };
```
| Port | Responsibility |
| -------------------- | ------------------------------------------------------------------- |
| `AgentChatServer` | Sessions, turns, streaming, draft `AgentSpec` sync |
| `AgentBuilderServer` | `getModels` / `getSkills` / `getMcp` / `searchAgents` / `saveAgent` |
+| `AgentMetricsServer` | Agent meter aggregates, chart definitions, and chart data |
**Zero-config TrueFoundry** — see [Getting started](#getting-started). The SDK calls `createTrueFoundryAgentUIServer` for you.
diff --git a/packages/trueforge-ui/docs/api.md b/packages/trueforge-ui/docs/api.md
index 287fb5e14..7224ed438 100644
--- a/packages/trueforge-ui/docs/api.md
+++ b/packages/trueforge-ui/docs/api.md
@@ -44,6 +44,13 @@ import { createTrueForgeAgentUIServer } from '@truefoundry/trueforge-ui/plugins/
const server = createTrueForgeAgentUIServer({ baseUrl: '/', token });
```
+The Harness factory includes the optional `AgentMetricsServer` port used by the
+agent-detail Metrics tab. Custom servers can provide `metrics` with
+`getCharts`, `getMeters`, and `getChartData`; access it with
+`useAgentMetricsServer` / `useOptionalAgentMetricsServer`. The default visual
+surface is split across the `AgentMetrics`, `AgentMetricsView`,
+`AgentMetricsTimeRangeFilter`, `AgentMetricCard`, and `AgentMetricChart` slots.
+
## Compose
| Export | Notes |
diff --git a/packages/trueforge-ui/docs/customization.md b/packages/trueforge-ui/docs/customization.md
index c8a050b67..43909dca1 100644
--- a/packages/trueforge-ui/docs/customization.md
+++ b/packages/trueforge-ui/docs/customization.md
@@ -69,6 +69,8 @@ Public override surface (primitives stay theme/CSS — not slots):
- **Agent details / sessions:** `AgentDetailsPage`, `AgentDetailsHeader`,
`AgentDetailsTabs`, `AgentDetailsUnavailable`, `AgentOverview`,
`AgentOverviewCard`, `AgentSessions`, `AgentSessionsFilters`, `SessionsPage`,
+ `AgentMetrics`, `AgentMetricsView`, `AgentMetricsTimeRangeFilter`,
+ `AgentMetricCard`, `AgentMetricChart`,
`AgentSessionListRow`, `AgentSessionDetailHeader`, `AgentSessionMetricsStrip`,
`AgentSessionTimelineContainer`, `AgentSessionEventTimeline`,
`AgentSessionEventTimelineChart`, `AgentSessionTurnHeader`,
@@ -99,7 +101,8 @@ Places mirrored to the URL:
- `/sessions/:sessionId` — a specific chat session
- `/settings` — settings overlay (closing navigates to the chat place below it)
- `/library` — Agents Library
-- `/library/:agentId` — agent details. `?tab=overview|sessions|code` selects the tab (default Overview)
+- `/library/:agentId` — agent details. `?tab=overview|sessions|code|metrics` selects the tab (default Overview);
+ Metrics is available when the server provides the optional `metrics` port
Customize the paths (only honored when `withRouter`). Set any entry to `false`
to keep that place overlay-only with no URL:
diff --git a/packages/trueforge-ui/package.json b/packages/trueforge-ui/package.json
index 29f968739..0b6fe2d1f 100644
--- a/packages/trueforge-ui/package.json
+++ b/packages/trueforge-ui/package.json
@@ -95,7 +95,7 @@
"@openuidev/react-headless": "^0.9.4",
"@openuidev/react-lang": "^0.2.9",
"@openuidev/react-ui": "^0.13.2",
- "@truefoundry/assistant-ui-runtime": "0.1.22",
+ "@truefoundry/assistant-ui-runtime": "0.1.23",
"@truefoundry/trueforge-sdk": "workspace:*",
"chart.js": "^4.5.1",
"clsx": "^2.1.1",
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsPage.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsPage.tsx
index dcbf6c79a..9d4ab195f 100644
--- a/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsPage.tsx
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsPage.tsx
@@ -2,7 +2,7 @@
import { Suspense, useCallback, useEffect, useState } from 'react';
import { useSessionShareSearch } from '../../hooks/useSessionShareSearch.js';
-import { useOptionalAgentSessionsServer } from '../../server/ServerContext.js';
+import { useOptionalAgentMetricsServer, useOptionalAgentSessionsServer } from '../../server/ServerContext.js';
import { useShellMode } from '../../server/ShellModeContext.js';
import type { AgentDetail, CodeSnippet } from '../../server/types.js';
import { useSlot } from '../../theme/SlotsProvider.js';
@@ -12,15 +12,18 @@ import type { AgentDetailsPageProps } from './types.js';
export function AgentDetailsPage({ agentId }: AgentDetailsPageProps) {
const sessionsServer = useOptionalAgentSessionsServer();
+ const metricsServer = useOptionalAgentMetricsServer();
const shell = useShellMode();
const share = useSessionShareSearch();
const { updateShareSearch } = share;
- const activeTab = libraryAgentTabFromSearch(share, agentId);
+ const requestedTab = libraryAgentTabFromSearch(share, agentId);
+ const activeTab = requestedTab === 'metrics' && metricsServer == null ? 'overview' : requestedTab;
const AgentDetailsHeader = useSlot('AgentDetailsHeader');
const AgentDetailsTabs = useSlot('AgentDetailsTabs');
const AgentDetailsUnavailable = useSlot('AgentDetailsUnavailable');
const AgentOverview = useSlot('AgentOverview');
const AgentSessions = useSlot('AgentSessions');
+ const AgentMetrics = useSlot('AgentMetrics');
const AgentCodeSnippets = useSlot('AgentCodeSnippets');
const [detail, setDetail] = useState<AgentDetail>();
const [detailFailed, setDetailFailed] = useState(false);
@@ -109,6 +112,8 @@ export function AgentDetailsPage({ agentId }: AgentDetailsPageProps) {
content = <AgentOverview detail={detail} />;
} else if (activeTab === 'sessions') {
content = <AgentSessions agentId={agentId} />;
+ } else if (activeTab === 'metrics') {
+ content = <AgentMetrics agentId={agentId} />;
} else if (snippetsFailed) {
content = <AgentDetailsUnavailable onBack={goBack} reason="Code samples for this agent could not be loaded." />;
} else if (snippets === undefined) {
@@ -128,6 +133,7 @@ export function AgentDetailsPage({ agentId }: AgentDetailsPageProps) {
{sessionsServer != null && !detailFailed ? (
<AgentDetailsTabs
activeTab={activeTab}
+ showMetrics={metricsServer != null}
onTabChange={tab =>
updateShareSearch({
agentId,
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsTabs.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsTabs.tsx
index a1978e5ee..892d36bae 100644
--- a/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsTabs.tsx
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsTabs.tsx
@@ -8,34 +8,37 @@ const tabs: Array<{ id: AgentDetailsTab; label: string; icon: string }> = [
{ id: 'overview', label: 'Overview', icon: 'info' },
{ id: 'sessions', label: 'Sessions', icon: 'clock-rotate-left' },
{ id: 'code', label: 'Use In Code', icon: 'code' },
+ { id: 'metrics', label: 'Metrics', icon: 'chart' },
];
-export function AgentDetailsTabs({ activeTab, onTabChange }: AgentDetailsTabsProps) {
+export function AgentDetailsTabs({ activeTab, onTabChange, showMetrics = false }: AgentDetailsTabsProps) {
return (
<div
role="tablist"
aria-label="Agent details"
className="flex shrink-0 gap-1 overflow-x-auto border-b border-border bg-primary-bg px-3"
>
- {tabs.map(tab => (
- <button
- key={tab.id}
- type="button"
- role="tab"
- aria-selected={activeTab === tab.id}
- aria-current={activeTab === tab.id ? 'page' : undefined}
- className={cn(
- 'relative flex h-10 shrink-0 cursor-pointer items-center gap-1.5 px-2 text-xs font-medium text-text-secondary',
- 'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-focus-ring',
- activeTab === tab.id &&
- 'text-primary-button-bg after:absolute after:inset-x-0 after:bottom-0 after:h-0.5 after:bg-primary-button-bg',
- )}
- onClick={() => onTabChange(tab.id)}
- >
- <Icon name={tab.icon} className="size-3.5" />
- {tab.label}
- </button>
- ))}
+ {tabs
+ .filter(tab => tab.id !== 'metrics' || showMetrics)
+ .map(tab => (
+ <button
+ key={tab.id}
+ type="button"
+ role="tab"
+ aria-selected={activeTab === tab.id}
+ aria-current={activeTab === tab.id ? 'page' : undefined}
+ className={cn(
+ 'relative flex h-10 shrink-0 cursor-pointer items-center gap-1.5 px-2 text-xs font-medium text-text-secondary',
+ 'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-focus-ring',
+ activeTab === tab.id &&
+ 'text-primary-button-bg after:absolute after:inset-x-0 after:bottom-0 after:h-0.5 after:bg-primary-button-bg',
+ )}
+ onClick={() => onTabChange(tab.id)}
+ >
+ <Icon name={tab.icon} className="size-3.5" />
+ {tab.label}
+ </button>
+ ))}
</div>
);
}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentMetricCard.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentMetricCard.tsx
new file mode 100644
index 000000000..bdba97e8f
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentMetricCard.tsx
@@ -0,0 +1,31 @@
+import type { ComponentType } from 'react';
+
+import { formatCostUsd, formatDurationMs } from '../../utils/sessionDisplayFormat.js';
+import type { AgentMetricCardProps } from './types.js';
+
+const numberFormatter = new Intl.NumberFormat(undefined, { maximumFractionDigits: 4 });
+
+function formatMeterValue(value: number, unit: string): string {
+ if (unit === '$') return formatCostUsd(value);
+ if (unit === 'ms') return formatDurationMs(value);
+ return `${numberFormatter.format(value)}${unit === 'count' || unit.length === 0 ? '' : ` ${unit}`}`;
+}
+
+export function AgentMetricCard({ meter }: AgentMetricCardProps) {
+ return (
+ <section className="min-w-0 rounded-lg border border-border bg-card-bg p-3" data-slot="agent-metric-card">
+ <h3 className="truncate text-xs font-medium text-text-secondary" title={meter.description}>
+ {meter.description}
+ </h3>
+ <p className="mt-2 text-xl font-semibold tabular-nums text-text-primary">
+ {formatMeterValue(meter.aggregateValue, meter.unit)}
+ </p>
+ </section>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentMetricCard: ComponentType<AgentMetricCardProps>;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentMetricChart.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentMetricChart.tsx
new file mode 100644
index 000000000..279fbde3f
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentMetricChart.tsx
@@ -0,0 +1,140 @@
+'use client';
+
+import {
+ CategoryScale,
+ Chart as ChartJS,
+ Legend,
+ LinearScale,
+ LineElement,
+ PointElement,
+ Tooltip,
+ type ChartData,
+ type ChartOptions,
+} from 'chart.js';
+import { useMemo, type ComponentType } from 'react';
+import { Line } from 'react-chartjs-2';
+
+import { useThemeMode } from '../../theme/SlotsProvider.js';
+import { formatCostUsd, formatDurationMs } from '../../utils/sessionDisplayFormat.js';
+import type { AgentMetricChartProps } from './types.js';
+
+ChartJS.register(CategoryScale, LinearScale, LineElement, PointElement, Legend, Tooltip);
+
+const LIGHT_COLORS = ['#2563eb', '#16a34a', '#9333ea', '#ea580c', '#0891b2'];
+const DARK_COLORS = ['#60a5fa', '#4ade80', '#c084fc', '#fb923c', '#22d3ee'];
+const numberFormatter = new Intl.NumberFormat(undefined, { maximumFractionDigits: 4 });
+const timestampFormatter = new Intl.DateTimeFormat(undefined, {
+ month: 'short',
+ day: 'numeric',
+ hour: 'numeric',
+ minute: '2-digit',
+});
+
+function formatValue(value: number, unit: string): string {
+ if (unit === '$') return formatCostUsd(value);
+ if (unit === 'ms') return formatDurationMs(value);
+ return `${numberFormatter.format(value)}${unit === 'count' || unit.length === 0 ? '' : ` ${unit}`}`;
+}
+
+function formatTimestamp(timestamp: string): string {
+ const date = new Date(timestamp);
+ return Number.isNaN(date.getTime()) ? timestamp : timestampFormatter.format(date);
+}
+
+export function AgentMetricChart({ graph, definition, error }: AgentMetricChartProps) {
+ const mode = useThemeMode();
+ const colors = mode === 'dark' ? DARK_COLORS : LIGHT_COLORS;
+ const axisColor = mode === 'dark' ? '#a1a1aa' : '#71717a';
+ const gridColor = mode === 'dark' ? '#27272a' : '#e4e4e7';
+ const labels = useMemo(
+ () =>
+ graph == null
+ ? []
+ : [...new Set(graph.graphLines.flatMap(line => line.values.map(point => point.timestamp)))].sort(),
+ [graph],
+ );
+ const data = useMemo<ChartData<'line', Array<number | null>, string>>(
+ () => ({
+ labels: labels.map(formatTimestamp),
+ datasets:
+ graph?.graphLines.map((line, index) => {
+ const valuesByTimestamp = new Map(line.values.map(point => [point.timestamp, point.value]));
+ const color = colors[index % colors.length];
+ return {
+ label: line.name,
+ data: labels.map(timestamp => valuesByTimestamp.get(timestamp) ?? null),
+ borderColor: color,
+ backgroundColor: color,
+ pointRadius: 2,
+ pointHoverRadius: 4,
+ borderWidth: 2,
+ tension: 0.25,
+ spanGaps: true,
+ };
+ }) ?? [],
+ }),
+ [colors, graph, labels],
+ );
+ const options = useMemo<ChartOptions<'line'>>(
+ () => ({
+ responsive: true,
+ maintainAspectRatio: false,
+ animation: false,
+ interaction: { intersect: false, mode: 'index' },
+ plugins: {
+ legend: {
+ display: (graph?.graphLines.length ?? 0) > 1,
+ labels: { color: axisColor, boxWidth: 10, boxHeight: 2 },
+ },
+ tooltip: {
+ callbacks: {
+ label: context => {
+ const value = context.parsed.y;
+ return `${context.dataset.label ?? ''}: ${value == null ? '—' : formatValue(value, graph?.unit ?? '')}`;
+ },
+ },
+ },
+ },
+ scales: {
+ x: {
+ grid: { display: false },
+ border: { color: gridColor },
+ ticks: { color: axisColor, maxRotation: 0, autoSkip: true, maxTicksLimit: 8 },
+ },
+ y: {
+ beginAtZero: true,
+ grid: { color: gridColor },
+ border: { display: false },
+ ticks: {
+ color: axisColor,
+ callback: value => formatValue(Number(value), graph?.unit ?? ''),
+ },
+ },
+ },
+ }),
+ [axisColor, graph, gridColor],
+ );
+ const hasData = graph?.graphLines.some(line => line.values.length > 0) === true;
+
+ return (
+ <section className="min-w-0 rounded-lg border border-border bg-card-bg p-4" data-slot="agent-metric-chart">
+ <h3 className="text-sm font-semibold text-text-primary">{graph?.displayName ?? definition.displayName}</h3>
+ <p className="mt-1 text-xs text-text-secondary">{graph?.description ?? definition.description}</p>
+ <div className="mt-4 h-64">
+ {error != null ? (
+ <div className="flex h-full items-center justify-center text-sm text-failure-bg">{error}</div>
+ ) : hasData ? (
+ <Line data={data} options={options} />
+ ) : (
+ <div className="flex h-full items-center justify-center text-sm text-text-secondary">No data</div>
+ )}
+ </div>
+ </section>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentMetricChart: ComponentType<AgentMetricChartProps>;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentMetricsTimeRangeFilter.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentMetricsTimeRangeFilter.tsx
new file mode 100644
index 000000000..e26b9e41e
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentMetricsTimeRangeFilter.tsx
@@ -0,0 +1,25 @@
+import type { ComponentType } from 'react';
+
+import { useSlot } from '../../theme/SlotsProvider.js';
+import type { AgentMetricsTimeRangeFilterProps } from './types.js';
+
+export function AgentMetricsTimeRangeFilter({ timeRange, onTimeRangeChange }: AgentMetricsTimeRangeFilterProps) {
+ const AgentSessionsFilters = useSlot('AgentSessionsFilters');
+
+ return (
+ <AgentSessionsFilters
+ agentId={null}
+ timeRange={timeRange}
+ onAgentChange={() => undefined}
+ onTimeRangeChange={onTimeRangeChange}
+ showAgentFilter={false}
+ showCustomTimeRange={false}
+ />
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentMetricsTimeRangeFilter: ComponentType<AgentMetricsTimeRangeFilterProps>;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentMetricsView.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentMetricsView.tsx
new file mode 100644
index 000000000..9b98c55bd
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentMetricsView.tsx
@@ -0,0 +1,88 @@
+'use client';
+
+import type { ComponentType } from 'react';
+
+import { useSlot } from '../../theme/SlotsProvider.js';
+import { Skeleton } from '../primitives/Skeleton.js';
+import type { AgentMetricsViewProps } from './types.js';
+
+export function AgentMetricsView({
+ meters,
+ meterError,
+ charts,
+ chartsLoading,
+ chartsError,
+ timeRange,
+ onTimeRangeChange,
+}: AgentMetricsViewProps) {
+ const AgentMetricCard = useSlot('AgentMetricCard');
+ const AgentMetricChart = useSlot('AgentMetricChart');
+ const AgentMetricsTimeRangeFilter = useSlot('AgentMetricsTimeRangeFilter');
+
+ return (
+ <div className="min-h-0 flex-1 overflow-auto p-4" data-slot="agent-metrics-view">
+ <div className="mb-4 flex justify-end">
+ <AgentMetricsTimeRangeFilter timeRange={timeRange} onTimeRangeChange={onTimeRangeChange} />
+ </div>
+
+ {meterError != null ? (
+ <div className="mb-4 rounded-lg border border-failure-bg/30 bg-failure-bg/10 p-3 text-sm text-failure-bg">
+ {meterError}
+ </div>
+ ) : meters == null ? (
+ <div className="mb-4 grid grid-cols-2 gap-3 md:grid-cols-3 xl:grid-cols-4" aria-label="Loading metrics">
+ {Array.from({ length: 4 }, (_, index) => (
+ <Skeleton key={index} className="h-20 rounded-lg" />
+ ))}
+ </div>
+ ) : meters.length === 0 ? (
+ <div className="mb-4 rounded-lg border border-border bg-card-bg p-6 text-center text-sm text-text-secondary">
+ No aggregate metrics
+ </div>
+ ) : (
+ <div className="mb-4 grid grid-cols-2 gap-3 md:grid-cols-3 xl:grid-cols-4">
+ {meters.map(meter => (
+ <AgentMetricCard key={meter.name} meter={meter} />
+ ))}
+ </div>
+ )}
+
+ {chartsError != null ? (
+ <div className="rounded-lg border border-failure-bg/30 bg-failure-bg/10 p-3 text-sm text-failure-bg">
+ {chartsError}
+ </div>
+ ) : chartsLoading && charts.length === 0 ? (
+ <div className="grid gap-4 lg:grid-cols-2" aria-label="Loading metric charts">
+ {Array.from({ length: 2 }, (_, index) => (
+ <Skeleton key={index} className="h-80 rounded-lg" />
+ ))}
+ </div>
+ ) : charts.length === 0 ? (
+ <div className="rounded-lg border border-border bg-card-bg p-6 text-center text-sm text-text-secondary">
+ No charts available
+ </div>
+ ) : (
+ <div className="grid gap-4 lg:grid-cols-2">
+ {charts.flatMap(chart =>
+ chart.graphs != null && chart.graphs.length > 0
+ ? chart.graphs.map(graph => (
+ <AgentMetricChart
+ key={`${chart.definition.name}:${graph.name}`}
+ definition={chart.definition}
+ graph={graph}
+ error={chart.error}
+ />
+ ))
+ : [<AgentMetricChart key={chart.definition.name} definition={chart.definition} error={chart.error} />],
+ )}
+ </div>
+ )}
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentMetricsView: ComponentType<AgentMetricsViewProps>;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionsFilters.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionsFilters.tsx
index cfddab0e8..440f67dad 100644
--- a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionsFilters.tsx
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionsFilters.tsx
@@ -30,6 +30,8 @@ export type AgentSessionsFiltersProps = {
timeRange: SessionTimeRange;
onAgentChange: (agentId: string | null) => void;
onTimeRangeChange: (range: SessionTimeRange) => void;
+ showAgentFilter?: boolean;
+ showCustomTimeRange?: boolean;
};
export function AgentSessionsFilters({
@@ -37,6 +39,8 @@ export function AgentSessionsFilters({
timeRange,
onAgentChange,
onTimeRangeChange,
+ showAgentFilter = true,
+ showCustomTimeRange = true,
}: AgentSessionsFiltersProps) {
const server = useOptionalServer();
const shell = useOptionalShellMode();
@@ -48,7 +52,7 @@ export function AgentSessionsFilters({
const popoverRef = useRef<HTMLDivElement>(null);
useEffect(() => {
- if (server == null) return undefined;
+ if (!showAgentFilter || server == null) return undefined;
let cancelled = false;
void searchAllAgents(server).then(
rows => {
@@ -59,7 +63,7 @@ export function AgentSessionsFilters({
return () => {
cancelled = true;
};
- }, [server, shell?.agentsListEpoch]);
+ }, [server, shell?.agentsListEpoch, showAgentFilter]);
useEffect(() => {
setFromValue(toDateTimeLocalValue(timeRange.startTs));
@@ -106,25 +110,27 @@ export function AgentSessionsFilters({
return (
<div className="flex min-w-0 items-center gap-2">
- <label className="flex items-center gap-1 text-xs text-text-secondary">
- Agents
- <select
- aria-label="Filter sessions by agent"
- className="h-8 max-w-36 rounded-md border border-border bg-primary-bg px-2 text-xs text-text-primary"
- value={agentId ?? ''}
- onChange={event => onAgentChange(event.target.value.length === 0 ? null : event.target.value)}
- >
- <option value="">All</option>
- {agents.map(agent => {
- const id = agent.agentId ?? agent.name;
- return (
- <option key={id} value={id}>
- {agent.name}
- </option>
- );
- })}
- </select>
- </label>
+ {showAgentFilter ? (
+ <label className="flex items-center gap-1 text-xs text-text-secondary">
+ Agents
+ <select
+ aria-label="Filter sessions by agent"
+ className="h-8 max-w-36 rounded-md border border-border bg-primary-bg px-2 text-xs text-text-primary"
+ value={agentId ?? ''}
+ onChange={event => onAgentChange(event.target.value.length === 0 ? null : event.target.value)}
+ >
+ <option value="">All</option>
+ {agents.map(agent => {
+ const id = agent.agentId ?? agent.name;
+ return (
+ <option key={id} value={id}>
+ {agent.name}
+ </option>
+ );
+ })}
+ </select>
+ </label>
+ ) : null}
<div className="relative" ref={popoverRef}>
<button
type="button"
@@ -179,18 +185,20 @@ export function AgentSessionsFilters({
</div>
) : null}
<div className="flex max-h-80 w-44 shrink-0 flex-col overflow-y-auto py-1" role="listbox">
- <button
- type="button"
- className={cn(
- 'px-3 py-2 text-left text-xs',
- timeRange.timeWindowMs == null
- ? 'bg-dropdown-selected-item-bg text-dropdown-selected-item-text'
- : 'text-text-primary hover:bg-ghost-button-hover',
- )}
- onClick={() => setCustomPickerOpen(true)}
- >
- Custom Time Range
- </button>
+ {showCustomTimeRange ? (
+ <button
+ type="button"
+ className={cn(
+ 'px-3 py-2 text-left text-xs',
+ timeRange.timeWindowMs == null
+ ? 'bg-dropdown-selected-item-bg text-dropdown-selected-item-text'
+ : 'text-text-primary hover:bg-ghost-button-hover',
+ )}
+ onClick={() => setCustomPickerOpen(true)}
+ >
+ Custom Time Range
+ </button>
+ ) : null}
{SESSION_TIME_PRESETS.map(preset => (
<button
key={preset.windowMs}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/types.ts b/packages/trueforge-ui/src/atoms/agent-details/types.ts
index b3e27b162..3f068228b 100644
--- a/packages/trueforge-ui/src/atoms/agent-details/types.ts
+++ b/packages/trueforge-ui/src/atoms/agent-details/types.ts
@@ -1,8 +1,14 @@
import type { ReactNode } from 'react';
-import type { AgentDetail, CodeSnippet } from '../../server/types.js';
+import type {
+ AgentDetail,
+ AgentMetricChartDefinition,
+ AgentMetricGraph,
+ AgentMetricMeter,
+ CodeSnippet,
+} from '../../server/types.js';
import type { SessionMetrics } from '../../utils/buildSessionMetrics.js';
import type { SessionEventTimelineSegment, SessionEventType } from '../../utils/sessionEventTimeline.js';
-import type { LibraryAgentTab } from '../../utils/sessionShareUrl.js';
+import type { LibraryAgentTab, SessionTimeRange } from '../../utils/sessionShareUrl.js';
import type { SessionTurnView } from '../../utils/sessionTurnViews.js';
export type AgentSessionsProps = {
@@ -75,6 +81,42 @@ export type AgentDetailsHeaderProps = {
export type AgentDetailsTabsProps = {
activeTab: AgentDetailsTab;
onTabChange: (tab: AgentDetailsTab) => void;
+ showMetrics?: boolean;
+};
+
+export type AgentMetricsProps = {
+ agentId: string;
+};
+
+export type AgentMetricChartResult = {
+ definition: AgentMetricChartDefinition;
+ graphs?: AgentMetricGraph[];
+ error?: string;
+};
+
+export type AgentMetricsViewProps = {
+ meters?: AgentMetricMeter[];
+ meterError?: string;
+ charts: AgentMetricChartResult[];
+ chartsLoading: boolean;
+ chartsError?: string;
+ timeRange: SessionTimeRange;
+ onTimeRangeChange: (range: SessionTimeRange) => void;
+};
+
+export type AgentMetricsTimeRangeFilterProps = {
+ timeRange: SessionTimeRange;
+ onTimeRangeChange: (range: SessionTimeRange) => void;
+};
+
+export type AgentMetricCardProps = {
+ meter: AgentMetricMeter;
+};
+
+export type AgentMetricChartProps = {
+ graph?: AgentMetricGraph;
+ definition: AgentMetricChartDefinition;
+ error?: string;
};
export type AgentOverviewProps = {
diff --git a/packages/trueforge-ui/src/containers/AgentMetricsContainer.tsx b/packages/trueforge-ui/src/containers/AgentMetricsContainer.tsx
new file mode 100644
index 000000000..a1026dd75
--- /dev/null
+++ b/packages/trueforge-ui/src/containers/AgentMetricsContainer.tsx
@@ -0,0 +1,121 @@
+'use client';
+
+import { useEffect, useState, type ComponentType } from 'react';
+
+import type { AgentMetricChartResult, AgentMetricsProps } from '../atoms/agent-details/types.js';
+import { useAgentMetricsServer } from '../server/ServerContext.js';
+import type { AgentMetricChartDefinition, AgentMetricMeter } from '../server/types.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+import { getErrorMessage } from '../utils/getErrorMessage.js';
+import { resolveSessionTimeRange, type SessionTimeRange } from '../utils/sessionShareUrl.js';
+
+const DEFAULT_METRICS_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+export function AgentMetricsContainer({ agentId }: AgentMetricsProps) {
+ const metricsServer = useAgentMetricsServer();
+ const AgentMetricsView = useSlot('AgentMetricsView');
+ const [timeRange, setTimeRange] = useState<SessionTimeRange>(() => {
+ const endTs = Date.now();
+ return {
+ startTs: endTs - DEFAULT_METRICS_WINDOW_MS,
+ endTs,
+ timeWindowMs: DEFAULT_METRICS_WINDOW_MS,
+ };
+ });
+ const [definitions, setDefinitions] = useState<AgentMetricChartDefinition[]>();
+ const [chartsError, setChartsError] = useState<string>();
+ const [meters, setMeters] = useState<AgentMetricMeter[]>();
+ const [meterError, setMeterError] = useState<string>();
+ const [charts, setCharts] = useState<AgentMetricChartResult[]>([]);
+ const [chartsLoading, setChartsLoading] = useState(true);
+
+ useEffect(() => {
+ let cancelled = false;
+ setDefinitions(undefined);
+ setChartsError(undefined);
+ void metricsServer.getCharts().then(
+ result => {
+ if (!cancelled) setDefinitions(result);
+ },
+ error => {
+ if (!cancelled) {
+ setDefinitions([]);
+ setChartsError(getErrorMessage(error, 'Metric charts could not be loaded.'));
+ setChartsLoading(false);
+ }
+ },
+ );
+ return () => {
+ cancelled = true;
+ };
+ }, [metricsServer]);
+
+ useEffect(() => {
+ if (definitions == null) return undefined;
+ let cancelled = false;
+ const resolvedRange = resolveSessionTimeRange(timeRange);
+ const request = {
+ agentId,
+ startTimestamp: new Date(resolvedRange.startTs).toISOString(),
+ endTimestamp: new Date(resolvedRange.endTs).toISOString(),
+ };
+
+ setMeters(undefined);
+ setMeterError(undefined);
+ setCharts(definitions.map(definition => ({ definition })));
+ setChartsLoading(true);
+
+ void metricsServer.getMeters(request).then(
+ result => {
+ if (!cancelled) setMeters(result);
+ },
+ error => {
+ if (!cancelled) setMeterError(getErrorMessage(error, 'Aggregate metrics could not be loaded.'));
+ },
+ );
+
+ void Promise.all(
+ definitions.map(async definition => {
+ try {
+ const data = await metricsServer.getChartData({
+ ...request,
+ chartName: definition.name,
+ });
+ return { definition, graphs: data.graphs } satisfies AgentMetricChartResult;
+ } catch (error) {
+ return {
+ definition,
+ error: getErrorMessage(error, `${definition.displayName} could not be loaded.`),
+ } satisfies AgentMetricChartResult;
+ }
+ }),
+ ).then(result => {
+ if (!cancelled) {
+ setCharts(result);
+ setChartsLoading(false);
+ }
+ });
+
+ return () => {
+ cancelled = true;
+ };
+ }, [agentId, definitions, metricsServer, timeRange]);
+
+ return (
+ <AgentMetricsView
+ meters={meters}
+ meterError={meterError}
+ charts={charts}
+ chartsLoading={chartsLoading}
+ chartsError={chartsError}
+ timeRange={timeRange}
+ onTimeRangeChange={setTimeRange}
+ />
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentMetrics: ComponentType<AgentMetricsProps>;
+ }
+}
diff --git a/packages/trueforge-ui/src/icons/IconRegistry.tsx b/packages/trueforge-ui/src/icons/IconRegistry.tsx
index 923f97853..0ce6efa9b 100644
--- a/packages/trueforge-ui/src/icons/IconRegistry.tsx
+++ b/packages/trueforge-ui/src/icons/IconRegistry.tsx
@@ -26,6 +26,7 @@ import {
History,
Info,
Lightbulb,
+ LineChart,
Link2,
ListChecks,
ListFilter,
@@ -165,6 +166,7 @@ const defaults: Record<string, IconEntry> = {
brain: Brain,
terminal: Terminal,
code: Code2,
+ chart: LineChart,
expand: Maximize2,
'expand-alt': Maximize2,
compress: Minimize2,
diff --git a/packages/trueforge-ui/src/index.ts b/packages/trueforge-ui/src/index.ts
index 54b0f732c..6f97b8f51 100644
--- a/packages/trueforge-ui/src/index.ts
+++ b/packages/trueforge-ui/src/index.ts
@@ -239,8 +239,10 @@ export {
export type { CustomActionRendererProps, CustomActionRenderers } from './server/CustomActionRenderersContext.js';
export {
ServerProvider,
+ useAgentMetricsServer,
useAgentSessionsServer,
useCatalogServer,
+ useOptionalAgentMetricsServer,
useOptionalAgentSessionsServer,
useOptionalCatalogServer,
useOptionalServer,
@@ -262,6 +264,16 @@ export type {
AgentChatServer,
AgentDetail,
AgentLibraryEntry,
+ AgentMetricChartData,
+ AgentMetricChartDataRequest,
+ AgentMetricChartDefinition,
+ AgentMetricChartType,
+ AgentMetricGraph,
+ AgentMetricGraphLine,
+ AgentMetricMeter,
+ AgentMetricPoint,
+ AgentMetricRangeRequest,
+ AgentMetricsServer,
AgentSessionsServer,
AgentSkill,
AgentSpec,
@@ -356,6 +368,10 @@ export { AgentDetailsHeader } from './atoms/agent-details/AgentDetailsHeader.js'
export { AgentDetailsPage } from './atoms/agent-details/AgentDetailsPage.js';
export { AgentDetailsTabs } from './atoms/agent-details/AgentDetailsTabs.js';
export { AgentDetailsUnavailable } from './atoms/agent-details/AgentDetailsUnavailable.js';
+export { AgentMetricCard } from './atoms/agent-details/AgentMetricCard.js';
+export { AgentMetricChart } from './atoms/agent-details/AgentMetricChart.js';
+export { AgentMetricsTimeRangeFilter } from './atoms/agent-details/AgentMetricsTimeRangeFilter.js';
+export { AgentMetricsView } from './atoms/agent-details/AgentMetricsView.js';
export { AgentOverviewCard } from './atoms/agent-details/AgentOverviewCard.js';
export type {
AgentCodeBlockProps,
@@ -365,6 +381,12 @@ export type {
AgentDetailsTab,
AgentDetailsTabsProps,
AgentDetailsUnavailableProps,
+ AgentMetricCardProps,
+ AgentMetricChartProps,
+ AgentMetricChartResult,
+ AgentMetricsProps,
+ AgentMetricsTimeRangeFilterProps,
+ AgentMetricsViewProps,
AgentOverviewCardProps,
AgentOverviewProps,
AgentSessionDetailHeaderProps,
@@ -375,6 +397,7 @@ export type {
AgentSessionTurnHeaderProps,
AgentSessionsProps,
} from './atoms/agent-details/types.js';
+export { AgentMetricsContainer } from './containers/AgentMetricsContainer.js';
export type { SessionEventTimelineSegment, SessionEventType } from './utils/sessionEventTimeline.js';
export type { SessionTurnView } from './utils/sessionTurnViews.js';
diff --git a/packages/trueforge-ui/src/layouts/DrawerLayout.tsx b/packages/trueforge-ui/src/layouts/DrawerLayout.tsx
index a2645f385..1d7e6b519 100644
--- a/packages/trueforge-ui/src/layouts/DrawerLayout.tsx
+++ b/packages/trueforge-ui/src/layouts/DrawerLayout.tsx
@@ -36,6 +36,10 @@ export function DrawerLayout({ className }: { className?: string }) {
const sessionsOpen = shell?.sessionsOpen === true;
const overlayOpen = settingsOpen || libraryOpen || sessionsOpen;
+ useEffect(() => {
+ if (libraryOpen || sessionsOpen) setThreadsOpen(false);
+ }, [libraryOpen, sessionsOpen]);
+
useEffect(() => {
if (!threadsOpen) return;
const onKeyDown = (event: KeyboardEvent) => {
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/agentMetricsServer.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/agentMetricsServer.ts
new file mode 100644
index 000000000..dcfdc4cf9
--- /dev/null
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/agentMetricsServer.ts
@@ -0,0 +1,45 @@
+import type { TrueForge, TrueForgeApi } from '@truefoundry/trueforge-sdk';
+
+import type { AgentMetricsServer } from '../../server/types.js';
+import { createTrueForgeClient, parseIsoDate, type CreateTrueForgeClientOptions } from './client.js';
+
+export type CreateHarnessAgentMetricsServerOptions = CreateTrueForgeClientOptions & {
+ client?: TrueForge;
+};
+
+function toHarnessChartName(name: string): TrueForgeApi.SessionMetricsChartName {
+ if (name === 'sessions_over_time' || name === 'sessions_cost_over_time' || name === 'turns_over_time') {
+ return name;
+ }
+ throw new Error(`Unsupported Harness metrics chart: ${name}`);
+}
+
+export function createHarnessAgentMetricsServer(
+ options: CreateHarnessAgentMetricsServerOptions = {},
+): AgentMetricsServer {
+ const client = options.client ?? createTrueForgeClient(options);
+
+ return {
+ async getCharts() {
+ const { data } = await client.internal.metrics.listCharts();
+ return data.charts;
+ },
+ async getMeters({ agentId, startTimestamp, endTimestamp }) {
+ const { data } = await client.internal.metrics.getMeters({
+ agentId,
+ startTimestamp: parseIsoDate(startTimestamp),
+ endTimestamp: parseIsoDate(endTimestamp),
+ });
+ return data.meters;
+ },
+ async getChartData({ agentId, startTimestamp, endTimestamp, chartName }) {
+ const { data } = await client.internal.metrics.getChartData({
+ agentId,
+ startTimestamp: parseIsoDate(startTimestamp),
+ endTimestamp: parseIsoDate(endTimestamp),
+ chartName: toHarnessChartName(chartName),
+ });
+ return data;
+ },
+ };
+}
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/agentSessionsServer.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/agentSessionsServer.ts
index 2f31b625f..14843d745 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/agentSessionsServer.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/agentSessionsServer.ts
@@ -1,7 +1,7 @@
import type { TrueForge, TrueForgeApi } from '@truefoundry/trueforge-sdk';
import type { AgentSessionsServer, SessionListEntry } from '../../server/types.js';
import { toListResult, toUiAgentSpec } from './chatServer.js';
-import { createTrueForgeClient, type CreateTrueForgeClientOptions } from './client.js';
+import { createTrueForgeClient, parseIsoDate, type CreateTrueForgeClientOptions } from './client.js';
import { toUiEventItem } from './toUiTurnState.js';
import type { HarnessAgentSpec } from './types.js';
@@ -9,27 +9,16 @@ export type CreateHarnessAgentSessionsServerOptions = CreateTrueForgeClientOptio
client?: TrueForge;
};
-function toIsoDate(value: string): Date {
- const date = new Date(value);
- if (Number.isNaN(date.getTime())) {
- throw new Error(`Invalid ISO timestamp: ${value}`);
- }
- return date;
-}
-
function toSessionListEntry(session: TrueForgeApi.Session): SessionListEntry<HarnessAgentSpec> {
return {
id: session.id,
createdAt: session.createdAt,
updatedAt: session.updatedAt,
lastActivityAt: session.updatedAt,
- // TrueForge listSessions (packages/trueforge/src/apis/sessions.ts) and SessionSchema
- // (packages/trueforge-core/src/agent-session/schemas/session.ts) have no aggregate
- // metrics field yet, so the UI contract stays zero until that API exists.
metrics: {
- totalTurns: 0,
- totalCostInUsd: 0,
- totalDurationMs: 0,
+ totalTurns: session.metrics.totalTurns,
+ totalCostInUsd: session.metrics.totalCostInUsd,
+ totalDurationMs: session.metrics.totalDurationMs,
},
...(session.title === null ? {} : { title: session.title }),
...(session.agent.type === 'reference' && session.agent.name !== null ? { agentName: session.agent.name } : {}),
@@ -62,8 +51,8 @@ export function createHarnessAgentSessionsServer(
...(requestParams.pageToken === undefined ? {} : { pageToken: requestParams.pageToken }),
...(requestParams.startTimestamp === undefined
? {}
- : { startTimestamp: toIsoDate(requestParams.startTimestamp) }),
- ...(requestParams.endTimestamp === undefined ? {} : { endTimestamp: toIsoDate(requestParams.endTimestamp) }),
+ : { startTimestamp: parseIsoDate(requestParams.startTimestamp) }),
+ ...(requestParams.endTimestamp === undefined ? {} : { endTimestamp: parseIsoDate(requestParams.endTimestamp) }),
...(requestParams.agentId === undefined || requestParams.agentId.length === 0
? {}
: { agentId: requestParams.agentId }),
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/client.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/client.ts
index c4e6ca47f..0430fc710 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/client.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/client.ts
@@ -34,3 +34,11 @@ export function createTrueForgeClient(options: CreateTrueForgeClientOptions = {}
...(options.fetch === undefined ? {} : { fetch: options.fetch }),
});
}
+
+export function parseIsoDate(value: string): Date {
+ const date = new Date(value);
+ if (Number.isNaN(date.getTime())) {
+ throw new Error(`Invalid ISO timestamp: ${value}`);
+ }
+ return date;
+}
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/index.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/index.ts
index 7f948e9a0..47406fea1 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/index.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/index.ts
@@ -3,6 +3,7 @@
*/
import { createTrueFoundryServer } from '../../server/createTrueFoundryServer.js';
import type { CatalogServer } from '../../server/types.js';
+import { createHarnessAgentMetricsServer } from './agentMetricsServer.js';
import { createHarnessAgentSessionsServer } from './agentSessionsServer.js';
import { createHarnessBuilderServer } from './builderServer.js';
import { createConnectorCatalog } from './catalogs/connectorCatalog.js';
@@ -13,6 +14,7 @@ import { createHarnessChatServer } from './chatServer.js';
import { createTrueForgeClient, type CreateTrueForgeClientOptions } from './client.js';
import type { HarnessAgentSpec } from './types.js';
+export { createHarnessAgentMetricsServer, type CreateHarnessAgentMetricsServerOptions } from './agentMetricsServer.js';
export {
createHarnessAgentSessionsServer,
type CreateHarnessAgentSessionsServerOptions,
@@ -81,5 +83,6 @@ export function createTrueForgeAgentUIServer(options: CreateTrueForgeAgentUIServ
...createHarnessBuilderServer({ client }),
catalog,
sessions: createHarnessAgentSessionsServer({ ...clientOptions, client }),
+ metrics: createHarnessAgentMetricsServer({ ...clientOptions, client }),
});
}
diff --git a/packages/trueforge-ui/src/server/ServerContext.tsx b/packages/trueforge-ui/src/server/ServerContext.tsx
index 6b19b640b..5e8110b2c 100644
--- a/packages/trueforge-ui/src/server/ServerContext.tsx
+++ b/packages/trueforge-ui/src/server/ServerContext.tsx
@@ -2,7 +2,13 @@
import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
-import type { AgentBuilderCapabilitiesResponse, AgentSessionsServer, AgentUIServer, CatalogServer } from './types.js';
+import type {
+ AgentBuilderCapabilitiesResponse,
+ AgentMetricsServer,
+ AgentSessionsServer,
+ AgentUIServer,
+ CatalogServer,
+} from './types.js';
const ServerContext = createContext<AgentUIServer | null>(null);
const ServerCapabilitiesContext = createContext<{
@@ -92,3 +98,15 @@ export function useAgentSessionsServer(): AgentSessionsServer {
export function useOptionalAgentSessionsServer(): AgentSessionsServer | null {
return useOptionalServer()?.sessions ?? null;
}
+
+export function useAgentMetricsServer(): AgentMetricsServer {
+ const metrics = useServer().metrics;
+ if (metrics == null) {
+ throw new Error('useAgentMetricsServer requires AgentUIServer.metrics.');
+ }
+ return metrics;
+}
+
+export function useOptionalAgentMetricsServer(): AgentMetricsServer | null {
+ return useOptionalServer()?.metrics ?? null;
+}
diff --git a/packages/trueforge-ui/src/server/createTrueFoundryServer.ts b/packages/trueforge-ui/src/server/createTrueFoundryServer.ts
index 14fe8c24a..ed342ba73 100644
--- a/packages/trueforge-ui/src/server/createTrueFoundryServer.ts
+++ b/packages/trueforge-ui/src/server/createTrueFoundryServer.ts
@@ -3,6 +3,7 @@ import type {
AgentBuilderServer,
AgentChatServer,
AgentLibraryEntry,
+ AgentMetricsServer,
AgentSessionsServer,
AgentSkill,
AgentSpec,
@@ -24,6 +25,7 @@ export type CreateTrueFoundryServerOptions<
TCatalog extends CatalogServer = CatalogServer,
TCapabilities extends AgentBuilderCapabilitiesResponse = AgentBuilderCapabilitiesResponse,
TSessions extends AgentSessionsServer<TSpec> = AgentSessionsServer<TSpec>,
+ TMetrics extends AgentMetricsServer = AgentMetricsServer,
> = {
/** Chat port — e.g. from `@truefoundry/agent-server-adapter`. */
chatServer: AgentChatServer<TSpec>;
@@ -38,6 +40,8 @@ export type CreateTrueFoundryServerOptions<
catalog?: TCatalog;
/** Optional agent-detail port (Overview + Use In Code). */
sessions?: TSessions;
+ /** Optional aggregate metrics + chart port. */
+ metrics?: TMetrics;
};
export type TrueFoundryServer<
@@ -50,10 +54,12 @@ export type TrueFoundryServer<
TCatalog extends CatalogServer = CatalogServer,
TCapabilities extends AgentBuilderCapabilitiesResponse = AgentBuilderCapabilitiesResponse,
TSessions extends AgentSessionsServer<TSpec> = AgentSessionsServer<TSpec>,
+ TMetrics extends AgentMetricsServer = AgentMetricsServer,
> = AgentChatServer<TSpec> &
AgentBuilderServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCapabilities> & {
catalog?: TCatalog;
sessions?: TSessions;
+ metrics?: TMetrics;
};
/**
@@ -71,9 +77,21 @@ export function createTrueFoundryServer<
TCatalog extends CatalogServer = CatalogServer,
TCapabilities extends AgentBuilderCapabilitiesResponse = AgentBuilderCapabilitiesResponse,
TSessions extends AgentSessionsServer<TSpec> = AgentSessionsServer<TSpec>,
+ TMetrics extends AgentMetricsServer = AgentMetricsServer,
>(
- opts: CreateTrueFoundryServerOptions<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCatalog, TCapabilities, TSessions>,
-): TrueFoundryServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCatalog, TCapabilities, TSessions> {
+ opts: CreateTrueFoundryServerOptions<
+ TSpec,
+ TModel,
+ TSkill,
+ TMcp,
+ TAgent,
+ TSave,
+ TCatalog,
+ TCapabilities,
+ TSessions,
+ TMetrics
+ >,
+): TrueFoundryServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCatalog, TCapabilities, TSessions, TMetrics> {
const builder: AgentBuilderServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCapabilities> = {
getCapabilities: opts.getCapabilities,
getModels: opts.getModels,
@@ -90,11 +108,23 @@ export function createTrueFoundryServer<
},
};
- const server: TrueFoundryServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCatalog, TCapabilities, TSessions> = {
+ const server: TrueFoundryServer<
+ TSpec,
+ TModel,
+ TSkill,
+ TMcp,
+ TAgent,
+ TSave,
+ TCatalog,
+ TCapabilities,
+ TSessions,
+ TMetrics
+ > = {
...opts.chatServer,
...builder,
...(opts.catalog != null ? { catalog: opts.catalog } : {}),
...(opts.sessions != null ? { sessions: opts.sessions } : {}),
+ ...(opts.metrics != null ? { metrics: opts.metrics } : {}),
};
return server;
}
diff --git a/packages/trueforge-ui/src/server/types.ts b/packages/trueforge-ui/src/server/types.ts
index 0cf0658a9..334a3f7ec 100644
--- a/packages/trueforge-ui/src/server/types.ts
+++ b/packages/trueforge-ui/src/server/types.ts
@@ -14,6 +14,16 @@ export type {
AgentChatServer,
AgentDetail,
AgentLibraryEntry,
+ AgentMetricChartData,
+ AgentMetricChartDataRequest,
+ AgentMetricChartDefinition,
+ AgentMetricChartType,
+ AgentMetricGraph,
+ AgentMetricGraphLine,
+ AgentMetricMeter,
+ AgentMetricPoint,
+ AgentMetricRangeRequest,
+ AgentMetricsServer,
AgentRuntimeConfig,
AgentSessionsServer,
AgentSkill,
diff --git a/packages/trueforge-ui/src/theme/defaultSlots.ts b/packages/trueforge-ui/src/theme/defaultSlots.ts
index dd15c9629..df5a1859d 100644
--- a/packages/trueforge-ui/src/theme/defaultSlots.ts
+++ b/packages/trueforge-ui/src/theme/defaultSlots.ts
@@ -12,6 +12,9 @@ import { AgentDetailsHeader } from '../atoms/agent-details/AgentDetailsHeader.js
import { AgentDetailsPage } from '../atoms/agent-details/AgentDetailsPage.js';
import { AgentDetailsTabs } from '../atoms/agent-details/AgentDetailsTabs.js';
import { AgentDetailsUnavailable } from '../atoms/agent-details/AgentDetailsUnavailable.js';
+import { AgentMetricCard } from '../atoms/agent-details/AgentMetricCard.js';
+import { AgentMetricsTimeRangeFilter } from '../atoms/agent-details/AgentMetricsTimeRangeFilter.js';
+import { AgentMetricsView } from '../atoms/agent-details/AgentMetricsView.js';
import { AgentOverviewCard } from '../atoms/agent-details/AgentOverviewCard.js';
import { AgentSessionDetailHeader } from '../atoms/agent-details/AgentSessionDetailHeader.js';
import { AgentSessionListRow } from '../atoms/agent-details/AgentSessionListRow.js';
@@ -21,6 +24,7 @@ import { AgentSessionTurnHeader } from '../atoms/agent-details/AgentSessionTurnH
import { SessionsPage } from '../atoms/agent-details/SessionsPage.js';
import type {
AgentCodeSnippetsProps,
+ AgentMetricChartProps,
AgentOverviewProps,
AgentSessionEventTimelineChartProps,
AgentSessionEventTimelineProps,
@@ -75,6 +79,7 @@ import { UserMessageActionBar } from '../atoms/UserMessageActionBar.js';
import { UserMessageBubble } from '../atoms/UserMessageBubble.js';
import { UserMessageEdit } from '../atoms/UserMessageEdit.js';
import { WelcomeScreen } from '../atoms/WelcomeScreen.js';
+import { AgentMetricsContainer } from '../containers/AgentMetricsContainer.js';
import { AgentSessionTimelineContainer } from '../containers/AgentSessionTimelineContainer.js';
import { BrandLogo } from './brand.js';
import type { AtomSlots } from './SlotsProvider.js';
@@ -95,6 +100,10 @@ const AgentSessionEventTimelineChart: ComponentType<AgentSessionEventTimelineCha
const mod = await import('../atoms/agent-details/AgentSessionEventTimelineChart.js');
return { default: mod.AgentSessionEventTimelineChart };
});
+const AgentMetricChart: ComponentType<AgentMetricChartProps> = lazy(async () => {
+ const mod = await import('../atoms/agent-details/AgentMetricChart.js');
+ return { default: mod.AgentMetricChart };
+});
// ponytail: primitives stay CSS/token-styled (not slots) — see docs/customization.md.
// import { Button } from "../atoms/primitives/Button.js";
@@ -161,6 +170,11 @@ export const defaultSlots = {
AgentDetailsUnavailable,
AgentOverview,
AgentOverviewCard,
+ AgentMetrics: AgentMetricsContainer,
+ AgentMetricsView,
+ AgentMetricsTimeRangeFilter,
+ AgentMetricCard,
+ AgentMetricChart,
AgentSessionDetailHeader,
AgentSessionsFilters,
SessionsPage,
diff --git a/packages/trueforge-ui/src/utils/sessionShareUrl.ts b/packages/trueforge-ui/src/utils/sessionShareUrl.ts
index 9c642bcd1..a1a783015 100644
--- a/packages/trueforge-ui/src/utils/sessionShareUrl.ts
+++ b/packages/trueforge-ui/src/utils/sessionShareUrl.ts
@@ -10,7 +10,7 @@ export const SESSION_TIME_BUFFER_MS = 5 * 60 * 1000;
export const SESSION_CUSTOM_RANGE_MAX_DAYS = 70;
export const DEFAULT_SESSION_TIME_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
-export type LibraryAgentTab = 'overview' | 'sessions' | 'code';
+export type LibraryAgentTab = 'overview' | 'sessions' | 'code' | 'metrics';
export type SessionTimeRange = {
startTs: number;
@@ -35,7 +35,7 @@ export type SessionShareWrite = {
};
function parseLibraryAgentTab(value: string | null): LibraryAgentTab | null {
- if (value === 'overview' || value === 'sessions' || value === 'code') return value;
+ if (value === 'overview' || value === 'sessions' || value === 'code' || value === 'metrics') return value;
return null;
}
diff --git a/packages/trueforge-ui/test/atoms/AgentDetailsPage.test.tsx b/packages/trueforge-ui/test/atoms/AgentDetailsPage.test.tsx
index e784bda1d..8d89a8426 100644
--- a/packages/trueforge-ui/test/atoms/AgentDetailsPage.test.tsx
+++ b/packages/trueforge-ui/test/atoms/AgentDetailsPage.test.tsx
@@ -7,7 +7,14 @@ import { AgentDetailsPage } from '@/atoms/agent-details/AgentDetailsPage.js';
import { AgentSessions } from '@/atoms/agent-details/AgentSessions.js';
import { ServerProvider } from '@/server/ServerContext.js';
import { ShellModeProvider } from '@/server/ShellModeContext.js';
-import type { AgentDetail, CodeSnippet, Session, SessionEventItem, SessionListEntry } from '@/server/types.js';
+import type {
+ AgentDetail,
+ AgentMetricsServer,
+ CodeSnippet,
+ Session,
+ SessionEventItem,
+ SessionListEntry,
+} from '@/server/types.js';
import { SlotsProvider, type SlotOverrides } from '@/theme/SlotsProvider.js';
import { createMockAgentUIServer } from '../server/mockServer.js';
@@ -67,6 +74,7 @@ function renderPage({
updatedAt: '2026-01-02T00:00:00.000Z',
})),
withSessions = true,
+ metrics,
overrides,
initialEntries = ['/library/agent-1'],
}: {
@@ -76,12 +84,14 @@ function renderPage({
listSessionEvents?: () => Promise<{ data: SessionEventItem[] }>;
getSession?: () => Promise<Session>;
withSessions?: boolean;
+ metrics?: AgentMetricsServer;
overrides?: SlotOverrides;
initialEntries?: string[];
} = {}) {
const server = createMockAgentUIServer({
getSession,
...(withSessions ? { sessions: { getAgent, getCodeSnippets, listSessions, listSessionEvents } } : {}),
+ ...(metrics == null ? {} : { metrics }),
});
render(
<MemoryRouter initialEntries={initialEntries}>
@@ -117,6 +127,37 @@ describe('AgentDetailsPage', () => {
expect(await screen.findByText('Custom overview')).toBeInTheDocument();
});
+ it('shows the Metrics tab when supported and renders it through slots', async () => {
+ renderPage({
+ metrics: {
+ getCharts: vi.fn(async () => []),
+ getMeters: vi.fn(async () => []),
+ getChartData: vi.fn(async () => ({ step: '3600', graphs: [] })),
+ },
+ overrides: { AgentMetrics: () => <div>Custom metrics</div> },
+ });
+
+ fireEvent.click(await screen.findByRole('tab', { name: 'Metrics' }));
+ expect(screen.getByText('Custom metrics')).toBeInTheDocument();
+ expect(new URL(window.location.href).searchParams.get('tab')).toBe('metrics');
+ });
+
+ it('honors tab=metrics when the metrics port is available', async () => {
+ window.history.replaceState(null, '', '/library/agent-1?tab=metrics');
+ renderPage({
+ initialEntries: ['/library/agent-1?tab=metrics'],
+ metrics: {
+ getCharts: vi.fn(async () => []),
+ getMeters: vi.fn(async () => []),
+ getChartData: vi.fn(async () => ({ step: '3600', graphs: [] })),
+ },
+ overrides: { AgentMetrics: () => <div>Metrics deep link</div> },
+ });
+
+ expect(await screen.findByRole('tab', { name: 'Metrics' })).toHaveAttribute('aria-selected', 'true');
+ expect(screen.getByText('Metrics deep link')).toBeInTheDocument();
+ });
+
it('loads code snippets lazily and retains them across tab changes', async () => {
const { getCodeSnippets } = renderPage();
await screen.findByRole('heading', { name: 'release-notes-writer' });
@@ -279,6 +320,21 @@ describe('AgentDetailsPage', () => {
expect(screen.getByText('timeline-body')).toBeInTheDocument();
});
+ it('passes session API metrics into the selected session detail', async () => {
+ renderPage({
+ overrides: {
+ AgentSessionTimelineContainer: ({ listMetrics }) => (
+ <div>{`${String(listMetrics?.totalTurns)} turns, ${String(listMetrics?.totalDurationMs)}ms, $${String(listMetrics?.totalCostInUsd)}`}</div>
+ ),
+ },
+ });
+ await screen.findByRole('heading', { name: 'release-notes-writer' });
+ fireEvent.click(screen.getByRole('tab', { name: 'Sessions' }));
+ fireEvent.click(await screen.findByText('Release notes draft'));
+
+ expect(await screen.findByText('2 turns, 120000ms, $0.5')).toBeInTheDocument();
+ });
+
it('shows the shared unavailable state without the optional server', () => {
renderPage({ withSessions: false });
expect(screen.getByRole('heading', { name: 'Agent details unavailable' })).toBeInTheDocument();
diff --git a/packages/trueforge-ui/test/atoms/AgentMetricsContainer.test.tsx b/packages/trueforge-ui/test/atoms/AgentMetricsContainer.test.tsx
new file mode 100644
index 000000000..46fc8b44d
--- /dev/null
+++ b/packages/trueforge-ui/test/atoms/AgentMetricsContainer.test.tsx
@@ -0,0 +1,126 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { AgentMetricsContainer } from '@/containers/AgentMetricsContainer.js';
+import { ServerProvider } from '@/server/ServerContext.js';
+import type {
+ AgentMetricChartData,
+ AgentMetricChartDataRequest,
+ AgentMetricChartDefinition,
+ AgentMetricRangeRequest,
+ AgentMetricsServer,
+} from '@/server/types.js';
+import { SlotsProvider } from '@/theme/SlotsProvider.js';
+import { createMockAgentUIServer } from '../server/mockServer.js';
+
+const definitions: AgentMetricChartDefinition[] = [
+ {
+ name: 'sessions_over_time',
+ displayName: 'Sessions',
+ description: 'Session starts over time',
+ chartType: 'line',
+ },
+];
+
+function renderMetrics(metrics: AgentMetricsServer) {
+ render(
+ <SlotsProvider
+ overrides={{
+ AgentMetricChart: ({ graph, definition, error }) => (
+ <div>
+ {error ?? `${definition.displayName}: ${String(graph?.graphLines[0]?.values[0]?.value ?? 'empty')}`}
+ </div>
+ ),
+ AgentMetricsTimeRangeFilter: ({ onTimeRangeChange }) => (
+ <button
+ type="button"
+ onClick={() =>
+ onTimeRangeChange({
+ startTs: Date.parse('2026-08-20T00:00:00.000Z'),
+ endTs: Date.parse('2026-08-21T00:00:00.000Z'),
+ })
+ }
+ >
+ Set custom range
+ </button>
+ ),
+ }}
+ >
+ <ServerProvider server={createMockAgentUIServer({ metrics })}>
+ <AgentMetricsContainer agentId="agent-1" />
+ </ServerProvider>
+ </SlotsProvider>,
+ );
+}
+
+describe('AgentMetricsContainer', () => {
+ beforeEach(() => {
+ vi.useFakeTimers({ shouldAdvanceTime: true });
+ vi.setSystemTime(new Date('2026-08-28T13:00:00.000Z'));
+ });
+
+ afterEach(() => {
+ vi.useRealTimers();
+ });
+
+ it('loads the default 24-hour range and reloads a custom range', async () => {
+ const getMeters = vi.fn(async (_request: AgentMetricRangeRequest) => [
+ { name: 'total_sessions', aggregateValue: 12, description: 'Total sessions', unit: 'count' },
+ { name: 'total_cost', aggregateValue: 1.248, description: 'Total cost', unit: '$' },
+ ]);
+ const getChartData = vi.fn(async (_request: AgentMetricChartDataRequest): Promise<AgentMetricChartData> => ({
+ step: '3600',
+ graphs: [
+ {
+ name: 'sessions_over_time',
+ displayName: 'Sessions per hour',
+ description: 'Sessions each hour',
+ unit: 'count',
+ chartType: 'line',
+ graphLines: [
+ {
+ name: 'sessions',
+ values: [{ timestamp: '2026-08-28T12:00:00.000Z', value: 4 }],
+ },
+ ],
+ },
+ ],
+ }));
+ renderMetrics({
+ getCharts: vi.fn(async () => definitions),
+ getMeters,
+ getChartData,
+ });
+
+ expect(await screen.findByText('Total sessions')).toBeInTheDocument();
+ expect(screen.getByText('12')).toBeInTheDocument();
+ expect(screen.getByText('$1.2480')).toBeInTheDocument();
+ expect(await screen.findByText('Sessions: 4')).toBeInTheDocument();
+ const defaultRequest = getMeters.mock.calls[0]?.[0];
+ expect(defaultRequest?.agentId).toBe('agent-1');
+ expect(Date.parse(defaultRequest?.endTimestamp ?? '') - Date.parse(defaultRequest?.startTimestamp ?? '')).toBe(
+ 24 * 60 * 60 * 1000,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'Set custom range' }));
+ await waitFor(() => expect(getMeters).toHaveBeenCalledTimes(2));
+ expect(getChartData).toHaveBeenLastCalledWith({
+ agentId: 'agent-1',
+ startTimestamp: '2026-08-20T00:00:00.000Z',
+ endTimestamp: '2026-08-21T00:00:00.000Z',
+ chartName: 'sessions_over_time',
+ });
+ });
+
+ it('shows empty states when the server returns no metrics', async () => {
+ renderMetrics({
+ getCharts: vi.fn(async () => []),
+ getMeters: vi.fn(async () => []),
+ getChartData: vi.fn(async () => ({ step: '3600', graphs: [] })),
+ });
+
+ expect(await screen.findByText('No aggregate metrics')).toBeInTheDocument();
+ expect(screen.getByText('No charts available')).toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui/test/atoms/AgentSessionsFilters.test.tsx b/packages/trueforge-ui/test/atoms/AgentSessionsFilters.test.tsx
index 1122253f7..652c3b01e 100644
--- a/packages/trueforge-ui/test/atoms/AgentSessionsFilters.test.tsx
+++ b/packages/trueforge-ui/test/atoms/AgentSessionsFilters.test.tsx
@@ -1,5 +1,5 @@
// @vitest-environment jsdom
-import { render, screen, waitFor } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
import { describe, expect, it, vi } from 'vitest';
import { AgentSessionsFilters } from '@/atoms/agent-details/AgentSessionsFilters.js';
@@ -30,4 +30,21 @@ describe('AgentSessionsFilters', () => {
expect(searchAgents).toHaveBeenNthCalledWith(1, { limit: 50, offset: 0 });
expect(searchAgents).toHaveBeenNthCalledWith(2, { limit: 50, offset: 50 });
});
+
+ it('can hide the custom time range option', () => {
+ const endTs = Date.parse('2026-08-01T00:00:00');
+ render(
+ <AgentSessionsFilters
+ agentId={null}
+ timeRange={{ startTs: endTs - 24 * 60 * 60 * 1000, endTs, timeWindowMs: 24 * 60 * 60 * 1000 }}
+ onAgentChange={() => undefined}
+ onTimeRangeChange={() => undefined}
+ showAgentFilter={false}
+ showCustomTimeRange={false}
+ />,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'Last 24 hours' }));
+ expect(screen.queryByRole('button', { name: 'Custom Time Range' })).not.toBeInTheDocument();
+ });
});
diff --git a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentMetricsServer.test.ts b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentMetricsServer.test.ts
new file mode 100644
index 000000000..86af1d409
--- /dev/null
+++ b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentMetricsServer.test.ts
@@ -0,0 +1,143 @@
+import assert from 'node:assert/strict';
+import { describe, it, vi } from 'vitest';
+
+import { createHarnessAgentMetricsServer } from '@/plugins/trueforge-agent-server-adapter/agentMetricsServer.js';
+
+const range = {
+ agentId: 'agent-1',
+ startTimestamp: '2026-08-27T13:00:00.000Z',
+ endTimestamp: '2026-08-28T13:00:00.000Z',
+};
+
+describe('createHarnessAgentMetricsServer', () => {
+ it('maps charts, meters, and chart data to the UI contract', async () => {
+ const fetch = vi.fn(async (input: Request | string | URL) => {
+ const url = new URL(input instanceof Request ? input.url : input);
+ const path = url.pathname;
+ if (path === '/internal/metrics/charts') {
+ return Response.json({
+ data: {
+ charts: [
+ {
+ name: 'sessions_over_time',
+ display_name: 'Sessions',
+ description: 'Session starts over time',
+ chart_type: 'line',
+ },
+ ],
+ },
+ });
+ }
+ if (path === '/internal/metrics/meters') {
+ return Response.json({
+ data: {
+ meters: [
+ {
+ name: 'total_cost_in_usd',
+ aggregate_value: 1.248,
+ description: 'Total cost',
+ unit: '$',
+ },
+ ],
+ },
+ });
+ }
+ return Response.json({
+ data: {
+ step: '3600',
+ graphs: [
+ {
+ name: 'sessions_over_time',
+ display_name: 'Sessions per hour',
+ description: 'How many sessions started each hour',
+ unit: 'count',
+ chart_type: 'line',
+ graph_lines: [
+ {
+ name: 'sessions',
+ values: [{ timestamp: '2026-08-27T15:00:00.000Z', value: 2 }],
+ },
+ ],
+ },
+ ],
+ },
+ });
+ });
+ const server = createHarnessAgentMetricsServer({ baseUrl: 'https://trueforge.example', fetch });
+
+ assert.deepEqual(await server.getCharts(), [
+ {
+ name: 'sessions_over_time',
+ displayName: 'Sessions',
+ description: 'Session starts over time',
+ chartType: 'line',
+ },
+ ]);
+ assert.deepEqual(await server.getMeters(range), [
+ {
+ name: 'total_cost_in_usd',
+ aggregateValue: 1.248,
+ description: 'Total cost',
+ unit: '$',
+ },
+ ]);
+ assert.deepEqual(
+ await server.getChartData({
+ ...range,
+ chartName: 'sessions_over_time',
+ }),
+ {
+ step: '3600',
+ graphs: [
+ {
+ name: 'sessions_over_time',
+ displayName: 'Sessions per hour',
+ description: 'How many sessions started each hour',
+ unit: 'count',
+ chartType: 'line',
+ graphLines: [
+ {
+ name: 'sessions',
+ values: [{ timestamp: '2026-08-27T15:00:00.000Z', value: 2 }],
+ },
+ ],
+ },
+ ],
+ },
+ );
+
+ const meterInput = fetch.mock.calls[1]?.[0];
+ const meterUrl = new URL(meterInput instanceof Request ? meterInput.url : String(meterInput));
+ assert.equal(meterUrl.pathname, '/internal/metrics/meters');
+ assert.deepEqual(Object.fromEntries(meterUrl.searchParams), {
+ agent_id: 'agent-1',
+ start_timestamp: range.startTimestamp,
+ end_timestamp: range.endTimestamp,
+ });
+ const chartInput = fetch.mock.calls[2]?.[0];
+ const chartUrl = new URL(chartInput instanceof Request ? chartInput.url : String(chartInput));
+ assert.deepEqual(Object.fromEntries(chartUrl.searchParams), {
+ agent_id: 'agent-1',
+ start_timestamp: range.startTimestamp,
+ end_timestamp: range.endTimestamp,
+ chart_name: 'sessions_over_time',
+ });
+ });
+
+ it('reports non-success response bodies', async () => {
+ const server = createHarnessAgentMetricsServer({
+ baseUrl: 'https://trueforge.example',
+ fetch: vi.fn(async () => Response.json({ error: { message: 'metrics unavailable' } }, { status: 503 })),
+ });
+
+ await assert.rejects(
+ server.getCharts(),
+ error =>
+ error instanceof Error &&
+ 'statusCode' in error &&
+ error.statusCode === 503 &&
+ 'body' in error &&
+ JSON.stringify(error.body).includes('metrics unavailable'),
+ );
+ });
+});
diff --git a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentSessionsServer.test.ts b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentSessionsServer.test.ts
index cf0f16e0d..9b11b1d4a 100644
--- a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentSessionsServer.test.ts
+++ b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentSessionsServer.test.ts
@@ -64,6 +64,11 @@ describe('createHarnessAgentSessionsServer', () => {
name: 'writer',
},
createdBy: 'user-1',
+ metrics: {
+ totalTurns: 3,
+ totalCostInUsd: 0.25,
+ totalDurationMs: 29_711,
+ },
},
],
response: { pagination: { nextPageToken: 'next-1' } },
@@ -92,7 +97,7 @@ describe('createHarnessAgentSessionsServer', () => {
createdAt: '2026-01-01T00:00:00.000Z',
updatedAt: '2026-01-02T00:00:00.000Z',
lastActivityAt: '2026-01-02T00:00:00.000Z',
- metrics: { totalTurns: 0, totalCostInUsd: 0, totalDurationMs: 0 },
+ metrics: { totalTurns: 3, totalCostInUsd: 0.25, totalDurationMs: 29_711 },
agentName: 'writer',
},
],
diff --git a/packages/trueforge-ui/test/publicUiExports.test.ts b/packages/trueforge-ui/test/publicUiExports.test.ts
index b437d7d65..1599884da 100644
--- a/packages/trueforge-ui/test/publicUiExports.test.ts
+++ b/packages/trueforge-ui/test/publicUiExports.test.ts
@@ -8,6 +8,11 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = [
'AgentDetailsPage',
'AgentDetailsTabs',
'AgentDetailsUnavailable',
+ 'AgentMetricCard',
+ 'AgentMetricChart',
+ 'AgentMetricsContainer',
+ 'AgentMetricsTimeRangeFilter',
+ 'AgentMetricsView',
'AgentOverviewCard',
'AgentSessionsFilters',
'AgentStepsCard',
@@ -124,6 +129,7 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = [
'shellIsMutable',
'threadHasPendingMcpAuth',
'trueFoundryAttachmentAdapter',
+ 'useAgentMetricsServer',
'useAgentSessionsServer',
'useAui',
'useAuiState',
@@ -137,6 +143,7 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = [
'useToaster',
'useToasterOptional',
'useMCPAuth',
+ 'useOptionalAgentMetricsServer',
'useOptionalAgentSessionsServer',
'useOptionalCatalogServer',
'useOptionalContentClassNames',
diff --git a/packages/trueforge-ui/test/utils/sessionShareUrl.test.ts b/packages/trueforge-ui/test/utils/sessionShareUrl.test.ts
index d5b4cb475..ffbe51952 100644
--- a/packages/trueforge-ui/test/utils/sessionShareUrl.test.ts
+++ b/packages/trueforge-ui/test/utils/sessionShareUrl.test.ts
@@ -100,5 +100,6 @@ describe('sessionShareUrl', () => {
'overview',
);
assert.equal(libraryAgentTabFromSearch(readSessionShareSearch('?tab=code'), 'agent-1'), 'code');
+ assert.equal(libraryAgentTabFromSearch(readSessionShareSearch('?tab=metrics'), 'agent-1'), 'metrics');
});
});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 37d494647..a72690c99 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -66,8 +66,8 @@ importers:
specifier: 0.2.21
'@truefoundry/assistant-ui-runtime':
- specifier: 0.1.22
+ specifier: 0.1.23
'@truefoundry/trueforge-sdk':
specifier: workspace:*
version: link:../trueforge-sdk
@@ -354,8 +354,8 @@ importers:
specifier: ^0.13.2
'@truefoundry/assistant-ui-runtime':
- specifier: 0.1.22
+ specifier: 0.1.23
'@truefoundry/trueforge-sdk':
specifier: workspace:*
version: link:../trueforge-sdk
@@ -3627,8 +3627,8 @@ packages:
'@types/react-dom':
optional: true
- '@truefoundry/[email protected]':
- resolution: {integrity: sha512-tvAkqZNJMM+NwB2bU5tZubbTKyDR2k/k6cFTxJZwczjpUw3Vp3q5ESxguNqooqqXMeC3/6xjBQH6my6ziFgWgw==}
+ '@truefoundry/[email protected]':
+ resolution: {integrity: sha512-hw0fVLkYA6g4hkuEqpbZ6FAK5QFH/yVoZoJ8uwkXaM93gys6OojeDfnkB7fugrAAIfL6E2IFHyShOJX3BG7s3w==}
peerDependencies:
'@types/react': '*'
react: ^18 || ^19
@@ -10869,7 +10869,7 @@ snapshots:
'@types/react': 19.2.18
'@types/react-dom': 19.2.5(@types/[email protected])
dependencies:
'@assistant-ui/store': 0.2.21(@assistant-ui/[email protected](@types/[email protected])([email protected]))(@types/[email protected])([email protected])
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index b75d2467b..c850084b3 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -17,7 +17,7 @@ allowBuilds:
# Silence peer mismatches between trueforge-ui peers and the versions we pin.
peerDependencyRules:
allowedVersions:
- '@truefoundry/assistant-ui-runtime': '0.1.18'
+ '@truefoundry/assistant-ui-runtime': '0.1.23'
# One Context module for assistant-ui (avoids "requires an AuiProvider").
overrides: