Skip to content

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

Feature: Add agent details, sessions and code snippet (#529)

harshil-2096a1894825b8c4
diff --git a/.changeset/adapter-sdk-code-snippets.md b/.changeset/adapter-sdk-code-snippets.md
new file mode 100644
index 000000000..a1b97311a
--- /dev/null
+++ b/.changeset/adapter-sdk-code-snippets.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge-ui": patch
+---
+
+Load agent Use In Code snippets through `client.internal.agents.getCodeSnippets` instead of a raw `client.fetch`.
diff --git a/.changeset/agent-library-details.md b/.changeset/agent-library-details.md
new file mode 100644
index 000000000..18768e5d6
--- /dev/null
+++ b/.changeset/agent-library-details.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge-ui": minor
+---
+
+Add routed agent detail pages with lazy Overview, Sessions, and Use In Code tabs backed by the optional AgentSessionsServer port and built-in TrueForge adapter.
diff --git a/.changeset/agent-sessions-tab.md b/.changeset/agent-sessions-tab.md
new file mode 100644
index 000000000..5beb47359
--- /dev/null
+++ b/.changeset/agent-sessions-tab.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge-ui": minor
+---
+
+Add the agent library Sessions tab and an all-user Sessions sidebar page (including drafts) with agent and time filters, shareable query params, and the same two-pane timeline. Library agent details keep the active tab in `?tab=` so opening an agent lands on Overview.
diff --git a/.cursor/rules/trueforge-ui-slots.mdc b/.cursor/rules/trueforge-ui-slots.mdc
new file mode 100644
index 000000000..af35f6e31
--- /dev/null
+++ b/.cursor/rules/trueforge-ui-slots.mdc
@@ -0,0 +1,43 @@
+---
+description: trueforge-ui JSX components must be host-overridable via useSlot / AtomSlots
+globs: packages/trueforge-ui/src/**/*.{tsx,ts}
+alwaysApply: false
+---
+
+# Slotted UI components (`useSlot`)
+
+Every newly created or newly JSX-bearing component in `@truefoundry/trueforge-ui`
+MUST be host-overridable through the slots system. Do not hard-import leaf UI into
+layouts/containers when a slot exists (or should exist).
+
+## Checklist for a new / newly JSX component
+
+1. Export the component and augment `AtomSlots` in the same file:
+
+```tsx
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ MyComponent: typeof MyComponent;
+ }
+}
+```
+
+2. Register the default in `src/theme/defaultSlots.ts`.
+3. Parents render it via `useSlot('MyComponent')`, never a direct import of the
+ default implementation (except inside `defaultSlots.ts`).
+4. Keep the public prop surface stable so hosts can swap the implementation.
+
+## Examples
+
+```tsx
+// ❌ BAD — layout hard-wires a leaf
+import { AgentsLibraryButton } from '../atoms/AgentsLibraryButton.js';
+<AgentsLibraryButton compact />
+
+// ✅ GOOD — host can override
+const AgentsLibraryButton = useSlot('AgentsLibraryButton');
+<AgentsLibraryButton compact />
+```
+
+Primitives that are already slotted (Button, SearchInput, etc.) follow the same
+rule when exposed as named atoms; internal helpers with no JSX need no slot.
diff --git a/packages/frontend/package.json b/packages/frontend/package.json
index a489b8940..3437e7cb5 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.21",
+ "@truefoundry/assistant-ui-runtime": "0.1.22",
"@truefoundry/trueforge-sdk": "workspace:*",
"@truefoundry/trueforge-ui": "workspace:*",
"monaco-editor": "^0.52.0",
diff --git a/packages/trueforge-ui/docs/compatibility.md b/packages/trueforge-ui/docs/compatibility.md
index 288eaef6e..7703150d2 100644
--- a/packages/trueforge-ui/docs/compatibility.md
+++ b/packages/trueforge-ui/docs/compatibility.md
@@ -21,7 +21,7 @@ Install once at the app root.
| ----------------------------------- | ---------- |
| `@assistant-ui/core` | `^0.2.22` |
| `@assistant-ui/react` | `^0.14.24` |
-| `@truefoundry/assistant-ui-runtime` | `0.1.18` |
+| `@truefoundry/assistant-ui-runtime` | `0.1.22` |
| `truefoundry-gateway-sdk` | `^0.4.0` |
| `lucide-react` | `^0.562.0` |
diff --git a/packages/trueforge-ui/docs/customization.md b/packages/trueforge-ui/docs/customization.md
index 85392bb6b..c8a050b67 100644
--- a/packages/trueforge-ui/docs/customization.md
+++ b/packages/trueforge-ui/docs/customization.md
@@ -64,8 +64,15 @@ Public override surface (primitives stay theme/CSS — not slots):
`ChatFileDownload`, `MonacoEditorCore`, `CodeEditor`
- **Thread list:** `ThreadListShell`, `ThreadListNewButton`, `ThreadListRow`,
`ThreadListRowSkeleton`, `ThreadListEmptyState`, `HistoryLoader`,
- `AgentsLibrary`, `AgentsLibraryButton`, `SaveAgentButton`,
- `SelectAgentEmptyState`, `ClearChatButton`
+ `AgentsLibrary`, `AgentsLibraryButton`, `SessionsBrowserButton`,
+ `SaveAgentButton`, `SelectAgentEmptyState`, `ClearChatButton`
+- **Agent details / sessions:** `AgentDetailsPage`, `AgentDetailsHeader`,
+ `AgentDetailsTabs`, `AgentDetailsUnavailable`, `AgentOverview`,
+ `AgentOverviewCard`, `AgentSessions`, `AgentSessionsFilters`, `SessionsPage`,
+ `AgentSessionListRow`, `AgentSessionDetailHeader`, `AgentSessionMetricsStrip`,
+ `AgentSessionTimelineContainer`, `AgentSessionEventTimeline`,
+ `AgentSessionEventTimelineChart`, `AgentSessionTurnHeader`,
+ `AgentCodeSnippets`, `AgentCodeBlock`
- **Attachments / toasts:** `AttachmentCard`, `AttachmentPreviewDialog`,
`AttachmentPickerButton`, `Toast`, `ToastStack`
- **Tools / prompts:** `ToolCallCard`, `ToolCallContentBlock`,
@@ -88,8 +95,11 @@ Places mirrored to the URL:
- `/` — new chat / library landing (mode-dependent)
- `/agents/:agentName` — immutable "Try" of a library agent
+- `/sessions` — all-user Sessions browser (named agents and drafts)
- `/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)
Customize the paths (only honored when `withRouter`). Set any entry to `false`
to keep that place overlay-only with no URL:
@@ -100,12 +110,12 @@ to keep that place overlay-only with no URL:
withRouter
routes={{
basename: '/app',
- paths: { session: '/chats/:sessionId', settings: false },
+ paths: { session: '/chats/:sessionId', libraryAgent: '/library/:agentId', settings: false },
}}
/>
```
-Custom `agent` / `session` templates must keep their `:param` segment, or the
+Custom `agent` / `session` / `libraryAgent` templates must keep their `:param` segment, or the
place can be written to the URL but not read back.
Shell state stays the source of truth; the router mirrors it. Combining
@@ -113,8 +123,20 @@ Shell state stays the source of truth; the router mirrors it. Combining
Notes on behaviour:
-- Only the pathname is owned; query string and hash are preserved across
- navigation, so host state in `?…` survives switching sessions.
+- Hashes and host-owned query keys are preserved across navigation. Session
+ keys (`sessionId`, `agentId`, `tab`, `view`, `s_tw`, `s_sts`, `s_ets`) are
+ removed when the destination does not own them, preventing stale filters or
+ selections from leaking into unrelated routes.
+- A copied library session link is `?agentId=&sessionId=` on the current page
+ (plus `/library/:agentId` when `withRouter`). Opening it lands on that
+ agent's Sessions tab. Clicking an agent in the library writes `?tab=overview`
+ so a leftover chat `sessionId` does not open Sessions. The same query works
+ when `withRouter` is off.
+- The all-user Sessions page is `/sessions` when `withRouter` is on, or
+ `?view=sessions` when it is off. Agent and time filters live in the query
+ (`agentId`, `s_tw` for a relative window, or `s_sts`/`s_ets` for an absolute
+ range). Opening a session pins `s_sts`/`s_ets` around `created_at` (±5 min)
+ so a refresh still finds that row on page 1 without scrolling the list.
- A `/sessions/:sessionId` link is resolved through `getSession` so the chat
opens with its own agent binding and mutability rather than as a new draft.
- Unrecognized paths (and malformed escapes) normalize to the root place.
diff --git a/packages/trueforge-ui/package.json b/packages/trueforge-ui/package.json
index 00daa93fd..29f968739 100644
--- a/packages/trueforge-ui/package.json
+++ b/packages/trueforge-ui/package.json
@@ -95,12 +95,14 @@
"@openuidev/react-headless": "^0.9.4",
"@openuidev/react-lang": "^0.2.9",
"@openuidev/react-ui": "^0.13.2",
- "@truefoundry/assistant-ui-runtime": "0.1.21",
+ "@truefoundry/assistant-ui-runtime": "0.1.22",
"@truefoundry/trueforge-sdk": "workspace:*",
+ "chart.js": "^4.5.1",
"clsx": "^2.1.1",
"lucide-react": "^0.562.0",
"monaco-editor": "^0.56.0",
"partial-json": "^0.1.7",
+ "react-chartjs-2": "^5.3.1",
"react-markdown": "^10.1.0",
"react-router-dom": "^6 || ^7",
"react-syntax-highlighter": "^16.1.1",
diff --git a/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx b/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx
index e0a1755d3..299bde754 100644
--- a/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx
+++ b/packages/trueforge-ui/src/atoms/AgentsLibrary.tsx
@@ -1,27 +1,28 @@
'use client';
-import { useEffect, useState } from 'react';
+import { useCallback, useEffect, useState } from 'react';
+import { useSessionShareSearch } from '../hooks/useSessionShareSearch.js';
import { Icon } from '../icons/Icon.js';
-import { libraryAgentId, useOptionalShellMode } from '../server/ShellModeContext.js';
+import { useOptionalAgentSessionsServer } from '../server/ServerContext.js';
+import { libraryAgentId, useShellMode } from '../server/ShellModeContext.js';
import type { AgentLibraryEntry, AgentSpec } from '../server/types.js';
+import { useSlot } from '../theme/SlotsProvider.js';
import { auiButtonClass } from './lib/buttonClasses.js';
import { cn } from './lib/cn.js';
import { useSearchAgentsList } from './lib/useSearchAgentsList.js';
-import { CenteredModal } from './primitives/CenteredModal.js';
import SearchInput from './primitives/SearchInput.js';
import { Skeleton } from './primitives/Skeleton.js';
import { Tooltip } from './primitives/Tooltip.js';
export type AgentsLibraryProps = {
- open: boolean;
- onOpenChange: (open: boolean) => void;
onSelectAgent?: (agentName: string) => void;
};
-type AgentLibraryRowProps = {
+export type AgentLibraryRowProps = {
agent: AgentLibraryEntry;
showEdit: boolean;
+ onOpen?: () => void;
onTry: () => void;
onEdit: () => void;
};
@@ -32,7 +33,7 @@ function displayModelLabel(modelName: string): string {
return slash >= 0 ? modelName.slice(slash + 1) : modelName;
}
-function AgentLibraryRow({ agent, showEdit, onTry, onEdit }: AgentLibraryRowProps) {
+export function AgentLibraryRow({ agent, showEdit, onOpen, onTry, onEdit }: AgentLibraryRowProps) {
const spec = agent.agentSpec;
const modelName = spec?.model.name;
const skillsCount = spec?.skills?.length ?? 0;
@@ -45,11 +46,23 @@ function AgentLibraryRow({ agent, showEdit, onTry, onEdit }: AgentLibraryRowProp
return (
<div
role="menuitem"
+ tabIndex={onOpen == null ? undefined : 0}
+ aria-label={onOpen == null ? undefined : `Open ${agent.name}`}
className={cn(
'flex w-full items-center gap-2.5 rounded-md border border-transparent px-2.5 py-2 transition-colors',
'hover:border-border hover:bg-ghost-button-hover',
'focus-within:border-border focus-within:bg-ghost-button-hover',
+ onOpen != null &&
+ 'cursor-pointer focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-focus-ring',
)}
+ onClick={onOpen}
+ onKeyDown={event => {
+ if (onOpen == null || event.target !== event.currentTarget || (event.key !== 'Enter' && event.key !== ' ')) {
+ return;
+ }
+ event.preventDefault();
+ onOpen();
+ }}
>
<span className="bg-primary-bg text-text-secondary inline-flex size-8 shrink-0 items-center justify-center rounded-md border border-border">
<Icon name="robot" className="size-4" />
@@ -88,7 +101,10 @@ function AgentLibraryRow({ agent, showEdit, onTry, onEdit }: AgentLibraryRowProp
variant: 'ghost',
size: 'sm',
})}
- onClick={onEdit}
+ onClick={event => {
+ event.stopPropagation();
+ onEdit();
+ }}
>
<Icon name="pencil" className="size-3.5" />
Edit
@@ -101,7 +117,10 @@ function AgentLibraryRow({ agent, showEdit, onTry, onEdit }: AgentLibraryRowProp
variant: 'outline',
size: 'sm',
})}
- onClick={onTry}
+ onClick={event => {
+ event.stopPropagation();
+ onTry();
+ }}
>
<Icon name="play" className="size-3.5" />
Try
@@ -111,17 +130,37 @@ function AgentLibraryRow({ agent, showEdit, onTry, onEdit }: AgentLibraryRowProp
);
}
-export function AgentsLibrary({ open, onOpenChange, onSelectAgent }: AgentsLibraryProps) {
- const shell = useOptionalShellMode();
+export function AgentsLibrary({ onSelectAgent }: AgentsLibraryProps) {
+ const shell = useShellMode();
+ const { updateShareSearch } = useSessionShareSearch();
+ const sessionsServer = useOptionalAgentSessionsServer();
+ const SlottedAgentLibraryRow = useSlot('AgentLibraryRow');
const [query, setQuery] = useState('');
+ const open = shell.libraryOpen;
- const canEdit = shell?.isComposerEnabled === true;
- const agentsListEpoch = shell?.agentsListEpoch ?? 0;
+ const canEdit = shell.isComposerEnabled === true;
+ const agentsListEpoch = shell.agentsListEpoch;
useEffect(() => {
if (!open) setQuery('');
}, [open]);
+ const closeLibrary = useCallback(() => {
+ shell.setLibraryOpen(false);
+ setQuery('');
+ }, [shell]);
+
+ useEffect(() => {
+ if (!open) return;
+ const onKeyDown = (event: KeyboardEvent) => {
+ if (event.key !== 'Escape') return;
+ event.stopImmediatePropagation();
+ closeLibrary();
+ };
+ window.addEventListener('keydown', onKeyDown, true);
+ return () => window.removeEventListener('keydown', onKeyDown, true);
+ }, [closeLibrary, open]);
+
const { agents, isInitialLoading, isSearching, loadingMore, error, hasMore, listRef, sentinelRef } =
useSearchAgentsList({
enabled: open,
@@ -129,15 +168,10 @@ export function AgentsLibrary({ open, onOpenChange, onSelectAgent }: AgentsLibra
refreshKey: agentsListEpoch,
});
- const closeLibrary = () => {
- onOpenChange(false);
- setQuery('');
- };
-
const handleTry = (agent: AgentLibraryEntry) => {
closeLibrary();
onSelectAgent?.(agent.name);
- shell?.selectLibraryAgent({
+ shell.selectLibraryAgent({
isMutable: false,
agentId: libraryAgentId(agent),
agentName: agent.name,
@@ -147,7 +181,7 @@ export function AgentsLibrary({ open, onOpenChange, onSelectAgent }: AgentsLibra
const handleEdit = (agent: AgentLibraryEntry, agentSpec: AgentSpec) => {
closeLibrary();
onSelectAgent?.(agent.name);
- shell?.selectLibraryAgent({
+ shell.selectLibraryAgent({
isMutable: true,
agentId: libraryAgentId(agent),
agentName: agent.name,
@@ -155,8 +189,23 @@ export function AgentsLibrary({ open, onOpenChange, onSelectAgent }: AgentsLibra
});
};
+ if (!open) return null;
+
return (
- <CenteredModal open={open} onOpenChange={onOpenChange} title="Agents Library">
+ <div className="flex h-full min-h-0 w-full flex-col bg-primary-bg">
+ <header className="flex shrink-0 items-center gap-2 border-b border-border px-2 py-1.5">
+ <button
+ type="button"
+ aria-label="Back"
+ title="Back"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={closeLibrary}
+ >
+ <Icon name="arrow-left" />
+ </button>
+ <h1 className="text-lg font-semibold tracking-tight text-text-primary">Agents Library</h1>
+ </header>
+
<div className="bg-secondary-bg/40 flex min-h-0 flex-1 flex-col">
<div className="shrink-0 border-b border-border px-4 py-3">
<SearchInput query={query} setQuery={setQuery} placeholder="Search agents" />
@@ -190,12 +239,27 @@ export function AgentsLibrary({ open, onOpenChange, onSelectAgent }: AgentsLibra
<>
{agents.map(agent => {
const agentSpec = agent.agentSpec;
+ const agentId = agent.agentId;
const showEdit = canEdit && agentSpec != null;
return (
- <AgentLibraryRow
+ <SlottedAgentLibraryRow
key={libraryAgentId(agent)}
agent={agent}
showEdit={showEdit}
+ {...(sessionsServer != null && agentId != null
+ ? {
+ onOpen: () => {
+ updateShareSearch({
+ agentId,
+ tab: 'overview',
+ sessionId: null,
+ view: null,
+ timeRange: null,
+ });
+ shell.openLibraryAgent(agentId);
+ },
+ }
+ : {})}
onTry={() => handleTry(agent)}
onEdit={() => {
if (agentSpec != null) handleEdit(agent, agentSpec);
@@ -216,12 +280,13 @@ export function AgentsLibrary({ open, onOpenChange, onSelectAgent }: AgentsLibra
)}
</div>
</div>
- </CenteredModal>
+ </div>
);
}
declare module '../theme/SlotsProvider.js' {
interface AtomSlots {
AgentsLibrary: typeof AgentsLibrary;
+ AgentLibraryRow: typeof AgentLibraryRow;
}
}
diff --git a/packages/trueforge-ui/src/atoms/AgentsLibraryButton.tsx b/packages/trueforge-ui/src/atoms/AgentsLibraryButton.tsx
index 9b5509439..77ee2f9ec 100644
--- a/packages/trueforge-ui/src/atoms/AgentsLibraryButton.tsx
+++ b/packages/trueforge-ui/src/atoms/AgentsLibraryButton.tsx
@@ -5,7 +5,6 @@ import { useEffect, useState } from 'react';
import { Icon } from '../icons/Icon.js';
import { useOptionalServer } from '../server/ServerContext.js';
import { useOptionalShellMode } from '../server/ShellModeContext.js';
-import { useSlot } from '../theme/SlotsProvider.js';
import { auiButtonClass } from './lib/buttonClasses.js';
import { cn } from './lib/cn.js';
import { SEARCH_AGENTS_PAGE_SIZE } from './lib/useSearchAgentsList.js';
@@ -13,17 +12,15 @@ import { SEARCH_AGENTS_PAGE_SIZE } from './lib/useSearchAgentsList.js';
export type AgentsLibraryButtonProps = {
className?: string;
compact?: boolean;
- onSelectAgent?: (agentName: string) => void;
};
-export function AgentsLibraryButton({ className, compact = false, onSelectAgent }: AgentsLibraryButtonProps) {
- const AgentsLibrary = useSlot('AgentsLibrary');
+export function AgentsLibraryButton({ className, compact = false }: AgentsLibraryButtonProps) {
const server = useOptionalServer();
const shell = useOptionalShellMode();
- const [open, setOpen] = useState(false);
const [countLabel, setCountLabel] = useState<string | null>(null);
const enabled = shell?.isLibraryEnabled === true && server != null;
+ const libraryOpen = shell?.libraryOpen === true;
const agentsListEpoch = shell?.agentsListEpoch ?? 0;
useEffect(() => {
@@ -47,38 +44,34 @@ export function AgentsLibraryButton({ className, compact = false, onSelectAgent
if (!enabled) return null;
return (
- <>
- <div className={cn('relative min-w-0', compact ? 'w-8' : 'w-full', className)}>
- <button
- type="button"
- aria-label={compact ? 'Agents Library' : undefined}
- title={compact ? 'Agents Library' : undefined}
- aria-haspopup="dialog"
- aria-expanded={open}
- className={auiButtonClass({
- variant: 'ghost',
- className: cn(
- 'h-8 rounded-md text-sm font-medium text-text-primary shadow-none hover:bg-ghost-button-hover hover:text-ghost-button-text',
- compact ? 'w-8 !justify-center p-0' : 'w-full !justify-start px-2.5',
- open && 'bg-dropdown-selected-item-bg text-dropdown-selected-item-text',
- ),
- })}
- onClick={() => setOpen(true)}
- >
- <Icon name="robot" />
- {!compact ? (
- <>
- <span className="truncate">
- Agents Library
- {countLabel != null ? <span className="text-text-secondary"> ({countLabel})</span> : null}
- </span>
- <Icon name="chevron-right" className="ml-auto size-3.5 shrink-0 opacity-60" />
- </>
- ) : null}
- </button>
- </div>
- <AgentsLibrary open={open} onOpenChange={setOpen} onSelectAgent={onSelectAgent} />
- </>
+ <div className={cn('relative min-w-0', compact ? 'w-8' : 'w-full', className)}>
+ <button
+ type="button"
+ aria-label={compact ? 'Agents Library' : undefined}
+ title={compact ? 'Agents Library' : undefined}
+ aria-current={libraryOpen ? 'page' : undefined}
+ className={auiButtonClass({
+ variant: 'ghost',
+ className: cn(
+ 'h-8 rounded-md text-sm font-medium text-text-primary shadow-none hover:bg-ghost-button-hover hover:text-ghost-button-text',
+ compact ? 'w-8 !justify-center p-0' : 'w-full !justify-start px-2.5',
+ libraryOpen && 'bg-dropdown-selected-item-bg text-dropdown-selected-item-text',
+ ),
+ })}
+ onClick={() => shell?.setLibraryOpen(true)}
+ >
+ <Icon name="robot" />
+ {!compact ? (
+ <>
+ <span className="truncate">
+ Agents Library
+ {countLabel != null ? <span className="text-text-secondary"> ({countLabel})</span> : null}
+ </span>
+ <Icon name="chevron-right" className="ml-auto size-3.5 shrink-0 opacity-60" />
+ </>
+ ) : null}
+ </button>
+ </div>
);
}
diff --git a/packages/trueforge-ui/src/atoms/SessionsBrowserButton.tsx b/packages/trueforge-ui/src/atoms/SessionsBrowserButton.tsx
new file mode 100644
index 000000000..64be5ea56
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/SessionsBrowserButton.tsx
@@ -0,0 +1,68 @@
+'use client';
+
+import { useSessionShareSearch } from '../hooks/useSessionShareSearch.js';
+import { Icon } from '../icons/Icon.js';
+import { useOptionalAgentSessionsServer } from '../server/ServerContext.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import { defaultSessionTimeRange, readSessionShareSearch } from '../utils/sessionShareUrl.js';
+import { auiButtonClass } from './lib/buttonClasses.js';
+import { cn } from './lib/cn.js';
+
+export type SessionsBrowserButtonProps = {
+ className?: string;
+ compact?: boolean;
+};
+
+export function SessionsBrowserButton({ className, compact = false }: SessionsBrowserButtonProps) {
+ const sessionsServer = useOptionalAgentSessionsServer();
+ const shell = useOptionalShellMode();
+ const { updateShareSearch } = useSessionShareSearch();
+ const sessionsOpen = shell?.sessionsOpen === true;
+
+ if (sessionsServer == null || shell == null) return null;
+
+ return (
+ <div className={cn('relative min-w-0', compact ? 'w-8' : 'w-full', className)}>
+ <button
+ type="button"
+ aria-label={compact ? 'Sessions' : undefined}
+ title={compact ? 'Sessions' : undefined}
+ aria-current={sessionsOpen ? 'page' : undefined}
+ className={auiButtonClass({
+ variant: 'ghost',
+ className: cn(
+ 'h-8 rounded-md text-sm font-medium text-text-primary shadow-none hover:bg-ghost-button-hover hover:text-ghost-button-text',
+ compact ? 'w-8 !justify-center p-0' : 'w-full !justify-start px-2.5',
+ sessionsOpen && 'bg-dropdown-selected-item-bg text-dropdown-selected-item-text',
+ ),
+ })}
+ onClick={() => {
+ if (!sessionsOpen) {
+ const share = readSessionShareSearch(window.location.search);
+ updateShareSearch({
+ view: 'sessions',
+ agentId: null,
+ sessionId: null,
+ timeRange: share.timeRange ?? defaultSessionTimeRange(),
+ });
+ }
+ shell.setSessionsOpen(true);
+ }}
+ >
+ <Icon name="clock-rotate-left" />
+ {!compact ? (
+ <>
+ <span className="truncate">Sessions</span>
+ <Icon name="chevron-right" className="ml-auto size-3.5 shrink-0 opacity-60" />
+ </>
+ ) : null}
+ </button>
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ SessionsBrowserButton: typeof SessionsBrowserButton;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/ThreadShell.tsx b/packages/trueforge-ui/src/atoms/ThreadShell.tsx
index b03d3d2b2..b012a8be9 100644
--- a/packages/trueforge-ui/src/atoms/ThreadShell.tsx
+++ b/packages/trueforge-ui/src/atoms/ThreadShell.tsx
@@ -78,7 +78,7 @@ export const MessageGroup = forwardRef<HTMLDivElement, MessageGroupProps>(({ cla
<div
ref={ref}
data-slot="aui_message-group"
- className={cn('flex flex-col gap-y-6 empty:hidden', className)}
+ className={cn('flex flex-col gap-y-4 empty:hidden', className)}
{...rest}
/>
));
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentCodeBlock.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentCodeBlock.tsx
new file mode 100644
index 000000000..ea2c61f8e
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentCodeBlock.tsx
@@ -0,0 +1,25 @@
+'use client';
+
+import { useSlot, useThemeMode } from '../../theme/SlotsProvider.js';
+import type { AgentCodeBlockProps } from './types.js';
+
+export function AgentCodeBlock({ code, language }: AgentCodeBlockProps) {
+ const SyntaxHighlighter = useSlot('SyntaxHighlighter');
+ const mode = useThemeMode();
+ return (
+ <SyntaxHighlighter
+ code={code}
+ language={language}
+ showLineNumbers
+ darkTheme={mode === 'dark'}
+ // Stretch the highlighted `pre` past the code so its theme background fills the panel.
+ className="m-0 flex min-h-full flex-col rounded-none [&>pre]:flex-1"
+ />
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentCodeBlock: typeof AgentCodeBlock;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentCodeSnippets.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentCodeSnippets.tsx
new file mode 100644
index 000000000..651593224
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentCodeSnippets.tsx
@@ -0,0 +1,90 @@
+'use client';
+
+import { useEffect, useState, type ComponentType } from 'react';
+import { Icon } from '../../icons/Icon.js';
+import { useSlot } from '../../theme/SlotsProvider.js';
+import { cn } from '../lib/cn.js';
+import type { AgentCodeSnippetsProps } from './types.js';
+
+type SnippetMode = 'stream' | 'nonStream';
+
+export default function AgentCodeSnippets({ snippets }: AgentCodeSnippetsProps) {
+ const AgentCodeBlock = useSlot('AgentCodeBlock');
+ const [selectedLanguage, setSelectedLanguage] = useState(snippets[0]?.language);
+ const [mode, setMode] = useState<SnippetMode>('stream');
+
+ useEffect(() => {
+ setSelectedLanguage(snippets[0]?.language);
+ setMode('stream');
+ }, [snippets]);
+
+ const selected = snippets.find(snippet => snippet.language === selectedLanguage) ?? snippets[0];
+
+ if (selected === undefined) {
+ return (
+ <div className="flex h-full min-h-64 items-center justify-center px-6 text-sm text-text-secondary">
+ No code samples for this agent.
+ </div>
+ );
+ }
+
+ return (
+ <div className="flex min-h-0 flex-1 flex-col gap-3 p-3 md:flex-row">
+ <nav aria-label="Code sample languages" className="flex shrink-0 gap-1 overflow-auto md:w-44 md:flex-col">
+ {snippets.map(snippet => (
+ <button
+ key={snippet.language}
+ type="button"
+ aria-current={selected.language === snippet.language ? 'page' : undefined}
+ className={cn(
+ 'flex h-9 shrink-0 cursor-pointer items-center gap-2 rounded-md px-2.5 text-left text-xs text-text-secondary',
+ 'hover:bg-ghost-button-hover hover:text-text-primary',
+ selected.language === snippet.language && 'bg-primary-button-bg/10 font-medium text-primary-button-bg',
+ )}
+ onClick={() => setSelectedLanguage(snippet.language)}
+ >
+ {snippet.icon ? (
+ <img src={snippet.icon} alt="" className="size-4 shrink-0 object-contain" />
+ ) : (
+ <Icon name="code" className="size-4 shrink-0" />
+ )}
+ {snippet.labelName}
+ </button>
+ ))}
+ </nav>
+
+ <section className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden rounded-lg border border-border bg-card-bg">
+ <div className="flex h-10 shrink-0 items-end gap-1 border-b border-border px-3">
+ {(
+ [
+ ['stream', 'Stream'],
+ ['nonStream', 'Non-stream'],
+ ] satisfies Array<[SnippetMode, string]>
+ ).map(([id, label]) => (
+ <button
+ key={id}
+ type="button"
+ className={cn(
+ 'relative h-10 cursor-pointer px-3 text-xs font-medium text-text-secondary',
+ mode === id &&
+ 'text-primary-button-bg after:absolute after:inset-x-0 after:bottom-0 after:h-0.5 after:bg-primary-button-bg',
+ )}
+ onClick={() => setMode(id)}
+ >
+ {label}
+ </button>
+ ))}
+ </div>
+ <div className="min-h-0 flex-1 overflow-auto">
+ <AgentCodeBlock code={selected.sampleCode[mode]} language={selected.language} />
+ </div>
+ </section>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentCodeSnippets: ComponentType<AgentCodeSnippetsProps>;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsHeader.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsHeader.tsx
new file mode 100644
index 000000000..ee2ba7a34
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsHeader.tsx
@@ -0,0 +1,85 @@
+'use client';
+
+import { Icon } from '../../icons/Icon.js';
+import { useShellMode } from '../../server/ShellModeContext.js';
+import { auiButtonClass } from '../lib/buttonClasses.js';
+import type { AgentDetailsHeaderProps } from './types.js';
+
+export function AgentDetailsHeader({ agentId, detail, onBack }: AgentDetailsHeaderProps) {
+ const shell = useShellMode();
+ const canEdit = shell.isComposerEnabled && detail != null;
+
+ const handleTry = () => {
+ if (detail == null) return;
+ shell.selectLibraryAgent({
+ isMutable: false,
+ agentId: detail.agentId,
+ agentName: detail.name,
+ });
+ };
+
+ const handleEdit = () => {
+ if (detail == null) return;
+ shell.selectLibraryAgent({
+ isMutable: true,
+ agentId: detail.agentId,
+ agentName: detail.name,
+ agentSpec: detail.agentSpec,
+ });
+ };
+
+ return (
+ <header className="shrink-0 border-b border-border bg-primary-bg">
+ <div className="flex min-w-0 flex-wrap items-center gap-2 px-3 py-2">
+ <button
+ type="button"
+ aria-label="Back to Agents Library"
+ title="Back to Agents Library"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={onBack}
+ >
+ <Icon name="arrow-left" />
+ </button>
+ <div className="min-w-0 flex-1">
+ <div className="flex min-w-0 items-center gap-1 text-xs text-text-secondary">
+ <button type="button" className="cursor-pointer truncate hover:text-text-primary" onClick={onBack}>
+ Agents Library
+ </button>
+ <Icon name="chevron-right" className="size-3 shrink-0" />
+ <span className="truncate">{detail?.name ?? agentId}</span>
+ </div>
+ <h1 className="truncate text-lg font-semibold tracking-tight text-text-primary">{detail?.name ?? agentId}</h1>
+ </div>
+ <div className="flex shrink-0 items-center gap-1.5">
+ <button
+ type="button"
+ aria-label="Try agent"
+ disabled={detail == null}
+ className={auiButtonClass({ variant: 'default', size: 'sm' })}
+ onClick={handleTry}
+ >
+ <Icon name="play" className="size-3.5" />
+ Try
+ </button>
+ {canEdit ? (
+ <button
+ type="button"
+ aria-label="Edit agent"
+ className={auiButtonClass({ variant: 'outline', size: 'sm' })}
+ onClick={handleEdit}
+ >
+ <Icon name="pencil" className="size-3.5" />
+ Edit
+ </button>
+ ) : null}
+ </div>
+ </div>
+ </header>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentDetailsHeader: typeof AgentDetailsHeader;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsPage.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsPage.tsx
new file mode 100644
index 000000000..dcbf6c79a
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsPage.tsx
@@ -0,0 +1,162 @@
+'use client';
+
+import { Suspense, useCallback, useEffect, useState } from 'react';
+import { useSessionShareSearch } from '../../hooks/useSessionShareSearch.js';
+import { 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';
+import { libraryAgentTabFromSearch } from '../../utils/sessionShareUrl.js';
+import { Skeleton } from '../primitives/Skeleton.js';
+import type { AgentDetailsPageProps } from './types.js';
+
+export function AgentDetailsPage({ agentId }: AgentDetailsPageProps) {
+ const sessionsServer = useOptionalAgentSessionsServer();
+ const shell = useShellMode();
+ const share = useSessionShareSearch();
+ const { updateShareSearch } = share;
+ const activeTab = libraryAgentTabFromSearch(share, agentId);
+ const AgentDetailsHeader = useSlot('AgentDetailsHeader');
+ const AgentDetailsTabs = useSlot('AgentDetailsTabs');
+ const AgentDetailsUnavailable = useSlot('AgentDetailsUnavailable');
+ const AgentOverview = useSlot('AgentOverview');
+ const AgentSessions = useSlot('AgentSessions');
+ const AgentCodeSnippets = useSlot('AgentCodeSnippets');
+ const [detail, setDetail] = useState<AgentDetail>();
+ const [detailFailed, setDetailFailed] = useState(false);
+ const [snippets, setSnippets] = useState<CodeSnippet[]>();
+ const [snippetsFailed, setSnippetsFailed] = useState(false);
+
+ const goBack = useCallback(() => {
+ updateShareSearch({
+ sessionId: null,
+ agentId: null,
+ tab: null,
+ view: null,
+ timeRange: null,
+ });
+ shell.closeLibraryAgent();
+ }, [shell, updateShareSearch]);
+
+ useEffect(() => {
+ const onKeyDown = (event: KeyboardEvent) => {
+ if (event.key !== 'Escape') return;
+ event.stopImmediatePropagation();
+ goBack();
+ };
+ window.addEventListener('keydown', onKeyDown, true);
+ return () => window.removeEventListener('keydown', onKeyDown, true);
+ }, [goBack]);
+
+ useEffect(() => {
+ if (sessionsServer == null) return;
+ let cancelled = false;
+ void sessionsServer.getAgent({ agentId }).then(
+ result => {
+ if (!cancelled) setDetail(result);
+ },
+ () => {
+ if (!cancelled) setDetailFailed(true);
+ },
+ );
+ return () => {
+ cancelled = true;
+ };
+ }, [agentId, sessionsServer]);
+
+ useEffect(() => {
+ if (activeTab !== 'code' || sessionsServer == null || snippets !== undefined || snippetsFailed) return;
+ let cancelled = false;
+ void sessionsServer.getCodeSnippets({ agentId }).then(
+ result => {
+ if (!cancelled) setSnippets(result);
+ },
+ () => {
+ if (!cancelled) setSnippetsFailed(true);
+ },
+ );
+ return () => {
+ cancelled = true;
+ };
+ }, [activeTab, agentId, sessionsServer, snippets, snippetsFailed]);
+
+ let content;
+ if (sessionsServer == null) {
+ content = (
+ <AgentDetailsUnavailable
+ onBack={goBack}
+ reason="This host does not provide agent details. Return to the library to choose an agent."
+ />
+ );
+ } else if (detailFailed) {
+ content = <AgentDetailsUnavailable onBack={goBack} />;
+ } else if (detail == null) {
+ content = (
+ <div
+ className="grid min-h-0 gap-3 overflow-auto p-4 md:grid-cols-[minmax(0,1fr)_18rem]"
+ role="status"
+ aria-label="Loading agent details"
+ >
+ <Skeleton className="min-h-80 rounded-lg" />
+ <div className="space-y-3">
+ {['mcp', 'skills', 'model', 'execution'].map(item => (
+ <Skeleton key={item} className="h-24 rounded-lg" />
+ ))}
+ </div>
+ </div>
+ );
+ } else if (activeTab === 'overview') {
+ content = <AgentOverview detail={detail} />;
+ } else if (activeTab === 'sessions') {
+ content = <AgentSessions agentId={agentId} />;
+ } else if (snippetsFailed) {
+ content = <AgentDetailsUnavailable onBack={goBack} reason="Code samples for this agent could not be loaded." />;
+ } else if (snippets === undefined) {
+ content = (
+ <div className="flex min-h-64 gap-3 p-3" role="status" aria-label="Loading code samples">
+ <Skeleton className="hidden w-44 shrink-0 rounded-lg md:block" />
+ <Skeleton className="min-h-64 min-w-0 flex-1 rounded-lg" />
+ </div>
+ );
+ } else {
+ content = <AgentCodeSnippets snippets={snippets} />;
+ }
+
+ return (
+ <div className="flex h-full min-h-0 w-full flex-col bg-primary-bg">
+ <AgentDetailsHeader agentId={agentId} detail={detail} onBack={goBack} />
+ {sessionsServer != null && !detailFailed ? (
+ <AgentDetailsTabs
+ activeTab={activeTab}
+ onTabChange={tab =>
+ updateShareSearch({
+ agentId,
+ tab,
+ view: null,
+ timeRange: null,
+ ...(tab === 'sessions' ? {} : { sessionId: null }),
+ })
+ }
+ />
+ ) : null}
+ {/* Tabs own their scrolling so long instructions / code samples stay inside their card. */}
+ <main className="flex min-h-0 flex-1 flex-col overflow-hidden" role="tabpanel">
+ <Suspense
+ fallback={
+ <div className="p-4" role="status" aria-label="Loading">
+ <Skeleton className="min-h-64 rounded-lg" />
+ </div>
+ }
+ >
+ {content}
+ </Suspense>
+ </main>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentDetailsPage: typeof AgentDetailsPage;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsTabs.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsTabs.tsx
new file mode 100644
index 000000000..a1978e5ee
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsTabs.tsx
@@ -0,0 +1,47 @@
+'use client';
+
+import { Icon } from '../../icons/Icon.js';
+import { cn } from '../lib/cn.js';
+import type { AgentDetailsTab, AgentDetailsTabsProps } from './types.js';
+
+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' },
+];
+
+export function AgentDetailsTabs({ activeTab, onTabChange }: 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>
+ ))}
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentDetailsTabs: typeof AgentDetailsTabs;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsUnavailable.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsUnavailable.tsx
new file mode 100644
index 000000000..a634576cc
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentDetailsUnavailable.tsx
@@ -0,0 +1,29 @@
+import { Icon } from '../../icons/Icon.js';
+import { auiButtonClass } from '../lib/buttonClasses.js';
+import type { AgentDetailsUnavailableProps } from './types.js';
+
+export function AgentDetailsUnavailable({ onBack, reason }: AgentDetailsUnavailableProps) {
+ return (
+ <div className="flex h-full min-h-64 flex-col items-center justify-center gap-3 px-6 text-center">
+ <span className="flex size-11 items-center justify-center rounded-full bg-secondary-bg text-text-secondary">
+ <Icon name="circle-exclamation" />
+ </span>
+ <div>
+ <h2 className="text-base font-semibold text-text-primary">Agent details unavailable</h2>
+ <p className="mt-1 max-w-md text-sm text-text-secondary">
+ {reason ?? 'The agent details could not be loaded. Please try again later.'}
+ </p>
+ </div>
+ <button type="button" className={auiButtonClass({ variant: 'outline', size: 'sm' })} onClick={onBack}>
+ <Icon name="arrow-left" className="size-3.5" />
+ Back to Agents Library
+ </button>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentDetailsUnavailable: typeof AgentDetailsUnavailable;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentOverview.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentOverview.tsx
new file mode 100644
index 000000000..8467742d3
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentOverview.tsx
@@ -0,0 +1,225 @@
+'use client';
+
+import { useState, type ComponentType } from 'react';
+import { Icon } from '../../icons/Icon.js';
+import { useSlot } from '../../theme/SlotsProvider.js';
+import { cn } from '../lib/cn.js';
+import type { AgentOverviewProps } from './types.js';
+
+type InstructionsView = 'markdown' | 'raw';
+
+const valueClassName = 'text-right font-mono text-primary-button-bg';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value != null;
+}
+
+function readName(value: object): string | null {
+ if (!('name' in value) || typeof value.name !== 'string') return null;
+ return value.name;
+}
+
+function readRecordValue(record: Record<string, unknown> | null, ...keys: string[]): unknown {
+ for (const key of keys) {
+ const value = record?.[key];
+ if (value !== undefined) return value;
+ }
+ return undefined;
+}
+
+function hasAllTools(value: object): boolean {
+ if (!isRecord(value)) return false;
+ const tools = readRecordValue(value, 'enableTools', 'enable_tools');
+ return tools === undefined || (Array.isArray(tools) && tools.includes('@all'));
+}
+
+function displayModelName(name: string): string {
+ const slash = name.lastIndexOf('/');
+ return slash >= 0 ? name.slice(slash + 1) : name;
+}
+
+export default function AgentOverview({ detail }: AgentOverviewProps) {
+ const Markdown = useSlot('Markdown');
+ const AgentOverviewCard = useSlot('AgentOverviewCard');
+ const [instructionsView, setInstructionsView] = useState<InstructionsView>('markdown');
+ const [copied, setCopied] = useState(false);
+ const spec = detail.agentSpec;
+ const skills = spec.skills ?? [];
+ const connectors = spec.mcpServers ?? [];
+ const modelParams = isRecord(spec.model.params) ? spec.model.params : null;
+ const maxTokens = readRecordValue(modelParams, 'maxTokens', 'max_tokens');
+ const temperature = readRecordValue(modelParams, 'temperature');
+ const config = isRecord(spec.config) ? spec.config : null;
+ const sandbox = isRecord(config?.sandbox) ? config.sandbox : null;
+ const instructions = spec.instructions?.trim() ? spec.instructions : null;
+ const execution = [
+ ['Sandbox', typeof sandbox?.enabled === 'boolean' ? (sandbox.enabled ? 'Enabled' : 'Disabled') : undefined],
+ ['Iteration limit', readRecordValue(config, 'iterationLimit', 'iteration_limit')],
+ ['Response format', readRecordValue(config, 'responseFormat', 'response_format')],
+ ].filter((entry): entry is [string, string | number] => {
+ return typeof entry[1] === 'string' || typeof entry[1] === 'number';
+ });
+ const capabilities = [
+ ['Generative UI', spec.config?.generativeUi?.enabled],
+ ['Dynamic sub-agents', spec.config?.dynamicSubAgents?.enabled],
+ ['Ask user questions', spec.config?.askUserQuestions?.enabled],
+ ].filter((entry): entry is [string, boolean] => typeof entry[1] === 'boolean');
+ const toggleLabel = instructionsView === 'markdown' ? 'Raw' : 'Markdown';
+
+ return (
+ <div className="grid min-h-0 flex-1 gap-3 overflow-auto p-4 md:grid-cols-[minmax(0,1fr)_18rem] md:overflow-hidden">
+ <section className="flex min-h-64 flex-col rounded-lg border border-border bg-card-bg p-4 text-text-primary">
+ <div className="mb-3 flex shrink-0 items-center justify-between gap-2">
+ <h2 className="flex items-center gap-1.5 text-sm font-semibold">
+ <Icon name="file" className="size-4 text-text-secondary" />
+ Instructions
+ </h2>
+ {instructions ? (
+ <div
+ className="inline-flex h-7 items-stretch overflow-hidden rounded-md border border-border bg-primary-bg text-xs font-medium text-text-secondary"
+ role="group"
+ aria-label="Instructions actions"
+ >
+ <button
+ type="button"
+ aria-label={`Show ${toggleLabel}`}
+ onClick={() => setInstructionsView(view => (view === 'markdown' ? 'raw' : 'markdown'))}
+ className="cursor-pointer px-2.5 transition-colors hover:bg-ghost-button-hover hover:text-text-primary"
+ >
+ {toggleLabel}
+ </button>
+ <span className="w-px self-stretch bg-border" aria-hidden />
+ <button
+ type="button"
+ title={copied ? 'Copied!' : 'Copy'}
+ aria-label={copied ? 'Copied!' : 'Copy'}
+ onClick={() => {
+ void navigator.clipboard.writeText(instructions).then(() => {
+ setCopied(true);
+ setTimeout(() => setCopied(false), 2000);
+ });
+ }}
+ className="inline-flex cursor-pointer items-center justify-center px-2 transition-colors hover:bg-ghost-button-hover hover:text-text-primary"
+ >
+ <Icon name={copied ? 'check' : 'copy'} size={12} />
+ </button>
+ </div>
+ ) : null}
+ </div>
+ <div className="min-h-0 flex-1 overflow-auto">
+ {instructions ? (
+ instructionsView === 'markdown' ? (
+ <Markdown content={instructions} readOnly className="text-sm" />
+ ) : (
+ <pre className="whitespace-pre-wrap break-words font-mono text-sm text-text-primary">{instructions}</pre>
+ )
+ ) : (
+ <p className="text-sm text-text-secondary">No instructions for this agent.</p>
+ )}
+ </div>
+ </section>
+
+ <aside className="flex min-h-0 min-w-0 flex-col gap-3 md:overflow-auto">
+ <AgentOverviewCard title="MCP Servers" icon="plug" count={connectors.length}>
+ {connectors.length === 0 ? (
+ <p className="text-xs text-text-secondary">No connectors attached.</p>
+ ) : (
+ <ul className="space-y-1.5">
+ {connectors.map((connector, index) => (
+ <li
+ key={`${readName(connector) ?? 'connector'}-${index}`}
+ className="rounded-md bg-secondary-bg px-2 py-1.5 text-xs"
+ >
+ <span className="flex items-center justify-between gap-2">
+ <span className="truncate">{readName(connector) ?? `Connector ${index + 1}`}</span>
+ {hasAllTools(connector) ? (
+ <span className="shrink-0 rounded-full bg-primary-button-bg/10 px-1.5 py-0.5 text-[10px] text-primary-button-bg">
+ All tools
+ </span>
+ ) : null}
+ </span>
+ </li>
+ ))}
+ </ul>
+ )}
+ </AgentOverviewCard>
+
+ <AgentOverviewCard title="Attached Skills" icon="lightbulb" count={skills.length}>
+ {skills.length === 0 ? (
+ <p className="text-xs text-text-secondary">No skills attached.</p>
+ ) : (
+ <ul className="space-y-1.5">
+ {skills.map((skill, index) => (
+ <li
+ key={`${readName(skill) ?? 'skill'}-${index}`}
+ className="rounded-md bg-secondary-bg px-2 py-1.5 text-xs"
+ >
+ {readName(skill) ?? `Skill ${index + 1}`}
+ </li>
+ ))}
+ </ul>
+ )}
+ </AgentOverviewCard>
+
+ <AgentOverviewCard title="Model Configuration" icon="cpu">
+ <dl className="grid grid-cols-[auto_minmax(0,1fr)] gap-x-3 gap-y-1 text-xs">
+ <dt className="text-text-secondary">Model</dt>
+ <dd className={cn(valueClassName, 'truncate')} title={spec.model.name}>
+ {displayModelName(spec.model.name)}
+ </dd>
+ {typeof maxTokens === 'number' ? (
+ <>
+ <dt className="text-text-secondary">Max tokens</dt>
+ <dd className={valueClassName}>{maxTokens}</dd>
+ </>
+ ) : null}
+ {spec.model.params?.reasoningEffort !== undefined ? (
+ <>
+ <dt className="text-text-secondary">Reasoning</dt>
+ <dd className={valueClassName}>{spec.model.params.reasoningEffort}</dd>
+ </>
+ ) : null}
+ {typeof temperature === 'number' ? (
+ <>
+ <dt className="text-text-secondary">Temperature</dt>
+ <dd className={valueClassName}>{temperature}</dd>
+ </>
+ ) : null}
+ </dl>
+ </AgentOverviewCard>
+
+ {execution.length > 0 ? (
+ <AgentOverviewCard title="Execution" icon="terminal">
+ <dl className="space-y-1 text-xs">
+ {execution.map(([label, value]) => (
+ <div key={label} className="flex justify-between gap-3">
+ <dt className="text-text-secondary">{label}</dt>
+ <dd className={valueClassName}>{value}</dd>
+ </div>
+ ))}
+ </dl>
+ </AgentOverviewCard>
+ ) : null}
+
+ {capabilities.length > 0 ? (
+ <AgentOverviewCard title="Capabilities" icon="cube">
+ <dl className="space-y-1 text-xs">
+ {capabilities.map(([label, enabled]) => (
+ <div key={label} className="flex justify-between gap-3">
+ <dt className="text-text-secondary">{label}</dt>
+ <dd className={valueClassName}>{enabled ? 'Enabled' : 'Disabled'}</dd>
+ </div>
+ ))}
+ </dl>
+ </AgentOverviewCard>
+ ) : null}
+ </aside>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentOverview: ComponentType<AgentOverviewProps>;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentOverviewCard.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentOverviewCard.tsx
new file mode 100644
index 000000000..eb1ba46a1
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentOverviewCard.tsx
@@ -0,0 +1,21 @@
+import { Icon } from '../../icons/Icon.js';
+import type { AgentOverviewCardProps } from './types.js';
+
+export function AgentOverviewCard({ title, icon, count, children }: AgentOverviewCardProps) {
+ return (
+ <section className="rounded-lg border border-border bg-card-bg p-3 text-text-primary">
+ <h2 className="mb-2 flex items-center gap-1.5 text-xs font-semibold">
+ <Icon name={icon} className="size-3.5 text-text-secondary" />
+ {title}
+ {count !== undefined ? <span className="text-text-secondary">({count})</span> : null}
+ </h2>
+ {children}
+ </section>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentOverviewCard: typeof AgentOverviewCard;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionDetailHeader.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionDetailHeader.tsx
new file mode 100644
index 000000000..d68da3bd9
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionDetailHeader.tsx
@@ -0,0 +1,76 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { Icon } from '../../icons/Icon.js';
+import { buildAgentSessionShareUrl } from '../../utils/sessionShareUrl.js';
+import { cn } from '../lib/cn.js';
+import { LightTooltip } from '../primitives/Tooltip.js';
+import type { AgentSessionDetailHeaderProps } from './types.js';
+
+export { buildAgentSessionShareUrl } from '../../utils/sessionShareUrl.js';
+
+export function AgentSessionDetailHeader({
+ title,
+ sessionId,
+ agentId,
+ createdAt,
+ view,
+ onClose,
+}: AgentSessionDetailHeaderProps) {
+ const [copied, setCopied] = useState(false);
+
+ useEffect(() => {
+ if (!copied) return undefined;
+ const timer = window.setTimeout(() => setCopied(false), 2000);
+ return () => window.clearTimeout(timer);
+ }, [copied]);
+
+ const copySessionLink = async () => {
+ try {
+ await navigator.clipboard.writeText(buildAgentSessionShareUrl({ sessionId, agentId, createdAt, view }));
+ setCopied(true);
+ } catch {
+ // Clipboard may be unavailable; ignore.
+ }
+ };
+
+ return (
+ <div className="flex shrink-0 items-center gap-3 border-b border-border px-4 py-3">
+ <div className="flex min-w-0 flex-1 items-center gap-1.5">
+ <h2 className="min-w-0 truncate text-sm font-semibold text-text-primary">{title}</h2>
+ <code className="min-w-0 truncate font-mono text-xs text-text-secondary">{sessionId}</code>
+ <LightTooltip title={copied ? 'Copied' : 'Copy session link'} dismissOnClick={false}>
+ <button
+ type="button"
+ aria-label="Copy session link"
+ className={cn(
+ 'inline-flex size-6 shrink-0 items-center justify-center rounded-md text-text-secondary',
+ 'hover:bg-ghost-button-hover hover:text-text-primary',
+ )}
+ onClick={() => void copySessionLink()}
+ >
+ <Icon name="link" className="size-3.5" />
+ </button>
+ </LightTooltip>
+ </div>
+ <button
+ type="button"
+ aria-label="Close session details"
+ className={cn(
+ 'inline-flex size-8 shrink-0 items-center justify-center rounded-md text-text-secondary',
+ 'hover:bg-ghost-button-hover hover:text-text-primary',
+ )}
+ onClick={onClose}
+ >
+ <Icon name="xmark" className="size-4" />
+ </button>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentSessionDetailHeader: typeof AgentSessionDetailHeader;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionEventTimeline.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionEventTimeline.tsx
new file mode 100644
index 000000000..f7a00055d
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionEventTimeline.tsx
@@ -0,0 +1,74 @@
+'use client';
+
+import { useCallback, useMemo, useState, type ComponentType } from 'react';
+
+import { useSlot } from '../../theme/SlotsProvider.js';
+import { SESSION_EVENT_TYPES, type SessionEventType } from '../../utils/sessionEventTimeline.js';
+import { cn } from '../lib/cn.js';
+import type { AgentSessionEventTimelineProps } from './types.js';
+
+export function AgentSessionEventTimeline({ turns, segments, onSelectTurn }: AgentSessionEventTimelineProps) {
+ const AgentSessionEventTimelineChart = useSlot('AgentSessionEventTimelineChart');
+ const [hiddenTypes, setHiddenTypes] = useState<Set<SessionEventType>>(() => new Set());
+
+ const availableEventTypes = useMemo(() => {
+ const available = new Set(segments.map(segment => segment.type));
+ return SESSION_EVENT_TYPES.filter(eventType => available.has(eventType.id));
+ }, [segments]);
+
+ const handleToggleType = useCallback((type: SessionEventType) => {
+ setHiddenTypes(previous => {
+ const next = new Set(previous);
+ if (next.has(type)) next.delete(type);
+ else next.add(type);
+ return next;
+ });
+ }, []);
+
+ if (segments.length === 0) return null;
+
+ return (
+ <div className="w-full" data-slot="agent-session-event-timeline">
+ <div
+ className="flex flex-wrap items-center gap-2 border-b border-border px-3 py-2"
+ data-slot="agent-session-event-types"
+ >
+ <span className="text-xs font-medium uppercase text-text-secondary">Event types</span>
+ <div className="flex flex-wrap items-center gap-1">
+ {availableEventTypes.map(eventType => {
+ const isVisible = !hiddenTypes.has(eventType.id);
+ return (
+ <button
+ key={eventType.id}
+ type="button"
+ aria-pressed={isVisible}
+ className={cn(
+ 'flex items-center gap-1.5 rounded-full border px-2 py-0.5 text-xs font-medium',
+ isVisible ? 'border-border text-text-primary' : 'border-transparent text-text-secondary opacity-80',
+ )}
+ onClick={() => handleToggleType(eventType.id)}
+ >
+ <span className="size-2 rounded-sm" style={{ backgroundColor: eventType.color }} />
+ {eventType.label}
+ </button>
+ );
+ })}
+ </div>
+ </div>
+ <div className="w-full py-2">
+ <AgentSessionEventTimelineChart
+ turns={turns}
+ segments={segments}
+ hiddenTypes={hiddenTypes}
+ onSelectTurn={onSelectTurn}
+ />
+ </div>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentSessionEventTimeline: ComponentType<AgentSessionEventTimelineProps>;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionEventTimelineChart.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionEventTimelineChart.tsx
new file mode 100644
index 000000000..c488b05d9
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionEventTimelineChart.tsx
@@ -0,0 +1,442 @@
+'use client';
+
+import {
+ BarElement,
+ Chart as ChartJS,
+ LinearScale,
+ Tooltip,
+ type ChartData,
+ type ChartOptions,
+ type Plugin,
+} from 'chart.js';
+import { useEffect, useMemo, useRef, useState, type ComponentType, type CSSProperties } from 'react';
+import { Bar } from 'react-chartjs-2';
+
+import { useThemeMode } from '../../theme/SlotsProvider.js';
+import {
+ formatTimelineDuration,
+ getSessionEventColor,
+ getSessionEventHoverColor,
+ getSessionEventLabel,
+ MAIN_THREAD_ID,
+ type SessionEventTimelineSegment,
+} from '../../utils/sessionEventTimeline.js';
+import {
+ buildTimelineAxisTicks,
+ getActiveTimelineMs,
+ getSubAgentLanes,
+ getTimelineHoverTargetId,
+ getTimelineLayout,
+ getTimelineRange,
+ groupOverlappingToolCalls,
+ pickLongestNonOverlappingSegments,
+ TIMELINE_TYPE,
+ type TimelineGap,
+ type TimelineHoverTarget,
+ type TimelineTurnBar,
+} from '../../utils/sessionEventTimelineChart.js';
+import { LightTooltip } from '../primitives/Tooltip.js';
+import {
+ hasSessionEventTooltip,
+ SessionEventTooltip,
+ SessionToolCallGroupTooltip,
+ SessionTurnTooltip,
+} from './AgentSessionTimelineTooltip.js';
+import type { AgentSessionEventTimelineChartProps } from './types.js';
+
+ChartJS.register(LinearScale, BarElement, Tooltip);
+
+const MARKER_PX = 4;
+const TURN_GAP_PX = 12;
+const END_PAD_PX = 12;
+const BAR_RADIUS_PX = 2;
+const ROW_GAP_PX = 8;
+const OVERHEAD_PX = 30;
+
+type BarPoint = { x: [number, number]; y: number };
+
+function rowCenters(heights: number[], gap: number): { centers: number[]; band: number } {
+ const centers: number[] = [];
+ let offset = 0;
+ for (const height of heights) {
+ centers.push(offset + height / 2);
+ offset += height + gap;
+ }
+ return { centers, band: Math.max(0, offset - gap) };
+}
+
+function eventOrder(type: SessionEventTimelineSegment['type']): number {
+ if (type === 'sub_agent') return 0;
+ if (type === 'model') return 2;
+ return 1;
+}
+
+function turnBarLabelPoint(element: object): { x: number; y: number } | null {
+ if (!('x' in element) || !('y' in element) || !('base' in element)) return null;
+ const { x, y, base } = element;
+ if (typeof x !== 'number' || typeof y !== 'number' || typeof base !== 'number') return null;
+ return { x: (x + base) / 2, y };
+}
+
+export function AgentSessionEventTimelineChart({
+ turns,
+ segments,
+ hiddenTypes,
+ onSelectTurn,
+}: AgentSessionEventTimelineChartProps) {
+ const mode = useThemeMode();
+ const isDark = mode === 'dark';
+ const axis = isDark ? '#8c8c92' : '#71717a';
+ const grid = isDark ? '#27272a' : '#e4e4e7';
+ const turnFill = isDark ? '#3f3f46' : '#e4e4e7';
+ const turnHover = isDark ? '#52525b' : '#d4d4d8';
+ const wrapperRef = useRef<HTMLDivElement>(null);
+ const [widthPx, setWidthPx] = useState(0);
+ const [overheadPx, setOverheadPx] = useState(OVERHEAD_PX);
+ const [tooltipTarget, setTooltipTarget] = useState<TimelineHoverTarget | null>(null);
+ const [tooltipAnchor, setTooltipAnchor] = useState<{ left: number; top: number } | null>(null);
+ const tooltipIdRef = useRef('');
+
+ useEffect(() => {
+ const wrapper = wrapperRef.current;
+ if (wrapper == null) return undefined;
+ const update = () => setWidthPx(wrapper.clientWidth);
+ update();
+ const observer = new ResizeObserver(update);
+ observer.observe(wrapper);
+ return () => observer.disconnect();
+ }, []);
+
+ const activeTotalMs = Math.max(1, ...segments.map(segment => segment.endMs));
+ const { turnStartsMs, turnOrdinals, turnRanges } = useMemo(() => getTimelineLayout(segments), [segments]);
+ const gapCount = Math.max(0, turnStartsMs.length - 1);
+ const scaleWidthPx = Math.max(widthPx / 2, widthPx - TURN_GAP_PX * gapCount - END_PAD_PX);
+ const msPerPx = activeTotalMs / Math.max(1, scaleWidthPx);
+ const turnGapMs = TURN_GAP_PX * msPerPx;
+ const totalMs = activeTotalMs + gapCount * turnGapMs;
+ const timelineMaxMs = totalMs + END_PAD_PX * msPerPx;
+ const timelineGaps = useMemo<TimelineGap[]>(
+ () =>
+ turnStartsMs
+ .slice(1)
+ .map((startMs, index) => ({ startMs: startMs + index * turnGapMs, endMs: startMs + (index + 1) * turnGapMs })),
+ [turnGapMs, turnStartsMs],
+ );
+
+ const visibleSegments = useMemo(
+ () =>
+ segments.flatMap(segment => {
+ if (hiddenTypes.has(segment.type)) return [];
+ const shiftMs = (turnOrdinals.get(segment.turnIndex) ?? 0) * turnGapMs;
+ return [{ ...segment, startMs: segment.startMs + shiftMs, endMs: segment.endMs + shiftMs }];
+ }),
+ [hiddenTypes, segments, turnGapMs, turnOrdinals],
+ );
+ const turnBars = useMemo<TimelineTurnBar[]>(
+ () =>
+ turnRanges.length < 2
+ ? []
+ : turnRanges.map(range => ({
+ ...range,
+ id: `turn-${range.turnIndex}`,
+ durationMs: range.endMs - range.startMs,
+ startMs: range.startMs + range.ordinal * turnGapMs,
+ endMs: range.endMs + range.ordinal * turnGapMs + MARKER_PX * msPerPx,
+ })),
+ [msPerPx, turnGapMs, turnRanges],
+ );
+ const subAgentSegments = useMemo(
+ () => visibleSegments.filter(segment => segment.type === 'sub_agent'),
+ [visibleSegments],
+ );
+ const mainSubAgents = useMemo(() => pickLongestNonOverlappingSegments(subAgentSegments), [subAgentSegments]);
+ const subAgentLanes = useMemo(
+ () => getSubAgentLanes({ subAgentSegments, threadSegments: visibleSegments, minWidthMs: MARKER_PX * msPerPx }),
+ [msPerPx, subAgentSegments, visibleSegments],
+ );
+ const mainCandidates = useMemo(() => {
+ const kept = new Set(mainSubAgents.map(segment => segment.id));
+ return visibleSegments.filter(
+ segment => segment.threadId === MAIN_THREAD_ID || (segment.type === 'sub_agent' && kept.has(segment.id)),
+ );
+ }, [mainSubAgents, visibleSegments]);
+ const toolCallGroups = useMemo(
+ () =>
+ groupOverlappingToolCalls(mainCandidates.filter(segment => segment.type === 'tool_call')).filter(
+ group => group.segments.length > 1,
+ ),
+ [mainCandidates],
+ );
+ const groupedIds = useMemo(
+ () => new Set(toolCallGroups.flatMap(group => group.segments.map(segment => segment.id))),
+ [toolCallGroups],
+ );
+ const mainEventSegments = useMemo(
+ () => mainCandidates.filter(segment => !groupedIds.has(segment.id)),
+ [groupedIds, mainCandidates],
+ );
+ const laneCount = subAgentLanes.reduce((count, lane) => Math.max(count, lane.lane + 1), 0);
+ const hasTurnRow = turnBars.length > 0;
+ const eventRow = hasTurnRow ? 1 : 0;
+ const { centers, band } = useMemo(
+ () => rowCenters([...(hasTurnRow ? [16] : []), 28, ...Array.from({ length: laneCount }, () => 12)], ROW_GAP_PX),
+ [hasTurnRow, laneCount],
+ );
+
+ const chartTargets = useMemo<Array<TimelineHoverTarget | null>>(
+ () => [
+ ...turnBars.map((bar): TimelineHoverTarget => ({ type: TIMELINE_TYPE.turn, bar })),
+ ...subAgentLanes.flatMap(lane =>
+ lane.segments.map((segment): TimelineHoverTarget => ({ type: TIMELINE_TYPE.event, segment })),
+ ),
+ ...mainEventSegments.map((segment): TimelineHoverTarget | null =>
+ segment.type === 'sub_agent' ? null : { type: TIMELINE_TYPE.event, segment },
+ ),
+ ...toolCallGroups.map((group): TimelineHoverTarget => ({ type: TIMELINE_TYPE.toolCallGroup, group })),
+ ],
+ [mainEventSegments, subAgentLanes, toolCallGroups, turnBars],
+ );
+
+ const barDataset = ({
+ label,
+ range,
+ y,
+ color,
+ hover,
+ thickness,
+ order = 1,
+ inflateAmount,
+ }: {
+ label: string;
+ range: TimelineGap;
+ y: number;
+ color: string;
+ hover: string;
+ thickness: number;
+ order?: number;
+ inflateAmount?: number;
+ }) => ({
+ label,
+ data: [{ x: getTimelineRange(range), y }] satisfies BarPoint[],
+ backgroundColor: color,
+ hoverBackgroundColor: hover,
+ hoverBorderColor: hover,
+ borderWidth: 0,
+ borderSkipped: false,
+ borderRadius: BAR_RADIUS_PX,
+ minBarLength: MARKER_PX,
+ barThickness: thickness,
+ grouped: false,
+ order,
+ ...(inflateAmount == null ? {} : { inflateAmount }),
+ });
+
+ const chartData = useMemo<ChartData<'bar', BarPoint[], string>>(
+ () => ({
+ datasets: [
+ ...turnBars.map(bar =>
+ barDataset({
+ label: `Turn ${bar.ordinal + 1}`,
+ range: bar,
+ y: centers[0] ?? 0,
+ color: turnFill,
+ hover: turnHover,
+ thickness: 16,
+ }),
+ ),
+ ...subAgentLanes.flatMap(lane =>
+ lane.segments.map(segment =>
+ barDataset({
+ label: `${getSessionEventLabel(segment.type)}: ${segment.title}`,
+ range: segment,
+ y: centers[eventRow + 1 + lane.lane] ?? 0,
+ color: getSessionEventColor(segment.type),
+ hover: getSessionEventHoverColor(segment.type),
+ thickness: 12,
+ order: eventOrder(segment.type),
+ inflateAmount: 0.5,
+ }),
+ ),
+ ),
+ ...mainEventSegments.map(segment =>
+ barDataset({
+ label: `${getSessionEventLabel(segment.type)}: ${segment.title}`,
+ range: segment,
+ y: centers[eventRow] ?? 0,
+ color: getSessionEventColor(segment.type),
+ hover: getSessionEventHoverColor(segment.type),
+ thickness: 28,
+ order: eventOrder(segment.type),
+ inflateAmount: 0.5,
+ }),
+ ),
+ ...toolCallGroups.map(group =>
+ barDataset({
+ label: 'Parallel tool calls',
+ range: group,
+ y: centers[eventRow] ?? 0,
+ color: getSessionEventColor('tool_call'),
+ hover: getSessionEventHoverColor('tool_call'),
+ thickness: 28,
+ order: eventOrder('tool_call'),
+ inflateAmount: 0.5,
+ }),
+ ),
+ ],
+ }),
+ [centers, eventRow, mainEventSegments, subAgentLanes, toolCallGroups, turnBars, turnFill, turnHover],
+ );
+
+ const turnLabelPlugin = useMemo<Plugin<'bar'>>(
+ () => ({
+ id: 'turnLabels',
+ afterDatasetsDraw(chart) {
+ const { ctx } = chart;
+ ctx.save();
+ ctx.fillStyle = axis;
+ ctx.font = '500 10px sans-serif';
+ ctx.textAlign = 'center';
+ ctx.textBaseline = 'middle';
+ turnBars.forEach((bar, index) => {
+ const element = chart.getDatasetMeta(index).data[0];
+ if (element == null) return;
+ const point = turnBarLabelPoint(element);
+ if (point) ctx.fillText(`T${bar.ordinal + 1}`, point.x, point.y);
+ });
+ ctx.restore();
+ },
+ }),
+ [axis, turnBars],
+ );
+ const overheadPlugin = useMemo<Plugin<'bar'>>(
+ () => ({
+ id: 'timelineOverhead',
+ afterLayout(chart) {
+ const next = Math.round(chart.height - chart.chartArea.height);
+ setOverheadPx(previous => (previous === next ? previous : next));
+ },
+ }),
+ [],
+ );
+
+ const chartOptions = useMemo<ChartOptions<'bar'>>(
+ () => ({
+ indexAxis: 'y',
+ animation: false,
+ responsive: true,
+ maintainAspectRatio: false,
+ onClick: (_event, elements) => {
+ const target = chartTargets[elements[0]?.datasetIndex ?? -1];
+ if (target?.type === TIMELINE_TYPE.turn) onSelectTurn?.(target.bar.turnIndex);
+ },
+ onHover: (event, elements) => {
+ const hoveredDatasetIndex = elements[0]?.datasetIndex;
+ const next = hoveredDatasetIndex == null ? null : (chartTargets[hoveredDatasetIndex] ?? null);
+ const native = event.native;
+ if (native?.target instanceof HTMLElement) {
+ native.target.style.cursor = next?.type === TIMELINE_TYPE.turn ? 'pointer' : 'default';
+ }
+ // Pointer between bars keeps the current tooltip; a bar without a tooltip dismisses it.
+ if (hoveredDatasetIndex == null) return;
+ const nextId = getTimelineHoverTargetId(next);
+ if (tooltipIdRef.current === nextId) return;
+ tooltipIdRef.current = nextId;
+ setTooltipTarget(next);
+ if (next == null) {
+ setTooltipAnchor(null);
+ return;
+ }
+ if (!(native instanceof MouseEvent) || !(native.target instanceof HTMLElement)) return;
+ setTooltipAnchor({
+ left: native.clientX,
+ top: native.target.getBoundingClientRect().bottom,
+ });
+ },
+ plugins: { legend: { display: false }, tooltip: { enabled: false } },
+ scales: {
+ x: {
+ type: 'linear',
+ position: 'top',
+ min: 0,
+ max: timelineMaxMs,
+ grid: { color: grid },
+ border: { color: grid },
+ afterBuildTicks: scale => {
+ scale.ticks = buildTimelineAxisTicks({
+ ticks: scale.ticks,
+ totalMs,
+ timelineMaxMs,
+ });
+ },
+ ticks: {
+ color: axis,
+ autoSkip: false,
+ includeBounds: true,
+ maxTicksLimit: 9,
+ stepSize: timelineMaxMs / 8,
+ callback: value => {
+ const timelineMs = Number(value);
+ return timelineMs <= totalMs ? formatTimelineDuration(getActiveTimelineMs(timelineMs, timelineGaps)) : '';
+ },
+ },
+ },
+ y: {
+ type: 'linear',
+ display: false,
+ reverse: true,
+ offset: false,
+ min: 0,
+ max: band,
+ grid: { display: false },
+ },
+ },
+ }),
+ [axis, band, chartTargets, grid, onSelectTurn, timelineGaps, timelineMaxMs, totalMs],
+ );
+
+ const tooltipTurn = tooltipTarget?.type === TIMELINE_TYPE.turn ? turns[tooltipTarget.bar.turnIndex] : undefined;
+ const containerStyle = useMemo<CSSProperties>(() => ({ height: band + overheadPx }), [band, overheadPx]);
+ const tooltipContent =
+ tooltipTarget?.type === TIMELINE_TYPE.turn && tooltipTurn != null ? (
+ <SessionTurnTooltip
+ turn={tooltipTurn}
+ turnNumber={tooltipTarget.bar.ordinal + 1}
+ durationMs={tooltipTarget.bar.durationMs}
+ segments={segments.filter(segment => segment.turnIndex === tooltipTarget.bar.turnIndex)}
+ />
+ ) : tooltipTarget?.type === TIMELINE_TYPE.event && hasSessionEventTooltip(tooltipTarget.segment) ? (
+ <SessionEventTooltip
+ segment={tooltipTarget.segment}
+ subAgentLabel={
+ tooltipTarget.segment.type === 'sub_agent'
+ ? undefined
+ : subAgentLanes.find(lane => lane.threadId === tooltipTarget.segment.threadId)?.track.description
+ }
+ />
+ ) : tooltipTarget?.type === TIMELINE_TYPE.toolCallGroup ? (
+ <SessionToolCallGroupTooltip group={tooltipTarget.group} />
+ ) : null;
+
+ return (
+ <div ref={wrapperRef} className="w-full" data-slot="agent-session-event-timeline-chart">
+ <LightTooltip
+ title={tooltipContent}
+ side="bottom"
+ triggerClassName="block w-full"
+ followCursor
+ className="max-w-[min(25rem,calc(100vw-1rem))] whitespace-normal"
+ anchor={tooltipAnchor}
+ >
+ <div className="w-full" style={containerStyle}>
+ <Bar data={chartData} options={chartOptions} plugins={[turnLabelPlugin, overheadPlugin]} />
+ </div>
+ </LightTooltip>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentSessionEventTimelineChart: ComponentType<AgentSessionEventTimelineChartProps>;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionListRow.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionListRow.tsx
new file mode 100644
index 000000000..87a135835
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionListRow.tsx
@@ -0,0 +1,53 @@
+'use client';
+
+import { Icon } from '../../icons/Icon.js';
+import { formatSessionListMetrics } from '../../utils/sessionDisplayFormat.js';
+import { cn } from '../lib/cn.js';
+import { formatRelativeShort } from '../lib/threadListMeta.js';
+import type { AgentSessionListRowProps } from './types.js';
+
+export function AgentSessionListRow({
+ title,
+ agentName,
+ lastActivityAt,
+ metrics,
+ active,
+ onSelect,
+}: AgentSessionListRowProps) {
+ const relative = formatRelativeShort(new Date(lastActivityAt));
+
+ return (
+ <button
+ type="button"
+ onClick={onSelect}
+ data-active={active || undefined}
+ className={cn(
+ 'flex w-full flex-col gap-2 border-b border-border px-3 py-3 text-left transition-colors',
+ active ? 'bg-dropdown-selected-item-bg' : 'hover:bg-ghost-button-hover',
+ )}
+ >
+ <span className="line-clamp-2 text-sm font-medium text-text-primary">{title}</span>
+ <span className="flex items-end justify-between gap-2 text-xs text-text-secondary">
+ <span className="flex min-w-0 items-center gap-1">
+ {agentName != null ? (
+ <>
+ <Icon name="robot" className="size-3 shrink-0" />
+ <span className="truncate">{agentName}</span>
+ </>
+ ) : (
+ <span>Draft</span>
+ )}
+ <span aria-hidden="true">·</span>
+ <span>{relative}</span>
+ </span>
+ <span className="shrink-0 tabular-nums">{formatSessionListMetrics(metrics)}</span>
+ </span>
+ </button>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentSessionListRow: typeof AgentSessionListRow;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionMetricCharts.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionMetricCharts.tsx
new file mode 100644
index 000000000..3704b8e54
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionMetricCharts.tsx
@@ -0,0 +1,122 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+import type { SessionMetricBarDatum } from '../../utils/buildSessionMetrics.js';
+import { LightTooltip } from '../primitives/Tooltip.js';
+
+const MIN_VERTICAL_BAR_HEIGHT_PERCENT = 6;
+
+export function SessionMetricTooltipContent({
+ title,
+ children,
+ fitWidth = false,
+}: {
+ title: string;
+ children: ReactNode;
+ fitWidth?: boolean;
+}) {
+ return (
+ <div
+ className={
+ fitWidth ? 'min-w-40 w-fit px-2 py-2 text-xs text-text-primary' : 'w-72 px-2 py-2 text-xs text-text-primary'
+ }
+ >
+ <div className="mb-3 text-xs font-medium capitalize tracking-wider text-text-secondary">{title}</div>
+ {children}
+ </div>
+ );
+}
+
+export function StackedProportionBar({
+ data,
+ formatValue,
+}: {
+ data: SessionMetricBarDatum[];
+ formatValue: (value: number) => string;
+}) {
+ const visibleData = data.filter(item => item.value > 0);
+ const total = visibleData.reduce((sum, item) => sum + item.value, 0);
+ if (visibleData.length === 0) return null;
+
+ return (
+ <div>
+ <div className="mb-3 flex h-3 w-full overflow-hidden rounded-full bg-secondary-bg">
+ {visibleData.map(item => (
+ <span
+ key={item.label}
+ className="h-full"
+ style={{ width: `${(item.value / total) * 100}%`, backgroundColor: item.color }}
+ />
+ ))}
+ </div>
+ <div className="space-y-2">
+ {visibleData.map(item => (
+ <div key={item.label} className="flex items-center gap-2">
+ <span className="size-2 shrink-0 rounded-sm" style={{ backgroundColor: item.color }} />
+ <span className="min-w-0 flex-1 truncate text-text-secondary">{item.label}</span>
+ <span className="font-semibold text-text-primary">{formatValue(item.value)}</span>
+ </div>
+ ))}
+ </div>
+ </div>
+ );
+}
+
+export function HorizontalBarRows({
+ data,
+ formatValue,
+}: {
+ data: SessionMetricBarDatum[];
+ formatValue: (value: number) => string;
+}) {
+ const maxValue = Math.max(0, ...data.map(item => item.value)) || 1;
+ return (
+ <div className="grid grid-cols-[max-content_minmax(0,1fr)_max-content] items-center gap-x-2 gap-y-2">
+ {data.map(item => (
+ <div key={item.label} className="contents">
+ <span className="max-w-28 truncate text-text-secondary">{item.label}</span>
+ <div className="h-1.5 min-w-0 overflow-hidden rounded-full bg-secondary-bg">
+ <div
+ className="h-full rounded-full"
+ style={{ width: `${(item.value / maxValue) * 100}%`, backgroundColor: item.color }}
+ />
+ </div>
+ <span className="text-right font-semibold text-text-primary">{formatValue(item.value)}</span>
+ </div>
+ ))}
+ </div>
+ );
+}
+
+export function VerticalBarColumns({
+ data,
+ formatValue,
+}: {
+ data: SessionMetricBarDatum[];
+ formatValue: (value: number) => string;
+}) {
+ const maxValue = Math.max(0, ...data.map(item => item.value)) || 1;
+ return (
+ <div className="h-24 overflow-x-auto">
+ <div className="mx-auto flex h-full w-fit items-end">
+ {data.map(item => (
+ <LightTooltip key={item.label} title={formatValue(item.value)} side="top">
+ <div className="flex h-full w-10 shrink-0 flex-col items-center justify-end gap-1">
+ <div className="flex h-[4.5rem] items-end">
+ <div
+ className="w-6 rounded-t-sm"
+ style={{
+ height: `${Math.max(MIN_VERTICAL_BAR_HEIGHT_PERCENT, (item.value / maxValue) * 100)}%`,
+ backgroundColor: item.color,
+ }}
+ />
+ </div>
+ <span className="text-[0.625rem] leading-4 text-text-secondary">{item.label}</span>
+ </div>
+ </LightTooltip>
+ ))}
+ </div>
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionMetricsStrip.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionMetricsStrip.tsx
new file mode 100644
index 000000000..173a4546c
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionMetricsStrip.tsx
@@ -0,0 +1,122 @@
+'use client';
+
+import type { ComponentType, ReactNode } from 'react';
+
+import { Icon } from '../../icons/Icon.js';
+import { formatCostUsd, formatTokenCount } from '../../utils/sessionDisplayFormat.js';
+import { formatTimelineDuration } from '../../utils/sessionEventTimeline.js';
+import { LightTooltip } from '../primitives/Tooltip.js';
+import {
+ HorizontalBarRows,
+ SessionMetricTooltipContent,
+ StackedProportionBar,
+ VerticalBarColumns,
+} from './AgentSessionMetricCharts.js';
+import type { AgentSessionMetricsStripProps } from './types.js';
+
+function SessionMetricTile({
+ id,
+ label,
+ value,
+ tooltip,
+}: {
+ id: string;
+ label: string;
+ value: string | number;
+ tooltip?: ReactNode;
+}) {
+ const content = (
+ <div
+ className="h-full w-full border-b border-r border-border bg-primary-bg px-3 py-2"
+ data-slot={`session-metric-${id}`}
+ >
+ <div className="mb-0.5 flex items-center gap-1 text-[0.625rem] font-medium uppercase tracking-wider text-text-secondary">
+ {label}
+ {tooltip != null ? <Icon name="info" className="size-2.5 text-text-secondary" /> : null}
+ </div>
+ <div className="pt-1 text-base font-medium leading-none text-text-primary">{value}</div>
+ </div>
+ );
+ if (tooltip == null) return content;
+ return (
+ <LightTooltip title={tooltip} side="bottom" triggerClassName="block w-full">
+ {content}
+ </LightTooltip>
+ );
+}
+
+export function AgentSessionMetricsStrip({ metrics }: AgentSessionMetricsStripProps) {
+ return (
+ <div className="@container overflow-hidden border-b border-border" data-slot="agent-session-metrics-strip">
+ <div className="-mb-px -mr-px grid grid-cols-3 @min-[24rem]:grid-cols-4 @min-[48rem]:grid-cols-8">
+ <SessionMetricTile id="turns" label="Turns" value={metrics.totalTurns} />
+ <SessionMetricTile
+ id="wall-time"
+ label="Duration"
+ value={formatTimelineDuration(metrics.wallTimeMs)}
+ tooltip={
+ <SessionMetricTooltipContent title="Where the time went">
+ <StackedProportionBar data={metrics.timeBreakdown} formatValue={formatTimelineDuration} />
+ </SessionMetricTooltipContent>
+ }
+ />
+ <SessionMetricTile
+ id="cost"
+ label="Cost"
+ value={formatCostUsd(metrics.totalCostUsd)}
+ tooltip={
+ metrics.costPerTurn.length > 1 && metrics.totalCostUsd > 0 ? (
+ <SessionMetricTooltipContent title="Cost per turn" fitWidth>
+ <VerticalBarColumns data={metrics.costPerTurn} formatValue={formatCostUsd} />
+ </SessionMetricTooltipContent>
+ ) : null
+ }
+ />
+ <SessionMetricTile
+ id="tokens"
+ label="Tokens"
+ value={formatTokenCount(metrics.totalTokens)}
+ tooltip={
+ metrics.totalTokens > 0 ? (
+ <SessionMetricTooltipContent title="Tokens">
+ <StackedProportionBar data={metrics.tokenBreakdown} formatValue={formatTokenCount} />
+ </SessionMetricTooltipContent>
+ ) : null
+ }
+ />
+ <SessionMetricTile
+ id="context"
+ label="Context"
+ value={formatTokenCount(metrics.contextTokens)}
+ tooltip={
+ metrics.contextByTurn.length > 1 && metrics.contextTokens > 0 ? (
+ <SessionMetricTooltipContent title="Context length at end of turn">
+ <HorizontalBarRows data={metrics.contextByTurn} formatValue={formatTokenCount} />
+ </SessionMetricTooltipContent>
+ ) : null
+ }
+ />
+ <SessionMetricTile
+ id="tool-calls"
+ label="Tool calls"
+ value={metrics.toolCalls}
+ tooltip={
+ metrics.toolCalls > 1 ? (
+ <SessionMetricTooltipContent title="Tool call frequency">
+ <HorizontalBarRows data={metrics.toolCallFrequency} formatValue={String} />
+ </SessionMetricTooltipContent>
+ ) : null
+ }
+ />
+ <SessionMetricTile id="sub-agents" label="Sub-agents" value={metrics.subAgents} />
+ <SessionMetricTile id="errors" label="Errors" value={metrics.errors} />
+ </div>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentSessionMetricsStrip: ComponentType<AgentSessionMetricsStripProps>;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionTimelineTooltip.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionTimelineTooltip.tsx
new file mode 100644
index 000000000..c66a87a19
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionTimelineTooltip.tsx
@@ -0,0 +1,120 @@
+'use client';
+
+import { formatCostUsd, formatDurationMs, formatTokenCount } from '../../utils/sessionDisplayFormat.js';
+import {
+ formatTimelineDuration,
+ getSessionEventColor,
+ getSessionEventTooltipHeading,
+ SESSION_EVENT_TOOLTIP_HIDE_DURATION,
+ type SessionEventTimelineSegment,
+} from '../../utils/sessionEventTimeline.js';
+import type { TimelineToolCallGroup } from '../../utils/sessionEventTimelineChart.js';
+import type { SessionTurnView } from '../../utils/sessionTurnViews.js';
+
+export function hasSessionEventTooltip(segment: SessionEventTimelineSegment): boolean {
+ return segment.type !== 'system' || segment.description.trim().length > 0;
+}
+
+export function SessionEventTooltip({
+ segment,
+ subAgentLabel,
+}: {
+ segment: SessionEventTimelineSegment;
+ subAgentLabel?: string;
+}) {
+ const showDuration = !segment.isMarker && !SESSION_EVENT_TOOLTIP_HIDE_DURATION.has(segment.type);
+ const content = segment.description.trim();
+ if (segment.type === 'system') {
+ if (content.length === 0) return null;
+ return (
+ <p className="max-w-[25rem] whitespace-normal break-words text-xs font-medium text-text-primary">{content}</p>
+ );
+ }
+
+ return (
+ <div className="max-h-72 max-w-[25rem] overflow-auto whitespace-normal break-words text-xs">
+ {subAgentLabel != null ? (
+ <div className="border-b border-border py-1.5 text-text-secondary">{`Sub-Agent: ${subAgentLabel}`}</div>
+ ) : null}
+ <div className="flex items-center justify-between gap-3 pt-1">
+ <span className={segment.type === 'error' ? 'font-medium text-failure-bg' : 'font-medium text-text-secondary'}>
+ {getSessionEventTooltipHeading(segment.type)}
+ </span>
+ {showDuration ? (
+ <span className="tabular-nums text-text-secondary">
+ {formatTimelineDuration(segment.endMs - segment.startMs)}
+ </span>
+ ) : null}
+ </div>
+ {content.length > 0 ? <p className="mt-1.5 line-clamp-6 font-medium text-text-primary">{content}</p> : null}
+ </div>
+ );
+}
+
+export function SessionTurnTooltip({
+ turn,
+ turnNumber,
+ durationMs,
+ segments,
+}: {
+ turn: SessionTurnView;
+ turnNumber: number;
+ durationMs: number;
+ segments: SessionEventTimelineSegment[];
+}) {
+ return (
+ <div className="max-h-72 w-72 max-w-full overflow-auto text-xs text-text-primary">
+ <div className="flex items-center justify-between gap-3">
+ <span className="font-semibold">{`Turn ${turnNumber}`}</span>
+ <span className="tabular-nums text-text-secondary">{formatDurationMs(durationMs)}</span>
+ </div>
+ <div className="mt-1 flex flex-col text-text-secondary">
+ {turn.totalCostInUsd != null ? <span>{`Cost: ${formatCostUsd(turn.totalCostInUsd)}`}</span> : null}
+ {turn.totalTokens != null ? <span>{`Tokens: ${formatTokenCount(turn.totalTokens)}`}</span> : null}
+ </div>
+ <div className="mt-2 border-t border-border pt-2">
+ {segments.map(segment => {
+ const label =
+ segment.type === 'tool_call' || segment.type === 'sub_agent' ? segment.description : segment.title;
+ return (
+ <div key={segment.id} className="flex min-w-0 items-center gap-1.5">
+ <span
+ className="size-1.5 shrink-0 rounded-full"
+ style={{ backgroundColor: getSessionEventColor(segment.type) }}
+ />
+ <span className="min-w-0 flex-1 truncate">{label}</span>
+ {segment.isMarker ? null : (
+ <span className="ml-auto shrink-0 tabular-nums text-text-secondary">
+ {formatTimelineDuration(segment.endMs - segment.startMs)}
+ </span>
+ )}
+ </div>
+ );
+ })}
+ </div>
+ </div>
+ );
+}
+
+export function SessionToolCallGroupTooltip({ group }: { group: TimelineToolCallGroup }) {
+ return (
+ <div className="max-h-72 w-80 max-w-full overflow-auto text-xs">
+ <div className="flex items-center justify-between gap-3">
+ <span className="font-medium text-text-secondary">Tool calls</span>
+ <span className="tabular-nums text-text-secondary">{formatTimelineDuration(group.endMs - group.startMs)}</span>
+ </div>
+ <div className="mt-1.5 border-t border-border pt-1.5">
+ {group.segments.map(segment => (
+ <div key={segment.id} className="flex items-center justify-between gap-2 py-0.5">
+ <span className="min-w-0 truncate font-medium text-text-primary">
+ {segment.description || segment.title}
+ </span>
+ <span className="shrink-0 tabular-nums text-text-secondary">
+ {formatTimelineDuration(segment.endMs - segment.startMs)}
+ </span>
+ </div>
+ ))}
+ </div>
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionTurnHeader.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionTurnHeader.tsx
new file mode 100644
index 000000000..5b845f259
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionTurnHeader.tsx
@@ -0,0 +1,44 @@
+'use client';
+
+import { Icon } from '../../icons/Icon.js';
+import { formatCostUsd, formatDurationMs, formatTokenCount } from '../../utils/sessionDisplayFormat.js';
+import type { AgentSessionTurnHeaderProps } from './types.js';
+
+export function AgentSessionTurnHeader({
+ turnNumber,
+ totalTokens,
+ durationMs,
+ totalCostInUsd,
+}: AgentSessionTurnHeaderProps) {
+ const hasMetrics = totalTokens != null || durationMs != null || totalCostInUsd != null;
+
+ return (
+ <div className="flex items-center gap-3 py-1 text-xs text-text-secondary">
+ <span className="shrink-0 font-semibold text-text-primary">{`Turn ${turnNumber}`}</span>
+ <div className="h-px min-w-4 flex-1 bg-border" aria-hidden="true" />
+ {hasMetrics ? (
+ <div className="flex shrink-0 items-center gap-3 tabular-nums">
+ {totalTokens != null ? (
+ <span className="inline-flex items-center gap-1">
+ <Icon name="link" className="size-3.5 shrink-0" />
+ {`Tokens ${formatTokenCount(totalTokens)}`}
+ </span>
+ ) : null}
+ {durationMs != null ? (
+ <span className="inline-flex items-center gap-1">
+ <Icon name="clock" className="size-3.5 shrink-0" />
+ {`Duration ${formatDurationMs(durationMs)}`}
+ </span>
+ ) : null}
+ {totalCostInUsd != null ? <span>{`Cost ${formatCostUsd(totalCostInUsd)}`}</span> : null}
+ </div>
+ ) : null}
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentSessionTurnHeader: typeof AgentSessionTurnHeader;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessions.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessions.tsx
new file mode 100644
index 000000000..50e38b42e
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessions.tsx
@@ -0,0 +1,244 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState, type ComponentType } from 'react';
+
+import { useSessionShareSearch } from '../../hooks/useSessionShareSearch.js';
+import { useAgentSessionsServer, useServer } from '../../server/ServerContext.js';
+import type { Session, SessionEventItem, SessionListEntry } from '../../server/types.js';
+import { useSlot } from '../../theme/SlotsProvider.js';
+import { drainListPages } from '../../utils/drainListPages.js';
+import { sessionTimeRangeFromCreatedAt } from '../../utils/sessionShareUrl.js';
+import { Skeleton } from '../primitives/Skeleton.js';
+import type { AgentSessionsProps } from './types.js';
+
+function sessionTitle(entry: Pick<SessionListEntry, 'title'>): string {
+ const title = entry.title?.trim();
+ return title != null && title.length > 0 ? title : 'Untitled session';
+}
+
+export function AgentSessions({ agentId, startTimestamp, endTimestamp, shareView }: AgentSessionsProps) {
+ const sessionsServer = useAgentSessionsServer();
+ const chatServer = useServer();
+ const { sessionId: selectedSessionId, updateShareSearch } = useSessionShareSearch();
+
+ const AgentSessionListRow = useSlot('AgentSessionListRow');
+ const AgentSessionDetailHeader = useSlot('AgentSessionDetailHeader');
+ const AgentSessionTimelineContainer = useSlot('AgentSessionTimelineContainer');
+
+ const [entries, setEntries] = useState<SessionListEntry[]>([]);
+ const [nextPageToken, setNextPageToken] = useState<string | undefined>();
+ const [listLoading, setListLoading] = useState(true);
+ const [listLoadingMore, setListLoadingMore] = useState(false);
+ const [listFailed, setListFailed] = useState(false);
+ const listRequestIdRef = useRef(0);
+ const [detailEvents, setDetailEvents] = useState<SessionEventItem[]>();
+ const [detailSession, setDetailSession] = useState<Session>();
+ const [detailLoading, setDetailLoading] = useState(false);
+ const [detailFailed, setDetailFailed] = useState(false);
+
+ const listRequest = useMemo(
+ () => ({
+ order: 'desc' as const,
+ limit: 20,
+ ...(agentId == null || agentId.length === 0 ? {} : { agentId }),
+ ...(startTimestamp == null ? {} : { startTimestamp }),
+ ...(endTimestamp == null ? {} : { endTimestamp }),
+ }),
+ [agentId, endTimestamp, startTimestamp],
+ );
+
+ useEffect(() => {
+ const requestId = ++listRequestIdRef.current;
+ let cancelled = false;
+ setListLoading(true);
+ setListLoadingMore(false);
+ setListFailed(false);
+ void sessionsServer
+ .listSessions(listRequest)
+ .then(page => {
+ if (cancelled || listRequestIdRef.current !== requestId) return;
+ setEntries(page.data);
+ setNextPageToken(page.nextPageToken);
+ })
+ .catch(() => {
+ if (cancelled || listRequestIdRef.current !== requestId) return;
+ setEntries([]);
+ setNextPageToken(undefined);
+ setListFailed(true);
+ })
+ .finally(() => {
+ if (!cancelled && listRequestIdRef.current === requestId) setListLoading(false);
+ });
+
+ return () => {
+ cancelled = true;
+ };
+ }, [listRequest, sessionsServer]);
+
+ const loadMore = useCallback(async () => {
+ if (nextPageToken == null || listLoadingMore) return;
+ const requestId = listRequestIdRef.current;
+ setListLoadingMore(true);
+ try {
+ const page = await sessionsServer.listSessions({ ...listRequest, pageToken: nextPageToken });
+ if (listRequestIdRef.current !== requestId) return;
+ setEntries(current => [...current, ...page.data]);
+ setNextPageToken(page.nextPageToken);
+ } catch {
+ // Keep the current page and token visible so the user can retry.
+ } finally {
+ if (listRequestIdRef.current === requestId) setListLoadingMore(false);
+ }
+ }, [listLoadingMore, listRequest, nextPageToken, sessionsServer]);
+
+ useEffect(() => {
+ if (selectedSessionId == null || selectedSessionId.length === 0) {
+ setDetailEvents(undefined);
+ setDetailSession(undefined);
+ setDetailFailed(false);
+ setDetailLoading(false);
+ return;
+ }
+
+ let cancelled = false;
+ setDetailLoading(true);
+ setDetailFailed(false);
+ setDetailEvents(undefined);
+ setDetailSession(undefined);
+
+ void Promise.all([
+ drainListPages({
+ fetchPage: pageToken =>
+ sessionsServer.listSessionEvents({
+ sessionId: selectedSessionId,
+ limit: 100,
+ ...(pageToken == null ? {} : { pageToken }),
+ }),
+ }),
+ chatServer.getSession({ sessionId: selectedSessionId }).catch(() => undefined),
+ ])
+ .then(([itemsNewestFirst, session]) => {
+ if (cancelled) return;
+ setDetailEvents([...itemsNewestFirst].reverse());
+ setDetailSession(session);
+ })
+ .catch(() => {
+ if (!cancelled) setDetailFailed(true);
+ })
+ .finally(() => {
+ if (!cancelled) setDetailLoading(false);
+ });
+
+ return () => {
+ cancelled = true;
+ };
+ }, [chatServer, selectedSessionId, sessionsServer]);
+
+ const selectSession = (entry: SessionListEntry) => {
+ const pinned = shareView === 'sessions' ? sessionTimeRangeFromCreatedAt(entry.createdAt) : null;
+ updateShareSearch({
+ sessionId: entry.id,
+ ...(shareView === 'sessions'
+ ? { view: 'sessions', ...(pinned == null ? {} : { timeRange: pinned }) }
+ : { agentId: agentId ?? null, tab: 'sessions', view: null, timeRange: null }),
+ });
+ };
+
+ const clearSelectedSession = () => {
+ if (selectedSessionId == null) return;
+ updateShareSearch({ sessionId: null });
+ };
+
+ const selectedEntry = entries.find(entry => entry.id === selectedSessionId);
+ const selectedTitle =
+ detailSession != null
+ ? sessionTitle(detailSession)
+ : selectedEntry != null
+ ? sessionTitle(selectedEntry)
+ : (selectedSessionId ?? 'Untitled session');
+
+ return (
+ <div className="flex h-full min-h-0 w-full">
+ <aside className="flex w-full max-w-xs shrink-0 flex-col border-r border-border bg-primary-bg md:max-w-sm">
+ <div className="min-h-0 flex-1 overflow-y-auto">
+ {listLoading ? (
+ <div className="space-y-2 p-3" role="status" aria-label="Loading sessions">
+ {['a', 'b', 'c'].map(key => (
+ <Skeleton key={key} className="h-16 rounded-md" />
+ ))}
+ </div>
+ ) : listFailed ? (
+ <p className="px-3 py-6 text-center text-xs text-text-secondary">Sessions could not be loaded.</p>
+ ) : entries.length === 0 ? (
+ <p className="px-3 py-6 text-center text-xs text-text-secondary">No sessions are there yet</p>
+ ) : (
+ entries.map(entry => (
+ <AgentSessionListRow
+ key={entry.id}
+ title={sessionTitle(entry)}
+ agentName={entry.agentName ?? undefined}
+ lastActivityAt={entry.lastActivityAt}
+ metrics={entry.metrics}
+ active={entry.id === selectedSessionId}
+ onSelect={() => selectSession(entry)}
+ />
+ ))
+ )}
+ </div>
+
+ {nextPageToken != null && !listLoading ? (
+ <div className="shrink-0 border-t border-border p-3">
+ <button
+ type="button"
+ disabled={listLoadingMore}
+ onClick={() => void loadMore()}
+ className="h-8 w-full rounded-md border border-border text-xs font-medium text-text-primary hover:bg-ghost-button-hover disabled:opacity-60"
+ >
+ {listLoadingMore ? 'Loading…' : 'Load more'}
+ </button>
+ </div>
+ ) : null}
+ </aside>
+
+ <section className="flex min-w-0 flex-1 flex-col bg-primary-bg">
+ {selectedSessionId == null ? (
+ <div className="flex flex-1 items-center justify-center px-6 text-sm text-text-secondary">
+ Select a session to view details
+ </div>
+ ) : detailFailed ? (
+ <div className="flex flex-1 items-center justify-center px-6 text-sm text-text-secondary">
+ Session details could not be loaded.
+ </div>
+ ) : (
+ <>
+ <AgentSessionDetailHeader
+ title={selectedTitle}
+ sessionId={selectedSessionId}
+ agentId={agentId}
+ createdAt={detailSession?.createdAt ?? selectedEntry?.createdAt}
+ view={shareView}
+ onClose={clearSelectedSession}
+ />
+ {detailLoading || detailEvents === undefined ? (
+ <div className="flex flex-1 flex-col p-4" role="status" aria-label="Loading session details">
+ <Skeleton className="min-h-64 flex-1 rounded-lg" />
+ </div>
+ ) : (
+ <AgentSessionTimelineContainer
+ sessionId={selectedSessionId}
+ events={detailEvents}
+ listMetrics={selectedEntry?.metrics}
+ />
+ )}
+ </>
+ )}
+ </section>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentSessions: ComponentType<AgentSessionsProps>;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/AgentSessionsFilters.tsx b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionsFilters.tsx
new file mode 100644
index 000000000..cfddab0e8
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/AgentSessionsFilters.tsx
@@ -0,0 +1,230 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+import { useOptionalServer } from '../../server/ServerContext.js';
+import { useOptionalShellMode } from '../../server/ShellModeContext.js';
+import type { AgentBuilderServer, AgentLibraryEntry } from '../../server/types.js';
+import { SESSION_CUSTOM_RANGE_MAX_DAYS, type SessionTimeRange } from '../../utils/sessionShareUrl.js';
+import {
+ formatSessionTimePresetLabel,
+ formatTimezoneOffsetLabel,
+ fromDateTimeLocalValue,
+ SESSION_TIME_PRESETS,
+ toDateTimeLocalValue,
+} from '../../utils/sessionTimePresets.js';
+import { cn } from '../lib/cn.js';
+import { SEARCH_AGENTS_PAGE_SIZE } from '../lib/useSearchAgentsList.js';
+
+async function searchAllAgents(
+ server: Pick<AgentBuilderServer, 'searchAgents'>,
+ offset = 0,
+): Promise<AgentLibraryEntry[]> {
+ const rows = await server.searchAgents({ limit: SEARCH_AGENTS_PAGE_SIZE, offset });
+ if (rows.length < SEARCH_AGENTS_PAGE_SIZE) return rows;
+ return [...rows, ...(await searchAllAgents(server, offset + rows.length))];
+}
+
+export type AgentSessionsFiltersProps = {
+ agentId: string | null;
+ timeRange: SessionTimeRange;
+ onAgentChange: (agentId: string | null) => void;
+ onTimeRangeChange: (range: SessionTimeRange) => void;
+};
+
+export function AgentSessionsFilters({
+ agentId,
+ timeRange,
+ onAgentChange,
+ onTimeRangeChange,
+}: AgentSessionsFiltersProps) {
+ const server = useOptionalServer();
+ const shell = useOptionalShellMode();
+ const [agents, setAgents] = useState<AgentLibraryEntry[]>([]);
+ const [menuOpen, setMenuOpen] = useState(false);
+ const [customPickerOpen, setCustomPickerOpen] = useState(false);
+ const [fromValue, setFromValue] = useState(() => toDateTimeLocalValue(timeRange.startTs));
+ const [toValue, setToValue] = useState(() => toDateTimeLocalValue(timeRange.endTs));
+ const popoverRef = useRef<HTMLDivElement>(null);
+
+ useEffect(() => {
+ if (server == null) return undefined;
+ let cancelled = false;
+ void searchAllAgents(server).then(
+ rows => {
+ if (!cancelled) setAgents(rows);
+ },
+ () => undefined,
+ );
+ return () => {
+ cancelled = true;
+ };
+ }, [server, shell?.agentsListEpoch]);
+
+ useEffect(() => {
+ setFromValue(toDateTimeLocalValue(timeRange.startTs));
+ setToValue(toDateTimeLocalValue(timeRange.endTs));
+ }, [timeRange.endTs, timeRange.startTs]);
+
+ useEffect(() => {
+ if (!menuOpen) return undefined;
+ const onPointerDown = (event: PointerEvent) => {
+ if (popoverRef.current?.contains(event.target as Node) !== true) {
+ setMenuOpen(false);
+ setCustomPickerOpen(false);
+ }
+ };
+ const onKeyDown = (event: KeyboardEvent) => {
+ if (event.key !== 'Escape') return;
+ setMenuOpen(false);
+ setCustomPickerOpen(false);
+ };
+ document.addEventListener('pointerdown', onPointerDown);
+ document.addEventListener('keydown', onKeyDown);
+ return () => {
+ document.removeEventListener('pointerdown', onPointerDown);
+ document.removeEventListener('keydown', onKeyDown);
+ };
+ }, [menuOpen]);
+
+ const timeLabel =
+ timeRange.timeWindowMs != null
+ ? (formatSessionTimePresetLabel(timeRange.timeWindowMs) ?? 'Custom Time Range')
+ : 'Custom Time Range';
+
+ const applyCustom = () => {
+ const startTs = fromDateTimeLocalValue(fromValue);
+ const endTs = fromDateTimeLocalValue(toValue);
+ if (startTs == null || endTs == null || startTs >= endTs) return;
+ const minStart = Date.now() - SESSION_CUSTOM_RANGE_MAX_DAYS * 24 * 60 * 60 * 1000;
+ const clampedStartTs = Math.max(startTs, minStart);
+ if (clampedStartTs >= endTs) return;
+ onTimeRangeChange({ startTs: clampedStartTs, endTs });
+ setMenuOpen(false);
+ setCustomPickerOpen(false);
+ };
+
+ 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>
+ <div className="relative" ref={popoverRef}>
+ <button
+ type="button"
+ aria-expanded={menuOpen}
+ aria-haspopup="listbox"
+ className="h-8 min-w-36 rounded-md border border-border bg-primary-bg px-2 text-left text-xs text-text-primary"
+ onClick={() => {
+ setMenuOpen(open => {
+ if (open) setCustomPickerOpen(false);
+ return !open;
+ });
+ }}
+ >
+ {timeLabel}
+ </button>
+ {menuOpen ? (
+ <div className="absolute right-0 z-20 mt-1 flex overflow-hidden rounded-md border border-border bg-card-bg shadow-md">
+ {customPickerOpen ? (
+ <div className="flex w-64 min-w-0 flex-col gap-2 border-r border-border p-3">
+ <div className="text-sm font-medium text-text-primary">Select Time Range</div>
+ <p className="text-xs text-text-secondary">{`You can select time for last ${String(SESSION_CUSTOM_RANGE_MAX_DAYS)} days`}</p>
+ <label className="flex flex-col gap-1 text-xs text-text-secondary">
+ From
+ <input
+ type="datetime-local"
+ step="1"
+ className="h-8 rounded-md border border-border bg-primary-bg px-2 text-xs text-text-primary"
+ value={fromValue}
+ onChange={event => setFromValue(event.target.value)}
+ />
+ </label>
+ <label className="flex flex-col gap-1 text-xs text-text-secondary">
+ To
+ <input
+ type="datetime-local"
+ step="1"
+ className="h-8 rounded-md border border-border bg-primary-bg px-2 text-xs text-text-primary"
+ value={toValue}
+ onChange={event => setToValue(event.target.value)}
+ />
+ </label>
+ <p className="text-xs text-text-secondary">
+ Timezone: <span className="font-medium text-text-primary">{formatTimezoneOffsetLabel()}</span>
+ </p>
+ <button
+ type="button"
+ className="mt-auto h-8 rounded-md bg-primary-button-bg px-3 text-xs font-medium text-primary-button-text"
+ onClick={applyCustom}
+ >
+ Apply
+ </button>
+ </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>
+ {SESSION_TIME_PRESETS.map(preset => (
+ <button
+ key={preset.windowMs}
+ type="button"
+ className={cn(
+ 'px-3 py-2 text-left text-xs',
+ timeRange.timeWindowMs === preset.windowMs
+ ? 'bg-dropdown-selected-item-bg text-dropdown-selected-item-text'
+ : 'text-text-primary hover:bg-ghost-button-hover',
+ )}
+ onClick={() => {
+ const endTs = Date.now();
+ onTimeRangeChange({
+ startTs: endTs - preset.windowMs,
+ endTs,
+ timeWindowMs: preset.windowMs,
+ });
+ setMenuOpen(false);
+ setCustomPickerOpen(false);
+ }}
+ >
+ {preset.label}
+ </button>
+ ))}
+ </div>
+ </div>
+ ) : null}
+ </div>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentSessionsFilters: typeof AgentSessionsFilters;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/SessionsPage.tsx b/packages/trueforge-ui/src/atoms/agent-details/SessionsPage.tsx
new file mode 100644
index 000000000..5837eaa9c
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/SessionsPage.tsx
@@ -0,0 +1,98 @@
+'use client';
+
+import { Suspense, useEffect, useMemo, useState } from 'react';
+
+import { useSessionShareSearch } from '../../hooks/useSessionShareSearch.js';
+import { useOptionalAgentSessionsServer } from '../../server/ServerContext.js';
+import { useSlot } from '../../theme/SlotsProvider.js';
+import {
+ defaultSessionTimeRange,
+ readSessionShareSearch,
+ resolveSessionTimeRange,
+ type SessionTimeRange,
+} from '../../utils/sessionShareUrl.js';
+import { Skeleton } from '../primitives/Skeleton.js';
+
+export function SessionsPage() {
+ const sessionsServer = useOptionalAgentSessionsServer();
+ const { updateShareSearch } = useSessionShareSearch();
+ const AgentSessions = useSlot('AgentSessions');
+ const AgentSessionsFilters = useSlot('AgentSessionsFilters');
+
+ const [agentFilter, setAgentFilter] = useState<string | null>(
+ () => readSessionShareSearch(window.location.search).agentId,
+ );
+ const [timeRange, setTimeRange] = useState<SessionTimeRange>(
+ () => readSessionShareSearch(window.location.search).timeRange ?? defaultSessionTimeRange(),
+ );
+
+ useEffect(() => {
+ const share = readSessionShareSearch(window.location.search);
+ updateShareSearch({
+ view: 'sessions',
+ ...(share.timeRange == null ? { timeRange } : {}),
+ });
+ // Seed `view=sessions` and the default window once; later writes come from the filters.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, []);
+
+ useEffect(() => {
+ const syncFilters = () => {
+ const share = readSessionShareSearch(window.location.search);
+ setAgentFilter(share.agentId);
+ setTimeRange(share.timeRange ?? defaultSessionTimeRange());
+ };
+ window.addEventListener('popstate', syncFilters);
+ return () => window.removeEventListener('popstate', syncFilters);
+ }, []);
+
+ // Resolve relative presets only when the filter changes. Unrelated query
+ // updates (such as selecting a session) must not shift/refetch the list.
+ const resolved = useMemo(() => resolveSessionTimeRange(timeRange), [timeRange]);
+
+ return (
+ <div className="flex h-full min-h-0 w-full flex-col bg-primary-bg">
+ <div className="flex shrink-0 items-center justify-between gap-3 border-b border-border px-4 py-3">
+ <h1 className="text-lg font-semibold tracking-tight text-text-primary">Agent Sessions</h1>
+ <AgentSessionsFilters
+ agentId={agentFilter}
+ timeRange={timeRange}
+ onAgentChange={nextAgentId => {
+ setAgentFilter(nextAgentId);
+ updateShareSearch({ agentId: nextAgentId, sessionId: null, view: 'sessions' });
+ }}
+ onTimeRangeChange={nextRange => {
+ setTimeRange(nextRange);
+ updateShareSearch({ timeRange: nextRange, sessionId: null, view: 'sessions' });
+ }}
+ />
+ </div>
+ <div className="min-h-0 flex-1">
+ {sessionsServer == null ? (
+ <p className="px-6 py-12 text-center text-sm text-text-secondary">Session history is not available.</p>
+ ) : (
+ <Suspense
+ fallback={
+ <div className="p-4" role="status" aria-label="Loading sessions">
+ <Skeleton className="min-h-64 rounded-lg" />
+ </div>
+ }
+ >
+ <AgentSessions
+ agentId={agentFilter ?? undefined}
+ startTimestamp={new Date(resolved.startTs).toISOString()}
+ endTimestamp={new Date(resolved.endTs).toISOString()}
+ shareView="sessions"
+ />
+ </Suspense>
+ )}
+ </div>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ SessionsPage: typeof SessionsPage;
+ }
+}
diff --git a/packages/trueforge-ui/src/atoms/agent-details/types.ts b/packages/trueforge-ui/src/atoms/agent-details/types.ts
new file mode 100644
index 000000000..b3e27b162
--- /dev/null
+++ b/packages/trueforge-ui/src/atoms/agent-details/types.ts
@@ -0,0 +1,103 @@
+import type { ReactNode } from 'react';
+import type { AgentDetail, 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 { SessionTurnView } from '../../utils/sessionTurnViews.js';
+
+export type AgentSessionsProps = {
+ /** Library tab locks the list to this agent. Omit on the all-user Sessions page. */
+ agentId?: string;
+ startTimestamp?: string;
+ endTimestamp?: string;
+ /** When `sessions`, selection writes `view=sessions` and pins `s_sts`/`s_ets`. */
+ shareView?: 'sessions' | null;
+};
+
+export type AgentSessionListRowProps = {
+ title: string;
+ agentName?: string;
+ lastActivityAt: string;
+ metrics: {
+ totalTurns: number;
+ totalCostInUsd: number;
+ totalDurationMs: number;
+ };
+ active: boolean;
+ onSelect: () => void;
+};
+
+export type AgentSessionDetailHeaderProps = {
+ title: string;
+ sessionId: string;
+ agentId?: string;
+ createdAt?: string;
+ view?: 'sessions' | null;
+ onClose: () => void;
+};
+
+export type AgentSessionTurnHeaderProps = {
+ turnNumber: number;
+ totalTokens?: number;
+ durationMs?: number;
+ totalCostInUsd?: number;
+};
+
+export type AgentSessionMetricsStripProps = {
+ metrics: SessionMetrics;
+};
+
+export type AgentSessionEventTimelineProps = {
+ turns: SessionTurnView[];
+ segments: SessionEventTimelineSegment[];
+ onSelectTurn?: (index: number) => void;
+};
+
+export type AgentSessionEventTimelineChartProps = {
+ turns: SessionTurnView[];
+ segments: SessionEventTimelineSegment[];
+ hiddenTypes: ReadonlySet<SessionEventType>;
+ onSelectTurn?: (index: number) => void;
+};
+
+export type AgentDetailsTab = LibraryAgentTab;
+
+export type AgentDetailsPageProps = {
+ agentId: string;
+};
+
+export type AgentDetailsHeaderProps = {
+ agentId: string;
+ detail?: AgentDetail;
+ onBack: () => void;
+};
+
+export type AgentDetailsTabsProps = {
+ activeTab: AgentDetailsTab;
+ onTabChange: (tab: AgentDetailsTab) => void;
+};
+
+export type AgentOverviewProps = {
+ detail: AgentDetail;
+};
+
+export type AgentOverviewCardProps = {
+ title: string;
+ icon: string;
+ count?: number;
+ children: ReactNode;
+};
+
+export type AgentCodeSnippetsProps = {
+ snippets: CodeSnippet[];
+};
+
+export type AgentCodeBlockProps = {
+ code: string;
+ language: string;
+};
+
+export type AgentDetailsUnavailableProps = {
+ onBack: () => void;
+ reason?: string;
+};
diff --git a/packages/trueforge-ui/src/atoms/primitives/Tooltip.tsx b/packages/trueforge-ui/src/atoms/primitives/Tooltip.tsx
index 3101f4b8c..a8c8cc864 100644
--- a/packages/trueforge-ui/src/atoms/primitives/Tooltip.tsx
+++ b/packages/trueforge-ui/src/atoms/primitives/Tooltip.tsx
@@ -5,6 +5,48 @@ import { createPortal } from 'react-dom';
import { cn } from '../lib/cn.js';
+const TOOLTIP_VIEWPORT_PAD = 8;
+
+/** `left`/`top` are the desired center and top-edge (bottom) or bottom-edge (top). */
+export function clampCenteredTooltip({
+ left,
+ top,
+ width,
+ height,
+ side,
+ viewportWidth,
+ viewportHeight,
+ pad = TOOLTIP_VIEWPORT_PAD,
+}: {
+ left: number;
+ top: number;
+ width: number;
+ height: number;
+ side: 'top' | 'bottom';
+ viewportWidth: number;
+ viewportHeight: number;
+ pad?: number;
+}): { top: number; left: number } {
+ let nextLeft = left;
+ if (width > 0) {
+ const half = width / 2;
+ const minCenter = pad + half;
+ const maxCenter = viewportWidth - pad - half;
+ nextLeft = maxCenter < minCenter ? viewportWidth / 2 : Math.min(maxCenter, Math.max(minCenter, left));
+ }
+
+ let nextTop = top;
+ if (height > 0) {
+ if (side === 'bottom') {
+ const overflow = top + height - (viewportHeight - pad);
+ if (overflow > 0) nextTop = Math.max(pad, top - overflow);
+ } else if (top - height < pad) {
+ nextTop = pad + height;
+ }
+ }
+ return { top: nextTop, left: nextLeft };
+}
+
// Keep portaled chrome under ThemeProvider so preset/custom CSS vars still apply.
function themePortalRoot(from: HTMLElement | null): HTMLElement {
// A native <dialog> opened with showModal() renders in the top layer, above any
@@ -15,17 +57,73 @@ function themePortalRoot(from: HTMLElement | null): HTMLElement {
return from?.closest('.aui-theme-root') ?? document.body;
}
+function hasTooltipContent(content: React.ReactNode): boolean {
+ if (content == null || content === false) return false;
+ if (typeof content === 'string') return content.trim().length > 0;
+ return true;
+}
+
+export type TooltipAnchor = {
+ left: number;
+ top: number;
+};
+
export type TooltipProps = {
content: React.ReactNode;
children: React.ReactElement;
className?: string;
+ triggerClassName?: string;
side?: 'top' | 'bottom';
+ dismissOnClick?: boolean;
+ followCursor?: boolean;
+ /** When set, tooltip is pinned to these viewport coords instead of the trigger. */
+ anchor?: TooltipAnchor | null;
};
-export function Tooltip({ content, children, className, side = 'top' }: TooltipProps) {
+export function Tooltip({
+ content,
+ children,
+ className,
+ triggerClassName,
+ side = 'top',
+ dismissOnClick = true,
+ followCursor = false,
+ anchor = null,
+}: TooltipProps) {
const [visible, setVisible] = useState(false);
const [pos, setPos] = useState<{ top: number; left: number } | null>(null);
const triggerWrapRef = useRef<HTMLSpanElement>(null);
+ const tooltipRef = useRef<HTMLSpanElement>(null);
+ const cursorXRef = useRef<number | null>(null);
+ const placeRef = useRef<() => void>(() => {});
+
+ placeRef.current = () => {
+ const trigger = triggerWrapRef.current;
+ let next: { top: number; left: number } | null = null;
+ if (anchor != null) {
+ next = { top: side === 'bottom' ? anchor.top + 6 : anchor.top - 6, left: anchor.left };
+ } else if (trigger) {
+ const rect = trigger.getBoundingClientRect();
+ next = {
+ top: side === 'bottom' ? rect.bottom + 6 : rect.top - 6,
+ left: followCursor && cursorXRef.current != null ? cursorXRef.current : rect.left + rect.width / 2,
+ };
+ }
+ if (next == null) return;
+ const tooltipEl = tooltipRef.current;
+ setPos(
+ tooltipEl
+ ? clampCenteredTooltip({
+ ...next,
+ width: tooltipEl.offsetWidth,
+ height: tooltipEl.offsetHeight,
+ side,
+ viewportWidth: window.innerWidth,
+ viewportHeight: window.innerHeight,
+ })
+ : next,
+ );
+ };
useLayoutEffect(() => {
if (!visible) {
@@ -33,16 +131,7 @@ export function Tooltip({ content, children, className, side = 'top' }: TooltipP
return;
}
- const update = () => {
- const el = triggerWrapRef.current;
- if (!el) return;
- const rect = el.getBoundingClientRect();
- setPos({
- top: side === 'bottom' ? rect.bottom + 6 : rect.top - 6,
- left: rect.left + rect.width / 2,
- });
- };
-
+ const update = () => placeRef.current();
update();
window.addEventListener('scroll', update, true);
window.addEventListener('resize', update);
@@ -50,7 +139,7 @@ export function Tooltip({ content, children, className, side = 'top' }: TooltipP
window.removeEventListener('scroll', update, true);
window.removeEventListener('resize', update);
};
- }, [visible, side]);
+ }, [anchor, followCursor, visible, side, content]);
if (!isValidElement(children)) return children;
@@ -58,10 +147,19 @@ export function Tooltip({ content, children, className, side = 'top' }: TooltipP
const p = children.props as AnyProps;
const child = cloneElement(children as React.ReactElement<AnyProps>, {
onMouseEnter(e: React.MouseEvent<Element>) {
+ if (followCursor) cursorXRef.current = e.clientX;
setVisible(true);
(p.onMouseEnter as ((e: React.MouseEvent<Element>) => void) | undefined)?.(e);
},
+ onMouseMove(e: React.MouseEvent<Element>) {
+ if (followCursor && anchor == null) {
+ cursorXRef.current = e.clientX;
+ placeRef.current();
+ }
+ (p.onMouseMove as ((e: React.MouseEvent<Element>) => void) | undefined)?.(e);
+ },
onMouseLeave(e: React.MouseEvent<Element>) {
+ cursorXRef.current = null;
setVisible(false);
(p.onMouseLeave as ((e: React.MouseEvent<Element>) => void) | undefined)?.(e);
},
@@ -74,23 +172,25 @@ export function Tooltip({ content, children, className, side = 'top' }: TooltipP
(p.onBlur as ((e: React.FocusEvent<Element>) => void) | undefined)?.(e);
},
onClick(e: React.MouseEvent<Element>) {
- setVisible(false);
+ if (dismissOnClick) setVisible(false);
(p.onClick as ((e: React.MouseEvent<Element>) => void) | undefined)?.(e);
},
});
const tooltip =
- visible && content != null && pos != null
+ visible && hasTooltipContent(content)
? createPortal(
<span
+ ref={tooltipRef}
role="tooltip"
style={{
- top: pos.top,
- left: pos.left,
+ top: pos?.top ?? 0,
+ left: pos?.left ?? 0,
transform: side === 'bottom' ? 'translate(-50%, 0)' : 'translate(-50%, -100%)',
+ visibility: pos == null ? 'hidden' : undefined,
}}
className={cn(
- 'pointer-events-none fixed z-[200]',
+ 'pointer-events-none fixed z-[200] max-w-[calc(100vw-1rem)]',
'whitespace-nowrap rounded bg-card-bg px-2 py-1 text-xs text-text-primary shadow-md',
className,
)}
@@ -102,7 +202,7 @@ export function Tooltip({ content, children, className, side = 'top' }: TooltipP
: null;
return (
- <span ref={triggerWrapRef} className="relative inline-flex">
+ <span ref={triggerWrapRef} className={cn('relative inline-flex', triggerClassName)}>
{child}
{tooltip}
</span>
@@ -113,13 +213,35 @@ export type LightTooltipProps = {
title: React.ReactNode;
children: React.ReactElement;
className?: string;
+ triggerClassName?: string;
size?: string;
side?: 'top' | 'bottom';
+ dismissOnClick?: boolean;
+ followCursor?: boolean;
+ anchor?: TooltipAnchor | null;
};
-export function LightTooltip({ title, children, className, size: _size, side }: LightTooltipProps) {
+export function LightTooltip({
+ title,
+ children,
+ className,
+ triggerClassName,
+ size: _size,
+ side,
+ dismissOnClick,
+ followCursor,
+ anchor,
+}: LightTooltipProps) {
return (
- <Tooltip content={title} className={className} side={side}>
+ <Tooltip
+ content={title}
+ className={className}
+ triggerClassName={triggerClassName}
+ side={side}
+ dismissOnClick={dismissOnClick}
+ followCursor={followCursor}
+ anchor={anchor}
+ >
{children}
</Tooltip>
);
diff --git a/packages/trueforge-ui/src/containers/AgentSessionTimelineContainer.tsx b/packages/trueforge-ui/src/containers/AgentSessionTimelineContainer.tsx
new file mode 100644
index 000000000..44d8d622f
--- /dev/null
+++ b/packages/trueforge-ui/src/containers/AgentSessionTimelineContainer.tsx
@@ -0,0 +1,203 @@
+'use client';
+
+import { ThreadPrimitive, type ThreadMessageLike } from '@assistant-ui/react';
+import { convertTurnsToThreadMessages } from '@truefoundry/assistant-ui-runtime';
+import { Suspense, useCallback, useEffect, useMemo, useRef, useState, type ComponentType } from 'react';
+
+import { useServer } from '../server/ServerContext.js';
+import type { AgentChatServer, SessionEventItem } from '../server/types.js';
+import type { SlotOverrides } from '../theme/SlotsProvider.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+import { buildSessionMetrics } from '../utils/buildSessionMetrics.js';
+import { buildSessionTimelineSegments } from '../utils/buildSessionTimelineSegments.js';
+import { createCachedListEventsBridge } from '../utils/cachedListEventsBridge.js';
+import { buildSessionTurnViews, type SessionTurnView } from '../utils/sessionTurnViews.js';
+import { AssistantMessageContainer } from './AssistantMessageContainer.js';
+import { ReadOnlySessionTurnRuntime } from './ReadOnlySessionTurnRuntime.js';
+import { UserMessageContainer } from './UserMessageContainer.js';
+
+const READ_ONLY_SLOT_OVERRIDES: SlotOverrides = {
+ UserMessageActionBar: () => <></>,
+ MessageActionBar: () => <></>,
+};
+
+function turnIdFromMessage(message: ThreadMessageLike): string {
+ const messageId = message.id ?? '';
+ if (message.role === 'user') {
+ return messageId.replace(/-user$/, '');
+ }
+ const custom = message.metadata?.custom;
+ if (custom != null && typeof custom === 'object' && 'turnId' in custom) {
+ const turnId = Reflect.get(custom, 'turnId');
+ if (typeof turnId === 'string' && turnId.length > 0) {
+ return turnId;
+ }
+ }
+ return messageId.replace(/-assistant$/, '');
+}
+
+function messagesForTurn(messages: ThreadMessageLike[], turnId: string): ThreadMessageLike[] {
+ return messages.filter(message => turnIdFromMessage(message) === turnId);
+}
+
+export type AgentSessionTimelineContainerProps = {
+ sessionId: string;
+ events: SessionEventItem[];
+ listMetrics?: {
+ totalTurns: number;
+ totalCostInUsd: number;
+ totalDurationMs: number;
+ };
+};
+
+export function AgentSessionTimelineContainer({ sessionId, events, listMetrics }: AgentSessionTimelineContainerProps) {
+ const server = useServer();
+ const AgentSessionTurnHeader = useSlot('AgentSessionTurnHeader');
+ const AgentSessionEventTimeline = useSlot('AgentSessionEventTimeline');
+ const AgentSessionMetricsStrip = useSlot('AgentSessionMetricsStrip');
+ const MessageListSkeleton = useSlot('MessageListSkeleton');
+ const ThreadViewportShell = useSlot('ThreadViewportShell');
+
+ const [messages, setMessages] = useState<ThreadMessageLike[]>();
+ const [loadFailed, setLoadFailed] = useState(false);
+ const sectionRefs = useRef(new Map<number, HTMLElement>());
+
+ const turnViews = useMemo(() => buildSessionTurnViews(events), [events]);
+ const timelineSegments = useMemo(() => buildSessionTimelineSegments(turnViews), [turnViews]);
+ const sessionMetrics = useMemo(
+ () => buildSessionMetrics({ turns: turnViews, segments: timelineSegments, listMetrics }),
+ [listMetrics, timelineSegments, turnViews],
+ );
+
+ const handleSelectTurn = useCallback((index: number) => {
+ sectionRefs.current.get(index)?.scrollIntoView({ behavior: 'smooth', block: 'start' });
+ }, []);
+
+ useEffect(() => {
+ let cancelled = false;
+ setMessages(undefined);
+ setLoadFailed(false);
+
+ const bridge = createCachedListEventsBridge(events);
+ // Events already include every turn.created / turn.done, so skip listTurns.
+ const chatServer: AgentChatServer = {
+ ...server,
+ listEvents: req => bridge.listEvents(req),
+ listTurns: async () => ({ data: [] }),
+ };
+
+ void convertTurnsToThreadMessages(chatServer, sessionId)
+ .then(result => {
+ if (!cancelled) setMessages(result.messages);
+ })
+ .catch(() => {
+ if (!cancelled) setLoadFailed(true);
+ });
+
+ return () => {
+ cancelled = true;
+ };
+ }, [events, server, sessionId]);
+
+ if (loadFailed) {
+ return (
+ <div className="flex flex-1 items-center justify-center px-6 text-sm text-text-secondary">
+ Session messages could not be loaded.
+ </div>
+ );
+ }
+
+ if (messages === undefined) {
+ return (
+ <div className="flex min-h-0 flex-1 flex-col overflow-hidden p-4">
+ <MessageListSkeleton />
+ </div>
+ );
+ }
+
+ if (messages.length === 0 && turnViews.length === 0) {
+ return (
+ <div className="flex flex-1 items-center justify-center px-6 text-sm text-text-secondary">
+ This session has no messages yet.
+ </div>
+ );
+ }
+
+ return (
+ <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
+ <div className="shrink-0 border-b border-border">
+ <AgentSessionMetricsStrip metrics={sessionMetrics} />
+ <Suspense fallback={null}>
+ <AgentSessionEventTimeline turns={turnViews} segments={timelineSegments} onSelectTurn={handleSelectTurn} />
+ </Suspense>
+ </div>
+ <ThreadViewportShell className="flex-1 pb-4">
+ <div className="flex flex-col gap-4">
+ {turnViews.map(turn => (
+ <SessionTurnSection
+ key={turn.turnId}
+ turn={turn}
+ messages={messagesForTurn(messages, turn.turnId)}
+ AgentSessionTurnHeader={AgentSessionTurnHeader}
+ onMount={node => {
+ if (node == null) sectionRefs.current.delete(turn.turnNumber - 1);
+ else sectionRefs.current.set(turn.turnNumber - 1, node);
+ }}
+ />
+ ))}
+ </div>
+ </ThreadViewportShell>
+ </div>
+ );
+}
+
+function SessionTurnSection({
+ turn,
+ messages,
+ AgentSessionTurnHeader,
+ onMount,
+}: {
+ turn: SessionTurnView;
+ messages: ThreadMessageLike[];
+ AgentSessionTurnHeader: ComponentType<{
+ turnNumber: number;
+ totalTokens?: number;
+ durationMs?: number;
+ totalCostInUsd?: number;
+ }>;
+ onMount: (node: HTMLElement | null) => void;
+}) {
+ if (!turn.showHeader && messages.length === 0) {
+ return null;
+ }
+
+ return (
+ <section ref={onMount} id={`session-turn-${turn.turnNumber}`} className="flex flex-col gap-2">
+ {turn.showHeader ? (
+ <AgentSessionTurnHeader
+ turnNumber={turn.turnNumber}
+ totalTokens={turn.totalTokens}
+ durationMs={turn.durationMs}
+ totalCostInUsd={turn.totalCostInUsd}
+ />
+ ) : null}
+ {messages.length > 0 ? (
+ <ReadOnlySessionTurnRuntime slotOverrides={READ_ONLY_SLOT_OVERRIDES} messages={messages}>
+ <ThreadPrimitive.Root asChild>
+ <div className="aui-root aui-thread-root flex w-full flex-col">
+ <ThreadPrimitive.Messages>
+ {({ message }) => (message.role === 'user' ? <UserMessageContainer /> : <AssistantMessageContainer />)}
+ </ThreadPrimitive.Messages>
+ </div>
+ </ThreadPrimitive.Root>
+ </ReadOnlySessionTurnRuntime>
+ ) : null}
+ </section>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentSessionTimelineContainer: typeof AgentSessionTimelineContainer;
+ }
+}
diff --git a/packages/trueforge-ui/src/containers/ReadOnlySessionTurnRuntime.tsx b/packages/trueforge-ui/src/containers/ReadOnlySessionTurnRuntime.tsx
new file mode 100644
index 000000000..c9dc8bee5
--- /dev/null
+++ b/packages/trueforge-ui/src/containers/ReadOnlySessionTurnRuntime.tsx
@@ -0,0 +1,30 @@
+'use client';
+
+import { AssistantRuntimeProvider, useExternalStoreRuntime, type ThreadMessageLike } from '@assistant-ui/react';
+import type { ReactNode } from 'react';
+
+import { SlotsProvider, type SlotOverrides } from '../theme/SlotsProvider.js';
+
+/** Read-only assistant-ui runtime for one turn's projected messages. */
+export function ReadOnlySessionTurnRuntime({
+ messages,
+ slotOverrides,
+ children,
+}: {
+ messages: ThreadMessageLike[];
+ slotOverrides?: SlotOverrides;
+ children: ReactNode;
+}) {
+ const runtime = useExternalStoreRuntime<ThreadMessageLike>({
+ messages,
+ isRunning: false,
+ convertMessage: message => message,
+ onNew: async () => {},
+ });
+
+ const tree = <AssistantRuntimeProvider runtime={runtime}>{children}</AssistantRuntimeProvider>;
+ if (slotOverrides == null) {
+ return tree;
+ }
+ return <SlotsProvider overrides={slotOverrides}>{tree}</SlotsProvider>;
+}
diff --git a/packages/trueforge-ui/src/containers/ThreadListContainer.tsx b/packages/trueforge-ui/src/containers/ThreadListContainer.tsx
index 230b16fe1..5b7923871 100644
--- a/packages/trueforge-ui/src/containers/ThreadListContainer.tsx
+++ b/packages/trueforge-ui/src/containers/ThreadListContainer.tsx
@@ -143,6 +143,8 @@ function ThreadListItemRow({
onSelect={() => {
onThreadOpen?.();
shell?.setSettingsOpen(false);
+ shell?.setLibraryOpen(false);
+ shell?.setSessionsOpen(false);
// Prefer custom.isMutable (session wire); agentName-only is a legacy fallback.
const sessionMutable = threadListItemIsMutable(custom);
@@ -266,6 +268,7 @@ export function ThreadListContainer({ onThreadOpen }: ThreadListContainerProps =
const ThreadListShell = useSlot('ThreadListShell');
const ThreadListNewButton = useSlot('ThreadListNewButton');
const AgentsLibraryButton = useSlot('AgentsLibraryButton');
+ const SessionsBrowserButton = useSlot('SessionsBrowserButton');
const ThreadListRowSkeleton = useSlot('ThreadListRowSkeleton');
const ThreadListEmptyState = useSlot('ThreadListEmptyState');
@@ -321,6 +324,8 @@ export function ThreadListContainer({ onThreadOpen }: ThreadListContainerProps =
const handleNewChat = () => {
onThreadOpen?.();
+ shell?.setLibraryOpen(false);
+ shell?.setSessionsOpen(false);
if (shell?.isComposerEnabled) {
shell.openDraft();
return;
@@ -349,11 +354,8 @@ export function ThreadListContainer({ onThreadOpen }: ThreadListContainerProps =
header={
<div className="flex flex-col gap-1">
{showNewChat ? <ThreadListNewButton onClick={handleNewChat} /> : null}
- <AgentsLibraryButton
- onSelectAgent={() => {
- onThreadOpen?.();
- }}
- />
+ <AgentsLibraryButton />
+ <SessionsBrowserButton />
</div>
}
>
diff --git a/packages/trueforge-ui/src/containers/TrueForgeUIShell.tsx b/packages/trueforge-ui/src/containers/TrueForgeUIShell.tsx
index 7bdb3d6a3..ab176e247 100644
--- a/packages/trueforge-ui/src/containers/TrueForgeUIShell.tsx
+++ b/packages/trueforge-ui/src/containers/TrueForgeUIShell.tsx
@@ -7,6 +7,7 @@ import { DraftCatalogProvider } from '../atoms/draft/DraftCatalogProvider.js';
import { DraftSpecPreferenceBridge } from '../atoms/draft/DraftSpecPreferenceBridge.js';
import { cn } from '../atoms/lib/cn.js';
import { Spinner } from '../atoms/primitives/Spinner.js';
+import { LibrarySessionShareBoot } from '../routing/LibrarySessionShareBoot.js';
import { RemoteIdRouteBridge } from '../routing/RemoteIdRouteBridge.js';
import type { ResolvedRoutes, RoutesConfig } from '../routing/types.js';
import { CustomActionRenderersProvider, type CustomActionRenderers } from '../server/CustomActionRenderersContext.js';
@@ -254,6 +255,7 @@ export function TrueForgeUIShell(props: TrueForgeUIShellProps) {
<CustomActionRenderersProvider renderers={customActionRenderers}>
<ServerProvider server={server}>
<ShellModeProvider agentConfig={agentConfig} initialSettingsOpen={initialSettingsOpen}>
+ <LibrarySessionShareBoot />
{resolvedRoutes != null ? (
<Suspense fallback={null}>
<ShellRouteSync
diff --git a/packages/trueforge-ui/src/github-markdown-bridge.css b/packages/trueforge-ui/src/github-markdown-bridge.css
index 5996ee06a..ad633815c 100644
--- a/packages/trueforge-ui/src/github-markdown-bridge.css
+++ b/packages/trueforge-ui/src/github-markdown-bridge.css
@@ -125,6 +125,18 @@
font-size: inherit;
}
+.aui-markdown.markdown-body h1 {
+ font-size: 1.4em;
+}
+
+.aui-markdown.markdown-body h2 {
+ font-size: 1.2em;
+}
+
+.aui-markdown.markdown-body h3 {
+ font-size: 1em;
+}
+
/* Preset typography applies to prose only; code always keeps a monospace stack. */
.aui-markdown.markdown-body :is(code, kbd, pre, samp, tt) {
font-family: var(
diff --git a/packages/trueforge-ui/src/hooks/useSessionShareSearch.ts b/packages/trueforge-ui/src/hooks/useSessionShareSearch.ts
new file mode 100644
index 000000000..acbcbea51
--- /dev/null
+++ b/packages/trueforge-ui/src/hooks/useSessionShareSearch.ts
@@ -0,0 +1,43 @@
+'use client';
+
+import { useCallback, useSyncExternalStore } from 'react';
+
+import {
+ readSessionShareSearch,
+ replaceSessionShareSearch,
+ SESSION_SHARE_CHANGE_EVENT,
+ type SessionShareSearch,
+ type SessionShareWrite,
+} from '../utils/sessionShareUrl.js';
+
+function subscribeShareSearch(onStoreChange: () => void): () => void {
+ window.addEventListener('popstate', onStoreChange);
+ window.addEventListener(SESSION_SHARE_CHANGE_EVENT, onStoreChange);
+ return () => {
+ window.removeEventListener('popstate', onStoreChange);
+ window.removeEventListener(SESSION_SHARE_CHANGE_EVENT, onStoreChange);
+ };
+}
+
+function getShareSearchSnapshot(): string {
+ return window.location.search;
+}
+
+function getServerShareSearchSnapshot(): string {
+ return '';
+}
+
+/**
+ * Session share query on `window.location`.
+ * Does not use react-router, so it works with `withRouter` on or off.
+ */
+export function useSessionShareSearch(): SessionShareSearch & {
+ updateShareSearch: (next: SessionShareWrite) => void;
+} {
+ const search = useSyncExternalStore(subscribeShareSearch, getShareSearchSnapshot, getServerShareSearchSnapshot);
+ const updateShareSearch = useCallback((next: SessionShareWrite) => {
+ replaceSessionShareSearch(next);
+ }, []);
+
+ return { ...readSessionShareSearch(search), updateShareSearch };
+}
diff --git a/packages/trueforge-ui/src/icons/IconRegistry.tsx b/packages/trueforge-ui/src/icons/IconRegistry.tsx
index f80f061ef..923f97853 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,
+ Link2,
ListChecks,
ListFilter,
ListOrdered,
@@ -154,6 +155,7 @@ const defaults: Record<string, IconEntry> = {
'list-check': ListChecks,
lock: Lock,
lightbulb: Lightbulb,
+ link: Link2,
wrench: Wrench,
cpu: Cpu,
cube: Box,
diff --git a/packages/trueforge-ui/src/index.ts b/packages/trueforge-ui/src/index.ts
index ca2f6ccbb..54b0f732c 100644
--- a/packages/trueforge-ui/src/index.ts
+++ b/packages/trueforge-ui/src/index.ts
@@ -239,7 +239,9 @@ export {
export type { CustomActionRendererProps, CustomActionRenderers } from './server/CustomActionRenderersContext.js';
export {
ServerProvider,
+ useAgentSessionsServer,
useCatalogServer,
+ useOptionalAgentSessionsServer,
useOptionalCatalogServer,
useOptionalServer,
useServer,
@@ -258,13 +260,17 @@ export type {
AgentBuilderCapabilitiesResponse,
AgentBuilderServer,
AgentChatServer,
+ AgentDetail,
AgentLibraryEntry,
+ AgentSessionsServer,
AgentSkill,
AgentSpec,
AgentUIServer,
ApprovalDecision,
AuthenticateConnectorRequest,
CatalogServer,
+ CodeSnippet,
+ CodeSnippetSampleCode,
ConnectorAuth,
ConnectorAuthApiKey,
ConnectorAuthNone,
@@ -290,6 +296,7 @@ export type {
GithubSkill,
ImportGithubSkillRequest,
ListResult,
+ ListSessionEventsParams,
ListSessionsOrder,
ListSessionsParams,
McpServerMount,
@@ -320,6 +327,8 @@ export type {
SelectRegistrySkillRequest,
Session,
SessionEventItem,
+ SessionListEntry,
+ SessionListMetrics,
SkillBase,
SkillCatalogEntry,
SkillCatalogServer,
@@ -327,6 +336,7 @@ export type {
SkillMount,
ToolBase,
Turn,
+ TurnDoneMetrics,
TurnInputItem,
TurnState,
TurnStreamData,
@@ -341,11 +351,41 @@ export type {
UserToolResponseEvent,
} from './server/types.js';
+export { AgentCodeBlock } from './atoms/agent-details/AgentCodeBlock.js';
+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 { AgentOverviewCard } from './atoms/agent-details/AgentOverviewCard.js';
+export type {
+ AgentCodeBlockProps,
+ AgentCodeSnippetsProps,
+ AgentDetailsHeaderProps,
+ AgentDetailsPageProps,
+ AgentDetailsTab,
+ AgentDetailsTabsProps,
+ AgentDetailsUnavailableProps,
+ AgentOverviewCardProps,
+ AgentOverviewProps,
+ AgentSessionDetailHeaderProps,
+ AgentSessionEventTimelineChartProps,
+ AgentSessionEventTimelineProps,
+ AgentSessionListRowProps,
+ AgentSessionMetricsStripProps,
+ AgentSessionTurnHeaderProps,
+ AgentSessionsProps,
+} from './atoms/agent-details/types.js';
+export type { SessionEventTimelineSegment, SessionEventType } from './utils/sessionEventTimeline.js';
+export type { SessionTurnView } from './utils/sessionTurnViews.js';
+
// Utils
export { computeAgentStepsSplit } from './utils/computeAgentStepsSplit.js';
export type { AgentStepPart, AgentStepsSplitResult } from './utils/computeAgentStepsSplit.js';
export { getErrorMessage } from './utils/getErrorMessage.js';
+export { AgentSessionsFilters } from './atoms/agent-details/AgentSessionsFilters.js';
+export type { AgentSessionsFiltersProps } from './atoms/agent-details/AgentSessionsFilters.js';
+export { SessionsPage } from './atoms/agent-details/SessionsPage.js';
export { AgentsLibrary } from './atoms/AgentsLibrary.js';
export type { AgentsLibraryProps } from './atoms/AgentsLibrary.js';
export { AgentsLibraryButton } from './atoms/AgentsLibraryButton.js';
@@ -357,3 +397,5 @@ export type { DraftCompositeSelectorProps } from './atoms/draft/DraftCompositeSe
export { DraftModelSelector } from './atoms/draft/DraftModelSelector.js';
export type { DraftModelSelectorProps } from './atoms/draft/DraftModelSelector.js';
export { SaveAgentButton } from './atoms/SaveAgentButton.js';
+export { SessionsBrowserButton } from './atoms/SessionsBrowserButton.js';
+export type { SessionsBrowserButtonProps } from './atoms/SessionsBrowserButton.js';
diff --git a/packages/trueforge-ui/src/layouts/DrawerLayout.tsx b/packages/trueforge-ui/src/layouts/DrawerLayout.tsx
index caed58cd6..a2645f385 100644
--- a/packages/trueforge-ui/src/layouts/DrawerLayout.tsx
+++ b/packages/trueforge-ui/src/layouts/DrawerLayout.tsx
@@ -20,6 +20,9 @@ export function DrawerLayout({ className }: { className?: string }) {
const aui = useAui();
const shell = useOptionalShellMode();
const ClearChatButton = useSlot('ClearChatButton');
+ const AgentDetailsPage = useSlot('AgentDetailsPage');
+ const AgentsLibrary = useSlot('AgentsLibrary');
+ const SessionsPage = useSlot('SessionsPage');
const SaveAgentButton = useSlot('SaveAgentButton');
const SelectAgentEmptyState = useSlot('SelectAgentEmptyState');
const [threadsOpen, setThreadsOpen] = useState(false);
@@ -29,6 +32,9 @@ export function DrawerLayout({ className }: { className?: string }) {
const wasOpen = useRef(false);
const isIdle = shell?.mode.status === 'idle';
const settingsOpen = shell?.settingsOpen === true;
+ const libraryOpen = shell?.libraryOpen === true;
+ const sessionsOpen = shell?.sessionsOpen === true;
+ const overlayOpen = settingsOpen || libraryOpen || sessionsOpen;
useEffect(() => {
if (!threadsOpen) return;
@@ -55,6 +61,8 @@ export function DrawerLayout({ className }: { className?: string }) {
}, [threadsOpen]);
const handleNewChat = () => {
+ shell?.setLibraryOpen(false);
+ shell?.setSessionsOpen(false);
if (shell?.isComposerEnabled) {
shell.openDraft();
} else {
@@ -68,7 +76,7 @@ export function DrawerLayout({ className }: { className?: string }) {
<div className={cn('relative flex h-full min-h-0 w-full flex-col bg-primary-bg', className)}>
{/* Keep ShellActions mounted across Settings open/close so host action-slot state persists. */}
<header className="flex shrink-0 items-center gap-1 border-b border-border bg-topbar-bg px-2 py-1.5">
- {!settingsOpen ? (
+ {!overlayOpen ? (
<>
<NamedAgentHeaderLabel />
<span className="min-w-0 flex-1" />
@@ -79,7 +87,7 @@ export function DrawerLayout({ className }: { className?: string }) {
<span className="min-w-0 flex-1" />
)}
<ShellActions key="shell-actions" />
- {!settingsOpen ? (
+ {!overlayOpen ? (
<>
{shell?.isNewChatEnabled !== false ? (
<button
@@ -122,6 +130,12 @@ export function DrawerLayout({ className }: { className?: string }) {
>
<TruefoundrySettingsBuilder />
</Suspense>
+ ) : sessionsOpen ? (
+ <SessionsPage />
+ ) : libraryOpen && shell?.libraryAgentId != null ? (
+ <AgentDetailsPage key={shell.libraryAgentId} agentId={shell.libraryAgentId} />
+ ) : libraryOpen ? (
+ <AgentsLibrary onSelectAgent={() => setThreadsOpen(false)} />
) : isIdle ? (
<SelectAgentEmptyState />
) : (
diff --git a/packages/trueforge-ui/src/layouts/SidebarLayout.tsx b/packages/trueforge-ui/src/layouts/SidebarLayout.tsx
index c34c6f1a2..672f912c2 100644
--- a/packages/trueforge-ui/src/layouts/SidebarLayout.tsx
+++ b/packages/trueforge-ui/src/layouts/SidebarLayout.tsx
@@ -31,7 +31,11 @@ export function SidebarLayout({ className }: { className?: string }) {
const brandName = useBrandName();
const chrome = resolveBrandChrome(brand);
const BrandLogo = useSlot('BrandLogo');
+ const AgentDetailsPage = useSlot('AgentDetailsPage');
+ const AgentsLibrary = useSlot('AgentsLibrary');
const AgentsLibraryButton = useSlot('AgentsLibraryButton');
+ const SessionsBrowserButton = useSlot('SessionsBrowserButton');
+ const SessionsPage = useSlot('SessionsPage');
const ClearChatButton = useSlot('ClearChatButton');
const SaveAgentButton = useSlot('SaveAgentButton');
const SelectAgentEmptyState = useSlot('SelectAgentEmptyState');
@@ -50,6 +54,9 @@ export function SidebarLayout({ className }: { className?: string }) {
const wasOpen = useRef(false);
const isIdle = shell?.mode.status === 'idle';
const settingsOpen = shell?.settingsOpen === true;
+ const libraryOpen = shell?.libraryOpen === true;
+ const sessionsOpen = shell?.sessionsOpen === true;
+ const overlayOpen = settingsOpen || libraryOpen || sessionsOpen;
const hasChatHeaderContent = useChatHeaderContentVisible();
useEffect(() => {
@@ -77,6 +84,8 @@ export function SidebarLayout({ className }: { className?: string }) {
}, [mobileNavOpen]);
const handleNewChat = () => {
+ shell?.setLibraryOpen(false);
+ shell?.setSessionsOpen(false);
if (shell?.isComposerEnabled) {
shell.openDraft();
return;
@@ -132,6 +141,7 @@ export function SidebarLayout({ className }: { className?: string }) {
</button>
) : null}
<AgentsLibraryButton compact />
+ <SessionsBrowserButton compact />
</nav>
<div className="flex min-h-0 flex-1 flex-col overflow-hidden" hidden={collapsed}>
<ThreadListContainer />
@@ -155,10 +165,10 @@ export function SidebarLayout({ className }: { className?: string }) {
'flex shrink-0 items-center gap-1 border-b border-border bg-topbar-bg px-2 py-1.5',
// Desktop: hide when settings/idle or the thread header has nothing to show
// (empty untitled draft). Mobile still needs Sessions + ShellActions.
- (settingsOpen || isIdle || !hasChatHeaderContent) && 'md:hidden',
+ (overlayOpen || isIdle || !hasChatHeaderContent) && 'md:hidden',
)}
>
- {!settingsOpen ? (
+ {!overlayOpen ? (
<>
<button
ref={menuBtnRef}
@@ -200,6 +210,12 @@ export function SidebarLayout({ className }: { className?: string }) {
>
<TruefoundrySettingsBuilder />
</Suspense>
+ ) : sessionsOpen ? (
+ <SessionsPage />
+ ) : libraryOpen && shell?.libraryAgentId != null ? (
+ <AgentDetailsPage key={shell.libraryAgentId} agentId={shell.libraryAgentId} />
+ ) : libraryOpen ? (
+ <AgentsLibrary onSelectAgent={() => setMobileNavOpen(false)} />
) : isIdle ? (
<SelectAgentEmptyState />
) : (
diff --git a/packages/trueforge-ui/src/layouts/StackChatPanel.tsx b/packages/trueforge-ui/src/layouts/StackChatPanel.tsx
index e84396494..e638633dd 100644
--- a/packages/trueforge-ui/src/layouts/StackChatPanel.tsx
+++ b/packages/trueforge-ui/src/layouts/StackChatPanel.tsx
@@ -31,10 +31,15 @@ export function StackChatPanel({ className, threadHeaderEnd }: StackChatPanelPro
const aui = useAui();
const shell = useOptionalShellMode();
const ClearChatButton = useSlot('ClearChatButton');
+ const AgentDetailsPage = useSlot('AgentDetailsPage');
+ const AgentsLibrary = useSlot('AgentsLibrary');
+ const SessionsPage = useSlot('SessionsPage');
const SaveAgentButton = useSlot('SaveAgentButton');
const SelectAgentEmptyState = useSlot('SelectAgentEmptyState');
const isIdle = shell?.mode.status === 'idle';
const settingsOpen = shell?.settingsOpen === true;
+ const libraryOpen = shell?.libraryOpen === true;
+ const sessionsOpen = shell?.sessionsOpen === true;
useEffect(() => {
if (isIdle) return;
@@ -61,6 +66,18 @@ export function StackChatPanel({ className, threadHeaderEnd }: StackChatPanelPro
<TruefoundrySettingsBuilder />
</Suspense>
</div>
+ ) : sessionsOpen ? (
+ <div className="min-h-0 flex-1">
+ <SessionsPage />
+ </div>
+ ) : libraryOpen && shell?.libraryAgentId != null ? (
+ <div className="min-h-0 flex-1">
+ <AgentDetailsPage key={shell.libraryAgentId} agentId={shell.libraryAgentId} />
+ </div>
+ ) : libraryOpen ? (
+ <div className="min-h-0 flex-1">
+ <AgentsLibrary onSelectAgent={() => setView('thread')} />
+ </div>
) : view === 'list' ? (
<ThreadListContainer onThreadOpen={() => setView('thread')} />
) : (
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
new file mode 100644
index 000000000..2f31b625f
--- /dev/null
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/agentSessionsServer.ts
@@ -0,0 +1,81 @@
+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 { toUiEventItem } from './toUiTurnState.js';
+import type { HarnessAgentSpec } from './types.js';
+
+export type CreateHarnessAgentSessionsServerOptions = CreateTrueForgeClientOptions & {
+ 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,
+ },
+ ...(session.title === null ? {} : { title: session.title }),
+ ...(session.agent.type === 'reference' && session.agent.name !== null ? { agentName: session.agent.name } : {}),
+ ...(session.agent.type === 'inline' ? { agentSpec: toUiAgentSpec(session.agent.spec) } : {}),
+ };
+}
+
+export function createHarnessAgentSessionsServer(
+ options: CreateHarnessAgentSessionsServerOptions = {},
+): AgentSessionsServer<HarnessAgentSpec> {
+ const client = options.client ?? createTrueForgeClient(options);
+
+ return {
+ async getAgent({ agentId }) {
+ const { data } = await client.agents.get(agentId);
+ return {
+ agentId: data.id,
+ name: data.name,
+ agentSpec: toUiAgentSpec(data.manifest),
+ };
+ },
+ async getCodeSnippets({ agentId }) {
+ const { data } = await client.internal.agents.getCodeSnippets(agentId);
+ return data.snippets;
+ },
+ async listSessions(requestParams = {}) {
+ const page = await client.sessions.list({
+ ...(requestParams.limit === undefined ? {} : { limit: requestParams.limit }),
+ ...(requestParams.order === undefined ? {} : { order: requestParams.order }),
+ ...(requestParams.pageToken === undefined ? {} : { pageToken: requestParams.pageToken }),
+ ...(requestParams.startTimestamp === undefined
+ ? {}
+ : { startTimestamp: toIsoDate(requestParams.startTimestamp) }),
+ ...(requestParams.endTimestamp === undefined ? {} : { endTimestamp: toIsoDate(requestParams.endTimestamp) }),
+ ...(requestParams.agentId === undefined || requestParams.agentId.length === 0
+ ? {}
+ : { agentId: requestParams.agentId }),
+ });
+ return toListResult(page, toSessionListEntry);
+ },
+ async listSessionEvents({ sessionId, pageToken, limit }) {
+ const page = await client.sessions.listEvents(sessionId, {
+ ...(pageToken === undefined ? {} : { pageToken }),
+ ...(limit === undefined ? {} : { limit }),
+ });
+ return toListResult(page, toUiEventItem);
+ },
+ };
+}
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts
index f52d9f896..34ba147fc 100644
--- a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/chatServer.ts
@@ -16,12 +16,12 @@ import type {
AgentChatServer,
ListResult,
Session,
- SessionEventItem,
Turn,
TurnInputItem,
UserMessageContent,
} from '../../server/types.js';
import { createTrueForgeClient, type CreateTrueForgeClientOptions } from './client.js';
+import { toUiEventItem, toUiStreamingEvent, toUiTurnState } from './toUiTurnState.js';
import type { HarnessAgentSpec, HarnessMcpServerMount, HarnessSkillMount } from './types.js';
export type { HarnessAgentSpec, HarnessMcpServerMount, HarnessSkillMount } from './types.js';
@@ -93,24 +93,21 @@ function toUiInput(input: TrueForgeApi.TurnInputItem[]): TurnInputItem[] {
}
function toUiTurn(turn: TrueForgeApi.Turn): Turn {
- const { previousTurnId, input, ...rest } = turn;
+ const { previousTurnId, input, state, ...rest } = turn;
return {
...rest,
+ state: toUiTurnState(state),
...(previousTurnId === null ? {} : { previousTurnId }),
...(input === undefined ? {} : { input: toUiInput(input) }),
};
}
-function toUiEventItem(item: TrueForgeApi.SessionEventItem): SessionEventItem {
- return { turnId: item.turnId, event: { ...item.event } };
-}
-
-interface HarnessPageSource<T> {
+export interface HarnessPageSource<T> {
data: T[];
response: { pagination: TrueForgeApi.TokenPagination };
}
-function toListResult<TSource, TResult>(
+export function toListResult<TSource, TResult>(
page: HarnessPageSource<TSource>,
map: (item: TSource) => TResult,
): ListResult<TResult> {
@@ -218,7 +215,7 @@ export function createHarnessChatServer(
for await (const item of stream.withMetadata()) {
yield {
sequenceNumber: sequenceNumber(item.id, fallbackSequence),
- event: { ...item.data },
+ event: toUiStreamingEvent(item.data),
};
fallbackSequence += 1;
}
@@ -241,7 +238,7 @@ export function createHarnessChatServer(
for await (const item of stream.withMetadata()) {
yield {
sequenceNumber: sequenceNumber(item.id, fallbackSequence),
- event: { ...item.data },
+ event: toUiStreamingEvent(item.data),
};
fallbackSequence += 1;
}
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 e1b6dce46..c4e6ca47f 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
@@ -13,9 +13,23 @@ export interface CreateTrueForgeClientOptions {
const DEFAULT_BASE_URL = '/';
+/**
+ * SDK passthrough `fetch` only attaches Bearer when `baseUrl` and the request URL
+ * are absolute same-origin URLs. Relative defaults like `/` fail that check, so
+ * absolutize against the page origin in the browser.
+ */
+export function resolveTrueForgeBaseUrl(baseUrl: string): string {
+ if (/^https?:\/\//i.test(baseUrl)) return baseUrl;
+ const origin = globalThis.location?.origin;
+ if (typeof origin === 'string' && origin.length > 0 && origin !== 'null') {
+ return new URL(baseUrl, origin).href;
+ }
+ return baseUrl;
+}
+
export function createTrueForgeClient(options: CreateTrueForgeClientOptions = {}): TrueForge {
return new TrueForge({
- baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+ baseUrl: resolveTrueForgeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL),
...(options.token === undefined ? {} : { token: options.token }),
...(options.fetch === undefined ? {} : { fetch: options.fetch }),
});
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 22f806734..7f948e9a0 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 { createHarnessAgentSessionsServer } from './agentSessionsServer.js';
import { createHarnessBuilderServer } from './builderServer.js';
import { createConnectorCatalog } from './catalogs/connectorCatalog.js';
import { createModelProviderCatalog } from './catalogs/modelProviderCatalog.js';
@@ -12,6 +13,10 @@ import { createHarnessChatServer } from './chatServer.js';
import { createTrueForgeClient, type CreateTrueForgeClientOptions } from './client.js';
import type { HarnessAgentSpec } from './types.js';
+export {
+ createHarnessAgentSessionsServer,
+ type CreateHarnessAgentSessionsServerOptions,
+} from './agentSessionsServer.js';
export {
createHarnessBuilderServer,
modelProviderLogosByName,
@@ -57,7 +62,7 @@ export type CreateTrueForgeAgentUIServerOptions = CreateTrueForgeClientOptions &
};
/**
- * Compose chat + builder + default settings catalogs into an `AgentUIServer`.
+ * Compose chat + builder + agent sessions + default settings catalogs into an `AgentUIServer`.
*/
export function createTrueForgeAgentUIServer(options: CreateTrueForgeAgentUIServerOptions = {}) {
const { catalog: catalogOverride, ...clientOptions } = options;
@@ -75,5 +80,6 @@ export function createTrueForgeAgentUIServer(options: CreateTrueForgeAgentUIServ
chatServer: createHarnessChatServer({ client }),
...createHarnessBuilderServer({ client }),
catalog,
+ sessions: createHarnessAgentSessionsServer({ ...clientOptions, client }),
});
}
diff --git a/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/toUiTurnState.ts b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/toUiTurnState.ts
new file mode 100644
index 000000000..3eda956b5
--- /dev/null
+++ b/packages/trueforge-ui/src/plugins/trueforge-agent-server-adapter/toUiTurnState.ts
@@ -0,0 +1,50 @@
+import type { TrueForgeApi } from '@truefoundry/trueforge-sdk';
+import type { SessionEventItem, TurnDoneMetrics, TurnState, TurnStreamingEvent } from '../../server/types.js';
+
+/** SDK token fields are optional; the UI contract requires numbers. Keep cost for session tiles. */
+export function toUiTurnDoneMetrics(metrics: TrueForgeApi.TurnMetrics): TurnDoneMetrics & { totalCostInUsd?: number } {
+ return {
+ totalInputTokens: metrics.totalInputTokens ?? 0,
+ totalOutputTokens: metrics.totalOutputTokens ?? 0,
+ totalTokens: metrics.totalTokens ?? 0,
+ totalCacheReadTokens: metrics.totalCacheReadTokens ?? 0,
+ totalCacheWriteTokens: metrics.totalCacheWriteTokens ?? 0,
+ totalReasoningTokens: metrics.totalReasoningTokens ?? 0,
+ ...(metrics.totalCostInUsd == null ? {} : { totalCostInUsd: metrics.totalCostInUsd }),
+ };
+}
+
+export function toUiTurnState(state: TrueForgeApi.TurnState | TrueForgeApi.TurnDoneEventState): TurnState {
+ return state.status === 'running' ? { status: 'running' } : toUiTerminalTurnState(state);
+}
+
+function toUiTerminalTurnState(state: TrueForgeApi.TurnDoneEventState): Exclude<TurnState, { status: 'running' }> {
+ switch (state.status) {
+ case 'cancelled':
+ return { status: 'cancelled', reason: state.reason, completedAt: state.completedAt };
+ case 'error':
+ return { status: 'error', message: state.message, completedAt: state.completedAt };
+ case 'done':
+ return {
+ status: 'done',
+ completedAt: state.completedAt,
+ requiredActions: state.requiredActions,
+ ...(state.output == null ? {} : { output: state.output }),
+ ...(state.metrics == null ? {} : { metrics: toUiTurnDoneMetrics(state.metrics) }),
+ };
+ }
+}
+
+export function toUiSessionEvent(event: TrueForgeApi.SessionEvent): SessionEventItem['event'] {
+ if (event.type !== 'turn.done') return { ...event };
+ return { ...event, state: toUiTerminalTurnState(event.state) };
+}
+
+export function toUiStreamingEvent(event: TrueForgeApi.TurnStreamingEvent): TurnStreamingEvent {
+ if (event.type !== 'turn.done') return { ...event };
+ return { ...event, state: toUiTerminalTurnState(event.state) };
+}
+
+export function toUiEventItem(item: TrueForgeApi.SessionEventItem): SessionEventItem {
+ return { turnId: item.turnId, event: toUiSessionEvent(item.event) };
+}
diff --git a/packages/trueforge-ui/src/routing/LibrarySessionShareBoot.tsx b/packages/trueforge-ui/src/routing/LibrarySessionShareBoot.tsx
new file mode 100644
index 000000000..dd07c9901
--- /dev/null
+++ b/packages/trueforge-ui/src/routing/LibrarySessionShareBoot.tsx
@@ -0,0 +1,23 @@
+'use client';
+
+import { useEffect } from 'react';
+
+import { useShellMode } from '../server/ShellModeContext.js';
+import { readSessionShareSearch } from '../utils/sessionShareUrl.js';
+
+/** Open the sessions browser or a library agent from the share query — with or without `withRouter`. */
+export function LibrarySessionShareBoot() {
+ const { openLibraryAgent, setSessionsOpen } = useShellMode();
+
+ useEffect(() => {
+ const share = readSessionShareSearch(window.location.search);
+ if (share.view === 'sessions') {
+ setSessionsOpen(true);
+ return;
+ }
+ if (share.agentId == null) return;
+ openLibraryAgent(share.agentId);
+ }, [openLibraryAgent, setSessionsOpen]);
+
+ return null;
+}
diff --git a/packages/trueforge-ui/src/routing/ShellRouteSync.tsx b/packages/trueforge-ui/src/routing/ShellRouteSync.tsx
index 7cac209fb..1d7f87864 100644
--- a/packages/trueforge-ui/src/routing/ShellRouteSync.tsx
+++ b/packages/trueforge-ui/src/routing/ShellRouteSync.tsx
@@ -6,7 +6,7 @@ import { useLocation, useNavigate } from 'react-router-dom';
import { useOptionalServer } from '../server/ServerContext.js';
import { useShellMode } from '../server/ShellModeContext.js';
import { deriveChatPlace, derivePlace } from './derivePlace.js';
-import { buildPath, matchPath, placesEqual } from './paths.js';
+import { buildPath, matchLocation, placesEqual, sanitizeSearchForPlace } from './paths.js';
import type { ResolvedRoutes, RoutePlace, ShellSnapshot } from './types.js';
/**
@@ -29,6 +29,9 @@ export function ShellRouteSync({
const snapshot: ShellSnapshot = {
settingsOpen: shell.settingsOpen,
+ libraryOpen: shell.libraryOpen,
+ sessionsOpen: shell.sessionsOpen,
+ libraryAgentId: shell.libraryAgentId,
pendingSessionId: shell.pendingSessionId,
activeRemoteId,
mode: shell.mode,
@@ -87,15 +90,27 @@ export function ShellRouteSync({
case 'settings':
shell.setSettingsOpen(true);
return;
+ case 'library':
+ shell.setLibraryOpen(true);
+ return;
+ case 'sessionsBrowser':
+ shell.setSessionsOpen(true);
+ return;
+ case 'libraryAgent':
+ shell.openLibraryAgent(target.agentId);
+ return;
case 'session':
+ shell.setLibraryOpen(false);
if (shell.pendingSessionId === target.sessionId || activeRemoteId === target.sessionId) return;
openSession(target.sessionId);
return;
case 'agent':
+ shell.setLibraryOpen(false);
shell.selectLibraryAgent({ isMutable: false, agentName: target.agentName });
return;
case 'root':
shell.setSettingsOpen(false);
+ shell.setLibraryOpen(false);
switch (shell.agentConfigMode) {
case 'AgentLibrary':
shell.openLibraryHome();
@@ -119,11 +134,21 @@ export function ShellRouteSync({
if (bootedRef.current) return;
bootedRef.current = true;
- const urlPlace = matchPath(location.pathname, routes) ?? { type: 'root' };
+ const urlPlace = matchLocation({
+ pathname: location.pathname,
+ search: location.search,
+ routes,
+ }) ?? { type: 'root' };
const settingsOnBoot = initialSettingsOpen || urlPlace.type === 'settings';
if (urlPlace.type === 'settings') {
shell.setSettingsOpen(true);
+ } else if (urlPlace.type === 'library') {
+ shell.setLibraryOpen(true);
+ } else if (urlPlace.type === 'sessionsBrowser') {
+ shell.setSessionsOpen(true);
+ } else if (urlPlace.type === 'libraryAgent') {
+ shell.openLibraryAgent(urlPlace.agentId);
} else {
const chatPlace = deriveChatPlace(snapshot);
if (!placesEqual(chatPlace, urlPlace)) applyPlace(urlPlace);
@@ -132,10 +157,11 @@ export function ShellRouteSync({
const desiredPlace: RoutePlace = settingsOnBoot ? { type: 'settings' } : urlPlace;
const desiredPath = buildPath(desiredPlace, routes);
+ const desiredSearch = sanitizeSearchForPlace(desiredPlace, location.search);
prevPlaceRef.current = desiredPlace;
- if (desiredPath != null && desiredPath !== location.pathname) {
- selfNavPathRef.current = desiredPath;
- navigate({ pathname: desiredPath, search: location.search, hash: location.hash }, { replace: true });
+ if (desiredPath != null && (desiredPath !== location.pathname || desiredSearch !== location.search)) {
+ selfNavPathRef.current = desiredPath !== location.pathname ? desiredPath : null;
+ navigate({ pathname: desiredPath, search: desiredSearch, hash: location.hash }, { replace: true });
}
// Boot runs once; snapshot is read imperatively here.
// eslint-disable-next-line react-hooks/exhaustive-deps
@@ -150,19 +176,23 @@ export function ShellRouteSync({
}
const target = buildPath(place, routes);
if (target == null) return; // place has no configured URL (e.g. settings disabled)
+ const basename = routes.basename.endsWith('/') ? routes.basename.slice(0, -1) : routes.basename;
+ const browserPathname = `${basename}${location.pathname}` || '/';
+ const latestSearch = window.location.pathname === browserPathname ? window.location.search : location.search;
+ const targetSearch = sanitizeSearchForPlace(place, latestSearch);
const prev = prevPlaceRef.current;
prevPlaceRef.current = place;
- if (target === location.pathname) return;
+ if (target === location.pathname && targetSearch === location.search) return;
// Replace when a fresh chat just acquired its session id (same place, new id).
const replace =
place.type === 'session' && shell.pendingSessionId == null && prev != null && prev.type !== 'session';
- selfNavPathRef.current = target;
- // Only the pathname is ours; host query/hash state rides along unchanged.
- navigate({ pathname: target, search: location.search, hash: location.hash }, { replace });
+ selfNavPathRef.current = target !== location.pathname ? target : null;
+ // Query keys owned by other shell places are removed; host keys and hash survive.
+ navigate({ pathname: target, search: targetSearch, hash: location.hash }, { replace });
// location.pathname intentionally excluded: only react to shell-derived place changes.
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [placeKey]);
@@ -178,12 +208,17 @@ export function ShellRouteSync({
selfNavPathRef.current = null;
return;
}
- const urlPlace = matchPath(location.pathname, routes);
+ const urlPlace = matchLocation({
+ pathname: location.pathname,
+ search: location.search,
+ routes,
+ });
if (urlPlace == null) {
// Unknown path: normalize to root.
const rootPath = routes.root;
+ const rootSearch = sanitizeSearchForPlace({ type: 'root' }, location.search);
selfNavPathRef.current = rootPath;
- navigate({ pathname: rootPath, search: location.search, hash: location.hash }, { replace: true });
+ navigate({ pathname: rootPath, search: rootSearch, hash: location.hash }, { replace: true });
applyPlace({ type: 'root' });
return;
}
@@ -191,6 +226,12 @@ export function ShellRouteSync({
// Leaving settings via Back to a chat place.
shell.setSettingsOpen(false);
}
+ if (urlPlace.type !== 'library' && urlPlace.type !== 'libraryAgent' && shell.libraryOpen) {
+ shell.setLibraryOpen(false);
+ }
+ if (urlPlace.type !== 'sessionsBrowser' && shell.sessionsOpen) {
+ shell.setSessionsOpen(false);
+ }
applyPlace(urlPlace);
// eslint-disable-next-line react-hooks/exhaustive-deps
}, [location.pathname]);
diff --git a/packages/trueforge-ui/src/routing/derivePlace.ts b/packages/trueforge-ui/src/routing/derivePlace.ts
index 0f0cddccb..59dbf4b6b 100644
--- a/packages/trueforge-ui/src/routing/derivePlace.ts
+++ b/packages/trueforge-ui/src/routing/derivePlace.ts
@@ -1,7 +1,7 @@
import type { RoutePlace, ShellSnapshot } from './types.js';
/**
- * The chat place implied by shell state, ignoring the settings overlay.
+ * The chat place implied by shell state, ignoring overlay routes (settings, library).
* SingleAgent canonicalizes to `root` so `/` and `/agents/{name}` alias.
*/
export function deriveChatPlace(snapshot: ShellSnapshot): RoutePlace {
@@ -19,8 +19,13 @@ export function deriveChatPlace(snapshot: ShellSnapshot): RoutePlace {
return { type: 'root' };
}
-/** Full place including the settings overlay, which wins over the chat place. */
+/** Full place including overlay routes, which win over the chat place. */
export function derivePlace(snapshot: ShellSnapshot): RoutePlace {
if (snapshot.settingsOpen) return { type: 'settings' };
+ if (snapshot.sessionsOpen) return { type: 'sessionsBrowser' };
+ if (snapshot.libraryOpen && snapshot.libraryAgentId != null) {
+ return { type: 'libraryAgent', agentId: snapshot.libraryAgentId };
+ }
+ if (snapshot.libraryOpen) return { type: 'library' };
return deriveChatPlace(snapshot);
}
diff --git a/packages/trueforge-ui/src/routing/paths.ts b/packages/trueforge-ui/src/routing/paths.ts
index 90604bff2..5c1010b7e 100644
--- a/packages/trueforge-ui/src/routing/paths.ts
+++ b/packages/trueforge-ui/src/routing/paths.ts
@@ -1,10 +1,14 @@
+import { readSessionShareSearch, writeSessionShareSearch } from '../utils/sessionShareUrl.js';
import type { ResolvedRoutes, RoutePlace, RoutesConfig } from './types.js';
const DEFAULTS = {
root: '/',
settings: '/settings',
+ library: '/library',
+ libraryAgent: '/library/:agentId',
agent: '/agents/:agentName',
session: '/sessions/:sessionId',
+ sessionsBrowser: '/sessions',
} as const;
function normalizePath(path: string): string {
@@ -25,8 +29,11 @@ export function resolveRoutesConfig(routes?: RoutesConfig): ResolvedRoutes {
basename: routes?.basename ?? '',
root: normalizePath(paths?.root ?? DEFAULTS.root),
settings: resolveOptional(paths?.settings, DEFAULTS.settings),
+ library: resolveOptional(paths?.library, DEFAULTS.library),
+ libraryAgent: resolveOptional(paths?.libraryAgent, DEFAULTS.libraryAgent),
agent: resolveOptional(paths?.agent, DEFAULTS.agent),
session: resolveOptional(paths?.session, DEFAULTS.session),
+ sessionsBrowser: resolveOptional(paths?.sessionsBrowser, DEFAULTS.sessionsBrowser),
};
}
@@ -51,13 +58,49 @@ export function buildPath(place: RoutePlace, routes: ResolvedRoutes): string | n
return routes.root;
case 'settings':
return routes.settings;
+ case 'library':
+ return routes.library;
+ case 'libraryAgent':
+ return routes.libraryAgent == null ? null : fillTemplate(routes.libraryAgent, place.agentId);
case 'agent':
return routes.agent == null ? null : fillTemplate(routes.agent, place.agentName);
case 'session':
return routes.session == null ? null : fillTemplate(routes.session, place.sessionId);
+ case 'sessionsBrowser':
+ return routes.sessionsBrowser;
}
}
+/**
+ * Remove query state owned by a different shell place while preserving host
+ * parameters. Settings is an overlay, so it retains the underlying place state.
+ */
+export function sanitizeSearchForPlace(place: RoutePlace, search: string): string {
+ if (place.type === 'settings') return search;
+
+ const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
+ if (place.type === 'sessionsBrowser') {
+ writeSessionShareSearch(params, { tab: null });
+ } else if (place.type === 'libraryAgent') {
+ const share = readSessionShareSearch(search);
+ writeSessionShareSearch(params, {
+ view: null,
+ timeRange: null,
+ ...(share.sessionId != null && share.agentId !== place.agentId ? { sessionId: null, agentId: null } : {}),
+ });
+ } else {
+ writeSessionShareSearch(params, {
+ sessionId: null,
+ agentId: null,
+ tab: null,
+ view: null,
+ timeRange: null,
+ });
+ }
+ const next = params.toString();
+ return next.length > 0 ? `?${next}` : '';
+}
+
/** Percent-decode a segment; `null` when the URL carries a malformed escape. */
function decodeSegment(segment: string): string | null {
try {
@@ -95,6 +138,16 @@ export function matchPath(pathname: string, routes: ResolvedRoutes): RoutePlace
if (routes.settings != null && normalized === routes.settings) {
return { type: 'settings' };
}
+ if (routes.library != null && normalized === routes.library) {
+ return { type: 'library' };
+ }
+ if (routes.sessionsBrowser != null && normalized === routes.sessionsBrowser) {
+ return { type: 'sessionsBrowser' };
+ }
+ if (routes.libraryAgent != null) {
+ const agentId = matchTemplate(routes.libraryAgent, segments);
+ if (agentId != null) return { type: 'libraryAgent', agentId };
+ }
if (routes.agent != null) {
const agentName = matchTemplate(routes.agent, segments);
if (agentName != null) return { type: 'agent', agentName };
@@ -109,9 +162,26 @@ export function matchPath(pathname: string, routes: ResolvedRoutes): RoutePlace
return null;
}
+/** Pathname place, or library agent from `?agentId=` when the path is root. */
+export function matchLocation({
+ pathname,
+ search,
+ routes,
+}: {
+ pathname: string;
+ search: string;
+ routes: ResolvedRoutes;
+}): RoutePlace | null {
+ const matched = matchPath(pathname, routes);
+ if (matched == null || matched.type !== 'root') return matched;
+ const { agentId } = readSessionShareSearch(search);
+ return agentId != null ? { type: 'libraryAgent', agentId } : matched;
+}
+
export function placesEqual(a: RoutePlace, b: RoutePlace): boolean {
if (a.type !== b.type) return false;
if (a.type === 'agent' && b.type === 'agent') return a.agentName === b.agentName;
+ if (a.type === 'libraryAgent' && b.type === 'libraryAgent') return a.agentId === b.agentId;
if (a.type === 'session' && b.type === 'session') return a.sessionId === b.sessionId;
return true;
}
diff --git a/packages/trueforge-ui/src/routing/types.ts b/packages/trueforge-ui/src/routing/types.ts
index d2c1b9235..0d1e01a0b 100644
--- a/packages/trueforge-ui/src/routing/types.ts
+++ b/packages/trueforge-ui/src/routing/types.ts
@@ -8,7 +8,10 @@ export type RoutePlace =
| { type: 'root' }
| { type: 'agent'; agentName: string }
| { type: 'session'; sessionId: string }
- | { type: 'settings' };
+ | { type: 'settings' }
+ | { type: 'library' }
+ | { type: 'libraryAgent'; agentId: string }
+ | { type: 'sessionsBrowser' };
/**
* Host-facing route path customization. Only honored when `withRouter`.
@@ -23,10 +26,16 @@ export type RoutesConfig = {
root?: string;
/** Settings overlay. `false` keeps settings overlay-only (no URL). Default `'/settings'`. */
settings?: string | false;
+ /** Agents Library overlay. `false` keeps library overlay-only (no URL). Default `'/library'`. */
+ library?: string | false;
+ /** Agent detail under the library. Default `'/library/:agentId'`. */
+ libraryAgent?: string | false;
/** Immutable "Try" agent. `false` disables. Default `'/agents/:agentName'`. */
agent?: string | false;
/** Session deep link. `false` disables. Default `'/sessions/:sessionId'`. */
session?: string | false;
+ /** All-user sessions browser. `false` disables. Default `'/sessions'`. */
+ sessionsBrowser?: string | false;
};
};
@@ -35,13 +44,19 @@ export type ResolvedRoutes = {
basename: string;
root: string;
settings: string | null;
+ library: string | null;
+ libraryAgent: string | null;
agent: string | null;
session: string | null;
+ sessionsBrowser: string | null;
};
/** Inputs for deriving the current place from shell + runtime state. */
export type ShellSnapshot = {
settingsOpen: boolean;
+ libraryOpen: boolean;
+ sessionsOpen: boolean;
+ libraryAgentId: string | null;
pendingSessionId?: string;
/** Remote id of the active thread once a fresh chat is persisted. */
activeRemoteId?: string;
diff --git a/packages/trueforge-ui/src/server/ServerContext.tsx b/packages/trueforge-ui/src/server/ServerContext.tsx
index cf643ba85..6b19b640b 100644
--- a/packages/trueforge-ui/src/server/ServerContext.tsx
+++ b/packages/trueforge-ui/src/server/ServerContext.tsx
@@ -2,7 +2,7 @@
import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
-import type { AgentBuilderCapabilitiesResponse, AgentUIServer, CatalogServer } from './types.js';
+import type { AgentBuilderCapabilitiesResponse, AgentSessionsServer, AgentUIServer, CatalogServer } from './types.js';
const ServerContext = createContext<AgentUIServer | null>(null);
const ServerCapabilitiesContext = createContext<{
@@ -80,3 +80,15 @@ export function useCatalogServer(): CatalogServer {
export function useOptionalCatalogServer(): CatalogServer | null {
return useOptionalServer()?.catalog ?? null;
}
+
+export function useAgentSessionsServer(): AgentSessionsServer {
+ const sessions = useServer().sessions;
+ if (sessions == null) {
+ throw new Error('useAgentSessionsServer requires AgentUIServer.sessions.');
+ }
+ return sessions;
+}
+
+export function useOptionalAgentSessionsServer(): AgentSessionsServer | null {
+ return useOptionalServer()?.sessions ?? null;
+}
diff --git a/packages/trueforge-ui/src/server/ShellModeContext.tsx b/packages/trueforge-ui/src/server/ShellModeContext.tsx
index 6012a0301..16ba02196 100644
--- a/packages/trueforge-ui/src/server/ShellModeContext.tsx
+++ b/packages/trueforge-ui/src/server/ShellModeContext.tsx
@@ -2,6 +2,7 @@
import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import { replaceSessionShareSearch } from '../utils/sessionShareUrl.js';
import {
readDraftSpecPreferences,
selectDraftSpecPreferences,
@@ -63,6 +64,16 @@ type ShellModeContextValue = {
settingsOpen: boolean;
settingsSection: SettingsSection;
setSettingsOpen: (open: boolean, section?: SettingsSection) => void;
+ /** Agents Library main-pane overlay (sidebar layout). */
+ libraryOpen: boolean;
+ libraryAgentId: string | null;
+ setLibraryAgentId: (id: string | null) => void;
+ setLibraryOpen: (open: boolean) => void;
+ /** All-user sessions browser (includes drafts). */
+ sessionsOpen: boolean;
+ setSessionsOpen: (open: boolean) => void;
+ openLibraryAgent: (agentId: string) => void;
+ closeLibraryAgent: () => void;
/**
* Bind from the Agents Library (Try = immutable, Edit = mutable + agentSpec).
* Prefer this over `selectAgent` / `openDraft` when both fields are available.
@@ -184,18 +195,63 @@ export function ShellModeProvider({
const [agentsListEpoch, setAgentsListEpoch] = useState(0);
const [settingsOpenState, setSettingsOpenState] = useState(initialSettingsOpen);
const [settingsSection, setSettingsSection] = useState<SettingsSection>('models');
+ const [libraryOpenState, setLibraryOpenState] = useState(false);
+ const [sessionsOpenState, setSessionsOpenState] = useState(false);
+ const [libraryAgentId, setLibraryAgentId] = useState<string | null>(null);
const [historyAgentFilter, setHistoryAgentFilter] = useState<string | null>(null);
const [pendingSessionId, setPendingSessionId] = useState<string | undefined>(undefined);
const settingsEnabled = capabilities?.settings?.enabled !== false;
const settingsOpen = settingsEnabled && settingsOpenState;
+ const libraryOpen = isLibraryEnabled && libraryOpenState;
+ const sessionsOpen = sessionsOpenState;
+ const setSessionsOpen = useCallback((open: boolean) => {
+ if (open) {
+ setSettingsOpenState(false);
+ setLibraryOpenState(false);
+ setLibraryAgentId(null);
+ } else {
+ replaceSessionShareSearch({ view: null });
+ }
+ setSessionsOpenState(open);
+ }, []);
+ const setLibraryOpen = useCallback(
+ (open: boolean) => {
+ if (!isLibraryEnabled) return;
+ if (open) {
+ setSettingsOpenState(false);
+ setSessionsOpen(false);
+ }
+ setLibraryAgentId(null);
+ setLibraryOpenState(open);
+ },
+ [isLibraryEnabled, setSessionsOpen],
+ );
+ const openLibraryAgent = useCallback(
+ (agentId: string) => {
+ if (!isLibraryEnabled) return;
+ setSettingsOpenState(false);
+ setSessionsOpen(false);
+ setLibraryOpenState(true);
+ setLibraryAgentId(agentId);
+ },
+ [isLibraryEnabled, setSessionsOpen],
+ );
+ const closeLibraryAgent = useCallback(() => {
+ setLibraryAgentId(null);
+ }, []);
const setSettingsOpen = useCallback(
(open: boolean, section?: SettingsSection) => {
if (section !== undefined) {
setSettingsSection(section);
}
+ if (open) {
+ setLibraryOpenState(false);
+ setLibraryAgentId(null);
+ setSessionsOpen(false);
+ }
setSettingsOpenState(settingsEnabled && open);
},
- [settingsEnabled],
+ [setSessionsOpen, settingsEnabled],
);
useEffect(() => {
@@ -236,6 +292,9 @@ export function ShellModeProvider({
if (req.isMutable) {
if (!isComposerEnabled) return;
setSettingsOpen(false);
+ setLibraryOpenState(false);
+ setLibraryAgentId(null);
+ setSessionsOpen(false);
setPendingSessionId(undefined);
setMode({
status: 'active',
@@ -252,6 +311,9 @@ export function ShellModeProvider({
const agentName = req.agentName ?? req.agentId;
if (agentName == null) return;
setSettingsOpen(false);
+ setLibraryOpenState(false);
+ setLibraryAgentId(null);
+ setSessionsOpen(false);
setPendingSessionId(undefined);
setMode({
status: 'active',
@@ -262,7 +324,7 @@ export function ShellModeProvider({
});
bumpEpoch(false);
},
- [isComposerEnabled, isLibraryEnabled, bumpEpoch, setSettingsOpen],
+ [isComposerEnabled, isLibraryEnabled, bumpEpoch, setSettingsOpen, setSessionsOpen],
);
const bindMutableAgent = useCallback(
@@ -318,6 +380,9 @@ export function ShellModeProvider({
isMutable?: boolean;
}) => {
setSettingsOpen(false);
+ setLibraryOpenState(false);
+ setLibraryAgentId(null);
+ setSessionsOpen(false);
setPendingSessionId(sessionId);
const isMutable = isMutableOpt ?? agentName == null;
if (isMutable) {
@@ -345,7 +410,7 @@ export function ShellModeProvider({
});
bumpEpoch(false);
},
- [isLibraryEnabled, isComposerEnabled, locked, lockedAgentName, bumpEpoch, setSettingsOpen],
+ [isLibraryEnabled, isComposerEnabled, locked, lockedAgentName, bumpEpoch, setSettingsOpen, setSessionsOpen],
);
const clearChat = useCallback(() => {
@@ -372,6 +437,8 @@ export function ShellModeProvider({
if (!isLibraryEnabled || isComposerEnabled) return;
setPendingSessionId(undefined);
setSettingsOpen(false);
+ setLibraryOpenState(false);
+ setLibraryAgentId(null);
setMode({ status: 'idle' });
bumpEpoch(false);
}, [isLibraryEnabled, isComposerEnabled, setSettingsOpen, bumpEpoch]);
@@ -397,6 +464,14 @@ export function ShellModeProvider({
settingsOpen,
settingsSection,
setSettingsOpen,
+ libraryOpen,
+ libraryAgentId,
+ setLibraryAgentId,
+ setLibraryOpen,
+ sessionsOpen,
+ setSessionsOpen,
+ openLibraryAgent,
+ closeLibraryAgent,
selectLibraryAgent,
bindMutableAgent,
selectAgent,
@@ -422,6 +497,13 @@ export function ShellModeProvider({
settingsOpen,
settingsSection,
setSettingsOpen,
+ libraryOpen,
+ libraryAgentId,
+ setLibraryOpen,
+ sessionsOpen,
+ setSessionsOpen,
+ openLibraryAgent,
+ closeLibraryAgent,
selectLibraryAgent,
bindMutableAgent,
selectAgent,
diff --git a/packages/trueforge-ui/src/server/createTrueFoundryServer.ts b/packages/trueforge-ui/src/server/createTrueFoundryServer.ts
index 96d192f32..14fe8c24a 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,
+ AgentSessionsServer,
AgentSkill,
AgentSpec,
CatalogServer,
@@ -22,6 +23,7 @@ export type CreateTrueFoundryServerOptions<
TSave extends SaveAgentResult = SaveAgentResult,
TCatalog extends CatalogServer = CatalogServer,
TCapabilities extends AgentBuilderCapabilitiesResponse = AgentBuilderCapabilitiesResponse,
+ TSessions extends AgentSessionsServer<TSpec> = AgentSessionsServer<TSpec>,
> = {
/** Chat port — e.g. from `@truefoundry/agent-server-adapter`. */
chatServer: AgentChatServer<TSpec>;
@@ -34,6 +36,8 @@ export type CreateTrueFoundryServerOptions<
deleteAgent?: (req: { agentName: string }) => Promise<void>;
/** Settings catalog (models + connectors). Optional. */
catalog?: TCatalog;
+ /** Optional agent-detail port (Overview + Use In Code). */
+ sessions?: TSessions;
};
export type TrueFoundryServer<
@@ -45,9 +49,11 @@ export type TrueFoundryServer<
TSave extends SaveAgentResult = SaveAgentResult,
TCatalog extends CatalogServer = CatalogServer,
TCapabilities extends AgentBuilderCapabilitiesResponse = AgentBuilderCapabilitiesResponse,
+ TSessions extends AgentSessionsServer<TSpec> = AgentSessionsServer<TSpec>,
> = AgentChatServer<TSpec> &
AgentBuilderServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCapabilities> & {
catalog?: TCatalog;
+ sessions?: TSessions;
};
/**
@@ -64,9 +70,10 @@ export function createTrueFoundryServer<
TSave extends SaveAgentResult = SaveAgentResult,
TCatalog extends CatalogServer = CatalogServer,
TCapabilities extends AgentBuilderCapabilitiesResponse = AgentBuilderCapabilitiesResponse,
+ TSessions extends AgentSessionsServer<TSpec> = AgentSessionsServer<TSpec>,
>(
- opts: CreateTrueFoundryServerOptions<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCatalog, TCapabilities>,
-): TrueFoundryServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCatalog, TCapabilities> {
+ opts: CreateTrueFoundryServerOptions<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCatalog, TCapabilities, TSessions>,
+): TrueFoundryServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCatalog, TCapabilities, TSessions> {
const builder: AgentBuilderServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCapabilities> = {
getCapabilities: opts.getCapabilities,
getModels: opts.getModels,
@@ -83,10 +90,11 @@ export function createTrueFoundryServer<
},
};
- const server: TrueFoundryServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCatalog, TCapabilities> = {
+ const server: TrueFoundryServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCatalog, TCapabilities, TSessions> = {
...opts.chatServer,
...builder,
...(opts.catalog != null ? { catalog: opts.catalog } : {}),
+ ...(opts.sessions != null ? { sessions: opts.sessions } : {}),
};
return server;
}
diff --git a/packages/trueforge-ui/src/server/types.ts b/packages/trueforge-ui/src/server/types.ts
index d4b5ba2d7..0cf0658a9 100644
--- a/packages/trueforge-ui/src/server/types.ts
+++ b/packages/trueforge-ui/src/server/types.ts
@@ -12,14 +12,18 @@ export type {
AgentBuilderServer,
AgentCapabilityConfig,
AgentChatServer,
+ AgentDetail,
AgentLibraryEntry,
AgentRuntimeConfig,
+ AgentSessionsServer,
AgentSkill,
AgentSpec,
AgentUIServer,
ApprovalDecision,
AuthenticateConnectorRequest,
CatalogServer,
+ CodeSnippet,
+ CodeSnippetSampleCode,
ConnectorAuth,
ConnectorAuthApiKey,
ConnectorAuthNone,
@@ -45,6 +49,7 @@ export type {
GithubSkill,
ImportGithubSkillRequest,
ListResult,
+ ListSessionEventsParams,
ListSessionsOrder,
ListSessionsParams,
McpServerMount,
@@ -75,6 +80,8 @@ export type {
SelectRegistrySkillRequest,
Session,
SessionEventItem,
+ SessionListEntry,
+ SessionListMetrics,
SkillBase,
SkillCatalogEntry,
SkillCatalogServer,
@@ -82,6 +89,7 @@ export type {
SkillMount,
ToolBase,
Turn,
+ TurnDoneMetrics,
TurnInputItem,
TurnState,
TurnStreamData,
diff --git a/packages/trueforge-ui/src/theme/defaultSlots.ts b/packages/trueforge-ui/src/theme/defaultSlots.ts
index e3a9f07c1..dd15c9629 100644
--- a/packages/trueforge-ui/src/theme/defaultSlots.ts
+++ b/packages/trueforge-ui/src/theme/defaultSlots.ts
@@ -1,3 +1,4 @@
+import { lazy, type ComponentType } from 'react';
import { Accordion, AccordionDetails, AccordionSummary } from '../atoms/primitives/Accordion.js';
import { AgentStepsCard } from '../atoms/adapters/AgentStepsCardAdapter.js';
@@ -6,7 +7,26 @@ import { McpAuthPrompt } from '../atoms/adapters/McpAuthPromptAdapter.js';
import { ReasoningCard } from '../atoms/adapters/ReasoningCardAdapter.js';
import { ResumeUnavailable } from '../atoms/ResumeUnavailable.js';
-import { AgentsLibrary } from '../atoms/AgentsLibrary.js';
+import { AgentCodeBlock } from '../atoms/agent-details/AgentCodeBlock.js';
+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 { AgentOverviewCard } from '../atoms/agent-details/AgentOverviewCard.js';
+import { AgentSessionDetailHeader } from '../atoms/agent-details/AgentSessionDetailHeader.js';
+import { AgentSessionListRow } from '../atoms/agent-details/AgentSessionListRow.js';
+import { AgentSessionMetricsStrip } from '../atoms/agent-details/AgentSessionMetricsStrip.js';
+import { AgentSessionsFilters } from '../atoms/agent-details/AgentSessionsFilters.js';
+import { AgentSessionTurnHeader } from '../atoms/agent-details/AgentSessionTurnHeader.js';
+import { SessionsPage } from '../atoms/agent-details/SessionsPage.js';
+import type {
+ AgentCodeSnippetsProps,
+ AgentOverviewProps,
+ AgentSessionEventTimelineChartProps,
+ AgentSessionEventTimelineProps,
+ AgentSessionsProps,
+} from '../atoms/agent-details/types.js';
+import { AgentLibraryRow, AgentsLibrary } from '../atoms/AgentsLibrary.js';
import { AgentsLibraryButton } from '../atoms/AgentsLibraryButton.js';
import { AssistantMessageBubble } from '../atoms/AssistantMessageBubble.js';
import { AttachmentCard } from '../atoms/AttachmentCard.js';
@@ -33,6 +53,7 @@ import { SandboxToolCallCard } from '../atoms/SandboxToolCallCard.js';
import { SaveAgentButton } from '../atoms/SaveAgentButton.js';
import { ScrollToBottomButton } from '../atoms/ScrollToBottomButton.js';
import { SelectAgentEmptyState } from '../atoms/SelectAgentEmptyState.js';
+import { SessionsBrowserButton } from '../atoms/SessionsBrowserButton.js';
import { ShellActionsActionSlot } from '../atoms/ShellActionsActionSlot.js';
import { MessageListSkeleton } from '../atoms/Skeletons.js';
import { SubAgentCard } from '../atoms/SubAgentCard.js';
@@ -54,9 +75,27 @@ 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 { AgentSessionTimelineContainer } from '../containers/AgentSessionTimelineContainer.js';
import { BrandLogo } from './brand.js';
import type { AtomSlots } from './SlotsProvider.js';
+const AgentOverview: ComponentType<AgentOverviewProps> = lazy(() => import('../atoms/agent-details/AgentOverview.js'));
+const AgentSessions: ComponentType<AgentSessionsProps> = lazy(async () => {
+ const mod = await import('../atoms/agent-details/AgentSessions.js');
+ return { default: mod.AgentSessions };
+});
+const AgentCodeSnippets: ComponentType<AgentCodeSnippetsProps> = lazy(
+ () => import('../atoms/agent-details/AgentCodeSnippets.js'),
+);
+const AgentSessionEventTimeline: ComponentType<AgentSessionEventTimelineProps> = lazy(async () => {
+ const mod = await import('../atoms/agent-details/AgentSessionEventTimeline.js');
+ return { default: mod.AgentSessionEventTimeline };
+});
+const AgentSessionEventTimelineChart: ComponentType<AgentSessionEventTimelineChartProps> = lazy(async () => {
+ const mod = await import('../atoms/agent-details/AgentSessionEventTimelineChart.js');
+ return { default: mod.AgentSessionEventTimelineChart };
+});
+
// ponytail: primitives stay CSS/token-styled (not slots) — see docs/customization.md.
// import { Button } from "../atoms/primitives/Button.js";
// import { Dialog, Modal } from "../atoms/primitives/Dialog.js";
@@ -113,7 +152,27 @@ export const defaultSlots = {
ThreadListRow,
ThreadListNewButton,
AgentsLibrary,
+ AgentLibraryRow,
AgentsLibraryButton,
+ SessionsBrowserButton,
+ AgentDetailsPage,
+ AgentDetailsHeader,
+ AgentDetailsTabs,
+ AgentDetailsUnavailable,
+ AgentOverview,
+ AgentOverviewCard,
+ AgentSessionDetailHeader,
+ AgentSessionsFilters,
+ SessionsPage,
+ AgentSessionEventTimeline,
+ AgentSessionEventTimelineChart,
+ AgentSessionListRow,
+ AgentSessionMetricsStrip,
+ AgentSessionTimelineContainer,
+ AgentSessionTurnHeader,
+ AgentSessions,
+ AgentCodeSnippets,
+ AgentCodeBlock,
SaveAgentButton,
SelectAgentEmptyState,
ClearChatButton,
diff --git a/packages/trueforge-ui/src/utils/buildSessionMetrics.ts b/packages/trueforge-ui/src/utils/buildSessionMetrics.ts
new file mode 100644
index 000000000..cee6a3a80
--- /dev/null
+++ b/packages/trueforge-ui/src/utils/buildSessionMetrics.ts
@@ -0,0 +1,150 @@
+import { getSessionEventColor, type SessionEventTimelineSegment } from './sessionEventTimeline.js';
+import { isRecord } from './sessionTimelineEvents.js';
+import type { SessionTurnView } from './sessionTurnViews.js';
+
+export type SessionMetricBarDatum = {
+ label: string;
+ value: number;
+ color: string;
+};
+
+export type SessionMetrics = {
+ totalTurns: number;
+ wallTimeMs: number;
+ totalCostUsd: number;
+ totalTokens: number;
+ contextTokens: number;
+ toolCalls: number;
+ subAgents: number;
+ errors: number;
+ timeBreakdown: SessionMetricBarDatum[];
+ costPerTurn: SessionMetricBarDatum[];
+ tokenBreakdown: SessionMetricBarDatum[];
+ contextByTurn: SessionMetricBarDatum[];
+ toolCallFrequency: SessionMetricBarDatum[];
+};
+
+export type SessionListMetricsHint = {
+ totalTurns: number;
+ totalCostInUsd: number;
+ totalDurationMs: number;
+};
+
+function readNumber(record: Record<string, unknown>, camel: string, snake: string): number {
+ const camelValue = record[camel];
+ if (typeof camelValue === 'number' && Number.isFinite(camelValue)) return camelValue;
+ const snakeValue = record[snake];
+ return typeof snakeValue === 'number' && Number.isFinite(snakeValue) ? snakeValue : 0;
+}
+
+function metricsRecord(state: unknown): Record<string, unknown> | undefined {
+ if (!isRecord(state)) return undefined;
+ return isRecord(state.metrics) ? state.metrics : undefined;
+}
+
+function segmentDurationMs(segment: SessionEventTimelineSegment): number {
+ return Math.max(0, segment.endMs - segment.startMs);
+}
+
+function hintHasValues(hint?: SessionListMetricsHint): boolean {
+ return hint != null && (hint.totalTurns > 0 || hint.totalCostInUsd > 0 || hint.totalDurationMs > 0);
+}
+
+export function buildSessionMetrics({
+ turns,
+ segments,
+ listMetrics,
+}: {
+ turns: SessionTurnView[];
+ segments: SessionEventTimelineSegment[];
+ listMetrics?: SessionListMetricsHint;
+}): SessionMetrics {
+ let derivedWallTimeMs = 0;
+ let derivedCostUsd = 0;
+ let totalTokens = 0;
+ let totalUncachedInputTokens = 0;
+ let totalOutputTokens = 0;
+ let totalCachedTokens = 0;
+ let contextTokens = 0;
+ const costPerTurn: SessionMetricBarDatum[] = [];
+ const contextByTurn: SessionMetricBarDatum[] = [];
+
+ for (const turn of turns) {
+ const label = `T${turn.turnNumber}`;
+ derivedWallTimeMs += turn.durationMs ?? 0;
+ const metrics = metricsRecord(turn.done?.state);
+ if (metrics == null) {
+ costPerTurn.push({ label, value: 0, color: getSessionEventColor('tool_call') });
+ contextByTurn.push({ label, value: contextTokens, color: getSessionEventColor('model') });
+ continue;
+ }
+
+ const inputTokens = readNumber(metrics, 'totalInputTokens', 'total_input_tokens');
+ const outputTokens = readNumber(metrics, 'totalOutputTokens', 'total_output_tokens');
+ const cachedTokens =
+ readNumber(metrics, 'totalCacheReadTokens', 'total_cache_read_tokens') +
+ readNumber(metrics, 'totalCacheWriteTokens', 'total_cache_write_tokens');
+ const uncachedInputTokens = Math.max(0, inputTokens - cachedTokens);
+ const turnTotalTokens = readNumber(metrics, 'totalTokens', 'total_tokens') || inputTokens + outputTokens;
+ const turnCostUsd = readNumber(metrics, 'totalCostInUsd', 'total_cost_in_usd');
+
+ derivedCostUsd += turnCostUsd;
+ totalTokens += turnTotalTokens;
+ totalUncachedInputTokens += uncachedInputTokens;
+ totalOutputTokens += outputTokens;
+ totalCachedTokens += cachedTokens;
+ contextTokens += turnTotalTokens;
+ costPerTurn.push({ label, value: turnCostUsd, color: getSessionEventColor('tool_call') });
+ contextByTurn.push({ label, value: contextTokens, color: getSessionEventColor('model') });
+ }
+
+ const modelTimeMs = segments
+ .filter(segment => segment.type === 'model')
+ .reduce((sum, segment) => sum + segmentDurationMs(segment), 0);
+ const toolTimeMs = segments
+ .filter(segment => segment.type === 'tool_call')
+ .reduce((sum, segment) => sum + segmentDurationMs(segment), 0);
+ const waitingTimeMs = segments
+ .filter(segment => segment.type === 'waiting_on_human' || segment.type === 'approval')
+ .reduce((sum, segment) => sum + segmentDurationMs(segment), 0);
+ const wallTimeMs = hintHasValues(listMetrics)
+ ? (listMetrics?.totalDurationMs ?? derivedWallTimeMs)
+ : derivedWallTimeMs;
+ const overheadTimeMs = Math.max(0, wallTimeMs - modelTimeMs - toolTimeMs - waitingTimeMs);
+
+ const toolCallCounts = new Map<string, number>();
+ for (const segment of segments) {
+ if (segment.type !== 'tool_call') continue;
+ toolCallCounts.set(segment.description, (toolCallCounts.get(segment.description) ?? 0) + 1);
+ }
+ const toolCallFrequency = Array.from(toolCallCounts, ([label, value]) => ({
+ label,
+ value,
+ color: getSessionEventColor('tool_call'),
+ })).sort((left, right) => right.value - left.value);
+
+ return {
+ totalTurns: hintHasValues(listMetrics) ? (listMetrics?.totalTurns ?? turns.length) : turns.length,
+ wallTimeMs,
+ totalCostUsd: hintHasValues(listMetrics) ? (listMetrics?.totalCostInUsd ?? derivedCostUsd) : derivedCostUsd,
+ totalTokens,
+ contextTokens,
+ toolCalls: toolCallFrequency.reduce((sum, toolCall) => sum + toolCall.value, 0),
+ subAgents: segments.filter(segment => segment.type === 'sub_agent').length,
+ errors: segments.filter(segment => segment.type === 'error').length,
+ timeBreakdown: [
+ { label: 'model', value: modelTimeMs, color: getSessionEventColor('model') },
+ { label: 'tools', value: toolTimeMs, color: getSessionEventColor('tool_call') },
+ { label: 'waiting on human', value: waitingTimeMs, color: getSessionEventColor('approval') },
+ { label: 'overhead', value: overheadTimeMs, color: getSessionEventColor('system') },
+ ],
+ costPerTurn,
+ tokenBreakdown: [
+ { label: 'input', value: totalUncachedInputTokens, color: getSessionEventColor('model') },
+ { label: 'output', value: totalOutputTokens, color: getSessionEventColor('user') },
+ { label: 'cached', value: totalCachedTokens, color: getSessionEventColor('sub_agent') },
+ ],
+ contextByTurn,
+ toolCallFrequency,
+ };
+}
diff --git a/packages/trueforge-ui/src/utils/buildSessionTimelineSegments.ts b/packages/trueforge-ui/src/utils/buildSessionTimelineSegments.ts
new file mode 100644
index 000000000..5dfc04b02
--- /dev/null
+++ b/packages/trueforge-ui/src/utils/buildSessionTimelineSegments.ts
@@ -0,0 +1,330 @@
+import { MAIN_THREAD_ID, type SessionEventTimelineSegment } from './sessionEventTimeline.js';
+import { compressInterTurnGaps } from './sessionEventTimelineChart.js';
+import {
+ asTimelineEvent,
+ eventCreatedAt,
+ eventId,
+ eventThreadId,
+ extractText,
+ getSubAgentDescription,
+ getTurnInputSummary,
+ getTurnInputType,
+ parentToolCallId,
+ parseTimestamp,
+ readString,
+ terminalCompletedAt,
+ terminalMessage,
+ terminalStatus,
+ toolCallDescription,
+ toolCallsOf,
+ type TimelineEvent,
+} from './sessionTimelineEvents.js';
+import type { SessionTurnView } from './sessionTurnViews.js';
+
+/**
+ * Convert server turns and events into the transport-independent intervals
+ * consumed by the Sessions timeline.
+ *
+ * The conversion runs in two passes because several bars need a later event
+ * to determine their end:
+ * - tool calls span from the model event that requested them to `tool.response`;
+ * - sub-agent tracks span from `thread.created` to `thread.done`;
+ * - approval-gated and sub-agent parent calls are excluded from ordinary tool
+ * bars because they have dedicated visual representations.
+ *
+ * The second pass emits one user marker per turn, then chronological event
+ * segments for each thread. Finally, real idle gaps between turns are removed
+ * so old sessions remain readable without changing durations inside a turn.
+ */
+export function buildSessionTimelineSegments(turns: SessionTurnView[]): SessionEventTimelineSegment[] {
+ const originMs = parseTimestamp(turns[0]?.created.createdAt);
+ if (originMs == null) return [];
+
+ // Correlation indexes built up front let the emission pass calculate complete
+ // intervals without depending on the source event order.
+ const toolResponsesByTurnId = new Map<string, Map<string, TimelineEvent>>();
+ const approvalRequiredIdsByTurnId = new Map<string, Set<string>>();
+ const threadDoneEvents = new Map<string, TimelineEvent>();
+ const subAgentToolCallIds = new Set<string>();
+ let latestMs = originMs;
+
+ for (const turn of turns) {
+ latestMs = Math.max(latestMs, parseTimestamp(turn.created.createdAt) ?? latestMs);
+ latestMs = Math.max(latestMs, parseTimestamp(terminalCompletedAt(turn.done?.state)) ?? latestMs);
+ for (const raw of turn.events) {
+ const event = asTimelineEvent(raw);
+ if (event == null) continue;
+ latestMs = Math.max(latestMs, parseTimestamp(eventCreatedAt(event)) ?? latestMs);
+ if (event.type === 'tool.response') {
+ const toolCallId = readString(event, 'toolCallId', 'tool_call_id');
+ if (toolCallId == null) continue;
+ const responses = toolResponsesByTurnId.get(turn.turnId) ?? new Map();
+ responses.set(toolCallId, event);
+ toolResponsesByTurnId.set(turn.turnId, responses);
+ } else if (event.type === 'tool.approval_required') {
+ const ids = approvalRequiredIdsByTurnId.get(turn.turnId) ?? new Set<string>();
+ for (const toolCall of toolCallsOf(event)) {
+ if (typeof toolCall.id === 'string') ids.add(toolCall.id);
+ }
+ approvalRequiredIdsByTurnId.set(turn.turnId, ids);
+ } else if (event.type === 'thread.created') {
+ const toolCallId = parentToolCallId(event);
+ if (toolCallId != null) subAgentToolCallIds.add(toolCallId);
+ } else if (event.type === 'thread.done') {
+ threadDoneEvents.set(eventThreadId(event), event);
+ }
+ }
+ }
+
+ const segments: SessionEventTimelineSegment[] = [];
+
+ for (const turn of turns) {
+ const createdMs = parseTimestamp(turn.created.createdAt);
+ if (createdMs == null) continue;
+ const turnIndex = turn.turnNumber - 1;
+
+ segments.push({
+ id: `${turn.turnId}-user`,
+ type: 'user',
+ title: getTurnInputType(turn),
+ description: getTurnInputSummary(turn),
+ startMs: createdMs - originMs,
+ endMs: createdMs - originMs,
+ turnIndex,
+ threadId: MAIN_THREAD_ID,
+ isMarker: true,
+ });
+
+ // Model intervals are independent per thread. Using one global previous
+ // timestamp would make concurrent sub-agent bars consume each other's time.
+ const lastTimestampByThreadId = new Map<string, number>();
+ const events = [...turn.events]
+ .map(asTimelineEvent)
+ .filter((event): event is TimelineEvent => event != null)
+ .sort(
+ (left, right) => (parseTimestamp(eventCreatedAt(left)) ?? 0) - (parseTimestamp(eventCreatedAt(right)) ?? 0),
+ );
+
+ for (const event of events) {
+ const eventMs = parseTimestamp(eventCreatedAt(event));
+ if (eventMs == null) continue;
+ const threadId = eventThreadId(event);
+ appendEventSegments({
+ event,
+ eventMs,
+ createdMs,
+ originMs,
+ turn,
+ turnIndex,
+ threadId,
+ lastTimestampByThreadId,
+ toolResponsesByTurnId,
+ approvalRequiredIdsByTurnId,
+ subAgentToolCallIds,
+ threadDoneEvents,
+ segments,
+ });
+ lastTimestampByThreadId.set(threadId, eventMs);
+ }
+
+ appendTerminalSegment({ turn, turnIndex, originMs, latestMs, segments });
+ }
+
+ return compressInterTurnGaps(
+ segments.map(segment => ({
+ ...segment,
+ startMs: Math.max(0, segment.startMs),
+ endMs: Math.max(0, segment.endMs),
+ })),
+ ).sort((left, right) => left.startMs - right.startMs || left.endMs - right.endMs);
+}
+
+/**
+ * Map one supported server event to zero or more visual segments.
+ *
+ * New event types should be added here
+ * when they have a clear visual category and useful timing semantics.
+ */
+function appendEventSegments({
+ event,
+ eventMs,
+ createdMs,
+ originMs,
+ turn,
+ turnIndex,
+ threadId,
+ lastTimestampByThreadId,
+ toolResponsesByTurnId,
+ approvalRequiredIdsByTurnId,
+ subAgentToolCallIds,
+ threadDoneEvents,
+ segments,
+}: {
+ event: TimelineEvent;
+ eventMs: number;
+ createdMs: number;
+ originMs: number;
+ turn: SessionTurnView;
+ turnIndex: number;
+ threadId: string;
+ lastTimestampByThreadId: Map<string, number>;
+ toolResponsesByTurnId: Map<string, Map<string, TimelineEvent>>;
+ approvalRequiredIdsByTurnId: Map<string, Set<string>>;
+ subAgentToolCallIds: Set<string>;
+ threadDoneEvents: Map<string, TimelineEvent>;
+ segments: SessionEventTimelineSegment[];
+}): void {
+ switch (event.type) {
+ case 'model.message': {
+ const previousMs = lastTimestampByThreadId.get(threadId) ?? createdMs;
+ const modelContent = extractText(event.content);
+ const responses = toolResponsesByTurnId.get(turn.turnId);
+ const approvalIds = approvalRequiredIdsByTurnId.get(turn.turnId);
+
+ // A model event can request several tools at once. Each tool gets its own
+ // response-bounded interval; overlapping intervals are grouped later by
+ // the chart-layout utility into one parallel-tool-call bar.
+ for (const toolCall of toolCallsOf(event)) {
+ const toolCallId = typeof toolCall.id === 'string' ? toolCall.id : undefined;
+ // Skip parent create_sub_agent calls and approval-gated calls; they have their own segments.
+ if (toolCallId == null || subAgentToolCallIds.has(toolCallId) || approvalIds?.has(toolCallId)) continue;
+ const response = responses?.get(toolCallId);
+ const responseMs = response == null ? null : parseTimestamp(eventCreatedAt(response));
+ if (responseMs == null || responseMs < eventMs) continue;
+ segments.push({
+ id: `${eventId(event)}-${toolCallId}`,
+ type: 'tool_call',
+ title: 'tool.call',
+ description: toolCallDescription(toolCall),
+ startMs: eventMs - originMs,
+ endMs: responseMs - originMs,
+ turnIndex,
+ threadId,
+ });
+ }
+
+ // The model bar covers processing since the previous event on this thread.
+ // Keep an empty root model segment because it may still contain tool calls
+ // and therefore represents real model time.
+ if (modelContent.length > 0 || threadId === MAIN_THREAD_ID) {
+ segments.push({
+ id: eventId(event),
+ type: 'model',
+ title: event.type,
+ description: modelContent,
+ startMs: Math.max(0, previousMs - originMs),
+ endMs: Math.max(0, eventMs - originMs),
+ turnIndex,
+ threadId,
+ isMarker: eventMs <= previousMs,
+ });
+ }
+ return;
+ }
+ case 'thread.created': {
+ // The parent call is represented by this track, while child events are
+ // assigned to the same thread id and rendered on the track's lane.
+ const doneEvent = threadDoneEvents.get(threadId);
+ const doneMs = doneEvent == null ? null : parseTimestamp(eventCreatedAt(doneEvent));
+ segments.push({
+ id: eventId(event),
+ type: 'sub_agent',
+ title: event.type,
+ description: getSubAgentDescription(event),
+ startMs: eventMs - originMs,
+ endMs: doneMs != null && doneMs >= eventMs ? doneMs - originMs : eventMs - originMs,
+ turnIndex,
+ threadId,
+ isMarker: doneMs == null || doneMs < eventMs,
+ });
+ return;
+ }
+ case 'tool.approval_required':
+ case 'tool.response_required':
+ case 'mcp.auth_required':
+ case 'mcp.initialize':
+ case 'sandbox.created':
+ // These are point-in-time state transitions, so start and end are equal
+ // and Chart.js renders them with the configured minimum marker width.
+ segments.push({
+ id: eventId(event),
+ type:
+ event.type === 'tool.approval_required'
+ ? 'approval'
+ : event.type === 'tool.response_required' || event.type === 'mcp.auth_required'
+ ? 'waiting_on_human'
+ : 'system',
+ title: event.type,
+ description:
+ event.type === 'tool.approval_required'
+ ? 'Approval required'
+ : event.type === 'tool.response_required'
+ ? 'Waiting for user response'
+ : event.type === 'mcp.auth_required'
+ ? 'MCP authentication required'
+ : event.type === 'mcp.initialize'
+ ? 'MCP initialized'
+ : 'Sandbox created',
+ startMs: eventMs - originMs,
+ endMs: eventMs - originMs,
+ turnIndex,
+ threadId,
+ isMarker: true,
+ });
+ return;
+ default:
+ return;
+ }
+}
+
+/**
+ * Add the terminal marker that closes a turn.
+ *
+ * Errors use the latest observed timestamp when the backend omitted
+ * `completed_at`, ensuring failures remain visible instead of being dropped.
+ * Running/paused turns have no terminal marker because they have not ended.
+ */
+function appendTerminalSegment({
+ turn,
+ turnIndex,
+ originMs,
+ latestMs,
+ segments,
+}: {
+ turn: SessionTurnView;
+ turnIndex: number;
+ originMs: number;
+ latestMs: number;
+ segments: SessionEventTimelineSegment[];
+}): void {
+ const status = terminalStatus(turn.done?.state);
+ if (status === 'error') {
+ const errorMs = parseTimestamp(terminalCompletedAt(turn.done?.state)) ?? latestMs;
+ segments.push({
+ id: `${turn.turnId}-error`,
+ type: 'error',
+ title: 'turn.error',
+ description: terminalMessage(turn.done?.state),
+ startMs: errorMs - originMs,
+ endMs: errorMs - originMs,
+ turnIndex,
+ threadId: MAIN_THREAD_ID,
+ isMarker: true,
+ });
+ return;
+ }
+ if (status !== 'done') return;
+ const doneMs = parseTimestamp(terminalCompletedAt(turn.done?.state));
+ if (doneMs == null) return;
+ segments.push({
+ id: `${turn.turnId}-turn.done`,
+ type: 'system',
+ title: 'turn.done',
+ description: 'Turn completed',
+ startMs: doneMs - originMs,
+ endMs: doneMs - originMs,
+ turnIndex,
+ threadId: MAIN_THREAD_ID,
+ isMarker: true,
+ });
+}
diff --git a/packages/trueforge-ui/src/utils/cachedListEventsBridge.ts b/packages/trueforge-ui/src/utils/cachedListEventsBridge.ts
new file mode 100644
index 000000000..1e1871827
--- /dev/null
+++ b/packages/trueforge-ui/src/utils/cachedListEventsBridge.ts
@@ -0,0 +1,20 @@
+import type { AgentChatServer, ListResult, SessionEventItem } from '../server/types.js';
+
+const DEFAULT_PAGE_SIZE = 100;
+
+/** Serve preloaded session events through `AgentChatServer.listEvents` pagination. */
+export function createCachedListEventsBridge(itemsAsc: SessionEventItem[]): Pick<AgentChatServer, 'listEvents'> {
+ const itemsNewestFirst = [...itemsAsc].reverse();
+
+ return {
+ async listEvents({ limit = DEFAULT_PAGE_SIZE, pageToken }) {
+ const offset = pageToken == null || pageToken.length === 0 ? 0 : Number.parseInt(pageToken, 10);
+ const start = Number.isFinite(offset) ? offset : 0;
+ const data = itemsNewestFirst.slice(start, start + limit);
+ const nextOffset = start + limit;
+ const nextPageToken = nextOffset < itemsNewestFirst.length ? String(nextOffset) : undefined;
+ const page: ListResult<SessionEventItem> = { data };
+ return nextPageToken == null ? page : { ...page, nextPageToken };
+ },
+ };
+}
diff --git a/packages/trueforge-ui/src/utils/drainListPages.ts b/packages/trueforge-ui/src/utils/drainListPages.ts
new file mode 100644
index 000000000..3557d4708
--- /dev/null
+++ b/packages/trueforge-ui/src/utils/drainListPages.ts
@@ -0,0 +1,17 @@
+import type { ListResult } from '../server/types.js';
+
+/** Drain token-paginated list endpoints until `nextPageToken` is exhausted. */
+export async function drainListPages<T>({
+ fetchPage,
+}: {
+ fetchPage: (pageToken?: string) => Promise<ListResult<T>>;
+}): Promise<T[]> {
+ const items: T[] = [];
+ let pageToken: string | undefined;
+ do {
+ const page = await fetchPage(pageToken);
+ items.push(...page.data);
+ pageToken = page.nextPageToken;
+ } while (pageToken != null && pageToken.length > 0);
+ return items;
+}
diff --git a/packages/trueforge-ui/src/utils/sessionDisplayFormat.ts b/packages/trueforge-ui/src/utils/sessionDisplayFormat.ts
new file mode 100644
index 000000000..3a723324f
--- /dev/null
+++ b/packages/trueforge-ui/src/utils/sessionDisplayFormat.ts
@@ -0,0 +1,34 @@
+/** Compact token count for session/turn headers (e.g. 122K). */
+export function formatTokenCount(tokens: number): string {
+ if (tokens >= 1_000_000) {
+ return `${(tokens / 1_000_000).toFixed(tokens >= 10_000_000 ? 0 : 1)}M`;
+ }
+ if (tokens >= 1_000) {
+ return `${(tokens / 1_000).toFixed(0)}K`;
+ }
+ return String(tokens);
+}
+
+/** USD cost with four decimal places (e.g. $0.1615). */
+export function formatCostUsd(costInUsd: number): string {
+ return `$${costInUsd.toFixed(4)}`;
+}
+
+/** Duration from milliseconds (e.g. 41.38s, 1.92m). */
+export function formatDurationMs(durationMs: number): string {
+ if (durationMs < 60_000) {
+ return `${(durationMs / 1_000).toFixed(2)}s`;
+ }
+ if (durationMs < 3_600_000) {
+ return `${(durationMs / 60_000).toFixed(2)}m`;
+ }
+ return `${(durationMs / 3_600_000).toFixed(2)}h`;
+}
+
+export function formatSessionListMetrics(metrics: {
+ totalTurns: number;
+ totalCostInUsd: number;
+ totalDurationMs: number;
+}): string {
+ return `${metrics.totalTurns} turns | ${formatCostUsd(metrics.totalCostInUsd)} | ${formatDurationMs(metrics.totalDurationMs)}`;
+}
diff --git a/packages/trueforge-ui/src/utils/sessionEventTimeline.ts b/packages/trueforge-ui/src/utils/sessionEventTimeline.ts
new file mode 100644
index 000000000..2a642f793
--- /dev/null
+++ b/packages/trueforge-ui/src/utils/sessionEventTimeline.ts
@@ -0,0 +1,102 @@
+/**
+ * Shared presentation model for the Sessions timeline.
+ *
+ * Raw server events are intentionally converted to this small, stable shape
+ * before they reach Chart.js. That keeps transport compatibility and event
+ * correlation out of the chart component and makes atoms easy to override.
+ */
+
+/** Events without a thread id belong to the root agent conversation. */
+export const MAIN_THREAD_ID = 'main';
+
+export type SessionEventType =
+ 'system' | 'user' | 'model' | 'tool_call' | 'approval' | 'sub_agent' | 'waiting_on_human' | 'error';
+
+export type SessionEventTypeDefinition = {
+ id: SessionEventType;
+ label: string;
+ color: string;
+};
+
+/**
+ * One drawable interval on the timeline.
+ *
+ * Times are milliseconds relative to the session origin, not wall-clock
+ * timestamps. Equal start/end times are rendered as markers; intervals become
+ * horizontal bars. `turnIndex` groups intervals into turn backgrounds and
+ * `threadId` assigns sub-agent work to its lane.
+ */
+export type SessionEventTimelineSegment = {
+ id: string;
+ type: SessionEventType;
+ title: string;
+ description: string;
+ startMs: number;
+ endMs: number;
+ turnIndex: number;
+ threadId: string;
+ isMarker?: boolean;
+};
+
+/** Canonical legend order, labels, and base colours for timeline event types. */
+export const SESSION_EVENT_TYPES: SessionEventTypeDefinition[] = [
+ { id: 'system', label: 'System', color: '#94a3b8' },
+ { id: 'user', label: 'User', color: '#34d399' },
+ { id: 'model', label: 'Model', color: '#3b82f6' },
+ { id: 'tool_call', label: 'Tool call', color: '#f59e0b' },
+ { id: 'approval', label: 'Approval / HITL', color: '#f472b6' },
+ { id: 'sub_agent', label: 'Sub-agent', color: '#c084fc' },
+ { id: 'waiting_on_human', label: 'Waiting on human', color: '#22d3ee' },
+ { id: 'error', label: 'Error', color: '#f87171' },
+];
+
+/** Marker-like events have no meaningful elapsed duration in their tooltip. */
+export const SESSION_EVENT_TOOLTIP_HIDE_DURATION = new Set<SessionEventType>(['system', 'user', 'error']);
+
+const TOOLTIP_HEADINGS: Partial<Record<SessionEventType, string>> = {
+ user: 'User Message',
+ model: 'Model Response',
+};
+
+/** Format an axis/tooltip duration compactly while retaining roughly three significant digits. */
+export function formatTimelineDuration(durationMs: number): string {
+ if (durationMs <= 0) return '0ms';
+ if (durationMs < 1_000) return `${Math.round(durationMs)}ms`;
+ if (durationMs < 60_000) return `${Number((durationMs / 1_000).toPrecision(3))}s`;
+ if (durationMs < 3_600_000) return `${Number((durationMs / 60_000).toPrecision(3))}m`;
+ return `${Number((durationMs / 3_600_000).toPrecision(3))}h`;
+}
+
+/** Resolve a segment's color from the same registry used to build the legend. */
+export function getSessionEventColor(type: SessionEventType): string {
+ return SESSION_EVENT_TYPES.find(eventType => eventType.id === type)?.color ?? '#94a3b8';
+}
+
+/** Darken the base color by 10% so hover remains recognizable in either theme. */
+export function getSessionEventHoverColor(type: SessionEventType): string {
+ const hex = getSessionEventColor(type).replace('#', '');
+ const normalized =
+ hex.length === 3
+ ? hex
+ .split('')
+ .map(char => `${char}${char}`)
+ .join('')
+ : hex;
+ if (normalized.length !== 6) return getSessionEventColor(type);
+ const value = Number.parseInt(normalized, 16);
+ const channel = (shift: number) =>
+ Math.max(0, Math.round(((value >> shift) & 255) * 0.9))
+ .toString(16)
+ .padStart(2, '0');
+ return `#${channel(16)}${channel(8)}${channel(0)}`;
+}
+
+/** Return the contributor-facing label shown in the event-type filter and dataset metadata. */
+export function getSessionEventLabel(type: SessionEventType): string {
+ return SESSION_EVENT_TYPES.find(eventType => eventType.id === type)?.label ?? type;
+}
+
+/** Use message-specific tooltip headings while falling back to the legend label. */
+export function getSessionEventTooltipHeading(type: SessionEventType): string {
+ return TOOLTIP_HEADINGS[type] ?? getSessionEventLabel(type);
+}
diff --git a/packages/trueforge-ui/src/utils/sessionEventTimelineChart.ts b/packages/trueforge-ui/src/utils/sessionEventTimelineChart.ts
new file mode 100644
index 000000000..88a4e738c
--- /dev/null
+++ b/packages/trueforge-ui/src/utils/sessionEventTimelineChart.ts
@@ -0,0 +1,275 @@
+import type { SessionEventTimelineSegment } from './sessionEventTimeline.js';
+
+/**
+ * Pure layout helpers for the Sessions timeline.
+ *
+ * Segment construction owns event meaning; this module owns visual grouping,
+ * lane allocation, and the compressed time axis. Keeping these calculations
+ * outside React/Chart.js makes the rendering rules deterministic and testable.
+ */
+
+/** Minimal interval shared by bars, compressed gaps, and grouped tool calls. */
+export type TimelineGap = {
+ startMs: number;
+ endMs: number;
+};
+
+export type TimelineTurnRange = {
+ turnIndex: number;
+ startMs: number;
+ endMs: number;
+ ordinal: number;
+};
+
+export type TimelineLayout = {
+ turnStartsMs: number[];
+ turnOrdinals: Map<number, number>;
+ turnRanges: TimelineTurnRange[];
+};
+
+export type TimelineTurnBar = TimelineTurnRange & {
+ id: string;
+ durationMs: number;
+};
+
+export type TimelineSubAgentBar = SessionEventTimelineSegment & {
+ lane: number;
+ visualEndMs: number;
+};
+
+export type TimelineSubAgentLane = {
+ threadId: string;
+ lane: number;
+ track: TimelineSubAgentBar;
+ segments: SessionEventTimelineSegment[];
+};
+
+export type TimelineToolCallGroup = TimelineGap & {
+ id: string;
+ segments: SessionEventTimelineSegment[];
+};
+
+export const TIMELINE_TYPE = {
+ turn: 'turn',
+ event: 'event',
+ toolCallGroup: 'toolCallGroup',
+} as const;
+
+export type TimelineHoverTarget =
+ | { type: typeof TIMELINE_TYPE.turn; bar: TimelineTurnBar }
+ | { type: typeof TIMELINE_TYPE.event; segment: SessionEventTimelineSegment }
+ | { type: typeof TIMELINE_TYPE.toolCallGroup; group: TimelineToolCallGroup };
+
+/** Stable identity used to avoid replacing tooltip state while hovering the same bar. */
+export function getTimelineHoverTargetId(target: TimelineHoverTarget | null): string {
+ if (target == null) return '';
+ if (target.type === TIMELINE_TYPE.turn) return target.bar.id;
+ if (target.type === TIMELINE_TYPE.event) return target.segment.id;
+ return target.group.id;
+}
+
+/** Convert an interval to Chart.js's floating horizontal-bar data shape. */
+export function getTimelineRange({ startMs, endMs }: TimelineGap): [number, number] {
+ return [startMs, endMs];
+}
+
+/**
+ * Derive one background range per turn from all of that turn's segments.
+ *
+ * Turn numbers can be sparse after filtering or incomplete server data, so
+ * `ordinal` is a dense visual position while `turnIndex` remains the source id.
+ */
+export function getTimelineLayout(segments: SessionEventTimelineSegment[]): TimelineLayout {
+ const rangesByTurnIndex = new Map<number, TimelineGap>();
+
+ for (const segment of segments) {
+ const range = rangesByTurnIndex.get(segment.turnIndex);
+ if (range) {
+ range.startMs = Math.min(range.startMs, segment.startMs);
+ range.endMs = Math.max(range.endMs, segment.endMs);
+ } else {
+ rangesByTurnIndex.set(segment.turnIndex, { startMs: segment.startMs, endMs: segment.endMs });
+ }
+ }
+
+ const ranges = Array.from(rangesByTurnIndex.entries()).sort(([left], [right]) => left - right);
+ return {
+ turnStartsMs: ranges.map(([, range]) => range.startMs),
+ turnOrdinals: new Map(ranges.map(([turnIndex], ordinal) => [turnIndex, ordinal])),
+ turnRanges: ranges.map(([turnIndex, range], ordinal) => ({
+ turnIndex,
+ startMs: range.startMs,
+ endMs: range.endMs,
+ ordinal,
+ })),
+ };
+}
+
+/** Touching endpoints do not overlap, allowing adjacent bars to share a row. */
+function segmentsOverlap(left: SessionEventTimelineSegment, right: SessionEventTimelineSegment): boolean {
+ return left.startMs < right.endMs && right.startMs < left.endMs;
+}
+
+/**
+ * Select representative sub-agent tracks for the main event row.
+ *
+ * Longest-first selection preserves the tracks that explain the most elapsed
+ * time; overlapping tracks are still available in dedicated sub-agent lanes.
+ */
+export function pickLongestNonOverlappingSegments(
+ segments: SessionEventTimelineSegment[],
+): SessionEventTimelineSegment[] {
+ const selected: SessionEventTimelineSegment[] = [];
+ for (const segment of [...segments].sort((left, right) => {
+ const durationDiff = right.endMs - right.startMs - (left.endMs - left.startMs);
+ return durationDiff !== 0 ? durationDiff : left.startMs - right.startMs;
+ })) {
+ if (selected.some(kept => segmentsOverlap(kept, segment))) continue;
+ selected.push(segment);
+ }
+ return selected.sort((left, right) => left.startMs - right.startMs);
+}
+
+/**
+ * Merge transitively overlapping tool calls within the same turn and thread.
+ *
+ * Concurrent calls would otherwise draw on top of one another in the main
+ * event row. The merged bar spans the union and its tooltip lists every member.
+ * Calls from different turns/threads never merge even if timestamps overlap.
+ */
+export function groupOverlappingToolCalls(segments: SessionEventTimelineSegment[]): TimelineToolCallGroup[] {
+ const groups: TimelineToolCallGroup[] = [];
+ for (const segment of [...segments].sort((left, right) => left.startMs - right.startMs || left.endMs - right.endMs)) {
+ const current = groups.at(-1);
+ if (
+ current == null ||
+ current.segments[0]?.turnIndex !== segment.turnIndex ||
+ current.segments[0]?.threadId !== segment.threadId ||
+ segment.startMs >= current.endMs
+ ) {
+ groups.push({
+ id: `tool-call-group-${segment.id}`,
+ startMs: segment.startMs,
+ endMs: segment.endMs,
+ segments: [segment],
+ });
+ continue;
+ }
+ current.endMs = Math.max(current.endMs, segment.endMs);
+ current.segments.push(segment);
+ }
+ return groups;
+}
+
+/**
+ * Assign sub-agent tracks to the first reusable non-overlapping lane and attach
+ * each thread's child events to that track.
+ *
+ * `minWidthMs` matches the chart's minimum pixel width in time units, preventing
+ * visually widened markers from colliding even when their raw durations do not.
+ */
+export function getSubAgentLanes({
+ subAgentSegments,
+ threadSegments,
+ minWidthMs,
+}: {
+ subAgentSegments: SessionEventTimelineSegment[];
+ threadSegments: SessionEventTimelineSegment[];
+ minWidthMs: number;
+}): TimelineSubAgentLane[] {
+ const laneEndsMs: number[] = [];
+ const tracks = [...subAgentSegments]
+ .sort((left, right) => left.startMs - right.startMs)
+ .map(segment => {
+ const visualEndMs = Math.max(segment.endMs, segment.startMs + minWidthMs);
+ const freeLane = laneEndsMs.findIndex(laneEndMs => laneEndMs <= segment.startMs);
+ const lane = freeLane === -1 ? laneEndsMs.length : freeLane;
+ laneEndsMs[lane] = visualEndMs;
+ return { ...segment, id: `${segment.id}-lane`, lane, visualEndMs };
+ });
+
+ const childrenByThreadId = new Map<string, SessionEventTimelineSegment[]>();
+ for (const segment of threadSegments) {
+ if (segment.type === 'sub_agent') continue;
+ const children = childrenByThreadId.get(segment.threadId);
+ if (children) children.push(segment);
+ else childrenByThreadId.set(segment.threadId, [segment]);
+ }
+
+ return tracks.map(track => ({
+ threadId: track.threadId,
+ lane: track.lane,
+ track,
+ segments: childrenByThreadId.get(track.threadId) ?? [],
+ }));
+}
+
+/**
+ * Collapse real idle time between turns while preserving all within-turn
+ * offsets and durations.
+ *
+ * Session history may contain minutes or days between user messages. Displaying
+ * that idle time would squeeze useful execution bars into a few pixels, so each
+ * turn is translated to begin where the previous one ended. The chart adds a
+ * small fixed visual separator afterward.
+ */
+export function compressInterTurnGaps(segments: SessionEventTimelineSegment[]): SessionEventTimelineSegment[] {
+ const rangesByTurnIndex = new Map<number, { turnIndex: number; startMs: number; endMs: number }>();
+ for (const segment of segments) {
+ const range = rangesByTurnIndex.get(segment.turnIndex);
+ if (range) {
+ range.startMs = Math.min(range.startMs, segment.startMs);
+ range.endMs = Math.max(range.endMs, segment.endMs);
+ } else {
+ rangesByTurnIndex.set(segment.turnIndex, {
+ turnIndex: segment.turnIndex,
+ startMs: segment.startMs,
+ endMs: segment.endMs,
+ });
+ }
+ }
+
+ const shiftsByTurnIndex = new Map<number, number>();
+ let previousEndMs = 0;
+ for (const [rangeIndex, range] of Array.from(rangesByTurnIndex.values())
+ .sort((left, right) => left.turnIndex - right.turnIndex)
+ .entries()) {
+ const targetStartMs = rangeIndex === 0 ? 0 : previousEndMs;
+ const shiftMs = targetStartMs - range.startMs;
+ shiftsByTurnIndex.set(range.turnIndex, shiftMs);
+ previousEndMs = range.endMs + shiftMs;
+ }
+
+ return segments.map(segment => {
+ const shiftMs = shiftsByTurnIndex.get(segment.turnIndex) ?? 0;
+ return { ...segment, startMs: segment.startMs + shiftMs, endMs: segment.endMs + shiftMs };
+ });
+}
+
+/**
+ * Translate a chart-axis coordinate back to active elapsed time by subtracting
+ * the fixed visual gaps inserted between turn bars.
+ */
+export function getActiveTimelineMs(valueMs: number, gaps: TimelineGap[]): number {
+ let activeMs = valueMs;
+ for (const gap of gaps) {
+ activeMs -= Math.max(0, Math.min(valueMs, gap.endMs) - gap.startMs);
+ }
+ return Math.max(0, activeMs);
+}
+
+/**
+ * Keep generated ticks before the active endpoint, then force endpoint and
+ * padding ticks so the final duration label and trailing whitespace are stable.
+ */
+export function buildTimelineAxisTicks<T extends { value: number }>({
+ ticks,
+ totalMs,
+ timelineMaxMs,
+}: {
+ ticks: readonly T[];
+ totalMs: number;
+ timelineMaxMs: number;
+}): Array<T | { value: number }> {
+ return [...ticks.filter(tick => tick.value < totalMs), { value: totalMs }, { value: timelineMaxMs }];
+}
diff --git a/packages/trueforge-ui/src/utils/sessionShareUrl.ts b/packages/trueforge-ui/src/utils/sessionShareUrl.ts
new file mode 100644
index 000000000..9c642bcd1
--- /dev/null
+++ b/packages/trueforge-ui/src/utils/sessionShareUrl.ts
@@ -0,0 +1,160 @@
+export const SESSION_ID_QUERY = 'sessionId';
+export const AGENT_ID_QUERY = 'agentId';
+export const AGENT_TAB_QUERY = 'tab';
+export const SESSIONS_VIEW_QUERY = 'view';
+export const SESSIONS_VIEW_VALUE = 'sessions';
+export const SESSION_START_TIME_QUERY = 's_sts';
+export const SESSION_END_TIME_QUERY = 's_ets';
+export const SESSION_TIME_WINDOW_QUERY = 's_tw';
+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 SessionTimeRange = {
+ startTs: number;
+ endTs: number;
+ timeWindowMs?: number;
+};
+
+export type SessionShareSearch = {
+ sessionId: string | null;
+ agentId: string | null;
+ tab: LibraryAgentTab | null;
+ view: typeof SESSIONS_VIEW_VALUE | null;
+ timeRange: SessionTimeRange | null;
+};
+
+export type SessionShareWrite = {
+ sessionId?: string | null;
+ agentId?: string | null;
+ tab?: LibraryAgentTab | null;
+ view?: typeof SESSIONS_VIEW_VALUE | null;
+ timeRange?: SessionTimeRange | null;
+};
+
+function parseLibraryAgentTab(value: string | null): LibraryAgentTab | null {
+ if (value === 'overview' || value === 'sessions' || value === 'code') return value;
+ return null;
+}
+
+function nonEmpty(value: string | null): string | null {
+ return value != null && value.length > 0 ? value : null;
+}
+
+function parseMs(value: string | null): number | null {
+ if (value == null || value.length === 0) return null;
+ const parsed = Number(value);
+ return Number.isFinite(parsed) ? parsed : null;
+}
+
+export function defaultSessionTimeRange(now = Date.now()): SessionTimeRange {
+ return {
+ startTs: now - DEFAULT_SESSION_TIME_WINDOW_MS,
+ endTs: now,
+ timeWindowMs: DEFAULT_SESSION_TIME_WINDOW_MS,
+ };
+}
+
+export function sessionTimeRangeFromCreatedAt(createdAt: string): SessionTimeRange | null {
+ const createdAtMs = new Date(createdAt).getTime();
+ if (Number.isNaN(createdAtMs)) return null;
+ return {
+ startTs: createdAtMs - SESSION_TIME_BUFFER_MS,
+ endTs: createdAtMs + SESSION_TIME_BUFFER_MS,
+ };
+}
+
+export function resolveSessionTimeRange(range: SessionTimeRange, now = Date.now()): { startTs: number; endTs: number } {
+ if (range.timeWindowMs != null) {
+ return { startTs: now - range.timeWindowMs, endTs: now };
+ }
+ return { startTs: range.startTs, endTs: range.endTs };
+}
+
+export function readSessionShareSearch(search: string): SessionShareSearch {
+ const params = new URLSearchParams(search.startsWith('?') ? search.slice(1) : search);
+ const startTs = parseMs(params.get(SESSION_START_TIME_QUERY));
+ const endTs = parseMs(params.get(SESSION_END_TIME_QUERY));
+ const timeWindowMs = parseMs(params.get(SESSION_TIME_WINDOW_QUERY));
+ const view = params.get(SESSIONS_VIEW_QUERY);
+ return {
+ sessionId: nonEmpty(params.get(SESSION_ID_QUERY)),
+ agentId: nonEmpty(params.get(AGENT_ID_QUERY)),
+ tab: parseLibraryAgentTab(params.get(AGENT_TAB_QUERY)),
+ view: view === SESSIONS_VIEW_VALUE ? SESSIONS_VIEW_VALUE : null,
+ timeRange:
+ startTs != null && endTs != null
+ ? { startTs, endTs }
+ : timeWindowMs != null
+ ? { startTs: Date.now() - timeWindowMs, endTs: Date.now(), timeWindowMs }
+ : null,
+ };
+}
+
+/** Library details tab: `tab=` wins; a matching share `sessionId` still opens Sessions. */
+export function libraryAgentTabFromSearch(share: SessionShareSearch, agentId: string): LibraryAgentTab {
+ if (share.tab != null) return share.tab;
+ return share.sessionId != null && share.agentId === agentId ? 'sessions' : 'overview';
+}
+
+export function writeSessionShareSearch(params: URLSearchParams, next: SessionShareWrite): void {
+ if (next.sessionId === null) params.delete(SESSION_ID_QUERY);
+ else if (next.sessionId != null) params.set(SESSION_ID_QUERY, next.sessionId);
+ if (next.agentId === null) params.delete(AGENT_ID_QUERY);
+ else if (next.agentId != null) params.set(AGENT_ID_QUERY, next.agentId);
+ if (next.tab === null) params.delete(AGENT_TAB_QUERY);
+ else if (next.tab != null) params.set(AGENT_TAB_QUERY, next.tab);
+ if (next.view === null) params.delete(SESSIONS_VIEW_QUERY);
+ else if (next.view != null) params.set(SESSIONS_VIEW_QUERY, next.view);
+ if (next.timeRange === null) {
+ params.delete(SESSION_START_TIME_QUERY);
+ params.delete(SESSION_END_TIME_QUERY);
+ params.delete(SESSION_TIME_WINDOW_QUERY);
+ } else if (next.timeRange != null) {
+ if (next.timeRange.timeWindowMs != null) {
+ params.set(SESSION_TIME_WINDOW_QUERY, String(next.timeRange.timeWindowMs));
+ params.delete(SESSION_START_TIME_QUERY);
+ params.delete(SESSION_END_TIME_QUERY);
+ } else {
+ params.set(SESSION_START_TIME_QUERY, String(next.timeRange.startTs));
+ params.set(SESSION_END_TIME_QUERY, String(next.timeRange.endTs));
+ params.delete(SESSION_TIME_WINDOW_QUERY);
+ }
+ }
+}
+
+/** Share link for a library or global session. Works with or without `withRouter`. */
+export function buildAgentSessionShareUrl({
+ sessionId,
+ agentId,
+ createdAt,
+ view,
+ href = typeof window === 'undefined' ? '' : window.location.href,
+}: {
+ sessionId: string;
+ agentId?: string;
+ createdAt?: string;
+ view?: typeof SESSIONS_VIEW_VALUE | null;
+ href?: string;
+}): string {
+ const url = new URL(href);
+ writeSessionShareSearch(url.searchParams, {
+ sessionId,
+ agentId: agentId == null || agentId.length === 0 ? null : agentId,
+ ...(view === undefined ? {} : { view }),
+ timeRange: createdAt == null ? undefined : sessionTimeRangeFromCreatedAt(createdAt),
+ });
+ return url.toString();
+}
+
+export const SESSION_SHARE_CHANGE_EVENT = 'trueforge-session-share';
+
+export function replaceSessionShareSearch(next: SessionShareWrite): string {
+ const url = new URL(window.location.href);
+ writeSessionShareSearch(url.searchParams, next);
+ window.history.replaceState(window.history.state, '', url);
+ window.dispatchEvent(new Event(SESSION_SHARE_CHANGE_EVENT));
+ return url.search;
+}
diff --git a/packages/trueforge-ui/src/utils/sessionTimePresets.ts b/packages/trueforge-ui/src/utils/sessionTimePresets.ts
new file mode 100644
index 000000000..ea2537f0c
--- /dev/null
+++ b/packages/trueforge-ui/src/utils/sessionTimePresets.ts
@@ -0,0 +1,35 @@
+export const SESSION_TIME_PRESETS = [
+ { label: 'Last 30 minutes', windowMs: 30 * 60 * 1000 },
+ { label: 'Last 1 hour', windowMs: 60 * 60 * 1000 },
+ { label: 'Last 3 hours', windowMs: 3 * 60 * 60 * 1000 },
+ { label: 'Last 6 hours', windowMs: 6 * 60 * 60 * 1000 },
+ { label: 'Last 12 hours', windowMs: 12 * 60 * 60 * 1000 },
+ { label: 'Last 24 hours', windowMs: 24 * 60 * 60 * 1000 },
+ { label: 'Last 2 days', windowMs: 2 * 24 * 60 * 60 * 1000 },
+ { label: 'Last 7 days', windowMs: 7 * 24 * 60 * 60 * 1000 },
+ { label: 'Last 30 days', windowMs: 30 * 24 * 60 * 60 * 1000 },
+] as const;
+
+export function formatSessionTimePresetLabel(windowMs: number): string | null {
+ return SESSION_TIME_PRESETS.find(preset => preset.windowMs === windowMs)?.label ?? null;
+}
+
+export function formatTimezoneOffsetLabel(date = new Date()): string {
+ const offsetMin = -date.getTimezoneOffset();
+ const sign = offsetMin >= 0 ? '+' : '-';
+ const abs = Math.abs(offsetMin);
+ const hours = String(Math.floor(abs / 60)).padStart(2, '0');
+ const minutes = String(abs % 60).padStart(2, '0');
+ return `UTC${sign}${hours}:${minutes}`;
+}
+
+export function toDateTimeLocalValue(ts: number): string {
+ const date = new Date(ts);
+ const pad = (value: number) => String(value).padStart(2, '0');
+ return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
+export function fromDateTimeLocalValue(value: string): number | null {
+ const parsed = new Date(value).getTime();
+ return Number.isNaN(parsed) ? null : parsed;
+}
diff --git a/packages/trueforge-ui/src/utils/sessionTimelineEvents.ts b/packages/trueforge-ui/src/utils/sessionTimelineEvents.ts
new file mode 100644
index 000000000..9b1851e63
--- /dev/null
+++ b/packages/trueforge-ui/src/utils/sessionTimelineEvents.ts
@@ -0,0 +1,132 @@
+import { MAIN_THREAD_ID } from './sessionEventTimeline.js';
+import type { SessionTurnView } from './sessionTurnViews.js';
+import { parseSandboxArgs, SANDBOX_TOOL_NAMES } from './toolCallParsing.js';
+
+export type TimelineEvent = Record<string, unknown> & { type: string };
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === 'object' && value != null;
+}
+
+export function asTimelineEvent(event: unknown): TimelineEvent | null {
+ return isRecord(event) && typeof event.type === 'string' ? { ...event, type: event.type } : null;
+}
+
+export function readString(record: Record<string, unknown>, camel: string, snake: string): string | undefined {
+ const camelValue = record[camel];
+ if (typeof camelValue === 'string' && camelValue.length > 0) return camelValue;
+ const snakeValue = record[snake];
+ return typeof snakeValue === 'string' && snakeValue.length > 0 ? snakeValue : undefined;
+}
+
+export function parseTimestamp(timestamp: string | undefined): number | null {
+ if (timestamp == null) return null;
+ const timestampMs = Date.parse(timestamp);
+ return Number.isNaN(timestampMs) ? null : timestampMs;
+}
+
+export function eventCreatedAt(event: TimelineEvent): string | undefined {
+ return readString(event, 'createdAt', 'created_at');
+}
+
+export function eventThreadId(event: TimelineEvent): string {
+ return readString(event, 'threadId', 'thread_id') ?? MAIN_THREAD_ID;
+}
+
+export function eventId(event: TimelineEvent): string {
+ return typeof event.id === 'string' ? event.id : `${event.type}-${eventCreatedAt(event) ?? 'unknown'}`;
+}
+
+export function extractText(content: unknown): string {
+ if (typeof content === 'string') return content.trim();
+ if (!Array.isArray(content)) return '';
+ return content
+ .flatMap(item => {
+ if (typeof item === 'string') return item ? [item] : [];
+ if (isRecord(item) && typeof item.text === 'string' && item.text.length > 0) return [item.text];
+ return [];
+ })
+ .join('\n')
+ .trim();
+}
+
+export function toolCallsOf(event: TimelineEvent): Record<string, unknown>[] {
+ const toolCalls = event.toolCalls ?? event.tool_calls;
+ return Array.isArray(toolCalls) ? toolCalls.filter(isRecord) : [];
+}
+
+export function parentToolCallId(event: TimelineEvent): string | undefined {
+ const parent = isRecord(event.parent) ? event.parent : undefined;
+ return parent == null ? undefined : readString(parent, 'toolCallId', 'tool_call_id');
+}
+
+export function terminalCompletedAt(state: unknown): string | undefined {
+ return isRecord(state) ? readString(state, 'completedAt', 'completed_at') : undefined;
+}
+
+export function terminalMessage(state: unknown): string {
+ return isRecord(state) && typeof state.message === 'string' ? state.message : '';
+}
+
+export function terminalStatus(state: unknown): string | undefined {
+ return isRecord(state) && typeof state.status === 'string' ? state.status : undefined;
+}
+
+function turnInputItems(
+ created: SessionTurnView['created'],
+): Array<{ type?: unknown; content?: unknown; approval?: unknown }> {
+ const input = Reflect.get(created, 'input');
+ if (!Array.isArray(input)) return [];
+ return input.flatMap(item => {
+ if (typeof item !== 'object' || item == null) return [];
+ return [
+ {
+ ...('type' in item ? { type: item.type } : {}),
+ ...('content' in item ? { content: item.content } : {}),
+ ...('approval' in item ? { approval: item.approval } : {}),
+ },
+ ];
+ });
+}
+
+export function getTurnInputType(turn: SessionTurnView): string {
+ const item = turnInputItems(turn.created).find(entry => typeof entry.type === 'string');
+ return typeof item?.type === 'string' ? item.type : 'user.message';
+}
+
+export function getTurnInputSummary(turn: SessionTurnView): string {
+ const item = turnInputItems(turn.created).find(entry => typeof entry.type === 'string');
+ if (item == null) return '';
+ if (item.type === 'user.tool_approval') {
+ const approval = isRecord(item.approval) ? item.approval : undefined;
+ const reason = typeof approval?.reason === 'string' ? approval.reason.trim() : '';
+ if (approval?.status === 'deny') return reason.length > 0 ? `Denied: ${reason}` : 'Denied';
+ if (approval?.status === 'allow') return 'Approved';
+ return 'Tool approval';
+ }
+ if (item.type === 'user.tool_response') return extractText(item.content) || 'Tool response';
+ return extractText(item.content) || 'User message';
+}
+
+export function getSubAgentDescription(event: TimelineEvent): string {
+ const title = typeof event.title === 'string' ? event.title.trim() : '';
+ const agentInfo = isRecord(event.agentInfo)
+ ? event.agentInfo
+ : isRecord(event.agent_info)
+ ? event.agent_info
+ : undefined;
+ const name = typeof agentInfo?.name === 'string' ? agentInfo.name.trim() : '';
+ const input = typeof agentInfo?.input === 'string' ? agentInfo.input.trim() : '';
+ return title || name || input;
+}
+
+export function toolCallDescription(toolCall: Record<string, unknown>): string {
+ const fn = isRecord(toolCall.function) ? toolCall.function : undefined;
+ const name = typeof fn?.name === 'string' ? fn.name : '';
+ if (SANDBOX_TOOL_NAMES.has(name) || name === 'code_sandbox') {
+ const argumentsJson = typeof fn?.arguments === 'string' ? fn.arguments : undefined;
+ const intent = parseSandboxArgs(argumentsJson).intent?.trim();
+ return intent != null && intent.length > 0 ? intent : name;
+ }
+ return name;
+}
diff --git a/packages/trueforge-ui/src/utils/sessionTurnViews.ts b/packages/trueforge-ui/src/utils/sessionTurnViews.ts
new file mode 100644
index 000000000..c96d5a03b
--- /dev/null
+++ b/packages/trueforge-ui/src/utils/sessionTurnViews.ts
@@ -0,0 +1,115 @@
+import type { SessionEventItem } from '../server/types.js';
+
+type TurnCreatedEvent = Extract<SessionEventItem['event'], { type: 'turn.created' }>;
+type TurnDoneEvent = Extract<SessionEventItem['event'], { type: 'turn.done' }>;
+type TurnEvent = Exclude<SessionEventItem['event'], TurnCreatedEvent | TurnDoneEvent>;
+
+export type SessionTurnView = {
+ turnId: string;
+ turnNumber: number;
+ showHeader: boolean;
+ created: TurnCreatedEvent;
+ done?: TurnDoneEvent;
+ events: TurnEvent[];
+ totalTokens?: number;
+ totalCostInUsd?: number;
+ durationMs?: number;
+};
+
+type TurnGroup = {
+ created?: TurnCreatedEvent;
+ done?: TurnDoneEvent;
+ events: TurnEvent[];
+};
+
+const RENDERABLE_INPUT_TYPES = new Set(['user.message', 'user.tool_approval', 'user.tool_response']);
+
+function timestampMs(createdAt: string): number {
+ const value = Date.parse(createdAt);
+ return Number.isNaN(value) ? 0 : value;
+}
+
+function isRenderableTurn(created: TurnCreatedEvent): boolean {
+ const input = Reflect.get(created, 'input');
+ if (!Array.isArray(input)) return false;
+ return input.some(item => {
+ if (typeof item !== 'object' || item == null || !('type' in item)) return false;
+ const type = Reflect.get(item, 'type');
+ return typeof type === 'string' && RENDERABLE_INPUT_TYPES.has(type);
+ });
+}
+
+function metricsFromTerminalState(state: unknown): {
+ totalTokens?: number;
+ totalCostInUsd?: number;
+} {
+ if (typeof state !== 'object' || state == null || !('status' in state)) {
+ return {};
+ }
+ const status = Reflect.get(state, 'status');
+ if (status !== 'done' && status !== 'cancelled' && status !== 'error') {
+ return {};
+ }
+ const metrics = Reflect.get(state, 'metrics');
+ if (metrics == null || typeof metrics !== 'object') {
+ return {};
+ }
+ const totalTokens = Reflect.get(metrics, 'totalTokens') ?? Reflect.get(metrics, 'total_tokens');
+ const totalCostInUsd = Reflect.get(metrics, 'totalCostInUsd') ?? Reflect.get(metrics, 'total_cost_in_usd');
+ return {
+ ...(typeof totalTokens === 'number' ? { totalTokens } : {}),
+ ...(typeof totalCostInUsd === 'number' ? { totalCostInUsd } : {}),
+ };
+}
+
+/**
+ * Build canonical ascending turn groups from durable session events.
+ * Pair by turnId so interleaved turn.created / turn.done still match; ignore
+ * orphan terminal or content events that never had a turn.created.
+ */
+export function buildSessionTurnViews(itemsAsc: SessionEventItem[]): SessionTurnView[] {
+ const groupsByTurnId = new Map<string, TurnGroup>();
+
+ for (const item of itemsAsc) {
+ const { turnId, event } = item;
+ const group = groupsByTurnId.get(turnId) ?? { events: [] };
+
+ if (event.type === 'turn.created') {
+ group.created = event;
+ } else if (event.type === 'turn.done') {
+ group.done = event;
+ } else {
+ group.events.push(event);
+ }
+ groupsByTurnId.set(turnId, group);
+ }
+
+ // Number only renderable turns so cards and the timeline share one index.
+ const groups = Array.from(groupsByTurnId.entries())
+ .flatMap(([turnId, group]) =>
+ group.created === undefined || !isRenderableTurn(group.created)
+ ? []
+ : [{ turnId, created: group.created, group }],
+ )
+ .sort((left, right) => timestampMs(left.created.createdAt) - timestampMs(right.created.createdAt));
+
+ return groups.map(({ turnId, created, group }, index) => {
+ const done = group.done;
+ group.events.sort((left, right) => timestampMs(left.createdAt) - timestampMs(right.createdAt));
+
+ return {
+ turnId,
+ turnNumber: index + 1,
+ showHeader: true,
+ created,
+ ...(done === undefined
+ ? {}
+ : {
+ done,
+ durationMs: Math.max(0, timestampMs(done.createdAt) - timestampMs(created.createdAt)),
+ ...metricsFromTerminalState(done.state),
+ }),
+ events: group.events,
+ };
+ });
+}
diff --git a/packages/trueforge-ui/test/atoms/AgentDetailsPage.test.tsx b/packages/trueforge-ui/test/atoms/AgentDetailsPage.test.tsx
new file mode 100644
index 000000000..e784bda1d
--- /dev/null
+++ b/packages/trueforge-ui/test/atoms/AgentDetailsPage.test.tsx
@@ -0,0 +1,293 @@
+// @vitest-environment jsdom
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { MemoryRouter } from 'react-router-dom';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+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 { SlotsProvider, type SlotOverrides } from '@/theme/SlotsProvider.js';
+import { createMockAgentUIServer } from '../server/mockServer.js';
+
+const detail: AgentDetail = {
+ agentId: 'agent-1',
+ name: 'release-notes-writer',
+ agentSpec: {
+ model: { name: 'openai/gpt-5.1', params: { maxTokens: 16000 } },
+ instructions: '# Who you are\n\nWrite concise release notes.',
+ skills: [{ name: 'release-writing' }],
+ mcpServers: [{ name: 'github' }],
+ },
+};
+
+const snippets: CodeSnippet[] = [
+ {
+ labelName: 'TypeScript',
+ language: 'typescript',
+ sampleCode: { stream: 'const stream = true;', nonStream: 'const stream = false;' },
+ },
+];
+
+const sessionRows: SessionListEntry[] = [
+ {
+ id: 'sess-1',
+ title: 'Release notes draft',
+ createdAt: '2026-01-01T00:00:00.000Z',
+ updatedAt: '2026-01-02T00:00:00.000Z',
+ lastActivityAt: '2026-01-02T00:00:00.000Z',
+ metrics: { totalTurns: 2, totalCostInUsd: 0.5, totalDurationMs: 120_000 },
+ agentName: 'release-notes-writer',
+ },
+];
+
+function deferred<T>() {
+ let settle: ((value: T) => void) | undefined;
+ return {
+ promise: new Promise<T>(resolve => {
+ settle = resolve;
+ }),
+ resolve(value: T) {
+ settle?.(value);
+ },
+ };
+}
+
+function renderPage({
+ getAgent = vi.fn(async () => detail),
+ getCodeSnippets = vi.fn(async () => snippets),
+ listSessions = vi.fn(async () => ({ data: sessionRows })),
+ listSessionEvents = vi.fn(async () => ({ data: [] as SessionEventItem[] })),
+ getSession = vi.fn(async (): Promise<Session> => ({
+ id: 'sess-1',
+ title: 'From getSession',
+ isMutable: false,
+ createdAt: '2026-01-01T00:00:00.000Z',
+ updatedAt: '2026-01-02T00:00:00.000Z',
+ })),
+ withSessions = true,
+ overrides,
+ initialEntries = ['/library/agent-1'],
+}: {
+ getAgent?: () => Promise<AgentDetail>;
+ getCodeSnippets?: () => Promise<CodeSnippet[]>;
+ listSessions?: () => Promise<{ data: SessionListEntry[] }>;
+ listSessionEvents?: () => Promise<{ data: SessionEventItem[] }>;
+ getSession?: () => Promise<Session>;
+ withSessions?: boolean;
+ overrides?: SlotOverrides;
+ initialEntries?: string[];
+} = {}) {
+ const server = createMockAgentUIServer({
+ getSession,
+ ...(withSessions ? { sessions: { getAgent, getCodeSnippets, listSessions, listSessionEvents } } : {}),
+ });
+ render(
+ <MemoryRouter initialEntries={initialEntries}>
+ <SlotsProvider overrides={overrides}>
+ <ServerProvider server={server}>
+ <ShellModeProvider>
+ <AgentDetailsPage agentId="agent-1" />
+ </ShellModeProvider>
+ </ServerProvider>
+ </SlotsProvider>
+ </MemoryRouter>,
+ );
+ return { getAgent, getCodeSnippets, listSessions, listSessionEvents, getSession };
+}
+
+describe('AgentDetailsPage', () => {
+ afterEach(() => {
+ window.history.replaceState(null, '', '/');
+ });
+
+ it('loads Overview and renders agent details', async () => {
+ const { getAgent } = renderPage();
+
+ expect(await screen.findByRole('heading', { name: 'release-notes-writer' })).toBeInTheDocument();
+ expect(await screen.findByText('Write concise release notes.')).toBeInTheDocument();
+ expect(await screen.findByText('github')).toBeInTheDocument();
+ expect(await screen.findByText('release-writing')).toBeInTheDocument();
+ expect(getAgent).toHaveBeenCalledTimes(1);
+ });
+
+ it('renders tab bodies through SlotProvider overrides', async () => {
+ renderPage({ overrides: { AgentOverview: () => <div>Custom overview</div> } });
+ expect(await screen.findByText('Custom overview')).toBeInTheDocument();
+ });
+
+ it('loads code snippets lazily and retains them across tab changes', async () => {
+ const { getCodeSnippets } = renderPage();
+ await screen.findByRole('heading', { name: 'release-notes-writer' });
+ expect(getCodeSnippets).not.toHaveBeenCalled();
+
+ fireEvent.click(screen.getByRole('tab', { name: 'Use In Code' }));
+ expect(await screen.findByText('const stream = true;')).toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'Non-stream' }));
+ expect(screen.getByText('const stream = false;')).toBeInTheDocument();
+
+ fireEvent.click(screen.getByRole('tab', { name: 'Overview' }));
+ fireEvent.click(screen.getByRole('tab', { name: 'Use In Code' }));
+ expect(await screen.findByText('const stream = true;')).toBeInTheDocument();
+ expect(getCodeSnippets).toHaveBeenCalledTimes(1);
+ });
+
+ it('loads the Sessions tab list scoped to the agent', async () => {
+ const { listSessions } = renderPage();
+ await screen.findByRole('heading', { name: 'release-notes-writer' });
+ fireEvent.click(screen.getByRole('tab', { name: 'Sessions' }));
+ expect(await screen.findByText('Release notes draft')).toBeInTheDocument();
+ expect(screen.getByText('Select a session to view details')).toBeInTheDocument();
+ expect(listSessions).toHaveBeenCalledWith(
+ expect.objectContaining({ agentId: 'agent-1', order: 'desc', limit: 20 }),
+ );
+ });
+
+ it('ignores a stale list response after the agent filter changes', async () => {
+ const first = deferred<{ data: SessionListEntry[] }>();
+ const second = deferred<{ data: SessionListEntry[] }>();
+ const listSessions = vi.fn((request?: { agentId?: string }) =>
+ request?.agentId === 'agent-1' ? first.promise : second.promise,
+ );
+ const server = createMockAgentUIServer({
+ sessions: {
+ getAgent: vi.fn(async () => detail),
+ getCodeSnippets: vi.fn(async () => snippets),
+ listSessions,
+ listSessionEvents: vi.fn(async () => ({ data: [] })),
+ },
+ });
+ const ui = (agentId: string) => (
+ <SlotsProvider>
+ <ServerProvider server={server}>
+ <ShellModeProvider>
+ <AgentSessions agentId={agentId} />
+ </ShellModeProvider>
+ </ServerProvider>
+ </SlotsProvider>
+ );
+ const view = render(ui('agent-1'));
+ view.rerender(ui('agent-2'));
+
+ await act(async () => {
+ second.resolve({
+ data: [
+ {
+ id: 'sess-2',
+ title: 'Second agent session',
+ createdAt: '2026-01-03T00:00:00.000Z',
+ updatedAt: '2026-01-03T00:01:00.000Z',
+ lastActivityAt: '2026-01-03T00:01:00.000Z',
+ metrics: { totalTurns: 1, totalCostInUsd: 0, totalDurationMs: 1000 },
+ agentName: 'second-agent',
+ },
+ ],
+ });
+ });
+ expect(await screen.findByText('Second agent session')).toBeInTheDocument();
+
+ await act(async () => {
+ first.resolve({ data: sessionRows });
+ });
+ expect(screen.queryByText('Release notes draft')).not.toBeInTheDocument();
+ });
+
+ it('keeps loaded rows visible when loading another page fails', async () => {
+ const listSessions = vi.fn(async (request?: { pageToken?: string }) => {
+ if (request?.pageToken != null) throw new Error('network error');
+ return { data: sessionRows, nextPageToken: 'next-page' };
+ });
+ renderPage({ listSessions });
+ await screen.findByRole('heading', { name: 'release-notes-writer' });
+ fireEvent.click(screen.getByRole('tab', { name: 'Sessions' }));
+ expect(await screen.findByText('Release notes draft')).toBeInTheDocument();
+
+ fireEvent.click(screen.getByRole('button', { name: 'Load more' }));
+ await waitFor(() => expect(listSessions).toHaveBeenCalledTimes(2));
+ expect(screen.getByText('Release notes draft')).toBeInTheDocument();
+ expect(screen.queryByText('Sessions could not be loaded.')).not.toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Load more' })).toBeEnabled();
+ });
+
+ it('opens the Sessions tab and selected session from the share URL', async () => {
+ window.history.replaceState(null, '', '/library/agent-1?sessionId=sess-1&agentId=agent-1');
+ const { getSession, listSessionEvents } = renderPage({
+ overrides: { AgentSessionTimelineContainer: () => <div>timeline-body</div> },
+ });
+ expect(await screen.findByRole('tab', { name: 'Sessions' })).toHaveAttribute('aria-selected', 'true');
+ await waitFor(() => {
+ expect(getSession).toHaveBeenCalledWith({ sessionId: 'sess-1' });
+ expect(listSessionEvents).toHaveBeenCalledWith(expect.objectContaining({ sessionId: 'sess-1' }));
+ });
+ expect(screen.getByText('timeline-body')).toBeInTheDocument();
+ });
+
+ it('stays on Overview when the URL only has an unrelated chat sessionId', async () => {
+ window.history.replaceState(null, '', '/library/agent-1?sessionId=chat-sess');
+ renderPage();
+ expect(await screen.findByRole('tab', { name: 'Overview' })).toHaveAttribute('aria-selected', 'true');
+ expect(screen.getByRole('tab', { name: 'Sessions' })).toHaveAttribute('aria-selected', 'false');
+ });
+
+ it('honors tab= in the URL and writes it when the user switches tabs', async () => {
+ window.history.replaceState(null, '', '/library/agent-1?tab=code&agentId=agent-1&sessionId=stale');
+ const { getCodeSnippets } = renderPage();
+ expect(await screen.findByRole('tab', { name: 'Use In Code' })).toHaveAttribute('aria-selected', 'true');
+ await screen.findByText('const stream = true;');
+ expect(getCodeSnippets).toHaveBeenCalledTimes(1);
+
+ fireEvent.click(screen.getByRole('tab', { name: 'Overview' }));
+ expect(screen.getByRole('tab', { name: 'Overview' })).toHaveAttribute('aria-selected', 'true');
+ const params = new URL(window.location.href).searchParams;
+ expect(params.get('tab')).toBe('overview');
+ expect(params.get('agentId')).toBe('agent-1');
+ expect(params.get('sessionId')).toBeNull();
+ });
+
+ it('clears agent share state when Escape closes details', async () => {
+ window.history.replaceState(
+ null,
+ '',
+ '/?agentId=agent-1&tab=sessions&sessionId=sess-1&view=sessions&s_tw=2592000000',
+ );
+ renderPage({ initialEntries: ['/?agentId=agent-1&tab=sessions&sessionId=sess-1&view=sessions&s_tw=2592000000'] });
+ await screen.findByRole('heading', { name: 'release-notes-writer' });
+
+ fireEvent.keyDown(window, { key: 'Escape' });
+
+ const params = new URL(window.location.href).searchParams;
+ expect(params.get('agentId')).toBeNull();
+ expect(params.get('tab')).toBeNull();
+ expect(params.get('sessionId')).toBeNull();
+ expect(params.get('view')).toBeNull();
+ expect(params.get('s_tw')).toBeNull();
+ });
+
+ it('loads session metadata from getSession when a row is selected', async () => {
+ const { getSession, listSessionEvents } = renderPage({
+ overrides: { AgentSessionTimelineContainer: () => <div>timeline-body</div> },
+ });
+ await screen.findByRole('heading', { name: 'release-notes-writer' });
+ fireEvent.click(screen.getByRole('tab', { name: 'Sessions' }));
+ fireEvent.click(await screen.findByText('Release notes draft'));
+ await waitFor(() => {
+ expect(getSession).toHaveBeenCalledWith({ sessionId: 'sess-1' });
+ expect(listSessionEvents).toHaveBeenCalledWith(expect.objectContaining({ sessionId: 'sess-1' }));
+ });
+ expect(await screen.findByText('From getSession')).toBeInTheDocument();
+ expect(screen.getByText('timeline-body')).toBeInTheDocument();
+ });
+
+ it('shows the shared unavailable state without the optional server', () => {
+ renderPage({ withSessions: false });
+ expect(screen.getByRole('heading', { name: 'Agent details unavailable' })).toBeInTheDocument();
+ });
+
+ it('shows the shared unavailable state when loading fails', async () => {
+ renderPage({ getAgent: vi.fn(async () => Promise.reject(new Error('not found'))) });
+ await waitFor(() => {
+ expect(screen.getByRole('heading', { name: 'Agent details unavailable' })).toBeInTheDocument();
+ });
+ });
+});
diff --git a/packages/trueforge-ui/test/atoms/AgentSessionDetailHeader.test.tsx b/packages/trueforge-ui/test/atoms/AgentSessionDetailHeader.test.tsx
new file mode 100644
index 000000000..fcb56de9f
--- /dev/null
+++ b/packages/trueforge-ui/test/atoms/AgentSessionDetailHeader.test.tsx
@@ -0,0 +1,60 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { AgentSessionDetailHeader } from '@/atoms/agent-details/AgentSessionDetailHeader.js';
+import { buildAgentSessionShareUrl } from '@/utils/sessionShareUrl.js';
+
+const clipboardDescriptor = Object.getOwnPropertyDescriptor(navigator, 'clipboard');
+
+describe('buildAgentSessionShareUrl', () => {
+ it('puts agent id and session id on the current page URL', () => {
+ const href = buildAgentSessionShareUrl({
+ sessionId: 'sess-1',
+ agentId: 'agent-1',
+ href: 'https://app.example/library/agent-1',
+ });
+ const url = new URL(href);
+ expect(url.origin + url.pathname).toBe('https://app.example/library/agent-1');
+ expect(url.searchParams.get('sessionId')).toBe('sess-1');
+ expect(url.searchParams.get('agentId')).toBe('agent-1');
+ });
+});
+
+describe('AgentSessionDetailHeader', () => {
+ afterEach(() => {
+ if (clipboardDescriptor === undefined) {
+ Reflect.deleteProperty(navigator, 'clipboard');
+ } else {
+ Object.defineProperty(navigator, 'clipboard', clipboardDescriptor);
+ }
+ });
+
+ it('keeps title and session id on one line and copies the session link', async () => {
+ const writeText = vi.fn(async () => undefined);
+ Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } });
+
+ render(
+ <AgentSessionDetailHeader
+ title="Help me find more details"
+ sessionId="sess-1"
+ agentId="agent-1"
+ onClose={() => undefined}
+ />,
+ );
+
+ const heading = screen.getByRole('heading', { name: 'Help me find more details' });
+ expect(heading.parentElement).toHaveClass('items-center');
+ expect(heading.parentElement).toHaveTextContent('sess-1');
+
+ const copyButton = screen.getByRole('button', { name: 'Copy session link' });
+ fireEvent.mouseEnter(copyButton);
+ expect(screen.getByRole('tooltip')).toHaveTextContent('Copy session link');
+
+ fireEvent.click(copyButton);
+ await waitFor(() => {
+ expect(writeText).toHaveBeenCalledWith(buildAgentSessionShareUrl({ sessionId: 'sess-1', agentId: 'agent-1' }));
+ expect(screen.getByRole('tooltip')).toHaveTextContent('Copied');
+ });
+ });
+});
diff --git a/packages/trueforge-ui/test/atoms/AgentSessionEventTimeline.test.tsx b/packages/trueforge-ui/test/atoms/AgentSessionEventTimeline.test.tsx
new file mode 100644
index 000000000..3baa6b9a3
--- /dev/null
+++ b/packages/trueforge-ui/test/atoms/AgentSessionEventTimeline.test.tsx
@@ -0,0 +1,82 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { AgentSessionEventTimeline } from '@/atoms/agent-details/AgentSessionEventTimeline.js';
+import { SlotsProvider } from '@/theme/SlotsProvider.js';
+import type { SessionEventTimelineSegment } from '@/utils/sessionEventTimeline.js';
+import type { SessionTurnView } from '@/utils/sessionTurnViews.js';
+
+const turns = [
+ {
+ turnId: 't1',
+ turnNumber: 1,
+ showHeader: true,
+ created: {
+ type: 'turn.created',
+ id: 'c1',
+ turnId: 't1',
+ previousTurnId: null,
+ input: [{ type: 'user.message', content: 'hi' }],
+ state: { status: 'running' },
+ createdAt: '2026-01-01T00:00:00.000Z',
+ threadId: null,
+ },
+ events: [],
+ },
+] as SessionTurnView[];
+
+const segments: SessionEventTimelineSegment[] = [
+ {
+ id: 't1-user',
+ type: 'user',
+ title: 'user.message',
+ description: 'hi',
+ startMs: 0,
+ endMs: 0,
+ turnIndex: 0,
+ threadId: 'main',
+ isMarker: true,
+ },
+ {
+ id: 't1-model',
+ type: 'model',
+ title: 'model.message',
+ description: 'hello',
+ startMs: 0,
+ endMs: 1_000,
+ turnIndex: 0,
+ threadId: 'main',
+ },
+];
+
+describe('AgentSessionEventTimeline', () => {
+ it('renders event-type filters and honors a chart slot override', () => {
+ const onSelectTurn = vi.fn();
+ render(
+ <SlotsProvider
+ overrides={{
+ AgentSessionEventTimelineChart: ({ hiddenTypes, onSelectTurn: select }) => (
+ <button type="button" onClick={() => select?.(0)}>
+ {`chart hidden=${[...hiddenTypes].join(',') || 'none'}`}
+ </button>
+ ),
+ }}
+ >
+ <AgentSessionEventTimeline turns={turns} segments={segments} onSelectTurn={onSelectTurn} />
+ </SlotsProvider>,
+ );
+
+ expect(screen.getByText('Event types')).toBeInTheDocument();
+ expect(screen.getByText('Event types').parentElement).toHaveClass('border-b');
+ fireEvent.click(screen.getByRole('button', { name: 'User' }));
+ expect(screen.getByRole('button', { name: /chart hidden=/ })).toHaveTextContent('user');
+ fireEvent.click(screen.getByRole('button', { name: /chart hidden=/ }));
+ expect(onSelectTurn).toHaveBeenCalledWith(0);
+ });
+
+ it('renders nothing when there are no segments', () => {
+ const { container } = render(<AgentSessionEventTimeline turns={turns} segments={[]} />);
+ expect(container).toBeEmptyDOMElement();
+ });
+});
diff --git a/packages/trueforge-ui/test/atoms/AgentSessionMetricsStrip.test.tsx b/packages/trueforge-ui/test/atoms/AgentSessionMetricsStrip.test.tsx
new file mode 100644
index 000000000..569673dc5
--- /dev/null
+++ b/packages/trueforge-ui/test/atoms/AgentSessionMetricsStrip.test.tsx
@@ -0,0 +1,60 @@
+// @vitest-environment jsdom
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { AgentSessionMetricsStrip } from '@/atoms/agent-details/AgentSessionMetricsStrip.js';
+import type { SessionMetrics } from '@/utils/buildSessionMetrics.js';
+
+const metrics: SessionMetrics = {
+ totalTurns: 7,
+ wallTimeMs: 120_000,
+ totalCostUsd: 2.6229,
+ totalTokens: 280_000,
+ contextTokens: 280_000,
+ toolCalls: 9,
+ subAgents: 0,
+ errors: 0,
+ timeBreakdown: [
+ { label: 'model', value: 80_000, color: '#3b82f6' },
+ { label: 'tools', value: 20_000, color: '#f59e0b' },
+ { label: 'waiting on human', value: 0, color: '#f472b6' },
+ { label: 'overhead', value: 20_000, color: '#94a3b8' },
+ ],
+ costPerTurn: [
+ { label: 'T1', value: 2, color: '#f59e0b' },
+ { label: 'T2', value: 0.6, color: '#f59e0b' },
+ ],
+ tokenBreakdown: [
+ { label: 'input', value: 200_000, color: '#3b82f6' },
+ { label: 'output', value: 80_000, color: '#34d399' },
+ { label: 'cached', value: 0, color: '#c084fc' },
+ ],
+ contextByTurn: [
+ { label: 'T1', value: 200_000, color: '#3b82f6' },
+ { label: 'T2', value: 280_000, color: '#3b82f6' },
+ ],
+ toolCallFrequency: [{ label: 'search', value: 9, color: '#f59e0b' }],
+};
+
+describe('AgentSessionMetricsStrip', () => {
+ it('renders the session metric tiles', () => {
+ render(<AgentSessionMetricsStrip metrics={metrics} />);
+ expect(screen.getByText('Turns')).toBeInTheDocument();
+ expect(screen.getByText('7')).toBeInTheDocument();
+ expect(screen.getByText('Duration')).toBeInTheDocument();
+ expect(screen.getByText('Cost')).toBeInTheDocument();
+ expect(screen.getByText('$2.6229')).toBeInTheDocument();
+ expect(screen.getByText('Tokens')).toBeInTheDocument();
+ expect(screen.getByText('Tool calls')).toBeInTheDocument();
+ expect(screen.getByText('Sub-agents')).toBeInTheDocument();
+ expect(screen.getByText('Errors')).toBeInTheDocument();
+ expect(document.querySelector('[data-slot="agent-session-metrics-strip"]')).toHaveClass('@container');
+ expect(document.querySelector('[data-slot="agent-session-metrics-strip"]')).not.toHaveClass('rounded-md');
+ expect(document.querySelector('[data-slot="agent-session-metrics-strip"] > div')).toHaveClass(
+ 'grid-cols-3',
+ '@min-[24rem]:grid-cols-4',
+ '@min-[48rem]:grid-cols-8',
+ );
+ expect(document.querySelector('[data-slot="session-metric-wall-time"]')).toHaveClass('w-full');
+ });
+});
diff --git a/packages/trueforge-ui/test/atoms/AgentSessionsFilters.test.tsx b/packages/trueforge-ui/test/atoms/AgentSessionsFilters.test.tsx
new file mode 100644
index 000000000..1122253f7
--- /dev/null
+++ b/packages/trueforge-ui/test/atoms/AgentSessionsFilters.test.tsx
@@ -0,0 +1,33 @@
+// @vitest-environment jsdom
+import { render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { AgentSessionsFilters } from '@/atoms/agent-details/AgentSessionsFilters.js';
+import { ServerProvider } from '@/server/ServerContext.js';
+import type { AgentLibraryEntry } from '@/server/types.js';
+import { createMockAgentUIServer } from '../server/mockServer.js';
+
+describe('AgentSessionsFilters', () => {
+ it('loads every page of agents', async () => {
+ const agents: AgentLibraryEntry[] = Array.from({ length: 51 }, (_, index) => ({
+ agentId: `agent-${String(index + 1)}`,
+ name: `Agent ${String(index + 1)}`,
+ }));
+ const searchAgents = vi.fn(async ({ limit = 50, offset = 0 } = {}) => agents.slice(offset, offset + limit));
+
+ render(
+ <ServerProvider server={createMockAgentUIServer({ searchAgents })}>
+ <AgentSessionsFilters
+ agentId={null}
+ timeRange={{ startTs: 1, endTs: 2 }}
+ onAgentChange={() => undefined}
+ onTimeRangeChange={() => undefined}
+ />
+ </ServerProvider>,
+ );
+
+ await waitFor(() => expect(screen.getByRole('option', { name: 'Agent 51' })).toBeInTheDocument());
+ expect(searchAgents).toHaveBeenNthCalledWith(1, { limit: 50, offset: 0 });
+ expect(searchAgents).toHaveBeenNthCalledWith(2, { limit: 50, offset: 50 });
+ });
+});
diff --git a/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx b/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx
index e82a6ccdb..0b5e0ed79 100644
--- a/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx
+++ b/packages/trueforge-ui/test/atoms/AgentsLibrary.test.tsx
@@ -1,6 +1,7 @@
// @vitest-environment jsdom
import { fireEvent, render, screen, waitFor } from '@testing-library/react';
-import { beforeAll, describe, expect, it, vi } from 'vitest';
+import type { ReactNode } from 'react';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
import { AgentsLibrary } from '@/atoms/AgentsLibrary.js';
import { AgentsLibraryButton } from '@/atoms/AgentsLibraryButton.js';
@@ -22,6 +23,10 @@ beforeAll(() => {
};
});
+afterEach(() => {
+ window.history.replaceState(null, '', '/');
+});
+
function mockServer(
agents: Array<{
name: string;
@@ -38,6 +43,39 @@ function mockServer(
});
}
+function renderLibrary(
+ ui: ReactNode,
+ {
+ server = mockServer(),
+ agentConfig,
+ }: {
+ server?: AgentUIServer;
+ agentConfig?: Parameters<typeof ShellModeProvider>[0]['agentConfig'];
+ } = {},
+) {
+ return render(
+ <SlotsProvider>
+ <ServerProvider server={server}>
+ <ShellModeProvider agentConfig={agentConfig}>{ui}</ShellModeProvider>
+ </ServerProvider>
+ </SlotsProvider>,
+ );
+}
+
+function LibraryHarness({ children, onSelectAgent }: { children?: ReactNode; onSelectAgent?: (name: string) => void }) {
+ const shell = useShellMode();
+ return (
+ <>
+ <button type="button" onClick={() => shell.setLibraryOpen(true)}>
+ Open library
+ </button>
+ <output data-testid="library-agent-id">{shell.libraryAgentId ?? ''}</output>
+ <AgentsLibrary onSelectAgent={onSelectAgent} />
+ {children}
+ </>
+ );
+}
+
describe('CenteredModal', () => {
it('opens with desktop-centered and mobile bottom-sheet classes', () => {
render(
@@ -70,32 +108,52 @@ describe('CenteredModal', () => {
});
describe('AgentsLibrary', () => {
+ it('opens agent details from the row only when the optional server is available', async () => {
+ window.history.replaceState(null, '', '/library?theme=dark&sessionId=stale&view=sessions&s_sts=1&s_ets=2');
+ const server = createMockAgentUIServer({
+ searchAgents: vi.fn(async () => [{ name: 'alpha-agent', agentId: 'agent-1' }]),
+ sessions: {
+ getAgent: vi.fn(),
+ getCodeSnippets: vi.fn(),
+ listSessions: vi.fn(async () => ({ data: [] })),
+ listSessionEvents: vi.fn(async () => ({ data: [] })),
+ },
+ });
+ renderLibrary(<LibraryHarness />, { server });
+ fireEvent.click(screen.getByRole('button', { name: 'Open library' }));
+
+ fireEvent.click(await screen.findByRole('menuitem', { name: 'Open alpha-agent' }));
+ expect(screen.getByTestId('library-agent-id')).toHaveTextContent('agent-1');
+ const params = new URL(window.location.href).searchParams;
+ expect(params.get('theme')).toBe('dark');
+ expect(params.get('agentId')).toBe('agent-1');
+ expect(params.get('tab')).toBe('overview');
+ expect(params.get('sessionId')).toBeNull();
+ expect(params.get('view')).toBeNull();
+ expect(params.get('s_sts')).toBeNull();
+ expect(params.get('s_ets')).toBeNull();
+ });
+
it('lists agents and selects a named agent (Try = immutable)', async () => {
const server = mockServer([
{ name: 'alpha-agent', agentId: 'alpha-agent' },
{ name: 'beta-agent', agentId: 'beta-agent' },
]);
const onSelectAgent = vi.fn();
- const onOpenChange = vi.fn();
- render(
- <SlotsProvider>
- <ServerProvider server={server}>
- <ShellModeProvider>
- <AgentsLibrary open onOpenChange={onOpenChange} onSelectAgent={onSelectAgent} />
- </ShellModeProvider>
- </ServerProvider>
- </SlotsProvider>,
- );
+ renderLibrary(<LibraryHarness onSelectAgent={onSelectAgent} />, { server });
- expect(screen.getByRole('dialog', { name: 'Agents Library' })).toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'Open library' }));
+ expect(screen.getByRole('heading', { name: 'Agents Library' })).toBeInTheDocument();
await waitFor(() => {
expect(screen.getByRole('button', { name: 'Try agent alpha-agent' })).toBeInTheDocument();
});
fireEvent.click(screen.getByRole('button', { name: 'Try agent beta-agent' }));
- expect(onOpenChange).toHaveBeenCalledWith(false);
expect(onSelectAgent).toHaveBeenCalledWith('beta-agent');
+ await waitFor(() => {
+ expect(screen.queryByRole('heading', { name: 'Agents Library' })).not.toBeInTheDocument();
+ });
});
it('shows Edit when composer is enabled and agentSpec is present', async () => {
@@ -108,15 +166,12 @@ describe('AgentsLibrary', () => {
{ name: 'try-only', agentId: 'try-only' },
]);
- render(
- <SlotsProvider>
- <ServerProvider server={server}>
- <ShellModeProvider agentConfig={{ mode: 'AgentLibraryWithComposer' }}>
- <AgentsLibrary open onOpenChange={() => undefined} />
- </ShellModeProvider>
- </ServerProvider>
- </SlotsProvider>,
- );
+ renderLibrary(<LibraryHarness />, {
+ server,
+ agentConfig: { mode: 'AgentLibraryWithComposer' },
+ });
+
+ fireEvent.click(screen.getByRole('button', { name: 'Open library' }));
await waitFor(() => {
expect(screen.getByRole('button', { name: 'Edit agent writer' })).toBeInTheDocument();
@@ -139,15 +194,12 @@ describe('AgentsLibrary', () => {
{ name: 'bare', agentId: 'bare' },
]);
- render(
- <SlotsProvider>
- <ServerProvider server={server}>
- <ShellModeProvider agentConfig={{ mode: 'AgentLibraryWithComposer' }}>
- <AgentsLibrary open onOpenChange={() => undefined} />
- </ShellModeProvider>
- </ServerProvider>
- </SlotsProvider>,
- );
+ renderLibrary(<LibraryHarness />, {
+ server,
+ agentConfig: { mode: 'AgentLibraryWithComposer' },
+ });
+
+ fireEvent.click(screen.getByRole('button', { name: 'Open library' }));
await waitFor(() => {
expect(screen.getByText('gpt-5-5')).toBeInTheDocument();
@@ -167,15 +219,12 @@ describe('AgentsLibrary', () => {
},
]);
- render(
- <SlotsProvider>
- <ServerProvider server={server}>
- <ShellModeProvider agentConfig={{ mode: 'AgentLibrary' }}>
- <AgentsLibrary open onOpenChange={() => undefined} />
- </ShellModeProvider>
- </ServerProvider>
- </SlotsProvider>,
- );
+ renderLibrary(<LibraryHarness />, {
+ server,
+ agentConfig: { mode: 'AgentLibrary' },
+ });
+
+ fireEvent.click(screen.getByRole('button', { name: 'Open library' }));
await waitFor(() => {
expect(screen.getByRole('button', { name: 'Try agent writer' })).toBeInTheDocument();
@@ -186,15 +235,9 @@ describe('AgentsLibrary', () => {
it('shows create-one guidance when there are no agents yet', async () => {
const server = mockServer([]);
- render(
- <SlotsProvider>
- <ServerProvider server={server}>
- <ShellModeProvider>
- <AgentsLibrary open onOpenChange={() => undefined} />
- </ShellModeProvider>
- </ServerProvider>
- </SlotsProvider>,
- );
+ renderLibrary(<LibraryHarness />, { server });
+
+ fireEvent.click(screen.getByRole('button', { name: 'Open library' }));
await waitFor(() => {
expect(screen.getByText('No agents yet. Build one in a chat, then save it as an agent.')).toBeInTheDocument();
@@ -204,15 +247,9 @@ describe('AgentsLibrary', () => {
it('shows a no-matches message (not the create-one guidance) when a search returns nothing', async () => {
const server = mockServer([]);
- render(
- <SlotsProvider>
- <ServerProvider server={server}>
- <ShellModeProvider>
- <AgentsLibrary open onOpenChange={() => undefined} />
- </ShellModeProvider>
- </ServerProvider>
- </SlotsProvider>,
- );
+ renderLibrary(<LibraryHarness />, { server });
+
+ fireEvent.click(screen.getByRole('button', { name: 'Open library' }));
fireEvent.change(screen.getByPlaceholderText('Search agents'), { target: { value: 'zzz' } });
@@ -221,24 +258,33 @@ describe('AgentsLibrary', () => {
});
expect(screen.queryByText('No agents yet. Build one in a chat, then save it as an agent.')).not.toBeInTheDocument();
});
+
+ it('closes via the back button', () => {
+ renderLibrary(<LibraryHarness />);
+
+ fireEvent.click(screen.getByRole('button', { name: 'Open library' }));
+ expect(screen.getByRole('heading', { name: 'Agents Library' })).toBeInTheDocument();
+
+ fireEvent.click(screen.getByRole('button', { name: 'Back' }));
+ expect(screen.queryByRole('heading', { name: 'Agents Library' })).not.toBeInTheDocument();
+ });
});
describe('AgentsLibraryButton', () => {
- it('opens the Agents Library dialog from the trigger', async () => {
+ it('opens the Agents Library panel from the trigger', async () => {
const server = mockServer([{ name: 'alpha-agent', agentId: 'alpha-agent' }]);
- render(
- <SlotsProvider>
- <ServerProvider server={server}>
- <ShellModeProvider>
- <AgentsLibraryButton />
- </ShellModeProvider>
- </ServerProvider>
- </SlotsProvider>,
+ renderLibrary(
+ <>
+ <AgentsLibraryButton />
+ <AgentsLibrary />
+ </>,
+ { server },
);
fireEvent.click(screen.getByRole('button', { name: /Agents Library/ }));
- expect(screen.getByRole('dialog', { name: 'Agents Library' })).toBeInTheDocument();
+ expect(screen.getByRole('heading', { name: 'Agents Library' })).toBeInTheDocument();
+ expect(screen.getByRole('button', { name: /Agents Library/ })).toHaveAttribute('aria-current', 'page');
await waitFor(() => {
expect(screen.getByRole('button', { name: 'Try agent alpha-agent' })).toBeInTheDocument();
});
@@ -263,15 +309,12 @@ describe('AgentsLibraryButton', () => {
);
}
- render(
- <SlotsProvider>
- <ServerProvider server={server}>
- <ShellModeProvider>
- <AgentsLibraryButton />
- <Invalidate />
- </ShellModeProvider>
- </ServerProvider>
- </SlotsProvider>,
+ renderLibrary(
+ <>
+ <AgentsLibraryButton />
+ <Invalidate />
+ </>,
+ { server },
);
await waitFor(() => {
@@ -293,15 +336,7 @@ describe('AgentsLibraryButton', () => {
}));
const server = mockServer(agents);
- render(
- <SlotsProvider>
- <ServerProvider server={server}>
- <ShellModeProvider>
- <AgentsLibraryButton />
- </ShellModeProvider>
- </ServerProvider>
- </SlotsProvider>,
- );
+ renderLibrary(<AgentsLibraryButton />, { server });
await waitFor(() => {
expect(screen.getByRole('button', { name: /Agents Library \(50\+\)/ })).toBeInTheDocument();
@@ -312,15 +347,7 @@ describe('AgentsLibraryButton', () => {
const searchAgents = vi.fn(async () => [{ name: 'alpha', agentId: 'alpha' }]);
const server = createMockAgentUIServer({ searchAgents });
- render(
- <SlotsProvider>
- <ServerProvider server={server}>
- <ShellModeProvider>
- <AgentsLibraryButton compact />
- </ShellModeProvider>
- </ServerProvider>
- </SlotsProvider>,
- );
+ renderLibrary(<AgentsLibraryButton compact />, { server });
expect(screen.getByRole('button', { name: 'Agents Library' })).toBeInTheDocument();
expect(searchAgents).not.toHaveBeenCalled();
diff --git a/packages/trueforge-ui/test/atoms/SessionsPage.test.tsx b/packages/trueforge-ui/test/atoms/SessionsPage.test.tsx
new file mode 100644
index 000000000..9d035de45
--- /dev/null
+++ b/packages/trueforge-ui/test/atoms/SessionsPage.test.tsx
@@ -0,0 +1,163 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { SessionsPage } from '@/atoms/agent-details/SessionsPage.js';
+import { ServerProvider } from '@/server/ServerContext.js';
+import { ShellModeProvider } from '@/server/ShellModeContext.js';
+import type { Session, SessionEventItem, SessionListEntry } from '@/server/types.js';
+import { SlotsProvider } from '@/theme/SlotsProvider.js';
+import { DEFAULT_SESSION_TIME_WINDOW_MS, SESSION_TIME_BUFFER_MS } from '@/utils/sessionShareUrl.js';
+import { toDateTimeLocalValue } from '@/utils/sessionTimePresets.js';
+import { createMockAgentUIServer } from '../server/mockServer.js';
+
+const namedRow: SessionListEntry = {
+ id: 'sess-1',
+ title: 'Named session',
+ createdAt: '2026-01-01T00:10:00.000Z',
+ updatedAt: '2026-01-01T00:12:00.000Z',
+ lastActivityAt: '2026-01-01T00:12:00.000Z',
+ metrics: { totalTurns: 1, totalCostInUsd: 0, totalDurationMs: 1000 },
+ agentName: 'release-notes-writer',
+};
+
+const draftRow: SessionListEntry = {
+ id: 'sess-draft',
+ title: 'Draft session',
+ createdAt: '2026-01-01T00:11:00.000Z',
+ updatedAt: '2026-01-01T00:11:30.000Z',
+ lastActivityAt: '2026-01-01T00:11:30.000Z',
+ metrics: { totalTurns: 1, totalCostInUsd: 0, totalDurationMs: 500 },
+};
+
+type ListSessionsRequest = {
+ agentId?: string;
+ startTimestamp?: string;
+ endTimestamp?: string;
+};
+
+function renderPage({
+ listSessions = vi.fn(async (_req?: ListSessionsRequest) => ({ data: [namedRow, draftRow] })),
+ listSessionEvents = vi.fn(async () => ({ data: [] as SessionEventItem[] })),
+ getSession = vi.fn(async (): Promise<Session> => ({
+ id: 'sess-1',
+ title: 'Named session',
+ isMutable: false,
+ createdAt: namedRow.createdAt,
+ updatedAt: namedRow.updatedAt,
+ })),
+}: {
+ listSessions?: (req?: ListSessionsRequest) => Promise<{ data: SessionListEntry[] }>;
+ listSessionEvents?: () => Promise<{ data: SessionEventItem[] }>;
+ getSession?: () => Promise<Session>;
+} = {}) {
+ const server = createMockAgentUIServer({
+ getSession,
+ searchAgents: vi.fn(async () => [
+ { agentId: 'agent-1', name: 'release-notes-writer', agentSpec: { model: { name: 'openai/gpt-5.1' } } },
+ ]),
+ sessions: { getAgent: vi.fn(), getCodeSnippets: vi.fn(), listSessions, listSessionEvents },
+ });
+ render(
+ <SlotsProvider>
+ <ServerProvider server={server}>
+ <ShellModeProvider>
+ <SessionsPage />
+ </ShellModeProvider>
+ </ServerProvider>
+ </SlotsProvider>,
+ );
+ return { listSessions, listSessionEvents, getSession };
+}
+
+describe('SessionsPage', () => {
+ afterEach(() => {
+ vi.restoreAllMocks();
+ window.history.replaceState(null, '', '/');
+ });
+
+ it('lists all user sessions without agent_id and applies the default time window', async () => {
+ const { listSessions } = renderPage();
+ expect(await screen.findByRole('heading', { name: 'Agent Sessions' })).toBeInTheDocument();
+ expect(await screen.findByText('Named session')).toBeInTheDocument();
+ expect(screen.getByText('Draft session')).toBeInTheDocument();
+ expect(screen.getByText('Draft')).toBeInTheDocument();
+ expect(listSessions).toHaveBeenCalledWith(
+ expect.objectContaining({
+ order: 'desc',
+ limit: 20,
+ startTimestamp: expect.any(String),
+ endTimestamp: expect.any(String),
+ }),
+ );
+ const request = vi.mocked(listSessions).mock.calls[0]?.[0];
+ expect(request).toEqual(
+ expect.objectContaining({
+ startTimestamp: expect.any(String),
+ endTimestamp: expect.any(String),
+ }),
+ );
+ expect(request?.agentId).toBeUndefined();
+ expect(request?.startTimestamp).toBeDefined();
+ expect(request?.endTimestamp).toBeDefined();
+ if (request?.startTimestamp == null || request.endTimestamp == null) {
+ throw new Error('expected listSessions time bounds');
+ }
+ expect(Date.parse(request.endTimestamp) - Date.parse(request.startTimestamp)).toBe(DEFAULT_SESSION_TIME_WINDOW_MS);
+ expect(window.location.search).toContain('view=sessions');
+ expect(screen.getByRole('button', { name: 'Last 30 days' })).toBeInTheDocument();
+ });
+
+ it('shows the custom range picker only after Custom Time Range is clicked', async () => {
+ renderPage();
+ const timeButton = await screen.findByRole('button', { name: 'Last 30 days' });
+ fireEvent.click(timeButton);
+ expect(screen.getByRole('button', { name: 'Custom Time Range' })).toBeInTheDocument();
+ expect(screen.queryByText('Select Time Range')).not.toBeInTheDocument();
+
+ fireEvent.click(screen.getByRole('button', { name: 'Custom Time Range' }));
+ expect(screen.getByText('Select Time Range')).toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Apply' })).toBeInTheDocument();
+ });
+
+ it('does not apply a custom range inverted by the 70-day clamp', async () => {
+ vi.spyOn(Date, 'now').mockReturnValue(Date.parse('2026-08-31T12:00:00.000Z'));
+ const listSessions = vi.fn(async () => ({ data: [namedRow, draftRow] }));
+ renderPage({ listSessions });
+ fireEvent.click(await screen.findByRole('button', { name: 'Last 30 days' }));
+ fireEvent.click(screen.getByRole('button', { name: 'Custom Time Range' }));
+ fireEvent.change(screen.getByLabelText('From'), {
+ target: { value: toDateTimeLocalValue(Date.parse('2026-05-01T00:00:00.000Z')) },
+ });
+ fireEvent.change(screen.getByLabelText('To'), {
+ target: { value: toDateTimeLocalValue(Date.parse('2026-05-02T00:00:00.000Z')) },
+ });
+ const requestsBeforeApply = listSessions.mock.calls.length;
+
+ fireEvent.click(screen.getByRole('button', { name: 'Apply' }));
+
+ expect(listSessions).toHaveBeenCalledTimes(requestsBeforeApply);
+ expect(screen.getByText('Select Time Range')).toBeInTheDocument();
+ });
+
+ it('writes a pinned time window when a session is opened and does not require the row to be scrolled into view', async () => {
+ const { listSessions } = renderPage();
+ const mockedListSessions = vi.mocked(listSessions);
+ const row = await screen.findByText('Named session');
+ const initialListRequest = mockedListSessions.mock.calls[0]?.[0];
+ fireEvent.click(row.closest('button') ?? row);
+ await waitFor(() => {
+ const params = new URLSearchParams(window.location.search);
+ expect(params.get('sessionId')).toBe('sess-1');
+ expect(params.get('view')).toBe('sessions');
+ expect(params.get('s_tw')).toBeNull();
+ const createdAtMs = Date.parse(namedRow.createdAt);
+ expect(params.get('s_sts')).toBe(String(createdAtMs - SESSION_TIME_BUFFER_MS));
+ expect(params.get('s_ets')).toBe(String(createdAtMs + SESSION_TIME_BUFFER_MS));
+ });
+ // Pinning makes refresh/deep-link boot find the selected row, but must not
+ // replace the active list filter during this mounted interaction.
+ expect(mockedListSessions.mock.calls.every(([request]) => request === initialListRequest)).toBe(true);
+ expect(screen.getByRole('heading', { name: 'Named session' })).toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui/test/atoms/primitives/Tooltip.test.tsx b/packages/trueforge-ui/test/atoms/primitives/Tooltip.test.tsx
index 6c45ddc8e..0f34a14f6 100644
--- a/packages/trueforge-ui/test/atoms/primitives/Tooltip.test.tsx
+++ b/packages/trueforge-ui/test/atoms/primitives/Tooltip.test.tsx
@@ -1,7 +1,7 @@
import { act, fireEvent, render, screen } from '@testing-library/react';
import { describe, expect, it, vi } from 'vitest';
-import { LightTooltip, Tooltip } from '@/atoms/primitives/Tooltip.js';
+import { clampCenteredTooltip, LightTooltip, Tooltip } from '@/atoms/primitives/Tooltip.js';
describe('Tooltip', () => {
it('shows and hides on hover while merging the child callbacks', () => {
@@ -31,6 +31,17 @@ describe('Tooltip', () => {
expect(screen.queryByRole('tooltip')).not.toBeInTheDocument();
});
+ it('does not render an empty tooltip shell', () => {
+ render(
+ <Tooltip content="">
+ <button>Chart</button>
+ </Tooltip>,
+ );
+
+ fireEvent.mouseEnter(screen.getByRole('button', { name: 'Chart' }));
+ expect(screen.queryByRole('tooltip')).not.toBeInTheDocument();
+ });
+
it('shows and hides on keyboard focus while merging the child callbacks', () => {
const onFocus = vi.fn();
const onBlur = vi.fn();
@@ -76,6 +87,62 @@ describe('Tooltip', () => {
expect(onClick).not.toHaveBeenCalled();
});
+ it('follows the cursor horizontally when followCursor is set', () => {
+ render(
+ <Tooltip content="Turn 1" side="bottom" followCursor>
+ <button>Chart</button>
+ </Tooltip>,
+ );
+
+ const trigger = screen.getByRole('button', { name: 'Chart' });
+ fireEvent.mouseEnter(trigger, { clientX: 240 });
+ expect(screen.getByRole('tooltip')).toHaveStyle({ left: '240px' });
+
+ fireEvent.mouseMove(trigger, { clientX: 410 });
+ expect(screen.getByRole('tooltip')).toHaveStyle({ left: '410px' });
+ });
+
+ it('pins the tooltip to explicit cursor-anchor coords', () => {
+ render(
+ <Tooltip content="Turn 1" side="bottom" followCursor anchor={{ left: 640, top: 120 }}>
+ <button>Chart</button>
+ </Tooltip>,
+ );
+
+ const trigger = screen.getByRole('button', { name: 'Chart' });
+ fireEvent.mouseEnter(trigger, { clientX: 240 });
+ expect(screen.getByRole('tooltip')).toHaveStyle({ left: '640px', top: '126px' });
+
+ fireEvent.mouseMove(trigger, { clientX: 410 });
+ expect(screen.getByRole('tooltip')).toHaveStyle({ left: '640px', top: '126px' });
+ });
+
+ it('clamps a centered tooltip so it stays inside the viewport', () => {
+ expect(
+ clampCenteredTooltip({
+ left: 800,
+ top: 40,
+ width: 320,
+ height: 80,
+ side: 'bottom',
+ viewportWidth: 900,
+ viewportHeight: 600,
+ }),
+ ).toEqual({ left: 732, top: 40 });
+
+ expect(
+ clampCenteredTooltip({
+ left: 10,
+ top: 40,
+ width: 200,
+ height: 80,
+ side: 'bottom',
+ viewportWidth: 900,
+ viewportHeight: 600,
+ }),
+ ).toEqual({ left: 108, top: 40 });
+ });
+
it('opens below the trigger when side is bottom', () => {
render(
<Tooltip content="Below tip" side="bottom">
@@ -91,6 +158,20 @@ describe('Tooltip', () => {
expect(tooltip.className).toMatch(/fixed/);
});
+ it('keeps the tooltip open on click when dismissOnClick is false', () => {
+ render(
+ <Tooltip content="Copy session link" dismissOnClick={false}>
+ <button>Link</button>
+ </Tooltip>,
+ );
+
+ const trigger = screen.getByRole('button', { name: 'Link' });
+ fireEvent.mouseEnter(trigger);
+ fireEvent.click(trigger);
+
+ expect(screen.getByRole('tooltip')).toHaveTextContent('Copy session link');
+ });
+
it('dismisses on click while still invoking the child handler', () => {
const onClick = vi.fn();
diff --git a/packages/trueforge-ui/test/containers/AgentSessionTimelineContainer.test.tsx b/packages/trueforge-ui/test/containers/AgentSessionTimelineContainer.test.tsx
new file mode 100644
index 000000000..7c9325944
--- /dev/null
+++ b/packages/trueforge-ui/test/containers/AgentSessionTimelineContainer.test.tsx
@@ -0,0 +1,77 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { AgentSessionTimelineContainer } from '@/containers/AgentSessionTimelineContainer.js';
+import { ServerProvider } from '@/server/ServerContext.js';
+import type { SessionEventItem } from '@/server/types.js';
+import { SlotsProvider } from '@/theme/SlotsProvider.js';
+import { createMockAgentUIServer } from '../server/mockServer.js';
+
+vi.mock('@truefoundry/assistant-ui-runtime', async () => {
+ const actual = await vi.importActual<typeof import('@truefoundry/assistant-ui-runtime')>(
+ '@truefoundry/assistant-ui-runtime',
+ );
+ return {
+ ...actual,
+ convertTurnsToThreadMessages: vi.fn(async () => ({ messages: [] })),
+ };
+});
+
+const events: SessionEventItem[] = [
+ {
+ turnId: 'turn-1',
+ event: {
+ type: 'turn.created',
+ id: 'c1',
+ turnId: 'turn-1',
+ previousTurnId: null,
+ input: [{ type: 'user.message', content: 'hello' }],
+ state: { status: 'running' },
+ createdAt: '2026-01-01T00:00:00.000Z',
+ threadId: null,
+ },
+ },
+ {
+ turnId: 'turn-1',
+ event: {
+ type: 'turn.done',
+ id: 'd1',
+ state: { status: 'done', completedAt: '2026-01-01T00:00:02.000Z', output: null, requiredActions: [] },
+ createdAt: '2026-01-01T00:00:02.000Z',
+ threadId: null,
+ },
+ },
+];
+
+describe('AgentSessionTimelineContainer', () => {
+ it('passes grouped turns to the timeline slot and scrolls on select', async () => {
+ const scrollIntoView = vi.fn();
+ HTMLElement.prototype.scrollIntoView = scrollIntoView;
+
+ render(
+ <SlotsProvider
+ overrides={{
+ AgentSessionEventTimeline: ({ turns, onSelectTurn }) => (
+ <button type="button" onClick={() => onSelectTurn?.(0)}>
+ {`timeline turns=${turns.length}`}
+ </button>
+ ),
+ }}
+ >
+ <ServerProvider server={createMockAgentUIServer()}>
+ <AgentSessionTimelineContainer sessionId="sess-1" events={events} />
+ </ServerProvider>
+ </SlotsProvider>,
+ );
+
+ expect(await screen.findByText('timeline turns=1')).toBeInTheDocument();
+ expect(await screen.findByText('Turn 1')).toBeInTheDocument();
+ expect(screen.getByText('Turns')).toBeInTheDocument();
+ expect(screen.getByText('Duration')).toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'timeline turns=1' }));
+ await waitFor(() => {
+ expect(scrollIntoView).toHaveBeenCalled();
+ });
+ });
+});
diff --git a/packages/trueforge-ui/test/containers/ThreadListContainer.pagination.test.tsx b/packages/trueforge-ui/test/containers/ThreadListContainer.pagination.test.tsx
index 27d607ec3..e84e4bf32 100644
--- a/packages/trueforge-ui/test/containers/ThreadListContainer.pagination.test.tsx
+++ b/packages/trueforge-ui/test/containers/ThreadListContainer.pagination.test.tsx
@@ -1,12 +1,13 @@
// @vitest-environment jsdom
-import { fireEvent, render, waitFor } from '@testing-library/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
import { StrictMode, type ReactNode } from 'react';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { ThreadListContainer } from '@/containers/ThreadListContainer.js';
-const { loadMore } = vi.hoisted(() => ({
+const { loadMore, setSessionsOpen } = vi.hoisted(() => ({
loadMore: vi.fn().mockResolvedValue(undefined),
+ setSessionsOpen: vi.fn(),
}));
let resizeCallback: ResizeObserverCallback | undefined;
@@ -74,6 +75,7 @@ vi.mock('@assistant-ui/react', () => ({
vi.mock('@/server/ServerContext.js', () => ({
useOptionalServer: () => undefined,
+ useOptionalAgentSessionsServer: () => null,
}));
vi.mock('@/server/ShellModeContext.js', () => ({
@@ -83,6 +85,8 @@ vi.mock('@/server/ShellModeContext.js', () => ({
isComposerEnabled: false,
mode: { status: 'active', isMutable: false, agentName: 'agent', agentId: 'agent', locked: false },
setSettingsOpen: vi.fn(),
+ setLibraryOpen: vi.fn(),
+ setSessionsOpen,
selectLibraryAgent: vi.fn(),
openDraft: vi.fn(),
openHistorySession: vi.fn(),
@@ -113,9 +117,18 @@ afterEach(() => {
vi.restoreAllMocks();
vi.unstubAllGlobals();
loadMore.mockReset().mockResolvedValue(undefined);
+ setSessionsOpen.mockReset();
});
describe('ThreadListContainer pagination', () => {
+ it('closes Sessions when selecting a thread', () => {
+ render(<ThreadListContainer />);
+
+ fireEvent.click(screen.getByRole('button', { name: 'Session' }));
+
+ expect(setSessionsOpen).toHaveBeenCalledWith(false);
+ });
+
it('remeasures when a hidden viewport becomes visible', async () => {
loadMore.mockClear();
const { container } = render(<ThreadListContainer />);
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
new file mode 100644
index 000000000..cf0f16e0d
--- /dev/null
+++ b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/agentSessionsServer.test.ts
@@ -0,0 +1,109 @@
+import type { TrueForge } from '@truefoundry/trueforge-sdk';
+import assert from 'node:assert/strict';
+import { describe, it, vi } from 'vitest';
+
+import { createHarnessAgentSessionsServer } from '@/plugins/trueforge-agent-server-adapter/agentSessionsServer.js';
+
+describe('createHarnessAgentSessionsServer', () => {
+ it('maps agent details and code snippets to the UI contract', async () => {
+ const get = vi.fn(async () => ({
+ data: {
+ id: 'agent-1',
+ name: 'writer',
+ manifest: { model: { name: 'openai/gpt-5' }, instructions: 'Write.' },
+ },
+ }));
+ const getCodeSnippets = vi.fn(async () => ({
+ data: {
+ baseUrl: 'https://trueforge.example',
+ snippets: [
+ {
+ labelName: 'TypeScript',
+ language: 'typescript',
+ icon: 'https://assets.example/typescript.svg',
+ sampleCode: { stream: 'stream()', nonStream: 'run()' },
+ },
+ ],
+ },
+ }));
+ const server = createHarnessAgentSessionsServer({
+ client: {
+ agents: { get },
+ internal: { agents: { getCodeSnippets } },
+ } as unknown as TrueForge,
+ });
+
+ assert.deepEqual(await server.getAgent({ agentId: 'agent-1' }), {
+ agentId: 'agent-1',
+ name: 'writer',
+ agentSpec: { model: { name: 'openai/gpt-5' }, instructions: 'Write.' },
+ });
+ assert.deepEqual(await server.getCodeSnippets({ agentId: 'agent-1' }), [
+ {
+ labelName: 'TypeScript',
+ language: 'typescript',
+ icon: 'https://assets.example/typescript.svg',
+ sampleCode: { stream: 'stream()', nonStream: 'run()' },
+ },
+ ]);
+ assert.deepEqual(get.mock.calls[0], ['agent-1']);
+ assert.deepEqual(getCodeSnippets.mock.calls[0], ['agent-1']);
+ });
+
+ it('maps listSessions and listSessionEvents onto the UI contract', async () => {
+ const list = vi.fn(async () => ({
+ data: [
+ {
+ id: 'sess-1',
+ title: 'hello',
+ createdAt: '2026-01-01T00:00:00.000Z',
+ updatedAt: '2026-01-02T00:00:00.000Z',
+ agent: {
+ type: 'reference',
+ id: 'agent-1',
+ name: 'writer',
+ },
+ createdBy: 'user-1',
+ },
+ ],
+ response: { pagination: { nextPageToken: 'next-1' } },
+ }));
+ const listEvents = vi.fn(async () => ({
+ data: [{ turnId: 'turn-1', event: { type: 'turn.created', id: 'evt-1', turnId: 'turn-1' } }],
+ response: { pagination: {} },
+ }));
+ const server = createHarnessAgentSessionsServer({
+ baseUrl: 'https://trueforge.example',
+ client: {
+ agents: {
+ get: vi.fn(async () => ({
+ data: { id: 'agent-1', name: 'writer', manifest: { model: { name: 'openai/gpt-5' } } },
+ })),
+ },
+ sessions: { list, listEvents },
+ } as unknown as TrueForge,
+ });
+
+ assert.deepEqual(await server.listSessions({ agentId: 'agent-1', limit: 10 }), {
+ data: [
+ {
+ id: 'sess-1',
+ title: 'hello',
+ 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 },
+ agentName: 'writer',
+ },
+ ],
+ nextPageToken: 'next-1',
+ });
+ assert.deepEqual(await server.listSessionEvents({ sessionId: 'sess-1', limit: 25 }), {
+ data: [{ turnId: 'turn-1', event: { type: 'turn.created', id: 'evt-1', turnId: 'turn-1' } }],
+ });
+ await assert.rejects(
+ () => server.listSessions({ startTimestamp: 'not-a-timestamp' }),
+ /Invalid ISO timestamp: not-a-timestamp/,
+ );
+ });
+});
diff --git a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/harnessServer.test.ts b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/harnessServer.test.ts
index da3dce514..b82b34117 100644
--- a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/harnessServer.test.ts
+++ b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/harnessServer.test.ts
@@ -285,4 +285,43 @@ describe('createHarnessChatServer', () => {
},
]);
});
+
+ it('fills missing turn.done metrics fields for the runtime contract', async () => {
+ const fetchGetTurn: typeof fetch = async (input, init) => {
+ const url = input instanceof Request ? input.url : String(input);
+ const method = init?.method ?? 'GET';
+ if (url.endsWith('/api/v1/sessions/ses_1/turns/trn_1') && method === 'GET') {
+ return Response.json({
+ data: {
+ id: 'trn_1',
+ session_id: 'ses_1',
+ previous_turn_id: null,
+ created_at: '2026-08-03T00:00:00.000Z',
+ state: {
+ status: 'done',
+ completed_at: '2026-08-03T00:00:01.000Z',
+ output: null,
+ required_actions: [],
+ metrics: { total_input_tokens: 12 },
+ },
+ },
+ });
+ }
+ return fetchMock(input, init);
+ };
+
+ const server = createHarnessChatServer({ fetch: fetchGetTurn });
+ const turn = await server.getTurn({ sessionId: 'ses_1', turnId: 'trn_1' });
+
+ assert.equal(turn.state.status, 'done');
+ if (turn.state.status !== 'done') throw new Error('expected done');
+ assert.deepEqual(turn.state.metrics, {
+ totalInputTokens: 12,
+ totalOutputTokens: 0,
+ totalTokens: 0,
+ totalCacheReadTokens: 0,
+ totalCacheWriteTokens: 0,
+ totalReasoningTokens: 0,
+ });
+ });
});
diff --git a/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/toUiTurnState.test.ts b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/toUiTurnState.test.ts
new file mode 100644
index 000000000..02d1e471e
--- /dev/null
+++ b/packages/trueforge-ui/test/plugins/trueforge-agent-server-adapter/toUiTurnState.test.ts
@@ -0,0 +1,43 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'vitest';
+
+import { toUiTurnDoneMetrics, toUiTurnState } from '@/plugins/trueforge-agent-server-adapter/toUiTurnState.js';
+
+describe('toUiTurnState', () => {
+ it('fills optional SDK token fields so TurnDoneMetrics is complete', () => {
+ assert.deepEqual(toUiTurnDoneMetrics({ totalInputTokens: 3, totalCostInUsd: 0.12 }), {
+ totalInputTokens: 3,
+ totalOutputTokens: 0,
+ totalTokens: 0,
+ totalCacheReadTokens: 0,
+ totalCacheWriteTokens: 0,
+ totalReasoningTokens: 0,
+ totalCostInUsd: 0.12,
+ });
+ });
+
+ it('maps a done state with partial metrics', () => {
+ assert.deepEqual(
+ toUiTurnState({
+ status: 'done',
+ completedAt: '2026-01-01T00:00:00.000Z',
+ output: null,
+ requiredActions: [],
+ metrics: { totalTokens: 10 },
+ }),
+ {
+ status: 'done',
+ completedAt: '2026-01-01T00:00:00.000Z',
+ requiredActions: [],
+ metrics: {
+ totalInputTokens: 0,
+ totalOutputTokens: 0,
+ totalTokens: 10,
+ totalCacheReadTokens: 0,
+ totalCacheWriteTokens: 0,
+ totalReasoningTokens: 0,
+ },
+ },
+ );
+ });
+});
diff --git a/packages/trueforge-ui/test/publicUiExports.test.ts b/packages/trueforge-ui/test/publicUiExports.test.ts
index aeb910515..b437d7d65 100644
--- a/packages/trueforge-ui/test/publicUiExports.test.ts
+++ b/packages/trueforge-ui/test/publicUiExports.test.ts
@@ -3,6 +3,13 @@ import { describe, expect, it } from 'vitest';
import * as sdk from '@/index.js';
const expectedRuntimeExports: Array<keyof typeof sdk> = [
+ 'AgentCodeBlock',
+ 'AgentDetailsHeader',
+ 'AgentDetailsPage',
+ 'AgentDetailsTabs',
+ 'AgentDetailsUnavailable',
+ 'AgentOverviewCard',
+ 'AgentSessionsFilters',
'AgentStepsCard',
'AgentStepsContainer',
'AgentsLibrary',
@@ -66,6 +73,8 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = [
'ScrollToBottomButton',
'SelectAgentEmptyState',
'ServerProvider',
+ 'SessionsBrowserButton',
+ 'SessionsPage',
'ShellActionsActionSlot',
'ShellModeProvider',
'SlotsProvider',
@@ -115,6 +124,7 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = [
'shellIsMutable',
'threadHasPendingMcpAuth',
'trueFoundryAttachmentAdapter',
+ 'useAgentSessionsServer',
'useAui',
'useAuiState',
'useBrand',
@@ -127,6 +137,7 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = [
'useToaster',
'useToasterOptional',
'useMCPAuth',
+ 'useOptionalAgentSessionsServer',
'useOptionalCatalogServer',
'useOptionalContentClassNames',
'useOptionalCustomActionRenderers',
diff --git a/packages/trueforge-ui/test/routing/LibrarySessionShareBoot.test.tsx b/packages/trueforge-ui/test/routing/LibrarySessionShareBoot.test.tsx
new file mode 100644
index 000000000..ae1e78c60
--- /dev/null
+++ b/packages/trueforge-ui/test/routing/LibrarySessionShareBoot.test.tsx
@@ -0,0 +1,56 @@
+// @vitest-environment jsdom
+import { render } from '@testing-library/react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { LibrarySessionShareBoot } from '@/routing/LibrarySessionShareBoot.js';
+import { ShellModeProvider, useShellMode } from '@/server/ShellModeContext.js';
+
+afterEach(() => {
+ window.history.replaceState(null, '', '/');
+});
+
+function Probe() {
+ const shell = useShellMode();
+ return (
+ <div>
+ <span>{shell.libraryAgentId ?? 'none'}</span>
+ <span>{shell.sessionsOpen ? 'sessions-open' : 'sessions-closed'}</span>
+ </div>
+ );
+}
+
+describe('LibrarySessionShareBoot', () => {
+ it('opens the library agent from ?agentId= without a router', () => {
+ window.history.replaceState(null, '', '/?agentId=agent-1&sessionId=sess-1');
+ const { getByText } = render(
+ <ShellModeProvider>
+ <LibrarySessionShareBoot />
+ <Probe />
+ </ShellModeProvider>,
+ );
+ expect(getByText('agent-1')).toBeInTheDocument();
+ });
+
+ it('leaves the library closed when the share query is absent', () => {
+ const { getByText } = render(
+ <ShellModeProvider>
+ <LibrarySessionShareBoot />
+ <Probe />
+ </ShellModeProvider>,
+ );
+ expect(getByText('none')).toBeInTheDocument();
+ expect(getByText('sessions-closed')).toBeInTheDocument();
+ });
+
+ it('opens the sessions browser from ?view=sessions without a router', () => {
+ window.history.replaceState(null, '', '/?view=sessions&agentId=agent-1');
+ const { getByText } = render(
+ <ShellModeProvider>
+ <LibrarySessionShareBoot />
+ <Probe />
+ </ShellModeProvider>,
+ );
+ expect(getByText('none')).toBeInTheDocument();
+ expect(getByText('sessions-open')).toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui/test/routing/ShellRouteSync.test.tsx b/packages/trueforge-ui/test/routing/ShellRouteSync.test.tsx
index c36623c42..03605774d 100644
--- a/packages/trueforge-ui/test/routing/ShellRouteSync.test.tsx
+++ b/packages/trueforge-ui/test/routing/ShellRouteSync.test.tsx
@@ -1,5 +1,5 @@
// @vitest-environment jsdom
-import { act, render } from '@testing-library/react';
+import { act, render, waitFor } from '@testing-library/react';
import { useEffect, useState } from 'react';
import { MemoryRouter, useLocation } from 'react-router-dom';
import { describe, expect, it } from 'vitest';
@@ -14,6 +14,7 @@ type Shell = ReturnType<typeof useShellMode>;
let shell: Shell;
let pathname = '';
+let search = '';
let setRemoteId: (id: string | undefined) => void = () => undefined;
function CaptureShell() {
@@ -24,9 +25,11 @@ function CaptureShell() {
function CaptureLocation() {
const location = useLocation();
pathname = location.pathname;
+ search = location.search;
useEffect(() => {
pathname = location.pathname;
- }, [location.pathname]);
+ search = location.search;
+ }, [location.pathname, location.search]);
return null;
}
@@ -85,6 +88,32 @@ describe('ShellRouteSync', () => {
expect(pathname).toBe('/');
});
+ it('mirrors library open/close through history', () => {
+ renderSync({ initialEntries: ['/'], agentConfig: { mode: 'AgentLibraryWithComposer' } });
+ act(() => shell.setLibraryOpen(true));
+ expect(pathname).toBe('/library');
+ act(() => shell.setLibraryOpen(false));
+ expect(pathname).toBe('/');
+ });
+
+ it('mirrors library agent detail through history', () => {
+ renderSync({ initialEntries: ['/'], agentConfig: { mode: 'AgentLibraryWithComposer' } });
+ act(() => shell.openLibraryAgent('agent/id'));
+ expect(pathname).toBe('/library/agent%2Fid');
+ expect(shell.libraryAgentId).toBe('agent/id');
+ act(() => shell.closeLibraryAgent());
+ expect(pathname).toBe('/library');
+ });
+
+ it('closes the library when selecting a session from the overlay', () => {
+ renderSync({ initialEntries: ['/library'], agentConfig: { mode: 'AgentLibraryWithComposer' } });
+ expect(shell.libraryOpen).toBe(true);
+ expect(pathname).toBe('/library');
+ act(() => shell.openHistorySession({ sessionId: 'sess-1', isMutable: false, agentName: 'helper' }));
+ expect(shell.libraryOpen).toBe(false);
+ expect(pathname).toBe('/sessions/sess-1');
+ });
+
it('replaces to the session path when a fresh chat acquires a remote id', () => {
render(
<MemoryRouter initialEntries={['/']}>
@@ -115,4 +144,33 @@ describe('ShellRouteSync', () => {
act(() => shell.setSettingsOpen(false));
expect(pathname).toBe('/');
});
+
+ it('opens library on boot from a /library deep link', () => {
+ renderSync({ initialEntries: ['/library'], agentConfig: { mode: 'AgentLibraryWithComposer' } });
+ expect(shell.libraryOpen).toBe(true);
+ expect(pathname).toBe('/library');
+ });
+
+ it('clears stale session query state from the library URL while preserving host keys', async () => {
+ renderSync({
+ initialEntries: ['/library?theme=dark&sessionId=sess-1&agentId=agent-1&s_sts=1&s_ets=2'],
+ agentConfig: { mode: 'AgentLibraryWithComposer' },
+ });
+ expect(pathname).toBe('/library');
+ await waitFor(() => expect(search).toBe('?theme=dark'));
+ });
+
+ it('opens agent details on boot from a /library/:agentId deep link', () => {
+ renderSync({ initialEntries: ['/library/agent-7'], agentConfig: { mode: 'AgentLibraryWithComposer' } });
+ expect(shell.libraryOpen).toBe(true);
+ expect(shell.libraryAgentId).toBe('agent-7');
+ expect(pathname).toBe('/library/agent-7');
+ });
+
+ it('returns to the chat place when a /library deep link is closed', () => {
+ renderSync({ initialEntries: ['/library'], agentConfig: { mode: 'AgentLibraryWithComposer' } });
+ expect(shell.libraryOpen).toBe(true);
+ act(() => shell.setLibraryOpen(false));
+ expect(pathname).toBe('/');
+ });
});
diff --git a/packages/trueforge-ui/test/routing/derivePlace.test.ts b/packages/trueforge-ui/test/routing/derivePlace.test.ts
index 5d4dfb757..efe8cd4d6 100644
--- a/packages/trueforge-ui/test/routing/derivePlace.test.ts
+++ b/packages/trueforge-ui/test/routing/derivePlace.test.ts
@@ -6,6 +6,9 @@ import type { ShellSnapshot } from '@/routing/types.js';
function snap(partial: Partial<ShellSnapshot>): ShellSnapshot {
return {
settingsOpen: false,
+ libraryOpen: false,
+ sessionsOpen: false,
+ libraryAgentId: null,
mode: { status: 'idle' },
agentConfigMode: 'AgentLibraryWithComposer',
...partial,
@@ -17,6 +20,25 @@ describe('derivePlace', () => {
expect(derivePlace(snap({ settingsOpen: true, pendingSessionId: 'abc' }))).toEqual({ type: 'settings' });
});
+ it('library overlay wins over the chat place when settings is closed', () => {
+ expect(derivePlace(snap({ libraryOpen: true, pendingSessionId: 'abc' }))).toEqual({ type: 'library' });
+ });
+
+ it('sessions browser wins over the chat place when settings is closed', () => {
+ expect(derivePlace(snap({ sessionsOpen: true, pendingSessionId: 'abc' }))).toEqual({ type: 'sessionsBrowser' });
+ });
+
+ it('library agent detail wins over the library list and chat place', () => {
+ expect(derivePlace(snap({ libraryOpen: true, libraryAgentId: 'agent-1', pendingSessionId: 'abc' }))).toEqual({
+ type: 'libraryAgent',
+ agentId: 'agent-1',
+ });
+ });
+
+ it('settings overlay wins over library', () => {
+ expect(derivePlace(snap({ settingsOpen: true, libraryOpen: true }))).toEqual({ type: 'settings' });
+ });
+
it('pendingSessionId maps to a session while no thread has reported yet', () => {
expect(derivePlace(snap({ pendingSessionId: 'abc' }))).toEqual({ type: 'session', sessionId: 'abc' });
});
diff --git a/packages/trueforge-ui/test/routing/paths.test.ts b/packages/trueforge-ui/test/routing/paths.test.ts
index d68e15471..78c005ff5 100644
--- a/packages/trueforge-ui/test/routing/paths.test.ts
+++ b/packages/trueforge-ui/test/routing/paths.test.ts
@@ -1,6 +1,13 @@
import { describe, expect, it } from 'vitest';
-import { buildPath, matchPath, placesEqual, resolveRoutesConfig } from '@/routing/paths.js';
+import {
+ buildPath,
+ matchLocation,
+ matchPath,
+ placesEqual,
+ resolveRoutesConfig,
+ sanitizeSearchForPlace,
+} from '@/routing/paths.js';
describe('resolveRoutesConfig', () => {
it('applies defaults', () => {
@@ -8,8 +15,11 @@ describe('resolveRoutesConfig', () => {
basename: '',
root: '/',
settings: '/settings',
+ library: '/library',
+ libraryAgent: '/library/:agentId',
agent: '/agents/:agentName',
session: '/sessions/:sessionId',
+ sessionsBrowser: '/sessions',
});
});
@@ -38,8 +48,11 @@ describe('buildPath', () => {
it('builds each place', () => {
expect(buildPath({ type: 'root' }, routes)).toBe('/');
expect(buildPath({ type: 'settings' }, routes)).toBe('/settings');
+ expect(buildPath({ type: 'library' }, routes)).toBe('/library');
+ expect(buildPath({ type: 'libraryAgent', agentId: 'agent/id' }, routes)).toBe('/library/agent%2Fid');
expect(buildPath({ type: 'agent', agentName: 'code-helper' }, routes)).toBe('/agents/code-helper');
expect(buildPath({ type: 'session', sessionId: 'abc123' }, routes)).toBe('/sessions/abc123');
+ expect(buildPath({ type: 'sessionsBrowser' }, routes)).toBe('/sessions');
});
it('encodes param values', () => {
@@ -47,19 +60,49 @@ describe('buildPath', () => {
});
it('returns null for disabled places', () => {
- const disabled = resolveRoutesConfig({ paths: { settings: false, agent: false } });
+ const disabled = resolveRoutesConfig({
+ paths: { settings: false, library: false, libraryAgent: false, agent: false },
+ });
expect(buildPath({ type: 'settings' }, disabled)).toBeNull();
+ expect(buildPath({ type: 'library' }, disabled)).toBeNull();
+ expect(buildPath({ type: 'libraryAgent', agentId: 'x' }, disabled)).toBeNull();
expect(buildPath({ type: 'agent', agentName: 'x' }, disabled)).toBeNull();
});
});
+describe('sanitizeSearchForPlace', () => {
+ const sessionSearch = '?theme=dark&sessionId=sess-1&agentId=agent-1&tab=sessions&view=sessions&s_sts=1&s_ets=2';
+
+ it('clears session-owned query keys on unrelated places without dropping host keys', () => {
+ expect(sanitizeSearchForPlace({ type: 'library' }, sessionSearch)).toBe('?theme=dark');
+ expect(sanitizeSearchForPlace({ type: 'root' }, sessionSearch)).toBe('?theme=dark');
+ expect(sanitizeSearchForPlace({ type: 'session', sessionId: 'sess-2' }, sessionSearch)).toBe('?theme=dark');
+ });
+
+ it('keeps only the query state owned by the destination place', () => {
+ expect(sanitizeSearchForPlace({ type: 'sessionsBrowser' }, sessionSearch)).toBe(
+ '?theme=dark&sessionId=sess-1&agentId=agent-1&view=sessions&s_sts=1&s_ets=2',
+ );
+ expect(sanitizeSearchForPlace({ type: 'libraryAgent', agentId: 'agent-1' }, sessionSearch)).toBe(
+ '?theme=dark&sessionId=sess-1&agentId=agent-1&tab=sessions',
+ );
+ expect(sanitizeSearchForPlace({ type: 'libraryAgent', agentId: 'agent-2' }, sessionSearch)).toBe(
+ '?theme=dark&tab=sessions',
+ );
+ expect(sanitizeSearchForPlace({ type: 'settings' }, sessionSearch)).toBe(sessionSearch);
+ });
+});
+
describe('matchPath', () => {
const routes = resolveRoutesConfig();
it('matches each place and decodes params', () => {
expect(matchPath('/', routes)).toEqual({ type: 'root' });
expect(matchPath('/settings', routes)).toEqual({ type: 'settings' });
+ expect(matchPath('/library', routes)).toEqual({ type: 'library' });
+ expect(matchPath('/library/agent%2Fid', routes)).toEqual({ type: 'libraryAgent', agentId: 'agent/id' });
expect(matchPath('/agents/a%2Fb', routes)).toEqual({ type: 'agent', agentName: 'a/b' });
+ expect(matchPath('/sessions', routes)).toEqual({ type: 'sessionsBrowser' });
expect(matchPath('/sessions/xyz', routes)).toEqual({ type: 'session', sessionId: 'xyz' });
});
@@ -84,8 +127,11 @@ describe('matchPath', () => {
for (const place of [
{ type: 'root' as const },
{ type: 'settings' as const },
+ { type: 'library' as const },
+ { type: 'libraryAgent' as const, agentId: 'agent id/1' },
{ type: 'agent' as const, agentName: 'weird name/1' },
{ type: 'session' as const, sessionId: 'sess 9' },
+ { type: 'sessionsBrowser' as const },
]) {
const path = buildPath(place, routes);
if (path == null) throw new Error(`Expected a path for ${place.type}`);
@@ -94,11 +140,33 @@ describe('matchPath', () => {
});
});
+describe('matchLocation', () => {
+ const routes = resolveRoutesConfig();
+
+ it('opens a library agent from ?agentId= when the path is root', () => {
+ expect(matchLocation({ pathname: '/', search: '?agentId=agent-1&sessionId=sess-1', routes })).toEqual({
+ type: 'libraryAgent',
+ agentId: 'agent-1',
+ });
+ });
+
+ it('keeps a concrete pathname over the share query', () => {
+ expect(matchLocation({ pathname: '/sessions/sess-1', search: '?agentId=agent-1', routes })).toEqual({
+ type: 'session',
+ sessionId: 'sess-1',
+ });
+ expect(matchLocation({ pathname: '/sessions', search: '?agentId=agent-1&view=sessions', routes })).toEqual({
+ type: 'sessionsBrowser',
+ });
+ });
+});
+
describe('placesEqual', () => {
it('compares type and params', () => {
expect(placesEqual({ type: 'root' }, { type: 'root' })).toBe(true);
expect(placesEqual({ type: 'agent', agentName: 'a' }, { type: 'agent', agentName: 'a' })).toBe(true);
expect(placesEqual({ type: 'agent', agentName: 'a' }, { type: 'agent', agentName: 'b' })).toBe(false);
+ expect(placesEqual({ type: 'libraryAgent', agentId: 'a' }, { type: 'libraryAgent', agentId: 'a' })).toBe(true);
expect(placesEqual({ type: 'session', sessionId: '1' }, { type: 'root' })).toBe(false);
});
});
diff --git a/packages/trueforge-ui/test/routing/withRouter.integration.test.tsx b/packages/trueforge-ui/test/routing/withRouter.integration.test.tsx
index 8441653fb..968067016 100644
--- a/packages/trueforge-ui/test/routing/withRouter.integration.test.tsx
+++ b/packages/trueforge-ui/test/routing/withRouter.integration.test.tsx
@@ -4,7 +4,7 @@ import { fireEvent, render, screen, waitFor } from '@testing-library/react';
import { useState } from 'react';
import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
-import { createMockAgentUIServer } from '../server/mockServer.js';
+import { createMockAgentSessionsServer, createMockAgentUIServer } from '../server/mockServer.js';
/** Thread list driven by the test: a local draft plus one remote session row. */
const threadState = {
@@ -54,10 +54,12 @@ vi.mock('@truefoundry/assistant-ui-runtime', () => ({
}));
import { CompactLayoutProvider } from '@/atoms/lib/CompactLayoutContext.js';
+import { SessionsBrowserButton } from '@/atoms/SessionsBrowserButton.js';
import type { ThreadListRowProps } from '@/atoms/ThreadListRow.js';
import { ThreadListContainer } from '@/containers/ThreadListContainer.js';
import { TrueForgeUI } from '@/containers/TrueForgeUI.js';
import { useShellMode } from '@/server/ShellModeContext.js';
+import { DEFAULT_SESSION_TIME_WINDOW_MS } from '@/utils/sessionShareUrl.js';
beforeAll(() => {
HTMLDialogElement.prototype.showModal = function showModal() {
@@ -183,4 +185,29 @@ describe('withRouter end to end', () => {
expect(window.location.pathname).toBe('/sessions/session-2');
});
});
+
+ it('keeps the latest share query when opening Sessions from an agent route', async () => {
+ window.history.replaceState(null, '', '/library/agent-1?agentId=agent-1&sessionId=stale&s_sts=1&s_ets=2');
+ render(
+ <TrueForgeUI
+ server={createMockAgentUIServer({ sessions: createMockAgentSessionsServer() })}
+ agentConfig={{ mode: 'AgentLibraryWithComposer' }}
+ withRouter
+ layout={() => <SessionsBrowserButton />}
+ />,
+ );
+
+ fireEvent.click(await screen.findByRole('button', { name: 'Sessions' }));
+
+ await waitFor(() => {
+ expect(window.location.pathname).toBe('/sessions');
+ const params = new URL(window.location.href).searchParams;
+ expect(params.get('view')).toBe('sessions');
+ expect(params.get('sessionId')).toBeNull();
+ expect(params.get('agentId')).toBeNull();
+ expect(params.get('s_tw')).toBe(String(DEFAULT_SESSION_TIME_WINDOW_MS));
+ expect(params.get('s_sts')).toBeNull();
+ expect(params.get('s_ets')).toBeNull();
+ });
+ });
});
diff --git a/packages/trueforge-ui/test/server/ServerContext.test.tsx b/packages/trueforge-ui/test/server/ServerContext.test.tsx
index a12c7f849..a01253c9a 100644
--- a/packages/trueforge-ui/test/server/ServerContext.test.tsx
+++ b/packages/trueforge-ui/test/server/ServerContext.test.tsx
@@ -5,7 +5,9 @@ import { describe, expect, it, vi } from 'vitest';
import {
ServerProvider,
+ useAgentSessionsServer,
useCatalogServer,
+ useOptionalAgentSessionsServer,
useOptionalCatalogServer,
useOptionalRefreshServerCapabilities,
useOptionalServer,
@@ -164,4 +166,27 @@ describe('useCatalogServer', () => {
});
expect(result.current).toBeNull();
});
+
+ it('provides the optional agent sessions server', () => {
+ const sessions = {
+ getAgent: vi.fn(),
+ getCodeSnippets: vi.fn(),
+ listSessions: vi.fn(async () => ({ data: [] })),
+ listSessionEvents: vi.fn(async () => ({ data: [] })),
+ };
+ const server = createMockAgentUIServer({ sessions });
+ const required = renderHook(() => useAgentSessionsServer(), { wrapper: wrap(server) });
+ const optional = renderHook(() => useOptionalAgentSessionsServer(), { wrapper: wrap(server) });
+ expect(required.result.current).toBe(sessions);
+ expect(optional.result.current).toBe(sessions);
+ });
+
+ it('handles an omitted agent sessions server', () => {
+ const server = createMockAgentUIServer();
+ expect(() => renderHook(() => useAgentSessionsServer(), { wrapper: wrap(server) })).toThrow(
+ /requires AgentUIServer\.sessions/,
+ );
+ const { result } = renderHook(() => useOptionalAgentSessionsServer(), { wrapper: wrap(server) });
+ expect(result.current).toBeNull();
+ });
});
diff --git a/packages/trueforge-ui/test/server/ShellModeContext.test.tsx b/packages/trueforge-ui/test/server/ShellModeContext.test.tsx
index de1de30be..8f850663b 100644
--- a/packages/trueforge-ui/test/server/ShellModeContext.test.tsx
+++ b/packages/trueforge-ui/test/server/ShellModeContext.test.tsx
@@ -68,6 +68,41 @@ describe('ShellModeProvider', () => {
expect(result.current.settingsSection).toBe('connectors');
});
+ it('closes the library when settings opens and vice versa', () => {
+ const { result } = renderHook(() => useShellMode(), { wrapper: wrap() });
+
+ act(() => result.current.setLibraryOpen(true));
+ expect(result.current.libraryOpen).toBe(true);
+ expect(result.current.settingsOpen).toBe(false);
+
+ act(() => result.current.setSettingsOpen(true));
+ expect(result.current.settingsOpen).toBe(true);
+ expect(result.current.libraryOpen).toBe(false);
+
+ act(() => result.current.setLibraryOpen(true));
+ expect(result.current.libraryOpen).toBe(true);
+ expect(result.current.settingsOpen).toBe(false);
+ });
+
+ it('opens agent details and returns to the library list', () => {
+ const { result } = renderHook(() => useShellMode(), { wrapper: wrap() });
+
+ act(() => result.current.openLibraryAgent('agent-1'));
+ expect(result.current.libraryOpen).toBe(true);
+ expect(result.current.libraryAgentId).toBe('agent-1');
+
+ act(() => result.current.closeLibraryAgent());
+ expect(result.current.libraryOpen).toBe(true);
+ expect(result.current.libraryAgentId).toBeNull();
+
+ act(() => result.current.setLibraryAgentId('agent-2'));
+ expect(result.current.libraryAgentId).toBe('agent-2');
+
+ act(() => result.current.setLibraryOpen(false));
+ expect(result.current.libraryOpen).toBe(false);
+ expect(result.current.libraryAgentId).toBeNull();
+ });
+
it('defaults to AgentLibraryWithComposer (mutable + library)', () => {
const { result } = renderHook(() => useShellMode(), { wrapper: wrap() });
expect(result.current.mode).toMatchObject({ status: 'active', isMutable: true, locked: false });
diff --git a/packages/trueforge-ui/test/server/createTrueFoundryServer.test.ts b/packages/trueforge-ui/test/server/createTrueFoundryServer.test.ts
index a40c26614..3e07de2f0 100644
--- a/packages/trueforge-ui/test/server/createTrueFoundryServer.test.ts
+++ b/packages/trueforge-ui/test/server/createTrueFoundryServer.test.ts
@@ -35,6 +35,12 @@ describe('createTrueFoundryServer', () => {
const getMcp = vi.fn(async () => []);
const searchAgents = vi.fn(async () => [{ name: 'ask-ai-agent', agentId: 'ask-ai-agent' }]);
const saveAgent = vi.fn(async (): Promise<SaveAgentResult> => ({ agentId: 'agent-1' }));
+ const sessions = {
+ getAgent: vi.fn(),
+ getCodeSnippets: vi.fn(),
+ listSessions: vi.fn(async () => ({ data: [] })),
+ listSessionEvents: vi.fn(async () => ({ data: [] })),
+ };
const server = createTrueFoundryServer({
chatServer,
@@ -44,11 +50,13 @@ describe('createTrueFoundryServer', () => {
getMcp,
searchAgents,
saveAgent,
+ sessions,
});
expect(server.createSession).toBe(chatServer.createSession);
expect(server.listSessions).toBe(chatServer.listSessions);
expect(server.catalog).toBeUndefined();
+ expect(server.sessions).toBe(sessions);
await expect(server.getCapabilities()).resolves.toEqual(capabilities);
await expect(server.getModels()).resolves.toHaveLength(1);
diff --git a/packages/trueforge-ui/test/server/mockServer.ts b/packages/trueforge-ui/test/server/mockServer.ts
index 5cce475c4..473308ffc 100644
--- a/packages/trueforge-ui/test/server/mockServer.ts
+++ b/packages/trueforge-ui/test/server/mockServer.ts
@@ -1,4 +1,4 @@
-import type { AgentUIServer, CatalogServer } from '@/server/types.js';
+import type { AgentSessionsServer, AgentUIServer, CatalogServer } from '@/server/types.js';
async function unavailable(): Promise<never> {
throw new Error('Unexpected mock server call');
@@ -28,6 +28,16 @@ export function createMockCatalog(overrides: Partial<CatalogServer> = {}): Catal
};
}
+export function createMockAgentSessionsServer(overrides: Partial<AgentSessionsServer> = {}): AgentSessionsServer {
+ return {
+ getAgent: unavailable,
+ getCodeSnippets: async () => [],
+ listSessions: async () => ({ data: [] }),
+ listSessionEvents: async () => ({ data: [] }),
+ ...overrides,
+ };
+}
+
export function createMockAgentUIServer(overrides: Partial<AgentUIServer> = {}): AgentUIServer {
return {
createSession: unavailable,
diff --git a/packages/trueforge-ui/test/utils/sessionAgentDetails.test.ts b/packages/trueforge-ui/test/utils/sessionAgentDetails.test.ts
new file mode 100644
index 000000000..83bd2faf4
--- /dev/null
+++ b/packages/trueforge-ui/test/utils/sessionAgentDetails.test.ts
@@ -0,0 +1,263 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'vitest';
+
+import type { SessionEventItem } from '@/server/types.js';
+import {
+ formatCostUsd,
+ formatDurationMs,
+ formatSessionListMetrics,
+ formatTokenCount,
+} from '@/utils/sessionDisplayFormat.js';
+import { buildSessionTurnViews } from '@/utils/sessionTurnViews.js';
+
+type TurnCreatedEvent = Extract<SessionEventItem['event'], { type: 'turn.created' }>;
+type TurnDoneEvent = Extract<SessionEventItem['event'], { type: 'turn.done' }>;
+
+function createdItem({
+ turnId,
+ createdAt,
+ input,
+}: {
+ turnId: string;
+ createdAt: string;
+ input?: TurnCreatedEvent['input'];
+}): SessionEventItem {
+ return {
+ turnId,
+ event: {
+ type: 'turn.created',
+ id: `${turnId}-created`,
+ turnId,
+ previousTurnId: null,
+ input,
+ state: { status: 'running' },
+ createdAt,
+ threadId: null,
+ },
+ };
+}
+
+function doneItem({
+ turnId,
+ createdAt,
+ state,
+}: {
+ turnId: string;
+ createdAt: string;
+ state: TurnDoneEvent['state'];
+}): SessionEventItem {
+ return {
+ turnId,
+ event: {
+ type: 'turn.done',
+ id: `${turnId}-done`,
+ state,
+ createdAt,
+ threadId: null,
+ },
+ };
+}
+
+function messageItem({ turnId, id, createdAt }: { turnId: string; id: string; createdAt: string }): SessionEventItem {
+ return {
+ turnId,
+ event: {
+ type: 'model.message',
+ id,
+ threadId: 'main',
+ content: id,
+ createdAt,
+ },
+ };
+}
+
+describe('sessionDisplayFormat', () => {
+ it('formats list metrics like the sessions mock', () => {
+ assert.equal(
+ formatSessionListMetrics({ totalTurns: 5, totalCostInUsd: 0.1615, totalDurationMs: 41_380 }),
+ '5 turns | $0.1615 | 41.38s',
+ );
+ assert.equal(formatTokenCount(122_000), '122K');
+ assert.equal(formatCostUsd(1.4872), '$1.4872');
+ assert.equal(formatDurationMs(76_800), '1.28m');
+ });
+});
+
+describe('buildSessionTurnViews', () => {
+ it('pairs interleaved lifecycle events and sorts turns and their events', () => {
+ const doneState = {
+ status: 'done',
+ completedAt: '2026-01-01T00:01:00.000Z',
+ output: null,
+ requiredActions: [],
+ metrics: {
+ totalTokens: 122_000,
+ totalCostInUsd: 1.4872,
+ totalInputTokens: 0,
+ totalOutputTokens: 0,
+ totalCacheReadTokens: 0,
+ totalCacheWriteTokens: 0,
+ totalReasoningTokens: 0,
+ },
+ } satisfies TurnDoneEvent['state'] & {
+ metrics: { totalTokens: number; totalCostInUsd: number };
+ };
+ const itemsAsc: SessionEventItem[] = [
+ createdItem({
+ turnId: 'turn-2',
+ createdAt: '2026-01-01T00:00:10.000Z',
+ input: [{ type: 'user.message', content: 'second' }],
+ }),
+ createdItem({
+ turnId: 'turn-1',
+ createdAt: '2026-01-01T00:00:00.000Z',
+ input: [{ type: 'user.message', content: 'first' }],
+ }),
+ messageItem({ turnId: 'turn-2', id: 'later', createdAt: '2026-01-01T00:00:40.000Z' }),
+ doneItem({ turnId: 'turn-1', createdAt: '2026-01-01T00:01:00.000Z', state: doneState }),
+ messageItem({ turnId: 'turn-2', id: 'earlier', createdAt: '2026-01-01T00:00:20.000Z' }),
+ doneItem({ turnId: 'turn-2', createdAt: '2026-01-01T00:01:10.000Z', state: doneState }),
+ ];
+
+ const views = buildSessionTurnViews(itemsAsc);
+ assert.deepEqual(
+ views.map(({ turnId, turnNumber, showHeader, durationMs, totalTokens, totalCostInUsd }) => ({
+ turnId,
+ turnNumber,
+ showHeader,
+ durationMs,
+ totalTokens,
+ totalCostInUsd,
+ })),
+ [
+ {
+ turnId: 'turn-1',
+ turnNumber: 1,
+ showHeader: true,
+ durationMs: 60_000,
+ totalTokens: 122_000,
+ totalCostInUsd: 1.4872,
+ },
+ {
+ turnId: 'turn-2',
+ turnNumber: 2,
+ showHeader: true,
+ durationMs: 60_000,
+ totalTokens: 122_000,
+ totalCostInUsd: 1.4872,
+ },
+ ],
+ );
+ assert.deepEqual(
+ views[1]?.events.map(event => event.id),
+ ['earlier', 'later'],
+ );
+ assert.equal(views[0]?.created.turnId, 'turn-1');
+ assert.equal(views[0]?.done?.id, 'turn-1-done');
+ });
+
+ it('ignores terminal and content events without turn.created', () => {
+ const terminalState = {
+ status: 'cancelled',
+ reason: 'stopped',
+ completedAt: '2026-01-01T00:00:02.000Z',
+ } satisfies TurnDoneEvent['state'];
+
+ assert.deepEqual(
+ buildSessionTurnViews([
+ doneItem({ turnId: 'orphan', createdAt: '2026-01-01T00:00:02.000Z', state: terminalState }),
+ messageItem({ turnId: 'orphan', id: 'orphan-message', createdAt: '2026-01-01T00:00:01.000Z' }),
+ ]),
+ [],
+ );
+ });
+
+ it('includes running and resume-only turns', () => {
+ const views = buildSessionTurnViews([
+ createdItem({
+ turnId: 'normal',
+ createdAt: '2026-01-01T00:00:00.000Z',
+ input: [{ type: 'user.message', content: 'hello' }],
+ }),
+ createdItem({
+ turnId: 'resume',
+ createdAt: '2026-01-01T00:00:05.000Z',
+ input: [
+ {
+ type: 'user.tool_response',
+ threadId: 'main',
+ toolCallId: 'call-1',
+ content: 'approved result',
+ },
+ ],
+ }),
+ ]);
+
+ assert.deepEqual(
+ views.map(view => ({
+ turnId: view.turnId,
+ turnNumber: view.turnNumber,
+ status: view.created.state?.status,
+ durationMs: view.durationMs,
+ })),
+ [
+ { turnId: 'normal', turnNumber: 1, status: 'running', durationMs: undefined },
+ { turnId: 'resume', turnNumber: 2, status: 'running', durationMs: undefined },
+ ],
+ );
+ assert.equal(views[1]?.created.input?.[0]?.type, 'user.tool_response');
+ });
+
+ it('derives duration and metrics from error terminal state', () => {
+ const errorState = {
+ status: 'error',
+ message: 'model failed',
+ completedAt: '2026-01-01T00:00:03.000Z',
+ metrics: { totalTokens: 7, totalCostInUsd: 0.25 },
+ } satisfies TurnDoneEvent['state'] & {
+ metrics: { totalTokens: number; totalCostInUsd: number };
+ };
+
+ const views = buildSessionTurnViews([
+ createdItem({
+ turnId: 'failed',
+ createdAt: '2026-01-01T00:00:01.000Z',
+ input: [{ type: 'user.message', content: 'retry' }],
+ }),
+ doneItem({ turnId: 'failed', createdAt: '2026-01-01T00:00:03.000Z', state: errorState }),
+ ]);
+
+ assert.deepEqual(
+ views.map(({ turnId, durationMs, totalTokens, totalCostInUsd }) => ({
+ turnId,
+ durationMs,
+ totalTokens,
+ totalCostInUsd,
+ })),
+ [
+ {
+ turnId: 'failed',
+ durationMs: 2_000,
+ totalTokens: 7,
+ totalCostInUsd: 0.25,
+ },
+ ],
+ );
+ });
+
+ it('skips turns that have no renderable user input', () => {
+ assert.deepEqual(
+ buildSessionTurnViews([
+ createdItem({ turnId: 'hidden', createdAt: '2026-01-01T00:00:00.000Z' }),
+ createdItem({
+ turnId: 'shown',
+ createdAt: '2026-01-01T00:00:01.000Z',
+ input: [
+ { type: 'user.tool_approval', threadId: 'main', toolCallId: 'call-1', approval: { status: 'allow' } },
+ ],
+ }),
+ ]).map(view => view.turnId),
+ ['shown'],
+ );
+ });
+});
diff --git a/packages/trueforge-ui/test/utils/sessionEventTimeline.test.ts b/packages/trueforge-ui/test/utils/sessionEventTimeline.test.ts
new file mode 100644
index 000000000..039db30b6
--- /dev/null
+++ b/packages/trueforge-ui/test/utils/sessionEventTimeline.test.ts
@@ -0,0 +1,330 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'vitest';
+
+import type { SessionEventItem } from '@/server/types.js';
+import { buildSessionMetrics } from '@/utils/buildSessionMetrics.js';
+import { buildSessionTimelineSegments } from '@/utils/buildSessionTimelineSegments.js';
+import type { SessionEventTimelineSegment } from '@/utils/sessionEventTimeline.js';
+import {
+ buildTimelineAxisTicks,
+ compressInterTurnGaps,
+ getActiveTimelineMs,
+ getSubAgentLanes,
+ groupOverlappingToolCalls,
+ pickLongestNonOverlappingSegments,
+} from '@/utils/sessionEventTimelineChart.js';
+import { buildSessionTurnViews } from '@/utils/sessionTurnViews.js';
+
+function created({
+ turnId,
+ createdAt,
+ content = 'hello',
+}: {
+ turnId: string;
+ createdAt: string;
+ content?: string;
+}): SessionEventItem {
+ return {
+ turnId,
+ event: {
+ type: 'turn.created',
+ id: `${turnId}-created`,
+ turnId,
+ previousTurnId: null,
+ input: [{ type: 'user.message', content }],
+ state: { status: 'running' },
+ createdAt,
+ threadId: null,
+ },
+ };
+}
+
+function done({
+ turnId,
+ createdAt,
+ status = 'done',
+}: {
+ turnId: string;
+ createdAt: string;
+ status?: 'done' | 'error';
+}): SessionEventItem {
+ return {
+ turnId,
+ event: {
+ type: 'turn.done',
+ id: `${turnId}-done`,
+ state:
+ status === 'error'
+ ? { status: 'error', message: 'failed', completedAt: createdAt }
+ : { status: 'done', completedAt: createdAt, output: null, requiredActions: [] },
+ createdAt,
+ threadId: null,
+ },
+ };
+}
+
+describe('buildSessionTimelineSegments', () => {
+ it('compresses idle time between turns and keeps per-turn duration', () => {
+ const turns = buildSessionTurnViews([
+ created({ turnId: 't1', createdAt: '2026-01-01T00:00:00.000Z' }),
+ done({ turnId: 't1', createdAt: '2026-01-01T00:01:00.000Z' }),
+ created({ turnId: 't2', createdAt: '2026-01-01T00:10:00.000Z', content: 'next' }),
+ done({ turnId: 't2', createdAt: '2026-01-01T00:11:00.000Z' }),
+ ]);
+ const segments = buildSessionTimelineSegments(turns);
+ const users = segments.filter(segment => segment.type === 'user');
+ assert.equal(users[0]?.startMs, 0);
+ assert.equal(users[1]?.startMs, 60_000);
+ const systems = segments.filter(segment => segment.title === 'turn.done');
+ assert.equal(systems[0]?.endMs, 60_000);
+ assert.equal(systems[1]?.endMs, 120_000);
+ });
+
+ it('builds nested sub-agent and overlapping tool-call segments', () => {
+ const turns = buildSessionTurnViews([
+ created({ turnId: 't1', createdAt: '2026-01-01T00:00:00.000Z' }),
+ {
+ turnId: 't1',
+ event: {
+ type: 'model.message',
+ id: 'model-1',
+ threadId: 'main',
+ content: 'calling tools',
+ createdAt: '2026-01-01T00:00:01.000Z',
+ toolCalls: [
+ { id: 'call-a', type: 'function', function: { name: 'search', arguments: '{}' } },
+ { id: 'call-b', type: 'function', function: { name: 'lookup', arguments: '{}' } },
+ { id: 'call-sub', type: 'function', function: { name: 'create_sub_agent', arguments: '{}' } },
+ ],
+ },
+ },
+ {
+ turnId: 't1',
+ event: {
+ type: 'thread.created',
+ id: 'thread-1',
+ threadId: 'child',
+ title: 'Researcher',
+ createdAt: '2026-01-01T00:00:01.100Z',
+ agentInfo: { type: 'dynamic', name: 'researcher', input: 'research' },
+ parent: { threadId: 'main', toolCallId: 'call-sub' },
+ },
+ },
+ {
+ turnId: 't1',
+ event: {
+ type: 'tool.response',
+ id: 'resp-a',
+ threadId: 'main',
+ toolCallId: 'call-a',
+ content: 'a',
+ createdAt: '2026-01-01T00:00:03.000Z',
+ },
+ },
+ {
+ turnId: 't1',
+ event: {
+ type: 'tool.response',
+ id: 'resp-b',
+ threadId: 'main',
+ toolCallId: 'call-b',
+ content: 'b',
+ createdAt: '2026-01-01T00:00:02.500Z',
+ },
+ },
+ {
+ turnId: 't1',
+ event: {
+ type: 'thread.done',
+ id: 'thread-done',
+ threadId: 'child',
+ title: 'Researcher',
+ createdAt: '2026-01-01T00:00:04.000Z',
+ state: { status: 'completed' },
+ },
+ },
+ done({ turnId: 't1', createdAt: '2026-01-01T00:00:05.000Z' }),
+ ]);
+
+ const segments = buildSessionTimelineSegments(turns);
+ assert.equal(
+ segments.some(segment => segment.type === 'sub_agent' && segment.description === 'Researcher'),
+ true,
+ );
+ assert.equal(
+ segments.some(segment => segment.id.endsWith('call-sub')),
+ false,
+ );
+ const toolCalls = segments.filter(segment => segment.type === 'tool_call');
+ assert.equal(toolCalls.length, 2);
+ const groups = groupOverlappingToolCalls(toolCalls).filter(group => group.segments.length > 1);
+ assert.equal(groups.length, 1);
+ assert.equal(groups[0]?.segments.length, 2);
+ });
+});
+
+describe('sessionEventTimelineChart helpers', () => {
+ const bars = (items: Array<[number, number, number]>): SessionEventTimelineSegment[] =>
+ items.map(([startMs, endMs, turnIndex], index) => ({
+ id: `s${index}`,
+ type: 'tool_call',
+ title: 'tool.call',
+ description: `s${index}`,
+ startMs,
+ endMs,
+ turnIndex,
+ threadId: 'main',
+ }));
+
+ it('picks the longest non-overlapping sub-agent bars', () => {
+ const selected = pickLongestNonOverlappingSegments(
+ bars([
+ [0, 10, 0],
+ [2, 4, 0],
+ [12, 20, 0],
+ ]),
+ );
+ assert.deepEqual(
+ selected.map(segment => segment.id),
+ ['s0', 's2'],
+ );
+ });
+
+ it('assigns non-overlapping sub-agent lanes', () => {
+ const lanes = getSubAgentLanes({
+ subAgentSegments: [
+ {
+ id: 'a',
+ type: 'sub_agent',
+ title: 'thread.created',
+ description: 'A',
+ startMs: 0,
+ endMs: 10,
+ turnIndex: 0,
+ threadId: 'a',
+ },
+ {
+ id: 'b',
+ type: 'sub_agent',
+ title: 'thread.created',
+ description: 'B',
+ startMs: 2,
+ endMs: 8,
+ turnIndex: 0,
+ threadId: 'b',
+ },
+ {
+ id: 'c',
+ type: 'sub_agent',
+ title: 'thread.created',
+ description: 'C',
+ startMs: 10,
+ endMs: 12,
+ turnIndex: 0,
+ threadId: 'c',
+ },
+ ],
+ threadSegments: [],
+ minWidthMs: 1,
+ });
+ assert.equal(lanes.find(lane => lane.threadId === 'a')?.lane, 0);
+ assert.equal(lanes.find(lane => lane.threadId === 'b')?.lane, 1);
+ assert.equal(lanes.find(lane => lane.threadId === 'c')?.lane, 0);
+ });
+
+ it('subtracts visual turn-gap bands from axis labels', () => {
+ assert.equal(getActiveTimelineMs(150, [{ startMs: 100, endMs: 120 }]), 130);
+ });
+
+ it('keeps the session end time as the last labeled tick', () => {
+ assert.deepEqual(
+ buildTimelineAxisTicks({
+ ticks: [{ value: 0 }, { value: 4000 }, { value: 8000 }, { value: 9000 }],
+ totalMs: 7900,
+ timelineMaxMs: 9000,
+ }),
+ [{ value: 0 }, { value: 4000 }, { value: 7900 }, { value: 9000 }],
+ );
+ });
+
+ it('compresses inter-turn gaps onto a contiguous axis', () => {
+ const compressed = compressInterTurnGaps([
+ {
+ id: 'u1',
+ type: 'user',
+ title: 'user.message',
+ description: '',
+ startMs: 0,
+ endMs: 0,
+ turnIndex: 0,
+ threadId: 'main',
+ isMarker: true,
+ },
+ {
+ id: 'd1',
+ type: 'system',
+ title: 'turn.done',
+ description: '',
+ startMs: 50,
+ endMs: 50,
+ turnIndex: 0,
+ threadId: 'main',
+ isMarker: true,
+ },
+ {
+ id: 'u2',
+ type: 'user',
+ title: 'user.message',
+ description: '',
+ startMs: 500,
+ endMs: 500,
+ turnIndex: 1,
+ threadId: 'main',
+ isMarker: true,
+ },
+ ]);
+ assert.equal(compressed.find(segment => segment.id === 'u2')?.startMs, 50);
+ });
+});
+
+describe('buildSessionMetrics', () => {
+ it('derives tiles from terminal turn metrics and timeline segments', () => {
+ const turns = buildSessionTurnViews([
+ created({ turnId: 't1', createdAt: '2026-01-01T00:00:00.000Z' }),
+ {
+ turnId: 't1',
+ event: {
+ type: 'turn.done',
+ id: 't1-done',
+ state: {
+ status: 'done',
+ completedAt: '2026-01-01T00:00:02.000Z',
+ output: null,
+ requiredActions: [],
+ ...{
+ metrics: {
+ totalTokens: 80,
+ totalCostInUsd: 0.5,
+ totalInputTokens: 50,
+ totalOutputTokens: 30,
+ totalCacheReadTokens: 0,
+ totalCacheWriteTokens: 0,
+ totalReasoningTokens: 0,
+ },
+ },
+ },
+ createdAt: '2026-01-01T00:00:02.000Z',
+ threadId: null,
+ },
+ },
+ ]);
+ const segments = buildSessionTimelineSegments(turns);
+ const metrics = buildSessionMetrics({ turns, segments });
+ assert.equal(metrics.totalTurns, 1);
+ assert.equal(metrics.wallTimeMs, 2_000);
+ assert.equal(metrics.totalCostUsd, 0.5);
+ assert.equal(metrics.totalTokens, 80);
+ assert.equal(metrics.tokenBreakdown.find(item => item.label === 'input')?.value, 50);
+ assert.equal(metrics.errors, 0);
+ });
+});
diff --git a/packages/trueforge-ui/test/utils/sessionShareUrl.test.ts b/packages/trueforge-ui/test/utils/sessionShareUrl.test.ts
new file mode 100644
index 000000000..d5b4cb475
--- /dev/null
+++ b/packages/trueforge-ui/test/utils/sessionShareUrl.test.ts
@@ -0,0 +1,104 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'vitest';
+
+import {
+ DEFAULT_SESSION_TIME_WINDOW_MS,
+ defaultSessionTimeRange,
+ libraryAgentTabFromSearch,
+ readSessionShareSearch,
+ SESSION_TIME_BUFFER_MS,
+ sessionTimeRangeFromCreatedAt,
+ writeSessionShareSearch,
+} from '@/utils/sessionShareUrl.js';
+
+describe('sessionShareUrl', () => {
+ it('reads agent and session ids from the query string', () => {
+ assert.deepEqual(readSessionShareSearch('?sessionId=sess-1&agentId=agent-1'), {
+ sessionId: 'sess-1',
+ agentId: 'agent-1',
+ tab: null,
+ view: null,
+ timeRange: null,
+ });
+ assert.deepEqual(readSessionShareSearch(''), {
+ sessionId: null,
+ agentId: null,
+ tab: null,
+ view: null,
+ timeRange: null,
+ });
+ });
+
+ it('reads view=sessions and a relative time window', () => {
+ const share = readSessionShareSearch(`?view=sessions&s_tw=${String(DEFAULT_SESSION_TIME_WINDOW_MS)}`);
+ assert.equal(share.view, 'sessions');
+ assert.equal(share.timeRange?.timeWindowMs, DEFAULT_SESSION_TIME_WINDOW_MS);
+ assert.ok(
+ share.timeRange != null && share.timeRange.endTs - share.timeRange.startTs === DEFAULT_SESSION_TIME_WINDOW_MS,
+ );
+ });
+
+ it('reads an absolute pinned time range', () => {
+ assert.deepEqual(readSessionShareSearch('?s_sts=1000&s_ets=2000'), {
+ sessionId: null,
+ agentId: null,
+ tab: null,
+ view: null,
+ timeRange: { startTs: 1000, endTs: 2000 },
+ });
+ });
+
+ it('writes and clears share params without dropping host query keys', () => {
+ const params = new URLSearchParams('theme=dark');
+ writeSessionShareSearch(params, { sessionId: 'sess-1', agentId: 'agent-1', view: 'sessions' });
+ assert.equal(params.get('theme'), 'dark');
+ assert.equal(params.get('sessionId'), 'sess-1');
+ assert.equal(params.get('view'), 'sessions');
+ writeSessionShareSearch(params, { sessionId: null, view: null });
+ assert.equal(params.get('sessionId'), null);
+ assert.equal(params.get('view'), null);
+ assert.equal(params.get('agentId'), 'agent-1');
+ });
+
+ it('writes a relative window and replaces it with a pinned range', () => {
+ const params = new URLSearchParams();
+ writeSessionShareSearch(params, {
+ timeRange: { startTs: 1, endTs: 2, timeWindowMs: DEFAULT_SESSION_TIME_WINDOW_MS },
+ });
+ assert.equal(params.get('s_tw'), String(DEFAULT_SESSION_TIME_WINDOW_MS));
+ assert.equal(params.get('s_sts'), null);
+ writeSessionShareSearch(params, { timeRange: { startTs: 10, endTs: 20 } });
+ assert.equal(params.get('s_sts'), '10');
+ assert.equal(params.get('s_ets'), '20');
+ assert.equal(params.get('s_tw'), null);
+ });
+
+ it('pins a 5 minute buffer around created_at', () => {
+ const createdAt = '2026-01-01T00:10:00.000Z';
+ const createdAtMs = Date.parse(createdAt);
+ assert.deepEqual(sessionTimeRangeFromCreatedAt(createdAt), {
+ startTs: createdAtMs - SESSION_TIME_BUFFER_MS,
+ endTs: createdAtMs + SESSION_TIME_BUFFER_MS,
+ });
+ });
+
+ it('defaults the sessions filter to the last 30 days', () => {
+ const now = 1_700_000_000_000;
+ assert.deepEqual(defaultSessionTimeRange(now), {
+ startTs: now - DEFAULT_SESSION_TIME_WINDOW_MS,
+ endTs: now,
+ timeWindowMs: DEFAULT_SESSION_TIME_WINDOW_MS,
+ });
+ });
+
+ it('resolves the library details tab from tab= then a matching session share', () => {
+ const share = readSessionShareSearch('?sessionId=sess-1&agentId=agent-1');
+ assert.equal(libraryAgentTabFromSearch(share, 'agent-1'), 'sessions');
+ assert.equal(libraryAgentTabFromSearch(share, 'other-agent'), 'overview');
+ assert.equal(
+ libraryAgentTabFromSearch(readSessionShareSearch('?sessionId=sess-1&tab=overview'), 'agent-1'),
+ 'overview',
+ );
+ assert.equal(libraryAgentTabFromSearch(readSessionShareSearch('?tab=code'), 'agent-1'), 'code');
+ });
+});
diff --git a/packages/trueforge-ui/test/utils/sessionTimePresets.test.ts b/packages/trueforge-ui/test/utils/sessionTimePresets.test.ts
new file mode 100644
index 000000000..c56c35043
--- /dev/null
+++ b/packages/trueforge-ui/test/utils/sessionTimePresets.test.ts
@@ -0,0 +1,35 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'vitest';
+
+import {
+ formatSessionTimePresetLabel,
+ formatTimezoneOffsetLabel,
+ fromDateTimeLocalValue,
+ toDateTimeLocalValue,
+} from '@/utils/sessionTimePresets.js';
+
+describe('sessionTimePresets', () => {
+ it('labels known windows and rejects unknown ones', () => {
+ assert.equal(formatSessionTimePresetLabel(30 * 60 * 1000), 'Last 30 minutes');
+ assert.equal(formatSessionTimePresetLabel(12 * 60 * 60 * 1000), 'Last 12 hours');
+ assert.equal(formatSessionTimePresetLabel(1), null);
+ });
+
+ it('formats a timezone offset from a fixed date', () => {
+ const date = new Date('2026-01-01T00:00:00.000Z');
+ const offsetMin = -date.getTimezoneOffset();
+ const sign = offsetMin >= 0 ? '+' : '-';
+ const abs = Math.abs(offsetMin);
+ const hours = String(Math.floor(abs / 60)).padStart(2, '0');
+ const minutes = String(abs % 60).padStart(2, '0');
+ assert.equal(formatTimezoneOffsetLabel(date), `UTC${sign}${hours}:${minutes}`);
+ });
+
+ it('round-trips datetime-local values', () => {
+ const ts = Date.parse('2026-08-31T12:21:18.000Z');
+ const local = toDateTimeLocalValue(ts);
+ const parsed = fromDateTimeLocalValue(local);
+ assert.ok(parsed != null);
+ assert.equal(parsed, ts);
+ });
+});
diff --git a/packages/trueforge-ui/test/utils/sessionTimelineEvents.test.ts b/packages/trueforge-ui/test/utils/sessionTimelineEvents.test.ts
new file mode 100644
index 000000000..6030385b9
--- /dev/null
+++ b/packages/trueforge-ui/test/utils/sessionTimelineEvents.test.ts
@@ -0,0 +1,26 @@
+import { describe, expect, it } from 'vitest';
+
+import { toolCallDescription } from '@/utils/sessionTimelineEvents.js';
+
+describe('toolCallDescription', () => {
+ it('shows sandbox intent instead of the exec tool name', () => {
+ expect(
+ toolCallDescription({
+ function: {
+ name: 'exec',
+ arguments: JSON.stringify({ command: 'ls', intent: 'List workspace files' }),
+ },
+ }),
+ ).toBe('List workspace files');
+ expect(
+ toolCallDescription({
+ function: { name: 'sandbox_exec', arguments: '{"intent":"Generate a PDF"}' },
+ }),
+ ).toBe('Generate a PDF');
+ });
+
+ it('falls back to the tool name when intent is missing', () => {
+ expect(toolCallDescription({ function: { name: 'exec', arguments: '{"command":"ls"}' } })).toBe('exec');
+ expect(toolCallDescription({ function: { name: 'search', arguments: '{"q":"x"}' } })).toBe('search');
+ });
+});
diff --git a/packages/trueforge-ui/tsup.config.ts b/packages/trueforge-ui/tsup.config.ts
index 53ed3bf30..a72dd3855 100644
--- a/packages/trueforge-ui/tsup.config.ts
+++ b/packages/trueforge-ui/tsup.config.ts
@@ -47,5 +47,7 @@ export default defineConfig({
'react-syntax-highlighter',
'monaco-editor',
'@truefoundry/trueforge-sdk',
+ 'chart.js',
+ 'react-chartjs-2',
],
});
diff --git a/packages/trueforge/src/frontend.ts b/packages/trueforge/src/frontend.ts
index 378d7b04e..7acf61425 100644
--- a/packages/trueforge/src/frontend.ts
+++ b/packages/trueforge/src/frontend.ts
@@ -65,7 +65,7 @@ export function mountFrontend(app: OpenAPIHono, dir: string): boolean {
const serveAppShell = serveStatic({ root: dir, rewriteRequestPath: () => '/index.html', precompressed: true });
/**
- * Client routes (`/sessions/{id}`, `/settings`) have no file on disk, so a
+ * Client routes (`/sessions/{id}`, `/settings`, `/library`) have no file on disk, so a
* deep link only reaches the app when the shell answers the navigation.
* Runs after `serveBuild`, so real files still win; requests that do not
* accept HTML keep their 404 rather than getting the shell as a fake asset.
diff --git a/packages/trueforge/tests/unit/frontend.test.ts b/packages/trueforge/tests/unit/frontend.test.ts
index 211758559..8e64417d2 100644
--- a/packages/trueforge/tests/unit/frontend.test.ts
+++ b/packages/trueforge/tests/unit/frontend.test.ts
@@ -31,7 +31,14 @@ describe('mountFrontend', () => {
it('serves the app shell for client-only deep links', async () => {
const app = appWithFrontend(buildDir());
- for (const clientPath of ['/', '/settings', '/sessions/abc123', '/agents/my-agent']) {
+ for (const clientPath of [
+ '/',
+ '/settings',
+ '/library',
+ '/library/agent-1',
+ '/sessions/abc123',
+ '/agents/my-agent',
+ ]) {
const response = await app.request(clientPath, { headers: HTML_ACCEPT });
expect(response.status).toBe(200);
await expect(response.text()).resolves.toContain('id="root"');
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 9ce441bf3..a539836a4 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.21
+ specifier: 0.1.22
'@truefoundry/trueforge-sdk':
specifier: workspace:*
version: link:../trueforge-sdk
@@ -351,11 +351,14 @@ importers:
specifier: ^0.13.2
'@truefoundry/assistant-ui-runtime':
- specifier: 0.1.21
+ specifier: 0.1.22
'@truefoundry/trueforge-sdk':
specifier: workspace:*
version: link:../trueforge-sdk
+ chart.js:
+ specifier: ^4.5.1
+ version: 4.5.1
clsx:
specifier: ^2.1.1
version: 2.1.1
@@ -368,6 +371,9 @@ importers:
partial-json:
specifier: ^0.1.7
version: 0.1.7
+ react-chartjs-2:
+ specifier: ^5.3.1
react-dom:
specifier: ^18 || ^19
version: 19.2.8([email protected])
@@ -1047,6 +1053,12 @@ packages:
cpu: [ppc64]
os: [aix]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-Svl7tq8k/08+p6CXPpRjQ1fKX+1odH/BQbb48fV6fj3CWHhsoIOoY87w1oHXm0qEpkIK3ZfVgp0hed3XBXzXMQ==}
+ engines: {node: '>=18'}
+ cpu: [ppc64]
+ os: [aix]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==}
engines: {node: '>=18'}
@@ -1065,6 +1077,12 @@ packages:
cpu: [arm64]
os: [android]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-34EGEbCIAgosYz6goLcopX6Mo7NyGv9tfwEM2/7Ce2VcVRk568iSvniGWcUXIy7wEDR1wzolcxcriFVrWYcwBg==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [android]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==}
engines: {node: '>=18'}
@@ -1083,6 +1101,12 @@ packages:
cpu: [arm]
os: [android]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-0k2F129Xdio1TdJfzJ8sy1Q47vUD2NnwdhiAf7drUN1EBTfPf4hsFCtmMgu/6m8JSzsBrlmVjudMBQqOfG8usQ==}
+ engines: {node: '>=18'}
+ cpu: [arm]
+ os: [android]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==}
engines: {node: '>=18'}
@@ -1101,6 +1125,12 @@ packages:
cpu: [x64]
os: [android]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-dbwY7ltSMDWsRatcRpCnES4F+im88OCUgGZjy52shC7GqHRE/cYlxNbB4Z4UpJswpcc4Qxd2oE/ufM0p61IKng==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [android]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==}
engines: {node: '>=18'}
@@ -1119,6 +1149,12 @@ packages:
cpu: [arm64]
os: [darwin]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-TZbWkQY7kvTAXbXUT7uVACR5cMHsDiSz9z7ZKAX/RTq/WJEk3QyRr0wZpNhBDX+/0CtdqUIJlOiodQcta6tY3Q==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [darwin]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==}
engines: {node: '>=18'}
@@ -1137,6 +1173,12 @@ packages:
cpu: [x64]
os: [darwin]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-zfdzgK9ACBNZLI/CyHTOx81SyNbM6YXn7rxSgX97VjyiPl9W1i4Ka4fgKECEoFCKGpvBj5qArWIGgQjOwkgskQ==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [darwin]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==}
engines: {node: '>=18'}
@@ -1155,6 +1197,12 @@ packages:
cpu: [arm64]
os: [freebsd]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-wG2EA8ENdEI0qhkSZMjfqrdY+ziCYCPMmtZjjIwOmXFjmyzEHn+UUxk5of+SYsjtfs3VpnlC7QLzSI5hY/rOAw==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [freebsd]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==}
engines: {node: '>=18'}
@@ -1173,6 +1221,12 @@ packages:
cpu: [x64]
os: [freebsd]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-i7dZ9vQgnvSCzi/rYCXNgtF/U+eKZNJBzu3eTQbRgHnM7tNSizLOkRFAl3qzVc/Op/u5YkHHa4pf/3DOYHthLQ==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [freebsd]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==}
engines: {node: '>=18'}
@@ -1191,6 +1245,12 @@ packages:
cpu: [arm64]
os: [linux]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-yHs+0uc8+nvEAfAfxrWQKK5peSNzBc4PegcMO0EJ2hT71uA7vB8Ihg2e77R2P7SG5uYjPbHlLLmve4LLLRCf0g==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [linux]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==}
engines: {node: '>=18'}
@@ -1209,6 +1269,12 @@ packages:
cpu: [arm]
os: [linux]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-qVXBOHQS+d5Y722GwJzJUtOLlX7km3CraOaGormF1pDtPd2C/l1SHRPgjLunLGe51Sh5YYWKMFDyV4SxgMQYTQ==}
+ engines: {node: '>=18'}
+ cpu: [arm]
+ os: [linux]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==}
engines: {node: '>=18'}
@@ -1227,6 +1293,12 @@ packages:
cpu: [ia32]
os: [linux]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-d1z4ZuP0ajrfz/FhGT4vv278rX8KnPPJx8i5+AtK7TYbx9Le9F1hyzurZpkEyjkGa9dUGhQow4C1NmeGvqxN2w==}
+ engines: {node: '>=18'}
+ cpu: [ia32]
+ os: [linux]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==}
engines: {node: '>=18'}
@@ -1245,6 +1317,12 @@ packages:
cpu: [loong64]
os: [linux]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-M5sRjUVZrkm1OAPR3dlOYzNmN+loZKGVi1VUQGrwuqLcbR6qeAz+famMhjASeH3YVKvZz+zT1jlh/keC3Rj/lg==}
+ engines: {node: '>=18'}
+ cpu: [loong64]
+ os: [linux]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==}
engines: {node: '>=18'}
@@ -1263,6 +1341,12 @@ packages:
cpu: [mips64el]
os: [linux]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-mRObBZeHh2OxcBFPWE/FjylkRgZdYuiTR3vaTozquCGOH14iP9oN4x4Ge81CoIDYQrXmIxpFumJBu5MtZpnQJQ==}
+ engines: {node: '>=18'}
+ cpu: [mips64el]
+ os: [linux]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==}
engines: {node: '>=18'}
@@ -1281,6 +1365,12 @@ packages:
cpu: [ppc64]
os: [linux]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-slScBsMAb3GFDcdrCgLwZtPYRoH2H/youv10QiZyRjmsP48fznoveWytSgCI/R0ZcUgpc0ZhIUEx6LHts8yrfQ==}
+ engines: {node: '>=18'}
+ cpu: [ppc64]
+ os: [linux]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==}
engines: {node: '>=18'}
@@ -1299,6 +1389,12 @@ packages:
cpu: [riscv64]
os: [linux]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-kw0owk1o0GFETUJyW0jc0G4Yzs0BHZn0JDZ8JRT088vjJYX777BAs1fDGxAC+q831qOs2DTC96mNsG2opdfyyQ==}
+ engines: {node: '>=18'}
+ cpu: [riscv64]
+ os: [linux]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==}
engines: {node: '>=18'}
@@ -1317,6 +1413,12 @@ packages:
cpu: [s390x]
os: [linux]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-/lAIjX8aYFRByhh6L5rYtPEDRqa9de/4V/juOXcta5frjvzXO4/sqEtyytse0g3zZFuWu5cDN0MkLz2qRDD2Ag==}
+ engines: {node: '>=18'}
+ cpu: [s390x]
+ os: [linux]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==}
engines: {node: '>=18'}
@@ -1335,6 +1437,12 @@ packages:
cpu: [x64]
os: [linux]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-u/anNYF2mmVOEDwLtnQ1wOr3EZ9sTNGLWrsYGYwHWzGA3Si84IOkHXlbWTD1NB+9/1lcnweYKO54uhxZydNzfA==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [linux]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==}
engines: {node: '>=18'}
@@ -1353,6 +1461,12 @@ packages:
cpu: [arm64]
os: [netbsd]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-oks0DYbLwWMmaakTsCb+zL4E+aHRVLom9IJZOAthMQEPiQmydXHkziYEsGYRx0uNV/IjEKGAV941JzH02pflqw==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [netbsd]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==}
engines: {node: '>=18'}
@@ -1371,6 +1485,12 @@ packages:
cpu: [x64]
os: [netbsd]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-aeL6lAnN89Hz43Mlh1G8ARasbuoYvSITDEx0tHh5b7jJnHcssqgjy9Yx430GDpmCa6OyrKoS0aNRjKundRizGg==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [netbsd]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==}
engines: {node: '>=18'}
@@ -1389,6 +1509,12 @@ packages:
cpu: [arm64]
os: [openbsd]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-MEFJe5C3R8pwXdZ5Y21oo6m7ePiS0d9pWucn99O/wvyJZChoIQKrQDxKrGeW8F5+T0okTHesAmDeiHDTIq0V/Q==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [openbsd]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==}
engines: {node: '>=18'}
@@ -1407,6 +1533,12 @@ packages:
cpu: [x64]
os: [openbsd]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-i/ZLIOafE0Z8cI/XANJAixoJL/uRAoS2xOA3rb0xN+KK0K177cMAsQYkzHtBrtMXAKuAc7HGgcWiZ/sRC1Nxgw==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [openbsd]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==}
engines: {node: '>=18'}
@@ -1425,6 +1557,12 @@ packages:
cpu: [arm64]
os: [openharmony]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-ge+Z7EXFNt2BO1oAMsVpiQ8EwndV9i1xXerAeTIK7AtPs3bKFXQM7nlRxDSIUIMeueR1CNXxqztLzdNeReKBJg==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [openharmony]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==}
engines: {node: '>=18'}
@@ -1443,6 +1581,12 @@ packages:
cpu: [x64]
os: [sunos]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-BEjgtECkL3vY+SaSQ6nzVfiALUeFxpawyp8Jmf5PtYhf1Ug40N1h/hxlhts+f1FvSvarEigdxS3BlSMI2PJLcQ==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [sunos]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==}
engines: {node: '>=18'}
@@ -1461,6 +1605,12 @@ packages:
cpu: [arm64]
os: [win32]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-lCv9eK/H6ZJWbE7bh2nw54CZ9M2nupBxJcTsdk/QQnWkdSjKGuxmmH8/GWrlT1eMmZfn4dGcCjRte397WqfQXA==}
+ engines: {node: '>=18'}
+ cpu: [arm64]
+ os: [win32]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==}
engines: {node: '>=18'}
@@ -1479,6 +1629,12 @@ packages:
cpu: [ia32]
os: [win32]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-zvb/mB2bSCoJOpoCBgYKKpX6YM6mJBlBUVUtVj41DlZJVEB6/0CKlRYxP5wWl1C1ILiCoAU5wZZ4q1P3qeS6Eg==}
+ engines: {node: '>=18'}
+ cpu: [ia32]
+ os: [win32]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==}
engines: {node: '>=18'}
@@ -1497,6 +1653,12 @@ packages:
cpu: [x64]
os: [win32]
+ '@esbuild/[email protected]':
+ resolution: {integrity: sha512-bm4Mowrv+GXMlpWX++EcXw/iLyd1o3+bJkC2DkWXYVvgZCqD/bSj9ctZeAMC3cIxgjRVR2Dufaiu4YPxr5gW1A==}
+ engines: {node: '>=18'}
+ cpu: [x64]
+ os: [win32]
+
'@esbuild/[email protected]':
resolution: {integrity: sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==}
engines: {node: '>=18'}
@@ -1846,6 +2008,9 @@ packages:
'@js-sdsl/[email protected]':
resolution: {integrity: sha512-iUKgm52T8HOE/makSxjqoWhe95ZJA1/G1sYsGev2JDKUSS14KAgg1LHb+Ba+IPow0xflbnSkOsZcO08C7w1gYw==}
+ '@kurkle/[email protected]':
+ resolution: {integrity: sha512-M5UknZPHRu3DEDWoipU6sE8PdkZ6Z/S+v4dD+Ke8IaNlpdSQah50lz1KtcFBa2vsdOnwbbnxJwVM4wty6udA5w==}
+
'@manypkg/[email protected]':
resolution: {integrity: sha512-BcSqCyKhBVZ5YkSzOiheMCV41kqAFptW6xGqYSTjkVTl9XQpr+pqHhwgGCOHQtjDCv7Is6EFyA14Sm5GVbVABA==}
engines: {node: '>=20.0.0'}
@@ -3459,8 +3624,8 @@ packages:
'@types/react-dom':
optional: true
- '@truefoundry/[email protected]':
- resolution: {integrity: sha512-p7Heuc+vXArqLeisqYAp2HlHLPdIPoEcxJUbcF0e/7fSGhVs0SWVNYtQ2nTw68GJsC5nyuJwQJ445sX+OhCa6w==}
+ '@truefoundry/[email protected]':
+ resolution: {integrity: sha512-tvAkqZNJMM+NwB2bU5tZubbTKyDR2k/k6cFTxJZwczjpUw3Vp3q5ESxguNqooqqXMeC3/6xjBQH6my6ziFgWgw==}
peerDependencies:
'@types/react': '*'
react: ^18 || ^19
@@ -4199,6 +4364,10 @@ packages:
resolution: {integrity: sha512-iBZ4F4wRbyORVsu0jPV7gXkOsGYjGHPmAyv+HiHG8gi5PtC9KI2j1+v8/tlibRvjoWX027ypmG/n0HtO5t7unw==}
+ resolution: {integrity: sha512-GIjfiT9dbmHRiYi6Nl2yFCq7kkwdkp1W/lp2J99rX0yo9tgJGn3lKQATztIjb5tVtevcBtIdICNWqlq5+E8/Pw==}
+ engines: {pnpm: '>=8'}
+
resolution: {integrity: sha512-Qgzu8kfBvo+cA4962jnP1KkS6Dop5NS6g7R5LFYJr4b8Ub94PPQXUksCw9PvXoeXPRRddRNC5C1JQUR2SMGtnA==}
engines: {node: '>= 14.16.0'}
@@ -4630,6 +4799,11 @@ packages:
engines: {node: '>=18'}
hasBin: true
+ resolution: {integrity: sha512-HrJrvZv5ayxBzPfwphOoNzkzOIIlifzk0KJrGK2c8R4+LKpMtpYLQeUdjnwjWv/LZlkH2laZk+4w78pi99D4Vw==}
+ engines: {node: '>=18'}
+ hasBin: true
+
resolution: {integrity: sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==}
engines: {node: '>=18'}
@@ -6396,6 +6570,12 @@ packages:
resolution: {integrity: sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==}
engines: {node: '>= 0.10'}
+ resolution: {integrity: sha512-h5IPXKg9EXpjoBzUfyWJvllMjG2mQ4EiuHQFhms/AjUm0XSZHhyRy2xVmLXHKrtcdrPO4mnGqRtYoD0vp95A0A==}
+ peerDependencies:
+ chart.js: ^4.1.1
+ react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
resolution: {integrity: sha512-tBaoDWjPwe0M5pGrum4H0SR6Lyk+BO9oHnp9JbKpGKW2mlraNPgP9BMfsg5pWpwrssARmeqk7YBl2oXutZTaHA==}
engines: {node: '>=18'}
@@ -8275,6 +8455,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8284,6 +8467,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8293,6 +8479,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8302,6 +8491,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8311,6 +8503,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8320,6 +8515,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8329,6 +8527,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8338,6 +8539,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8347,6 +8551,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8356,6 +8563,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8365,6 +8575,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8374,6 +8587,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8383,6 +8599,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8392,6 +8611,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8401,6 +8623,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8410,6 +8635,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8419,6 +8647,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8428,6 +8659,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8437,6 +8671,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8446,6 +8683,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8455,6 +8695,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8464,6 +8707,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8473,6 +8719,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8482,6 +8731,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8491,6 +8743,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8500,6 +8755,9 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ '@esbuild/[email protected]':
+ optional: true
+
'@esbuild/[email protected]':
optional: true
@@ -8992,6 +9250,8 @@ snapshots:
'@js-sdsl/[email protected]': {}
+ '@kurkle/[email protected]': {}
+
'@manypkg/[email protected]':
dependencies:
'@manypkg/tools': 2.1.2
@@ -10606,7 +10866,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])
@@ -10796,10 +11056,10 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
'@eslint-community/regexpp': 4.12.2
'@typescript-eslint/scope-manager': 8.68.0
@@ -11447,6 +11707,10 @@ snapshots:
+ dependencies:
+ '@kurkle/color': 0.3.4
+
dependencies:
readdirp: 4.1.2
@@ -11858,6 +12122,35 @@ snapshots:
'@esbuild/win32-ia32': 0.27.7
'@esbuild/win32-x64': 0.27.7
+ optionalDependencies:
+ '@esbuild/aix-ppc64': 0.28.1
+ '@esbuild/android-arm': 0.28.1
+ '@esbuild/android-arm64': 0.28.1
+ '@esbuild/android-x64': 0.28.1
+ '@esbuild/darwin-arm64': 0.28.1
+ '@esbuild/darwin-x64': 0.28.1
+ '@esbuild/freebsd-arm64': 0.28.1
+ '@esbuild/freebsd-x64': 0.28.1
+ '@esbuild/linux-arm': 0.28.1
+ '@esbuild/linux-arm64': 0.28.1
+ '@esbuild/linux-ia32': 0.28.1
+ '@esbuild/linux-loong64': 0.28.1
+ '@esbuild/linux-mips64el': 0.28.1
+ '@esbuild/linux-ppc64': 0.28.1
+ '@esbuild/linux-riscv64': 0.28.1
+ '@esbuild/linux-s390x': 0.28.1
+ '@esbuild/linux-x64': 0.28.1
+ '@esbuild/netbsd-arm64': 0.28.1
+ '@esbuild/netbsd-x64': 0.28.1
+ '@esbuild/openbsd-arm64': 0.28.1
+ '@esbuild/openbsd-x64': 0.28.1
+ '@esbuild/openharmony-arm64': 0.28.1
+ '@esbuild/sunos-x64': 0.28.1
+ '@esbuild/win32-arm64': 0.28.1
+ '@esbuild/win32-ia32': 0.28.1
+ '@esbuild/win32-x64': 0.28.1
+
optionalDependencies:
'@esbuild/aix-ppc64': 0.28.2
@@ -11886,6 +12179,7 @@ snapshots:
'@esbuild/win32-arm64': 0.28.2
'@esbuild/win32-ia32': 0.28.2
'@esbuild/win32-x64': 0.28.2
+ optional: true
@@ -14189,6 +14483,11 @@ snapshots:
iconv-lite: 0.7.3
unpipe: 1.0.0
+ dependencies:
+ chart.js: 4.5.1
+ react: 19.2.8
+
dependencies:
'@date-fns/tz': 1.5.0
@@ -14949,7 +15248,7 @@ snapshots:
dependencies:
- esbuild: 0.28.2
+ esbuild: 0.28.1
optionalDependencies:
fsevents: 2.3.3
@@ -14984,7 +15283,7 @@ snapshots:
dependencies:
'@typescript-eslint/typescript-estree': 8.68.0([email protected])([email protected])