Skip to content
Merged
Show file tree
Hide file tree
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/adapter-sdk-code-snippets.md
Original file line number Diff line number Diff line change
@@ -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`.
5 changes: 5 additions & 0 deletions .changeset/agent-library-details.md
Original file line number Diff line number Diff line change
@@ -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.
5 changes: 5 additions & 0 deletions .changeset/agent-sessions-tab.md
Original file line number Diff line number Diff line change
@@ -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.
43 changes: 43 additions & 0 deletions .cursor/rules/trueforge-ui-slots.mdc
Original file line number Diff line number Diff line change
@@ -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.
2 changes: 1 addition & 1 deletion packages/frontend/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,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",
Expand Down
2 changes: 1 addition & 1 deletion packages/trueforge-ui/docs/compatibility.md
Original file line number Diff line number Diff line change
Expand Up @@ -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` |

Expand Down
34 changes: 28 additions & 6 deletions packages/trueforge-ui/docs/customization.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`,
Expand All @@ -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:
Expand All @@ -100,21 +110,33 @@ 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
`withRouter` with `initialSessionId` is not supported — the URL wins.

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.
Expand Down
4 changes: 3 additions & 1 deletion packages/trueforge-ui/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -97,12 +97,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",
Expand Down
111 changes: 88 additions & 23 deletions packages/trueforge-ui/src/atoms/AgentsLibrary.tsx
Original file line number Diff line number Diff line change
@@ -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;
};
Expand All @@ -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;
Expand All @@ -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" />
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -111,33 +130,48 @@ 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,
query,
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,
Expand All @@ -147,16 +181,31 @@ 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,
agentSpec,
});
};

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" />
Expand Down Expand Up @@ -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);
Expand All @@ -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;
}
}
Loading