Skip to content

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

Integrate @truefoundry/trueforge-ui SDK into the project (#66)

Govinda Vashishtha731bcbbb1948
diff --git a/.codegraph/.gitignore b/.codegraph/.gitignore
new file mode 100644
index 000000000..d20c0fe4b
--- /dev/null
+++ b/.codegraph/.gitignore
@@ -0,0 +1,5 @@
+# CodeGraph data files — local to each machine, not for committing.
+# Ignore everything in .codegraph/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+*
+!.gitignore
diff --git a/Dockerfile b/Dockerfile
index 695736907..2c0bb55ce 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -37,6 +37,7 @@ COPY package.json .npmrc tsconfig.base.json ./
COPY packages/harness/package.json packages/harness/package.json
COPY packages/server/package.json packages/server/package.json
COPY packages/frontend/package.json packages/frontend/package.json
+COPY packages/trueforge-ui-sdk/package.json packages/trueforge-ui-sdk/package.json
COPY packages/harness/scripts packages/harness/scripts
COPY packages/harness/src/core/sandbox/scripts packages/harness/src/core/sandbox/scripts
@@ -56,6 +57,8 @@ RUN pnpm --filter @truefoundry/utils-core build && pnpm --filter @truefoundry/ut
FROM workspace AS frontend-builder
RUN --mount=type=cache,id=pnpm,target=/pnpm/store \
pnpm install --frozen-lockfile --offline --filter frontend...
+COPY packages/trueforge-ui-sdk packages/trueforge-ui-sdk
+RUN pnpm --filter @truefoundry/trueforge-ui build
COPY packages/frontend packages/frontend
# trueforge is linked from packages/sdk (outside the pnpm workspace).
COPY packages/sdk/package.json packages/sdk/pnpm-lock.yaml packages/sdk/pnpm-workspace.yaml packages/sdk/
diff --git a/README.md b/README.md
index 590f990c2..00f9917e2 100644
--- a/README.md
+++ b/README.md
@@ -6,12 +6,13 @@ Out of the box you get multi-turn sessions with streaming, MCP tool servers (inc
> Note: Package and folder names will be renamed soon to match the release names below. They have been intentionally named "utils" to not leak before announcement.
-| Package | Release Name | Path | What it is |
-| ------------------------- | ----------------------------- | ---------------------------------------- | ----------------------------------------------------------- |
-| `@truefoundry/utils` | `@truefoundry/trueforge` | `[packages/server](packages/server)` | Agent server + bundled UI |
-| `@truefoundry/utils-core` | `@truefoundry/trueforge-core` | `[packages/harness](packages/harness)` | Library: agent core, sessions, and streaming |
-| `trueforge` | `@truefoundry/trueforge-sdk` | `[packages/sdk](packages/sdk)` | Generated TypeScript SDK |
-| `frontend` | — | `[packages/frontend](packages/frontend)` | Chat UI (bundled into the server; not published on its own) |
+| Package | Release Name | Path | What it is |
+| --------------------------- | ----------------------------- | -------------------------------------------------------- | ---------------------------------------------------- |
+| `@truefoundry/utils` | `@truefoundry/trueforge` | [`packages/server`](packages/server) | Agent server + bundled UI |
+| `@truefoundry/utils-core` | `@truefoundry/trueforge-core` | [`packages/harness`](packages/harness) | Library: agent core, sessions, and streaming |
+| `@truefoundry/trueforge-ui` | — | [`packages/trueforge-ui-sdk`](packages/trueforge-ui-sdk) | Published agent chat UI SDK |
+| `trueforge` | `@truefoundry/trueforge-sdk` | [`packages/sdk`](packages/sdk) | Generated TypeScript SDK |
+| `frontend` | — | [`packages/frontend`](packages/frontend) | Chat UI (bundled into the server; uses trueforge-ui) |
Requires **Node.js 22.13+** and **pnpm**.
@@ -142,7 +143,7 @@ The published package supports both CommonJS and ESM. Server-only dependencies (
| `pnpm smoke` / `pnpm smoke:down` | Full Docker Compose stack |
| `pnpm clean` / `pnpm clean:all` | Remove build outputs (+ `node_modules` for `:all`) |
-Local server scripts resolve `@truefoundry/utils-core` from source, so you do not need a utils-core `dist/` build for `pnpm dev` / `standalone:dev`.
+Local server scripts resolve `@truefoundry/utils-core` from source, so you do not need a utils-core `dist/` build for `pnpm dev` / `standalone:dev`. Frontend scripts build `@truefoundry/trueforge-ui` `dist/` before Vite starts (workspace package exports point at `dist/`).
### Smoke test (Docker)
diff --git a/package.json b/package.json
index df5683153..714ad6179 100644
--- a/package.json
+++ b/package.json
@@ -6,7 +6,7 @@
"node": ">=22.13.0"
},
"scripts": {
- "build": "pnpm --filter @truefoundry/utils-core build && pnpm --filter frontend build && pnpm --filter @truefoundry/utils build",
+ "build": "pnpm --filter @truefoundry/utils-core build && pnpm --filter @truefoundry/trueforge-ui build && pnpm --filter frontend build && pnpm --filter @truefoundry/utils build",
"clean:all": "node scripts/clean.mjs --dependencies",
"clean": "node scripts/clean.mjs",
"dev": "STANDALONE=false NODE_ENV=development pnpm --parallel --filter @truefoundry/utils-core --filter @truefoundry/utils --filter frontend dev",
@@ -30,8 +30,8 @@
"smoke:down": "docker compose down",
"smoke": "docker compose up --build --wait && node -e \"Promise.all([fetch('http://127.0.0.1:8791/healthz'), fetch('http://127.0.0.1:8791/')]).then(async ([health, ui]) => { if (!health.ok) throw new Error('healthz returned ' + health.status); const html = await ui.text(); if (!ui.ok || !html.includes('id=\\\"root\\\"')) throw new Error('UI did not return its app shell'); console.log('healthz and UI OK'); })\"",
"test:store:local": "bash scripts/test-store-local.sh",
- "test": "pnpm --filter @truefoundry/utils-core test && pnpm --filter @truefoundry/utils test && pnpm --filter frontend test",
- "typecheck": "pnpm --filter @truefoundry/utils-core typecheck && pnpm --filter @truefoundry/utils typecheck && pnpm --filter frontend typecheck",
+ "test": "pnpm --filter @truefoundry/utils-core test && pnpm --filter @truefoundry/trueforge-ui test && pnpm --filter @truefoundry/utils test && pnpm --filter frontend test",
+ "typecheck": "pnpm --filter @truefoundry/utils-core typecheck && pnpm --filter @truefoundry/trueforge-ui typecheck && pnpm --filter @truefoundry/utils typecheck && pnpm --filter frontend typecheck",
"ui:clean": "node ui-shots/clean.mjs",
"ui:shot": "node ui-shots/shot.mjs"
},
diff --git a/packages/frontend/README.md b/packages/frontend/README.md
index 696565570..cc8b4bb73 100644
--- a/packages/frontend/README.md
+++ b/packages/frontend/README.md
@@ -8,7 +8,7 @@ Built on:
trueforge (local Harness SDK)
→ Harness AgentChatServer adapter
→ createTrueFoundryServer (chat port + catalog callbacks)
- → @truefoundry/agent-ui-sdk (TrueFoundryAssistantUI, layout="sidebar")
+ → @truefoundry/trueforge-ui (TrueforgeUI, layout="sidebar")
```
The SDK owns the shell: sidebar, thread list, composer, model and connector pickers, and the
@@ -40,7 +40,7 @@ moves Vite off `:3000`. That proxy is the only dev-specific wiring and lives ent
contract. It maps mutable session DTOs, pagination, turns, event history, cancellation, and SSE
metadata while keeping the browser pointed directly at `/api/v1/sessions`.
-`agent-ui-sdk` still declares the pre-0.1.6 contract (mounts carry `id`, list results are
+`trueforge-ui` still declares the pre-0.1.6 contract (mounts carry `id`, list results are
`PageResult`, absent values are `undefined`) while the runtime it delegates to reads `nextPageToken`
and tolerates `null`. The adapter emits values valid under both — derived mount ids, pages carrying
`nextPageToken` _and_ `hasNextPage()`, `null` normalised to absent — so no layer needs a cast.
diff --git a/packages/frontend/package.json b/packages/frontend/package.json
index edfa339e6..513ea44f0 100644
--- a/packages/frontend/package.json
+++ b/packages/frontend/package.json
@@ -8,23 +8,24 @@
"type": "module",
"scripts": {
"sdk:build": "pnpm --pm-on-fail=ignore --dir ../sdk install --ignore-scripts && pnpm --pm-on-fail=ignore --dir ../sdk build",
- "predev": "pnpm run sdk:build",
+ "ui:build": "pnpm --filter @truefoundry/trueforge-ui build",
+ "predev": "pnpm run sdk:build && pnpm run ui:build",
"dev": "trap 'exit 0' INT TERM; vite",
"dev:no-watch": "pnpm run dev",
- "prebuild": "pnpm run sdk:build",
+ "prebuild": "pnpm run sdk:build && pnpm run ui:build",
"build": "tsc --noEmit && vite build",
"preview": "vite preview",
- "pretypecheck": "pnpm run sdk:build",
+ "pretypecheck": "pnpm run sdk:build && pnpm run ui:build",
"typecheck": "tsc --noEmit",
- "pretest": "pnpm run sdk:build",
+ "pretest": "pnpm run sdk:build && pnpm run ui:build",
"test": "tsx --test \"tests/**/*.test.ts\""
},
"dependencies": {
"@assistant-ui/core": "0.2.22",
"@assistant-ui/react": "^0.14.24",
"@assistant-ui/store": "0.2.21",
- "@truefoundry/agent-ui-sdk": "^0.1.3",
"@truefoundry/assistant-ui-runtime": "^0.1.7",
+ "@truefoundry/trueforge-ui": "workspace:*",
"monaco-editor": "^0.52.0",
"react": "^19.2.4",
"react-dom": "^19.2.4",
diff --git a/packages/frontend/src/App.tsx b/packages/frontend/src/App.tsx
index b72f312ad..9cf2f81c2 100644
--- a/packages/frontend/src/App.tsx
+++ b/packages/frontend/src/App.tsx
@@ -1,11 +1,11 @@
import {
createTrueFoundryServer,
- TrueFoundryAssistantUI,
+ TrueforgeUI,
useShellMode,
WelcomeScreen,
type SlotOverrides,
type WelcomeScreenProps,
-} from '@truefoundry/agent-ui-sdk';
+} from '@truefoundry/trueforge-ui';
import { useEffect, useMemo, useRef, useState } from 'react';
import './agentUiSlots';
import { getCapabilities, listMcpServers, listModels, listSkills } from './catalog';
@@ -51,6 +51,7 @@ const server = createTrueFoundryServer<HarnessAgentSpec>({
connectorCatalog: createConnectorCatalog(),
// Skills settings still deferred (UI create shape is repo/directory; Harness is git manifest).
skillCatalog: {
+ getSkillCatalog: () => Promise.resolve([]),
listSkills: () => Promise.resolve([]),
createSkill: () => Promise.reject(new Error('not implemented')),
},
@@ -131,7 +132,7 @@ export function App() {
return (
<div className="app-root">
- <TrueFoundryAssistantUI
+ <TrueforgeUI
server={server}
theme={{
brand: {
@@ -139,7 +140,10 @@ export function App() {
},
}}
layout="sidebar"
- defaultAgentSpec={boot.defaultAgentSpec}
+ agentConfig={{
+ mode: 'AgentComposer',
+ defaultAgentSpec: boot.defaultAgentSpec,
+ }}
overrides={overrides}
className="app-assistant"
/>
diff --git a/packages/frontend/src/agentUiSlots.ts b/packages/frontend/src/agentUiSlots.ts
index 9631603f4..2dbc20b29 100644
--- a/packages/frontend/src/agentUiSlots.ts
+++ b/packages/frontend/src/agentUiSlots.ts
@@ -2,9 +2,9 @@
* The SDK augments AtomSlots via an internal `../theme/SlotsProvider.js` path
* that does not merge for package consumers. Re-declare the slots we override.
*/
-import type { WelcomeScreen } from '@truefoundry/agent-ui-sdk';
+import type { WelcomeScreen } from '@truefoundry/trueforge-ui';
-declare module '@truefoundry/agent-ui-sdk' {
+declare module '@truefoundry/trueforge-ui' {
interface AtomSlots {
WelcomeScreen: typeof WelcomeScreen;
}
diff --git a/packages/frontend/src/connectorCatalog.ts b/packages/frontend/src/connectorCatalog.ts
index b014c2d97..c6947f990 100644
--- a/packages/frontend/src/connectorCatalog.ts
+++ b/packages/frontend/src/connectorCatalog.ts
@@ -1,5 +1,5 @@
/**
- * Maps agent-ui-sdk connector-settings calls onto Harness
+ * Maps trueforge-ui connector-settings calls onto Harness
* `/api/v1/settings/mcp-servers` (upsert/list/tools) and `/api/v1/mcp-servers` (authorize).
*
* UI: `oauth` / `apiKey` / `none`, connector `id`.
@@ -14,14 +14,14 @@ import type {
CreateConnectorRequest,
ToolBase,
UpdateConnectorRequest,
-} from '@truefoundry/agent-ui-sdk';
+} from '@truefoundry/trueforge-ui';
import type { TrueForgeApi as Harness } from 'trueforge';
import { TrueForge } from 'trueforge';
-export type UiConnectorAuth = ConnectorAuth<'none' | 'oauth' | 'apiKey'>;
-export type UiConnectorAuthPublic = ConnectorAuthPublic<'none' | 'oauth' | 'apiKey'>;
-export type UiConnector = ConnectorBase<ToolBase, UiConnectorAuthPublic>;
-export type UiConnectorCatalogEntry = ConnectorCatalogEntry<UiConnectorAuthPublic>;
+export type UiConnectorAuth = ConnectorAuth;
+export type UiConnectorAuthPublic = ConnectorAuthPublic;
+export type UiConnector = ConnectorBase;
+export type UiConnectorCatalogEntry = ConnectorCatalogEntry;
const DEFAULT_API_KEY_HEADER = 'Authorization';
@@ -32,7 +32,8 @@ export function toUiAuthPublic(auth: Harness.ConfiguredMcpServerAuth | undefined
return { type: 'none' };
}
if (auth.type === 'dcr') {
- return { type: 'oauth' };
+ // Public oauth rows require authUrl; Harness only has a URL after authorize.
+ return { type: 'oauth', authUrl: '' };
}
const headerName = Object.keys(auth.headers)[0];
return {
@@ -48,16 +49,13 @@ export function toHarnessAuth(auth: ConnectorAuth): Harness.ConfiguredMcpServerA
if (auth.type === 'oauth') {
return { type: 'dcr' };
}
- if (auth.type === 'apiKey') {
- const apiKey = auth.apiKey?.trim();
- if (apiKey === undefined || apiKey === '') {
- throw new Error('API key is required for header-authenticated MCP servers');
- }
- const trimmedHeader = auth.headerName?.trim();
- const headerName = trimmedHeader !== undefined && trimmedHeader !== '' ? trimmedHeader : DEFAULT_API_KEY_HEADER;
- return { type: 'header', headers: { [headerName]: apiKey } };
+ const apiKey = auth.apiKey?.trim();
+ if (apiKey === undefined || apiKey === '') {
+ throw new Error('API key is required for header-authenticated MCP servers');
}
- throw new Error(`Unsupported connector auth type: ${auth.type}`);
+ const trimmedHeader = auth.headerName?.trim();
+ const headerName = trimmedHeader !== undefined && trimmedHeader !== '' ? trimmedHeader : DEFAULT_API_KEY_HEADER;
+ return { type: 'header', headers: { [headerName]: apiKey } };
}
export function toUiCatalogEntry(server: Harness.CatalogMcpServer): UiConnectorCatalogEntry {
@@ -71,18 +69,20 @@ export function toUiCatalogEntry(server: Harness.CatalogMcpServer): UiConnectorC
export function toUiTool(tool: Record<string, unknown>): ToolBase {
const name = typeof tool.name === 'string' && tool.name !== '' ? tool.name : 'tool';
- return { id: name, name };
+ const description = typeof tool.description === 'string' ? tool.description : '';
+ return { id: name, name, description };
}
-export function toUiConnector(server: Harness.ConfiguredMcpServer, tools: ToolBase[]): UiConnector {
+export function toUiConnector(server: Harness.ConfiguredMcpServer): UiConnector {
+ const auth = toUiAuthPublic(server.auth);
return {
id: server.name,
name: server.name,
description: server.url,
url: server.url,
- auth: toUiAuthPublic(server.auth),
+ auth,
+ requiresAuth: auth.type === 'oauth',
authenticated: server.authStatus.status === 'authenticated',
- tools,
};
}
@@ -119,11 +119,6 @@ async function getConfigured(name: string): Promise<Harness.ConfiguredMcpServer>
return existing;
}
-async function toUiConnectorWithTools(server: Harness.ConfiguredMcpServer): Promise<UiConnector> {
- const tools = await listToolsSafe(server.name);
- return toUiConnector(server, tools);
-}
-
async function resolveWriteAuth(req: { id?: string; auth: ConnectorAuth }): Promise<ConnectorAuth> {
if (req.auth.type !== 'apiKey') {
return req.auth;
@@ -152,12 +147,6 @@ async function resolveWriteAuth(req: { id?: string; auth: ConnectorAuth }): Prom
return { type: 'apiKey', apiKey: stored, headerName };
}
-function openAuthorizationUrl(url: string): void {
- if (typeof globalThis.open === 'function') {
- globalThis.open(url, '_blank', 'noopener,noreferrer');
- }
-}
-
/** Settings connector port for `createTrueFoundryServer`. Delete omitted; disconnect unsupported. */
export function createConnectorCatalog(): ConnectorCatalogServer<
ToolBase,
@@ -165,8 +154,8 @@ export function createConnectorCatalog(): ConnectorCatalogServer<
UiConnectorAuthPublic,
UiConnector,
UiConnectorCatalogEntry,
- CreateConnectorRequest<UiConnectorAuth>,
- UpdateConnectorRequest<UiConnectorAuth>
+ CreateConnectorRequest,
+ UpdateConnectorRequest
> {
return {
getConnectorCatalog: async () => {
@@ -175,7 +164,7 @@ export function createConnectorCatalog(): ConnectorCatalogServer<
},
listConnectors: async req => {
const body = await client.settings.mcpServers.list();
- const connectors = await Promise.all(body.data.map(server => toUiConnectorWithTools(server)));
+ const connectors = body.data.map(toUiConnector);
const query = req?.query?.trim().toLowerCase();
if (query === undefined || query === '') {
return connectors;
@@ -187,27 +176,28 @@ export function createConnectorCatalog(): ConnectorCatalogServer<
connector.url.toLowerCase().includes(query),
);
},
+ getToolsByConnectorId: async ({ id }) => listToolsSafe(id),
createConnector: async req => {
const auth = await resolveWriteAuth({ auth: req.auth });
const body = await client.settings.mcpServers.upsert(toHarnessManifest({ name: req.name, url: req.url, auth }));
- return toUiConnectorWithTools(body.data);
+ return toUiConnector(body.data);
},
updateConnector: async req => {
const auth = await resolveWriteAuth({ id: req.id, auth: req.auth });
const body = await client.settings.mcpServers.upsert(toHarnessManifest({ name: req.id, url: req.url, auth }));
- return toUiConnectorWithTools(body.data);
+ return toUiConnector(body.data);
},
authenticateConnector: async req => {
- const redirectUrl = `${globalThis.location.origin}${globalThis.location.pathname}`;
+ const redirectUrl = req.redirectURL ?? `${globalThis.location.origin}${globalThis.location.pathname}`;
const result = await client.mcpServers.authorize(req.id, { redirectUrl });
if (result.status === 'auth_required') {
if (result.authorizationUrl === undefined) {
throw new Error(`Authorization URL missing for MCP server "${req.id}"`);
}
- openAuthorizationUrl(result.authorizationUrl);
+ return { authorization_endpoint: result.authorizationUrl };
}
const server = await getConfigured(req.id);
- return toUiConnectorWithTools(server);
+ return toUiConnector(server);
},
disconnectConnector: () => Promise.reject(new Error('Disconnect is not supported by Harness yet')),
};
diff --git a/packages/frontend/src/harnessServer.ts b/packages/frontend/src/harnessServer.ts
index 1deec226c..0fa25af19 100644
--- a/packages/frontend/src/harnessServer.ts
+++ b/packages/frontend/src/harnessServer.ts
@@ -1,5 +1,5 @@
/**
- * Harness `AgentUIServer` adapter for @truefoundry/agent-ui-sdk.
+ * Harness `AgentUIServer` adapter for @truefoundry/trueforge-ui.
*
* The SDK still declares the pre-0.1.6 server contract — mounts carry `id`,
* list results are `PageResult`, and absent values are `undefined` — while the
@@ -23,7 +23,7 @@ import type {
Turn,
TurnInputItem,
UserMessageContent,
-} from '@truefoundry/agent-ui-sdk';
+} from '@truefoundry/trueforge-ui';
import type { TrueForgeApi as Harness } from 'trueforge';
import { TrueForge } from 'trueforge';
export type HarnessSkillMount = SkillMount;
@@ -212,30 +212,19 @@ export function createHarnessChatServer(options: CreateHarnessServerOptions = {}
return toUiSession(response.data);
},
- async *prepareAndExecuteTurn({
+ async *createTurn({
sessionId,
input,
previousTurnId,
- abortSignal,
- headers,
}: {
sessionId: string;
input?: TurnInputItem[];
previousTurnId?: string;
- abortSignal?: AbortSignal;
- headers?: Record<string, string>;
}) {
- const stream = await client.sessions.createTurn(
- sessionId,
- {
- ...(input === undefined ? {} : { input: toHarnessInput(input) }),
- ...(previousTurnId === undefined ? {} : { previousTurnId: toHarnessPreviousTurnId(previousTurnId) }),
- },
- {
- ...(abortSignal === undefined ? {} : { abortSignal }),
- ...(headers === undefined ? {} : { headers }),
- },
- );
+ const stream = await client.sessions.createTurn(sessionId, {
+ ...(input === undefined ? {} : { input: toHarnessInput(input) }),
+ ...(previousTurnId === undefined ? {} : { previousTurnId: toHarnessPreviousTurnId(previousTurnId) }),
+ });
let fallbackSequence = 0;
for await (const item of stream.withMetadata()) {
yield {
diff --git a/packages/frontend/src/index.css b/packages/frontend/src/index.css
index 214f75797..f60c0a70e 100644
--- a/packages/frontend/src/index.css
+++ b/packages/frontend/src/index.css
@@ -1,8 +1,8 @@
/* The SDK ships utilities and theme tokens but no reset. Preflight goes in its
own layer: unlayered it would outrank `tfy-agent-ui-utilities` and strip the
SDK's own margin, padding and border. */
-@import 'tailwindcss/preflight.css' layer(preflight);
-@import '@truefoundry/agent-ui-sdk/styles.css';
+@import "tailwindcss";
+@import "@truefoundry/trueforge-ui/styles.css";
html,
body,
diff --git a/packages/frontend/src/modelProviderCatalog.ts b/packages/frontend/src/modelProviderCatalog.ts
index c4cfcd6f2..5c5a757d3 100644
--- a/packages/frontend/src/modelProviderCatalog.ts
+++ b/packages/frontend/src/modelProviderCatalog.ts
@@ -1,5 +1,5 @@
/**
- * Maps agent-ui-sdk model-settings calls onto Harness
+ * Maps trueforge-ui model-settings calls onto Harness
* `/api/v1/settings/model-providers` (name-keyed upsert, no delete).
*
* UI: flat `apiKey` / model `id`. Harness: `auth.apiKey` / `modelId`.
@@ -12,7 +12,7 @@ import type {
ModelProviderBase,
ModelProviderCatalogEntry,
UpdateModelProviderRequest,
-} from '@truefoundry/agent-ui-sdk';
+} from '@truefoundry/trueforge-ui';
import { TrueForgeApi as Harness, TrueForge } from 'trueforge';
/** Custom-form rows omit properties; catalog rows round-trip them. */
export type UiModelEntry = ModelEntry & {
diff --git a/packages/frontend/tests/connectorCatalog.test.ts b/packages/frontend/tests/connectorCatalog.test.ts
index c23c7e46c..c6d2a7de9 100644
--- a/packages/frontend/tests/connectorCatalog.test.ts
+++ b/packages/frontend/tests/connectorCatalog.test.ts
@@ -12,7 +12,7 @@ import {
describe('connectorCatalog mappers', () => {
it('maps harness auth to UI public auth without secrets', () => {
assert.deepEqual(toUiAuthPublic(undefined), { type: 'none' });
- assert.deepEqual(toUiAuthPublic({ type: 'dcr' }), { type: 'oauth' });
+ assert.deepEqual(toUiAuthPublic({ type: 'dcr' }), { type: 'oauth', authUrl: '' });
assert.deepEqual(toUiAuthPublic({ type: 'header', headers: { Authorization: 'Bearer secret' } }), {
type: 'apiKey',
headerName: 'Authorization',
@@ -48,37 +48,40 @@ describe('connectorCatalog mappers', () => {
id: 'linear',
name: 'linear',
url: 'https://mcp.linear.app/mcp',
- auth: { type: 'oauth' },
+ auth: { type: 'oauth', authUrl: '' },
},
);
});
- it('maps configured servers and tools for the settings list card', () => {
+ it('maps configured servers without embedding tools', () => {
assert.deepEqual(
- toUiConnector(
- {
- type: 'remote',
- name: 'deepwiki',
- url: 'https://mcp.deepwiki.com/mcp',
- authStatus: { status: 'authenticated' },
- },
- [toUiTool({ name: 'search' }), toUiTool({})],
- ),
+ toUiConnector({
+ type: 'remote',
+ name: 'deepwiki',
+ url: 'https://mcp.deepwiki.com/mcp',
+ authStatus: { status: 'authenticated' },
+ }),
{
id: 'deepwiki',
name: 'deepwiki',
description: 'https://mcp.deepwiki.com/mcp',
url: 'https://mcp.deepwiki.com/mcp',
auth: { type: 'none' },
+ requiresAuth: false,
authenticated: true,
- tools: [
- { id: 'search', name: 'search' },
- { id: 'tool', name: 'tool' },
- ],
},
);
});
+ it('maps tool rows with description for getToolsByConnectorId', () => {
+ assert.deepEqual(toUiTool({ name: 'search', description: 'Find docs' }), {
+ id: 'search',
+ name: 'search',
+ description: 'Find docs',
+ });
+ assert.deepEqual(toUiTool({}), { id: 'tool', name: 'tool', description: '' });
+ });
+
it('builds upsert manifests from UI create/update requests', () => {
assert.deepEqual(
toHarnessManifest({
diff --git a/packages/frontend/tests/harnessServer.test.ts b/packages/frontend/tests/harnessServer.test.ts
index 8a993efb7..b88984168 100644
--- a/packages/frontend/tests/harnessServer.test.ts
+++ b/packages/frontend/tests/harnessServer.test.ts
@@ -90,7 +90,7 @@ describe('createHarnessChatServer', () => {
const server = createHarnessChatServer({ fetch: fetchMock });
const events = [];
- for await (const event of server.prepareAndExecuteTurn({
+ for await (const event of server.createTurn({
sessionId: 'ses_1',
input: [{ type: 'user.message', content: 'hello' }],
// The runtime's root sentinel; Harness 404s unless it becomes `null`.
diff --git a/packages/server/registry/mcp.yaml b/packages/server/registry/mcp.yaml
new file mode 100644
index 000000000..1fe84ee8d
--- /dev/null
+++ b/packages/server/registry/mcp.yaml
@@ -0,0 +1,11 @@
+# MCP servers available to agents.
+#
+# Auth headers are configured via env vars, never in this file:
+# MCP_HEADERS - default headers for every MCP server
+# MCP_{NAME}_HEADERS - per-server overrides ({NAME} = server name,
+# uppercased, non-alphanumerics replaced by "_")
+mcp_servers:
+ - name: github-remote
+ # TODO(oss): replace internal endpoint with a placeholder before the repo
+ # goes public.
+ url: https://internal.devtest.truefoundry.tech/api/llm/truefoundry/mcp/github-remote/server
diff --git a/packages/server/registry/models.yaml b/packages/server/registry/models.yaml
new file mode 100644
index 000000000..9079c5826
--- /dev/null
+++ b/packages/server/registry/models.yaml
@@ -0,0 +1,19 @@
+# Models reachable through the OpenAI-compatible gateway at base_url.
+#
+# Auth headers are configured via env vars, never in this file:
+# MODEL_API_KEY - default API key for base_url (required)
+# MODEL_{NAME}_API_KEY - per-model API key override
+# MODEL_HEADERS - extra default headers for every model
+# MODEL_{NAME}_HEADERS - per-model overrides ({NAME} = model name,
+# uppercased, non-alphanumerics replaced by "_")
+
+models:
+ - name: claude-sonnet-4-6
+ model_id: anthropic/claude-sonnet-4-6
+ provider: generic
+ base_url: https://internal.devtest.truefoundry.tech/api/llm
+ max_output_tokens: 32768
+ reasoning_efforts:
+ - low
+ - medium
+ - high
diff --git a/packages/server/registry/skills.yaml b/packages/server/registry/skills.yaml
new file mode 100644
index 000000000..b034051ff
--- /dev/null
+++ b/packages/server/registry/skills.yaml
@@ -0,0 +1,11 @@
+# Agent skills, each a directory with a SKILL.md in a public git repository.
+# url - public git repository
+# path - directory containing SKILL.md (optional, repo root if omitted)
+# ref - branch, tag, or commit SHA to pin (optional, default branch if omitted)
+# description - concise guidance for when to use the skill
+skills:
+ - name: algorithmic-art
+ url: https://github.com/anthropics/skills
+ path: skills/algorithmic-art
+ ref: main
+ description: Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration.
diff --git a/packages/trueforge-ui-sdk/.gitignore b/packages/trueforge-ui-sdk/.gitignore
new file mode 100644
index 000000000..dbc315dff
--- /dev/null
+++ b/packages/trueforge-ui-sdk/.gitignore
@@ -0,0 +1,22 @@
+# dependencies
+node_modules/
+
+# tsup build output
+dist/
+
+# vitest
+coverage/
+
+# logs
+*.log
+npm-debug.log*
+pnpm-debug.log*
+
+# typescript
+*.tsbuildinfo
+
+# pack artifacts
+*.tgz
+
+# misc
+.DS_Store
diff --git a/packages/trueforge-ui-sdk/.prettierrc.json b/packages/trueforge-ui-sdk/.prettierrc.json
new file mode 100644
index 000000000..4a1222f56
--- /dev/null
+++ b/packages/trueforge-ui-sdk/.prettierrc.json
@@ -0,0 +1,7 @@
+{
+ "semi": true,
+ "singleQuote": false,
+ "trailingComma": "all",
+ "printWidth": 100,
+ "tabWidth": 2
+}
diff --git a/packages/trueforge-ui-sdk/CHANGELOG.md b/packages/trueforge-ui-sdk/CHANGELOG.md
new file mode 100644
index 000000000..5ce71771d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/CHANGELOG.md
@@ -0,0 +1,220 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Breaking
+
+- **Renamed `TrueFoundryAssistantUI` → `TrueforgeUI`** (props type
+ `TrueFoundryAssistantUIProps` → `TrueforgeUIProps`). Update imports and JSX.
+- **`TrueforgeUI` agent props** — replaced top-level `agentName` and
+ `defaultAgentSpec` with a single discriminated `agentConfig`. There is no
+ compat shim; hosts must update call sites.
+- **Icons use Lucide** (`lucide-react`) instead of Font Awesome. Default
+ registry keys are unchanged (`paperclip`, `xmark`, …); `theme.icons` values
+ are Lucide components, React nodes, render fns, or SVGR SVGs — not
+ `IconDefinition`. Drop `@fortawesome/*` if you only used them for this SDK.
+- **Removed `tfy-web-components`** dependency and peer. Primitives, icons,
+ theme, Markdown, and agent-chat molecules are owned by this SDK.
+- `theme` prop is now `ThemeConfig` (object), not `"light" | "dark"`. Mode
+ lives at `theme.mode`. Example: `theme={{ mode: "dark", preset: "claude" }}`.
+- Slot `Button` / `IconButton` use shadcn-aligned props (`variant`, `size`,
+ children). Compound APIs (`Button.Primary`, `icon=` string props) are gone.
+- Import styles with only `@import "@truefoundry/trueforge-ui/styles.css"`
+ (no `tfy-web-components/theme.css`).
+- `layout` accepts a built-in string **or** a host `React.ComponentType`.
+- **`server` prop no longer accepts `{ type: "custom", server }`.** Pass a ready
+ `AgentUIServer` directly (`server={agentServer}`). Built-in configs
+ (`truefoundry` / `trueforge`) are unchanged and now accept an optional
+ `catalog`.
+
+### Added
+
+- **Reasoning-effort selector** beside the model picker in the draft composer.
+ Shown only when the selected `ModelSelection` declares `reasoningEfforts`;
+ the effort is coerced into the spec on model change or explicit pick.
+- **Skills catalog** — `getSkillCatalog` with an Available/Selected split;
+ registry skills (`catalogId`) return to Available on remove, GitHub imports
+ are deleted for good. New types: `RegistrySkill`, `GithubSkill`,
+ `DefinedSkill`, `SkillConfigBase`, `SkillCatalogEntry`,
+ `CreateSkillRequestBase`, `SelectRegistrySkillRequest`,
+ `ImportGithubSkillRequest`, `SkillCatalogServer.getSkillCatalog`.
+- **Sandbox catalog** — list/create/update/delete of connected sandboxes from a
+ catalog. New types: `SandboxConfig`, `SandboxCatalogEntry`, `SandboxBase`,
+ `CreateSandboxRequest`, `UpdateSandboxRequest`, `SandboxCatalogServer`.
+ `apiKey` is never stored in the catalog and is optional on update (blank keeps
+ the existing key).
+- `TrueforgeBuiltInServerConfig` exported for hosts that build the built-in
+ config separately.
+
+- **`agentConfig` shell modes** on `TrueforgeUI` /
+ `ShellModeProvider`:
+ - `SingleAgent` — locked named agent (`name` required)
+ - `AgentLibrary` — Agents Library only; idle empty state until pick; no New Chat
+ - `AgentComposer` — draft composer only (no library)
+ - `AgentLibraryWithComposer` — library + draft (default when omitted)
+- **Clear Chat** control in thread headers (sidebar / drawer / dock / widget).
+ Resets the current named thread or opens a fresh draft.
+- `ClearChatButton`, `SelectAgentEmptyState`, `AgentConfig`,
+ `DEFAULT_AGENT_CONFIG` exported from the main barrel.
+- Owned `ThemeProvider` with light / dark / system, CSS token injection,
+ `theme.brand`, `theme.icons`, `theme.classNames`, `theme.className`.
+- Presets: `truefoundry`, `claude`, `chatgpt`, `gemini`.
+- `BrandLogo` / `BrandIcon` / `useBrand`; `Icon` / `IconRegistry`.
+- In-repo Markdown (OpenUI fences + syntax-highlighter), `MonacoEditorCore`,
+ `CodeEditor`.
+- Example app: preset switcher + custom layout demo; `VITE_TFY_AGENT_MODE` to
+ try shell modes.
+
+### Migration
+
+#### Component rename
+
+```tsx
+// Before
+import { TrueFoundryAssistantUI } from '@truefoundry/trueforge-ui';
+<TrueFoundryAssistantUI server={server} layout="sidebar" />;
+
+// After
+import { TrueforgeUI } from '@truefoundry/trueforge-ui';
+<TrueforgeUI server={server} layout="sidebar" />;
+```
+
+#### `agentConfig` (host must update)
+
+| Before | After |
+| ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| `agentName="support-agent"` | `agentConfig={{ mode: "SingleAgent", name: "support-agent" }}` |
+| omit `agentName` (+ optional `defaultAgentSpec`) | omit `agentConfig`, or `agentConfig={{ mode: "AgentLibraryWithComposer", defaultAgentSpec }}` |
+| — | `agentConfig={{ mode: "AgentLibrary" }}` — library only, pick agent to start |
+| — | `agentConfig={{ mode: "AgentComposer", defaultAgentSpec }}` — draft only |
+
+```tsx
+// Before
+<TrueFoundryAssistantUI server={server} layout="sidebar" agentName="support-agent" />
+<TrueFoundryAssistantUI
+ server={server}
+ layout="sidebar"
+ defaultAgentSpec={{ model: { name: "openai-main/gpt-4.1" } }}
+/>
+
+// After
+<TrueforgeUI
+ server={server}
+ layout="sidebar"
+ agentConfig={{ mode: "SingleAgent", name: "support-agent" }}
+/>
+<TrueforgeUI
+ server={server}
+ layout="sidebar"
+ agentConfig={{
+ mode: "AgentLibraryWithComposer",
+ defaultAgentSpec: { model: { name: "openai-main/gpt-4.1" } },
+ }}
+/>
+```
+
+`ShellModeProvider` likewise takes `agentConfig` instead of `agentName` /
+`defaultAgentSpec`.
+
+#### Other Unreleased migrations
+
+1. Drop `@import "tfy-web-components/theme.css"` and the `tfy-web-components`
+ package.
+2. Replace `theme="dark"` with `theme={{ mode: "dark" }}`.
+3. Update Button/IconButton overrides to the new prop surface.
+4. Replace product marks via `theme.brand`; action icons via `theme.icons`
+ (Lucide / SVG — not Font Awesome `IconDefinition`).
+5. Optionally set `layout={MyLayout}` and style content via
+ `theme.classNames` or `.aui-markdown` / `.aui-syntax-highlighter` /
+ `.aui-openui` / `.aui-monaco`.
+
+## [0.1.0]
+
+### Breaking
+
+- Main entry no longer re-exports tfy design-system **values** (`Button`,
+ `IconButton`, `IconProvider`, `Modal`, `Dialog`, `Accordion*`, `Skeleton`,
+ `LightTooltip`, `registerIcons`, …). Import those from `tfy-web-components`.
+ Override **types** `ButtonProps` / `ButtonSize` / `IconButtonProps` remain
+ on `@truefoundry/trueforge-ui`.
+- Peer dependency ranges aligned with supported versions (`@truefoundry/assistant-ui-runtime` `^0.1.4`, `truefoundry-gateway-sdk` `^0.4.0-rc.1`, `tfy-web-components` `^0.0.31`).
+- tfy/MUI peer stack (`@mui/material`, `@emotion/*`, Font Awesome, `@openuidev/*`) moved from `dependencies` to `peerDependencies`; hosts must install them.
+- `MessageTimestamp` is presentational and requires `createdAt`.
+- `UserMessageActionBar` is presentational (copy/edit/retry props); runtime wiring lives in containers.
+- `MessageActionBar` accepts optional `createdAt` and passes it to `MessageTimestamp`.
+- Default stylesheet no longer loads Google Fonts from the CDN; override `--font-agent-ui` in host CSS if needed.
+- `prepare` script replaced with `prepublishOnly` (install no longer builds automatically).
+
+### Added
+
+- `TrueforgeUI` quick-start component with `layout`: `sidebar` | `drawer` |
+ `dock` | `widget` (slots outside the chat provider so toast overrides apply).
+- Curated re-exports: `useAui`, `useAuiState`, `AssistantState` from the main
+ barrel and `@truefoundry/trueforge-ui/assistant-ui`; `useTheme` from the main
+ barrel.
+- Optional `onThreadOpen` on `ThreadListContainer` for stack/drawer chrome.
+- npm package metadata: `repository`, `homepage`, `bugs`, `keywords`.
+- Drawer / widget Escape-to-close; drawer backdrop dismiss; widget `aria-modal`.
+- Drawer / widget focus management (`inert` on background, focus dialog, restore).
+- `docs/api.md` curated public API reference.
+- CI coverage floor + example app build.
+- Apache-2.0 `LICENSE`, `NOTICE`, `CONTRIBUTING.md`, `SECURITY.md`, `CODE_OF_CONDUCT.md`.
+- GitHub issue/PR templates and CI workflow.
+- `docs/` (architecture, customization, compatibility).
+- ESLint + Prettier.
+- Unit tests for tool-call parsing helpers and `computeAgentStepsSplit`.
+
+### Changed
+
+- Required peers are only `react` / `react-dom`. `@assistant-ui/core`
+ (`^0.2.22`), `@assistant-ui/react` (`^0.14.24`), and
+ `tfy-web-components@^0.0.32` moved to `dependencies` (still listed as optional
+ peers for hosts that install them directly for customization). Happy path:
+ `yarn add @truefoundry/trueforge-ui`. Yarn `resolutions` pin a single
+ `@assistant-ui/core` / `store` / `tap` copy to avoid duplicate AuiProvider.
+- `tfy-web-components` resolves from npm (`^0.0.32`) instead of a local
+ `file:` tarball.
+- MUI / Emotion / OpenUI / Monaco / extra Font Awesome packages come from
+ `tfy-web-components` (not peers of this SDK).
+- Font Awesome packages this SDK imports (`fontawesome-svg-core`,
+ `free-solid-svg-icons`) moved to `dependencies`.
+- `SlotOverrides` is `Partial<AtomSlots>` only (no `Record<string, unknown>`).
+- `TrueforgeUI` lazy-layout `Suspense` fallback is a pulse skeleton
+ instead of blank.
+- README reordered: quick start (prefer `client`) before advanced sections.
+
+### Removed
+
+- Unused `TokensProvider` / `useTokens` / `defaultTokens` public API (and
+ related token types). Theme via CSS variables from `styles.css` instead.
+- `examples/vite-chat` sample app.
+- Unused `classnames` dependency (provided by `tfy-web-components@^0.0.32`).
+- Direct design-system `devDependencies` duplicated from web-components
+ (`@mui/material`, `@emotion/*`, `@openuidev/*`, `monaco-editor`,
+ `@fortawesome/free-regular-svg-icons`, `@fortawesome/react-fontawesome`).
+- Standalone `@truefoundry/trueforge-ui/openui.css` export — OpenUI styles ship
+ inside `styles.css`.
+- Unused packages: `lodash-es`, `react-markdown`, `remark-gfm`, `class-variance-authority`.
+- Broken `pack:dev` script.
+
+### Fixed
+
+- Error toasts stack (up to 5), use compact theme sizing, and include a copy action.
+- Atom/container architecture: atoms no longer import `@assistant-ui/*`.
+- Error toasts truncate large gateway response bodies.
+
+### Note
+
+- `github-markdown-css` remains a **devDependency** required to compile
+ `dist/styles.css` (pulled in via tfy Markdown CSS).
+
+## [0.0.8] - 2026-07-24
+
+### Changed
+
+- Package and dependency updates prior to the 0.1.0 open-source readiness pass.
diff --git a/packages/trueforge-ui-sdk/CODE_OF_CONDUCT.md b/packages/trueforge-ui-sdk/CODE_OF_CONDUCT.md
new file mode 100644
index 000000000..2aa0ebe11
--- /dev/null
+++ b/packages/trueforge-ui-sdk/CODE_OF_CONDUCT.md
@@ -0,0 +1,64 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment include:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes,
+ and learning from the experience
+- Focusing on what is best not just for us as individuals, but for the overall
+ community
+
+Examples of unacceptable behavior include:
+
+- The use of sexualized language or imagery, and sexual attention or advances of
+ any kind
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or email address,
+ without their explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+[homepage]: https://www.contributor-covenant.org
diff --git a/packages/trueforge-ui-sdk/CONTRIBUTING.md b/packages/trueforge-ui-sdk/CONTRIBUTING.md
new file mode 100644
index 000000000..e5487e88e
--- /dev/null
+++ b/packages/trueforge-ui-sdk/CONTRIBUTING.md
@@ -0,0 +1,37 @@
+# Contributing
+
+Thanks for contributing to `@truefoundry/trueforge-ui`.
+
+## Development
+
+From the monorepo root:
+
+```bash
+pnpm install
+pnpm --filter @truefoundry/trueforge-ui typecheck
+pnpm --filter @truefoundry/trueforge-ui test
+pnpm --filter @truefoundry/trueforge-ui build
+pnpm --filter @truefoundry/trueforge-ui lint
+```
+
+Local demo: build the SDK, then follow [example/README.md](./example/README.md).
+
+- Prefer small, focused PRs.
+- Match existing patterns in `src/atoms` (presentational) and `src/containers` (runtime wiring).
+- Atoms must not import `@assistant-ui/*` or TrueFoundry runtime hooks.
+- Containers resolve atoms via `useSlot`, not direct atom imports (types are fine).
+- Update `CHANGELOG.md` under **Unreleased** for user-visible changes.
+
+## Pull requests
+
+1. Open a PR against `main`.
+2. Ensure CI is green (`typecheck`, `test`, `build`, `lint`).
+3. Confirm the Unreleased changelog entry when the change is user-visible.
+
+## Reporting bugs
+
+Include package version, peer versions, and a minimal reproduction when possible.
+
+## Security
+
+Do not open public issues for vulnerabilities. See [SECURITY.md](./SECURITY.md).
diff --git a/packages/trueforge-ui-sdk/LICENSE b/packages/trueforge-ui-sdk/LICENSE
new file mode 100644
index 000000000..d64569567
--- /dev/null
+++ b/packages/trueforge-ui-sdk/LICENSE
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/packages/trueforge-ui-sdk/NOTICE b/packages/trueforge-ui-sdk/NOTICE
new file mode 100644
index 000000000..454f88d6b
--- /dev/null
+++ b/packages/trueforge-ui-sdk/NOTICE
@@ -0,0 +1,17 @@
+@truefoundry/trueforge-ui
+Copyright 2024-2026 TrueFoundry
+
+This product includes software developed at TrueFoundry.
+
+This distribution may include or depend on third-party software. Notable
+dependencies and their licenses include (non-exhaustive):
+
+- @assistant-ui/react / @assistant-ui/core — see their respective LICENSE files
+- tfy-web-components — see its LICENSE
+- @openuidev/react-ui and related OpenUI packages — see their LICENSE files
+- @fortawesome/fontawesome-svg-core and related packages — Font Awesome Free license
+- @mui/material and @emotion/* — see their respective LICENSE files
+- lucide-react — ISC / Lucide license
+
+Full license texts for installed packages are available in node_modules under
+each package's LICENSE (or equivalent) file.
diff --git a/packages/trueforge-ui-sdk/README.md b/packages/trueforge-ui-sdk/README.md
new file mode 100644
index 000000000..5ec8530e2
--- /dev/null
+++ b/packages/trueforge-ui-sdk/README.md
@@ -0,0 +1,497 @@
+# @truefoundry/trueforge-ui
+
+[CI](https://github.com/truefoundry/harness/actions/workflows/ci.yml)
+[npm](https://www.npmjs.com/package/@truefoundry/trueforge-ui)
+[License](./LICENSE)
+
+A themeable, composable React SDK for building production-ready AI agent chat applications.
+Build your own agent chat platform with a flexible UI layer that works with **TrueFoundry** (Control Plane + Gateway), **TrueForge** (harness), or any custom backend. The SDK is fully open source, giving you complete control over your architecture, components, and integrations.
+Powered by [assistant-ui](https://www.assistant-ui.com/), it follows the familiar **shadcn/ui** and **Tailwind CSS variable** theming conventions, making it easy to customize every aspect of the experience.
+
+**Features**
+
+- **Fully themeable** — Use built-in themes inspired by **TrueFoundry**, **ChatGPT**, **Claude**, and **Gemini**, or create your own brand identity.
+- **Composable by design** — Swap layouts, components, and interaction patterns to fit your product.
+- **Backend agnostic** — Connect to **TrueFoundry**, **TrueForge**, or any custom API via `TrueforgeServerConfig`.
+- **Open source** — Extend, customize, and contribute without vendor lock-in.
+- **Built on assistant-ui** — Leverage a modern React foundation with seamless shadcn/ui and Tailwind CSS integration.
+- **Production ready** — Focus on your agents while the SDK handles the chat experience.
+
+Bring your own **brand, colors, layout, components, and server**—the Agent SDK wires up the rest.
+
+### Checkout the Demo [here](./example/)
+
+---
+
+## Table of contents
+
+- [Installation](#installation)
+- [Getting started](#getting-started)
+- [`<TrueforgeUI />` props](#trueforgeui--props)
+- [Theming](#theming)
+- [Brand / logo](#brand--logo)
+- [Agent modes](#agent-modes)
+- [Layouts](#layouts)
+- [Custom layouts](#custom-layouts)
+- [Overriding components](#overriding-components)
+- [Server](#server)
+- [Exports](#exports)
+- [Docs](#docs)
+- [License](#license)
+
+---
+
+## Installation
+
+```bash
+npm install @truefoundry/trueforge-ui
+# or
+pnpm add @truefoundry/trueforge-ui
+# or
+yarn add @truefoundry/trueforge-ui
+```
+
+`react` / `react-dom` are required peers. Import the stylesheet after Tailwind in the host:
+
+```css
+@import 'tailwindcss';
+@import '@truefoundry/trueforge-ui/styles.css';
+```
+
+See [docs/compatibility.md](./docs/compatibility.md) for version ranges.
+
+---
+
+## Getting started
+
+**TrueFoundry** (`type: "truefoundry"`) — Control Plane + Gateway
+
+Zero-config path: the SDK builds the agent UI server from your API key and
+control plane URL (optional explicit gateway URL).
+
+```tsx
+import { TrueforgeUI } from '@truefoundry/trueforge-ui';
+
+export default function App() {
+ return (
+ <div style={{ height: '100dvh' }}>
+ <TrueforgeUI
+ server={{
+ type: 'truefoundry',
+ apiKey: process.env.TFY_API_KEY!,
+ controlPlaneURL: process.env.TFY_CONTROL_PLANE_URL!,
+ // gatewayPlaneURL: process.env.TFY_GATEWAY_URL, // optional
+ }}
+ layout="sidebar"
+ />
+ </div>
+ );
+}
+```
+
+**TrueForge** (`type: "trueforge"`) — harness (coming soon)
+
+Typed for hosts adopting the harness adapter; selecting it currently surfaces a
+not-implemented error until the adapter ships.
+
+```tsx
+<TrueforgeUI
+ server={{
+ type: 'trueforge',
+ apiKey: process.env.TFY_API_KEY!,
+ }}
+ layout="sidebar"
+/>
+```
+
+**Custom** — bring your own `AgentUIServer`
+
+Use this when you compose chat + builder yourself (e.g. chat-only gateway
+adapter + stub catalog, or a full host BFF). Pass the server object directly.
+
+```tsx
+import { TrueforgeUI, createTrueFoundryServer } from '@truefoundry/trueforge-ui';
+import { createTrueFoundryChatServer } from '@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter';
+
+const chatServer = createTrueFoundryChatServer({
+ apiKey: process.env.TFY_API_KEY!,
+ baseUrl: process.env.TFY_GATEWAY_URL!,
+});
+
+const server = createTrueFoundryServer({
+ chatServer,
+ getModels: async () => [],
+ getSkills: async () => [],
+ getMcp: async () => [],
+ searchAgents: async () => [],
+ saveAgent: async () => ({}),
+});
+
+export default function App() {
+ return (
+ <div style={{ height: '100dvh' }}>
+ <TrueforgeUI server={server} layout="sidebar" />
+ </div>
+ );
+}
+```
+
+## `<TrueforgeUI />` props
+
+`<TrueforgeUI />` is the single entry point. Every capability is driven by a prop.
+
+```tsx
+<TrueforgeUI
+ server={{
+ type: 'truefoundry',
+ apiKey: process.env.TFY_API_KEY!,
+ controlPlaneURL: process.env.TFY_CONTROL_PLANE_URL!,
+ }} // or agentServer / { type: "trueforge", apiKey }
+ layout="sidebar" // 'sidebar' | 'drawer' | 'dock' | 'widget' | CustomLayout
+ agentConfig={{
+ mode: 'AgentLibraryWithComposer', // default when omitted
+ defaultAgentSpec: { model: { name: 'openai-main/gpt-4.1' } },
+ }}
+ theme={{
+ preset: 'claude',
+ brand: { name: 'Acme', icon: { src: '/logo.svg', alt: 'Acme' } },
+ }}
+ overrides={{/* slot overrides */}}
+ className="h-full"
+/>
+```
+
+| Prop | Type | Required | Description |
+| ------------------ | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
+| `server` | `TrueforgeServerConfig` | ✅ | Built-in config (`truefoundry` / `trueforge`) **or** a ready `AgentUIServer`. |
+| `layout` | `LayoutProp` | ✅ | Built-in layout string **or** a custom React component. |
+| `agentConfig` | `AgentConfig` | — | Shell mode: SingleAgent / AgentLibrary / AgentComposer / AgentLibraryWithComposer. Defaults to library + composer. |
+| `theme` | `ThemeConfig` | — | Preset, mode, tokens, brand, icons (see [Theming](#theming)). |
+| `overrides` | `Partial<SlotOverrides>` | — | Map of slot overrides (see [Overriding components](#overriding-components)). |
+| `className` | `string` | — | Applied to the layout root. |
+| `initialSessionId` | `string` | — | Resume a specific session. |
+| `onError` | `(error: unknown) => void` | — | Host error hook (runtime + server init). |
+
+Later sections use `server` as a `TrueforgeServerConfig` (usually `type: "truefoundry"`). For a host-built port, pass the `AgentUIServer` directly.
+
+---
+
+## Theming
+
+Pass a preset and/or tokens and the whole UI adapts. Under the hood values map onto shadcn-style CSS variables (`--primary`, `--background`, `--foreground`, `--muted`, `--accent`, `--radius`), so no component needs palette-specific code.
+
+```tsx
+const server = {
+ type: 'truefoundry' as const,
+ apiKey: process.env.TFY_API_KEY!,
+ controlPlaneURL: process.env.TFY_CONTROL_PLANE_URL!,
+};
+
+<TrueforgeUI
+ server={server}
+ layout="sidebar"
+ theme={{
+ preset: 'claude', // 'truefoundry' | 'claude' | 'chatgpt' | 'gemini'
+ mode: 'dark', // omit for uncontrolled (useTheme().setTheme works)
+ tokens: {
+ primary: 'oklch(0.55 0.2 275)',
+ background: 'oklch(0.14 0.02 260)',
+ foreground: 'oklch(0.97 0 0)',
+ muted: 'oklch(0.22 0.02 260)',
+ accent: 'oklch(0.8 0.12 200)',
+ radius: '0.5rem',
+ },
+ }}
+/>;
+```
+
+You can also override tokens from host CSS:
+
+```css
+:root {
+ --font-agent-ui: 'Your Font', ui-sans-serif, system-ui, sans-serif;
+ --primary: oklch(0.55 0.2 275);
+}
+```
+
+> _Screenshot: the same layout rebranded with a custom palette._
+
+See [docs/theming.md](./docs/theming.md) for presets, controlled vs uncontrolled mode, and content classNames.
+
+---
+
+## Brand / logo
+
+**Base layouts** — pass `theme.brand` and the SDK positions name + icon in the default slots:
+
+```tsx
+<TrueforgeUI
+ server={server}
+ layout="sidebar"
+ theme={{
+ brand: {
+ name: 'Acme',
+ icon: { src: '/brand/icon.svg', alt: 'Acme' },
+ logo: { src: '/brand/logo.svg', alt: 'Acme' },
+ },
+ }}
+/>
+```
+
+**Custom layouts** — import `BrandLogo` / `BrandIcon` and place them anywhere (see [Custom layouts](#custom-layouts)).
+
+> _Screenshot: external brand mark rendered in the base layout header._
+
+---
+
+## Agent modes
+
+`agentConfig` controls library chrome, draft composer, and how New Chat / Clear Chat behave.
+
+| Mode | Layout chrome | Agent selection / New Chat |
+| -------------------------------------- | ------------------------------- | --------------------------------------------------------- |
+| `AgentLibraryWithComposer` _(default)_ | Agents Library + draft builder | New Chat opens draft; library picks a named agent |
+| `SingleAgent` | Named-only, plain composer | Locked to `name`; New Chat / Clear Chat = new thread |
+| `AgentLibrary` | Agents Library only (no draft) | Empty until pick; no New Chat; Clear Chat after selection |
+| `AgentComposer` | Draft builder only (no library) | Always draft; New Chat / Clear Chat = fresh draft |
+
+In library modes, picking an agent from the Agents Library switches to a named chat for that agent **and remounts the runtime** so the new agent starts from a clean conversation. Draft chats can be promoted via **Save as agent** (`server.saveAgent` on the resolved `AgentUIServer`). **Clear Chat** (thread header) resets the current named or draft session.
+
+```tsx
+{
+ /* Library + draft (default) */
+}
+<TrueforgeUI server={server} layout="sidebar" />;
+
+{
+ /* Named-only lock */
+}
+<TrueforgeUI server={server} layout="sidebar" agentConfig={{ mode: 'SingleAgent', name: 'support-agent' }} />;
+
+{
+ /* Library only — select an agent to start */
+}
+<TrueforgeUI server={server} layout="sidebar" agentConfig={{ mode: 'AgentLibrary' }} />;
+
+{
+ /* Composer only */
+}
+<TrueforgeUI
+ server={server}
+ layout="sidebar"
+ agentConfig={{
+ mode: 'AgentComposer',
+ defaultAgentSpec: { model: { name: 'openai-main/gpt-4.1' } },
+ }}
+/>;
+```
+
+> _Screenshot: Agents Library open; selecting an agent resets the thread._
+
+---
+
+## Layouts
+
+Built-in `layout` values:
+
+| Value | Description |
+| --------- | -------------------------------------------------------- |
+| `sidebar` | Left session list + main thread (ChatGPT / Claude style) |
+| `drawer` | Full-bleed thread; sessions open in a slide-over |
+| `dock` | Fixed-width right panel; list XOR thread stack |
+| `widget` | Same stack as `dock`, opened from a bottom-right FAB |
+
+The [example app](./example/) switches between these four modes.
+
+---
+
+## Custom layouts
+
+For full control, pass a React component as `layout`. The SDK still wires server, shell mode, slots, and runtime behind it.
+
+```tsx
+import { Thread, ThreadListContainer, BrandIcon, useTheme } from '@truefoundry/trueforge-ui';
+
+function Layout({ className }: { className?: string }) {
+ const { mode, setTheme } = useTheme();
+
+ return (
+ <div className={className} style={{ display: 'flex', height: '100%' }}>
+ <aside style={{ width: 256 }}>
+ <BrandIcon className="size-6" />
+ <ThreadListContainer />
+ </aside>
+ <main style={{ flex: 1, minWidth: 0 }}>
+ <button type="button" onClick={() => setTheme(mode === 'dark' ? 'light' : 'dark')}>
+ Theme
+ </button>
+ <Thread />
+ </main>
+ </div>
+ );
+}
+
+<TrueforgeUI server={server} layout={Layout} />;
+```
+
+For deeper composition without `TrueforgeUI`, nest `SlotsProvider` outside `TrueFoundryChatProvider` — see [docs/customization.md](./docs/customization.md).
+
+> _Screenshot: a custom layout assembled from_ `BrandIcon`_,_ `ThreadListContainer`_, and_ `Thread`_._
+
+---
+
+## Overriding components
+
+Every curated feature atom is overridable. Provide an `overrides` map to swap any single component while inheriting the rest.
+
+```tsx
+import { TrueforgeUI, type AssistantMessageBubbleProps } from '@truefoundry/trueforge-ui';
+
+function MyBubble(props: AssistantMessageBubbleProps) {
+ return <div className="mr-auto max-w-[75%] rounded-2xl bg-muted px-4 py-2">{props.children}</div>;
+}
+
+<TrueforgeUI
+ server={server}
+ layout="sidebar"
+ overrides={{
+ AssistantMessageBubble: MyBubble,
+ // WelcomeScreen, ComposerShell, ToolCallCard, … all overridable
+ }}
+/>;
+```
+
+Overridable slots include composer pieces (`ComposerShell`, `ComposerLeftSection`, `ComposerRightSection`, `ComposerSendButton`), messages (`AssistantMessageBubble`, `UserMessageBubble`, `UserMessageEdit`), `Markdown`, `WelcomeScreen`, thread-list atoms, and tool/prompt cards (`ToolCallCard`, `ToolApprovalBar`, `ToolGroupCard`, `SubAgentCard`, `SandboxToolCallCard`, `AgentStepsCard`, `ReasoningCard`, `AskUserPrompt`, `McpAuthPrompt`, and more).
+
+See [docs/customization.md](./docs/customization.md) for the full slot list.
+
+---
+
+## Server
+
+`<TrueforgeUI />` takes a **`TrueforgeServerConfig`**: built-in backends init
+inside the component, or pass a ready `AgentUIServer` directly.
+
+```ts
+type TrueforgeServerConfig =
+ | {
+ type: 'truefoundry';
+ apiKey: string;
+ controlPlaneURL: string;
+ gatewayPlaneURL?: string;
+ }
+ | { type: 'trueforge'; apiKey: string /* + open extras later */ }
+ | AgentUIServer;
+
+type AgentUIServer = AgentChatServer & AgentBuilderServer & { catalog?: CatalogServer };
+```
+
+| Port | Responsibility |
+| -------------------- | ------------------------------------------------------------------- |
+| `AgentChatServer` | Sessions, turns, streaming, draft `AgentSpec` sync |
+| `AgentBuilderServer` | `getModels` / `getSkills` / `getMcp` / `searchAgents` / `saveAgent` |
+
+**Zero-config TrueFoundry** — see [Getting started](#getting-started). The SDK calls `createTrueFoundryAgentUIServer` for you.
+
+**Compose your own `AgentUIServer` (custom):**
+
+```tsx
+import { TrueforgeUI, createTrueFoundryServer } from '@truefoundry/trueforge-ui';
+import { createTrueFoundryChatServer } from '@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter';
+
+const chatServer = createTrueFoundryChatServer({ apiKey, baseUrl });
+const agentServer = createTrueFoundryServer({
+ chatServer,
+ getModels,
+ getSkills,
+ getMcp,
+ searchAgents,
+ saveAgent,
+});
+
+<TrueforgeUI server={agentServer} layout="sidebar" />;
+```
+
+**Implement `AgentUIServer` yourself:**
+
+```tsx
+import { TrueforgeUI, type AgentUIServer } from '@truefoundry/trueforge-ui';
+
+const agentServer: AgentUIServer = {
+ // AgentChatServer methods…
+ createSession,
+ listSessions,
+ getSession,
+ updateSession,
+ createTurn,
+ // …
+ // AgentBuilderServer methods…
+ getModels: async () => [],
+ getSkills: async () => [],
+ getMcp: async () => [],
+ searchAgents: async () => [],
+ saveAgent: async ({ agentName, agentSpec }) => ({ ok: true }),
+};
+
+<TrueforgeUI server={agentServer} layout="sidebar" />;
+```
+
+See [docs/server.md](./docs/server.md) for the full method list and BYO guidance.
+
+---
+
+## Exports
+
+| Export | Kind | Purpose |
+| ------------------------------------------------------------ | ---------- | ------------------------------------------------------------ |
+| `TrueforgeUI` | Component | Root component — accepts all props above |
+| `TrueforgeServerConfig` | Type | `server` prop: `truefoundry` / `trueforge` / `AgentUIServer` |
+| `createTrueFoundryServer` | Function | Compose chat + builder into `AgentUIServer` |
+| `Thread`, `ThreadListContainer`, `BrandLogo`, `BrandIcon` | Components | Layout primitives for custom layouts |
+| Composer / message / tool atoms | Components | Overridable, themeable building blocks |
+| `SlotsProvider`, `useSlot`, `useTheme` | API | Overrides + theme mode |
+| `AgentUIServer`, `AgentChatServer`, `AgentBuilderServer` | Types | Resolved server contract |
+| `ThemeConfig`, `LayoutProp`, `SlotOverrides`, `AgentSpec`, … | Types | Configuration contracts |
+| `@truefoundry/trueforge-ui/styles.css` | CSS | Tokens, utilities, OpenUI |
+| `@truefoundry/trueforge-ui/assistant-ui` | Entry | Shared `useAui` / `useAuiState` (single instance) |
+
+Curated public API: [docs/api.md](./docs/api.md).
+
+---
+
+## Docs
+
+| Doc | Topic |
+| ------------------------------------------------ | ----------------------------- |
+| [docs/api.md](./docs/api.md) | Curated public API |
+| [docs/architecture.md](./docs/architecture.md) | Atoms, containers, slots |
+| [docs/customization.md](./docs/customization.md) | Theme, slots, custom layout |
+| [docs/compatibility.md](./docs/compatibility.md) | Peer matrix |
+| [docs/server.md](./docs/server.md) | Server port + BYO |
+| [docs/theming.md](./docs/theming.md) | Themes, brand, icons, presets |
+| [CHANGELOG.md](./CHANGELOG.md) | Migration notes |
+
+### Troubleshooting: "requires an AuiProvider"
+
+Usually duplicate `@assistant-ui/core` / `@assistant-ui/store` instances. Diagnose with `pnpm why`, align `react` across the workspace, and import chrome hooks from `@truefoundry/trueforge-ui` (or `/assistant-ui`) so you share the SDK’s copy.
+
+### Development
+
+From the monorepo root:
+
+```bash
+pnpm install
+pnpm --filter @truefoundry/trueforge-ui typecheck
+pnpm --filter @truefoundry/trueforge-ui test
+pnpm --filter @truefoundry/trueforge-ui build
+```
+
+Local demo: see [example/](./example/). Publishing: see [RELEASING.md](../../RELEASING.md#releasing-truefoundrytrueforge-ui).
+
+---
+
+## License
+
+Apache-2.0. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
+
+Security: [SECURITY.md](./SECURITY.md) · Conduct: [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) · Changes: [CHANGELOG.md](./CHANGELOG.md)
diff --git a/packages/trueforge-ui-sdk/SECURITY.md b/packages/trueforge-ui-sdk/SECURITY.md
new file mode 100644
index 000000000..7a0ecf18a
--- /dev/null
+++ b/packages/trueforge-ui-sdk/SECURITY.md
@@ -0,0 +1,17 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are applied to the latest published `0.x` release on npm.
+
+## Reporting a vulnerability
+
+Please report security issues privately to **[email protected]** (or your TrueFoundry security contact).
+
+Include:
+
+- Description of the issue and impact
+- Steps to reproduce or a proof of concept
+- Affected package version(s)
+
+We will acknowledge receipt and work with you on a fix and disclosure timeline. Please do not open a public GitHub issue for vulnerabilities.
diff --git a/packages/trueforge-ui-sdk/docs/api.md b/packages/trueforge-ui-sdk/docs/api.md
new file mode 100644
index 000000000..83c2cc452
--- /dev/null
+++ b/packages/trueforge-ui-sdk/docs/api.md
@@ -0,0 +1,53 @@
+# Public API
+
+Curated exports from `@truefoundry/trueforge-ui`. Design-system **component
+values** (`Button`, `Modal`, …) live on `tfy-web-components` — this package
+re-exports override **types** only where needed.
+
+## Quick start
+
+| Export | Notes |
+| -------------------------------- | --------------------------------- |
+| `TrueforgeUI` | Slots + runtime + built-in layout |
+| `TrueforgeUIProps`, `ChatLayout` | Props / layout union |
+
+## Compose
+
+| Export | Notes |
+| -------------------------------------------------------------------- | ------------------------------- |
+| `TrueFoundryChatProvider` | Named-agent runtime + toasts |
+| `TrueFoundryChatProviderProps` | `client` XOR `apiKey`+`baseUrl` |
+| `Thread` | Full thread + composer |
+| `ThreadContainer`, `ComposerContainer`, `ThreadListContainer` | Building blocks |
+| `ErrorToasterProvider`, `useErrorToaster`, `useErrorToasterOptional` | Error toasts |
+| Other `*Container` exports | Advanced message / tool wiring |
+
+## Slots / theme
+
+| Export | Notes |
+| -------------------------------------------------------------------- | --------------------------- |
+| `SlotsProvider`, `useSlot`, `defaultSlots` | Override registry |
+| `SlotOverrides`, `AtomSlots`, `ThemeMode` | Types |
+| `useTheme`, `useThemeMode` | Theme mode |
+| Feature atoms (`WelcomeScreen`, `ComposerShell`, bubbles, toasts, …) | Defaults + override targets |
+
+## Chrome / runtime
+
+| Export | Notes |
+| ------------------------------------------------------------------------------------- | --------------------------------------------- |
+| `useAui`, `useAuiState`, `AssistantState` | Also `@truefoundry/trueforge-ui/assistant-ui` |
+| `AgentSessionClient` | Gateway client |
+| `useTrueFoundryAgentRuntime`, `trueFoundryAttachmentAdapter`, other `useTrueFoundry*` | Runtime hooks |
+
+## Types for overrides
+
+| Export | Notes |
+| ---------------------------------------------- | ------------------------ |
+| `ButtonProps`, `ButtonSize`, `IconButtonProps` | Slot override contracts |
+| Atom `*Props` types | Per-atom override shapes |
+
+## Styles
+
+| Export path | Notes |
+| -------------------------------------- | --------------------------- |
+| `@truefoundry/trueforge-ui/styles.css` | Tokens + utilities + OpenUI |
diff --git a/packages/trueforge-ui-sdk/docs/architecture.md b/packages/trueforge-ui-sdk/docs/architecture.md
new file mode 100644
index 000000000..2b6d97b29
--- /dev/null
+++ b/packages/trueforge-ui-sdk/docs/architecture.md
@@ -0,0 +1,47 @@
+# Architecture
+
+This package splits UI into **atoms** (presentation) and **containers** (runtime wiring), with a **curated slot registry** for overrides.
+
+## Atoms (`src/atoms/**`)
+
+Presentational components. An atom:
+
+- Does **not** import `@assistant-ui/*` or TrueFoundry runtime hooks.
+- Receives data and callbacks as props.
+- Owns Tailwind classes / markup for what it renders.
+- Curated atoms register on `AtomSlots` via `declare module` augmentation;
+ chrome / primitives are direct imports (not slots).
+
+Defaults are registered in [`src/theme/defaultSlots.ts`](../src/theme/defaultSlots.ts).
+
+## Containers (`src/containers/**`)
+
+Stateful glue. A container:
+
+- Reads assistant-ui / TrueFoundry runtime hooks and primitives.
+- Derives plain props and callbacks.
+- Resolves curated atoms with `useSlot("Name")`; other atoms are imported
+ directly.
+- Avoids decorative styling beyond layout glue.
+
+## Slots (`SlotsProvider`)
+
+```tsx
+<SlotsProvider overrides={{ WelcomeScreen: MyWelcome }}>
+ <Thread />
+</SlotsProvider>
+```
+
+Nested providers fall through to parent overrides, then `defaultSlots`.
+Quick start: `TrueforgeUI` mounts `SlotsProvider` outside the chat
+provider. See [customization.md](./customization.md) for the keep-list.
+
+## Theming
+
+Default atoms use CSS variables from `styles.css`. Override colours in host
+`:root` / `.dark` after importing the SDK stylesheet, or via `theme.tokens`.
+
+## Errors
+
+`ErrorToasterProvider` shows a single toast (no queue). Descriptions from
+gateway errors are truncated for display.
diff --git a/packages/trueforge-ui-sdk/docs/compatibility.md b/packages/trueforge-ui-sdk/docs/compatibility.md
new file mode 100644
index 000000000..11685d13a
--- /dev/null
+++ b/packages/trueforge-ui-sdk/docs/compatibility.md
@@ -0,0 +1,52 @@
+# Compatibility
+
+Peer and dependency ranges for `@truefoundry/trueforge-ui` (see
+`package.json` for authoritative versions).
+
+**Status:** this package is `0.x` (APIs may change). It currently depends on
+`truefoundry-gateway-sdk@^0.4.0-rc.6` — pin with a lockfile for reproducible
+installs until a stable gateway release is adopted.
+
+## Required peers
+
+| Package | Range |
+| --------------------- | -------------- |
+| `react` / `react-dom` | `^18 \|\| ^19` |
+
+Install once at the app root.
+
+## Bundled dependencies (installed with the SDK)
+
+| Package | Range |
+| ----------------------------------- | ------------- |
+| `@assistant-ui/core` | `^0.2.22` |
+| `@assistant-ui/react` | `^0.14.24` |
+| `@truefoundry/assistant-ui-runtime` | `^0.1.9` |
+| `truefoundry-gateway-sdk` | `^0.4.0-rc.6` |
+| `lucide-react` | `^0.562.0` |
+
+`@assistant-ui/*` are also listed as **optional** peers so hosts that install
+them directly for customization stay on a compatible range.
+
+Runtime + gateway are wired by `TrueFoundryChatProvider` and re-exported for
+advanced use. `lucide-react` supplies default UI icons via `IconRegistry`;
+hosts may override via `theme.icons` or register custom SVGR components.
+
+## Optional direct install (customization)
+
+Chrome hooks (`useAui`, `useAuiState`, `useTheme`) are re-exported from
+`@truefoundry/trueforge-ui` — prefer those so the host shares the SDK instance.
+
+When importing deep `@assistant-ui/react` primitives, `@assistant-ui/core`, or
+`tfy-web-components` from host code, also add them as direct dependencies at
+versions within the ranges above so resolution is app-rooted. Force a
+singleton (Vite `dedupe`, Yarn `resolutions`, npm `overrides`) so the SDK and
+host share one copy — see README Troubleshooting.
+
+## Singletons
+
+These must resolve to one physical copy in the dependency graph:
+
+- `react` / `react-dom`
+- `@assistant-ui/core` / `@assistant-ui/react` / `@assistant-ui/store`
+- `tfy-web-components` (for shared theme context)
diff --git a/packages/trueforge-ui-sdk/docs/createTrueFoundryServer.temp.ts b/packages/trueforge-ui-sdk/docs/createTrueFoundryServer.temp.ts
new file mode 100644
index 000000000..258c61e13
--- /dev/null
+++ b/packages/trueforge-ui-sdk/docs/createTrueFoundryServer.temp.ts
@@ -0,0 +1,293 @@
+/**
+ * TEMP: Gateway-backed `AgentUIServer` for `docs/server-types.temp.ts`.
+ *
+ * Not wired into the package. Sketch of how `createTrueFoundryServer` would look
+ * once the unified session port is promoted.
+ *
+ * Pattern:
+ * - Host-facing API = unified (createSession / listSessions / updateSession + isMutable)
+ * - Gateway still has named + draft clients — adapter fans out internally
+ */
+
+import type { Page } from 'truefoundry-gateway-sdk';
+import type { AgentSession as GwAgentSession } from 'truefoundry-gateway-sdk/agents';
+import { AgentSessionClient } from 'truefoundry-gateway-sdk/agents';
+import type { AgentDraftSession as GwAgentDraftSession } from 'truefoundry-gateway-sdk/agents/private';
+import { PrivateAgentSessionClient } from 'truefoundry-gateway-sdk/agents/private';
+
+import type {
+ AgentLibraryEntry,
+ AgentSession,
+ AgentSkill,
+ AgentSpec,
+ AgentUIServer,
+ ConnectorState,
+ CreateSessionRequest,
+ ListSessionsParams,
+ ListSessionsResponse,
+ ModelEntry,
+ PageResult,
+ SearchAgentsParams,
+ Session,
+ UpdateSessionRequest,
+} from './server-types.temp.js';
+
+type GwSession = GwAgentSession | GwAgentDraftSession;
+
+export type CreateTrueFoundryServerOptions<
+ TModel extends ModelEntry = ModelEntry,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSpec extends AgentSpec = AgentSpec,
+ TSave = unknown,
+> = {
+ apiKey: string;
+ baseUrl: string;
+ getModels: () => Promise<TModel[]>;
+ getSkills: () => Promise<TSkill[]>;
+ getMcp: () => Promise<TMcp[]>;
+ searchAgents: (req?: SearchAgentsParams) => Promise<TAgent[]>;
+ saveAgent: (req: { agentName: string; agentSpec: TSpec; sessionId?: string }) => Promise<TSave>;
+ deleteAgent?: (req: { agentName: string }) => Promise<void>;
+ deleteSession?: (req: { sessionId: string }) => Promise<void>;
+};
+
+/** TFY adapter: unified port + gateway clients escape hatch. */
+export type TrueFoundryServer<
+ TModel extends ModelEntry = ModelEntry,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSpec extends AgentSpec = AgentSpec,
+ TSave = unknown,
+> = AgentUIServer<
+ Session,
+ CreateSessionRequest & { tfyMetadata?: string },
+ ListSessionsParams,
+ UpdateSessionRequest,
+ import('./server-types.temp.js').Turn,
+ import('./server-types.temp.js').SessionEventItem,
+ TSpec,
+ import('./server-types.temp.js').TurnStreamingEvent,
+ TModel,
+ TSkill,
+ TMcp,
+ TAgent,
+ TSave
+> & {
+ getGatewayClients(): {
+ client: AgentSessionClient;
+ privateClient: PrivateAgentSessionClient;
+ };
+};
+
+function isDraft(session: GwSession): session is GwAgentDraftSession {
+ return session.type === 'session/draft';
+}
+
+/** Map gateway named/draft session → unified UI session (+ methods). */
+function wrapSession(raw: GwSession): AgentSession {
+ const mutable = isDraft(raw);
+ return {
+ id: raw.id,
+ title: raw.title,
+ agentName: raw.agentName,
+ agentSpec: mutable ? raw.agentSpec : undefined,
+ isMutable: mutable,
+ createdBySubject: raw.createdBySubject,
+ createdAt: raw.createdAt,
+ updatedAt: raw.updatedAt,
+ prepareTurn: opts => raw.prepareTurn(opts),
+ listTurns: opts => raw.listTurns(opts) as unknown as ReturnType<AgentSession['listTurns']>,
+ getTurn: req => raw.getTurn(req),
+ cancel: () => raw.cancel(),
+ listEvents: opts => raw.listEvents(opts) as unknown as ReturnType<AgentSession['listEvents']>,
+ update: mutable ? req => raw.update(req) : undefined,
+ };
+}
+
+function mapPage<TIn, TOut, R>(page: Page<TIn, R>, map: (item: TIn) => TOut): PageResult<TOut, R> {
+ return {
+ data: page.data.map(map),
+ response: page.response,
+ hasNextPage: () => page.hasNextPage(),
+ getNextPage: async () => mapPage(await page.getNextPage(), map),
+ };
+}
+
+async function resolveRaw(
+ client: AgentSessionClient,
+ privateClient: PrivateAgentSessionClient,
+ sessionId: string,
+): Promise<GwSession> {
+ try {
+ return await client.getSession({ sessionId });
+ } catch {
+ return privateClient.getDraftSession({ draftSessionId: sessionId });
+ }
+}
+
+/**
+ * Composes gateway chat clients with host-provided builder catalog callbacks.
+ * Draft vs named is an internal fan-out; the host only sees unified sessions.
+ */
+export function createTrueFoundryServer<
+ TModel extends ModelEntry = ModelEntry,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSpec extends AgentSpec = AgentSpec,
+ TSave = unknown,
+>(
+ opts: CreateTrueFoundryServerOptions<TModel, TSkill, TMcp, TAgent, TSpec, TSave>,
+): TrueFoundryServer<TModel, TSkill, TMcp, TAgent, TSpec, TSave> {
+ const gatewayOpts = { apiKey: opts.apiKey, baseUrl: opts.baseUrl };
+ const client = new AgentSessionClient(gatewayOpts);
+ const privateClient = new PrivateAgentSessionClient(gatewayOpts);
+
+ type CreateReq = CreateSessionRequest & { tfyMetadata?: string };
+
+ const server = {
+ // --- unified chat ---
+ async createSession(req: CreateReq) {
+ if (req.agentSpec) {
+ const draft = await privateClient.createDraftSession({
+ agentSpec: req.agentSpec,
+ agentName: req.agentName,
+ tfyMetadata: req.tfyMetadata,
+ });
+ return wrapSession(draft);
+ }
+ if (req.agentName) {
+ const named = await client.createSession({
+ agentName: req.agentName,
+ tfyMetadata: req.tfyMetadata,
+ });
+ return wrapSession(named);
+ }
+ throw new Error('createSession requires agentName and/or agentSpec');
+ },
+
+ async listSessions(req?: ListSessionsParams) {
+ const page = await privateClient.listOwnedSessions(req);
+ return mapPage(page, wrapSession) as PageResult<AgentSession, ListSessionsResponse>;
+ },
+
+ async getSession(req: { sessionId: string }) {
+ return wrapSession(await resolveRaw(client, privateClient, req.sessionId));
+ },
+
+ async updateSession(req: UpdateSessionRequest) {
+ const raw = await resolveRaw(client, privateClient, req.sessionId);
+ if (!isDraft(raw)) {
+ throw new Error('updateSession: session is not mutable (isMutable=false)');
+ }
+ await raw.update({ agentSpec: req.agentSpec });
+ // title is not on gateway draft update today — host/BFF if needed
+ return wrapSession(raw);
+ },
+
+ createTurn: ((req: {
+ sessionId: string;
+ input?: Parameters<AgentSession['prepareTurn']>[0] extends infer O
+ ? O extends { input?: infer I }
+ ? I
+ : never
+ : never;
+ previousTurnId?: string | 'auto';
+ stream?: boolean;
+ pollIntervalMs?: number;
+ }) => {
+ if (req.stream === false) {
+ return (async () => {
+ const session = await resolveRaw(client, privateClient, req.sessionId);
+ return session
+ .prepareTurn({
+ input: req.input,
+ previousTurnId: req.previousTurnId,
+ })
+ .execute({ stream: false, pollIntervalMs: req.pollIntervalMs });
+ })();
+ }
+ return (async function* () {
+ const session = await resolveRaw(client, privateClient, req.sessionId);
+ yield* session
+ .prepareTurn({
+ input: req.input,
+ previousTurnId: req.previousTurnId,
+ })
+ .execute({ stream: true });
+ })();
+ }) as TrueFoundryServer['createTurn'],
+
+ async cancelSession({ sessionId }: { sessionId: string }) {
+ await (await resolveRaw(client, privateClient, sessionId)).cancel();
+ },
+
+ async deleteSession({ sessionId }: { sessionId: string }) {
+ if (!opts.deleteSession) {
+ throw new Error('deleteSession is not on the gateway SDK. Pass deleteSession to createTrueFoundryServer.');
+ }
+ await opts.deleteSession({ sessionId });
+ },
+
+ async listTurns({ sessionId, ...page }: { sessionId: string; limit?: number; pageToken?: string }) {
+ const raw = await resolveRaw(client, privateClient, sessionId);
+ return raw.listTurns(page) as unknown as ReturnType<TrueFoundryServer['listTurns']>;
+ },
+
+ async getTurn({ sessionId, turnId }: { sessionId: string; turnId: string }) {
+ return (await resolveRaw(client, privateClient, sessionId)).getTurn({
+ turnId,
+ });
+ },
+
+ async listEvents({
+ sessionId,
+ ...page
+ }: {
+ sessionId: string;
+ pageToken?: string;
+ lastTurnId?: string;
+ limit?: number;
+ }) {
+ const raw = await resolveRaw(client, privateClient, sessionId);
+ return raw.listEvents(page) as unknown as ReturnType<TrueFoundryServer['listEvents']>;
+ },
+
+ async *subscribeToTurn({
+ sessionId,
+ turnId,
+ afterSequenceNumber,
+ }: {
+ sessionId: string;
+ turnId: string;
+ afterSequenceNumber?: number;
+ }) {
+ const raw = await resolveRaw(client, privateClient, sessionId);
+ const turn = await raw.getTurn({ turnId });
+ yield* turn.stream({ afterSequenceNumber });
+ },
+
+ downloadSandboxFile: (sandboxId: string, req: { path: string }) =>
+ privateClient.downloadSandboxFile(sandboxId, req),
+
+ // --- builder (host-owned) ---
+ getModels: opts.getModels,
+ getSkills: opts.getSkills,
+ getMcp: opts.getMcp,
+ searchAgents: opts.searchAgents,
+ saveAgent: opts.saveAgent,
+ async deleteAgent(req: { agentName: string }) {
+ if (!opts.deleteAgent) {
+ throw new Error('deleteAgent is host-owned. Pass deleteAgent to createTrueFoundryServer.');
+ }
+ await opts.deleteAgent(req);
+ },
+
+ getGatewayClients: () => ({ client, privateClient }),
+ };
+
+ return server as TrueFoundryServer<TModel, TSkill, TMcp, TAgent, TSpec, TSave>;
+}
diff --git a/packages/trueforge-ui-sdk/docs/customization.md b/packages/trueforge-ui-sdk/docs/customization.md
new file mode 100644
index 000000000..400e99389
--- /dev/null
+++ b/packages/trueforge-ui-sdk/docs/customization.md
@@ -0,0 +1,107 @@
+# Customizing the UI
+
+Every curated feature atom is resolved through `useSlot`. Override via
+`SlotsProvider`; nested providers fall through to parents / defaults.
+Primitives (`Button`, `IconButton`, `Dialog`, …) are direct imports — not
+slots — so style them via theme tokens / CSS, or fork the host layout.
+
+```tsx
+import { SlotsProvider, Thread } from '@truefoundry/trueforge-ui';
+
+function MyWelcome({ heading }: { heading?: string }) {
+ return <p className="px-4 py-6 text-center text-lg">{heading ?? 'What are we building today?'}</p>;
+}
+
+<SlotsProvider overrides={{ WelcomeScreen: MyWelcome }}>
+ <Thread />
+</SlotsProvider>;
+```
+
+## Theme object
+
+Prefer `theme={{ preset, mode, tokens, brand, icons, className, classNames }}`
+over hacking third-party CSS:
+
+```tsx
+<TrueforgeUI
+ layout="sidebar"
+ theme={{
+ preset: 'claude',
+ mode: 'dark',
+ tokens: { primary: '#e11d48' },
+ brand: { name: 'Acme', icon: MyMark },
+ icons: { send: MySendSvg },
+ classNames: {
+ markdown: 'prose max-w-none',
+ syntaxHighlighter: { root: 'rounded-lg' },
+ openui: { root: 'my-openui' },
+ monaco: { root: 'h-64', monacoTheme: 'vs-dark' },
+ },
+ }}
+/>
+```
+
+Presets: `truefoundry` (default), `claude`, `chatgpt`, `gemini` — stylistic
+homages, not product replicas. Host CSS still works on `.aui-root` /
+`.aui-markdown` / `.aui-syntax-highlighter` / `.aui-openui` / `.aui-monaco`.
+
+## Slot coverage
+
+Public override surface (primitives stay theme/CSS — not slots):
+
+- **Layout / composer:** `Accordion`, `AccordionSummary`, `AccordionDetails`,
+ `ComposerShell`, `ComposerLeftSection`, `ComposerRightSection`,
+ `ComposerSendButton`, `ThreadRootShell`, `ThreadViewportShell`,
+ `ThreadComposerAreaShell`, `MessageGroup`, `ScrollToBottomButton`,
+ `MessageListSkeleton`, `WelcomeScreen`
+- **Messages / content:** `AssistantMessageBubble`, `UserMessageBubble`,
+ `UserMessageEdit`, `UserMessageActionBar`, `MessageActionBar`,
+ `MessageErrorBanner`, `MessageIndicator`, `MessageTimestamp`, `Markdown`,
+ `OpenUiFenceBlock`, `SandboxArtifactDownload`
+- **Thread list:** `ThreadListShell`, `ThreadListNewButton`, `ThreadListRow`,
+ `ThreadListRowSkeleton`, `ThreadListEmptyState`, `HistoryLoader`
+- **Attachments / toasts:** `AttachmentCard`, `AttachmentPreviewDialog`,
+ `AttachmentPickerButton`, `Toast`, `ToastStack`
+- **Tools / prompts:** `ToolCallCard`, `ToolCallContentBlock`,
+ `ToolApprovalBar`, `ToolGroupCard`, `SubAgentCard`, `SandboxToolCallCard`,
+ `AgentStepsCard`, `ReasoningCard`, `AskUserPrompt`, `McpAuthPrompt`
+
+## Custom layout
+
+Pass a React component as `layout` to own chrome; compose exported
+`Thread` / `ThreadListContainer` / brand helpers:
+
+```tsx
+function CenteredLayout({ className }: { className?: string }) {
+ return (
+ <div className={`mx-auto flex h-full max-w-3xl flex-col ${className ?? ""}`}>
+ <ThreadListContainer />
+ <Thread />
+ </div>
+ );
+}
+
+<TrueforgeUI layout={CenteredLayout} server={server} agentMode={…} />;
+```
+
+## Restyle bubbles
+
+```tsx
+import { SlotsProvider, Thread, type AssistantMessageBubbleProps } from '@truefoundry/trueforge-ui';
+
+function AssistantBubbleV2({ children, error, actionBar }: AssistantMessageBubbleProps) {
+ return (
+ <div className="mr-auto max-w-[75%] rounded-2xl bg-neutral-100 px-4 py-2">
+ {children}
+ {error}
+ {actionBar}
+ </div>
+ );
+}
+
+<SlotsProvider overrides={{ AssistantMessageBubble: AssistantBubbleV2 }}>
+ <Thread />
+</SlotsProvider>;
+```
+
+See [theming.md](./theming.md) for the full hard-cut design and migration notes.
diff --git a/packages/trueforge-ui-sdk/docs/server-types.temp.md b/packages/trueforge-ui-sdk/docs/server-types.temp.md
new file mode 100644
index 000000000..848f831a9
--- /dev/null
+++ b/packages/trueforge-ui-sdk/docs/server-types.temp.md
@@ -0,0 +1,542 @@
+# TEMP: Self-contained server types (copied, no imports)
+
+> **Draft only.** Not wired into the package.
+> Types below are **pasted** from `truefoundry-gateway-sdk` / runtime shapes so you can read the contract without imports.
+> Live code still re-exports from gateway (`src/server/types.ts`) until you decide to promote.
+
+Source pin (approx): `[email protected]`
+
+---
+
+## Catalog (SDK-owned — already local)
+
+```ts
+export interface ModelEntry {
+ name: string;
+ provider: string;
+ apiModel: string;
+ modelId: string;
+}
+
+export interface AgentSkill {
+ id: string;
+ name: string;
+ fqn?: string;
+ description?: string;
+}
+
+export interface ConnectorState {
+ id: string;
+ name: string;
+ description?: string;
+}
+
+export interface AgentLibraryEntry {
+ name: string;
+ description?: string;
+ model?: string;
+ skillsCount?: number;
+ mcpCount?: number;
+ author?: string;
+ updatedAt?: string;
+}
+
+export type SearchAgentsParams = {
+ query?: string;
+ limit?: number;
+ offset?: number;
+};
+
+export type DraftAgentSpecPatch = {
+ model: {
+ name: string;
+ params?: { maxTokens?: number; reasoningEffort?: string };
+ };
+ skills: { fqn: string; preload: false }[];
+ mcpServers: {
+ type: 'truefoundry-mcp-registry';
+ name: string;
+ enableTools: ['@all'];
+ }[];
+};
+```
+
+---
+
+## Gateway / runtime shapes (copied)
+
+### Subject
+
+```ts
+export interface Subject {
+ subjectId: string;
+ subjectType: string;
+ subjectSlug: string;
+}
+```
+
+### Pagination
+
+```ts
+export interface TokenPagination {
+ nextPageToken?: string;
+ previousPageToken?: string;
+ limit: number;
+}
+
+/** Structural page shape hosts must satisfy (gateway `Page` is a class). */
+export interface PageResult<T, R = unknown> {
+ data: T[];
+ response: R;
+ hasNextPage(): boolean;
+ getNextPage(): Promise<PageResult<T, R>>;
+}
+
+export type ListSessionsOrder = 'asc' | 'desc';
+
+export type PageParams = {
+ limit?: number;
+ order?: ListSessionsOrder;
+ pageToken?: string;
+ startTimestamp?: string;
+ endTimestamp?: string;
+};
+
+export type PreviousTurnIdInput = 'auto' | string;
+```
+
+### AgentSpec (+ nested)
+
+```ts
+export interface ModelParamsCacheControl {
+ type: string;
+}
+
+export interface ModelParams {
+ maxTokens?: number;
+ temperature?: number;
+ topP?: number;
+ topK?: number;
+ parallelToolCalls?: boolean;
+ reasoningEffort?: string;
+ cacheControl?: ModelParamsCacheControl;
+}
+
+export interface Model {
+ name: string;
+ params?: ModelParams;
+}
+
+export interface SkillMount {
+ /** Fully qualified name of the agent skill version. */
+ fqn: string;
+ /** If true, SKILL.md is injected into agent context. */
+ preload?: boolean;
+}
+
+export type ToolsSelectorTag = '@all' | '@read-only';
+export type ToolsSelectorItem = ToolsSelectorTag | string;
+
+export type RequireApprovalToolsSelectorTag = '@all' | '@write' | '@destructive';
+export type RequireApprovalToolSelectorItem = RequireApprovalToolsSelectorTag | string;
+
+export interface BaseMcpServer {
+ name: string;
+ enableTools?: ToolsSelectorItem[];
+ disableTools?: ToolsSelectorItem[];
+ preloadTools?: ToolsSelectorItem[];
+ requireApprovalForTools?: RequireApprovalToolSelectorItem[];
+ preload?: boolean;
+}
+
+export interface RegisteredMcpServer extends BaseMcpServer {
+ type: 'truefoundry-mcp-registry';
+}
+
+export interface InlineMcpServer extends BaseMcpServer {
+ type: 'inline';
+ url: string;
+}
+
+export type McpServer = RegisteredMcpServer | InlineMcpServer;
+
+export interface AgentSpecUserMessage {
+ type: 'user.message';
+ content: string;
+}
+
+export type ResponseFormat =
+ | { type: 'text' }
+ | { type: 'json_object' }
+ | {
+ type: 'json_schema';
+ jsonSchema: {
+ name: string;
+ description?: string;
+ schema?: Record<string, unknown>;
+ strict?: boolean;
+ };
+ };
+
+export interface RuntimeConfig {
+ iterationLimit?: number;
+ sandbox?: {
+ enabled: boolean;
+ fileDownloads?: boolean;
+ networkPolicy?: {
+ authInject?: Array<{
+ type: 'git';
+ match: { hosts: string[] };
+ authData: { type: 'basic'; username: string; password: string };
+ }>;
+ };
+ };
+ dynamicSubAgents?: { enabled?: boolean };
+ contextManagement?: {
+ compaction?: {
+ enabled?: boolean;
+ compactionThresholdTokens?: number;
+ };
+ largeToolResponse?: { enabled?: boolean };
+ };
+ generativeUi?: { enabled?: boolean };
+ askUserQuestions?: { enabled?: boolean };
+}
+
+/** Agent Definition (gateway `TruefoundryGatewayApi.AgentSpec`) */
+export interface AgentSpec {
+ model: Model;
+ instructions?: string;
+ messages?: AgentSpecUserMessage[];
+ mcpServers?: McpServer[];
+ responseFormat?: ResponseFormat;
+ skills?: SkillMount[];
+ config?: RuntimeConfig;
+ variables?: Record<string, string>;
+}
+
+/** Partial patch (from `@truefoundry/assistant-ui-runtime`) */
+export type AgentSpecUpdate = {
+ instructions?: string;
+ model?: Partial<Model> & {
+ params?: Partial<ModelParams>;
+ };
+ mcpServers?: McpServer[];
+ skills?: SkillMount[];
+ messages?: AgentSpecUserMessage[];
+ variables?: Record<string, string>;
+ responseFormat?: ResponseFormat;
+ config?: RuntimeConfig;
+};
+```
+
+### Session / DraftSession
+
+```ts
+export interface Session {
+ type: 'session';
+ id: string;
+ agentName: string;
+ title?: string;
+ createdBySubject: Subject;
+ createdAt: string;
+ updatedAt: string;
+}
+
+export interface DraftSession {
+ type: 'session/draft';
+ id: string;
+ agentSpec: AgentSpec;
+ agentName?: string;
+ title?: string;
+ createdBySubject: Subject;
+ createdAt: string;
+ updatedAt: string;
+}
+```
+
+### Turn input / state
+
+```ts
+export type UserMessageContent =
+ | string
+ | Array<
+ | { type: 'text'; text: string } // TextContent (simplified)
+ | { type: 'file'; /* FileContent — see gateway */ [key: string]: unknown }
+ >;
+
+export interface UserMessage {
+ type: 'user.message';
+ content: UserMessageContent;
+}
+
+export interface ApprovalAllow {
+ status: 'allow';
+}
+
+export interface ApprovalDeny {
+ status: 'deny';
+ reason?: string;
+}
+
+export type ApprovalDecision = ApprovalAllow | ApprovalDeny;
+
+export interface UserToolApprovalEvent {
+ type: 'user.tool_approval';
+ threadId: string;
+ toolCallId: string;
+ approval: ApprovalDecision;
+}
+
+export interface UserToolResponseEvent {
+ type: 'user.tool_response';
+ threadId: string;
+ toolCallId: string;
+ content: string;
+}
+
+export type TurnInputItem = UserMessage | UserToolApprovalEvent | UserToolResponseEvent;
+
+export interface TurnStateRunning {
+ status: 'running';
+}
+
+export interface TurnStateDone {
+ status: 'done';
+ output?: {
+ type: 'model.message';
+ id: string;
+ threadId: string;
+ createdAt: string;
+ content?: unknown;
+ name?: string;
+ refusal?: string;
+ reasoningContent?: string;
+ toolCalls?: unknown[];
+ finishReason?: string;
+ usage?: unknown;
+ };
+ requiredActions: unknown[]; // ActionRequiredEvent[] in gateway
+ completedAt: string;
+}
+
+export type TurnStateCancelledReason =
+ 'server-execution-timeout' | 'client-cancelled' | 'cancelled-for-next-turn' | 'abandoned';
+
+export interface TurnStateCancelled {
+ status: 'cancelled';
+ reason: TurnStateCancelledReason;
+ completedAt: string;
+}
+
+export interface TurnStateError {
+ status: 'error';
+ message: string;
+ completedAt: string;
+}
+
+export type TurnState = TurnStateRunning | TurnStateDone | TurnStateCancelled | TurnStateError;
+
+export interface Turn {
+ id: string;
+ sessionId: string;
+ previousTurnId?: string;
+ input?: TurnInputItem[];
+ state: TurnState;
+ createdBySubject: Subject;
+ createdAt: string;
+}
+```
+
+### Stream / session events
+
+```ts
+/**
+ * Gateway `TurnStreamingEvent` union (names only — full event payloads in gateway):
+ * ModelMessageEvent | ModelMessageDeltaEvent | ToolResponseEvent |
+ * ThreadCreatedEvent | ThreadDoneEvent | McpAuthRequiredEvent | McpInitializeEvent |
+ * SandboxCreatedEvent | ToolApprovalRequiredEvent | ToolResponseRequiredEvent |
+ * TurnCreatedEvent | TurnDoneEvent
+ */
+export type TurnStreamingEvent = { type: string; [key: string]: unknown };
+
+export interface TurnStreamData {
+ /** SSE event id for resume via subscribeToTurn. */
+ sequenceNumber: number;
+ event: TurnStreamingEvent;
+}
+
+/**
+ * Gateway `SessionEvent` union (subset of streaming, without deltas):
+ * TurnCreatedEvent | TurnDoneEvent | ModelMessageEvent | ToolResponseEvent |
+ * ThreadCreatedEvent | ThreadDoneEvent | McpAuthRequiredEvent | McpInitializeEvent |
+ * SandboxCreatedEvent | ToolApprovalRequiredEvent | ToolResponseRequiredEvent
+ */
+export type SessionEvent = { type: string; [key: string]: unknown };
+
+export interface SessionEventItem {
+ turnId: string;
+ event: SessionEvent;
+}
+```
+
+### List responses
+
+```ts
+export interface ListSessionsResponse {
+ data: Session[];
+ pagination: TokenPagination;
+}
+
+export interface ListDraftSessionsResponse {
+ data: DraftSession[];
+ pagination: TokenPagination;
+}
+
+export interface ListOwnedSessionsResponse {
+ data: Array<Session | DraftSession>;
+ pagination: TokenPagination;
+}
+
+export interface ListTurnsResponse {
+ data: Turn[];
+ pagination: TokenPagination;
+}
+
+export interface ListSessionEventsResponse {
+ data: SessionEventItem[];
+ pagination: TokenPagination;
+}
+```
+
+### Behavioral session surfaces (classes → structural paste)
+
+Gateway ships `AgentSession` / `AgentDraftSession` as classes. For a BYO-facing
+copy, treat them as DTO + methods:
+
+```ts
+export interface PreparedTurn {
+ execute(opts: { stream: false; pollIntervalMs?: number }): Promise<TurnState>;
+ execute(opts?: { stream?: true }): AsyncIterable<TurnStreamData>;
+}
+
+export interface AgentSession extends Session {
+ prepareTurn(opts?: { input?: TurnInputItem[]; previousTurnId?: PreviousTurnIdInput }): PreparedTurn;
+ listTurns(opts?: { pageToken?: string; limit?: number }): Promise<PageResult<Turn, ListTurnsResponse>>;
+ getTurn(req: { turnId: string }): Promise<Turn>;
+ cancel(): Promise<void>;
+ listEvents(opts?: {
+ pageToken?: string;
+ lastTurnId?: string;
+ limit?: number;
+ }): Promise<PageResult<SessionEventItem, ListSessionEventsResponse>>;
+}
+
+export interface AgentDraftSession extends DraftSession {
+ update(req?: { agentSpec?: AgentSpec }): Promise<void>;
+ prepareTurn(opts?: { input?: TurnInputItem[]; previousTurnId?: PreviousTurnIdInput }): PreparedTurn;
+ listTurns(opts?: { pageToken?: string; limit?: number }): Promise<PageResult<Turn, ListTurnsResponse>>;
+ getTurn(req: { turnId: string }): Promise<Turn>;
+ cancel(): Promise<void>;
+ listEvents(opts?: {
+ pageToken?: string;
+ lastTurnId?: string;
+ limit?: number;
+ }): Promise<PageResult<SessionEventItem, ListSessionEventsResponse>>;
+}
+```
+
+---
+
+## Server ports (using the copies above)
+
+```ts
+export interface AgentChatServer {
+ createSession(req: { agentName: string; tfyMetadata?: string }): Promise<AgentSession>;
+ // listSessions(
+ // req: { agentName: string } & PageParams,
+ // ): Promise<PageResult<AgentSession, ListSessionsResponse>>;
+ getSession(req: { sessionId: string }): Promise<AgentSession>;
+
+ createDraftSession(req: {
+ agentSpec: AgentSpec;
+ agentName?: string;
+ tfyMetadata?: string;
+ }): Promise<AgentDraftSession>;
+ getDraftSession(req: { draftSessionId: string }): Promise<AgentDraftSession>;
+ // listDraftSessions(
+ // req?: { agentName?: string } & PageParams,
+ // ): Promise<PageResult<AgentDraftSession, ListDraftSessionsResponse>>;
+ listSessions( // for all the sessions listing
+ req?: { agentName?: string } & PageParams, // agentName filter
+ ): Promise<PageResult<AgentSession | AgentDraftSession, ListOwnedSessionsResponse>>;
+ updateDraftSession(req: { draftSessionId: string; agentSpec?: AgentSpec }): Promise<AgentDraftSession>;
+
+ createTurn(req: {
+ sessionId: string;
+ input?: TurnInputItem[];
+ previousTurnId?: PreviousTurnIdInput;
+ stream: false;
+ pollIntervalMs?: number;
+ }): Promise<TurnState>;
+ createTurn(req: {
+ sessionId: string;
+ input?: TurnInputItem[];
+ previousTurnId?: PreviousTurnIdInput;
+ stream?: true;
+ }): AsyncIterable<TurnStreamData>;
+
+ cancelSession(req: { sessionId: string }): Promise<void>;
+ deleteSession?(req: { sessionId: string }): Promise<void>;
+ listTurns(req: {
+ sessionId: string;
+ limit?: number;
+ pageToken?: string;
+ }): Promise<PageResult<Turn, ListTurnsResponse>>;
+ getTurn(req: { sessionId: string; turnId: string }): Promise<Turn>;
+ listEvents(req: {
+ sessionId: string;
+ pageToken?: string;
+ lastTurnId?: string;
+ limit?: number;
+ }): Promise<PageResult<SessionEventItem, ListSessionEventsResponse>>;
+ subscribeToTurn?(req: {
+ sessionId: string;
+ turnId: string;
+ afterSequenceNumber?: number;
+ }): AsyncIterable<TurnStreamData>;
+
+ downloadSandboxFile?(sandboxId: string, req: { path: string }): Promise<unknown>; // BinaryResponse in gateway
+}
+
+export interface AgentBuilderServer<
+ TModel extends ModelEntry = ModelEntry,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSave = unknown,
+> {
+ getModels(): Promise<TModel[]>;
+ getSkills(): Promise<TSkill[]>;
+ getMcp(): Promise<TMcp[]>;
+ searchAgents(req?: SearchAgentsParams): Promise<TAgent[]>;
+ saveAgent(req: { agentName: string; agentSpec: AgentSpec; draftSessionId?: string }): Promise<TSave>;
+ deleteAgent?(req: { agentName: string }): Promise<void>;
+}
+
+export type AgentUIServer<
+ TModel extends ModelEntry = ModelEntry,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSave = unknown,
+> = AgentChatServer & AgentBuilderServer<TModel, TSkill, TMcp, TAgent, TSave>;
+```
+
+---
+
+## Notes / gaps in this paste
+
+- `TurnStreamingEvent` / `SessionEvent` / some `TurnStateDone` leaves are **summarized** (`unknown` / `{ type: string }`) — full event payloads are large gateway unions; expand on demand.
+- `Page` in gateway is a **class**; `PageResult` above is a structural stand-in.
+- Live `src/server/types.ts` still **imports/re-exports** gateway — this file is documentation / promotion draft only.
diff --git a/packages/trueforge-ui-sdk/docs/server-types.temp.ts b/packages/trueforge-ui-sdk/docs/server-types.temp.ts
new file mode 100644
index 000000000..72f3e7a53
--- /dev/null
+++ b/packages/trueforge-ui-sdk/docs/server-types.temp.ts
@@ -0,0 +1,560 @@
+/**
+ * TEMP: Self-contained server types (copied, no imports)
+ *
+ * Draft only. Not wired into the package.
+ *
+ * Intent:
+ * - One session surface (no draft/named method split). Named vs inline-spec is
+ * data on the session (`agentName` / `agentSpec`), not parallel APIs.
+ * - MUI-style constrained generics everywhere hosts implement or extend:
+ * `T extends Base = Base` — SDK declares the minimum; hosts add extras.
+ *
+ * Live code still re-exports from gateway (src/server/types.ts) until you
+ * promote this draft.
+ *
+ * Source pin (approx): [email protected]
+ */
+
+// ---------------------------------------------------------------------------
+// Catalog (SDK-owned — already local)
+// ---------------------------------------------------------------------------
+
+/**
+ * SDK-required model row. Hosts may add fields via `TModel extends ModelEntry`.
+ * Written to `AgentSpec.model.name` (host maps display → api id as needed).
+ *
+ * @example
+ * ```ts
+ * type MyModel = ModelEntry & { apiModel: string; modelId: string };
+ * // → AgentSpec.model.name = model.apiModel
+ * ```
+ */
+export interface ModelEntry {
+ /** Display label in the model picker, e.g. `"Sonnet 5"`. */
+ name: string;
+ /** Provider id for icon / grouping, e.g. `"anthropic"`. */
+ provider: string;
+}
+
+export interface AgentSkill {
+ id: string;
+ name: string;
+ description?: string;
+}
+
+/**
+ * SDK-required MCP connector row. Written to `AgentSpec.mcpServers[].name`.
+ *
+ * @example
+ * ```ts
+ * const mcp: ConnectorState = {
+ * id: "1",
+ * name: "ai-gateway-mcp",
+ * description: "mcp server for ai gateway",
+ * };
+ * // → AgentSpec.mcpServers[].name = mcp.name
+ * ```
+ */
+export interface ConnectorState {
+ /** Stable id for list keys, e.g. `"1"`. */
+ id: string;
+ /** Registry name mounted onto `mcpServers`, e.g. `"ai-gateway-mcp"`. */
+ name: string;
+ /** Optional blurb for the picker, e.g. `"mcp server for ai gateway"`. */
+ description?: string;
+}
+
+export interface AgentLibraryEntry {
+ name: string;
+}
+
+export type SearchAgentsParams = {
+ limit?: number;
+ offset?: number;
+};
+
+export type DraftAgentSpecPatch = {
+ model: {
+ name: string;
+ params?: { maxTokens?: number; reasoningEffort?: string };
+ };
+ skills: { fqn: string; preload: false }[];
+ mcpServers: {
+ type: 'truefoundry-mcp-registry';
+ name: string;
+ enableTools: ['@all'];
+ }[];
+};
+
+// ---------------------------------------------------------------------------
+// Shared primitives
+// ---------------------------------------------------------------------------
+
+export interface TokenPagination {
+ nextPageToken?: string;
+ previousPageToken?: string;
+ limit: number;
+}
+
+/** Structural page shape hosts must satisfy (gateway `Page` is a class). */
+export interface PageResult<T, R = unknown> {
+ data: T[];
+ response: R;
+ hasNextPage(): boolean;
+ getNextPage(): Promise<PageResult<T, R>>;
+}
+
+export type ListSessionsOrder = 'asc' | 'desc';
+
+export type PageParams = {
+ limit?: number;
+ order?: ListSessionsOrder;
+ pageToken?: string;
+ startTimestamp?: string;
+ endTimestamp?: string;
+};
+
+export type PreviousTurnIdInput = 'auto' | string;
+
+// ---------------------------------------------------------------------------
+// AgentSpec (+ nested) — base; hosts extend via TSpec extends AgentSpec
+// ---------------------------------------------------------------------------
+
+export interface ModelParamsCacheControl {
+ type: string;
+}
+
+export interface ModelParams {
+ maxTokens?: number;
+ temperature?: number;
+ topP?: number;
+ topK?: number;
+ parallelToolCalls?: boolean;
+ reasoningEffort?: string;
+ cacheControl?: ModelParamsCacheControl;
+}
+
+export interface Model {
+ name: string;
+ params?: ModelParams;
+}
+
+export interface SkillMount {
+ fqn: string;
+ preload?: boolean;
+}
+
+export type ToolsSelectorTag = '@all' | '@read-only';
+export type ToolsSelectorItem = ToolsSelectorTag | string;
+
+export type RequireApprovalToolsSelectorTag = '@all' | '@write' | '@destructive';
+export type RequireApprovalToolSelectorItem = RequireApprovalToolsSelectorTag | string;
+
+export interface BaseMcpServer {
+ name: string;
+ enableTools?: ToolsSelectorItem[];
+ disableTools?: ToolsSelectorItem[];
+ preloadTools?: ToolsSelectorItem[];
+ requireApprovalForTools?: RequireApprovalToolSelectorItem[];
+ preload?: boolean;
+}
+
+export interface RegisteredMcpServer extends BaseMcpServer {
+ type: 'truefoundry-mcp-registry';
+}
+
+export interface InlineMcpServer extends BaseMcpServer {
+ type: 'inline';
+ url: string;
+}
+
+export type McpServer = RegisteredMcpServer | InlineMcpServer;
+
+export interface AgentSpecUserMessage {
+ type: 'user.message';
+ content: string;
+}
+
+export type ResponseFormat =
+ | { type: 'text' }
+ | { type: 'json_object' }
+ | {
+ type: 'json_schema';
+ jsonSchema: {
+ name: string;
+ description?: string;
+ schema?: Record<string, unknown>;
+ strict?: boolean;
+ };
+ };
+
+export interface RuntimeConfig {
+ iterationLimit?: number;
+ sandbox?: {
+ enabled: boolean;
+ fileDownloads?: boolean;
+ networkPolicy?: {
+ authInject?: Array<{
+ type: 'git';
+ match: { hosts: string[] };
+ authData: { type: 'basic'; username: string; password: string };
+ }>;
+ };
+ };
+ dynamicSubAgents?: { enabled?: boolean };
+ contextManagement?: {
+ compaction?: {
+ enabled?: boolean;
+ compactionThresholdTokens?: number;
+ };
+ largeToolResponse?: { enabled?: boolean };
+ };
+ generativeUi?: { enabled?: boolean };
+ askUserQuestions?: { enabled?: boolean };
+}
+
+/** Agent definition base. Hosts extend via `TSpec extends AgentSpec`. */
+export interface AgentSpec {
+ model: Model;
+ instructions?: string;
+ messages?: AgentSpecUserMessage[];
+ mcpServers?: McpServer[];
+ // responseFormat?: ResponseFormat;
+ skills?: SkillMount[];
+ // config?: RuntimeConfig;
+ // variables?: Record<string, string>;
+}
+
+export type AgentSpecUpdate = {
+ instructions?: string;
+ model?: Partial<Model> & {
+ params?: Partial<ModelParams>;
+ };
+ mcpServers?: McpServer[];
+ skills?: SkillMount[];
+ messages?: AgentSpecUserMessage[];
+ variables?: Record<string, string>;
+ responseFormat?: ResponseFormat;
+ config?: RuntimeConfig;
+};
+
+// ---------------------------------------------------------------------------
+// Session — one shape (named vs inline-spec is data, not dual APIs)
+// ---------------------------------------------------------------------------
+
+/**
+ * SDK-minimal session row.
+ * - Bound to a published agent → `agentName` set, `agentSpec` usually absent.
+ * - Inline / mutable spec → `agentSpec` set (host may still set `agentName`).
+ * - `isMutable` tells the UI whether to show the mutable agent-spec builder
+ * (and allow `updateSession`); do not infer from `agentSpec` alone.
+ * Hosts add extras via `TSession extends Session`.
+ */
+export interface Session {
+ id: string;
+ title?: string;
+ agentName?: string;
+ agentSpec?: AgentSpec;
+ /** UI: mutable builder + `updateSession(spec)` when true; immutable otherwise. */
+ isMutable: boolean;
+ createdAt: string;
+ updatedAt: string;
+}
+
+/**
+ * Create payload base. Provide at least one of `agentName` | `agentSpec`
+ * (enforced by host / runtime, not the type system).
+ * Hosts add extras via `TCreate extends CreateSessionRequest`.
+ */
+export interface CreateSessionRequest {
+ agentName?: string;
+ agentSpec?: AgentSpec;
+}
+
+/** List filter + pagination. Hosts extend via `TList extends ListSessionsParams`. */
+export interface ListSessionsParams extends PageParams {
+ agentName?: string;
+}
+
+/**
+ * Patch session (title / inline spec). No-op or error when `isMutable` is false.
+ * Hosts extend via `TUpdate extends UpdateSessionRequest`.
+ */
+export interface UpdateSessionRequest {
+ sessionId: string;
+ agentSpec?: AgentSpec;
+ title?: string;
+}
+
+export interface ListSessionsResponse<TSession extends Session = Session> {
+ data: TSession[];
+ pagination: TokenPagination;
+}
+
+// ---------------------------------------------------------------------------
+// Turn input / state
+// ---------------------------------------------------------------------------
+
+export type UserMessageContent =
+ string | Array<{ type: 'text'; text: string } | { type: 'file'; [key: string]: unknown }>;
+
+export interface UserMessage {
+ type: 'user.message';
+ content: UserMessageContent;
+}
+
+export interface ApprovalAllow {
+ status: 'allow';
+}
+
+export interface ApprovalDeny {
+ status: 'deny';
+ reason?: string;
+}
+
+export type ApprovalDecision = ApprovalAllow | ApprovalDeny;
+
+export interface UserToolApprovalEvent {
+ type: 'user.tool_approval';
+ threadId: string;
+ toolCallId: string;
+ approval: ApprovalDecision;
+}
+
+export interface UserToolResponseEvent {
+ type: 'user.tool_response';
+ threadId: string;
+ toolCallId: string;
+ content: string;
+}
+
+export type TurnInputItem = UserMessage | UserToolApprovalEvent | UserToolResponseEvent;
+
+export interface TurnStateRunning {
+ status: 'running';
+}
+
+export interface TurnStateDone {
+ status: 'done';
+ output?: {
+ type: 'model.message';
+ id: string;
+ threadId: string;
+ createdAt: string;
+ content?: unknown;
+ name?: string;
+ refusal?: string;
+ reasoningContent?: string;
+ toolCalls?: unknown[];
+ finishReason?: string;
+ usage?: unknown;
+ };
+ requiredActions: unknown[];
+ completedAt: string;
+}
+
+export type TurnStateCancelledReason =
+ 'server-execution-timeout' | 'client-cancelled' | 'cancelled-for-next-turn' | 'abandoned';
+
+export interface TurnStateCancelled {
+ status: 'cancelled';
+ reason: TurnStateCancelledReason;
+ completedAt: string;
+}
+
+export interface TurnStateError {
+ status: 'error';
+ message: string;
+ completedAt: string;
+}
+
+export type TurnState = TurnStateRunning | TurnStateDone | TurnStateCancelled | TurnStateError;
+
+/** SDK-minimal turn. Hosts extend via `TTurn extends Turn`. */
+export interface Turn {
+ id: string;
+ sessionId: string;
+ previousTurnId?: string;
+ input?: TurnInputItem[];
+ state: TurnState;
+ createdAt: string;
+}
+
+export interface ListTurnsResponse<TTurn extends Turn = Turn> {
+ data: TTurn[];
+ pagination: TokenPagination;
+}
+
+// ---------------------------------------------------------------------------
+// Stream / session events
+// ---------------------------------------------------------------------------
+
+/**
+ * Opaque streaming event (full union lives in gateway).
+ * Hosts may narrow via `TStreamEvent extends TurnStreamingEvent`.
+ */
+export type TurnStreamingEvent = { type: string; [key: string]: unknown };
+
+export interface TurnStreamData<TStreamEvent extends TurnStreamingEvent = TurnStreamingEvent> {
+ sequenceNumber: number;
+ event: TStreamEvent;
+}
+
+export type SessionEvent = { type: string; [key: string]: unknown };
+
+/** SDK-minimal history event row. Hosts extend via `TEvent extends SessionEventItem`. */
+export interface SessionEventItem {
+ turnId: string;
+ event: SessionEvent;
+}
+
+export interface ListSessionEventsResponse<TEvent extends SessionEventItem = SessionEventItem> {
+ data: TEvent[];
+ pagination: TokenPagination;
+}
+
+// ---------------------------------------------------------------------------
+// Behavioral session surface (DTO + methods)
+// ---------------------------------------------------------------------------
+
+export interface PreparedTurn<TStreamEvent extends TurnStreamingEvent = TurnStreamingEvent> {
+ execute(opts: { stream: false; pollIntervalMs?: number }): Promise<TurnState>;
+ execute(opts?: { stream?: true }): AsyncIterable<TurnStreamData<TStreamEvent>>;
+}
+
+export interface SessionMethods<
+ TTurn extends Turn = Turn,
+ TEvent extends SessionEventItem = SessionEventItem,
+ TSpec extends AgentSpec = AgentSpec,
+ TStreamEvent extends TurnStreamingEvent = TurnStreamingEvent,
+> {
+ prepareTurn(opts?: { input?: TurnInputItem[]; previousTurnId?: PreviousTurnIdInput }): PreparedTurn<TStreamEvent>;
+ listTurns(opts?: { pageToken?: string; limit?: number }): Promise<PageResult<TTurn, ListTurnsResponse<TTurn>>>;
+ getTurn(req: { turnId: string }): Promise<TTurn>;
+ cancel(): Promise<void>;
+ listEvents(opts?: {
+ pageToken?: string;
+ lastTurnId?: string;
+ limit?: number;
+ }): Promise<PageResult<TEvent, ListSessionEventsResponse<TEvent>>>;
+ /** Present when `isMutable` is true. */
+ update?(req?: { agentSpec?: TSpec }): Promise<void>;
+}
+
+export type AgentSession<
+ TSession extends Session = Session,
+ TTurn extends Turn = Turn,
+ TEvent extends SessionEventItem = SessionEventItem,
+ TSpec extends AgentSpec = AgentSpec,
+ TStreamEvent extends TurnStreamingEvent = TurnStreamingEvent,
+> = TSession & SessionMethods<TTurn, TEvent, TSpec, TStreamEvent>;
+
+// ---------------------------------------------------------------------------
+// Server ports
+// ---------------------------------------------------------------------------
+
+/**
+ * Unified chat / session port.
+ * TFY adapter may still fan out to gateway createSession vs createDraftSession
+ * internally — that is an implementation detail, not part of this contract.
+ */
+export interface AgentChatServer<
+ TSession extends Session = Session,
+ TCreate extends CreateSessionRequest = CreateSessionRequest,
+ TList extends ListSessionsParams = ListSessionsParams,
+ TUpdate extends UpdateSessionRequest = UpdateSessionRequest,
+ TTurn extends Turn = Turn,
+ TEvent extends SessionEventItem = SessionEventItem,
+ TSpec extends AgentSpec = AgentSpec,
+ TStreamEvent extends TurnStreamingEvent = TurnStreamingEvent,
+> {
+ createSession(req: TCreate): Promise<AgentSession<TSession, TTurn, TEvent, TSpec, TStreamEvent>>;
+ listSessions(
+ req?: TList,
+ ): Promise<PageResult<AgentSession<TSession, TTurn, TEvent, TSpec, TStreamEvent>, ListSessionsResponse<TSession>>>;
+ getSession(req: { sessionId: string }): Promise<AgentSession<TSession, TTurn, TEvent, TSpec, TStreamEvent>>;
+ updateSession(req: TUpdate): Promise<AgentSession<TSession, TTurn, TEvent, TSpec, TStreamEvent>>;
+
+ createTurn(req: {
+ sessionId: string;
+ input?: TurnInputItem[];
+ previousTurnId?: PreviousTurnIdInput;
+ stream: false;
+ pollIntervalMs?: number;
+ }): Promise<TurnState>;
+ createTurn(req: {
+ sessionId: string;
+ input?: TurnInputItem[];
+ previousTurnId?: PreviousTurnIdInput;
+ stream?: true;
+ }): AsyncIterable<TurnStreamData<TStreamEvent>>;
+
+ cancelSession(req: { sessionId: string }): Promise<void>;
+ deleteSession?(req: { sessionId: string }): Promise<void>;
+ listTurns(req: {
+ sessionId: string;
+ limit?: number;
+ pageToken?: string;
+ }): Promise<PageResult<TTurn, ListTurnsResponse<TTurn>>>;
+ getTurn(req: { sessionId: string; turnId: string }): Promise<TTurn>;
+ listEvents(req: {
+ sessionId: string;
+ pageToken?: string;
+ lastTurnId?: string;
+ limit?: number;
+ }): Promise<PageResult<TEvent, ListSessionEventsResponse<TEvent>>>;
+ subscribeToTurn?(req: {
+ sessionId: string;
+ turnId: string;
+ afterSequenceNumber?: number;
+ }): AsyncIterable<TurnStreamData<TStreamEvent>>;
+
+ downloadSandboxFile?(sandboxId: string, req: { path: string }): Promise<unknown>;
+}
+
+export interface AgentBuilderServer<
+ TModel extends ModelEntry = ModelEntry,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSpec extends AgentSpec = AgentSpec,
+ TSave = unknown,
+> {
+ getModels(): Promise<TModel[]>;
+ getSkills(): Promise<TSkill[]>;
+ getMcp(): Promise<TMcp[]>;
+ listAgents(req?: SearchAgentsParams): Promise<TAgent[]>; // for now only pagination, no search
+ saveAgent(req: {
+ agentName: string;
+ agentSpec: TSpec;
+ /** Session that held the inline spec being promoted (if any). */
+ sessionId?: string;
+ }): Promise<TSave>;
+ deleteAgent?(req: { agentName: string }): Promise<void>;
+}
+
+export type AgentUIServer<
+ TSession extends Session = Session,
+ TCreate extends CreateSessionRequest = CreateSessionRequest,
+ TList extends ListSessionsParams = ListSessionsParams,
+ TUpdate extends UpdateSessionRequest = UpdateSessionRequest,
+ TTurn extends Turn = Turn,
+ TEvent extends SessionEventItem = SessionEventItem,
+ TSpec extends AgentSpec = AgentSpec,
+ TStreamEvent extends TurnStreamingEvent = TurnStreamingEvent,
+ TModel extends ModelEntry = ModelEntry,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSave = unknown,
+> = AgentChatServer<TSession, TCreate, TList, TUpdate, TTurn, TEvent, TSpec, TStreamEvent> &
+ AgentBuilderServer<TModel, TSkill, TMcp, TAgent, TSpec, TSave>;
+
+// Todo : Make the SkillsMount as Generic
+
+// TrueForge SDK FE -> Generic Type // User can bring his own APIs (no touch to our client)
+// Runtime // (Decouple from the SDK Client)
+// TrueForge SDK FE -> Work was done here
+
+//Generic -> TrueForge SDK FE -> Runtime + Gateway SDK -> Backend (Generic)
+// Should our Runtime package not have the Gateway SDK
diff --git a/packages/trueforge-ui-sdk/docs/server.md b/packages/trueforge-ui-sdk/docs/server.md
new file mode 100644
index 000000000..63aa086f9
--- /dev/null
+++ b/packages/trueforge-ui-sdk/docs/server.md
@@ -0,0 +1,840 @@
+# Plan: Server abstraction (UI SDK only)
+
+Host-facing port so TrueFoundry gateway **or** bring-your-own APIs plug into one
+contract:
+
+- **Chat** — sessions, turns, draft `AgentSpec` sync
+- **Builder** — catalog (models / skills / MCP, read-only) + `saveAgent`
+ (promote draft → named agent)
+
+## Constraint
+
+Everything lives in **`@truefoundry/trueforge-ui`**.
+
+**No changes** to `@truefoundry/assistant-ui-runtime`.
+
+The runtime keeps accepting `client: AgentSessionClient` (and `privateClient`
+for draft). This package owns the host-facing `Server` façade and adapters.
+
+## Implication (explicit)
+
+| Concern | Reality in this plan |
+| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| BYO builder (`getModels` / `getSkills` / `getMcp` / `saveAgent`) | Real — implemented and consumed in this SDK |
+| BYO chat streaming | Limited — hosts must still supply gateway-compatible clients to the runtime, **or** wrap their API behind objects the runtime already expects |
+| `AgentChatServer` | Stable **host** API in this SDK; TFY path extracts/passes gateway clients into the unchanged runtime |
+
+## Locked decisions
+
+| Decision | Choice |
+| ----------------------------- | ----------------------------------------------------------------------------------------------------------- |
+| Shape | TypeScript `interface` (compose), not inheritance |
+| Split | `AgentChatServer` + `AgentBuilderServer` |
+| Package | This SDK only |
+| Modes (v1) | Named + Draft (single agent) |
+| Chat request / response types | Gateway SDK types (`AgentSession`, `AgentSpec`, `Turn`, …) |
+| Catalog types | SDK-minimal `ModelEntry` / `AgentSkill` / `ConnectorState` / `AgentLibraryEntry`; hosts extend via generics |
+| `saveAgent` | Promote draft `AgentSpec` → named agent; return stays host-defined for now |
+| Catalog lists | Read-only in v1 |
+| Runtime | Unchanged; still `client` / `privateClient` / `agent` |
+| Chat generics | **None** in v1 — session/turn types are gateway-fixed re-exports |
+
+## Interfaces (target)
+
+Chat types are imported from `truefoundry-gateway-sdk` (agents + API).
+`AgentSpec` is gateway SDK (`TruefoundryGatewayApi.AgentSpec`), re-exported by
+`@truefoundry/assistant-ui-runtime`. Builder catalog types are **SDK-minimal**
+(fields this UI reads); hosts keep extras typed with `T extends Base`.
+
+```ts
+import type { AgentSession, AgentDraftSession, Turn, TurnStreamData } from 'truefoundry-gateway-sdk/agents';
+import type {
+ AgentSpec,
+ TurnInputItem,
+ PreviousTurnIdInput,
+ TurnState,
+ SessionEventItem,
+ ListSessionsResponse,
+ ListDraftSessionsResponse,
+ ListOwnedSessionsResponse,
+ ListTurnsResponse,
+ ListSessionEventsResponse,
+ ListSessionsOrder,
+} from 'truefoundry-gateway-sdk';
+import type { Page, BinaryResponse } from 'truefoundry-gateway-sdk/core'; // or equivalent core export
+
+type PageParams = {
+ limit?: number;
+ order?: ListSessionsOrder;
+ pageToken?: string;
+ startTimestamp?: string;
+ endTimestamp?: string;
+};
+
+/** Chat / session port — gateway-fixed (not generic). */
+interface AgentChatServer {
+ // named
+ createSession(req: { agentName: string; tfyMetadata?: string }): Promise<AgentSession>;
+ listSessions(req: { agentName: string } & PageParams): Promise<Page<AgentSession, ListSessionsResponse>>;
+ getSession(req: { sessionId: string }): Promise<AgentSession>;
+
+ // draft
+ createDraftSession(req: {
+ agentSpec: AgentSpec;
+ agentName?: string;
+ tfyMetadata?: string;
+ }): Promise<AgentDraftSession>;
+ getDraftSession(req: { draftSessionId: string }): Promise<AgentDraftSession>;
+ listDraftSessions(
+ req?: { agentName?: string } & PageParams,
+ ): Promise<Page<AgentDraftSession, ListDraftSessionsResponse>>;
+ listOwnedSessions(
+ req?: { agentName?: string } & PageParams,
+ ): Promise<Page<AgentSession | AgentDraftSession, ListOwnedSessionsResponse>>;
+ /** Port helper: getDraftSession + update. Runtime draft sync may still go via privateClient. */
+ updateDraftSession(req: { draftSessionId: string; agentSpec?: AgentSpec }): Promise<AgentDraftSession>;
+
+ // turns (overloads match PreparedTurn.execute)
+ createTurn(req: {
+ sessionId: string;
+ input?: TurnInputItem[];
+ previousTurnId?: PreviousTurnIdInput;
+ stream: false;
+ pollIntervalMs?: number;
+ }): Promise<TurnState>;
+ createTurn(req: {
+ sessionId: string;
+ input?: TurnInputItem[];
+ previousTurnId?: PreviousTurnIdInput;
+ stream?: true;
+ }): AsyncIterable<TurnStreamData>;
+
+ cancelSession(req: { sessionId: string }): Promise<void>;
+ /** Host/BFF — optional until delete-UI ships. */
+ deleteSession?(req: { sessionId: string }): Promise<void>;
+ listTurns(req: { sessionId: string; limit?: number; pageToken?: string }): Promise<Page<Turn, ListTurnsResponse>>;
+ getTurn(req: { sessionId: string; turnId: string }): Promise<Turn>;
+ listEvents(req: {
+ sessionId: string;
+ pageToken?: string;
+ lastTurnId?: string;
+ limit?: number;
+ }): Promise<Page<SessionEventItem, ListSessionEventsResponse>>;
+ subscribeToTurn(req: {
+ sessionId: string;
+ turnId: string;
+ afterSequenceNumber?: number;
+ }): AsyncIterable<TurnStreamData>;
+
+ downloadSandboxFile?(sandboxId: string, req: { path: string }): Promise<BinaryResponse>;
+}
+
+/**
+ * Builder catalog + persist.
+ * Not in truefoundry-gateway-sdk — host/BFF provides these.
+ * Like MUI Table: bases declare what the SDK needs; T extends Base keeps host extras typed.
+ */
+interface AgentBuilderServer<
+ TModel extends ModelEntry = ModelEntry,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSave = unknown,
+> {
+ getModels(): Promise<TModel[]>;
+ getSkills(): Promise<TSkill[]>;
+ getMcp(): Promise<TMcp[]>;
+ /** Search / list named agents for the Agents Library. */
+ searchAgents(req?: { query?: string; limit?: number; offset?: number }): Promise<TAgent[]>;
+ /** Promote draft AgentSpec → named agent */
+ saveAgent(req: { agentName: string; agentSpec: AgentSpec; draftSessionId?: string }): Promise<TSave>;
+ /** Host/BFF — optional until delete-agent UI ships. */
+ deleteAgent?(req: { agentName: string }): Promise<void>;
+}
+
+type AgentUIServer<
+ TModel extends ModelEntry = ModelEntry,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSave = unknown,
+> = AgentChatServer & AgentBuilderServer<TModel, TSkill, TMcp, TAgent, TSave>;
+```
+
+Defaults keep bare `AgentUIServer` equivalent to the SDK-minimal catalog shapes.
+**Note:** Gateway session helpers are class instances (`AgentSession` /
+`AgentDraftSession` with methods). The TFY adapter returns those directly. BYO
+implementations must return values that satisfy the same types (or wrap until
+the port only exposes plain DTOs — not required for v1).
+
+Plain DTOs are also re-exported as `Session` / `DraftSession` (`TruefoundryGatewayApi`).
+
+### Extending catalog types
+
+```ts
+type MyModel = ModelEntry & { latencyMs: number };
+
+const server: AgentUIServer<MyModel> = createTrueFoundryServer({
+ // …
+ getModels: async () => [{ name: '…', provider: '…', apiModel: '…', modelId: '…', latencyMs: 12 }],
+});
+// server.getModels() → Promise<MyModel[]>
+```
+
+## Catalog APIs & AgentSpec Types
+
+Catalog bases are **SDK-minimal** (fields this UI reads). Platform/cpApi payloads
+may be richer — map them into these shapes, or keep extras via generics.
+
+### Catalog methods
+
+```ts
+getModels(): Promise<ModelEntry[]>;
+getSkills(): Promise<AgentSkill[]>;
+getMcp(): Promise<ConnectorState[]>;
+searchAgents(req?: { query?: string; limit?: number; offset?: number }): Promise<AgentLibraryEntry[]>;
+```
+
+In platform apps the RTK Query endpoints are named `getEnabledModels`,
+`getAgentSkills`, `getMcpServers`, and `getAgents`
+(`GET /api/svc/v1/agents?namePrefix=…`).
+
+#### `AgentLibraryEntry`
+
+```ts
+interface AgentLibraryEntry {
+ name: string;
+ description?: string;
+ model?: string;
+ skillsCount?: number;
+ mcpCount?: number;
+ author?: string;
+ updatedAt?: string;
+}
+```
+
+#### `ModelEntry`
+
+Written to `AgentSpec.model.name` via `apiModel` (fallback: `name`).
+
+```ts
+interface ModelEntry {
+ name: string;
+ provider: string;
+ apiModel: string;
+ modelId: string;
+}
+```
+
+#### `AgentSkill`
+
+Mounted onto `AgentSpec.skills` via `fqn` (fallback: `name`).
+
+```ts
+interface AgentSkill {
+ id: string;
+ name: string;
+ fqn?: string;
+ description?: string;
+}
+```
+
+#### `ConnectorState`
+
+Written to `AgentSpec.mcpServers[].name`.
+
+```ts
+interface ConnectorState {
+ id: string;
+ name: string;
+ description?: string;
+}
+```
+
+#### Session / DraftSession (gateway DTOs)
+
+```ts
+interface Session {
+ type: 'session';
+ id: string;
+ agentName: string;
+ title?: string;
+ createdBySubject: Subject;
+ createdAt: string;
+ updatedAt: string;
+}
+
+interface DraftSession {
+ type: 'session/draft';
+ id: string;
+ agentSpec: AgentSpec;
+ agentName?: string;
+ title?: string;
+ createdBySubject: Subject;
+ createdAt: string;
+ updatedAt: string;
+}
+```
+
+Thread list uses `id`, `title?`, `updatedAt`. Draft title falls back to
+`agentSpec.model.name`. `AgentSession` / `AgentDraftSession` add methods on top.
+
+### `AgentSpec` (complete)
+
+Source of truth: `truefoundry-gateway-sdk` → `TruefoundryGatewayApi.AgentSpec`
+Re-exported by: `@truefoundry/assistant-ui-runtime`
+
+```ts
+interface AgentSpec {
+ model: Model;
+ instructions?: string;
+ messages?: AgentSpecUserMessage[];
+ mcpServers?: McpServer[];
+ responseFormat?: ResponseFormat;
+ skills?: SkillMount[];
+ config?: RuntimeConfig;
+ variables?: Record<string, string>;
+}
+
+interface Model {
+ name: string;
+ params?: ModelParams;
+}
+
+interface ModelParams {
+ maxTokens?: number;
+ temperature?: number;
+ topP?: number;
+ topK?: number;
+ parallelToolCalls?: boolean;
+ reasoningEffort?: string;
+ cacheControl?: { type: string };
+}
+
+interface SkillMount {
+ /** Fully qualified name of the agent skill version. */
+ fqn: string;
+ /** If true, SKILL.md is injected into agent context. */
+ preload?: boolean;
+}
+
+type ToolsSelectorTag = '@all' | '@read-only';
+type ToolsSelectorItem = ToolsSelectorTag | string;
+
+type RequireApprovalToolsSelectorTag = '@all' | '@write' | '@destructive';
+type RequireApprovalToolSelectorItem = RequireApprovalToolsSelectorTag | string;
+
+interface BaseMcpServer {
+ name: string;
+ enableTools?: ToolsSelectorItem[];
+ disableTools?: ToolsSelectorItem[];
+ preloadTools?: ToolsSelectorItem[];
+ requireApprovalForTools?: RequireApprovalToolSelectorItem[];
+ preload?: boolean;
+}
+
+interface RegisteredMcpServer extends BaseMcpServer {
+ type: 'truefoundry-mcp-registry';
+}
+
+interface InlineMcpServer extends BaseMcpServer {
+ type: 'inline';
+ url: string;
+}
+
+type McpServer = RegisteredMcpServer | InlineMcpServer;
+
+interface AgentSpecUserMessage {
+ type: 'user.message';
+ content: string;
+}
+
+type ResponseFormat =
+ | { type: 'text' }
+ | { type: 'json_object' }
+ | {
+ type: 'json_schema';
+ jsonSchema: {
+ name: string;
+ description?: string;
+ schema?: Record<string, unknown>;
+ strict?: boolean;
+ };
+ };
+
+interface RuntimeConfig {
+ iterationLimit?: number;
+ sandbox?: {
+ enabled: boolean;
+ fileDownloads?: boolean;
+ networkPolicy?: {
+ authInject?: Array<{
+ type: 'git';
+ match: { hosts: string[] };
+ authData: { type: 'basic'; username: string; password: string };
+ }>;
+ };
+ };
+ dynamicSubAgents?: { enabled?: boolean };
+ contextManagement?: {
+ compaction?: {
+ enabled?: boolean;
+ compactionThresholdTokens?: number;
+ };
+ largeToolResponse?: { enabled?: boolean };
+ };
+ generativeUi?: { enabled?: boolean };
+ askUserQuestions?: { enabled?: boolean };
+}
+```
+
+### `AgentSpecUpdate` (partial patch)
+
+```ts
+type AgentSpecUpdate = {
+ instructions?: string;
+ model?: Partial<Model> & {
+ params?: Partial<ModelParams>;
+ };
+ mcpServers?: McpServer[];
+ skills?: SkillMount[];
+ messages?: AgentSpecUserMessage[];
+ variables?: Record<string, string>;
+ responseFormat?: ResponseFormat;
+ config?: RuntimeConfig;
+};
+```
+
+### Draft subset this app writes
+
+Typical builder → draft patch shape (not the full `AgentSpec`):
+
+```ts
+{
+ model: {
+ name: string;
+ params?: { maxTokens?: number; reasoningEffort?: string };
+ };
+ skills: { fqn: string; preload: false }[];
+ mcpServers: {
+ type: "truefoundry-mcp-registry";
+ name: string;
+ enableTools: ["@all"];
+ }[];
+}
+```
+
+## Gateway mapping (`AgentChatServer`)
+
+| Port method | Gateway source |
+| -------------------------------------- | ----------------------------------------------- |
+| `createSession` | `AgentSessionClient.createSession` |
+| `listSessions` | `AgentSessionClient.listSessions` |
+| `getSession` | `AgentSessionClient.getSession` |
+| `createDraftSession` | `PrivateAgentSessionClient.createDraftSession` |
+| `getDraftSession` | `PrivateAgentSessionClient.getDraftSession` |
+| `listDraftSessions` | `PrivateAgentSessionClient.listDraftSessions` |
+| `listOwnedSessions` | `PrivateAgentSessionClient.listOwnedSessions` |
+| `updateDraftSession` | `getDraftSession` + `AgentDraftSession.update` |
+| `createTurn` | session `prepareTurn` → `execute` / stream |
+| `cancelSession` | session `cancel` |
+| `listTurns` / `getTurn` / `listEvents` | session turn helpers |
+| `subscribeToTurn` | turn `stream` / subscribe |
+| `downloadSandboxFile` | `PrivateAgentSessionClient.downloadSandboxFile` |
+
+**Not in gateway:** `getModels`, `getSkills`, `getMcp`, `searchAgents`, `saveAgent`,
+`deleteAgent?`, `deleteSession?`.
+
+## Call flow (end state)
+
+```
+Host
+ └─ createTrueFoundryServer / custom AgentUIServer
+TrueforgeUI({ server, agentConfig, … })
+ ├─ builder UI ──► server.getModels / getSkills / getMcp / saveAgent
+ └─ TrueFoundryChatProvider
+ └─ useTrueFoundryAgentRuntime({
+ client, // from TFY adapter internals
+ privateClient?, // draft
+ agent: named | draft
+ }) // runtime package untouched
+```
+
+## Phases
+
+### Phase 0 — Spec freeze
+
+1. Keep this doc as the source of truth for interfaces and mapping.
+2. Confirm compose type: `AgentUIServer = AgentChatServer & AgentBuilderServer`.
+
+**Done when:** interfaces agreed; no code required.
+
+### Phase 1 — Types + TFY compose helper
+
+1. Add `AgentChatServer`, `AgentBuilderServer`, `AgentUIServer` under e.g. `src/server/`.
+2. Add `createTrueFoundryServer({ apiKey, baseUrl, saveAgent, getModels?, getSkills?, getMcp? })`:
+ - constructs `AgentSessionClient` + `PrivateAgentSessionClient`
+ - implements chat methods as thin wraps
+ - implements builder methods via host callbacks (`ModelEntry[]` / `AgentSkill[]` / `ConnectorState[]`)
+ - exposes SDK-internal handles for the runtime, e.g.
+ `getGatewayClients(): { client, privateClient }`
+ (not part of the public BYO contract)
+3. Export from the package entry.
+
+**Done when:** types + factory exist; unit test that the factory returns both
+clients and delegates `createSession` / `createDraftSession`.
+
+### Phase 2 — Wire `server` into UI shell (named)
+
+1. Extend `TrueFoundryChatProvider` / `TrueforgeUI`:
+ - prefer `server: AgentUIServer`
+ - keep legacy `client` or `apiKey` + `baseUrl` temporarily
+2. When `server` is TFY-composed: resolve gateway clients → pass into existing
+ `useTrueFoundryAgentRuntime({ client, privateClient?, agentName | agent })`.
+3. Builder methods unused on the named-only path.
+
+**Done when:** named agent works with
+`server={createTrueFoundryServer(...)}` (same UX as today).
+
+**Verify:** provider tests with a mock/TFY server that still supplies
+gateway-shaped clients for the runtime.
+
+### Phase 3 — Draft mode + builder port usage
+
+1. Support `agentConfig` modes (`SingleAgent` | `AgentLibrary` |
+ `AgentComposer` | `AgentLibraryWithComposer`).
+2. Draft → runtime `agent: { mode: "draft", … }` + `privateClient` from TFY
+ server handles.
+3. Use builder port:
+ - read-only lists from `getModels` / `getSkills` / `getMcp`
+ - apply selection → `updateDraftSession` / runtime
+ `useTrueFoundryUpdateAgentSpec` (already re-exported where available)
+ - Save → `saveAgent({ agentName, agentSpec, draftSessionId? })`
+4. Builder surface: hooks-first or minimal chrome (confirm before build) —
+ still only in this SDK.
+
+**Done when:** draft chat runs against inline spec; save calls host
+`saveAgent` once.
+
+**Verify:** example or tests with stub catalogs + stub `saveAgent`.
+
+### Phase 4 — Docs + BYO guidance
+
+1. Gateway path: `createTrueFoundryServer` + shell props.
+2. BYO path (honest):
+ - implement `AgentBuilderServer` fully
+ - for chat: use TFY clients **or** provide `AgentChatServer` **plus**
+ whatever the shell still needs to feed the runtime (document the gap:
+ runtime is not abstracted)
+3. Optional: in-memory stub for builder methods only.
+
+**Done when:** README / this doc show both paths.
+
+## Usage sketch (gateway-direct)
+
+```tsx
+const server = createTrueFoundryServer({
+ apiKey: process.env.TFY_API_KEY!,
+ baseUrl: process.env.TFY_GATEWAY_URL!,
+ saveAgent: async ({ agentName, agentSpec }) => {
+ // platform/BFF — promote draft AgentSpec → named agent
+ return fetch('/api/agents', {
+ method: 'POST',
+ body: JSON.stringify({ name: agentName, spec: agentSpec }),
+ }).then(r => r.json());
+ },
+ getModels: async () => [],
+ getSkills: async () => [],
+ getMcp: async () => [],
+ searchAgents: async () => [],
+});
+
+<TrueforgeUI
+ server={server}
+ // omit agentConfig → AgentLibraryWithComposer (library + draft)
+ // agentConfig={{ mode: "SingleAgent", name: "my-agent" }}
+ layout="sidebar"
+/>;
+```
+
+## BYO completeness checklist
+
+### Catalog — complete for this UI
+
+| UI call | Required response fields |
+| --------------------------- | ---------------------------------------------------------- |
+| `getModels()` | `name`, `provider`, `apiModel`, `modelId` |
+| `getSkills()` | `id`, `name`; `fqn?`, `description?` |
+| `getMcp()` | `id`, `name`; `description?` |
+| `searchAgents(req?)` | `name`; optional display fields on `AgentLibraryEntry` |
+| `saveAgent` / `deleteAgent` | On port; **not called by UI yet** (optional until Save UI) |
+
+### Chat — method list complete; standalone BYO is not
+
+1. This UI does **not** call `server.*` chat methods. `TrueFoundryChatProvider`
+ resolves `client` / `privateClient` for `useTrueFoundryAgentRuntime`.
+2. Session returns are **behavioral** (methods), not plain JSON DTOs alone.
+3. Stream/history events are full gateway unions: `TurnStreamData.event` →
+ `TurnStreamingEvent`; history → `SessionEventItem`.
+4. Draft `updateAgentSpec` in the runtime goes through `PrivateAgentSessionClient`
+ → raw gateway `draftSessions.update`, **not** `server.updateDraftSession`.
+
+**Must work for product chat (via gateway clients / compatible BFF):**
+`createSession`, `listSessions`, `getSession`, `createTurn` (stream),
+`cancelSession`, `listEvents`, `subscribeToTurn`, plus draft:
+`createDraftSession`, `getDraftSession`, `listDraftSessions`,
+`updateDraftSession` (port), `downloadSandboxFile` when sandbox downloads are
+enabled.
+
+**On the port but unused by this UI today:**
+`listOwnedSessions`, non-stream `createTurn`, `deleteSession`,
+`saveAgent`, `deleteAgent`.
+
+### v1 BYO guidance
+
+- **Builder:** implement `AgentBuilderServer` fully against your APIs (real BYO surface).
+- **Chat:** point gateway clients at a gateway-compatible BFF, or use
+ `createTrueFoundryServer`. Do not claim “replace chat with arbitrary REST” in v1.
+
+## Usage sketch (bring your own backend)
+
+Map your APIs into `AgentUIServer`. Chat method **request/response shapes** must
+match gateway types (`AgentSession`, `AgentSpec`, `Turn`, …). Builder catalog
+returns SDK-minimal `ModelEntry[]` / `AgentSkill[]` / `ConnectorState[]` (extend
+via generics); `saveAgent` return is host-defined (`unknown`).
+
+```tsx
+import type {
+ AgentUIServer,
+ AgentSpec,
+ AgentSession,
+ AgentDraftSession,
+ ModelEntry,
+ AgentSkill,
+ ConnectorState,
+ AgentLibraryEntry,
+} from '@truefoundry/trueforge-ui';
+import {
+ TrueforgeUI,
+ // TFY path still needs gateway clients for the unchanged runtime:
+ AgentSessionClient,
+ PrivateAgentSessionClient,
+} from '@truefoundry/trueforge-ui';
+
+/**
+ * Example: your REST/BFF is the source of truth for catalog + save,
+ * and you adapt session CRUD to our chat port.
+ *
+ * v1 note: `@truefoundry/assistant-ui-runtime` still consumes
+ * AgentSessionClient / PrivateAgentSessionClient. A common pattern is:
+ * - implement AgentBuilderServer fully against your APIs
+ * - for chat, either wrap gateway clients OR implement AgentChatServer
+ * and still pass gateway-shaped clients into the shell for streaming
+ * (see docs/server.md implication table)
+ */
+function createMyBackendServer(opts: {
+ apiBase: string;
+ getToken: () => string;
+ /** Gateway clients used by the runtime for turn streaming (TFY-compatible). */
+ gateway: {
+ client: AgentSessionClient;
+ privateClient: PrivateAgentSessionClient;
+ };
+}): AgentUIServer {
+ const headers = () => ({
+ Authorization: `Bearer ${opts.getToken()}`,
+ 'Content-Type': 'application/json',
+ });
+
+ const chatFromGateway: Pick<
+ AgentUIServer,
+ | 'createSession'
+ | 'listSessions'
+ | 'getSession'
+ | 'createDraftSession'
+ | 'getDraftSession'
+ | 'listDraftSessions'
+ | 'listOwnedSessions'
+ | 'updateDraftSession'
+ | 'createTurn'
+ | 'cancelSession'
+ | 'listTurns'
+ | 'getTurn'
+ | 'listEvents'
+ | 'subscribeToTurn'
+ | 'downloadSandboxFile'
+ > = {
+ // Thin-wrap gateway for chat (simplest BYO that still streams today).
+ // Replace these bodies with fetch(opts.apiBase + …) once you map to gateway types.
+ createSession: req => opts.gateway.client.createSession(req),
+ listSessions: req => opts.gateway.client.listSessions(req),
+ getSession: req => opts.gateway.client.getSession(req),
+ createDraftSession: req => opts.gateway.privateClient.createDraftSession(req),
+ getDraftSession: req => opts.gateway.privateClient.getDraftSession(req),
+ listDraftSessions: req => opts.gateway.privateClient.listDraftSessions(req),
+ listOwnedSessions: req => opts.gateway.privateClient.listOwnedSessions(req),
+ updateDraftSession: async ({ draftSessionId, agentSpec }) => {
+ const draft = await opts.gateway.privateClient.getDraftSession({
+ draftSessionId,
+ });
+ await draft.update({ agentSpec });
+ return draft;
+ },
+ createTurn: async function* (req) {
+ const session =
+ (await opts.gateway.client.getSession({ sessionId: req.sessionId }).catch(() => null)) ??
+ (await opts.gateway.privateClient.getDraftSession({
+ draftSessionId: req.sessionId,
+ }));
+ const prepared = session.prepareTurn({
+ input: req.input,
+ previousTurnId: req.previousTurnId,
+ });
+ if (req.stream === false) {
+ yield await prepared.execute({
+ stream: false,
+ pollIntervalMs: req.pollIntervalMs,
+ });
+ return;
+ }
+ yield* prepared.execute({ stream: true });
+ },
+ cancelSession: async ({ sessionId }) => {
+ const session = await opts.gateway.client.getSession({ sessionId });
+ await session.cancel();
+ },
+ listTurns: async ({ sessionId, ...page }) => {
+ const session = await opts.gateway.client.getSession({ sessionId });
+ return session.listTurns(page);
+ },
+ getTurn: async ({ sessionId, turnId }) => {
+ const session = await opts.gateway.client.getSession({ sessionId });
+ return session.getTurn({ turnId });
+ },
+ listEvents: async ({ sessionId, ...page }) => {
+ const session = await opts.gateway.client.getSession({ sessionId });
+ return session.listEvents(page);
+ },
+ subscribeToTurn: async function* ({ sessionId, turnId, afterSequenceNumber }) {
+ const session = await opts.gateway.client.getSession({ sessionId });
+ const turn = await session.getTurn({ turnId });
+ yield* turn.stream({ afterSequenceNumber });
+ },
+ downloadSandboxFile: (sandboxId, req) => opts.gateway.privateClient.downloadSandboxFile(sandboxId, req),
+ };
+
+ return {
+ ...chatFromGateway,
+
+ // --- fully your backend ---
+ async getModels() {
+ const res = await fetch(`${opts.apiBase}/catalog/models`, {
+ headers: headers(),
+ });
+ return res.json() as Promise<ModelEntry[]>;
+ },
+ async getSkills() {
+ const res = await fetch(`${opts.apiBase}/catalog/skills`, {
+ headers: headers(),
+ });
+ return res.json() as Promise<AgentSkill[]>;
+ },
+ async getMcp() {
+ const res = await fetch(`${opts.apiBase}/catalog/mcp`, {
+ headers: headers(),
+ });
+ return res.json() as Promise<ConnectorState[]>;
+ },
+ async searchAgents(req) {
+ const params = new URLSearchParams();
+ if (req?.query) params.set('namePrefix', req.query);
+ if (req?.limit != null) params.set('limit', String(req.limit));
+ if (req?.offset != null) params.set('offset', String(req.offset));
+ const res = await fetch(`${opts.apiBase}/agents?${params}`, {
+ headers: headers(),
+ });
+ return res.json() as Promise<AgentLibraryEntry[]>;
+ },
+ async saveAgent({ agentName, agentSpec, draftSessionId }) {
+ const res = await fetch(`${opts.apiBase}/agents`, {
+ method: 'POST',
+ headers: headers(),
+ body: JSON.stringify({
+ name: agentName,
+ spec: agentSpec,
+ draftSessionId,
+ }),
+ });
+ if (!res.ok) throw new Error(await res.text());
+ return res.json();
+ },
+ };
+}
+
+// App
+const gatewayClient = new AgentSessionClient({
+ apiKey: process.env.TFY_API_KEY!,
+ baseUrl: process.env.TFY_GATEWAY_URL!,
+});
+const gatewayPrivate = new PrivateAgentSessionClient({
+ apiKey: process.env.TFY_API_KEY!,
+ baseUrl: process.env.TFY_GATEWAY_URL!,
+});
+
+const server = createMyBackendServer({
+ apiBase: 'https://api.mycompany.com/v1',
+ getToken: () => process.env.MY_API_TOKEN!,
+ gateway: { client: gatewayClient, privateClient: gatewayPrivate },
+});
+
+export function App() {
+ return (
+ <TrueforgeUI
+ server={server}
+ agentConfig={{
+ mode: 'AgentComposer',
+ defaultAgentSpec: {
+ model: { name: 'openai-main/gpt-4.1' },
+ instructions: 'You are helpful.',
+ } satisfies AgentSpec,
+ }}
+ layout="sidebar"
+ theme={{
+ preset: 'chatgpt',
+ brand: {
+ name: 'MyCo',
+ logo: { src: '/myco-wordmark.svg' },
+ icon: { src: '/myco-mark.svg' },
+ },
+ }}
+ />
+ );
+}
+```
+
+**Pure custom chat (no gateway):** implement every `AgentChatServer` method so
+return values satisfy gateway types (`AgentSession`, `Page<…>`,
+`AsyncIterable<TurnStreamData>`, …). Until the runtime accepts `AgentChatServer`
+directly, the shell still needs a path into `useTrueFoundryAgentRuntime` —
+document that gap for hosts; v1 BYO strength is **builder + branding**, with
+chat either on gateway or a compatible adapter.
+
+## Non-goals (v1)
+
+- Any PR to `@truefoundry/assistant-ui-runtime`
+- Full BYO chat streaming without gateway-shaped clients
+- Typed `saveAgent` response (stays `unknown` / host-defined)
+- Multi-agent
+- Publish flow beyond `saveAgent`
+- Removing `tfy-web-components` / theming overhaul (separate track)
+
+## PR sequence (all in this repo)
+
+1. Types + `createTrueFoundryServer` + tests
+2. `server` prop on provider / shell (named)
+3. Draft `agentConfig` + builder / save wiring
+4. Docs + examples (gateway + BYO stub for builder)
+
+## Open before Phase 3
+
+- Builder surface: **hooks-only** vs **in-package minimal UI**
diff --git a/packages/trueforge-ui-sdk/docs/theming.md b/packages/trueforge-ui-sdk/docs/theming.md
new file mode 100644
index 000000000..c4eeb4b1d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/docs/theming.md
@@ -0,0 +1,515 @@
+# Plan: Remove `tfy-web-components`, own shadcn primitives + themes
+
+Hard-cut `tfy-web-components`. Own primitives (shadcn-style, in-repo),
+Markdown/OpenUI/syntax-highlighter/Monaco, Lucide icons (swappable map +
+SVG transform), and a **theme object** with presets
+(`truefoundry` | `claude` | `chatgpt` | `gemini`) plus full token / className /
+icon / **brand** / **content classNames** customization. Shell also accepts a
+**custom layout** React component built from `Thread`, thread list, etc.
+
+## Principle: everything customizable
+
+Hosts must be able to restyle, rebrand, and rearrange chrome without forking
+the SDK. Layers (each independently overridable):
+
+| Layer | What it customizes | How |
+| ------------------ | -------------------------------------------- | --------------------------------------------- |
+| Preset | Baseline look | `theme.preset` |
+| Tokens | Colors, radius, fonts, bubble colors | `theme.tokens` + CSS vars |
+| Brand | Logo + brand mark / icon | `theme.brand` |
+| Icons | Action / UI icon set | `theme.icons` (Lucide + SVG transforms) |
+| Content classNames | Markdown, syntax-highlighter, OpenUI, Monaco | `theme.classNames` |
+| Root class | Arbitrary host utilities | `theme.className` |
+| Host CSS | Any token / layout tweak | documented `:root` / `.aui-root` overrides |
+| Slots | Replace any React piece | `overrides` / `SlotsProvider` |
+| Layout | Entire chrome arrangement | `layout` string **or** custom React component |
+
+No visual or chrome element should be hard-wired to TrueFoundry branding.
+Defaults may ship TFY look; every surface must accept a host override.
+
+## Constraint
+
+All work in **`@truefoundry/trueforge-ui`**. No runtime package changes for this
+track (orthogonal to [`docs/server.md`](./server.md)).
+
+## Locked decisions
+
+| Decision | Choice |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| Cutover | Hard cut — remove dep + peer |
+| Primitives | shadcn components **copied into** this repo |
+| Coverage | Everything currently pulled from tfy |
+| Slot API | **Breaking** — drop `Button.Primary` / icon-string contracts; new shadcn-aligned props |
+| Icons | Lucide defaults; host can replace map + supply SVG transforms |
+| Brand | Replacable via `theme.brand` (logo URL/node + brand icon URL/node/SVG) |
+| Theme API | Object (not string-only); every look aspect customizable |
+| Presets | Inspired-by packs: `truefoundry` (default), `claude`, `chatgpt`, `gemini` |
+| Custom styles | CSS tokens + `className`; host may also import CSS (documented). No “load CSS file” prop |
+| Light / dark | Controlled `mode` on the theme object **or** omit → uncontrolled `useTheme().setTheme` |
+| React overrides | Structural pieces via **`overrides` / slots**; full chrome via **`layout` component** |
+| Markdown | In-repo; OpenUI kept; code fences via syntax-highlighter |
+| Monaco | In-repo (code artifacts / rich code surfaces); classNames overridable |
+| Content styling | `theme.classNames` for markdown, highlighter, OpenUI, Monaco |
+| Layout | Built-in presets **or** host `React` layout using exported building blocks |
+| Release | Breaking **0.x** (slot API + styles + drop tfy) |
+
+## Inventory → replacements
+
+### Primitives (slot defaults today)
+
+| Current (tfy) | Target (in-repo shadcn-style) |
+| ------------------ | -------------------------------------------------------------------------- |
+| `Button` | `Button` (variants: default, secondary, ghost, destructive, outline, size) |
+| `IconButton` | `Button` size=`icon` **or** thin `IconButton` wrapper |
+| `Modal` / `Dialog` | `Dialog` (+ sheet if drawer needs it) |
+| `Accordion*` | `Accordion` |
+| `LightTooltip` | `Tooltip` |
+| `Skeleton` | `Skeleton` |
+| `Avatar*` | `Avatar` |
+| `Spinner` | small `Spinner` / loader (FA or inline SVG) |
+| `DropdownMenu` | `DropdownMenu` |
+
+### Feature atoms that wrap tfy molecules
+
+Rebuild in-repo (keep existing atom **names** / slots where possible, change
+props):
+
+- Bubbles: `AssistantMessageBubble`, `UserMessageBubble`, `UserMessageEdit`
+- Tools: `ToolCallCard`, `ToolCallContentBlock`, `ToolApprovalBar`,
+ `ToolGroupCard`, `SubAgentCard`, `SandboxToolCallCard`, `AgentStepsCard`,
+ `ReasoningCard`
+- Prompts: `AskUserPrompt`, `McpAuthPrompt`
+- `Markdown` (OpenUI + highlighter)
+- Layout helpers using `IconProvider` → local icon resolver
+
+### Theme / icons / brand infra
+
+| Remove | Replace with |
+| -------------------------------- | ------------------------------------------------------------------------------------------- |
+| `tfy-web-components/theme.css` | Own palette + semantic tokens in `styles.css` |
+| tfy `ThemeProvider` / `useTheme` | SDK `ThemeProvider` owned here |
+| `IconProvider` + `registerIcons` | `IconRegistry` + `theme.icons` / `setIcons` |
+| Hard-coded TFY marks | `theme.brand` (logo + brand icon) consumed by header, welcome, widget FAB, avatar fallbacks |
+
+### Code surfaces (Monaco + syntax highlighter)
+
+Not currently imported anywhere in `src/` — dormant tfy surface, but real:
+tfy's own `Markdown` fenced-code rendering depends on it, so dropping tfy
+loses it silently unless ported explicitly.
+
+| Current (tfy) | Target (in-repo) |
+| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `molecules/monacoEditorCore/MonacoEditorCore` (thin `monaco-editor` wrapper: `onMount`/`beforeMount`/`theme`/`options`) | Local `MonacoEditorCore` atom, same prop surface, direct `monaco-editor` dependency |
+| `molecules/SimpleCodeEditor` (copy/download/expand/fullscreen/line-numbers atop `MonacoEditorCore`) | Local `CodeEditor` atom (rebuilt on local `MonacoEditorCore`, same feature set) |
+| `molecules/CopyField` / `CopyFieldHighlighted` (copy affordance used by `SimpleCodeEditor`) | Fold into local `CodeEditor` copy button; no separate primitive needed |
+| `react-syntax-highlighter` used internally by tfy `Markdown`/`MarkdownWithOpenUI` for non-OpenUI fenced code | Local `SyntaxHighlighter` atom, called from the in-repo `Markdown` atom for non-openui fences (same line-numbers / light-dark theme mapping) |
+
+New direct dependencies this implies: `monaco-editor`, `react-syntax-highlighter`
+(+ `@types/react-syntax-highlighter`).
+
+## Theme API (target)
+
+```ts
+type ThemeMode = "light" | "dark" | "system";
+
+type ThemePreset = "truefoundry" | "claude" | "chatgpt" | "gemini";
+
+type SemanticTokens = {
+ background: string;
+ foreground: string;
+ card: string;
+ cardForeground: string;
+ popover: string;
+ popoverForeground: string;
+ primary: string;
+ primaryForeground: string;
+ secondary: string;
+ secondaryForeground: string;
+ muted: string;
+ mutedForeground: string;
+ accent: string;
+ accentForeground: string;
+ destructive: string;
+ destructiveForeground: string;
+ border: string;
+ input: string;
+ ring: string;
+ radius: string;
+ fontSans: string; // maps to --font-agent-ui
+ // optional chat-specific:
+ userBubble?: string;
+ userBubbleForeground?: string;
+ assistantBubble?: string;
+ assistantBubbleForeground?: string;
+};
+
+/** UI action icons (send, attach, copy, …) — Lucide, React nodes, or SVG wrappers */
+type IconMap = Record<
+ string,
+ | LucideIcon
+ | React.ReactNode
+ | ((props: IconProps) => React.ReactNode)
+ | React.FC<React.SVGProps<SVGSVGElement>>
+>;
+
+type BrandImage =
+ | { src: string; alt?: string }
+ | React.ReactNode
+ | ((props: { className?: string }) => React.ReactNode);
+
+/**
+ * Product branding — distinct from `icons` (UI chrome).
+ * Used anywhere a product mark appears today (header, welcome, widget FAB,
+ * empty states, assistant avatar fallback).
+ */
+type BrandConfig = {
+ /** Wordmark / wide logo (sidebar header, welcome). */
+ logo?: BrandImage;
+ /** Square brand mark / app icon (FAB, avatar fallback, compact chrome). */
+ icon?: BrandImage;
+ /** Optional display name next to logo. */
+ name?: string;
+};
+
+type ThemeConfig = {
+ preset?: ThemePreset; // default: "truefoundry"
+ mode?: ThemeMode; // omit = uncontrolled (useTheme().setTheme)
+ tokens?: Partial<SemanticTokens>;
+ brand?: BrandConfig; // logo + brand icon replacement
+ className?: string; // applied on .aui-root (or theme root)
+ icons?: IconMap; // full/partial UI icon replace + SVG transforms
+ /** Per-surface className hooks for content renderers */
+ classNames?: ContentClassNames;
+};
+
+/**
+ * Override CSS classes (and optional style props) on content engines.
+ * All fields optional; merge with defaults via `cn()`.
+ */
+type ContentClassNames = {
+ /** Wrapper / prose root for rendered markdown */
+ markdown?: string;
+ /** Non-openui fenced code blocks (syntax-highlighter root / pre / code) */
+ syntaxHighlighter?: {
+ root?: string;
+ pre?: string;
+ code?: string;
+ lineNumber?: string;
+ };
+ /** OpenUI fenced-block host + common child hooks */
+ openui?: {
+ root?: string;
+ /** Extra classes forwarded into OpenUI theme/host if supported */
+ [key: string]: string | undefined;
+ };
+ /** Monaco editor / diff surfaces */
+ monaco?: {
+ root?: string;
+ editor?: string;
+ /** Optional Monaco `theme` id or defineTheme hook name — styling adjacent */
+ monacoTheme?: string;
+ };
+};
+
+type BuiltInLayout = "sidebar" | "drawer" | "dock" | "widget";
+
+/**
+ * Shell layout: built-in string **or** a host component that composes
+ * exported building blocks (`Thread`, `ThreadListContainer`, …).
+ */
+type LayoutProp = BuiltInLayout | React.ComponentType<{ className?: string }>;
+
+// Usage — theme + custom layout
+function MyLayout({ className }: { className?: string }) {
+ return (
+ <div className={cn("flex h-full", className)}>
+ <aside className="w-64 border-r">
+ <ThreadListContainer />
+ </aside>
+ <main className="flex min-w-0 flex-1 flex-col">
+ <Thread />
+ </main>
+ </div>
+ );
+}
+
+<TrueforgeUI
+ layout={MyLayout} // or "sidebar" | "drawer" | "dock" | "widget"
+ theme={{
+ preset: "claude",
+ mode: "dark",
+ tokens: { primary: "#…", fontSans: '"My Font", system-ui' },
+ brand: {
+ name: "Acme Agent",
+ logo: { src: "/acme-wordmark.svg", alt: "Acme" },
+ icon: MyAcmeMark,
+ },
+ className: "my-chat",
+ icons: { send: MySendSvg, paperclip: MyAttachSvg },
+ classNames: {
+ markdown: "prose prose-neutral dark:prose-invert max-w-none",
+ syntaxHighlighter: {
+ root: "my-code-block rounded-lg",
+ pre: "bg-zinc-950 p-4",
+ code: "text-sm font-mono",
+ },
+ openui: { root: "my-openui-host" },
+ monaco: { root: "my-monaco h-64", monacoTheme: "vs-dark" },
+ },
+ }}
+ overrides={{ WelcomeScreen: MyWelcome }}
+/>
+```
+
+**Resolution order:** preset defaults → `tokens` → `brand` / `icons` →
+`classNames` → host CSS variables (documented) → `className` utilities.
+
+**Custom styles without the object:** host CSS still works:
+
+```css
+.aui-root {
+ --primary: #e11d48;
+ --font-agent-ui: 'My Font', system-ui, sans-serif;
+}
+
+/* Or target documented content hooks */
+.aui-root .aui-markdown {
+ /* … */
+}
+.aui-root .aui-syntax-highlighter {
+ /* … */
+}
+.aui-root .aui-openui {
+ /* … */
+}
+.aui-root .aui-monaco {
+ /* … */
+}
+```
+
+## Brand system
+
+1. All product marks render through `useBrand()` / `<BrandLogo />` /
+ `<BrandIcon />` — never hard-coded TFY assets in layouts or atoms.
+2. `theme.brand.logo` → headers, welcome, wide chrome.
+3. `theme.brand.icon` → widget FAB, compact headers, assistant avatar fallback
+ when no user avatar is set.
+4. `theme.brand.name` → accessible labels / text next to logo when provided.
+5. Omitting `brand` keeps the default TrueFoundry (or preset) mark; hosts
+ replace either or both logo and icon independently.
+
+## Icon system
+
+1. Ship default Lucide map (stable FA-style keys via `IconRegistry`).
+2. `theme.icons` merges over defaults (partial or full replace).
+3. Allow React SVG / SVGR transform wrappers as values.
+4. Custom agent SVGs stay on the SVGR pipeline (`registerAgentIcons`).
+5. `useIcon(name)` / `<Icon name="paperclip" />` for all call sites (breaking
+ vs string props on tfy `IconButton`).
+6. Brand marks are **not** mixed into `icons` — use `theme.brand` so product
+ identity stays separate from action icons.
+
+## Layout override
+
+`TrueforgeUI` / chat shell `layout` prop:
+
+| Value | Behavior |
+| --------------------------------------------------- | ---------------------------- |
+| `"sidebar"` \| `"drawer"` \| `"dock"` \| `"widget"` | Built-in layouts (unchanged) |
+| `React.ComponentType<{ className?: string }>` | Host-owned chrome |
+
+Custom layouts compose **exported** building blocks (same as today’s advanced
+compose path), for example:
+
+- `Thread` / `ThreadContainer`
+- `ThreadListContainer`
+- `Composer` pieces / slot-backed atoms as needed
+- Brand helpers (`BrandLogo`, `BrandIcon`) and `useTheme`
+
+The shell still wraps the custom layout with theme + slots + chat provider;
+only the chrome tree is replaced. Equivalent to skipping built-in layouts
+without dropping providers.
+
+```tsx
+import { TrueforgeUI, Thread, ThreadListContainer } from '@truefoundry/trueforge-ui';
+
+function CenteredLayout() {
+ return (
+ <div className="mx-auto flex h-full max-w-3xl flex-col">
+ <ThreadListContainer />
+ <Thread />
+ </div>
+ );
+}
+
+<TrueforgeUI
+ server={server}
+ agentConfig={{ mode: 'SingleAgent', name: 'my-agent' }}
+ layout={CenteredLayout}
+ theme={{ preset: 'gemini' }}
+/>;
+```
+
+## Presets (inspired-by)
+
+Ship as CSS variable maps under e.g. `src/theme/presets/`:
+
+| Preset | Intent (not a clone) |
+| ------------- | ------------------------------------------------------- |
+| `truefoundry` | Current indigo semantic look |
+| `claude` | Warm paper bg, soft borders, restrained accent |
+| `chatgpt` | Cool gray chrome, green/teal send accent, flat bubbles |
+| `gemini` | Light airy surface, blue accent, slightly larger radius |
+
+Each preset defines **light + dark** token sets. Document that these are
+stylistic homages, not product replicas.
+
+## Markdown / OpenUI / syntax-highlighter / Monaco
+
+1. Replace `MarkdownWithOpenUI` with in-repo `Markdown` atom.
+2. Keep `@openuidev/*` (already via `openui.css`) as first-party styling
+ surface; theme tokens should flow into OpenUI where possible.
+3. Fenced code (non-openui): syntax-highlighter themed from semantic tokens
+ **and** `theme.classNames.syntaxHighlighter`.
+4. Monaco in-repo for rich code / artifact surfaces; style via
+ `theme.classNames.monaco` (+ optional `monacoTheme` id).
+5. Stable DOM hooks (`aui-markdown`, `aui-syntax-highlighter`, `aui-openui`,
+ `aui-monaco`) so host CSS works without the theme object.
+6. Preload path: replace `preloadMarkdownOpenUI` with local equivalent.
+7. Pass `theme.classNames.markdown` / `openui` into the Markdown/OpenUI hosts.
+
+## Call flow
+
+```
+TrueforgeUI({ layout, theme, overrides, … })
+ └─ SlotsProvider / ThemeProvider
+ ├─ apply preset → CSS variables on .aui-root
+ ├─ merge theme.tokens / brand / icons / classNames / className
+ ├─ layout = built-in | <HostLayout />
+ └─ defaultSlots → local shadcn primitives + feature atoms
+ ├─ BrandLogo / BrandIcon wherever product mark appears
+ └─ Markdown / OpenUI / syntax-highlighter / Monaco
+ (classNames from theme)
+```
+
+## Phases
+
+### Phase 0 — Spec freeze
+
+1. Keep this doc as the source of truth.
+2. List every tfy import → owner file → replacement (use inventory above).
+3. Final `ThemeConfig` + new primitive prop types.
+
+**Done when:** interfaces agreed; inventory complete.
+
+### Phase 1 — Token foundation (no full visual rewrite yet)
+
+1. Stop importing `tfy-web-components/theme.css`.
+2. Inline a minimal palette + keep existing semantic `@layer` tokens.
+3. Own `ThemeProvider` / `useTheme` (mode light/dark/system); wire
+ `SlotsProvider` to it.
+4. Apply `theme.className` + CSS vars from `theme.tokens` / `preset` on root.
+5. Introduce `BrandConfig` plumbing (`useBrand`, `<BrandLogo />`,
+ `<BrandIcon />`) even if defaults still point at TFY assets.
+
+**Done when:** app runs with owned tokens (tfy components may still be present);
+host can override `--primary` and swap `theme.brand.icon` / `logo`.
+
+### Phase 2 — shadcn primitives + icon + brand registry
+
+1. Add in-repo primitives under `src/atoms/primitives/` (or `src/ui/`).
+2. New slot defaults; **break** compound Button / icon-string APIs.
+3. Lucide `IconRegistry`; migrate call sites; support `theme.icons`.
+4. Wire layouts / welcome / widget FAB / avatar fallbacks to `theme.brand`.
+5. Update [`docs/customization.md`](./customization.md) for new override
+ contracts (tokens, brand, icons, slots).
+
+**Done when:** no primitive imports from tfy; slots resolve to local components;
+brand logo/icon replaceable via theme.
+
+### Phase 3 — Rebuild feature atoms / molecules
+
+1. Replace each tfy agent-chat wrapper with local Tailwind + primitives.
+2. Keep slot **names** stable where possible (`AssistantMessageBubble`, …) so
+ overrides still work after prop migration.
+3. Layouts: remove `IconProvider`; support `layout={MyComponent}` on the shell
+ (built-ins unchanged).
+
+**Done when:** `rg tfy-web-components src` is empty; custom layout component
+renders inside providers.
+
+### Phase 4 — Markdown + OpenUI + highlighter + Monaco
+
+1. In-repo Markdown + OpenUI fences.
+2. Port `react-syntax-highlighter`-based fenced-code rendering out of tfy's
+ `Markdown` into a local `SyntaxHighlighter` atom (add direct deps:
+ `react-syntax-highlighter`, `@types/react-syntax-highlighter`).
+3. Port `MonacoEditorCore` + `SimpleCodeEditor` (copy/download/expand/
+ fullscreen/line-numbers) into local `MonacoEditorCore` + `CodeEditor`
+ atoms for rich code / artifact surfaces (lazy-load where possible; add
+ direct dep `monaco-editor`).
+4. Wire `theme.classNames` (`markdown`, `syntaxHighlighter`, `openui`,
+ `monaco`) + stable `aui-*` hooks for host CSS.
+5. Fix tests that mock `tfy-markdown-openui`.
+
+**Done when:** OpenUI / code fences / Monaco render without tfy; classNames
+overrides apply in the example app.
+
+### Phase 5 — Presets + polish
+
+1. Ship `claude` / `chatgpt` / `gemini` / `truefoundry` packs.
+2. Example app: theme switcher + custom layout demo + content classNames demo.
+3. Drop `tfy-web-components` from `dependencies` / `peerDependencies`.
+4. CHANGELOG + migration guide (slot props, styles, brand, layout, classNames).
+
+**Done when:** presets + custom layout + content classNames demos work; package
+no longer depends on tfy.
+
+## Migration notes (for consumers)
+
+- Remove `@import "tfy-web-components/theme.css"`.
+- Only `@import "@truefoundry/trueforge-ui/styles.css"` (+ host Tailwind
+ preflight as today).
+- Revisit `overrides` for `Button` / `IconButton` / bubbles (new props).
+- Prefer
+ `theme={{ preset, tokens, brand, icons, className, classNames }}`
+ over hacking a third-party theme.
+- Replace product marks with `theme.brand.logo` / `theme.brand.icon` (URL,
+ React node, or SVG component).
+- Pass `layout={MyLayout}` to own chrome; compose `Thread` /
+ `ThreadListContainer` / etc.
+- Style content engines via `theme.classNames` or `.aui-markdown` /
+ `.aui-syntax-highlighter` / `.aui-openui` / `.aui-monaco`.
+
+## Non-goals (v1)
+
+- Pixel-perfect Claude / ChatGPT / Gemini clones
+- Dual-running tfy + shadcn
+- Moving structural atom overrides into `theme` (those stay in `overrides`;
+ full chrome uses `layout` instead)
+- Runtime / Server abstraction work (see [`docs/server.md`](./server.md))
+
+## PR sequence
+
+1. Tokens + owned ThemeProvider (still on tfy components if needed mid-migration)
+2. Primitives + IconRegistry + slot API break
+3. Feature atoms migration (can split by domain: chrome → tools → messages)
+4. Custom `layout` component support
+5. Markdown / OpenUI / syntax-highlighter / Monaco + `theme.classNames`
+6. Presets + remove tfy dep + example + docs
+
+## Success criteria
+
+- `rg tfy-web-components src` → empty
+- Four presets + custom `tokens` / `brand` / `icons` / `className` /
+ `classNames` demo in example
+- Host can pass `layout={MyLayout}` built from `Thread` + thread list exports
+- Host can override classes on Markdown, syntax-highlighter, OpenUI, and Monaco
+ via `theme.classNames` and/or stable `aui-*` CSS hooks
+- Host can fully rebrand (colors, fonts, logo, brand icon, action icons)
+ without slot overrides
+- Host can still replace any component via `overrides` when needed
+- Light/dark controlled + uncontrolled both work
+- Slot override of `Button` works with new API
+- OpenUI fenced blocks still render
+- No hard-coded TrueFoundry logo/mark outside default `theme.brand` assets
diff --git a/packages/trueforge-ui-sdk/eslint.config.js b/packages/trueforge-ui-sdk/eslint.config.js
new file mode 100644
index 000000000..4e2db7b2a
--- /dev/null
+++ b/packages/trueforge-ui-sdk/eslint.config.js
@@ -0,0 +1,39 @@
+import eslint from '@eslint/js';
+import reactHooks from 'eslint-plugin-react-hooks';
+import globals from 'globals';
+import tseslint from 'typescript-eslint';
+
+export default tseslint.config(
+ {
+ ignores: ['dist/**', 'node_modules/**', 'coverage/**'],
+ },
+ eslint.configs.recommended,
+ ...tseslint.configs.recommended,
+ {
+ files: ['src/**/*.{ts,tsx}'],
+ languageOptions: {
+ ecmaVersion: 2022,
+ globals: {
+ ...globals.browser,
+ ...globals.node,
+ },
+ },
+ plugins: {
+ 'react-hooks': reactHooks,
+ },
+ rules: {
+ 'react-hooks/rules-of-hooks': 'error',
+ 'react-hooks/exhaustive-deps': 'warn',
+ // Slot registry pattern resolves components during render by design.
+ 'react-hooks/static-components': 'off',
+ 'react-hooks/set-state-in-effect': 'off',
+ 'react-hooks/refs': 'off',
+ 'react-hooks/immutability': 'off',
+ 'react-hooks/preserve-manual-memoization': 'off',
+ '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+ '@typescript-eslint/no-explicit-any': 'off',
+ '@typescript-eslint/ban-ts-comment': 'off',
+ '@typescript-eslint/no-empty-object-type': 'off',
+ },
+ },
+);
diff --git a/packages/trueforge-ui-sdk/example/.env.example b/packages/trueforge-ui-sdk/example/.env.example
new file mode 100644
index 000000000..db1a02645
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/.env.example
@@ -0,0 +1,7 @@
+VITE_TFY_API_KEY=
+VITE_TFY_CONTROL_PLANE_URL=
+# Optional — when omitted, resolved from the control plane session
+VITE_TFY_GATEWAY_URL=
+VITE_TFY_AGENT_NAME=ask-ai-agent
+# SingleAgent | AgentLibrary | AgentComposer | AgentLibraryWithComposer (default)
+VITE_TFY_AGENT_MODE=AgentLibraryWithComposer
diff --git a/packages/trueforge-ui-sdk/example/.gitignore b/packages/trueforge-ui-sdk/example/.gitignore
new file mode 100644
index 000000000..7b0716082
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/.gitignore
@@ -0,0 +1,5 @@
+node_modules
+dist
+.env
+.env.local
+*.local
diff --git a/packages/trueforge-ui-sdk/example/.yarnrc b/packages/trueforge-ui-sdk/example/.yarnrc
new file mode 100644
index 000000000..4f14322dc
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/.yarnrc
@@ -0,0 +1 @@
+--ignore-engines true
diff --git a/packages/trueforge-ui-sdk/example/README.md b/packages/trueforge-ui-sdk/example/README.md
new file mode 100644
index 000000000..570ad2987
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/README.md
@@ -0,0 +1,52 @@
+# Example app
+
+Minimal Vite + React demo for `@truefoundry/trueforge-ui`.
+
+## Setup
+
+1. Build the SDK from the repo root (the example depends on `link:..` / `dist/`):
+
+```bash
+cd ..
+yarn install --ignore-engines
+yarn build
+```
+
+`link:..` symlinks the SDK so example picks up a fresh `dist/` after each
+`yarn build`. Re-run `yarn` in `example/` if the link is missing. The example
+imports Tailwind via `@tailwindcss/vite` (`@import "tailwindcss"` in
+`src/index.css`) for preflight, since the SDK does not ship it.
+
+2. Configure env:
+
+```bash
+cd example
+cp .env.example .env
+```
+
+Fill in:
+
+| Variable | Description |
+| ---------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `VITE_TFY_API_KEY` | TrueFoundry API key |
+| `VITE_TFY_CONTROL_PLANE_URL` | Control Plane base URL (required for `type: "truefoundry"`) |
+| `VITE_TFY_GATEWAY_URL` | Optional gateway base URL; when omitted, resolved from CP |
+| `VITE_TFY_AGENT_NAME` | Named agent for `SingleAgent` mode (default `ask-ai-agent`) |
+| `VITE_TFY_AGENT_MODE` | Shell mode: `SingleAgent` \| `AgentLibrary` \| `AgentComposer` \| `AgentLibraryWithComposer` (default) |
+
+API keys in client env are for local demos only — keep secrets on a server in production.
+
+3. Install and run:
+
+```bash
+yarn
+yarn dev
+```
+
+Open the URL Vite prints (usually `http://localhost:5173`).
+
+The demo uses `server={{ type: "truefoundry", … }}` so `<TrueforgeUI />` builds
+the agent UI server from the control plane + API key (same path as production
+TrueFoundry hosts). Pass `agentConfig` to pick shell mode (see `src/App.tsx`).
+Default mode is **AgentLibraryWithComposer**. Change `VITE_TFY_AGENT_MODE` to
+try the other modes.
diff --git a/packages/trueforge-ui-sdk/example/index.html b/packages/trueforge-ui-sdk/example/index.html
new file mode 100644
index 000000000..d41a2561d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/index.html
@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>trueforge-ui example</title>
+ </head>
+ <body>
+ <div id="root"></div>
+ <script type="module" src="/src/main.tsx"></script>
+ </body>
+</html>
diff --git a/packages/trueforge-ui-sdk/example/package.json b/packages/trueforge-ui-sdk/example/package.json
new file mode 100644
index 000000000..36f533591
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/package.json
@@ -0,0 +1,34 @@
+{
+ "name": "trueforge-ui-example",
+ "private": true,
+ "version": "0.0.0",
+ "type": "module",
+ "scripts": {
+ "dev": "vite",
+ "build": "tsc -b && vite build",
+ "preview": "vite preview"
+ },
+ "dependencies": {
+ "@assistant-ui/core": "^0.2.22",
+ "@assistant-ui/react": "^0.14.24",
+ "@truefoundry/trueforge-ui": "link:..",
+ "@truefoundry/assistant-ui-runtime": "^0.1.9",
+ "react": "^19.2.4",
+ "react-dom": "^19.2.4",
+ "truefoundry-gateway-sdk": "^0.4.0-rc.5"
+ },
+ "devDependencies": {
+ "@tailwindcss/vite": "^4.3.2",
+ "@types/react": "^19.2.17",
+ "@types/react-dom": "^19.2.3",
+ "@vitejs/plugin-react": "^4.7.0",
+ "tailwindcss": "^4.3.2",
+ "typescript": "^5.9.3",
+ "vite": "^6.3.5"
+ },
+ "resolutions": {
+ "@assistant-ui/core": "0.2.22",
+ "@assistant-ui/store": "0.2.21",
+ "@assistant-ui/tap": "0.9.5"
+ }
+}
diff --git a/packages/trueforge-ui-sdk/example/sample/full-page.png b/packages/trueforge-ui-sdk/example/sample/full-page.png
new file mode 100644
index 000000000..583521a9a
Binary files /dev/null and b/packages/trueforge-ui-sdk/example/sample/full-page.png differ
diff --git a/packages/trueforge-ui-sdk/example/sample/right-docked.png b/packages/trueforge-ui-sdk/example/sample/right-docked.png
new file mode 100644
index 000000000..246ffd69d
Binary files /dev/null and b/packages/trueforge-ui-sdk/example/sample/right-docked.png differ
diff --git a/packages/trueforge-ui-sdk/example/sample/widget.png b/packages/trueforge-ui-sdk/example/sample/widget.png
new file mode 100644
index 000000000..ae349551f
Binary files /dev/null and b/packages/trueforge-ui-sdk/example/sample/widget.png differ
diff --git a/packages/trueforge-ui-sdk/example/src/App.tsx b/packages/trueforge-ui-sdk/example/src/App.tsx
new file mode 100644
index 000000000..84f604a12
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/src/App.tsx
@@ -0,0 +1,58 @@
+import { TrueforgeUI } from '@truefoundry/trueforge-ui';
+
+function MissingEnv({ missing }: { missing: string[] }) {
+ return (
+ <div className="missing-env">
+ <h1>Missing environment variables</h1>
+ <p>
+ Copy <code>.env.example</code> to <code>.env</code> and set:
+ </p>
+ <ul>
+ {missing.map(name => (
+ <li key={name}>
+ <code>{name}</code>
+ </li>
+ ))}
+ </ul>
+ </div>
+ );
+}
+
+export default function App() {
+ const apiKey = import.meta.env.VITE_TFY_API_KEY?.trim() ?? '';
+ const controlPlaneURL = import.meta.env.VITE_TFY_CONTROL_PLANE_URL?.trim() ?? '';
+ const gatewayPlaneURL = import.meta.env.VITE_TFY_GATEWAY_URL?.trim() || undefined;
+
+ const missing = [!apiKey && 'VITE_TFY_API_KEY', !controlPlaneURL && 'VITE_TFY_CONTROL_PLANE_URL'].filter(
+ Boolean,
+ ) as string[];
+
+ if (missing.length > 0) {
+ return <MissingEnv missing={missing} />;
+ }
+
+ return (
+ <div className="flex h-dvh min-h-0 w-full flex-1 flex-col">
+ <TrueforgeUI
+ server={{
+ type: 'truefoundry',
+ apiKey,
+ controlPlaneURL,
+ ...(gatewayPlaneURL ? { gatewayPlaneURL } : {}),
+ }}
+ agentConfig={{ mode: 'AgentLibraryWithComposer' }}
+ theme={{
+ brand: {
+ icon: {
+ src: 'https://media.licdn.com/dms/image/v2/C560BAQGQ9Tfeof4MbA/company-logo_200_200/company-logo_200_200/0/1644494262340/truefoundry_logo?e=2147483647&v=beta&t=Xm6c1LGNbVPD2Ehtj21Z5OcuSCGLhYwlJ763oEYb92M',
+ alt: 'TrueFoundry',
+ },
+ name: 'TFY',
+ },
+ }}
+ layout="sidebar"
+ className="h-full min-h-0"
+ />
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/example/src/index.css b/packages/trueforge-ui-sdk/example/src/index.css
new file mode 100644
index 000000000..2afc86f40
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/src/index.css
@@ -0,0 +1,184 @@
+@import "tailwindcss";
+@import "@truefoundry/trueforge-ui/styles.css";
+
+*,
+*::before,
+*::after {
+ box-sizing: border-box;
+}
+
+html,
+body,
+#root {
+ height: 100%;
+ margin: 0;
+}
+
+body {
+ font-family: var(--font-agent-ui, ui-sans-serif, system-ui, sans-serif);
+ background: var(--background, #fff);
+}
+
+.dark body {
+ background: var(--background, #0a0a0a);
+}
+
+.missing-env {
+ display: flex;
+ flex-direction: column;
+ gap: 0.75rem;
+ max-width: 36rem;
+ margin: 4rem auto;
+ padding: 1.5rem;
+ font-family: ui-sans-serif, system-ui, sans-serif;
+ line-height: 1.5;
+}
+
+.missing-env code {
+ font-size: 0.875em;
+}
+
+.missing-env ul {
+ margin: 0;
+ padding-left: 1.25rem;
+}
+
+.app-shell {
+ display: flex;
+ flex-direction: column;
+ height: 100dvh;
+ min-height: 0;
+}
+
+.app-shell__body {
+ flex: 1;
+ min-height: 0;
+ position: relative;
+ display: flex;
+ flex-direction: column;
+}
+
+.app-shell__body > * {
+ flex: 1;
+ min-height: 0;
+ height: 100%;
+}
+
+.app-shell__toolbar {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 0.5rem;
+ padding: 0.5rem 0.75rem;
+ border-bottom: 1px solid var(--border, #e5e7eb);
+ background: var(--background, #fff);
+ flex-shrink: 0;
+}
+
+.layout-switcher {
+ display: flex;
+ gap: 0.25rem;
+}
+
+.layout-switcher__btn,
+.theme-toggle {
+ appearance: none;
+ border: 1px solid transparent;
+ border-radius: 0.375rem;
+ background: transparent;
+ color: var(--muted-foreground, #6b7280);
+ cursor: pointer;
+ font: inherit;
+ font-size: 0.8125rem;
+ font-weight: 500;
+ padding: 0.375rem 0.75rem;
+}
+
+.layout-switcher__btn:hover,
+.theme-toggle:hover {
+ background: var(--muted, #f3f4f6);
+ color: var(--foreground, #111827);
+}
+
+.layout-switcher__btn.is-active,
+.theme-toggle[aria-pressed="true"] {
+ background: var(--muted, #f3f4f6);
+ border-color: var(--border, #e5e7eb);
+ color: var(--foreground, #111827);
+}
+
+.fake-host {
+ flex: 1;
+ min-width: 0;
+ height: 100%;
+ padding: 2.5rem 2rem;
+ background:
+ radial-gradient(ellipse 80% 50% at 20% 0%, color-mix(in oklab, var(--primary, #4f46e5) 12%, transparent), transparent),
+ var(--muted, #f3f4f6);
+}
+
+.fake-host__eyebrow {
+ margin: 0 0 0.5rem;
+ font-size: 0.75rem;
+ font-weight: 600;
+ letter-spacing: 0.06em;
+ text-transform: uppercase;
+ color: var(--muted-foreground, #6b7280);
+}
+
+.fake-host__title {
+ margin: 0 0 0.75rem;
+ font-size: 1.75rem;
+ font-weight: 650;
+ letter-spacing: -0.02em;
+ color: var(--foreground, #111827);
+}
+
+.fake-host__body {
+ margin: 0;
+ max-width: 28rem;
+ font-size: 0.9375rem;
+ line-height: 1.55;
+ color: var(--muted-foreground, #6b7280);
+}
+
+.embed-host {
+ display: flex;
+ height: 100%;
+ min-height: 0;
+ min-width: 0;
+}
+
+.embed-host__chat {
+ width: min(400px, 100%);
+ min-width: 0;
+ min-height: 0;
+ position: relative;
+ flex-shrink: 0;
+}
+
+@media (max-width: 640px) {
+ .embed-host {
+ flex-direction: column;
+ }
+
+ .embed-host__chat {
+ width: 100%;
+ flex: 1;
+ }
+
+ .fake-host {
+ display: none;
+ }
+}
+
+.widget-host {
+ position: relative;
+ height: 100%;
+ min-height: 0;
+}
+
+.widget-host__overlay {
+ position: absolute;
+ inset: 0;
+}
diff --git a/packages/trueforge-ui-sdk/example/src/main.tsx b/packages/trueforge-ui-sdk/example/src/main.tsx
new file mode 100644
index 000000000..7c89905d8
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/src/main.tsx
@@ -0,0 +1,11 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+
+import App from './App';
+import './index.css';
+
+createRoot(document.getElementById('root')!).render(
+ <StrictMode>
+ <App />
+ </StrictMode>,
+);
diff --git a/packages/trueforge-ui-sdk/example/src/vite-env.d.ts b/packages/trueforge-ui-sdk/example/src/vite-env.d.ts
new file mode 100644
index 000000000..ea01ffd25
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/src/vite-env.d.ts
@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+ readonly VITE_TFY_API_KEY: string;
+ readonly VITE_TFY_CONTROL_PLANE_URL: string;
+ /** Optional — when omitted, TrueforgeUI resolves gateway from the control plane. */
+ readonly VITE_TFY_GATEWAY_URL?: string;
+ readonly VITE_TFY_AGENT_NAME: string;
+ readonly VITE_TFY_AGENT_MODE?: string;
+}
+
+interface ImportMeta {
+ readonly env: ImportMetaEnv;
+}
diff --git a/packages/trueforge-ui-sdk/example/tsconfig.app.json b/packages/trueforge-ui-sdk/example/tsconfig.app.json
new file mode 100644
index 000000000..b382d79f5
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/tsconfig.app.json
@@ -0,0 +1,23 @@
+{
+ "compilerOptions": {
+ "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+ "target": "ES2022",
+ "useDefineForClassFields": true,
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
+ "module": "ESNext",
+ "skipLibCheck": true,
+ "moduleResolution": "bundler",
+ "allowImportingTsExtensions": true,
+ "verbatimModuleSyntax": true,
+ "moduleDetection": "force",
+ "noEmit": true,
+ "jsx": "react-jsx",
+ "strict": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true,
+ "erasableSyntaxOnly": true,
+ "noFallthroughCasesInSwitch": true,
+ "noUncheckedSideEffectImports": true
+ },
+ "include": ["src"]
+}
diff --git a/packages/trueforge-ui-sdk/example/tsconfig.json b/packages/trueforge-ui-sdk/example/tsconfig.json
new file mode 100644
index 000000000..d32ff6820
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/tsconfig.json
@@ -0,0 +1,4 @@
+{
+ "files": [],
+ "references": [{ "path": "./tsconfig.app.json" }, { "path": "./tsconfig.node.json" }]
+}
diff --git a/packages/trueforge-ui-sdk/example/tsconfig.node.json b/packages/trueforge-ui-sdk/example/tsconfig.node.json
new file mode 100644
index 000000000..953116cc5
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/tsconfig.node.json
@@ -0,0 +1,21 @@
+{
+ "compilerOptions": {
+ "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+ "target": "ES2023",
+ "lib": ["ES2023"],
+ "module": "ESNext",
+ "skipLibCheck": true,
+ "moduleResolution": "bundler",
+ "allowImportingTsExtensions": true,
+ "verbatimModuleSyntax": true,
+ "moduleDetection": "force",
+ "noEmit": true,
+ "strict": true,
+ "noUnusedLocals": true,
+ "noUnusedParameters": true,
+ "erasableSyntaxOnly": true,
+ "noFallthroughCasesInSwitch": true,
+ "noUncheckedSideEffectImports": true
+ },
+ "include": ["vite.config.ts"]
+}
diff --git a/packages/trueforge-ui-sdk/example/vite.config.ts b/packages/trueforge-ui-sdk/example/vite.config.ts
new file mode 100644
index 000000000..fec3797c5
--- /dev/null
+++ b/packages/trueforge-ui-sdk/example/vite.config.ts
@@ -0,0 +1,24 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import tailwindcss from '@tailwindcss/vite';
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+const exampleRoot = path.dirname(fileURLToPath(import.meta.url));
+const sdkRoot = path.resolve(exampleRoot, '..');
+
+export default defineConfig({
+ plugins: [tailwindcss(), react()],
+ resolve: {
+ dedupe: ['react', 'react-dom', '@assistant-ui/core', '@assistant-ui/react', '@assistant-ui/store'],
+ },
+ optimizeDeps: {
+ exclude: ['@truefoundry/trueforge-ui'],
+ },
+ server: {
+ fs: {
+ allow: [sdkRoot, exampleRoot],
+ },
+ },
+});
diff --git a/packages/trueforge-ui-sdk/package.json b/packages/trueforge-ui-sdk/package.json
new file mode 100644
index 000000000..7ad7fd38a
--- /dev/null
+++ b/packages/trueforge-ui-sdk/package.json
@@ -0,0 +1,122 @@
+{
+ "name": "@truefoundry/trueforge-ui",
+ "version": "0.1.4",
+ "description": "TrueFoundry agent chat UI (atoms + containers) built on assistant-ui, with owned theming, presets, and swappable slots.",
+ "license": "Apache-2.0",
+ "repository": {
+ "type": "git",
+ "url": "git+https://github.com/truefoundry/harness.git",
+ "directory": "packages/trueforge-ui-sdk"
+ },
+ "homepage": "https://github.com/truefoundry/harness/tree/main/packages/trueforge-ui-sdk#readme",
+ "bugs": {
+ "url": "https://github.com/truefoundry/harness/issues"
+ },
+ "keywords": [
+ "truefoundry",
+ "assistant-ui",
+ "react",
+ "chat",
+ "agent"
+ ],
+ "publishConfig": {
+ "access": "public",
+ "provenance": false
+ },
+ "type": "module",
+ "exports": {
+ ".": {
+ "types": "./dist/index.d.ts",
+ "default": "./dist/index.js"
+ },
+ "./assistant-ui": {
+ "types": "./dist/assistant-ui.d.ts",
+ "default": "./dist/assistant-ui.js"
+ },
+ "./styles.css": "./dist/styles.css"
+ },
+ "main": "./dist/index.js",
+ "types": "./dist/index.d.ts",
+ "files": [
+ "dist",
+ "README.md",
+ "LICENSE",
+ "NOTICE",
+ "CHANGELOG.md"
+ ],
+ "sideEffects": [
+ "dist/styles.css",
+ "src/icons/registerAgentIcons.ts"
+ ],
+ "scripts": {
+ "build": "tsup && tailwindcss --input src/build-styles.css --output dist/styles.css --minify",
+ "dev:watch": "tsup --watch",
+ "pack:tgz": "pnpm build && pnpm pack",
+ "test": "vitest run",
+ "test:coverage": "vitest run --coverage",
+ "typecheck": "tsc --noEmit",
+ "lint": "eslint src --ext .ts,.tsx",
+ "format": "prettier --write \"src/**/*.{ts,tsx,css,md}\" \"*.md\" \"docs/**/*.md\""
+ },
+ "peerDependencies": {
+ "@assistant-ui/core": "^0.2.22",
+ "@assistant-ui/react": "^0.14.24",
+ "@types/react": "*",
+ "react": "^18 || ^19",
+ "react-dom": "^18 || ^19"
+ },
+ "peerDependenciesMeta": {
+ "@assistant-ui/core": {
+ "optional": true
+ },
+ "@assistant-ui/react": {
+ "optional": true
+ },
+ "@types/react": {
+ "optional": true
+ }
+ },
+ "dependencies": {
+ "@assistant-ui/core": "^0.2.22",
+ "@assistant-ui/react": "^0.14.24",
+ "@openuidev/react-headless": "^0.9.4",
+ "@openuidev/react-lang": "^0.2.9",
+ "@openuidev/react-ui": "^0.13.2",
+ "@truefoundry/assistant-ui-runtime": "^0.1.9",
+ "clsx": "^2.1.1",
+ "lucide-react": "^0.562.0",
+ "monaco-editor": "^0.56.0",
+ "react-markdown": "^10.1.0",
+ "react-syntax-highlighter": "^16.1.1",
+ "remark-gfm": "^4.0.1",
+ "tailwind-merge": "^3.6.0",
+ "truefoundry-gateway-sdk": "^0.4.0-rc.6",
+ "zod": "^4.4.3"
+ },
+ "devDependencies": {
+ "@eslint/js": "^9.39.0",
+ "@tailwindcss/cli": "^4.3.2",
+ "@testing-library/dom": "^10.0.0",
+ "@testing-library/jest-dom": "^6.6.3",
+ "@testing-library/react": "^16.3.2",
+ "@types/node": "^20",
+ "@types/react": "^19.2.17",
+ "@types/react-dom": "^19.2.0",
+ "@types/react-syntax-highlighter": "^15.5.13",
+ "@vitest/coverage-v8": "^4.1.10",
+ "esbuild-plugin-svgr": "3.1.1",
+ "eslint": "^9.39.0",
+ "eslint-plugin-react-hooks": "^7.0.0",
+ "github-markdown-css": "^5.9.0",
+ "globals": "^16.4.0",
+ "jsdom": "^24.1.3",
+ "prettier": "^3.6.2",
+ "react": "^19.2.4",
+ "react-dom": "^19.2.4",
+ "tailwindcss": "^4.3.2",
+ "tsup": "^8.5.0",
+ "typescript": "^5.9.3",
+ "typescript-eslint": "^8.46.0",
+ "vitest": "^4.1.9"
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/assistant-ui.ts b/packages/trueforge-ui-sdk/src/assistant-ui.ts
new file mode 100644
index 000000000..9bbcee7cc
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/assistant-ui.ts
@@ -0,0 +1,3 @@
+/** Curated assistant-ui chrome hooks for advanced hosts. Deep primitives stay on `@assistant-ui/react`. */
+export { useAui, useAuiState } from '@assistant-ui/react';
+export type { AssistantState } from '@assistant-ui/react';
diff --git a/packages/trueforge-ui-sdk/src/atoms/AgentsLibrary.test.tsx b/packages/trueforge-ui-sdk/src/atoms/AgentsLibrary.test.tsx
new file mode 100644
index 000000000..08187621c
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/AgentsLibrary.test.tsx
@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { ServerProvider } from '../server/ServerContext.js';
+import { ShellModeProvider } from '../server/ShellModeContext.js';
+import type { AgentUIServer } from '../server/types.js';
+import { SlotsProvider } from '../theme/SlotsProvider.js';
+import { AgentsLibrary } from './AgentsLibrary.js';
+import { AgentsLibraryButton } from './AgentsLibraryButton.js';
+import { CenteredModal } from './primitives/CenteredModal.js';
+
+beforeAll(() => {
+ // jsdom does not implement HTMLDialogElement showModal/close.
+ HTMLDialogElement.prototype.showModal = function showModal() {
+ this.setAttribute('open', '');
+ };
+ HTMLDialogElement.prototype.close = function close() {
+ this.removeAttribute('open');
+ this.dispatchEvent(new Event('close'));
+ };
+});
+
+function mockServer(agents: Array<{ name: string }> = [{ name: 'alpha-agent' }]): AgentUIServer {
+ return {
+ searchAgents: vi.fn(async () => agents),
+ } as unknown as AgentUIServer;
+}
+
+describe('CenteredModal', () => {
+ it('opens with desktop-centered and mobile bottom-sheet classes', () => {
+ render(
+ <CenteredModal open onOpenChange={() => undefined} title="Demo">
+ <p>body</p>
+ </CenteredModal>,
+ );
+
+ const dialog = screen.getByRole('dialog', { name: 'Demo' });
+ expect(dialog).toHaveAttribute('open');
+ expect(dialog.className).toContain('mt-auto');
+ expect(dialog.className).toContain('md:m-auto');
+ expect(dialog.className).toContain('rounded-t-xl');
+ expect(dialog.className).toContain('md:rounded-xl');
+ expect(dialog.className).toContain('md:max-w-5xl');
+ expect(screen.getByText('body')).toBeInTheDocument();
+ });
+
+ it('closes via the close button', () => {
+ const onOpenChange = vi.fn();
+ render(
+ <CenteredModal open onOpenChange={onOpenChange} title="Demo">
+ <p>body</p>
+ </CenteredModal>,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'Close' }));
+ expect(onOpenChange).toHaveBeenCalledWith(false);
+ });
+});
+
+describe('AgentsLibrary', () => {
+ it('lists agents and selects a named agent', async () => {
+ const server = mockServer([{ name: 'alpha-agent' }, { name: '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>,
+ );
+
+ expect(screen.getByRole('dialog', { 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');
+ });
+});
+
+describe('AgentsLibraryButton', () => {
+ it('opens the Agents Library dialog from the trigger', async () => {
+ const server = mockServer([{ name: 'alpha-agent' }]);
+
+ render(
+ <SlotsProvider>
+ <ServerProvider server={server}>
+ <ShellModeProvider>
+ <AgentsLibraryButton />
+ </ShellModeProvider>
+ </ServerProvider>
+ </SlotsProvider>,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: /Agents Library/ }));
+ expect(screen.getByRole('dialog', { name: 'Agents Library' })).toBeInTheDocument();
+ await waitFor(() => {
+ expect(screen.getByRole('button', { name: 'Try agent alpha-agent' })).toBeInTheDocument();
+ });
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/atoms/AgentsLibrary.tsx b/packages/trueforge-ui-sdk/src/atoms/AgentsLibrary.tsx
new file mode 100644
index 000000000..f902396d3
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/AgentsLibrary.tsx
@@ -0,0 +1,145 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { Icon } from '../icons/Icon.js';
+import { useOptionalServer } from '../server/ServerContext.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import type { AgentLibraryEntry } from '../server/types.js';
+import { auiButtonClass } from './lib/buttonClasses.js';
+import { cn } from './lib/cn.js';
+import { useCompactLayout } from './lib/CompactLayoutContext.js';
+import { CenteredModal } from './primitives/CenteredModal.js';
+import { Skeleton } from './primitives/Skeleton.js';
+
+export type AgentsLibraryProps = {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ onSelectAgent?: (agentName: string) => void;
+};
+
+function AgentLibraryRow({ agent, onSelect }: { agent: AgentLibraryEntry; onSelect: () => void }) {
+ const compact = useCompactLayout();
+
+ return (
+ <div
+ role="menuitem"
+ className={cn(
+ 'group 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-accent',
+ 'focus-within:border-border focus-within:bg-accent',
+ )}
+ >
+ <span className="bg-background text-muted-foreground inline-flex size-8 shrink-0 items-center justify-center rounded-md border border-border">
+ <Icon name="robot" className="size-4" />
+ </span>
+ <span className="text-foreground min-w-0 flex-1 truncate text-left text-sm font-medium leading-tight">
+ {agent.name}
+ </span>
+ <button
+ type="button"
+ aria-label={`Try agent ${agent.name}`}
+ className={auiButtonClass({
+ variant: 'outline',
+ size: 'sm',
+ className: cn(
+ 'shrink-0 opacity-100 transition-opacity',
+ !compact && 'md:opacity-0 md:group-hover:opacity-100 md:group-focus-within:opacity-100',
+ 'focus-visible:opacity-100',
+ ),
+ })}
+ onClick={onSelect}
+ >
+ Try Agent
+ </button>
+ </div>
+ );
+}
+
+export function AgentsLibrary({ open, onOpenChange, onSelectAgent }: AgentsLibraryProps) {
+ const server = useOptionalServer();
+ const shell = useOptionalShellMode();
+ const [query, setQuery] = useState('');
+ const [agents, setAgents] = useState<AgentLibraryEntry[]>([]);
+ const [loading, setLoading] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+
+ useEffect(() => {
+ if (!open) {
+ setQuery('');
+ return;
+ }
+ if (!server) return;
+ let cancelled = false;
+ setLoading(true);
+ setError(null);
+ void server
+ .searchAgents({ query: query.trim() || undefined, limit: 50 })
+ .then(rows => {
+ if (!cancelled) setAgents(rows);
+ })
+ .catch((err: unknown) => {
+ if (!cancelled) {
+ setError(err instanceof Error ? err.message : 'Failed to load agents.');
+ setAgents([]);
+ }
+ })
+ .finally(() => {
+ if (!cancelled) setLoading(false);
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [open, query, server]);
+
+ const handleSelect = (name: string) => {
+ onOpenChange(false);
+ setQuery('');
+ onSelectAgent?.(name);
+ shell?.selectAgent(name);
+ };
+
+ return (
+ <CenteredModal open={open} onOpenChange={onOpenChange} title="Agents Library">
+ {/*
+ Single-pane layout modeled on the MCP tools modal's left column
+ (search + icon rows). Detail columns need fields beyond AgentLibraryEntry.
+ */}
+ <div className="bg-muted/40 flex min-h-0 flex-1 flex-col">
+ <div className="shrink-0 border-b border-border px-4 py-3">
+ <label className="relative block">
+ <Icon
+ name="search"
+ className="text-muted-foreground pointer-events-none absolute top-1/2 left-2.5 size-3.5 -translate-y-1/2"
+ />
+ <input
+ type="search"
+ value={query}
+ onChange={e => setQuery(e.target.value)}
+ placeholder="Search agents"
+ className="border-input bg-background placeholder:text-muted-foreground h-9 w-full rounded-md border py-1 pr-3 pl-8 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring/40"
+ autoFocus
+ />
+ </label>
+ </div>
+ <div className="flex min-h-0 flex-1 flex-col gap-0.5 overflow-y-auto p-2" role="menu" aria-label="Agents">
+ {loading ? (
+ <div className="flex flex-col gap-2 p-1" role="status" aria-label="Loading agents">
+ {Array.from({ length: 6 }, (_, i) => (
+ <Skeleton key={i} className="h-11 w-full rounded-md" />
+ ))}
+ </div>
+ ) : error ? (
+ <p className="text-destructive px-3 py-8 text-center text-sm">{error}</p>
+ ) : agents.length === 0 ? (
+ <p className="text-muted-foreground px-3 py-8 text-center text-sm">No agents found</p>
+ ) : (
+ agents.map(agent => (
+ <AgentLibraryRow key={agent.name} agent={agent} onSelect={() => handleSelect(agent.name)} />
+ ))
+ )}
+ </div>
+ </div>
+ </CenteredModal>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/AgentsLibraryButton.tsx b/packages/trueforge-ui-sdk/src/atoms/AgentsLibraryButton.tsx
new file mode 100644
index 000000000..ad12c9ec4
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/AgentsLibraryButton.tsx
@@ -0,0 +1,82 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { Icon } from '../icons/Icon.js';
+import { useOptionalServer } from '../server/ServerContext.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import { AgentsLibrary } from './AgentsLibrary.js';
+import { auiButtonClass } from './lib/buttonClasses.js';
+import { cn } from './lib/cn.js';
+
+export type AgentsLibraryButtonProps = {
+ className?: string;
+ compact?: boolean;
+ onSelectAgent?: (agentName: string) => void;
+};
+
+export function AgentsLibraryButton({ className, compact = false, onSelectAgent }: AgentsLibraryButtonProps) {
+ const server = useOptionalServer();
+ const shell = useOptionalShellMode();
+ const [open, setOpen] = useState(false);
+ const [count, setCount] = useState<number | null>(null);
+
+ const enabled = shell?.isLibraryEnabled === true && server != null;
+
+ useEffect(() => {
+ if (!enabled || !server) return;
+ let cancelled = false;
+ void server
+ .searchAgents({ limit: 50 })
+ .then(rows => {
+ if (!cancelled) setCount(rows.length);
+ })
+ .catch(() => undefined);
+ return () => {
+ cancelled = true;
+ };
+ }, [enabled, server]);
+
+ 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-foreground shadow-none hover:bg-accent hover:text-accent-foreground',
+ compact ? 'w-8 !justify-center p-0' : 'w-full !justify-start px-2.5',
+ open && 'bg-accent text-accent-foreground',
+ ),
+ })}
+ onClick={() => setOpen(true)}
+ >
+ <Icon name="robot" />
+ {!compact ? (
+ <>
+ <span className="truncate">
+ Agents Library
+ {count != null ? <span className="text-muted-foreground"> ({count})</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} />
+ </>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentsLibraryButton: typeof AgentsLibraryButton;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/AssistantMessageBubble.tsx b/packages/trueforge-ui-sdk/src/atoms/AssistantMessageBubble.tsx
new file mode 100644
index 000000000..5e588ae29
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/AssistantMessageBubble.tsx
@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react';
+
+import { cn } from './lib/cn.js';
+
+export type AssistantMessageBubbleProps = {
+ children: ReactNode;
+ error?: ReactNode;
+ actionBar?: ReactNode;
+ className?: string;
+};
+
+export function AssistantMessageBubble({ children, error, actionBar, className }: AssistantMessageBubbleProps) {
+ return (
+ <div
+ data-slot="aui_assistant-message-root"
+ className={cn('group/assistant relative min-w-0 max-w-full', className)}
+ >
+ <div className="min-w-0 max-w-full">
+ {children}
+ {error && <div className="mt-2 text-sm text-destructive">{error}</div>}
+ </div>
+ {actionBar && <div className="mt-1">{actionBar}</div>}
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AssistantMessageBubble: typeof AssistantMessageBubble;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/AttachmentCard.tsx b/packages/trueforge-ui-sdk/src/atoms/AttachmentCard.tsx
new file mode 100644
index 000000000..e518cebbd
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/AttachmentCard.tsx
@@ -0,0 +1,93 @@
+'use client';
+
+import { USER_MESSAGE_ATTACHMENT_PREVIEW_REM } from '../constants/attachments.js';
+import { Icon } from '../icons/Icon.js';
+import { auiButtonClass } from './lib/buttonClasses.js';
+import { cn } from './lib/cn.js';
+import { Avatar, AvatarFallback, AvatarImage } from './primitives/Avatar.js';
+
+export { USER_MESSAGE_ATTACHMENT_PREVIEW_REM };
+
+export type AttachmentCardSize = 'chip' | 'preview';
+
+export type AttachmentCardProps = {
+ name: string;
+ contentType?: string;
+ previewSrc?: string;
+ isImage?: boolean;
+ size?: AttachmentCardSize;
+ /** When set, constrains image preview and file chip width to this rem size. */
+ previewRem?: number;
+ onRemove?: () => void;
+ className?: string;
+};
+
+export function AttachmentCard({
+ name,
+ previewSrc,
+ isImage = false,
+ size = 'chip',
+ previewRem,
+ onRemove,
+ className,
+}: AttachmentCardProps) {
+ if (size === 'preview' && isImage && previewSrc) {
+ const previewSize = previewRem != null ? { width: `${previewRem}rem`, height: `${previewRem}rem` } : undefined;
+
+ return (
+ <div
+ data-slot="aui_attachment-preview"
+ style={previewSize}
+ className={cn(
+ 'aui-attachment-preview relative shrink-0 cursor-pointer overflow-hidden rounded-lg border',
+ previewRem == null && 'size-24',
+ className,
+ )}
+ >
+ <img src={previewSrc} alt={name} className="h-full w-full object-cover" />
+ </div>
+ );
+ }
+
+ return (
+ <div
+ data-slot="aui_attachment-chip"
+ style={previewRem != null ? { maxWidth: `${previewRem}rem` } : undefined}
+ className={cn(
+ 'aui-attachment-chip bg-muted flex max-w-full shrink-0 items-center gap-2 rounded-lg border px-2 py-1.5',
+ className,
+ )}
+ >
+ <div className="bg-background flex size-7 shrink-0 items-center justify-center overflow-hidden rounded-md border">
+ {isImage && previewSrc ? (
+ <Avatar className="size-7 rounded-none">
+ <AvatarImage src={previewSrc} alt={name} className="object-cover" />
+ <AvatarFallback>
+ <Icon name="file" size="1rem" className="text-muted-foreground" />
+ </AvatarFallback>
+ </Avatar>
+ ) : (
+ <Icon name="file" size="1rem" className="text-muted-foreground" />
+ )}
+ </div>
+ <span className="text-foreground min-w-0 truncate text-sm">{name}</span>
+ {onRemove && (
+ <button
+ type="button"
+ aria-label="Remove file"
+ title="Remove file"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon', className: 'size-6 shrink-0 rounded-full' })}
+ onClick={onRemove}
+ >
+ <Icon name="xmark" />
+ </button>
+ )}
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AttachmentCard: typeof AttachmentCard;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/AttachmentPickerButton.tsx b/packages/trueforge-ui-sdk/src/atoms/AttachmentPickerButton.tsx
new file mode 100644
index 000000000..3d9b3ccd9
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/AttachmentPickerButton.tsx
@@ -0,0 +1,30 @@
+import type { ComponentProps } from 'react';
+
+import { Icon } from '../icons/Icon.js';
+import { auiButtonClass } from './lib/buttonClasses.js';
+
+export type AttachmentPickerButtonProps = Omit<ComponentProps<'button'>, 'children' | 'aria-label'>;
+
+export function AttachmentPickerButton({ className, ...props }: AttachmentPickerButtonProps) {
+ return (
+ <button
+ type="button"
+ aria-label="Add Attachment"
+ title="Add Attachment"
+ className={auiButtonClass({
+ variant: 'ghost',
+ size: 'icon',
+ className: `size-7 rounded-full p-1 ${className ?? ''}`,
+ })}
+ {...props}
+ >
+ <Icon name="paperclip" />
+ </button>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AttachmentPickerButton: typeof AttachmentPickerButton;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/AttachmentPreviewDialog.tsx b/packages/trueforge-ui-sdk/src/atoms/AttachmentPreviewDialog.tsx
new file mode 100644
index 000000000..a884eb7ef
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/AttachmentPreviewDialog.tsx
@@ -0,0 +1,65 @@
+'use client';
+
+import type { ReactNode } from 'react';
+import { useState } from 'react';
+
+import { Icon } from '../icons/Icon.js';
+import { auiButtonClass } from './lib/buttonClasses.js';
+import { Dialog, DialogContent } from './primitives/Dialog.js';
+
+export type AttachmentPreviewDialogProps = {
+ previewSrc?: string;
+ children: ReactNode;
+};
+
+export function AttachmentPreviewDialog({ previewSrc, children }: AttachmentPreviewDialogProps) {
+ const [open, setOpen] = useState(false);
+
+ if (!previewSrc) return <>{children}</>;
+
+ return (
+ <>
+ <button
+ type="button"
+ aria-label="Open attachment preview"
+ onClick={() => setOpen(true)}
+ className="block max-w-full cursor-pointer border-0 bg-transparent p-0 text-left"
+ >
+ {children}
+ </button>
+ <Dialog
+ open={open}
+ onOpenChange={setOpen}
+ aria-label="Attachment preview"
+ className="max-w-[calc(100%-2rem)] sm:max-w-3xl"
+ >
+ <DialogContent className="relative p-2">
+ <span className="absolute top-2 right-2 z-10 inline-flex">
+ <button
+ type="button"
+ aria-label="Close"
+ title="Close"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={() => setOpen(false)}
+ >
+ <Icon name="xmark" />
+ </button>
+ </span>
+ <div className="bg-background relative mx-auto flex max-h-[80dvh] w-full items-center justify-center overflow-hidden">
+ <img
+ src={previewSrc}
+ alt="Attachment preview"
+ className="block h-auto max-h-[80vh] w-auto max-w-full object-contain"
+ />
+ </div>
+ </DialogContent>
+ </Dialog>
+ </>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AttachmentPreviewDialog: typeof AttachmentPreviewDialog;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ChatFileDownload.tsx b/packages/trueforge-ui-sdk/src/atoms/ChatFileDownload.tsx
new file mode 100644
index 000000000..212e7d69a
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ChatFileDownload.tsx
@@ -0,0 +1,95 @@
+'use client';
+
+import { useState, type MouseEvent } from 'react';
+
+import { Icon } from '../icons/Icon.js';
+import { cn } from './lib/cn.js';
+import { Spinner } from './primitives/Spinner.js';
+
+export type ChatFileDownloadFile = {
+ name: string;
+ path: string;
+};
+
+export type ChatFileDownloadProps = {
+ files: ChatFileDownloadFile[];
+ fileDownloadBaseUrl?: string;
+ onDownloadArtifact?: (path: string, filename: string) => Promise<void>;
+ readOnly?: boolean;
+};
+
+export function ChatFileDownload({ files, fileDownloadBaseUrl, onDownloadArtifact, readOnly }: ChatFileDownloadProps) {
+ const [downloadingPath, setDownloadingPath] = useState<string | null>(null);
+
+ return (
+ <details
+ open
+ className="aui-sandbox-artifacts group my-2 overflow-hidden rounded-lg border border-primary/20 bg-card"
+ data-testid="aui-sandbox-artifacts"
+ >
+ <summary className="flex min-h-9 cursor-pointer list-none items-center gap-2 bg-primary/5 px-3 py-2 text-xs font-medium leading-none text-primary [&::-webkit-details-marker]:hidden">
+ <Icon name="chevron-down" size={13} className="shrink-0 transition-transform group-open:rotate-180" />
+ <Icon name="file" size={16} className="shrink-0" />
+ <span className="leading-none">
+ {files.length} {files.length === 1 ? 'file' : 'files'} generated
+ </span>
+ </summary>
+
+ <div className="flex flex-wrap items-center gap-y-1 px-3 py-2">
+ {files.map(({ name, path }) => {
+ if (readOnly) {
+ return (
+ <span
+ key={path}
+ className="mr-3 inline-flex min-h-7 items-center gap-1.5 border-r border-border pr-3 text-xs text-muted-foreground last:mr-0 last:border-r-0 last:pr-0"
+ >
+ <Icon name="file" size={14} className="shrink-0" />
+ <span className="leading-none">{name}</span>
+ </span>
+ );
+ }
+
+ const href = fileDownloadBaseUrl ? `${fileDownloadBaseUrl}${path}` : undefined;
+ const canDownload = Boolean(onDownloadArtifact || href);
+ const isDownloading = downloadingPath === path;
+
+ const handleClick = (event: MouseEvent) => {
+ if (!onDownloadArtifact || isDownloading) {
+ event.preventDefault();
+ return;
+ }
+ event.preventDefault();
+ setDownloadingPath(path);
+ void onDownloadArtifact(path, name).finally(() => {
+ setDownloadingPath(current => (current === path ? null : current));
+ });
+ };
+
+ return (
+ <a
+ key={path}
+ href={canDownload ? (href ?? '#') : undefined}
+ onClick={onDownloadArtifact ? handleClick : undefined}
+ aria-busy={isDownloading || undefined}
+ className={cn(
+ 'mr-3 inline-flex min-h-7 items-center gap-1.5 border-r border-border pr-3 text-xs text-foreground last:mr-0 last:border-r-0 last:pr-0',
+ canDownload && !isDownloading && 'cursor-pointer hover:text-primary',
+ (isDownloading || !canDownload) && 'pointer-events-none opacity-60',
+ )}
+ download={name}
+ aria-label={isDownloading ? `Downloading ${name}` : `Download ${name}`}
+ >
+ <Icon name="file" size={14} className="shrink-0 text-muted-foreground" />
+ <span className="leading-none">{name}</span>
+ {isDownloading ? (
+ <Spinner size={14} className="shrink-0 text-primary" />
+ ) : (
+ <Icon name="download" size={14} className="shrink-0 text-primary" />
+ )}
+ </a>
+ );
+ })}
+ </div>
+ </details>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ClearChatButton.test.tsx b/packages/trueforge-ui-sdk/src/atoms/ClearChatButton.test.tsx
new file mode 100644
index 000000000..65191526d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ClearChatButton.test.tsx
@@ -0,0 +1,67 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ServerProvider } from '../server/ServerContext.js';
+import { ShellModeProvider } from '../server/ShellModeContext.js';
+import type { AgentUIServer } from '../server/types.js';
+import { SlotsProvider } from '../theme/SlotsProvider.js';
+import { ClearChatButton } from './ClearChatButton.js';
+import { SelectAgentEmptyState } from './SelectAgentEmptyState.js';
+
+function mockServer(): AgentUIServer {
+ return {
+ searchAgents: vi.fn(async () => [{ name: 'alpha' }]),
+ } as unknown as AgentUIServer;
+}
+
+describe('ClearChatButton', () => {
+ it('is hidden while idle', () => {
+ render(
+ <SlotsProvider>
+ <ShellModeProvider agentConfig={{ mode: 'AgentLibrary' }}>
+ <ClearChatButton />
+ </ShellModeProvider>
+ </SlotsProvider>,
+ );
+ expect(screen.queryByRole('button', { name: 'Clear chat' })).not.toBeInTheDocument();
+ });
+
+ it('calls clearChat when clicked in named mode', () => {
+ render(
+ <SlotsProvider>
+ <ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: 'a' }}>
+ <ClearChatButton />
+ </ShellModeProvider>
+ </SlotsProvider>,
+ );
+ expect(screen.getByRole('button', { name: 'Clear chat' })).toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'Clear chat' }));
+ });
+});
+
+describe('SelectAgentEmptyState', () => {
+ it('renders CTA when idle', () => {
+ render(
+ <SlotsProvider>
+ <ServerProvider server={mockServer()}>
+ <ShellModeProvider agentConfig={{ mode: 'AgentLibrary' }}>
+ <SelectAgentEmptyState />
+ </ShellModeProvider>
+ </ServerProvider>
+ </SlotsProvider>,
+ );
+ expect(screen.getByText('Select an agent to start chatting')).toBeInTheDocument();
+ });
+
+ it('renders nothing when not idle', () => {
+ render(
+ <SlotsProvider>
+ <ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: 'a' }}>
+ <SelectAgentEmptyState />
+ </ShellModeProvider>
+ </SlotsProvider>,
+ );
+ expect(screen.queryByText('Select an agent to start chatting')).not.toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/atoms/ClearChatButton.tsx b/packages/trueforge-ui-sdk/src/atoms/ClearChatButton.tsx
new file mode 100644
index 000000000..609ff4e51
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ClearChatButton.tsx
@@ -0,0 +1,30 @@
+'use client';
+
+import { Icon } from '../icons/Icon.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import { auiButtonClass } from './lib/buttonClasses.js';
+
+/** Resets the current named or draft chat. Hidden while the shell is idle. */
+export function ClearChatButton() {
+ const shell = useOptionalShellMode();
+
+ if (shell == null || shell.mode.type === 'idle') return null;
+
+ return (
+ <button
+ type="button"
+ aria-label="Clear chat"
+ title="Clear chat"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={() => shell.clearChat()}
+ >
+ <Icon name="rotate-right" />
+ </button>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ ClearChatButton: typeof ClearChatButton;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/CodeEditor.tsx b/packages/trueforge-ui-sdk/src/atoms/CodeEditor.tsx
new file mode 100644
index 000000000..8aec7c61d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/CodeEditor.tsx
@@ -0,0 +1,131 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+
+import { Icon } from '../icons/Icon.js';
+import { cn } from './lib/cn.js';
+import { MonacoEditorCore, type MonacoEditorCoreProps } from './MonacoEditorCore.js';
+
+export type CodeEditorProps = Omit<MonacoEditorCoreProps, 'options'> & {
+ filename?: string;
+ showToolbar?: boolean;
+};
+
+function ToolbarButton({
+ onClick,
+ tooltip,
+ icon,
+ active,
+}: {
+ onClick: () => void;
+ tooltip: string;
+ icon: string;
+ active?: boolean;
+}) {
+ return (
+ <button
+ type="button"
+ onClick={onClick}
+ title={tooltip}
+ className={cn(
+ 'flex cursor-pointer items-center justify-center rounded p-1.5 text-xs transition-colors',
+ 'hover:bg-muted text-muted-foreground hover:text-foreground',
+ active && 'bg-muted text-foreground',
+ )}
+ aria-label={tooltip}
+ >
+ <Icon name={icon} size="0.875em" />
+ </button>
+ );
+}
+
+export function CodeEditor({
+ value,
+ language,
+ theme,
+ filename,
+ onChange,
+ onMount,
+ beforeMount,
+ className,
+ height,
+ showToolbar = true,
+}: CodeEditorProps) {
+ const [showLineNumbers, setShowLineNumbers] = useState(false);
+ const [expanded, setExpanded] = useState(false);
+ const [copied, setCopied] = useState(false);
+
+ const handleCopy = useCallback(() => {
+ void navigator.clipboard.writeText(value).then(() => {
+ setCopied(true);
+ setTimeout(() => setCopied(false), 2000);
+ });
+ }, [value]);
+
+ const handleDownload = useCallback(() => {
+ const blob = new Blob([value], { type: 'text/plain' });
+ const url = URL.createObjectURL(blob);
+ const a = document.createElement('a');
+ a.href = url;
+ a.download = filename ?? `code.${language ?? 'txt'}`;
+ a.click();
+ URL.revokeObjectURL(url);
+ }, [value, filename, language]);
+
+ const editorOptions = {
+ lineNumbers: showLineNumbers ? 'on' : ('off' as const),
+ minimap: { enabled: false },
+ scrollBeyondLastLine: false,
+ wordWrap: 'on' as const,
+ };
+
+ const editorHeight = expanded ? '100%' : (height ?? 320);
+
+ return (
+ <div
+ className={cn(
+ 'aui-code-editor flex flex-col overflow-hidden rounded-md border border-border',
+ expanded && 'fixed inset-4 z-50 bg-background shadow-2xl',
+ className,
+ )}
+ >
+ {showToolbar && (
+ <div className="flex items-center justify-between gap-1 border-b border-border px-2 py-1">
+ {filename && <span className="truncate text-xs text-muted-foreground">{filename}</span>}
+ <div className="ml-auto flex items-center gap-0.5">
+ <ToolbarButton
+ onClick={() => setShowLineNumbers(v => !v)}
+ tooltip={showLineNumbers ? 'Hide line numbers' : 'Show line numbers'}
+ icon="list-ol"
+ active={showLineNumbers}
+ />
+ <ToolbarButton
+ onClick={handleCopy}
+ tooltip={copied ? 'Copied!' : 'Copy'}
+ icon={copied ? 'check' : 'copy'}
+ />
+ <ToolbarButton onClick={handleDownload} tooltip="Download" icon="download" />
+ <ToolbarButton
+ onClick={() => setExpanded(v => !v)}
+ tooltip={expanded ? 'Collapse' : 'Expand'}
+ icon={expanded ? 'compress' : 'expand'}
+ />
+ </div>
+ </div>
+ )}
+
+ <div className="flex-1 overflow-hidden" style={expanded ? undefined : { height: editorHeight }}>
+ <MonacoEditorCore
+ value={value}
+ language={language}
+ theme={theme}
+ options={editorOptions}
+ onChange={onChange}
+ onMount={onMount}
+ beforeMount={beforeMount}
+ height="100%"
+ />
+ </div>
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ComposerSections.tsx b/packages/trueforge-ui-sdk/src/atoms/ComposerSections.tsx
new file mode 100644
index 000000000..2df32378c
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ComposerSections.tsx
@@ -0,0 +1,74 @@
+'use client';
+
+import { Spinner } from '../atoms/primitives/Spinner.js';
+import { Icon } from '../icons/Icon.js';
+import { auiButtonClass } from './lib/buttonClasses.js';
+
+export type ComposerLeftSectionProps = {
+ disabled: boolean;
+ isRunning: boolean;
+ onAttach?: () => void;
+};
+
+export type ComposerRightSectionProps = {
+ disabled: boolean;
+ isRunning: boolean;
+};
+
+export type ComposerSendButtonProps = {
+ disabled: boolean;
+ canSubmit: boolean;
+ isRunning: boolean;
+ onSubmit: () => void;
+ onCancel?: () => void;
+};
+
+export function ComposerLeftSection({ onAttach }: ComposerLeftSectionProps) {
+ if (!onAttach) return null;
+
+ return (
+ <button
+ type="button"
+ aria-label="Attach"
+ title="Attach"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={onAttach}
+ >
+ <Icon name="paperclip" />
+ </button>
+ );
+}
+
+export function ComposerRightSection(_: ComposerRightSectionProps) {
+ return null;
+}
+
+export function ComposerSendButton({ canSubmit, isRunning, onSubmit, onCancel }: ComposerSendButtonProps) {
+ if (isRunning) {
+ return (
+ <button
+ type="button"
+ className={auiButtonClass({ size: 'sm' })}
+ disabled={!onCancel}
+ onClick={onCancel}
+ aria-label="Cancel"
+ >
+ <Spinner size={14} />
+ Cancel
+ </button>
+ );
+ }
+
+ return (
+ <button
+ type="button"
+ className={auiButtonClass({ size: 'icon' })}
+ disabled={!canSubmit}
+ onClick={onSubmit}
+ title="Send message"
+ aria-label="Send message"
+ >
+ <Icon name="arrow-up" />
+ </button>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ComposerShell.tsx b/packages/trueforge-ui-sdk/src/atoms/ComposerShell.tsx
new file mode 100644
index 000000000..8159d56d0
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ComposerShell.tsx
@@ -0,0 +1,84 @@
+'use client';
+
+import { type ReactNode } from 'react';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+import { cn } from './lib/cn.js';
+
+export type ComposerShellProps = {
+ /** Message input node, supplied by the container (e.g. `<ComposerPrimitive.Input />`). */
+ input: ReactNode;
+ disabled: boolean;
+ canSubmit: boolean;
+ isRunning?: boolean;
+ attachments?: ReactNode;
+ modelLabel?: string;
+ modelIcon?: ReactNode;
+ connectorStatusLabel?: string;
+ onSubmit: () => void;
+ onCancel?: () => void;
+ onAttach?: () => void;
+ className?: string;
+};
+
+export function ComposerShell({
+ input,
+ disabled,
+ canSubmit,
+ isRunning = false,
+ attachments,
+ modelLabel,
+ modelIcon,
+ connectorStatusLabel,
+ onSubmit,
+ onCancel,
+ onAttach,
+ className,
+}: ComposerShellProps) {
+ const ComposerLeftSection = useSlot('ComposerLeftSection');
+ const ComposerRightSection = useSlot('ComposerRightSection');
+ const ComposerSendButton = useSlot('ComposerSendButton');
+
+ return (
+ <div
+ data-slot="aui_composer-shell"
+ className={cn(
+ 'border-border/60 focus-within:border-ring focus-within:ring-ring/20 flex w-full flex-col gap-2 rounded-[var(--composer-radius,1.5rem)] border bg-[var(--composer-bg,var(--muted))] p-[var(--composer-padding,8px)] shadow-sm transition-colors focus-within:ring-3',
+ className,
+ )}
+ >
+ {attachments}
+ {input}
+ <div className="flex min-w-0 flex-wrap items-center justify-between gap-2 px-1">
+ <div className="flex min-w-0 max-w-full flex-wrap items-center gap-2">
+ <ComposerLeftSection disabled={disabled} isRunning={isRunning} onAttach={onAttach} />
+ {connectorStatusLabel && (
+ <span className="text-muted-foreground max-w-[12rem] truncate text-xs">{connectorStatusLabel}</span>
+ )}
+ </div>
+ <div className="ml-auto flex min-w-0 shrink-0 flex-wrap items-center justify-end gap-2">
+ {modelLabel && (
+ <span className="bg-muted text-muted-foreground flex max-w-[10rem] items-center gap-1 truncate rounded-full px-2 py-0.5 text-xs">
+ {modelIcon}
+ <span className="truncate">{modelLabel}</span>
+ </span>
+ )}
+ <ComposerRightSection disabled={disabled} isRunning={isRunning} />
+ <ComposerSendButton
+ disabled={disabled}
+ canSubmit={canSubmit}
+ isRunning={isRunning}
+ onSubmit={onSubmit}
+ onCancel={onCancel}
+ />
+ </div>
+ </div>
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ ComposerShell: typeof ComposerShell;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/HistoryLoader.tsx b/packages/trueforge-ui-sdk/src/atoms/HistoryLoader.tsx
new file mode 100644
index 000000000..194eb97d6
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/HistoryLoader.tsx
@@ -0,0 +1,37 @@
+import { forwardRef, type ComponentPropsWithRef } from 'react';
+
+import { cn } from './lib/cn.js';
+import { Spinner } from './primitives/Spinner.js';
+
+export type HistoryLoaderProps = ComponentPropsWithRef<'div'> & {
+ /** True while an older-history page is being fetched. */
+ isLoading?: boolean;
+};
+
+/**
+ * Inline status row shown at the top of the message list when older history
+ * pages are available. Doubles as the scroll sentinel observed by
+ * `HistoryLoaderContainer`.
+ */
+export const HistoryLoader = forwardRef<HTMLDivElement, HistoryLoaderProps>(
+ ({ className, isLoading = false, ...rest }, ref) => (
+ <div
+ ref={ref}
+ data-slot="aui_history-loader"
+ role="status"
+ aria-live="polite"
+ aria-label={isLoading ? 'Loading older messages' : 'Scroll up to load older messages'}
+ className={cn('flex justify-center py-2', className)}
+ {...rest}
+ >
+ {isLoading && <Spinner size={14} />}
+ </div>
+ ),
+);
+HistoryLoader.displayName = 'HistoryLoader';
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ HistoryLoader: typeof HistoryLoader;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/Markdown.test.tsx b/packages/trueforge-ui-sdk/src/atoms/Markdown.test.tsx
new file mode 100644
index 000000000..9dc2e2b1d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/Markdown.test.tsx
@@ -0,0 +1,32 @@
+// @vitest-environment jsdom
+import { render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { Markdown } from './Markdown.js';
+
+// @openuidev mocks are in testSetup.ts; they make OpenUiFenceBlock render
+// a simple div with data-testid="aui-openui-renderer" synchronously.
+
+describe('Markdown', () => {
+ it('renders basic markdown formatting', () => {
+ render(<Markdown content="**bold** text" />);
+ const strong = screen.getByText('bold');
+ expect(strong.tagName).toBe('STRONG');
+ expect(strong.closest('.markdown-body')).toBeTruthy();
+ });
+
+ it('renders openui fenced blocks via OpenUiFenceBlock', async () => {
+ render(<Markdown content={'```openui\nCard() { title: "Sales" }\n```'} />);
+ await waitFor(() => {
+ expect(screen.getByTestId('aui-openui-renderer')).toBeInTheDocument();
+ });
+ expect(screen.getByTestId('aui-openui-renderer')).toHaveTextContent('Card() { title: "Sales" }');
+ expect(document.querySelector('.code-block-header')).not.toBeInTheDocument();
+ });
+
+ it('renders a code fence with syntax highlighting for non-openui languages', () => {
+ render(<Markdown content={'```js\nconst x = 1;\n```'} />);
+ // react-syntax-highlighter renders the code as text nodes inside the fence block.
+ expect(screen.getByText(/const x = 1/)).toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/atoms/Markdown.tsx b/packages/trueforge-ui-sdk/src/atoms/Markdown.tsx
new file mode 100644
index 000000000..bc093d672
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/Markdown.tsx
@@ -0,0 +1,123 @@
+'use client';
+
+import type { ComponentType, ReactNode } from 'react';
+import ReactMarkdown, { type Components } from 'react-markdown';
+import remarkGfm from 'remark-gfm';
+
+import { useSlot, useThemeMode } from '../theme/SlotsProvider.js';
+import { useOptionalContentClassNames } from '../theme/ThemeProvider.js';
+import { cn } from './lib/cn.js';
+import type { OpenUiFenceBlockProps } from './OpenUiFenceBlock.js';
+import type { SandboxArtifactDownloadProps } from './SandboxArtifactDownload.js';
+import { SyntaxHighlighter } from './SyntaxHighlighter.js';
+
+/** Preloads OpenUiFenceBlock so it's ready before the user sees openui content. */
+export function preloadMarkdownOpenUI(): Promise<unknown> {
+ return import('./OpenUiFenceBlock.js');
+}
+
+export type MarkdownProps = {
+ content: string;
+ isStreaming?: boolean;
+ /** Base URL for resolving sandbox artifact download paths (e.g. gateway file endpoint). */
+ fileDownloadBaseUrl?: string;
+ /** Custom download handler that receives the original sandbox artifact path. */
+ onDownloadArtifact?: (path: string, filename: string) => Promise<void>;
+ /** When true, download actions in sandbox artifact blocks are hidden/disabled. */
+ readOnly?: boolean;
+ className?: string;
+};
+
+function makeComponents(opts: {
+ isStreaming?: boolean;
+ darkTheme: boolean;
+ fileDownloadBaseUrl?: string;
+ onDownloadArtifact?: (path: string, filename: string) => Promise<void>;
+ readOnly?: boolean;
+ OpenUiFenceBlock: ComponentType<OpenUiFenceBlockProps>;
+ SandboxArtifactDownload: ComponentType<SandboxArtifactDownloadProps>;
+}): Components {
+ const {
+ isStreaming,
+ darkTheme,
+ fileDownloadBaseUrl,
+ onDownloadArtifact,
+ readOnly,
+ OpenUiFenceBlock,
+ SandboxArtifactDownload,
+ } = opts;
+
+ return {
+ // Strip default <pre> wrapper — each block renderer provides its own container.
+ pre({ children }: { children?: ReactNode }) {
+ return <>{children}</>;
+ },
+ code({ className, children }) {
+ const language = /language-(\w+)/.exec(className ?? '')?.[1];
+ const code = String(children ?? '').replace(/\n$/, '');
+
+ // Inline code: no language class
+ if (!className) {
+ return <code className="aui-inline-code rounded px-1 py-0.5 font-mono text-sm bg-muted">{children}</code>;
+ }
+
+ if (language === 'openui') {
+ return <OpenUiFenceBlock content={code} isStreaming={isStreaming} darkTheme={darkTheme} />;
+ }
+
+ if (language === 'sandbox_artifacts') {
+ return (
+ <SandboxArtifactDownload
+ code={code}
+ fileDownloadBaseUrl={fileDownloadBaseUrl}
+ onDownloadArtifact={onDownloadArtifact}
+ readOnly={readOnly}
+ />
+ );
+ }
+
+ return <SyntaxHighlighter code={code} language={language} darkTheme={darkTheme} />;
+ },
+ };
+}
+
+export function Markdown({
+ content,
+ isStreaming,
+ fileDownloadBaseUrl,
+ onDownloadArtifact,
+ readOnly,
+ className,
+}: MarkdownProps) {
+ const mode = useThemeMode();
+ const classNames = useOptionalContentClassNames();
+ const darkTheme = mode === 'dark';
+ const OpenUiFenceBlock = useSlot('OpenUiFenceBlock');
+ const SandboxArtifactDownload = useSlot('SandboxArtifactDownload');
+
+ const components = makeComponents({
+ isStreaming,
+ darkTheme,
+ fileDownloadBaseUrl,
+ onDownloadArtifact,
+ readOnly,
+ OpenUiFenceBlock,
+ SandboxArtifactDownload,
+ });
+
+ return (
+ <div
+ className={cn('aui-markdown markdown-body min-w-0 max-w-full overflow-x-clip', classNames.markdown, className)}
+ >
+ <ReactMarkdown remarkPlugins={[remarkGfm]} components={components}>
+ {content}
+ </ReactMarkdown>
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ Markdown: typeof Markdown;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/MessageActionBar.tsx b/packages/trueforge-ui-sdk/src/atoms/MessageActionBar.tsx
new file mode 100644
index 000000000..0c6b0d65c
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/MessageActionBar.tsx
@@ -0,0 +1,36 @@
+'use client';
+
+import { Icon } from '../icons/Icon.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+import { cn } from './lib/cn.js';
+import { IconButton } from './primitives/IconButton.js';
+
+export type MessageActionBarProps = {
+ isCopied: boolean;
+ onCopy: () => void;
+ createdAt?: Date | string;
+ className?: string;
+};
+
+const actionBtnClass = 'h-6 w-6 text-muted-foreground hover:text-foreground [&_svg]:size-3.5';
+
+export function MessageActionBar({ isCopied, onCopy, createdAt, className }: MessageActionBarProps) {
+ const MessageTimestamp = useSlot('MessageTimestamp');
+
+ return (
+ <div
+ className={cn('aui-assistant-action-bar-root animate-in fade-in flex items-center gap-1 duration-200', className)}
+ >
+ <MessageTimestamp createdAt={createdAt} className="mr-1" />
+ <IconButton aria-label="Copy" tooltip="Copy" variant="ghost" className={actionBtnClass} onClick={onCopy}>
+ <Icon name={isCopied ? 'check' : 'clone'} size="0.875em" />
+ </IconButton>
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ MessageActionBar: typeof MessageActionBar;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/MessageErrorBanner.tsx b/packages/trueforge-ui-sdk/src/atoms/MessageErrorBanner.tsx
new file mode 100644
index 000000000..a6ff4969d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/MessageErrorBanner.tsx
@@ -0,0 +1,26 @@
+import { cn } from './lib/cn.js';
+
+export type MessageErrorBannerProps = {
+ message: string;
+ className?: string;
+};
+
+export function MessageErrorBanner({ message, className }: MessageErrorBannerProps) {
+ return (
+ <div
+ role="alert"
+ className={cn(
+ 'aui-message-error-root border-destructive bg-destructive/10 text-destructive dark:bg-destructive/5 mt-2 rounded-md border p-3 text-sm dark:text-red-200',
+ className,
+ )}
+ >
+ <span className="aui-message-error-message line-clamp-2">{message}</span>
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ MessageErrorBanner: typeof MessageErrorBanner;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/MessageIndicator.tsx b/packages/trueforge-ui-sdk/src/atoms/MessageIndicator.tsx
new file mode 100644
index 000000000..d216b4cd2
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/MessageIndicator.tsx
@@ -0,0 +1,23 @@
+import { cn } from './lib/cn.js';
+
+export type MessageIndicatorProps = {
+ className?: string;
+};
+
+export function MessageIndicator({ className }: MessageIndicatorProps) {
+ return (
+ <span
+ data-slot="aui_assistant-message-indicator"
+ className={cn('animate-pulse font-sans', className)}
+ aria-label="Assistant is working"
+ >
+ {'●'}
+ </span>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ MessageIndicator: typeof MessageIndicator;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/MessageTimestamp.tsx b/packages/trueforge-ui-sdk/src/atoms/MessageTimestamp.tsx
new file mode 100644
index 000000000..c4ea81e3f
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/MessageTimestamp.tsx
@@ -0,0 +1,61 @@
+'use client';
+
+import { cn } from './lib/cn.js';
+import { LightTooltip } from './primitives/Tooltip.js';
+
+function toDate(createdAt: Date | string | undefined): Date | null {
+ if (createdAt == null) {
+ return null;
+ }
+ const date = createdAt instanceof Date ? createdAt : new Date(createdAt);
+ return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function formatTime(date: Date): string {
+ return new Intl.DateTimeFormat(undefined, {
+ hour: '2-digit',
+ minute: '2-digit',
+ second: '2-digit',
+ hour12: true,
+ }).format(date);
+}
+
+function formatFullDate(date: Date): string {
+ return new Intl.DateTimeFormat(undefined, {
+ month: 'short',
+ day: 'numeric',
+ year: 'numeric',
+ hour: 'numeric',
+ minute: '2-digit',
+ hour12: true,
+ }).format(date);
+}
+
+export type MessageTimestampProps = {
+ createdAt?: Date | string;
+ className?: string;
+};
+
+export function MessageTimestamp({ createdAt, className }: MessageTimestampProps) {
+ const date = toDate(createdAt);
+
+ if (date == null) {
+ return null;
+ }
+
+ return (
+ <LightTooltip title={formatFullDate(date)} size="fit">
+ <span
+ className={cn('text-xs font-medium cursor-pointer leading-normal shrink-0 text-muted-foreground', className)}
+ >
+ {formatTime(date)}
+ </span>
+ </LightTooltip>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ MessageTimestamp: typeof MessageTimestamp;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/MonacoEditorCore.tsx b/packages/trueforge-ui-sdk/src/atoms/MonacoEditorCore.tsx
new file mode 100644
index 000000000..a88f27174
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/MonacoEditorCore.tsx
@@ -0,0 +1,287 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+import { useOptionalContentClassNames, useOptionalThemeMode } from '../theme/ThemeProvider.js';
+import { cn } from './lib/cn.js';
+
+export type MonacoEditorCoreProps = {
+ value: string;
+ language?: string;
+ /** Monaco theme name. Defaults to SDK light/dark themes (`aui-monaco-light` / `aui-monaco-dark`). */
+ theme?: string;
+ options?: Record<string, unknown>;
+ onChange?: (value: string) => void;
+ onMount?: (editor: unknown, monaco: unknown) => void;
+ beforeMount?: (monaco: unknown) => void;
+ className?: string;
+ /**
+ * Fixed height. Ignored when `autoHeight` is true (except as an initial
+ * fallback before the editor mounts). Use `"100%"` for fill-parent layouts
+ * (e.g. fullscreen dialogs) with `autoHeight={false}`.
+ */
+ height?: string | number;
+ /** Grow/shrink to content height, capped by `maxHeight`. Default false. */
+ autoHeight?: boolean;
+ /** Cap for `autoHeight` (px number or CSS length). Default `10.5rem`. */
+ maxHeight?: string | number;
+ /** Floor for `autoHeight` (px number or CSS length). Default one line. */
+ minHeight?: string | number;
+};
+
+type MonacoEditor = {
+ getValue(): string;
+ setValue(value: string): void;
+ getContentHeight(): number;
+ onDidChangeModelContent(listener: () => void): { dispose(): void };
+ onDidContentSizeChange(listener: () => void): { dispose(): void };
+ updateOptions(options: Record<string, unknown>): void;
+ dispose(): void;
+ layout(): void;
+};
+
+type MonacoModule = {
+ editor: {
+ create(container: HTMLElement, options: Record<string, unknown>): MonacoEditor;
+ defineTheme(
+ name: string,
+ theme: {
+ base: 'vs' | 'vs-dark' | 'hc-black' | 'hc-light';
+ inherit: boolean;
+ rules: unknown[];
+ colors: Record<string, string>;
+ },
+ ): void;
+ setTheme(name: string): void;
+ };
+};
+
+const AUI_MONACO_LIGHT = 'aui-monaco-light';
+const AUI_MONACO_DARK = 'aui-monaco-dark';
+const TRANSPARENT = '#00000000';
+const DEFAULT_LINE_HEIGHT = 18;
+const DEFAULT_VERTICAL_PADDING = 8;
+const DEFAULT_MAX_HEIGHT = '10.5rem';
+
+function defineAuiThemes(monaco: MonacoModule) {
+ const sharedColors = {
+ 'editor.background': TRANSPARENT,
+ 'editor.lineHighlightBackground': TRANSPARENT,
+ 'editor.lineHighlightBorder': TRANSPARENT,
+ 'editorGutter.background': TRANSPARENT,
+ 'minimap.background': TRANSPARENT,
+ focusBorder: TRANSPARENT,
+ 'scrollbar.shadow': TRANSPARENT,
+ 'editorOverviewRuler.border': TRANSPARENT,
+ 'editorOverviewRuler.background': TRANSPARENT,
+ };
+
+ monaco.editor.defineTheme(AUI_MONACO_LIGHT, {
+ base: 'vs',
+ inherit: true,
+ rules: [],
+ colors: sharedColors,
+ });
+
+ monaco.editor.defineTheme(AUI_MONACO_DARK, {
+ base: 'vs-dark',
+ inherit: true,
+ rules: [],
+ colors: sharedColors,
+ });
+}
+
+function resolveThemeName(
+ explicit: string | undefined,
+ classNameTheme: string | undefined,
+ mode: 'light' | 'dark',
+): string {
+ if (explicit) return explicit;
+ if (classNameTheme) return classNameTheme;
+ return mode === 'dark' ? AUI_MONACO_DARK : AUI_MONACO_LIGHT;
+}
+
+function toPx(value: string | number | undefined, fallback: number): number {
+ if (value == null) return fallback;
+ if (typeof value === 'number') return value;
+ const trimmed = value.trim();
+ if (trimmed.endsWith('rem')) {
+ const rem = parseFloat(trimmed);
+ const root =
+ typeof document !== 'undefined' ? parseFloat(getComputedStyle(document.documentElement).fontSize) || 16 : 16;
+ return Number.isFinite(rem) ? rem * root : fallback;
+ }
+ if (trimmed.endsWith('px')) {
+ const px = parseFloat(trimmed);
+ return Number.isFinite(px) ? px : fallback;
+ }
+ const n = parseFloat(trimmed);
+ return Number.isFinite(n) ? n : fallback;
+}
+
+function estimateHeightFromValue(value: string, minPx: number, maxPx: number): number {
+ const lines = Math.max(1, value.split('\n').length);
+ const estimated = lines * DEFAULT_LINE_HEIGHT + DEFAULT_VERTICAL_PADDING;
+ return Math.min(maxPx, Math.max(minPx, estimated));
+}
+
+const EMBEDDED_DEFAULTS: Record<string, unknown> = {
+ automaticLayout: true,
+ minimap: { enabled: false },
+ scrollBeyondLastLine: false,
+ wordWrap: 'on',
+ fontSize: 12,
+ fontFamily: 'ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace',
+ lineHeight: DEFAULT_LINE_HEIGHT,
+ padding: { top: 4, bottom: 4 },
+ renderLineHighlight: 'none',
+ overviewRulerLanes: 0,
+ overviewRulerBorder: false,
+ hideCursorInOverviewRuler: true,
+ glyphMargin: false,
+ folding: true,
+ scrollbar: {
+ verticalScrollbarSize: 8,
+ horizontalScrollbarSize: 8,
+ useShadows: false,
+ },
+ stickyScroll: { enabled: false },
+};
+
+export function MonacoEditorCore({
+ value,
+ language = 'plaintext',
+ theme,
+ options,
+ onChange,
+ onMount,
+ beforeMount,
+ className,
+ height = 400,
+ autoHeight = false,
+ maxHeight = DEFAULT_MAX_HEIGHT,
+ minHeight,
+}: MonacoEditorCoreProps) {
+ const mode = useOptionalThemeMode();
+ const classNames = useOptionalContentClassNames();
+ const containerRef = useRef<HTMLDivElement>(null);
+ const editorRef = useRef<MonacoEditor | null>(null);
+ const monacoRef = useRef<MonacoModule | null>(null);
+ const onChangeRef = useRef(onChange);
+ const onMountRef = useRef(onMount);
+ const beforeMountRef = useRef(beforeMount);
+ onChangeRef.current = onChange;
+ onMountRef.current = onMount;
+ beforeMountRef.current = beforeMount;
+
+ const minPx = toPx(minHeight, DEFAULT_LINE_HEIGHT + DEFAULT_VERTICAL_PADDING);
+ const maxPx = toPx(maxHeight, toPx(DEFAULT_MAX_HEIGHT, 168));
+ const clampRef = useRef({ minPx, maxPx, autoHeight });
+ clampRef.current = { minPx, maxPx, autoHeight };
+
+ const [autoPx, setAutoPx] = useState(() => (autoHeight ? estimateHeightFromValue(value, minPx, maxPx) : 0));
+
+ const resolvedTheme = resolveThemeName(theme, classNames.monaco?.monacoTheme, mode);
+
+ const syncAutoHeight = () => {
+ const editor = editorRef.current;
+ const el = containerRef.current;
+ const { minPx: min, maxPx: max, autoHeight: enabled } = clampRef.current;
+ if (!editor || !el || !enabled) return;
+ const next = Math.min(max, Math.max(min, editor.getContentHeight()));
+ setAutoPx(next);
+ el.style.height = `${next}px`;
+ editor.layout();
+ };
+
+ useEffect(() => {
+ if (!containerRef.current) return;
+
+ let editor: MonacoEditor | null = null;
+ let changeDisposable: { dispose(): void } | null = null;
+ let sizeDisposable: { dispose(): void } | null = null;
+ let destroyed = false;
+
+ void import('monaco-editor').then(mod => {
+ if (destroyed || !containerRef.current) return;
+
+ const monaco = mod as unknown as MonacoModule;
+ monacoRef.current = monaco;
+ defineAuiThemes(monaco);
+ beforeMountRef.current?.(monaco);
+
+ const initialHeight = autoHeight ? estimateHeightFromValue(value, minPx, maxPx) : height;
+
+ editor = monaco.editor.create(containerRef.current, {
+ value,
+ language,
+ theme: resolvedTheme,
+ ...EMBEDDED_DEFAULTS,
+ ...options,
+ });
+
+ editorRef.current = editor;
+ if (autoHeight) {
+ containerRef.current.style.height =
+ typeof initialHeight === 'number' ? `${initialHeight}px` : String(initialHeight);
+ }
+
+ changeDisposable = editor.onDidChangeModelContent(() => {
+ onChangeRef.current?.(editor!.getValue());
+ });
+
+ if (autoHeight) {
+ sizeDisposable = editor.onDidContentSizeChange(() => {
+ syncAutoHeight();
+ });
+ // Layout after first paint so getContentHeight is accurate.
+ requestAnimationFrame(() => syncAutoHeight());
+ }
+
+ onMountRef.current?.(editor, monaco);
+ });
+
+ return () => {
+ destroyed = true;
+ changeDisposable?.dispose();
+ sizeDisposable?.dispose();
+ editor?.dispose();
+ editorRef.current = null;
+ monacoRef.current = null;
+ };
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, []); // mount-only: editor manages its own state
+
+ // Sync external value changes without recreating the editor.
+ useEffect(() => {
+ const editor = editorRef.current;
+ if (editor && editor.getValue() !== value) {
+ editor.setValue(value);
+ if (autoHeight) {
+ requestAnimationFrame(() => syncAutoHeight());
+ }
+ }
+ }, [value, autoHeight, minPx, maxPx]);
+
+ // Re-clamp when max/min change.
+ useEffect(() => {
+ if (autoHeight) {
+ requestAnimationFrame(() => syncAutoHeight());
+ }
+ }, [autoHeight, minPx, maxPx]);
+
+ // Follow light/dark (and host theme overrides) after mount.
+ useEffect(() => {
+ monacoRef.current?.editor.setTheme(resolvedTheme);
+ }, [resolvedTheme]);
+
+ const styleHeight = autoHeight ? autoPx : typeof height === 'number' ? height : height;
+
+ return (
+ <div
+ ref={containerRef}
+ className={cn('aui-monaco overflow-hidden', classNames.monaco?.root, className)}
+ style={{ height: styleHeight }}
+ />
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/OpenUiFenceBlock.tsx b/packages/trueforge-ui-sdk/src/atoms/OpenUiFenceBlock.tsx
new file mode 100644
index 000000000..7a1c01fe3
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/OpenUiFenceBlock.tsx
@@ -0,0 +1,27 @@
+'use client';
+
+import { Renderer } from '@openuidev/react-lang';
+import { ThemeProvider, openuiLibrary } from '@openuidev/react-ui';
+
+import { useOptionalContentClassNames } from '../theme/ThemeProvider.js';
+import { cn } from './lib/cn.js';
+
+export type OpenUiFenceBlockProps = {
+ content: string;
+ isStreaming?: boolean;
+ darkTheme?: boolean;
+};
+
+export function OpenUiFenceBlock({ content, isStreaming, darkTheme }: OpenUiFenceBlockProps) {
+ const classNames = useOptionalContentClassNames();
+
+ return (
+ <div className={cn('aui-openui mb-2 w-full min-w-0 max-w-full', classNames.openui?.root)}>
+ <ThemeProvider mode={darkTheme ? 'dark' : 'light'} cssSelector=".markdown-openui-scope">
+ <div className="markdown-openui-scope min-w-0 w-full max-w-full overflow-x-auto">
+ <Renderer response={content} library={openuiLibrary} isStreaming={isStreaming} />
+ </div>
+ </ThemeProvider>
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/SandboxArtifactDownload.test.tsx b/packages/trueforge-ui-sdk/src/atoms/SandboxArtifactDownload.test.tsx
new file mode 100644
index 000000000..48a20e49f
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/SandboxArtifactDownload.test.tsx
@@ -0,0 +1,83 @@
+// @vitest-environment jsdom
+import { act, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { SlotsProvider } from '../theme/SlotsProvider.js';
+import { ThemeProvider } from '../theme/ThemeProvider.js';
+import { Markdown } from './Markdown.js';
+import { parseSandboxArtifacts, SandboxArtifactDownload } from './SandboxArtifactDownload.js';
+
+describe('parseSandboxArtifacts', () => {
+ it('parses tfy markdown-link pairs', () => {
+ expect(parseSandboxArtifacts('[sample.js](/tmp/sample.js)\n[notes.txt](/tmp/notes.txt)')).toEqual([
+ { name: 'sample.js', path: '/tmp/sample.js' },
+ { name: 'notes.txt', path: '/tmp/notes.txt' },
+ ]);
+ });
+
+ it('strips a leading sandbox_artifacts prefix', () => {
+ expect(parseSandboxArtifacts('sandbox_artifacts\n[a.py](/tmp/a.py)')).toEqual([
+ { name: 'a.py', path: '/tmp/a.py' },
+ ]);
+ });
+
+ it('falls back to name: path lines', () => {
+ expect(parseSandboxArtifacts('report.pdf: /sandbox/out/report.pdf')).toEqual([
+ { name: 'report.pdf', path: '/sandbox/out/report.pdf' },
+ ]);
+ });
+});
+
+describe('SandboxArtifactDownload', () => {
+ it('renders download links for link-format artifacts', () => {
+ const onDownload = vi.fn(async () => {});
+ render(<SandboxArtifactDownload code={'[hello.js](/tmp/hello.js)'} onDownloadArtifact={onDownload} />);
+ expect(screen.getByRole('link', { name: /Download hello\.js/i })).toBeInTheDocument();
+ expect(screen.getByText('1 file generated')).toBeInTheDocument();
+ });
+
+ it('shows a loader while the download is in flight', async () => {
+ let resolveDownload!: () => void;
+ const onDownload = vi.fn(
+ () =>
+ new Promise<void>(resolve => {
+ resolveDownload = resolve;
+ }),
+ );
+ render(<SandboxArtifactDownload code={'[hello.js](/tmp/hello.js)'} onDownloadArtifact={onDownload} />);
+
+ await act(async () => {
+ screen.getByRole('link', { name: /Download hello\.js/i }).click();
+ });
+ expect(screen.getByRole('link', { name: /Downloading hello\.js/i })).toBeInTheDocument();
+ expect(screen.getByRole('status', { name: 'Loading' })).toBeInTheDocument();
+
+ await act(async () => {
+ resolveDownload();
+ await Promise.resolve();
+ });
+ expect(screen.getByRole('link', { name: /Download hello\.js/i })).toBeInTheDocument();
+ expect(screen.queryByRole('status', { name: 'Loading' })).not.toBeInTheDocument();
+ });
+
+ it('renders nothing when the fence body does not parse', () => {
+ const { container } = render(<SandboxArtifactDownload code={'not an artifact'} />);
+ expect(container).toBeEmptyDOMElement();
+ });
+});
+
+describe('Markdown sandbox_artifacts fence', () => {
+ it('routes the fence to SandboxArtifactDownload', () => {
+ render(
+ <ThemeProvider>
+ <SlotsProvider>
+ <Markdown
+ content={['Files ready:', '', '```sandbox_artifacts', '[demo.js](/tmp/demo.js)', '```'].join('\n')}
+ />
+ </SlotsProvider>
+ </ThemeProvider>,
+ );
+ expect(screen.getByTestId('aui-sandbox-artifacts')).toBeInTheDocument();
+ expect(screen.getByText('demo.js')).toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/atoms/SandboxArtifactDownload.tsx b/packages/trueforge-ui-sdk/src/atoms/SandboxArtifactDownload.tsx
new file mode 100644
index 000000000..d40449839
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/SandboxArtifactDownload.tsx
@@ -0,0 +1,76 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import { ChatFileDownload, type ChatFileDownloadFile } from './ChatFileDownload.js';
+
+export type SandboxArtifactDownloadProps = {
+ code: string;
+ fileDownloadBaseUrl?: string;
+ onDownloadArtifact?: (path: string, filename: string) => Promise<void>;
+ readOnly?: boolean;
+};
+
+export type SandboxArtifact = ChatFileDownloadFile;
+
+const PREFIX = 'sandbox_artifacts';
+/** tfy / agent format: `[name](path)` */
+const PAIR_RE = /\[([^\]]*)\]\(([^)]*)\)/g;
+
+/**
+ * Parses a `sandbox_artifacts` fence body into `{ name, path }` entries.
+ * Primary format matches tfy-web-components: `[file.js](/tmp/file.js)`.
+ * Colon lines (`name: path`) are accepted as a fallback.
+ */
+export function parseSandboxArtifacts(raw: string): SandboxArtifact[] {
+ const trimmed = raw.trim();
+ const body = trimmed.startsWith(PREFIX) ? trimmed.slice(PREFIX.length).trimStart() : trimmed;
+
+ const fromLinks: SandboxArtifact[] = [];
+ PAIR_RE.lastIndex = 0;
+ let match: RegExpExecArray | null = PAIR_RE.exec(body);
+ while (match !== null) {
+ const name = match[1]?.trim() ?? '';
+ const path = match[2]?.trim() ?? '';
+ if (name && path) fromLinks.push({ name, path });
+ match = PAIR_RE.exec(body);
+ }
+ if (fromLinks.length > 0) return fromLinks;
+
+ // Fallback: `name: path` per line
+ return body.split('\n').flatMap(line => {
+ const idx = line.indexOf(':');
+ if (idx === -1) return [];
+ const name = line.slice(0, idx).trim();
+ const path = line.slice(idx + 1).trim();
+ if (!name || !path) return [];
+ // Skip leftover markdown link debris
+ if (name.startsWith('[') || path.startsWith('(')) return [];
+ return [{ name, path }];
+ });
+}
+
+export function SandboxArtifactDownload({
+ code,
+ fileDownloadBaseUrl,
+ onDownloadArtifact,
+ readOnly,
+}: SandboxArtifactDownloadProps) {
+ const artifacts = useMemo(() => parseSandboxArtifacts(code), [code]);
+ if (artifacts.length === 0) return null;
+
+ return (
+ <ChatFileDownload
+ files={artifacts}
+ fileDownloadBaseUrl={fileDownloadBaseUrl}
+ onDownloadArtifact={onDownloadArtifact}
+ readOnly={readOnly}
+ />
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ SandboxArtifactDownload: typeof SandboxArtifactDownload;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/SandboxToolCallCard.tsx b/packages/trueforge-ui-sdk/src/atoms/SandboxToolCallCard.tsx
new file mode 100644
index 000000000..4c19e56a5
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/SandboxToolCallCard.tsx
@@ -0,0 +1,244 @@
+'use client';
+
+import { Icon } from '../icons/Icon.js';
+import { cn } from './lib/cn.js';
+import { MonacoEditorCore } from './MonacoEditorCore.js';
+import { ToolCallCard, type ToolCallStatus } from './ToolCallCard.js';
+
+export type SandboxToolCallCardProps = {
+ name: string;
+ intent?: string;
+ status: ToolCallStatus;
+ expanded: boolean;
+ onToggle: () => void;
+ command?: string;
+ exitCode?: number | null;
+ argsJson?: string;
+ resultText?: string;
+ resultJson?: string;
+ viewMode?: 'terminal' | 'code';
+ hasContent?: boolean;
+ onViewModeChange?: (viewMode: 'terminal' | 'code') => void;
+ durationText?: string;
+ dataTestPrefix?: string;
+ className?: string;
+};
+
+function JsonPane({ value, className }: { value: string; className?: string }) {
+ return (
+ <MonacoEditorCore
+ language="json"
+ value={value}
+ autoHeight
+ maxHeight="10.5rem"
+ options={{
+ readOnly: true,
+ minimap: { enabled: false },
+ scrollBeyondLastLine: false,
+ wordWrap: 'on',
+ lineNumbers: 'off',
+ folding: true,
+ fontSize: 12,
+ }}
+ className={cn('!border-0', className)}
+ />
+ );
+}
+
+function SandboxBody({
+ command,
+ exitCode,
+ argsJson,
+ resultText,
+ resultJson,
+ viewMode = 'terminal',
+ hasContent = false,
+ onViewModeChange,
+ dataTestPrefix,
+}: Pick<
+ SandboxToolCallCardProps,
+ | 'command'
+ | 'exitCode'
+ | 'argsJson'
+ | 'resultText'
+ | 'resultJson'
+ | 'viewMode'
+ | 'hasContent'
+ | 'onViewModeChange'
+ | 'dataTestPrefix'
+>) {
+ return (
+ <div
+ className="rounded-lg border border-border bg-background"
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-sandbox` : undefined}
+ >
+ <div className="rounded-t-md border-b border-primary/30 bg-primary/10">
+ <div className="flex w-full min-w-0 items-center gap-2 px-3 py-1.5">
+ <p className="min-w-0 font-sans text-xs font-medium text-primary">sandbox</p>
+ <div
+ className="ml-auto flex shrink-0 items-center gap-1.5"
+ onClick={e => e.stopPropagation()}
+ onKeyDown={e => e.stopPropagation()}
+ >
+ {exitCode != null && (
+ <span
+ className={cn(
+ 'inline-flex h-6 items-center gap-1 rounded px-1.5 text-xs lowercase',
+ exitCode === 0
+ ? 'bg-green-500/10 text-green-700 dark:text-green-400'
+ : 'bg-destructive/10 text-destructive',
+ )}
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-exit-code` : undefined}
+ >
+ <Icon name={exitCode === 0 ? 'circle-check' : 'circle-xmark'} size={12} />
+ exit: {exitCode}
+ </span>
+ )}
+ <div
+ className="inline-flex h-6 items-center rounded-md border border-border bg-background p-0.5"
+ role="group"
+ aria-label="Sandbox view"
+ >
+ <button
+ type="button"
+ title="Terminal View"
+ aria-label="Terminal View"
+ aria-pressed={viewMode === 'terminal'}
+ onClick={() => onViewModeChange?.('terminal')}
+ className={cn(
+ 'inline-flex size-5 cursor-pointer items-center justify-center rounded-sm text-muted-foreground transition-colors',
+ viewMode === 'terminal' && 'bg-muted text-foreground shadow-sm',
+ )}
+ >
+ <Icon name="terminal" size={12} />
+ </button>
+ <button
+ type="button"
+ title="Code View"
+ aria-label="Code View"
+ aria-pressed={viewMode === 'code'}
+ onClick={() => onViewModeChange?.('code')}
+ className={cn(
+ 'inline-flex size-5 cursor-pointer items-center justify-center rounded-sm text-muted-foreground transition-colors',
+ viewMode === 'code' && 'bg-muted text-foreground shadow-sm',
+ )}
+ >
+ <Icon name="code" size={12} />
+ </button>
+ </div>
+ </div>
+ </div>
+ </div>
+
+ <div className="rounded-b-lg border border-t-0 border-border p-3">
+ {hasContent && (
+ <div className="max-h-80 overflow-x-hidden overflow-y-auto whitespace-pre-wrap break-words font-mono text-xs text-foreground">
+ {viewMode === 'code' ? (
+ <>
+ {argsJson && (
+ <div className="my-1 border-l-4 border-primary px-3">
+ <div className="mb-1 font-sans text-xs font-medium leading-4">Arguments</div>
+ <JsonPane value={argsJson} className="pl-2" />
+ </div>
+ )}
+ {resultJson && (
+ <div className="my-1 border-l-4 border-purple-400 px-3">
+ <div className="mb-1 mt-2 font-sans text-xs font-medium leading-4">Result</div>
+ <JsonPane value={resultJson} className="pl-2" />
+ </div>
+ )}
+ </>
+ ) : (
+ <>
+ {command && (
+ <div className="my-1 break-all border-l-4 border-primary px-3">
+ <div className="mb-1 text-[12px] font-medium leading-4 text-muted-foreground">COMMAND</div>
+ <div>
+ <span className="text-teal-500">$</span> {command}
+ </div>
+ </div>
+ )}
+ {resultText ? (
+ <>
+ <div className="mx-3 my-1 border-t border-border" />
+ <div className="my-1 break-all border-l-4 border-purple-400 px-3">
+ <div className="mb-1 text-[12px] font-medium leading-4 text-muted-foreground">OUTPUT</div>
+ <div>{resultText}</div>
+ </div>
+ </>
+ ) : (
+ resultJson && (
+ <>
+ <div className="mx-3 my-1 border-t border-border" />
+ <div className="my-1 border-l-4 border-purple-400 px-3">
+ <div className="mb-1 text-[12px] font-medium leading-4 text-muted-foreground">OUTPUT</div>
+ <JsonPane value={resultJson} className="pl-2" />
+ </div>
+ </>
+ )
+ )}
+ </>
+ )}
+ </div>
+ )}
+ </div>
+ </div>
+ );
+}
+
+export function SandboxToolCallCard({
+ name,
+ intent,
+ status,
+ expanded,
+ onToggle,
+ command,
+ exitCode,
+ argsJson,
+ resultText,
+ resultJson,
+ viewMode = 'terminal',
+ hasContent = false,
+ onViewModeChange,
+ durationText,
+ dataTestPrefix,
+ className,
+}: SandboxToolCallCardProps) {
+ const awaiting = status === 'running';
+
+ return (
+ <ToolCallCard
+ toolName={intent || name}
+ icon="cube"
+ iconClassName="text-primary shrink-0"
+ expanded={expanded}
+ onToggle={onToggle}
+ awaiting={awaiting}
+ awaitingText={durationText ?? 'Running…'}
+ showResponseLine={false}
+ status={awaiting ? undefined : status}
+ exitCode={exitCode}
+ dataTestPrefix={dataTestPrefix}
+ requestSlot={
+ <SandboxBody
+ command={command}
+ exitCode={exitCode}
+ argsJson={argsJson}
+ resultText={resultText}
+ resultJson={resultJson}
+ viewMode={viewMode}
+ hasContent={hasContent}
+ onViewModeChange={onViewModeChange}
+ dataTestPrefix={dataTestPrefix}
+ />
+ }
+ className={cn('aui-sandbox-tool-call-card', className)}
+ />
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ SandboxToolCallCard: typeof SandboxToolCallCard;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/SaveAgentButton.test.tsx b/packages/trueforge-ui-sdk/src/atoms/SaveAgentButton.test.tsx
new file mode 100644
index 000000000..5541224b7
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/SaveAgentButton.test.tsx
@@ -0,0 +1,113 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+
+import { ServerProvider } from '../server/ServerContext.js';
+import { ShellModeProvider } from '../server/ShellModeContext.js';
+import type { AgentUIServer } from '../server/types.js';
+import { SlotsProvider } from '../theme/SlotsProvider.js';
+import { SaveAgentButton } from './SaveAgentButton.js';
+
+vi.mock('@truefoundry/assistant-ui-runtime', () => ({
+ useTrueFoundryAgentSpec: () => ({
+ agentSpec: {
+ model: { name: 'openai-main/gpt-4.1' },
+ skills: [{ id: 's1', name: 'Skill One' }],
+ },
+ }),
+}));
+
+beforeAll(() => {
+ HTMLDialogElement.prototype.showModal = function showModal() {
+ this.setAttribute('open', '');
+ };
+ HTMLDialogElement.prototype.close = function close() {
+ this.removeAttribute('open');
+ this.dispatchEvent(new Event('close'));
+ };
+});
+
+function mockServer(saveAgent = vi.fn(async () => ({ ok: true }))): AgentUIServer {
+ return { saveAgent } as unknown as AgentUIServer;
+}
+
+describe('SaveAgentButton', () => {
+ it('is hidden when the shell is locked to a named agent', () => {
+ render(
+ <SlotsProvider>
+ <ServerProvider server={mockServer()}>
+ <ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: 'locked-agent' }}>
+ <SaveAgentButton />
+ </ShellModeProvider>
+ </ServerProvider>
+ </SlotsProvider>,
+ );
+
+ expect(screen.queryByRole('button', { name: 'Save as agent' })).not.toBeInTheDocument();
+ });
+
+ it('opens a name-only modal and saves the current agentSpec', async () => {
+ const saveAgent = vi.fn(async () => ({ ok: true }));
+
+ render(
+ <SlotsProvider>
+ <ServerProvider server={mockServer(saveAgent)}>
+ <ShellModeProvider>
+ <SaveAgentButton />
+ </ShellModeProvider>
+ </ServerProvider>
+ </SlotsProvider>,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'Save as agent' }));
+ const dialog = screen.getByRole('dialog', { name: 'Save as agent' });
+ expect(dialog).toBeInTheDocument();
+ expect(dialog.className).toContain('h-auto');
+ expect(dialog.className).toContain('md:max-w-md');
+ expect(dialog).toHaveStyle({ height: 'fit-content' });
+ expect(screen.getByLabelText('Name')).toBeInTheDocument();
+ expect(screen.queryByLabelText(/system instructions/i)).not.toBeInTheDocument();
+
+ fireEvent.change(screen.getByLabelText('Name'), { target: { value: ' my-agent ' } });
+ fireEvent.click(dialog.querySelector('button[type="submit"]')!);
+
+ await waitFor(() => {
+ expect(saveAgent).toHaveBeenCalledWith({
+ agentName: 'my-agent',
+ agentSpec: {
+ model: { name: 'openai-main/gpt-4.1' },
+ skills: [{ id: 's1', name: 'Skill One' }],
+ },
+ });
+ });
+ await waitFor(() => {
+ expect(screen.queryByRole('dialog', { name: 'Save as agent' })).not.toBeInTheDocument();
+ });
+ });
+
+ it('surfaces save errors without closing', async () => {
+ const saveAgent = vi.fn(async () => {
+ throw new Error('Name taken');
+ });
+
+ render(
+ <SlotsProvider>
+ <ServerProvider server={mockServer(saveAgent)}>
+ <ShellModeProvider>
+ <SaveAgentButton />
+ </ShellModeProvider>
+ </ServerProvider>
+ </SlotsProvider>,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'Save as agent' }));
+ const dialog = screen.getByRole('dialog', { name: 'Save as agent' });
+ fireEvent.change(screen.getByLabelText('Name'), { target: { value: 'dup' } });
+ fireEvent.click(dialog.querySelector('button[type="submit"]')!);
+
+ await waitFor(() => {
+ expect(screen.getByText('Name taken')).toBeInTheDocument();
+ });
+ expect(screen.getByRole('dialog', { name: 'Save as agent' })).toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/atoms/SaveAgentButton.tsx b/packages/trueforge-ui-sdk/src/atoms/SaveAgentButton.tsx
new file mode 100644
index 000000000..f1d1042fc
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/SaveAgentButton.tsx
@@ -0,0 +1,104 @@
+'use client';
+
+import { useTrueFoundryAgentSpec } from '@truefoundry/assistant-ui-runtime';
+import { useId, useState, type FormEvent } from 'react';
+
+import { useOptionalServer } from '../server/ServerContext.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import type { AgentSpec } from '../server/types.js';
+import { auiButtonClass } from './lib/buttonClasses.js';
+import { CenteredModal } from './primitives/CenteredModal.js';
+
+export function SaveAgentButton() {
+ const shell = useOptionalShellMode();
+ const server = useOptionalServer();
+ const { agentSpec } = useTrueFoundryAgentSpec();
+ const [open, setOpen] = useState(false);
+ const [name, setName] = useState('');
+ const [saving, setSaving] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+ const nameId = useId();
+
+ if (shell?.mode.type !== 'draft' || server == null) return null;
+
+ const draftSpec = shell.mode.defaultAgentSpec;
+ // Runtime AgentSpec is structurally compatible; cast across package boundary.
+ const specToSave: AgentSpec = (agentSpec as AgentSpec | undefined) ?? draftSpec;
+
+ const reset = () => {
+ setName('');
+ setError(null);
+ setSaving(false);
+ };
+
+ const handleOpenChange = (next: boolean) => {
+ setOpen(next);
+ if (!next) reset();
+ };
+
+ const handleSubmit = async (event: FormEvent) => {
+ event.preventDefault();
+ const agentName = name.trim();
+ if (!agentName || saving) return;
+
+ setSaving(true);
+ setError(null);
+ try {
+ await server.saveAgent({
+ agentName,
+ agentSpec: specToSave,
+ });
+ handleOpenChange(false);
+ } catch (err: unknown) {
+ setError(err instanceof Error ? err.message : 'Failed to save agent.');
+ setSaving(false);
+ }
+ };
+
+ return (
+ <>
+ <button
+ type="button"
+ className={auiButtonClass({ variant: 'outline', size: 'sm' })}
+ onClick={() => setOpen(true)}
+ >
+ Save as agent
+ </button>
+
+ <CenteredModal
+ open={open}
+ onOpenChange={handleOpenChange}
+ title="Save as agent"
+ description="Reuse this setup later from the Agents library"
+ contentSized
+ >
+ <form className="flex flex-col gap-4 p-5" onSubmit={e => void handleSubmit(e)}>
+ <div className="flex flex-col gap-1.5">
+ <label htmlFor={nameId} className="text-foreground text-sm font-medium">
+ Name
+ </label>
+ <input
+ id={nameId}
+ type="text"
+ value={name}
+ onChange={e => setName(e.target.value)}
+ placeholder="Agent Name"
+ autoFocus
+ autoComplete="off"
+ disabled={saving}
+ className="border-input bg-background placeholder:text-muted-foreground h-9 w-full rounded-md border px-3 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring/40 disabled:opacity-50"
+ />
+ </div>
+ {error ? <p className="text-destructive text-sm">{error}</p> : null}
+ <button
+ type="submit"
+ disabled={saving || name.trim().length === 0}
+ className={auiButtonClass({ variant: 'default', className: 'w-full' })}
+ >
+ {saving ? 'Saving…' : 'Save'}
+ </button>
+ </form>
+ </CenteredModal>
+ </>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ScrollToBottomButton.tsx b/packages/trueforge-ui-sdk/src/atoms/ScrollToBottomButton.tsx
new file mode 100644
index 000000000..bc39a0956
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ScrollToBottomButton.tsx
@@ -0,0 +1,42 @@
+import { forwardRef, type ComponentProps } from 'react';
+
+import { Icon } from '../icons/Icon.js';
+import { auiButtonClass } from './lib/buttonClasses.js';
+import { cn } from './lib/cn.js';
+
+export type ScrollToBottomButtonProps = Omit<ComponentProps<'button'>, 'children' | 'aria-label'>;
+
+export const ScrollToBottomButton = forwardRef<HTMLSpanElement, ScrollToBottomButtonProps>(
+ ({ className, disabled, ...rest }, ref) => {
+ if (disabled) return null;
+ return (
+ <span ref={ref} className={cn('absolute -top-14 z-10 inline-flex self-center')}>
+ <button
+ type="button"
+ aria-label="Scroll to bottom"
+ title="Scroll to bottom"
+ disabled={disabled}
+ className={auiButtonClass({
+ variant: 'ghost',
+ size: 'icon',
+ className: cn(
+ 'aui-thread-scroll-to-bottom rounded-full border border-border bg-background text-foreground shadow-sm hover:bg-accent hover:text-accent-foreground p-3',
+ className,
+ ),
+ })}
+ {...rest}
+ >
+ <Icon name="arrow-down" />
+ </button>
+ </span>
+ );
+ },
+);
+
+ScrollToBottomButton.displayName = 'ScrollToBottomButton';
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ ScrollToBottomButton: typeof ScrollToBottomButton;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/SelectAgentEmptyState.tsx b/packages/trueforge-ui-sdk/src/atoms/SelectAgentEmptyState.tsx
new file mode 100644
index 000000000..1fb0de0e3
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/SelectAgentEmptyState.tsx
@@ -0,0 +1,22 @@
+'use client';
+
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+
+/** Empty main pane when AgentLibrary has no agent selected yet. */
+export function SelectAgentEmptyState() {
+ const shell = useOptionalShellMode();
+ const AgentsLibraryButton = useSlot('AgentsLibraryButton');
+
+ if (shell?.mode.type !== 'idle') return null;
+
+ return (
+ <div
+ className="flex h-full min-h-0 w-full flex-col items-center justify-center gap-4 px-6"
+ data-slot="aui_select-agent-empty"
+ >
+ <p className="text-muted-foreground max-w-sm text-center text-sm">Select an agent to start chatting</p>
+ <AgentsLibraryButton className="w-56 max-w-full" />
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ShellActions.tsx b/packages/trueforge-ui-sdk/src/atoms/ShellActions.tsx
new file mode 100644
index 000000000..f761a2ab0
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ShellActions.tsx
@@ -0,0 +1,40 @@
+'use client';
+
+import { Icon } from '../icons/Icon.js';
+import { useOptionalCatalogServer } from '../server/ServerContext.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import { useTheme } from '../theme/ThemeProvider.js';
+import { auiButtonClass } from './lib/buttonClasses.js';
+import { cn } from './lib/cn.js';
+
+export function ShellActions({ className }: { className?: string }) {
+ const shell = useOptionalShellMode();
+ const catalog = useOptionalCatalogServer();
+ const { mode, setTheme } = useTheme();
+
+ return (
+ <div className={cn('flex shrink-0 items-center gap-1 text-foreground', className)}>
+ <button
+ type="button"
+ aria-label={mode === 'dark' ? 'Switch to light theme' : 'Switch to dark theme'}
+ title={mode === 'dark' ? 'Light theme' : 'Dark theme'}
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={() => setTheme(mode === 'dark' ? 'light' : 'dark')}
+ >
+ <Icon name={mode === 'dark' ? 'sun' : 'moon'} />
+ </button>
+ {shell != null && catalog != null ? (
+ <button
+ type="button"
+ aria-label="Settings"
+ title="Settings"
+ aria-expanded={shell.settingsOpen}
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={() => shell.setSettingsOpen(true)}
+ >
+ <Icon name="settings" />
+ </button>
+ ) : null}
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/Skeletons.tsx b/packages/trueforge-ui-sdk/src/atoms/Skeletons.tsx
new file mode 100644
index 000000000..75086da1e
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/Skeletons.tsx
@@ -0,0 +1,32 @@
+import { cn } from './lib/cn.js';
+import { Skeleton } from './primitives/Skeleton.js';
+
+export type MessageListSkeletonProps = {
+ className?: string;
+};
+
+export function MessageListSkeleton({ className }: MessageListSkeletonProps) {
+ return (
+ <div
+ role="status"
+ aria-label="Loading conversation"
+ data-slot="aui_thread-history-skeleton"
+ className={cn('mb-14 flex flex-col gap-y-6', className)}
+ >
+ <div className="flex justify-end">
+ <Skeleton className="h-10 w-[min(85%,20rem)] rounded-xl" />
+ </div>
+ <div className="flex flex-col gap-2 px-2">
+ <Skeleton className="h-4 w-full max-w-md" />
+ <Skeleton className="h-4 w-full max-w-sm" />
+ <Skeleton className="h-4 w-2/3 max-w-xs" />
+ </div>
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ MessageListSkeleton: typeof MessageListSkeleton;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/SubAgentCard.tsx b/packages/trueforge-ui-sdk/src/atoms/SubAgentCard.tsx
new file mode 100644
index 000000000..fa318303e
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/SubAgentCard.tsx
@@ -0,0 +1,95 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+import { AgentStepRow, type AgentStepStatus } from './agent-chat/AgentStepRow.js';
+import { cn } from './lib/cn.js';
+import type { ToolCallStatus } from './ToolCallCard.js';
+
+export type SubAgentCardProps = {
+ agentName: string;
+ instruction: string;
+ stepCount: number;
+ status: ToolCallStatus;
+ expanded: boolean;
+ onToggle: () => void;
+ durationText?: string;
+ children?: ReactNode;
+ renderInstruction?: (instruction: string) => ReactNode;
+ dataTestPrefix?: string;
+ className?: string;
+};
+
+export function SubAgentCard({
+ agentName,
+ instruction,
+ stepCount: _stepCount,
+ status,
+ expanded,
+ onToggle,
+ durationText,
+ children,
+ renderInstruction,
+ dataTestPrefix,
+ className,
+}: SubAgentCardProps) {
+ const Markdown = useSlot('Markdown');
+
+ const agentStatus: AgentStepStatus = status === 'running' ? 'running' : status === 'success' ? 'success' : 'error';
+
+ const instructionContent =
+ instruction.trim().length > 0 ? (
+ renderInstruction ? (
+ renderInstruction(instruction)
+ ) : (
+ <Markdown content={instruction} className="flex flex-col font-sans text-sm text-muted-foreground" />
+ )
+ ) : null;
+
+ return (
+ <div
+ className={cn('aui-sub-agent-card min-w-0', className)}
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-sub-agent-card` : undefined}
+ >
+ <AgentStepRow
+ icon="agent-2"
+ iconVariant="primary"
+ title={`Sub-agent: ${agentName}`}
+ expandable
+ expanded={expanded}
+ onToggle={onToggle}
+ status={agentStatus}
+ statusText={durationText}
+ dataTestPrefix={dataTestPrefix}
+ >
+ {instructionContent != null && (
+ <div className="mb-3 flex flex-col gap-2 rounded-md border border-border p-2">
+ <h4 className="text-sm font-semibold text-foreground">Instructions</h4>
+ <div
+ className="text-sm text-muted-foreground"
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-instructions` : undefined}
+ >
+ {instructionContent}
+ </div>
+ </div>
+ )}
+
+ {children != null && (
+ <div
+ className="flex min-w-0 flex-col gap-3"
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-nested-content` : undefined}
+ >
+ {children}
+ </div>
+ )}
+ </AgentStepRow>
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ SubAgentCard: typeof SubAgentCard;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/SyntaxHighlighter.tsx b/packages/trueforge-ui-sdk/src/atoms/SyntaxHighlighter.tsx
new file mode 100644
index 000000000..72cf483cc
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/SyntaxHighlighter.tsx
@@ -0,0 +1,49 @@
+'use client';
+
+import { Prism as PrismHighlighter } from 'react-syntax-highlighter';
+import { oneDark, oneLight } from 'react-syntax-highlighter/dist/esm/styles/prism';
+
+import { useOptionalContentClassNames } from '../theme/ThemeProvider.js';
+import { cn } from './lib/cn.js';
+
+export type SyntaxHighlighterProps = {
+ code: string;
+ language?: string;
+ darkTheme?: boolean;
+ className?: string;
+ showLineNumbers?: boolean;
+};
+
+export function SyntaxHighlighter({ code, language, darkTheme, className, showLineNumbers }: SyntaxHighlighterProps) {
+ const classNames = useOptionalContentClassNames();
+ const style = darkTheme ? oneDark : oneLight;
+
+ return (
+ <div
+ className={cn(
+ 'aui-syntax-highlighter my-2 max-w-full min-w-0 overflow-x-auto rounded-md',
+ classNames.syntaxHighlighter?.root,
+ className,
+ )}
+ >
+ <PrismHighlighter
+ language={language}
+ style={style}
+ showLineNumbers={showLineNumbers}
+ customStyle={{ margin: 0, maxWidth: '100%' }}
+ PreTag={({ children, className: preClass, ...rest }) => (
+ <pre {...rest} className={cn('max-w-full overflow-x-auto', classNames.syntaxHighlighter?.pre, preClass)}>
+ {children}
+ </pre>
+ )}
+ CodeTag={({ children, className: codeClass, ...rest }) => (
+ <code {...rest} className={cn(classNames.syntaxHighlighter?.code, codeClass)}>
+ {children}
+ </code>
+ )}
+ >
+ {code}
+ </PrismHighlighter>
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ThreadListMisc.tsx b/packages/trueforge-ui-sdk/src/atoms/ThreadListMisc.tsx
new file mode 100644
index 000000000..0c1cffaef
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ThreadListMisc.tsx
@@ -0,0 +1,92 @@
+import type { ComponentProps, ReactNode } from 'react';
+
+import { Icon } from '../icons/Icon.js';
+import { auiButtonClass } from './lib/buttonClasses.js';
+import { cn } from './lib/cn.js';
+import { Skeleton } from './primitives/Skeleton.js';
+
+export type ThreadListNewButtonProps = ComponentProps<'button'>;
+
+export function ThreadListNewButton({ className, children, style, ...rest }: ThreadListNewButtonProps) {
+ return (
+ <button
+ type="button"
+ aria-label="Start new chat"
+ style={{ borderRadius: 'var(--thread-list-item-radius, 0.5rem)', ...style }}
+ className={auiButtonClass({
+ variant: 'ghost',
+ className: cn(
+ '!justify-start h-8 px-2.5 text-sm font-medium text-foreground shadow-none hover:bg-accent hover:text-accent-foreground',
+ className,
+ ),
+ })}
+ {...rest}
+ >
+ {children ?? (
+ <>
+ <Icon name="pencil" />
+ New Chat
+ </>
+ )}
+ </button>
+ );
+}
+
+export type ThreadListRowSkeletonProps = {
+ count?: number;
+ className?: string;
+};
+
+export function ThreadListRowSkeleton({ count = 5, className }: ThreadListRowSkeletonProps) {
+ return (
+ <div className={cn('flex flex-col gap-1', className)} role="status" aria-label="Loading threads">
+ {Array.from({ length: count }, (_, i) => (
+ <div key={i} className="flex h-8 items-center px-2.5">
+ <Skeleton className="h-3.5 w-full" />
+ </div>
+ ))}
+ </div>
+ );
+}
+
+export type ThreadListEmptyStateProps = {
+ message?: string;
+ className?: string;
+};
+
+export function ThreadListEmptyState({ message = 'No threads yet', className }: ThreadListEmptyStateProps) {
+ return (
+ <div
+ className={cn(
+ 'text-muted-foreground flex flex-1 items-center justify-center px-4 text-center text-sm',
+ className,
+ )}
+ >
+ {message}
+ </div>
+ );
+}
+
+export type ThreadListShellProps = {
+ header: ReactNode;
+ children: ReactNode;
+ className?: string;
+};
+
+export function ThreadListShell({ header, children, className }: ThreadListShellProps) {
+ return (
+ <div className={cn('font-sans-flex flex h-full min-h-0 flex-1 flex-col overflow-hidden', className)}>
+ <div className="shrink-0 border-b border-border px-2 py-2">{header}</div>
+ <div className="flex min-h-0 flex-1 flex-col gap-0.5 overflow-y-auto p-2">{children}</div>
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ ThreadListNewButton: typeof ThreadListNewButton;
+ ThreadListRowSkeleton: typeof ThreadListRowSkeleton;
+ ThreadListEmptyState: typeof ThreadListEmptyState;
+ ThreadListShell: typeof ThreadListShell;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ThreadListRow.test.tsx b/packages/trueforge-ui-sdk/src/atoms/ThreadListRow.test.tsx
new file mode 100644
index 000000000..6f6c6496a
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ThreadListRow.test.tsx
@@ -0,0 +1,57 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { SlotsProvider } from '../theme/SlotsProvider.js';
+import { ThreadListRow } from './ThreadListRow.js';
+import { DropdownMenuItem } from './primitives/DropdownMenu.js';
+
+describe('ThreadListRow', () => {
+ it('hides actions when omitted', () => {
+ render(
+ <SlotsProvider>
+ <ThreadListRow title="Session A" active={false} onSelect={() => {}} />
+ </SlotsProvider>,
+ );
+ expect(screen.queryByRole('button', { name: 'Session actions' })).not.toBeInTheDocument();
+ });
+
+ it('renders actions without selecting the row when the action is clicked', () => {
+ const onSelect = vi.fn();
+ const onDelete = vi.fn();
+ render(
+ <SlotsProvider>
+ <ThreadListRow
+ title="Session A"
+ active={false}
+ onSelect={onSelect}
+ actions={<DropdownMenuItem onClick={onDelete}>Delete</DropdownMenuItem>}
+ />
+ </SlotsProvider>,
+ );
+
+ fireEvent.click(screen.getByRole('menuitem', { name: /Delete/i }));
+
+ expect(onDelete).toHaveBeenCalledOnce();
+ expect(onSelect).not.toHaveBeenCalled();
+ });
+
+ it('applies hover/active chrome on the row group so actions share the highlight', () => {
+ const { container, rerender } = render(
+ <SlotsProvider>
+ <ThreadListRow title="Session A" active={false} onSelect={() => {}} />
+ </SlotsProvider>,
+ );
+ const row = container.querySelector('[data-slot="aui_thread-list-item"]');
+ expect(row?.className).toMatch(/hover:bg-accent/);
+ expect(row?.className).not.toMatch(/bg-muted/);
+
+ rerender(
+ <SlotsProvider>
+ <ThreadListRow title="Session A" active onSelect={() => {}} />
+ </SlotsProvider>,
+ );
+ const activeRow = container.querySelector('[data-slot="aui_thread-list-item"]');
+ expect(activeRow?.className).toMatch(/bg-muted/);
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/atoms/ThreadListRow.tsx b/packages/trueforge-ui-sdk/src/atoms/ThreadListRow.tsx
new file mode 100644
index 000000000..924ceb481
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ThreadListRow.tsx
@@ -0,0 +1,52 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+import { auiButtonClass } from './lib/buttonClasses.js';
+import { cn } from './lib/cn.js';
+
+export type ThreadListRowProps = {
+ title: string;
+ active: boolean;
+ onSelect: () => void;
+ /** Overflow actions (e.g. delete menu) — rendered as a sibling of the title button. */
+ actions?: ReactNode;
+ className?: string;
+};
+
+export function ThreadListRow({ title, active, onSelect, actions, className }: ThreadListRowProps) {
+ return (
+ <div
+ data-slot="aui_thread-list-item"
+ data-active={active || undefined}
+ className={cn(
+ 'group flex min-w-0 items-center gap-0.5 rounded-md transition-colors',
+ active ? 'bg-muted text-foreground' : 'text-muted-foreground hover:bg-accent hover:text-foreground',
+ className,
+ )}
+ >
+ <button
+ type="button"
+ onClick={onSelect}
+ style={{ borderRadius: 'var(--thread-list-item-radius, 0.5rem)' }}
+ className={auiButtonClass({
+ variant: 'ghost',
+ className: cn(
+ '!justify-start h-8 min-w-0 flex-1 overflow-hidden rounded-md px-2.5 text-left font-normal shadow-none',
+ 'bg-transparent hover:bg-transparent hover:text-inherit',
+ active ? 'text-foreground' : 'text-inherit',
+ ),
+ })}
+ >
+ <span className="min-w-0 flex-1 truncate">{title}</span>
+ </button>
+ {actions != null ? <div className="shrink-0 pr-0.5">{actions}</div> : null}
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ ThreadListRow: typeof ThreadListRow;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ThreadShell.tsx b/packages/trueforge-ui-sdk/src/atoms/ThreadShell.tsx
new file mode 100644
index 000000000..dda5f2002
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ThreadShell.tsx
@@ -0,0 +1,95 @@
+import { forwardRef, type ComponentPropsWithRef, type CSSProperties } from 'react';
+
+import { cn } from './lib/cn.js';
+
+const THREAD_CSS_VARS: CSSProperties = {
+ ['--thread-max-width' as string]: '44rem',
+ ['--composer-bg' as string]: 'var(--card)',
+ ['--composer-padding' as string]: '8px',
+};
+
+export type ThreadRootShellProps = ComponentPropsWithRef<'div'>;
+
+export const ThreadRootShell = forwardRef<HTMLDivElement, ThreadRootShellProps>(
+ ({ className, style, ...rest }, ref) => (
+ <div
+ ref={ref}
+ className={cn(
+ 'font-sans-flex aui-root aui-thread-root bg-background @container flex h-full min-h-0 w-full min-w-0 flex-col overflow-hidden',
+ className,
+ )}
+ style={{ ...THREAD_CSS_VARS, ...style }}
+ {...rest}
+ />
+ ),
+);
+ThreadRootShell.displayName = 'ThreadRootShell';
+
+export type ThreadViewportShellProps = ComponentPropsWithRef<'div'> & {
+ isEmpty?: boolean;
+};
+
+export const ThreadViewportShell = forwardRef<HTMLDivElement, ThreadViewportShellProps>(
+ ({ className, isEmpty, children, ...rest }, ref) => (
+ <div
+ ref={ref}
+ data-slot="aui_thread-viewport"
+ className={cn(
+ 'relative flex min-h-0 min-w-0 flex-1 flex-col overflow-x-hidden overflow-y-auto overscroll-contain scroll-smooth',
+ className,
+ )}
+ {...rest}
+ >
+ <div
+ className={cn(
+ 'mx-auto flex w-full min-w-0 max-w-(--thread-max-width) flex-col px-3 pt-3 sm:px-4 sm:pt-4',
+ isEmpty ? 'min-h-full justify-center pb-4' : 'pb-32',
+ )}
+ >
+ {children}
+ </div>
+ </div>
+ ),
+);
+ThreadViewportShell.displayName = 'ThreadViewportShell';
+
+export type ThreadComposerAreaShellProps = ComponentPropsWithRef<'div'> & {
+ isEmpty?: boolean;
+};
+
+export const ThreadComposerAreaShell = forwardRef<HTMLDivElement, ThreadComposerAreaShellProps>(
+ ({ className, isEmpty, ...rest }, ref) => (
+ <div
+ ref={ref}
+ data-slot="aui_thread-composer"
+ className={cn(
+ 'aui-thread-composer bg-background relative mx-auto flex w-full min-w-0 max-w-(--thread-max-width) shrink-0 flex-col gap-3 px-3 pb-[max(1rem,env(safe-area-inset-bottom,0px))] sm:gap-4 sm:px-4 md:pb-[max(1.5rem,env(safe-area-inset-bottom,0px))]',
+ !isEmpty && 'rounded-t-(--composer-radius)',
+ className,
+ )}
+ {...rest}
+ />
+ ),
+);
+ThreadComposerAreaShell.displayName = 'ThreadComposerAreaShell';
+
+export type MessageGroupProps = ComponentPropsWithRef<'div'>;
+
+export const MessageGroup = forwardRef<HTMLDivElement, MessageGroupProps>(({ className, ...rest }, ref) => (
+ <div
+ ref={ref}
+ data-slot="aui_message-group"
+ className={cn('flex flex-col gap-y-6 empty:hidden', className)}
+ {...rest}
+ />
+));
+MessageGroup.displayName = 'MessageGroup';
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ ThreadRootShell: typeof ThreadRootShell;
+ ThreadViewportShell: typeof ThreadViewportShell;
+ ThreadComposerAreaShell: typeof ThreadComposerAreaShell;
+ MessageGroup: typeof MessageGroup;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/Toast.tsx b/packages/trueforge-ui-sdk/src/atoms/Toast.tsx
new file mode 100644
index 000000000..f511e38af
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/Toast.tsx
@@ -0,0 +1,94 @@
+'use client';
+
+import { useCallback, useState, type ReactNode } from 'react';
+
+import { Icon } from '../icons/Icon.js';
+import { auiButtonClass } from './lib/buttonClasses.js';
+import { cn } from './lib/cn.js';
+
+export type ToastProps = {
+ title: string;
+ description: string;
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ className?: string;
+};
+
+export function Toast({ title, description, open, onOpenChange, className }: ToastProps) {
+ const [copied, setCopied] = useState(false);
+
+ const handleCopy = useCallback(async () => {
+ const text = `${title}\n${description}`;
+ try {
+ await navigator.clipboard.writeText(text);
+ setCopied(true);
+ window.setTimeout(() => setCopied(false), 1500);
+ } catch {
+ // clipboard can fail in insecure contexts; toast still usable
+ }
+ }, [title, description]);
+
+ if (!open) return null;
+
+ return (
+ <div
+ role="alert"
+ className={cn(
+ 'font-sans-flex bg-background text-foreground pointer-events-auto flex w-full items-start gap-3 rounded-xl border border-gray-200 px-4 py-4 shadow-md dark:bg-card',
+ 'animate-in fade-in-0 slide-in-from-bottom-4',
+ className,
+ )}
+ >
+ <Icon name="circle-exclamation" size="1.25em" className="text-destructive shrink-0" />
+
+ <div className="min-w-0 flex-1">
+ <div className="flex items-start justify-between gap-2">
+ <div className="text-destructive text-sm leading-none font-semibold dark:text-red-200">{title}</div>
+ <div className="flex shrink-0 items-center gap-1">
+ <button
+ type="button"
+ aria-label="Copy"
+ title="Copy"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={handleCopy}
+ >
+ <Icon name={copied ? 'check' : 'clone'} />
+ </button>
+ <button
+ type="button"
+ aria-label="Close"
+ title="Close"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={() => onOpenChange(false)}
+ >
+ <Icon name="xmark" />
+ </button>
+ </div>
+ </div>
+ <div className="text-muted-foreground mt-1 max-h-24 overflow-y-auto text-sm leading-snug break-words whitespace-pre-wrap">
+ {description}
+ </div>
+ </div>
+ </div>
+ );
+}
+
+export type ToastStackProps = {
+ children: ReactNode;
+ duration?: number;
+};
+
+export function ToastStack({ children, duration: _duration = Number.POSITIVE_INFINITY }: ToastStackProps) {
+ return (
+ <div className="pointer-events-none fixed bottom-4 left-1/2 z-50 flex w-full max-w-md -translate-x-1/2 flex-col-reverse gap-2 px-4">
+ {children}
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ Toast: typeof Toast;
+ ToastStack: typeof ToastStack;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ToolApprovalBar.tsx b/packages/trueforge-ui-sdk/src/atoms/ToolApprovalBar.tsx
new file mode 100644
index 000000000..4d68a7bd9
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ToolApprovalBar.tsx
@@ -0,0 +1,215 @@
+'use client';
+
+import { Icon } from '../icons/Icon.js';
+import { StepIconBox } from './agent-chat/StepIconBox.js';
+import { cn } from './lib/cn.js';
+import { Button } from './primitives/Button.js';
+
+export type ApprovalOption = {
+ id: string;
+ label: string;
+ variant?: 'primary' | 'secondary' | 'destructive';
+ requiresReason?: boolean;
+ grants?: readonly string[];
+ confirm?: {
+ title?: string;
+ description?: string;
+ };
+};
+
+export type ToolApprovalBarProps = {
+ toolName: string;
+ approveOptions?: ApprovalOption[];
+ denyOptions?: ApprovalOption[];
+ onSelect: (optionId: string, reason?: string) => void;
+ status?: {
+ type: 'approved' | 'denied';
+ label?: string;
+ reason?: string;
+ };
+ selectedDenyOption?: ApprovalOption;
+ denialReason?: string;
+ showReasonError?: boolean;
+ onDenyOptionChange?: (optionId: string | null) => void;
+ onDenialReasonChange?: (reason: string) => void;
+ onReasonSubmit?: () => void;
+ disabled?: boolean;
+ readOnly?: boolean;
+ showLineBelow?: boolean;
+ dataTestPrefix?: string;
+ className?: string;
+};
+
+const DEFAULT_APPROVE_OPTIONS: ApprovalOption[] = [{ id: 'approve', label: 'Approve', variant: 'primary' }];
+
+const DEFAULT_DENY_OPTIONS: ApprovalOption[] = [
+ { id: 'deny', label: 'Deny', variant: 'secondary', requiresReason: true },
+];
+
+function optionVariant(option: ApprovalOption): 'default' | 'secondary' | 'destructive' {
+ if (option.variant === 'destructive') return 'destructive';
+ if (option.variant === 'secondary') return 'secondary';
+ return 'default';
+}
+
+export function ToolApprovalBar({
+ toolName,
+ approveOptions = DEFAULT_APPROVE_OPTIONS,
+ denyOptions = DEFAULT_DENY_OPTIONS,
+ onSelect,
+ status,
+ selectedDenyOption,
+ denialReason = '',
+ showReasonError = false,
+ onDenyOptionChange,
+ onDenialReasonChange,
+ onReasonSubmit,
+ disabled = false,
+ readOnly = false,
+ showLineBelow = false,
+ dataTestPrefix,
+ className,
+}: ToolApprovalBarProps) {
+ const isDecided = !!status;
+ const isApproved = status?.type === 'approved';
+ const isDenied = status?.type === 'denied';
+ const interactionsLocked = disabled && !isDecided;
+
+ const headingText = isApproved ? 'Tool Approved' : isDenied ? 'Tool Approval Denied' : 'Tool Approval Required for';
+
+ return (
+ <div
+ className={cn('aui-tool-approval-bar', className)}
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-approval` : undefined}
+ >
+ <div className="flex gap-2">
+ <div className={cn('flex shrink-0 flex-col items-center', !showLineBelow && 'pb-1')}>
+ <div className="min-h-[0.75rem] w-px flex-1 bg-border" />
+ <StepIconBox icon="wrench" variant="muted" iconSize="0.875em" className="my-1" />
+ {showLineBelow && <div className="min-h-[0.75rem] w-px flex-1 bg-border" />}
+ </div>
+
+ <div className="mt-2 flex flex-1 items-center justify-between">
+ <div className="flex w-full items-center justify-between gap-2">
+ <div className="flex items-center gap-2">
+ <span className="inline-flex flex-wrap items-center gap-1 font-sans text-xs font-medium leading-4 text-foreground">
+ {headingText}
+ <span className="rounded bg-muted px-1.5 py-0.5 text-xs text-muted-foreground">{toolName}</span>
+ </span>
+ {isDecided && (
+ <Icon
+ name={isDenied ? 'circle-xmark' : 'circle-check'}
+ size="0.875em"
+ className={cn('shrink-0', isDenied ? 'text-destructive' : 'text-green-600')}
+ />
+ )}
+ </div>
+ {!isDecided && !readOnly && selectedDenyOption && (
+ <Button
+ size="sm"
+ variant="secondary"
+ disabled={interactionsLocked}
+ onClick={() => onDenyOptionChange?.(null)}
+ >
+ Back
+ </Button>
+ )}
+ </div>
+ {!isDecided && !readOnly && !selectedDenyOption && (
+ <div className="flex gap-2">
+ {approveOptions.map(option => (
+ <Button
+ key={option.id}
+ size="sm"
+ variant={optionVariant(option)}
+ disabled={interactionsLocked}
+ onClick={() => onSelect(option.id)}
+ >
+ {option.variant === 'primary' && <Icon name="check" size="0.75em" className="mr-1" />}
+ {option.label}
+ </Button>
+ ))}
+ {denyOptions.map(option => (
+ <Button
+ key={option.id}
+ size="sm"
+ variant={optionVariant(option)}
+ disabled={interactionsLocked}
+ onClick={() => {
+ if (option.requiresReason) {
+ onDenyOptionChange?.(option.id);
+ } else {
+ onSelect(option.id);
+ }
+ }}
+ >
+ {option.label}
+ </Button>
+ ))}
+ </div>
+ )}
+ </div>
+ </div>
+
+ {!isDecided && !readOnly && selectedDenyOption && (
+ <div className="flex flex-col gap-1 pl-8 pt-3">
+ {(selectedDenyOption.confirm?.title || selectedDenyOption.confirm?.description) && (
+ <div className="flex flex-col gap-0.5">
+ {selectedDenyOption.confirm.title && (
+ <span className="text-xs font-medium text-foreground">{selectedDenyOption.confirm.title}</span>
+ )}
+ {selectedDenyOption.confirm.description && (
+ <span className="text-xs text-muted-foreground">{selectedDenyOption.confirm.description}</span>
+ )}
+ </div>
+ )}
+ {selectedDenyOption.grants && selectedDenyOption.grants.length > 0 && (
+ <div className="flex flex-wrap items-center gap-1">
+ <span className="text-xs text-muted-foreground">Grants:</span>
+ {selectedDenyOption.grants.map(grant => (
+ <span key={grant} className="rounded bg-muted px-1.5 py-0.5 text-xs text-muted-foreground">
+ {grant}
+ </span>
+ ))}
+ </div>
+ )}
+ <div className="flex gap-2">
+ <input
+ placeholder="Enter reason for denial"
+ aria-label="Reason for denial"
+ aria-invalid={showReasonError || undefined}
+ aria-describedby={showReasonError ? 'aui-denial-reason-error' : undefined}
+ value={denialReason}
+ disabled={interactionsLocked}
+ onChange={e => onDenialReasonChange?.(e.target.value)}
+ className={cn(
+ 'h-6 flex-1 rounded border border-input bg-background px-2 text-xs text-foreground',
+ 'focus:outline-none focus:ring-1 focus:ring-ring',
+ )}
+ />
+ <Button size="sm" disabled={interactionsLocked} onClick={onReasonSubmit}>
+ Submit
+ </Button>
+ </div>
+ {showReasonError && (
+ <span id="aui-denial-reason-error" className="text-xs text-destructive" role="alert">
+ Reason is required
+ </span>
+ )}
+ </div>
+ )}
+
+ {isDecided && status?.reason && (
+ <div className="pl-8 pt-2">
+ <span className="text-xs text-muted-foreground">Reason: {status.reason}</span>
+ </div>
+ )}
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ ToolApprovalBar: typeof ToolApprovalBar;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ToolCallCard.tsx b/packages/trueforge-ui-sdk/src/atoms/ToolCallCard.tsx
new file mode 100644
index 000000000..54b0e0304
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ToolCallCard.tsx
@@ -0,0 +1,121 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+import { AgentStepRow, type AgentStepStatus } from './agent-chat/AgentStepRow.js';
+import { cn } from './lib/cn.js';
+
+export type ToolCallStatus = 'running' | 'success' | 'error';
+
+export type ToolCallCardProps = {
+ icon?: string;
+ iconClassName?: string;
+ iconVariant?: 'primary' | 'muted';
+ toolName: string;
+ expanded?: boolean;
+ onToggle?: () => void;
+ awaiting?: boolean;
+ awaitingText?: string;
+ status?: ToolCallStatus;
+ exitCode?: number | null;
+ showExpandChevron?: boolean;
+ showResponseLine?: boolean;
+ responseIcon?: ReactNode;
+ approvalSlot?: ReactNode;
+ requestSlot?: ReactNode;
+ responseSlot?: ReactNode;
+ highlightCard?: boolean;
+ className?: string;
+ mcpServerName?: string;
+ dataTestPrefix?: string;
+};
+
+const DEFAULT_AWAITING_TEXT = 'Awaiting Response...';
+
+export function ToolCallCard({
+ icon = 'mcp-server',
+ iconClassName,
+ iconVariant,
+ toolName,
+ expanded = false,
+ onToggle,
+ awaiting = false,
+ awaitingText = DEFAULT_AWAITING_TEXT,
+ status: explicitStatus,
+ exitCode,
+ showExpandChevron = true,
+ showResponseLine = false,
+ approvalSlot,
+ requestSlot,
+ responseSlot,
+ highlightCard = false,
+ className,
+ mcpServerName: _mcpServerName,
+ dataTestPrefix,
+}: ToolCallCardProps) {
+ const hasApproval = !!approvalSlot;
+ const hasRequest = !!requestSlot;
+ const hasResponse = !!responseSlot;
+ const showConnector = hasApproval || hasRequest || hasResponse;
+ const isExpandable = showExpandChevron && (hasRequest || hasResponse);
+
+ let derivedStatus: AgentStepStatus = 'idle';
+ if (explicitStatus) derivedStatus = explicitStatus;
+ else if (awaiting) derivedStatus = 'running';
+ else if (exitCode === 0) derivedStatus = 'success';
+ else if (exitCode != null) derivedStatus = 'error';
+ else if (showResponseLine) derivedStatus = 'success';
+
+ const statusText = awaiting ? awaitingText : undefined;
+ const isCubeIcon = icon === 'cube';
+ const derivedIconVariant = iconVariant || (isCubeIcon ? 'primary' : 'muted');
+ const derivedIconSize = isCubeIcon ? '0.75em' : undefined;
+
+ return (
+ <div
+ className={cn(
+ 'aui-tool-call-card flex min-w-0 flex-col',
+ highlightCard ? 'rounded-md p-1 -mx-1' : 'mx-0 mt-2 p-0',
+ className,
+ )}
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-tool-call-card` : undefined}
+ >
+ <AgentStepRow
+ icon={icon}
+ iconClassName={iconClassName}
+ iconVariant={derivedIconVariant}
+ iconSize={derivedIconSize}
+ title={toolName}
+ expandable={isExpandable}
+ expanded={expanded}
+ onToggle={onToggle}
+ status={derivedStatus}
+ statusText={statusText}
+ showConnector={showConnector}
+ showContentConnector={true}
+ showPersistentContentConnector={!hasApproval}
+ dataTestPrefix={dataTestPrefix ? `${dataTestPrefix}-header` : undefined}
+ persistentChildren={
+ <>
+ {approvalSlot}
+ {expanded && showResponseLine && responseSlot && (
+ <div data-testid={dataTestPrefix ? `${dataTestPrefix}-response` : undefined}>{responseSlot}</div>
+ )}
+ </>
+ }
+ >
+ {requestSlot && (
+ <div className="py-2 pt-0" data-testid={dataTestPrefix ? `${dataTestPrefix}-request` : undefined}>
+ {requestSlot}
+ </div>
+ )}
+ </AgentStepRow>
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ ToolCallCard: typeof ToolCallCard;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ToolCallContentBlock.tsx b/packages/trueforge-ui-sdk/src/atoms/ToolCallContentBlock.tsx
new file mode 100644
index 000000000..b6d0c049f
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ToolCallContentBlock.tsx
@@ -0,0 +1,165 @@
+'use client';
+
+import { useState } from 'react';
+
+import { Icon } from '../icons/Icon.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+import { cn } from './lib/cn.js';
+import { MonacoEditorCore } from './MonacoEditorCore.js';
+import { Dialog, DialogContent, DialogHeader, DialogTitle } from './primitives/Dialog.js';
+import { IconButton } from './primitives/IconButton.js';
+
+export type ToolCallContentBlockProps = {
+ title: string;
+ content: string;
+ isJson?: boolean;
+ copyValue?: string;
+ maxHeight?: string;
+ resizable?: boolean;
+ fullscreen?: boolean;
+ onFullscreenChange?: (fullscreen: boolean) => void;
+ contentHeightRem?: number;
+ contentRef?: (node: HTMLDivElement | null) => void;
+ dataTestPrefix?: string;
+ className?: string;
+};
+
+function JsonEditor({
+ content,
+ height,
+ autoHeight = false,
+ maxHeight,
+}: {
+ content: string;
+ height?: string | number;
+ autoHeight?: boolean;
+ maxHeight?: string | number;
+}) {
+ return (
+ <MonacoEditorCore
+ language="json"
+ value={content}
+ height={height}
+ autoHeight={autoHeight}
+ maxHeight={maxHeight}
+ options={{
+ readOnly: true,
+ minimap: { enabled: false },
+ scrollBeyondLastLine: false,
+ wordWrap: 'on',
+ lineNumbers: 'on',
+ folding: true,
+ fontSize: 12,
+ }}
+ className="!border-0"
+ />
+ );
+}
+
+export function ToolCallContentBlock({
+ title,
+ content,
+ isJson = true,
+ copyValue,
+ maxHeight = '10.5rem',
+ resizable = false,
+ fullscreen = false,
+ onFullscreenChange,
+ contentHeightRem = 1.5,
+ contentRef,
+ dataTestPrefix,
+ className,
+}: ToolCallContentBlockProps) {
+ const Markdown = useSlot('Markdown');
+ const [copied, setCopied] = useState(false);
+
+ const handleCopy = () => {
+ const val = copyValue ?? content;
+ void navigator.clipboard.writeText(val).then(() => {
+ setCopied(true);
+ setTimeout(() => setCopied(false), 1500);
+ });
+ };
+
+ const bodyStyle = resizable
+ ? {
+ height: `${Math.min(contentHeightRem, 10)}rem`,
+ resize: 'vertical' as const,
+ padding: '0.25rem',
+ }
+ : {
+ padding: '0.25rem',
+ };
+
+ return (
+ <div
+ className={cn(
+ 'aui-tool-call-content-block flex flex-col font-sans text-xs font-medium leading-4 text-foreground',
+ className,
+ )}
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-content-block` : 'tfy-tool-call-content-block'}
+ data-content={content}
+ >
+ <div className="flex items-center justify-between rounded-t-lg border border-primary/30 bg-primary/10 px-3 py-1">
+ <div className="font-sans text-xs font-medium text-primary">{title}</div>
+ <div className="flex items-center gap-1">
+ <button
+ type="button"
+ onClick={handleCopy}
+ className="inline-flex size-6 cursor-pointer items-center justify-center rounded text-muted-foreground transition-colors hover:text-foreground"
+ aria-label="Copy"
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-copy` : undefined}
+ >
+ <Icon name={copied ? 'check' : 'clone'} size={14} />
+ </button>
+ <button
+ type="button"
+ onClick={() => onFullscreenChange?.(true)}
+ className="inline-flex size-6 cursor-pointer items-center justify-center rounded text-muted-foreground transition-colors hover:text-foreground"
+ aria-label="Expand"
+ >
+ <Icon name="expand-alt" size={14} />
+ </button>
+ </div>
+ </div>
+ <div
+ ref={resizable ? contentRef : undefined}
+ className={cn(
+ 'relative min-h-[1.875rem] rounded-b-lg border border-t-0 border-border bg-background',
+ resizable && 'overflow-y-auto',
+ )}
+ style={bodyStyle}
+ >
+ {isJson ? (
+ <JsonEditor content={content} autoHeight maxHeight={maxHeight} />
+ ) : (
+ <div className="overflow-y-auto" style={maxHeight ? { maxHeight } : undefined}>
+ <Markdown content={content} className="text-xs text-muted-foreground" />
+ </div>
+ )}
+ </div>
+
+ {fullscreen && (
+ <Dialog open onOpenChange={open => onFullscreenChange?.(open)}>
+ <DialogContent className="flex h-[80vh] max-w-4xl flex-col">
+ <DialogHeader className="flex flex-row items-center justify-between gap-2">
+ <DialogTitle>{title}</DialogTitle>
+ <IconButton variant="ghost" onClick={() => onFullscreenChange?.(false)} aria-label="Minimize">
+ <Icon name="compress" size="0.875em" />
+ </IconButton>
+ </DialogHeader>
+ <div className="min-h-0 flex-1">
+ <JsonEditor content={content} height="100%" />
+ </div>
+ </DialogContent>
+ </Dialog>
+ )}
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ ToolCallContentBlock: typeof ToolCallContentBlock;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ToolGroupCard.tsx b/packages/trueforge-ui-sdk/src/atoms/ToolGroupCard.tsx
new file mode 100644
index 000000000..ebb8ee21c
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ToolGroupCard.tsx
@@ -0,0 +1,72 @@
+import type { ReactNode } from 'react';
+
+import { Icon } from '../icons/Icon.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+import { cn } from './lib/cn.js';
+
+export type ToolGroupCardProps = {
+ toolCallCount: number;
+ expanded: boolean;
+ active?: boolean;
+ onToggle: () => void;
+ children: ReactNode;
+ className?: string;
+};
+
+export function ToolGroupCard({
+ toolCallCount,
+ expanded,
+ active = false,
+ onToggle,
+ children,
+ className,
+}: ToolGroupCardProps) {
+ const Accordion = useSlot('Accordion');
+ const AccordionSummary = useSlot('AccordionSummary');
+ const AccordionDetails = useSlot('AccordionDetails');
+ const label = `${toolCallCount} tool ${toolCallCount === 1 ? 'call' : 'calls'}`;
+
+ return (
+ <Accordion
+ data-slot="tool-group-card"
+ expanded={expanded}
+ onChange={() => onToggle()}
+ background="transparent"
+ className={cn('aui-tool-group-card group/tool-group w-full', className)}
+ sx={{ margin: 0, border: 'none', boxShadow: 'none' }}
+ >
+ <AccordionSummary
+ hideIcon
+ disableRipple
+ sx={{
+ padding: 0,
+ minHeight: 0,
+ '&.Mui-expanded': { minHeight: 0 },
+ '&:hover': { backgroundColor: 'transparent' },
+ '& .MuiAccordionSummary-content': { margin: 0, width: '100%' },
+ }}
+ >
+ <div className="text-muted-foreground hover:text-foreground flex origin-left items-center gap-2 py-1.5 text-sm transition-[color,scale] active:scale-[0.98]">
+ {active && <Icon name="loader" className="size-3 shrink-0 animate-spin [animation-duration:0.6s]" />}
+ <span className="text-xs font-medium">{label}</span>
+ <Icon
+ name="chevron-down"
+ className={cn(
+ 'size-3 shrink-0 transition-transform duration-200 ease-[cubic-bezier(0.32,0.72,0,1)]',
+ expanded ? 'rotate-0' : '-rotate-90',
+ )}
+ />
+ </div>
+ </AccordionSummary>
+ <AccordionDetails sx={{ padding: 0 }}>
+ <div className="mt-1 flex flex-col gap-2 text-foreground">{children}</div>
+ </AccordionDetails>
+ </Accordion>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ ToolGroupCard: typeof ToolGroupCard;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/UserMessageActionBar.tsx b/packages/trueforge-ui-sdk/src/atoms/UserMessageActionBar.tsx
new file mode 100644
index 000000000..a8fe325c0
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/UserMessageActionBar.tsx
@@ -0,0 +1,64 @@
+'use client';
+
+import { Icon } from '../icons/Icon.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+import { cn } from './lib/cn.js';
+import { IconButton } from './primitives/IconButton.js';
+
+export type UserMessageActionBarProps = {
+ isCopied: boolean;
+ editDisabled?: boolean;
+ createdAt?: Date | string;
+ onCopy: () => void;
+ onEdit: () => void;
+ onRetry: () => void;
+ className?: string;
+};
+
+const actionBtnClass = 'h-6 w-6 text-muted-foreground hover:text-foreground [&_svg]:size-3.5';
+
+export function UserMessageActionBar({
+ isCopied,
+ editDisabled,
+ createdAt,
+ onCopy,
+ onEdit,
+ onRetry,
+ className,
+}: UserMessageActionBarProps) {
+ const MessageTimestamp = useSlot('MessageTimestamp');
+
+ return (
+ <div className={cn('aui-user-action-bar-root animate-in fade-in flex items-center gap-1 duration-200', className)}>
+ <MessageTimestamp createdAt={createdAt} className="mr-1" />
+ <IconButton
+ aria-label="Try again"
+ tooltip="Try again"
+ variant="ghost"
+ className={actionBtnClass}
+ onClick={onRetry}
+ >
+ <Icon name="rotate-right" size="0.875em" />
+ </IconButton>
+ <IconButton
+ aria-label="Edit"
+ tooltip="Edit"
+ variant="ghost"
+ className={actionBtnClass}
+ disabled={editDisabled}
+ onClick={onEdit}
+ >
+ <Icon name="pencil" size="0.875em" />
+ </IconButton>
+ <IconButton aria-label="Copy" tooltip="Copy" variant="ghost" className={actionBtnClass} onClick={onCopy}>
+ <Icon name={isCopied ? 'check' : 'clone'} size="0.875em" />
+ </IconButton>
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ UserMessageActionBar: typeof UserMessageActionBar;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/UserMessageBubble.tsx b/packages/trueforge-ui-sdk/src/atoms/UserMessageBubble.tsx
new file mode 100644
index 000000000..09f13b39f
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/UserMessageBubble.tsx
@@ -0,0 +1,41 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+import { cn } from './lib/cn.js';
+
+export type UserMessageBubbleProps = {
+ text: string;
+ attachments?: ReactNode;
+ editAction?: ReactNode;
+ className?: string;
+};
+
+export function UserMessageBubble({ text, attachments, editAction, className }: UserMessageBubbleProps) {
+ return (
+ <div
+ data-slot="aui_user-message-root"
+ className={cn('group/user-message flex w-full min-w-0 flex-col items-end gap-1', className)}
+ >
+ {attachments}
+ <div
+ data-slot="aui_user-message-content"
+ style={{ borderRadius: 'var(--composer-radius, 1.5rem)' }}
+ className="max-w-[min(80%,100%)] min-w-0 bg-[var(--user-bubble,hsl(var(--primary)))] px-3 py-2 text-sm text-[var(--user-bubble-foreground,hsl(var(--primary-foreground)))] whitespace-pre-wrap break-words sm:px-4 sm:py-2.5"
+ >
+ {text}
+ </div>
+ {editAction && (
+ <div className="flex max-w-[min(80%,100%)] justify-end opacity-0 transition-opacity group-hover/user-message:opacity-100 focus-within:opacity-100">
+ {editAction}
+ </div>
+ )}
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ UserMessageBubble: typeof UserMessageBubble;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/UserMessageEdit.tsx b/packages/trueforge-ui-sdk/src/atoms/UserMessageEdit.tsx
new file mode 100644
index 000000000..09d86a16d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/UserMessageEdit.tsx
@@ -0,0 +1,43 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+import { forwardRef } from 'react';
+
+import { cn } from './lib/cn.js';
+
+export type UserMessageEditProps = {
+ /** Timestamp node rendered beside the "User" label. */
+ timestamp?: ReactNode;
+ /** Read-only attachments shown above the input while editing. */
+ attachments?: ReactNode;
+ input: ReactNode;
+ footer: ReactNode;
+ className?: string;
+};
+
+export const UserMessageEdit = forwardRef<HTMLDivElement, UserMessageEditProps & HTMLAttributes<HTMLDivElement>>(
+ function UserMessageEdit({ timestamp, attachments, input, footer, className, ...rest }, ref) {
+ return (
+ <div
+ ref={ref}
+ data-slot="aui_user-message-edit"
+ className={cn('flex flex-col gap-2 w-full', className)}
+ {...rest}
+ >
+ {(timestamp || attachments) && (
+ <div className="flex items-center gap-2 text-sm text-muted-foreground">
+ <span className="font-medium text-foreground">User</span>
+ {timestamp}
+ </div>
+ )}
+ {attachments && <div className="flex flex-wrap gap-1">{attachments}</div>}
+ <div className="w-full">{input}</div>
+ <div>{footer}</div>
+ </div>
+ );
+ },
+);
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ UserMessageEdit: typeof UserMessageEdit;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/WelcomeScreen.tsx b/packages/trueforge-ui-sdk/src/atoms/WelcomeScreen.tsx
new file mode 100644
index 000000000..bb9a9e555
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/WelcomeScreen.tsx
@@ -0,0 +1,68 @@
+import { Sparkle } from 'lucide-react';
+import type { ReactNode } from 'react';
+
+import { BrandIcon } from '../theme/brand.js';
+import { useOptionalThemePreset } from '../theme/ThemeProvider.js';
+import { cn } from './lib/cn.js';
+
+export type WelcomeScreenProps = {
+ heading?: string;
+ icon?: ReactNode;
+ className?: string;
+};
+
+export function WelcomeScreen({ heading = 'How can I help you today?', icon, className }: WelcomeScreenProps) {
+ const preset = useOptionalThemePreset();
+ const resolvedIcon =
+ icon !== undefined ? (
+ icon
+ ) : preset === 'chatgpt' ? null : preset === 'claude' ? (
+ <Sparkle aria-hidden className="size-5 fill-current text-primary" />
+ ) : (
+ <BrandIcon className={preset === 'gemini' ? 'size-5' : 'size-10'} />
+ );
+
+ return (
+ <div
+ data-preset={preset}
+ className={cn(
+ 'aui-thread-welcome-root relative isolate mb-6 flex flex-col items-center px-4 text-center text-foreground',
+ preset === 'gemini' && 'py-8',
+ className,
+ )}
+ >
+ {preset === 'gemini' && (
+ <div
+ aria-hidden
+ className="pointer-events-none absolute left-1/2 top-1/2 -z-10 size-64 -translate-x-1/2 -translate-y-1/2 rounded-full bg-primary/20 blur-3xl motion-safe:animate-pulse motion-reduce:animate-none [animation-duration:4s]"
+ />
+ )}
+ {resolvedIcon !== null && (
+ <div
+ className={cn(
+ 'fill-mode-both mb-4 motion-safe:animate-in motion-safe:fade-in motion-safe:slide-in-from-bottom-1 motion-reduce:animate-none',
+ preset === 'claude' ? 'duration-300' : 'duration-200',
+ )}
+ >
+ {resolvedIcon}
+ </div>
+ )}
+ <h1
+ className={cn(
+ 'aui-thread-welcome-message-inner fill-mode-both text-2xl motion-safe:animate-in motion-safe:fade-in motion-safe:slide-in-from-bottom-1 motion-reduce:animate-none',
+ preset === 'truefoundry' ? 'font-semibold' : 'font-normal',
+ resolvedIcon !== null && 'delay-75',
+ preset === 'gemini' ? 'text-[1.75rem] leading-tight duration-300' : 'duration-200',
+ )}
+ >
+ {heading}
+ </h1>
+ </div>
+ );
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ WelcomeScreen: typeof WelcomeScreen;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/adapters/AgentStepsCardAdapter.tsx b/packages/trueforge-ui-sdk/src/atoms/adapters/AgentStepsCardAdapter.tsx
new file mode 100644
index 000000000..83f16b6da
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/adapters/AgentStepsCardAdapter.tsx
@@ -0,0 +1,82 @@
+import type { ReactNode } from 'react';
+
+import { Icon } from '../../icons/Icon.js';
+import { cn } from '../lib/cn.js';
+import { Accordion, AccordionDetails, AccordionSummary } from '../primitives/Accordion.js';
+import { Spinner } from '../primitives/Spinner.js';
+
+export type AgentStepsCardProps = {
+ toolCount: number;
+ thinkingCount: number;
+ expanded: boolean;
+ active?: boolean;
+ onToggle: () => void;
+ children: ReactNode;
+ borderColor?: string;
+ background?: string;
+ dataTestPrefix?: string;
+ className?: string;
+};
+
+export function AgentStepsCard({
+ toolCount,
+ thinkingCount,
+ expanded,
+ active = false,
+ onToggle,
+ children,
+ borderColor,
+ background = 'transparent',
+ dataTestPrefix,
+ className,
+}: AgentStepsCardProps) {
+ const toolLabel = `${toolCount} tool ${toolCount === 1 ? 'call' : 'calls'}`;
+ const thinkingLabel = thinkingCount > 0 ? ` · ${thinkingCount} thought${thinkingCount === 1 ? '' : 's'}` : '';
+
+ return (
+ <Accordion
+ expanded={expanded}
+ onChange={() => onToggle()}
+ className={cn('aui-agent-steps-card mb-3 rounded-lg border border-border', className)}
+ style={{
+ background,
+ borderColor: borderColor ?? undefined,
+ }}
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-agent-steps-card` : undefined}
+ >
+ <AccordionSummary className="p-0">
+ <div className="flex w-full items-center gap-2 px-2 py-2 text-left text-xs">
+ <Icon
+ name={expanded ? 'chevron-down' : 'chevron-right'}
+ size="0.75em"
+ className="shrink-0 text-muted-foreground"
+ />
+ <span className="font-semibold text-foreground">Agent steps</span>
+ <span className="text-muted-foreground">
+ · {toolLabel}
+ {thinkingLabel}
+ </span>
+ {active && (
+ <div className="ml-auto">
+ <Spinner size={12} className="text-primary" />
+ </div>
+ )}
+ </div>
+ </AccordionSummary>
+ <AccordionDetails>
+ <div
+ className="space-y-3 border-t border-border p-3"
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-content` : undefined}
+ >
+ {children}
+ </div>
+ </AccordionDetails>
+ </Accordion>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AgentStepsCard: typeof AgentStepsCard;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/adapters/AskUserPromptAdapter.tsx b/packages/trueforge-ui-sdk/src/atoms/adapters/AskUserPromptAdapter.tsx
new file mode 100644
index 000000000..3d53a59f9
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/adapters/AskUserPromptAdapter.tsx
@@ -0,0 +1,257 @@
+import { Icon } from '../../icons/Icon.js';
+import { cn } from '../lib/cn.js';
+import { Button } from '../primitives/Button.js';
+import { IconButton } from '../primitives/IconButton.js';
+
+export type Question = {
+ id: string;
+ question: string;
+ options: string[];
+};
+
+export type AnsweredQuestion = Question & {
+ answer: string;
+ isCustom: boolean;
+};
+
+export type AskUserAnswerDraft = {
+ radioValue: string;
+ custom: string;
+};
+
+export const ASK_USER_CUSTOM_OPTION = '__tfy_ask_user_question_custom__';
+
+export type AskUserPromptProps = {
+ questions: Question[];
+ answeredQuestions?: AnsweredQuestion[];
+ onSubmit: () => void;
+ currentQuestion?: Question;
+ currentQuestionIndex?: number;
+ currentAnswer?: AskUserAnswerDraft;
+ totalQuestions?: number;
+ isMultiQuestion?: boolean;
+ isLastQuestion?: boolean;
+ allQuestionsAnswered?: boolean;
+ isSubmitDisabled?: boolean;
+ isSubmitAllDisabled?: boolean;
+ onCurrentQuestionIndexChange?: (index: number) => void;
+ onCurrentAnswerChange?: (questionId: string, update: Partial<AskUserAnswerDraft>) => void;
+ readOnly?: boolean;
+ dataTestPrefix?: string;
+ className?: string;
+};
+
+export function AskUserPrompt({
+ questions,
+ answeredQuestions = [],
+ onSubmit,
+ currentQuestion,
+ currentQuestionIndex = 0,
+ currentAnswer = { radioValue: '', custom: '' },
+ totalQuestions = questions.length,
+ isMultiQuestion: isMultiQuestionProp,
+ isLastQuestion: isLastQuestionProp,
+ allQuestionsAnswered = false,
+ isSubmitDisabled = true,
+ isSubmitAllDisabled = true,
+ onCurrentQuestionIndexChange,
+ onCurrentAnswerChange,
+ readOnly = false,
+ dataTestPrefix,
+ className,
+}: AskUserPromptProps) {
+ const isMultiQuestion = isMultiQuestionProp ?? totalQuestions > 1;
+ const isLastQuestion = isLastQuestionProp ?? currentQuestionIndex === totalQuestions - 1;
+
+ if (questions.length === 0) {
+ if (answeredQuestions.length === 0) return null;
+ return (
+ <div className={cn('aui-ask-user-prompt mt-2 flex flex-col gap-3', className)}>
+ {answeredQuestions.map(q => (
+ <div key={q.id} data-testid={dataTestPrefix ? `${dataTestPrefix}-answered-${q.id}` : undefined}>
+ <div className="flex items-center justify-between rounded-t-lg border border-primary/30 bg-primary/10 px-4 py-2">
+ <div className="font-sans text-xs font-medium text-primary">{q.question}</div>
+ <div className="flex h-fit shrink-0 items-center gap-1 rounded border border-primary/40 bg-background px-2 py-0.5 text-[0.6875rem] font-medium text-muted-foreground">
+ <span className="leading-tight">Answered</span>
+ </div>
+ </div>
+ <div className="flex items-center gap-2 rounded-b-lg border border-t-0 border-border px-4 py-3">
+ <Icon name="circle-check" size="0.875em" className="shrink-0 text-primary" />
+ <span className="font-sans text-[0.8125rem] font-medium text-foreground">
+ {q.isCustom ? `Other: ${q.answer}` : q.answer}
+ </span>
+ </div>
+ </div>
+ ))}
+ </div>
+ );
+ }
+
+ if (!currentQuestion) return null;
+
+ const isCustomSelected = currentAnswer.radioValue === ASK_USER_CUSTOM_OPTION;
+
+ const handleOptionSelect = (value: string) => {
+ if (readOnly) return;
+ onCurrentAnswerChange?.(currentQuestion.id, { radioValue: value });
+ };
+
+ return (
+ <div
+ className={cn('aui-ask-user-prompt', className)}
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-question-card` : undefined}
+ >
+ <div className="flex items-center justify-between rounded-t-lg border border-primary/30 bg-primary/10 px-4 py-2">
+ <div className="font-sans text-sm font-medium text-primary">
+ {totalQuestions > 1 ? 'Questions' : currentQuestion.question}
+ </div>
+ {readOnly ? (
+ <div className="flex h-fit shrink-0 items-center gap-1 rounded border border-primary/40 bg-background px-2 py-0.5 text-[0.6875rem] font-medium text-muted-foreground">
+ <span className="leading-tight">Unanswered</span>
+ </div>
+ ) : null}
+ {!readOnly && isMultiQuestion && (
+ <div className="flex items-center gap-1">
+ <IconButton
+ aria-label="Previous question"
+ variant="ghost"
+ onClick={() => onCurrentQuestionIndexChange?.(Math.max(0, currentQuestionIndex - 1))}
+ disabled={currentQuestionIndex === 0}
+ className="text-foreground"
+ >
+ <Icon name="chevron-left" size="0.75em" />
+ </IconButton>
+ <IconButton
+ aria-label="Next question"
+ variant="ghost"
+ onClick={() => onCurrentQuestionIndexChange?.(Math.min(totalQuestions - 1, currentQuestionIndex + 1))}
+ disabled={currentQuestionIndex === totalQuestions - 1}
+ className="text-foreground"
+ >
+ <Icon name="chevron-right" size="0.75em" />
+ </IconButton>
+ <div className="ml-1 rounded bg-primary/20 px-2 py-1 font-sans text-xs font-medium text-foreground">
+ <span> {currentQuestionIndex + 1} </span> <span> of </span> <span> {totalQuestions} </span>
+ </div>
+ </div>
+ )}
+ </div>
+
+ <div className="flex flex-col gap-4 rounded-b-lg border border-t-0 border-border px-4 py-3">
+ <div className="flex flex-col gap-3">
+ {isMultiQuestion && (
+ <div className="font-sans text-xs font-medium text-foreground">
+ {currentQuestion.question || 'What would you like to do?'}
+ </div>
+ )}
+ <div
+ className="flex flex-col gap-3 overflow-visible"
+ role="radiogroup"
+ aria-label={currentQuestion.question || 'Answer options'}
+ >
+ {currentQuestion.options.map((opt, index) => {
+ const isSelected = currentAnswer.radioValue === opt;
+ return (
+ <label
+ key={`${index}:${opt}`}
+ className={cn(
+ 'flex w-fit items-start gap-x-2 overflow-visible',
+ readOnly ? 'cursor-default' : 'cursor-pointer',
+ )}
+ >
+ <input
+ type="radio"
+ value={opt}
+ disabled={readOnly || !currentQuestion.id}
+ name={`ask-user-question-option-${currentQuestion.id}`}
+ checked={isSelected}
+ onChange={() => handleOptionSelect(opt)}
+ className="mt-0.5 accent-primary"
+ />
+ <span className="min-w-0 font-sans text-[0.8125rem] font-medium leading-snug text-foreground">
+ {opt}
+ </span>
+ </label>
+ );
+ })}
+
+ <label
+ className={cn(
+ 'flex items-center gap-x-2 overflow-visible',
+ readOnly ? 'cursor-default' : 'cursor-pointer',
+ )}
+ >
+ <input
+ type="radio"
+ disabled={readOnly || !currentQuestion.id}
+ value={ASK_USER_CUSTOM_OPTION}
+ name={`ask-user-question-option-${currentQuestion.id}`}
+ checked={isCustomSelected}
+ onChange={() => handleOptionSelect(ASK_USER_CUSTOM_OPTION)}
+ className="accent-primary"
+ />
+ <div className="min-w-0 flex-1">
+ <input
+ value={currentAnswer.custom}
+ disabled={readOnly || !currentQuestion.id}
+ onFocus={() =>
+ onCurrentAnswerChange?.(currentQuestion.id, {
+ radioValue: ASK_USER_CUSTOM_OPTION,
+ })
+ }
+ onChange={e => {
+ onCurrentAnswerChange?.(currentQuestion.id, {
+ custom: e.target.value,
+ radioValue: ASK_USER_CUSTOM_OPTION,
+ });
+ }}
+ placeholder="Other"
+ aria-label="Other (custom answer)"
+ className={cn(
+ 'h-6 w-full rounded border border-input bg-background px-2 text-[0.8125rem] text-foreground',
+ 'placeholder:text-[0.8125rem] focus:outline-none focus:ring-1 focus:ring-ring',
+ )}
+ />
+ </div>
+ </label>
+ </div>
+ </div>
+
+ {!readOnly && (
+ <div
+ className={cn('flex items-center', {
+ 'justify-between': isMultiQuestion,
+ 'justify-start': !isMultiQuestion,
+ })}
+ >
+ {isMultiQuestion && isLastQuestion && !allQuestionsAnswered ? (
+ <span className="text-xs font-medium text-destructive">Answer all questions to submit</span>
+ ) : (
+ <span />
+ )}
+ {isMultiQuestion && !isLastQuestion ? (
+ <Button
+ type="button"
+ size="sm"
+ onClick={() => onCurrentQuestionIndexChange?.(currentQuestionIndex + 1)}
+ disabled={isSubmitDisabled}
+ >
+ Next
+ </Button>
+ ) : (
+ <Button type="button" size="sm" onClick={onSubmit} disabled={isSubmitAllDisabled}>
+ Submit
+ </Button>
+ )}
+ </div>
+ )}
+ </div>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ AskUserPrompt: typeof AskUserPrompt;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/adapters/McpAuthPromptAdapter.tsx b/packages/trueforge-ui-sdk/src/atoms/adapters/McpAuthPromptAdapter.tsx
new file mode 100644
index 000000000..4768cfcff
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/adapters/McpAuthPromptAdapter.tsx
@@ -0,0 +1,71 @@
+import { Icon } from '../../icons/Icon.js';
+import { cn } from '../lib/cn.js';
+import { Button } from '../primitives/Button.js';
+
+export type McpServer = {
+ id: string;
+ name: string;
+};
+
+export type McpAuthPromptProps = {
+ servers: McpServer[];
+ onConnect: (serverId: string) => void;
+ onContinue?: () => void;
+ readOnly?: boolean;
+ title?: string;
+ dataTestPrefix?: string;
+ className?: string;
+};
+
+const DEFAULT_TITLE = 'MCP Authentication Required';
+
+export function McpAuthPrompt({
+ servers,
+ onConnect,
+ onContinue,
+ readOnly = false,
+ title = DEFAULT_TITLE,
+ dataTestPrefix,
+ className,
+}: McpAuthPromptProps) {
+ if (servers.length === 0) return null;
+
+ return (
+ <div
+ className={cn('aui-mcp-auth-prompt mt-2 overflow-hidden rounded-lg border border-border', className)}
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-mcp-auth-card` : undefined}
+ >
+ <div className="border-b border-primary/30 bg-primary/10 px-4 py-2">
+ <div className="font-sans text-sm font-medium text-primary">{title}</div>
+ </div>
+ <div className="flex flex-col gap-3 bg-background px-4 py-3">
+ {servers.map(server => (
+ <div key={server.id} className="flex items-center justify-between gap-4">
+ <div className="flex min-w-0 items-center gap-1.5 text-sm">
+ <span className="shrink-0 font-medium text-muted-foreground">MCP Server Name</span>
+ <span className="shrink-0 text-xs font-semibold text-muted-foreground">:</span>
+ <span className="truncate font-sans font-medium text-foreground">{server.name}</span>
+ </div>
+ <Button size="sm" disabled={readOnly} onClick={() => onConnect(server.id)} className="shrink-0">
+ Connect
+ <Icon name="external-link" size="0.75em" className="ml-1" />
+ </Button>
+ </div>
+ ))}
+ {onContinue && (
+ <div className="flex justify-end border-t border-border pt-2">
+ <Button size="sm" disabled={readOnly} onClick={onContinue}>
+ Continue
+ </Button>
+ </div>
+ )}
+ </div>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ McpAuthPrompt: typeof McpAuthPrompt;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/adapters/ReasoningCardAdapter.tsx b/packages/trueforge-ui-sdk/src/atoms/adapters/ReasoningCardAdapter.tsx
new file mode 100644
index 000000000..cbda7fab3
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/adapters/ReasoningCardAdapter.tsx
@@ -0,0 +1,73 @@
+import { useSlot } from '../../theme/SlotsProvider.js';
+import { AgentStepRow } from '../agent-chat/AgentStepRow.js';
+import { cn } from '../lib/cn.js';
+
+export type ReasoningCardProps = {
+ content: string;
+ isStreaming?: boolean;
+ expanded?: boolean;
+ onToggle?: () => void;
+ isMultiLine?: boolean;
+ reasoningTimeText?: string | null;
+ previewText?: string;
+ headingText?: string;
+ contentRef?: (node: HTMLDivElement | null) => void;
+ dataTestPrefix?: string;
+ className?: string;
+};
+
+export function ReasoningCard({
+ content,
+ isStreaming = false,
+ expanded = false,
+ onToggle,
+ isMultiLine = false,
+ reasoningTimeText,
+ headingText = 'Reasoning',
+ contentRef,
+ dataTestPrefix,
+ className,
+}: ReasoningCardProps) {
+ const Markdown = useSlot('Markdown');
+ const isShortText = !isStreaming && content.length > 0 && !isMultiLine;
+ const isExpandable = isShortText || isMultiLine || isStreaming;
+ const status = isStreaming ? 'running' : content.length > 0 ? 'success' : 'idle';
+ const title = isStreaming ? headingText : (reasoningTimeText ?? headingText);
+ const showContent = expanded && content.length > 0;
+
+ return (
+ <div
+ className={cn('aui-reasoning-card mt-2 flex min-w-0 flex-col', className)}
+ data-testid={
+ dataTestPrefix ? `${dataTestPrefix}-${isShortText ? 'reasoning-inline' : 'reasoning-accordion'}` : undefined
+ }
+ >
+ <AgentStepRow
+ icon={isStreaming ? 'brain' : 'brain-regular'}
+ iconVariant="primary"
+ title={title}
+ expandable={isExpandable}
+ expanded={expanded}
+ onToggle={onToggle}
+ status={status}
+ dataTestPrefix={dataTestPrefix}
+ >
+ {showContent && (
+ <div
+ ref={contentRef}
+ className="py-2 pt-0 font-sans text-sm font-normal text-muted-foreground"
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-content` : undefined}
+ >
+ <Markdown content={content} className="font-sans text-sm text-muted-foreground" />
+ </div>
+ )}
+ </AgentStepRow>
+ </div>
+ );
+}
+
+declare module '../../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ ReasoningCard: typeof ReasoningCard;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/agent-chat/AgentStepRow.tsx b/packages/trueforge-ui-sdk/src/atoms/agent-chat/AgentStepRow.tsx
new file mode 100644
index 000000000..02d71ff7c
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/agent-chat/AgentStepRow.tsx
@@ -0,0 +1,204 @@
+import type { ReactNode } from 'react';
+
+import { Icon } from '../../icons/Icon.js';
+import { cn } from '../lib/cn.js';
+import { Spinner } from '../primitives/Spinner.js';
+import { StatusDot } from './StatusDot.js';
+import { StepIconBox } from './StepIconBox.js';
+
+export type AgentStepStatus = 'idle' | 'running' | 'success' | 'error';
+
+export type AgentStepRowProps = {
+ icon: string;
+ iconVariant?: 'primary' | 'muted';
+ iconClassName?: string;
+ iconSize?: string | number;
+ title?: ReactNode;
+ label?: string;
+ body?: ReactNode;
+ expandable?: boolean;
+ expanded?: boolean;
+ onToggle?: () => void;
+ status?: AgentStepStatus;
+ statusText?: string;
+ showSpinner?: boolean;
+ showConnector?: boolean;
+ showContentConnector?: boolean;
+ showPersistentContentConnector?: boolean;
+ showChevronColumn?: boolean;
+ children?: ReactNode;
+ persistentChildren?: ReactNode;
+ dataTestPrefix?: string;
+ className?: string;
+ titleClassName?: string;
+ align?: 'center' | 'start';
+};
+
+export function AgentStepRow({
+ icon,
+ iconVariant = 'primary',
+ iconClassName,
+ iconSize,
+ title,
+ label,
+ body,
+ expandable = false,
+ expanded = false,
+ onToggle,
+ status = 'idle',
+ statusText,
+ showSpinner = false,
+ showConnector = false,
+ showContentConnector = true,
+ showPersistentContentConnector = true,
+ showChevronColumn = true,
+ children,
+ persistentChildren,
+ dataTestPrefix,
+ className,
+ titleClassName,
+ align = 'center',
+}: AgentStepRowProps) {
+ const hasChildren = !!children;
+ const hasPersistentChildren = !!persistentChildren;
+ const showExpandChevron = expandable && onToggle != null;
+ const isRunning = status === 'running';
+ const isSuccess = status === 'success';
+ const isError = status === 'error';
+ const alignStart = align === 'start';
+
+ return (
+ <div
+ className={cn('flex min-w-0 flex-col', className)}
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-step-row` : undefined}
+ >
+ <div className={cn('flex gap-2', alignStart ? 'items-start' : 'items-center')}>
+ {showChevronColumn &&
+ (showExpandChevron ? (
+ <button
+ type="button"
+ className="flex h-5 w-5 shrink-0 cursor-pointer items-center justify-center"
+ onClick={onToggle}
+ aria-expanded={expanded}
+ aria-label={expanded ? 'Collapse step' : 'Expand step'}
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-chevron` : undefined}
+ >
+ <Icon
+ name="chevron-right"
+ size="0.625rem"
+ className={cn(
+ 'shrink-0 text-muted-foreground transition-transform duration-300',
+ expanded && 'rotate-90',
+ )}
+ />
+ </button>
+ ) : (
+ <div className="w-5 shrink-0" />
+ ))}
+
+ <div className={cn('relative flex shrink-0 flex-col items-center', alignStart ? 'self-start' : 'self-center')}>
+ <StepIconBox icon={icon} variant={iconVariant} iconClassName={iconClassName} iconSize={iconSize} />
+ </div>
+
+ <div
+ className={cn('flex min-w-0 flex-1 flex-col justify-center', {
+ 'cursor-pointer': showExpandChevron,
+ })}
+ onClick={showExpandChevron ? onToggle : undefined}
+ >
+ {label && <span className="text-xs font-medium leading-none text-muted-foreground">{label}</span>}
+ {title && (
+ <div className="flex min-w-0 items-center gap-2">
+ <span
+ className={cn(
+ 'min-w-0 truncate font-sans text-[0.75rem] font-medium leading-5 text-foreground',
+ titleClassName,
+ )}
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-title` : undefined}
+ >
+ {title}
+ </span>
+ {isSuccess && (
+ <Icon
+ name="circle-check"
+ size="0.875rem"
+ className="shrink-0 text-green-600"
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-success-icon` : undefined}
+ />
+ )}
+ </div>
+ )}
+ {body && (
+ <div
+ className="mt-1 font-sans text-sm text-muted-foreground"
+ onClick={e => {
+ if (expanded && showExpandChevron) e.stopPropagation();
+ }}
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-body` : undefined}
+ >
+ {body}
+ </div>
+ )}
+ </div>
+
+ <div className={cn('flex shrink-0 items-center gap-2', alignStart ? 'self-start' : 'self-center')}>
+ {statusText && (
+ <span className="flex items-center gap-1">
+ {isRunning && <StatusDot colorClassName="bg-orange-500" />}
+ <span className="font-sans text-xs font-medium leading-4 text-muted-foreground">{statusText}</span>
+ </span>
+ )}
+ {!statusText && isRunning && (
+ <>
+ {showSpinner ? (
+ <div className="ml-1">
+ <Spinner size={12} />
+ </div>
+ ) : (
+ <StatusDot colorClassName="bg-orange-500" />
+ )}
+ </>
+ )}
+ {isError && (
+ <Icon
+ name="circle-xmark"
+ size="0.875rem"
+ className="text-destructive"
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-error-icon` : undefined}
+ />
+ )}
+ </div>
+ </div>
+
+ {expanded && hasChildren && (
+ <div
+ className="mt-2 flex min-w-0 gap-3"
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-expanded-content` : undefined}
+ >
+ {showChevronColumn && <div className="w-5 shrink-0" />}
+ {showContentConnector && showConnector && (
+ <div className="flex w-3 shrink-0 justify-center">
+ <div className="w-px bg-border" />
+ </div>
+ )}
+ <div className="min-w-0 flex-1">{children}</div>
+ </div>
+ )}
+
+ {hasPersistentChildren && (
+ <div
+ className="flex min-w-0 gap-3"
+ data-testid={dataTestPrefix ? `${dataTestPrefix}-persistent-content` : undefined}
+ >
+ {showChevronColumn && <div className="w-5 shrink-0" />}
+ {showPersistentContentConnector && showConnector && (
+ <div className="flex w-3 shrink-0 justify-center">
+ <div className="w-px bg-border" />
+ </div>
+ )}
+ <div className="min-w-0 flex-1">{persistentChildren}</div>
+ </div>
+ )}
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/agent-chat/StatusDot.tsx b/packages/trueforge-ui-sdk/src/atoms/agent-chat/StatusDot.tsx
new file mode 100644
index 000000000..004f21b38
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/agent-chat/StatusDot.tsx
@@ -0,0 +1,20 @@
+import { cn } from '../lib/cn.js';
+
+export type StatusDotProps = {
+ className?: string;
+ colorClassName?: string;
+};
+
+export function StatusDot({ className, colorClassName = 'bg-orange-500' }: StatusDotProps) {
+ return (
+ <span aria-hidden className={cn('relative inline-flex h-2 w-2 shrink-0', className)}>
+ <span
+ className={cn(
+ 'pointer-events-none absolute inline-flex h-full w-full rounded-full opacity-75 motion-safe:animate-ping motion-reduce:animate-none',
+ colorClassName,
+ )}
+ />
+ <span className={cn('relative inline-flex h-2 w-2 rounded-full', colorClassName)} />
+ </span>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/agent-chat/StepIconBox.tsx b/packages/trueforge-ui-sdk/src/atoms/agent-chat/StepIconBox.tsx
new file mode 100644
index 000000000..e984ecb2d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/agent-chat/StepIconBox.tsx
@@ -0,0 +1,28 @@
+import { Icon } from '../../icons/Icon.js';
+import { cn } from '../lib/cn.js';
+
+export type StepIconBoxProps = {
+ icon: string;
+ iconSize?: string | number;
+ variant?: 'primary' | 'muted';
+ className?: string;
+ iconClassName?: string;
+};
+
+export function StepIconBox({
+ icon,
+ iconSize = '0.75em',
+ variant = 'primary',
+ className,
+ iconClassName,
+}: StepIconBoxProps) {
+ return (
+ <div className={cn('flex size-5 shrink-0 items-center justify-center', className)}>
+ <Icon
+ name={icon}
+ size={iconSize}
+ className={cn(variant === 'primary' ? 'text-primary' : 'text-muted-foreground', iconClassName)}
+ />
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/draft/DraftCatalogProvider.tsx b/packages/trueforge-ui-sdk/src/atoms/draft/DraftCatalogProvider.tsx
new file mode 100644
index 000000000..00618fec6
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/draft/DraftCatalogProvider.tsx
@@ -0,0 +1,65 @@
+'use client';
+
+import { createContext, useContext, useEffect, useMemo, useState, type ReactNode } from 'react';
+
+import { useOptionalServer } from '../../server/ServerContext.js';
+import type { AgentSkill, ConnectorState, ModelSelection } from '../../server/types.js';
+
+type DraftCatalogValue = {
+ models: ModelSelection[];
+ skills: AgentSkill[];
+ connectors: ConnectorState[];
+ loading: boolean;
+ error: string | null;
+};
+
+const DraftCatalogContext = createContext<DraftCatalogValue | null>(null);
+
+export function DraftCatalogProvider({ children }: { children: ReactNode }) {
+ const server = useOptionalServer();
+ const [models, setModels] = useState<ModelSelection[]>([]);
+ const [skills, setSkills] = useState<AgentSkill[]>([]);
+ const [connectors, setConnectors] = useState<ConnectorState[]>([]);
+ const [loading, setLoading] = useState(false);
+ const [error, setError] = useState<string | null>(null);
+
+ useEffect(() => {
+ if (!server) return;
+ let cancelled = false;
+ setLoading(true);
+ setError(null);
+ void Promise.all([server.getModels(), server.getSkills(), server.getMcp()])
+ .then(([nextModels, nextSkills, nextMcp]) => {
+ if (cancelled) return;
+ setModels(nextModels);
+ setSkills(nextSkills);
+ setConnectors(nextMcp);
+ })
+ .catch((err: unknown) => {
+ if (!cancelled) {
+ setError(err instanceof Error ? err.message : 'Failed to load catalog.');
+ }
+ })
+ .finally(() => {
+ if (!cancelled) setLoading(false);
+ });
+ return () => {
+ cancelled = true;
+ };
+ }, [server]);
+
+ const value = useMemo(
+ () => ({ models, skills, connectors, loading, error }),
+ [models, skills, connectors, loading, error],
+ );
+
+ return <DraftCatalogContext.Provider value={value}>{children}</DraftCatalogContext.Provider>;
+}
+
+export function useDraftCatalog(): DraftCatalogValue {
+ const ctx = useContext(DraftCatalogContext);
+ if (ctx == null) {
+ return { models: [], skills: [], connectors: [], loading: false, error: null };
+ }
+ return ctx;
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/draft/DraftComposerSections.tsx b/packages/trueforge-ui-sdk/src/atoms/draft/DraftComposerSections.tsx
new file mode 100644
index 000000000..7c1656f29
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/draft/DraftComposerSections.tsx
@@ -0,0 +1,24 @@
+'use client';
+
+import type { ComposerLeftSectionProps, ComposerRightSectionProps } from '../ComposerSections.js';
+import { DraftCompositeSelector, DraftSelectionChips } from './DraftCompositeSelector.js';
+import { DraftModelSelector } from './DraftModelSelector.js';
+import { DraftReasoningEffortSelector } from './DraftReasoningEffortSelector.js';
+
+export function DraftComposerLeftSection({ disabled, isRunning, onAttach }: ComposerLeftSectionProps) {
+ return (
+ <div className="flex min-w-0 flex-wrap items-center gap-1.5">
+ <DraftCompositeSelector disabled={disabled} isRunning={isRunning} onAttach={onAttach} />
+ <DraftSelectionChips />
+ </div>
+ );
+}
+
+export function DraftComposerRightSection({ disabled, isRunning }: ComposerRightSectionProps) {
+ return (
+ <div className="flex min-w-0 items-center gap-1">
+ <DraftModelSelector disabled={disabled} isRunning={isRunning} />
+ <DraftReasoningEffortSelector disabled={disabled} isRunning={isRunning} />
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/draft/DraftCompositeSelector.tsx b/packages/trueforge-ui-sdk/src/atoms/draft/DraftCompositeSelector.tsx
new file mode 100644
index 000000000..7fb448d35
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/draft/DraftCompositeSelector.tsx
@@ -0,0 +1,301 @@
+'use client';
+
+import { useTrueFoundryAgentSpec, useTrueFoundryUpdateAgentSpec } from '@truefoundry/assistant-ui-runtime';
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
+
+import { Icon } from '../../icons/Icon.js';
+import type { AgentSkill, ConnectorState, McpServerMount, SkillMount } from '../../server/types.js';
+import { auiButtonClass } from '../lib/buttonClasses.js';
+import { cn } from '../lib/cn.js';
+import { useCompactLayout } from '../lib/CompactLayoutContext.js';
+import { useIsMobile } from '../lib/useIsMobile.js';
+import { BottomSheet } from '../primitives/BottomSheet.js';
+import { useDraftCatalog } from './DraftCatalogProvider.js';
+
+type AttachTab = 'connectors' | 'skills' | 'files';
+
+const TABS: { id: AttachTab; label: string; icon: string }[] = [
+ { id: 'connectors', label: 'Connectors', icon: 'plug' },
+ { id: 'skills', label: 'Skills', icon: 'list-check' },
+ { id: 'files', label: 'Attachment', icon: 'paperclip' },
+];
+
+function Checkbox({ checked }: { checked: boolean }) {
+ return (
+ <span
+ className={cn(
+ 'flex size-4 shrink-0 items-center justify-center rounded border',
+ checked ? 'border-primary bg-primary text-primary-foreground' : 'border-input bg-background',
+ )}
+ aria-hidden
+ >
+ {checked ? <Icon name="check" className="size-3" /> : null}
+ </span>
+ );
+}
+
+function CatalogRow({
+ title,
+ description,
+ checked,
+ onToggle,
+}: {
+ title: string;
+ description?: string;
+ checked: boolean;
+ onToggle: () => void;
+}) {
+ return (
+ <button
+ type="button"
+ role="menuitemcheckbox"
+ aria-checked={checked}
+ className="hover:bg-accent flex w-full items-start gap-2 rounded-md px-2 py-2 text-left"
+ onClick={onToggle}
+ >
+ <span className="bg-muted text-muted-foreground mt-0.5 flex size-7 shrink-0 items-center justify-center rounded text-xs font-semibold">
+ {title.charAt(0).toUpperCase()}
+ </span>
+ <span className="min-w-0 flex-1">
+ <span className="text-foreground block truncate text-sm font-medium">{title}</span>
+ {description ? <span className="text-muted-foreground line-clamp-1 text-xs">{description}</span> : null}
+ </span>
+ <Checkbox checked={checked} />
+ </button>
+ );
+}
+
+function SearchField({
+ value,
+ onChange,
+ placeholder,
+}: {
+ value: string;
+ onChange: (v: string) => void;
+ placeholder: string;
+}) {
+ return (
+ <label className="relative mx-3 my-2 block">
+ <Icon
+ name="search"
+ className="text-muted-foreground pointer-events-none absolute top-1/2 left-2 size-3.5 -translate-y-1/2"
+ />
+ <input
+ type="search"
+ value={value}
+ onChange={e => onChange(e.target.value)}
+ placeholder={placeholder}
+ className="border-input bg-muted/50 placeholder:text-muted-foreground h-8 w-full rounded-md border-0 py-1 pr-2 pl-7 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring/40"
+ />
+ </label>
+ );
+}
+
+export type DraftCompositeSelectorProps = {
+ disabled?: boolean;
+ isRunning?: boolean;
+ onAttach?: () => void;
+};
+
+export function DraftCompositeSelector({ disabled, isRunning, onAttach }: DraftCompositeSelectorProps) {
+ const { skills, connectors } = useDraftCatalog();
+ const { agentSpec } = useTrueFoundryAgentSpec();
+ const updateAgentSpec = useTrueFoundryUpdateAgentSpec();
+ const [open, setOpen] = useState(false);
+ const [tab, setTab] = useState<AttachTab>('connectors');
+ const [query, setQuery] = useState('');
+ const containerRef = useRef<HTMLDivElement>(null);
+ const menuId = useId();
+ const isMobile = useIsMobile();
+ const compactLayout = useCompactLayout();
+
+ const selectedMcp = useMemo(
+ () => (agentSpec?.mcpServers as McpServerMount[] | undefined) ?? [],
+ [agentSpec?.mcpServers],
+ );
+ const selectedSkills = useMemo(() => (agentSpec?.skills as SkillMount[] | undefined) ?? [], [agentSpec?.skills]);
+
+ const selectedMcpIds = useMemo(() => new Set(selectedMcp.map(m => m.id)), [selectedMcp]);
+ const selectedSkillIds = useMemo(() => new Set(selectedSkills.map(s => s.id)), [selectedSkills]);
+
+ useEffect(() => {
+ if (!open) return;
+ const handler = (e: MouseEvent) => {
+ if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+ setOpen(false);
+ }
+ };
+ document.addEventListener('mousedown', handler);
+ return () => document.removeEventListener('mousedown', handler);
+ }, [open]);
+
+ const filteredConnectors = useMemo(() => {
+ const needle = query.trim().toLowerCase();
+ if (!needle) return connectors;
+ return connectors.filter(
+ c => c.name.toLowerCase().includes(needle) || (c.description?.toLowerCase().includes(needle) ?? false),
+ );
+ }, [connectors, query]);
+
+ const filteredSkills = useMemo(() => {
+ const needle = query.trim().toLowerCase();
+ if (!needle) return skills;
+ return skills.filter(
+ s => s.name.toLowerCase().includes(needle) || (s.description?.toLowerCase().includes(needle) ?? false),
+ );
+ }, [skills, query]);
+
+ const toggleConnector = (connector: ConnectorState) => {
+ const next = selectedMcpIds.has(connector.id)
+ ? selectedMcp.filter(m => m.id !== connector.id)
+ : [...selectedMcp, { id: connector.id, name: connector.name }];
+ updateAgentSpec?.({ mcpServers: next });
+ };
+
+ const toggleSkill = (skill: AgentSkill) => {
+ const next = selectedSkillIds.has(skill.id)
+ ? selectedSkills.filter(s => s.id !== skill.id)
+ : [...selectedSkills, { id: skill.id, name: skill.name }];
+ updateAgentSpec?.({ skills: next });
+ };
+
+ const content = (
+ <>
+ <div className="flex shrink-0 border-b border-border">
+ {TABS.map(t => {
+ const count = t.id === 'connectors' ? selectedMcp.length : t.id === 'skills' ? selectedSkills.length : null;
+ const active = tab === t.id;
+ return (
+ <button
+ key={t.id}
+ type="button"
+ className={cn(
+ 'text-muted-foreground flex flex-1 items-center justify-center gap-1.5 px-2 py-2.5 text-xs font-medium',
+ active && 'text-foreground border-b-2 border-foreground',
+ )}
+ onClick={() => {
+ setTab(t.id);
+ setQuery('');
+ }}
+ >
+ <Icon name={t.icon} className="size-3.5" />
+ {t.label}
+ {count != null && count > 0 ? <span className="bg-muted rounded px-1 text-[10px]">{count}</span> : null}
+ </button>
+ );
+ })}
+ </div>
+
+ {tab === 'files' ? (
+ <button
+ type="button"
+ disabled={disabled}
+ onClick={() => {
+ onAttach?.();
+ setOpen(false);
+ }}
+ className={cn(
+ 'm-3 flex min-h-48 flex-1 flex-col items-center justify-center gap-2 rounded-lg border border-dashed border-border px-4 py-8',
+ 'text-center outline-none transition-colors hover:bg-accent/40',
+ 'disabled:cursor-not-allowed disabled:opacity-50',
+ )}
+ >
+ <Icon name="paperclip" className="text-primary size-6" />
+ <span className="text-sm font-medium">Add files or photos</span>
+ <span className="text-muted-foreground text-xs">Upto 5 attachments | 10 MB each</span>
+ </button>
+ ) : (
+ <>
+ <SearchField
+ value={query}
+ onChange={setQuery}
+ placeholder={tab === 'connectors' ? 'Search connectors...' : 'Search skills...'}
+ />
+ <div className="text-muted-foreground flex items-center justify-between px-3 pb-1 text-[11px] font-medium tracking-wide uppercase">
+ <span>Available ({tab === 'connectors' ? filteredConnectors.length : filteredSkills.length})</span>
+ </div>
+ <div className="min-h-0 flex-1 overflow-y-auto px-1 pb-2">
+ {tab === 'connectors'
+ ? filteredConnectors.map(c => (
+ <CatalogRow
+ key={c.id}
+ title={c.name}
+ description={c.description}
+ checked={selectedMcpIds.has(c.id)}
+ onToggle={() => toggleConnector(c)}
+ />
+ ))
+ : filteredSkills.map(s => (
+ <CatalogRow
+ key={s.id}
+ title={s.name}
+ description={s.description}
+ checked={selectedSkillIds.has(s.id)}
+ onToggle={() => toggleSkill(s)}
+ />
+ ))}
+ </div>
+ </>
+ )}
+ </>
+ );
+
+ return (
+ <div ref={containerRef} className="relative">
+ <button
+ type="button"
+ disabled={disabled || isRunning}
+ aria-label="Add connectors, skills, or attachments"
+ aria-haspopup="dialog"
+ aria-expanded={open}
+ aria-controls={open ? menuId : undefined}
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={() => setOpen(v => !v)}
+ >
+ <Icon name="plus" className="text-primary" />
+ </button>
+
+ {open ? (
+ isMobile || compactLayout ? (
+ <BottomSheet id={menuId} open onOpenChange={setOpen} aria-label="Add to composer">
+ {content}
+ </BottomSheet>
+ ) : (
+ <div
+ id={menuId}
+ role="dialog"
+ aria-label="Add to composer"
+ className="bg-popover text-popover-foreground absolute bottom-full left-0 z-50 mb-2 flex h-[22rem] w-[28rem] max-w-[min(28rem,calc(100vw-2rem))] flex-col overflow-hidden rounded-lg border border-border shadow-lg"
+ >
+ {content}
+ </div>
+ )
+ ) : null}
+ </div>
+ );
+}
+
+export function DraftSelectionChips() {
+ const { agentSpec } = useTrueFoundryAgentSpec();
+ const mcpCount = agentSpec?.mcpServers?.length ?? 0;
+ const skillCount = agentSpec?.skills?.length ?? 0;
+
+ if (mcpCount === 0 && skillCount === 0) return null;
+
+ return (
+ <div className="flex flex-wrap items-center gap-1.5">
+ {mcpCount > 0 ? (
+ <span className="bg-muted text-muted-foreground inline-flex items-center gap-1 rounded-full px-2 py-0.5 text-xs">
+ <Icon name="plug" className="size-3" />
+ {mcpCount} Connector{mcpCount === 1 ? '' : 's'}
+ </span>
+ ) : null}
+ {skillCount > 0 ? (
+ <span className="bg-muted text-muted-foreground inline-flex items-center gap-1 rounded-full px-2 py-0.5 text-xs">
+ <Icon name="list-check" className="size-3" />
+ {skillCount} Skill{skillCount === 1 ? '' : 's'}
+ </span>
+ ) : null}
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/draft/DraftModelSelector.tsx b/packages/trueforge-ui-sdk/src/atoms/draft/DraftModelSelector.tsx
new file mode 100644
index 000000000..c1b7c946e
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/draft/DraftModelSelector.tsx
@@ -0,0 +1,198 @@
+'use client';
+
+import { useTrueFoundryAgentSpec, useTrueFoundryUpdateAgentSpec } from '@truefoundry/assistant-ui-runtime';
+import { useEffect, useId, useMemo, useRef, useState } from 'react';
+
+import { Icon } from '../../icons/Icon.js';
+import type { ModelSelection } from '../../server/types.js';
+import { auiButtonClass } from '../lib/buttonClasses.js';
+import { cn } from '../lib/cn.js';
+import { useCompactLayout } from '../lib/CompactLayoutContext.js';
+import { useIsMobile } from '../lib/useIsMobile.js';
+import { BottomSheet } from '../primitives/BottomSheet.js';
+import { useDraftCatalog } from './DraftCatalogProvider.js';
+import { modelPatchWithReasoningEffort } from './reasoningEffort.js';
+
+type RichModel = ModelSelection & { apiModel?: string; modelId?: string };
+
+const PROVIDER_COLORS = ['#ec4899', '#0ea5e9', '#f59e0b', '#10b981', '#6366f1', '#8b5cf6'] as const;
+
+function monogram(value: string): string {
+ const trimmed = value.trim();
+ return trimmed ? trimmed.charAt(0).toUpperCase() : '?';
+}
+
+function colorFor(value: string): string {
+ let hash = 0;
+ for (const ch of value) hash = (hash + ch.charCodeAt(0)) % PROVIDER_COLORS.length;
+ return PROVIDER_COLORS[hash] ?? PROVIDER_COLORS[0];
+}
+
+function displayModelLabel(modelName: string): string {
+ const slash = modelName.lastIndexOf('/');
+ return slash >= 0 ? modelName.slice(slash + 1) : modelName;
+}
+
+function modelValue(model: RichModel): string {
+ return model.apiModel ?? model.name;
+}
+
+export type DraftModelSelectorProps = {
+ disabled?: boolean;
+ isRunning?: boolean;
+};
+
+export function DraftModelSelector({ disabled, isRunning }: DraftModelSelectorProps) {
+ const { models: rawModels, loading } = useDraftCatalog();
+ const models = rawModels as RichModel[];
+ const { agentSpec } = useTrueFoundryAgentSpec();
+ const updateAgentSpec = useTrueFoundryUpdateAgentSpec();
+ const [open, setOpen] = useState(false);
+ const [query, setQuery] = useState('');
+ const containerRef = useRef<HTMLDivElement>(null);
+ const menuId = useId();
+ const isMobile = useIsMobile();
+ const compactLayout = useCompactLayout();
+
+ const selectedName = agentSpec?.model?.name ?? (models[0] ? modelValue(models[0]) : '');
+ const selected = models.find(m => modelValue(m) === selectedName || m.name === selectedName);
+ const label = selected
+ ? displayModelLabel(modelValue(selected))
+ : selectedName
+ ? displayModelLabel(selectedName)
+ : loading
+ ? 'Loading…'
+ : 'Select model';
+
+ const filtered = useMemo(() => {
+ const needle = query.trim().toLowerCase();
+ if (!needle) return models;
+ return models.filter(
+ m =>
+ m.name.toLowerCase().includes(needle) ||
+ (m.apiModel?.toLowerCase().includes(needle) ?? false) ||
+ (m.modelId?.toLowerCase().includes(needle) ?? false) ||
+ m.provider.toLowerCase().includes(needle),
+ );
+ }, [models, query]);
+
+ useEffect(() => {
+ if (!open) return;
+ const handler = (e: MouseEvent) => {
+ if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+ setOpen(false);
+ }
+ };
+ document.addEventListener('mousedown', handler);
+ return () => document.removeEventListener('mousedown', handler);
+ }, [open]);
+
+ const account = selected?.provider ?? selectedName;
+ const iconBg = colorFor(account);
+
+ const content = (
+ <>
+ <div className="border-b border-border px-3 py-2">
+ <p className="text-foreground mb-2 text-sm font-semibold">Select model</p>
+ <label className="relative block">
+ <Icon
+ name="search"
+ className="text-muted-foreground pointer-events-none absolute top-1/2 left-2 size-3.5 -translate-y-1/2"
+ />
+ <input
+ type="search"
+ value={query}
+ onChange={e => setQuery(e.target.value)}
+ placeholder="Search"
+ className="border-input bg-background placeholder:text-muted-foreground h-8 w-full rounded-md border py-1 pr-2 pl-7 text-sm outline-none focus-visible:ring-2 focus-visible:ring-ring/40"
+ autoFocus
+ />
+ </label>
+ </div>
+ <div
+ id={menuId}
+ role="listbox"
+ aria-label="Select model"
+ className="flex min-h-0 flex-1 flex-col overflow-y-auto p-1"
+ >
+ {filtered.length === 0 ? (
+ <p className="text-muted-foreground px-2 py-4 text-center text-sm">No models</p>
+ ) : (
+ filtered.map(model => {
+ const value = modelValue(model);
+ const active = value === selectedName || model.name === selectedName;
+ return (
+ <button
+ key={value || model.modelId || model.name}
+ type="button"
+ role="option"
+ aria-selected={active}
+ className={cn(
+ 'flex w-full items-center gap-2 rounded-md px-2 py-2 text-left text-sm',
+ active ? 'bg-accent' : 'hover:bg-accent/60',
+ )}
+ onClick={() => {
+ updateAgentSpec?.({
+ model: modelPatchWithReasoningEffort(value, agentSpec?.model?.params, model.reasoningEfforts),
+ });
+ setOpen(false);
+ setQuery('');
+ }}
+ >
+ <span
+ className="flex size-6 shrink-0 items-center justify-center rounded text-[11px] font-bold text-white"
+ style={{ backgroundColor: colorFor(model.provider || model.name) }}
+ aria-hidden
+ >
+ {monogram(model.provider || model.name)}
+ </span>
+ <span className="truncate font-medium">{displayModelLabel(value)}</span>
+ </button>
+ );
+ })
+ )}
+ </div>
+ </>
+ );
+
+ return (
+ <div ref={containerRef} className="relative">
+ <button
+ type="button"
+ disabled={disabled || isRunning}
+ aria-haspopup="listbox"
+ aria-expanded={open}
+ aria-controls={open ? menuId : undefined}
+ title="Select model"
+ className={auiButtonClass({
+ variant: 'ghost',
+ size: 'sm',
+ className: cn('h-8 max-w-[12rem] gap-1.5 rounded-full px-2 text-xs font-medium', 'hover:bg-accent'),
+ })}
+ onClick={() => setOpen(v => !v)}
+ >
+ <span
+ className="flex size-5 shrink-0 items-center justify-center rounded text-[10px] font-bold text-white"
+ style={{ backgroundColor: iconBg }}
+ aria-hidden
+ >
+ {monogram(account)}
+ </span>
+ <span className="truncate">{label}</span>
+ <Icon name="chevron-down" className="size-3.5 shrink-0 opacity-60" />
+ </button>
+
+ {open ? (
+ isMobile || compactLayout ? (
+ <BottomSheet open onOpenChange={setOpen} aria-label="Select model">
+ {content}
+ </BottomSheet>
+ ) : (
+ <div className="bg-popover text-popover-foreground absolute right-0 bottom-full z-50 mb-2 flex max-h-[22rem] w-[18rem] flex-col overflow-hidden rounded-lg border border-border shadow-lg">
+ {content}
+ </div>
+ )
+ ) : null}
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/draft/DraftReasoningEffortSelector.tsx b/packages/trueforge-ui-sdk/src/atoms/draft/DraftReasoningEffortSelector.tsx
new file mode 100644
index 000000000..fce4aea3d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/draft/DraftReasoningEffortSelector.tsx
@@ -0,0 +1,134 @@
+'use client';
+
+import { useTrueFoundryAgentSpec, useTrueFoundryUpdateAgentSpec } from '@truefoundry/assistant-ui-runtime';
+import { useEffect, useId, useRef, useState } from 'react';
+
+import { Icon } from '../../icons/Icon.js';
+import type { ModelSelection } from '../../server/types.js';
+import { auiButtonClass } from '../lib/buttonClasses.js';
+import { cn } from '../lib/cn.js';
+import { useCompactLayout } from '../lib/CompactLayoutContext.js';
+import { useIsMobile } from '../lib/useIsMobile.js';
+import { BottomSheet } from '../primitives/BottomSheet.js';
+import { useDraftCatalog } from './DraftCatalogProvider.js';
+import { hasReasoningEfforts, modelPatchWithReasoningEffort, resolveReasoningEffort } from './reasoningEffort.js';
+
+type RichModel = ModelSelection & { apiModel?: string; modelId?: string };
+
+function modelValue(model: RichModel): string {
+ return model.apiModel ?? model.name;
+}
+
+export type DraftReasoningEffortSelectorProps = {
+ disabled?: boolean;
+ isRunning?: boolean;
+};
+
+export function DraftReasoningEffortSelector({ disabled, isRunning }: DraftReasoningEffortSelectorProps) {
+ const { models: rawModels } = useDraftCatalog();
+ const models = rawModels as RichModel[];
+ const { agentSpec } = useTrueFoundryAgentSpec();
+ const updateAgentSpec = useTrueFoundryUpdateAgentSpec();
+ const [open, setOpen] = useState(false);
+ const containerRef = useRef<HTMLDivElement>(null);
+ const menuId = useId();
+ const isMobile = useIsMobile();
+ const compactLayout = useCompactLayout();
+
+ const selectedName = agentSpec?.model?.name ?? (models[0] ? modelValue(models[0]) : '');
+ const selected = models.find(m => modelValue(m) === selectedName || m.name === selectedName);
+ const efforts = selected?.reasoningEfforts;
+ const currentEffort = agentSpec?.model?.params?.reasoningEffort;
+ // Display fallback only — coerce into the spec on model change / explicit pick.
+ const resolved = resolveReasoningEffort(efforts, currentEffort);
+
+ useEffect(() => {
+ if (!open) return;
+ const handler = (e: MouseEvent) => {
+ if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+ setOpen(false);
+ }
+ };
+ document.addEventListener('mousedown', handler);
+ return () => document.removeEventListener('mousedown', handler);
+ }, [open]);
+
+ if (!hasReasoningEfforts(efforts) || !resolved) return null;
+
+ const content = (
+ <>
+ <div className="border-b border-border px-3 py-2">
+ <p className="text-foreground text-sm font-semibold">Reasoning effort</p>
+ </div>
+ <div
+ id={menuId}
+ role="listbox"
+ aria-label="Select reasoning effort"
+ className="flex min-h-0 flex-1 flex-col overflow-y-auto p-1"
+ >
+ {efforts.map(effort => {
+ const active = effort === resolved;
+ return (
+ <button
+ key={effort}
+ type="button"
+ role="option"
+ aria-selected={active}
+ className={cn(
+ 'flex w-full items-center rounded-md px-2 py-2 text-left text-sm',
+ active ? 'bg-accent' : 'hover:bg-accent/60',
+ )}
+ onClick={() => {
+ if (!selected || !updateAgentSpec) return;
+ updateAgentSpec({
+ model: modelPatchWithReasoningEffort(
+ modelValue(selected),
+ { ...agentSpec?.model?.params, reasoningEffort: effort },
+ efforts,
+ ),
+ });
+ setOpen(false);
+ }}
+ >
+ <span className="truncate font-medium">{effort}</span>
+ </button>
+ );
+ })}
+ </div>
+ </>
+ );
+
+ return (
+ <div ref={containerRef} className="relative">
+ <button
+ type="button"
+ disabled={disabled || isRunning}
+ aria-haspopup="listbox"
+ aria-expanded={open}
+ aria-controls={open ? menuId : undefined}
+ title="Select reasoning effort"
+ className={auiButtonClass({
+ variant: 'ghost',
+ size: 'sm',
+ className: cn('h-8 max-w-[10rem] gap-1.5 rounded-full px-2 text-xs font-medium', 'hover:bg-accent'),
+ })}
+ onClick={() => setOpen(v => !v)}
+ >
+ <span className="truncate">{resolved}</span>
+ <Icon name="chevron-down" className="size-3.5 shrink-0 opacity-60" />
+ </button>
+
+ {open ? (
+ isMobile || compactLayout ? (
+ <BottomSheet open onOpenChange={setOpen} aria-label="Select reasoning effort">
+ {content}
+ </BottomSheet>
+ ) : (
+ <div className="bg-popover text-popover-foreground absolute right-0 bottom-full z-50 mb-2 flex max-h-[22rem] w-[12rem] flex-col overflow-hidden rounded-lg border border-border shadow-lg">
+ {content}
+ </div>
+ )
+ ) : null}
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/draft/reasoningEffort.test.ts b/packages/trueforge-ui-sdk/src/atoms/draft/reasoningEffort.test.ts
new file mode 100644
index 000000000..092e00522
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/draft/reasoningEffort.test.ts
@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+
+import { hasReasoningEfforts, modelPatchWithReasoningEffort, resolveReasoningEffort } from './reasoningEffort.js';
+
+describe('hasReasoningEfforts', () => {
+ it('is false for nullish or empty', () => {
+ expect(hasReasoningEfforts(undefined)).toBe(false);
+ expect(hasReasoningEfforts([])).toBe(false);
+ });
+
+ it('is true when non-empty', () => {
+ expect(hasReasoningEfforts(['low'])).toBe(true);
+ });
+});
+
+describe('resolveReasoningEffort', () => {
+ it('returns undefined when no efforts', () => {
+ expect(resolveReasoningEffort(undefined, 'high')).toBeUndefined();
+ expect(resolveReasoningEffort([], 'high')).toBeUndefined();
+ });
+
+ it('keeps current when still listed', () => {
+ expect(resolveReasoningEffort(['low', 'high'], 'high')).toBe('high');
+ });
+
+ it('falls back to first when current missing or invalid', () => {
+ expect(resolveReasoningEffort(['low', 'high'], undefined)).toBe('low');
+ expect(resolveReasoningEffort(['low', 'high'], 'medium')).toBe('low');
+ });
+});
+
+describe('modelPatchWithReasoningEffort', () => {
+ it('sets effort and preserves other params', () => {
+ expect(modelPatchWithReasoningEffort('m', { maxTokens: 100, reasoningEffort: 'high' }, ['low', 'high'])).toEqual({
+ name: 'm',
+ params: { maxTokens: 100, reasoningEffort: 'high' },
+ });
+ });
+
+ it('falls back to first and clears effort when model has none', () => {
+ expect(modelPatchWithReasoningEffort('m', { maxTokens: 100, reasoningEffort: 'high' }, ['low'])).toEqual({
+ name: 'm',
+ params: { maxTokens: 100, reasoningEffort: 'low' },
+ });
+
+ expect(modelPatchWithReasoningEffort('m', { maxTokens: 100, reasoningEffort: 'high' }, [])).toEqual({
+ name: 'm',
+ params: { maxTokens: 100 },
+ });
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/atoms/draft/reasoningEffort.ts b/packages/trueforge-ui-sdk/src/atoms/draft/reasoningEffort.ts
new file mode 100644
index 000000000..8bd00625d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/draft/reasoningEffort.ts
@@ -0,0 +1,33 @@
+import type { Model, ModelParams, ModelSelection } from '../../server/types.js';
+
+export function hasReasoningEfforts(efforts: ModelSelection['reasoningEfforts']): efforts is string[] {
+ return Array.isArray(efforts) && efforts.length > 0;
+}
+
+/** Keep current if still listed; otherwise first effort; none if model has no efforts. */
+export function resolveReasoningEffort(
+ efforts: ModelSelection['reasoningEfforts'],
+ current: string | undefined,
+): string | undefined {
+ if (!hasReasoningEfforts(efforts)) return undefined;
+ if (current && efforts.includes(current)) return current;
+ return efforts[0];
+}
+
+/** Draft model patch: preserve other params, set or clear `reasoningEffort`. */
+export function modelPatchWithReasoningEffort(
+ name: string,
+ existingParams: ModelParams | undefined,
+ efforts: ModelSelection['reasoningEfforts'],
+): Model {
+ const nextEffort = resolveReasoningEffort(efforts, existingParams?.reasoningEffort);
+ if (nextEffort === undefined) {
+ if (!existingParams) return { name };
+ const { reasoningEffort: _cleared, ...rest } = existingParams;
+ return Object.keys(rest).length > 0 ? { name, params: rest } : { name };
+ }
+ return {
+ name,
+ params: { ...existingParams, reasoningEffort: nextEffort },
+ };
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/lib/CompactLayoutContext.tsx b/packages/trueforge-ui-sdk/src/atoms/lib/CompactLayoutContext.tsx
new file mode 100644
index 000000000..494e1f30d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/lib/CompactLayoutContext.tsx
@@ -0,0 +1,13 @@
+'use client';
+
+import { createContext, useContext, type ReactNode } from 'react';
+
+const CompactLayoutContext = createContext(false);
+
+export function CompactLayoutProvider({ children }: { children: ReactNode }) {
+ return <CompactLayoutContext.Provider value>{children}</CompactLayoutContext.Provider>;
+}
+
+export function useCompactLayout() {
+ return useContext(CompactLayoutContext);
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/lib/buttonClasses.ts b/packages/trueforge-ui-sdk/src/atoms/lib/buttonClasses.ts
new file mode 100644
index 000000000..477c59737
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/lib/buttonClasses.ts
@@ -0,0 +1,35 @@
+import { cn } from './cn.js';
+
+export type AuiButtonVariant = 'default' | 'secondary' | 'ghost' | 'destructive' | 'outline';
+export type AuiButtonSize = 'default' | 'sm' | 'lg' | 'icon';
+
+const variantClasses: Record<AuiButtonVariant, string> = {
+ default: 'bg-primary text-primary-foreground shadow hover:bg-primary/90',
+ secondary: 'bg-secondary text-secondary-foreground shadow-sm hover:bg-secondary/80',
+ ghost: 'hover:bg-accent hover:text-accent-foreground',
+ destructive: 'bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90',
+ outline: 'border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground',
+};
+
+const sizeClasses: Record<AuiButtonSize, string> = {
+ default: 'h-9 px-4 py-2 text-sm',
+ sm: 'h-8 rounded-md px-3 text-xs',
+ lg: 'h-10 rounded-md px-8 text-base',
+ icon: 'h-8 w-8',
+};
+
+const baseClasses =
+ 'inline-flex cursor-pointer items-center justify-center gap-2 whitespace-nowrap rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50';
+
+/** Shared Button / native `<button>` className helper (SDK utilities are layered). */
+export function auiButtonClass({
+ variant = 'default',
+ size = 'default',
+ className,
+}: {
+ variant?: AuiButtonVariant;
+ size?: AuiButtonSize;
+ className?: string;
+} = {}): string {
+ return cn(baseClasses, variantClasses[variant], sizeClasses[size], className);
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/lib/cn.ts b/packages/trueforge-ui-sdk/src/atoms/lib/cn.ts
new file mode 100644
index 000000000..2819a830d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/lib/cn.ts
@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+ return twMerge(clsx(inputs));
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/lib/useCompactOverlayStyle.ts b/packages/trueforge-ui-sdk/src/atoms/lib/useCompactOverlayStyle.ts
new file mode 100644
index 000000000..0f70633f9
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/lib/useCompactOverlayStyle.ts
@@ -0,0 +1,44 @@
+'use client';
+
+import { useLayoutEffect, useState, type CSSProperties, type RefObject } from 'react';
+
+export function useCompactOverlayStyle(
+ ref: RefObject<HTMLElement | null>,
+ compact: boolean,
+ contentSized = false,
+): CSSProperties | undefined {
+ const [style, setStyle] = useState<CSSProperties>();
+
+ useLayoutEffect(() => {
+ if (!compact) {
+ setStyle(undefined);
+ return;
+ }
+
+ const container = ref.current?.closest<HTMLElement>('[data-aui-compact-layout]');
+ if (!container) return;
+
+ const update = () => {
+ const bounds = container.getBoundingClientRect();
+ const height = Math.min(bounds.height * 0.85, 480);
+ setStyle({
+ left: bounds.left,
+ bottom: window.innerHeight - bounds.bottom,
+ width: bounds.width,
+ height: contentSized ? 'fit-content' : height,
+ maxHeight: height,
+ });
+ };
+
+ update();
+ const observer = typeof ResizeObserver === 'function' ? new ResizeObserver(update) : null;
+ observer?.observe(container);
+ window.addEventListener('resize', update);
+ return () => {
+ observer?.disconnect();
+ window.removeEventListener('resize', update);
+ };
+ }, [compact, contentSized, ref]);
+
+ return style;
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/lib/useIsMobile.ts b/packages/trueforge-ui-sdk/src/atoms/lib/useIsMobile.ts
new file mode 100644
index 000000000..2ffcbe81c
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/lib/useIsMobile.ts
@@ -0,0 +1,20 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+
+const MOBILE_QUERY = '(max-width: 767px)';
+
+function subscribe(callback: () => void) {
+ if (typeof window.matchMedia !== 'function') return () => undefined;
+ const media = window.matchMedia(MOBILE_QUERY);
+ media.addEventListener('change', callback);
+ return () => media.removeEventListener('change', callback);
+}
+
+function getSnapshot() {
+ return typeof window.matchMedia === 'function' && window.matchMedia(MOBILE_QUERY).matches;
+}
+
+export function useIsMobile() {
+ return useSyncExternalStore(subscribe, getSnapshot, () => false);
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/primitives/Accordion.tsx b/packages/trueforge-ui-sdk/src/atoms/primitives/Accordion.tsx
new file mode 100644
index 000000000..4c5138184
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/primitives/Accordion.tsx
@@ -0,0 +1,186 @@
+import React, { createContext, useContext, useId, useState, type ReactNode } from 'react';
+
+import { cn } from '../lib/cn.js';
+
+/**
+ * Controlled accordion compatible with prior tfy `expanded` / `onChange` slot usage.
+ */
+export type AccordionProps = {
+ expanded?: boolean;
+ onChange?: (event: unknown, expanded: boolean) => void;
+ children?: ReactNode;
+ className?: string;
+ background?: string;
+ sx?: unknown;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'>;
+
+export function Accordion({
+ expanded,
+ onChange,
+ children,
+ className,
+ background: _background,
+ sx: _sx,
+ ...rest
+}: AccordionProps) {
+ const panelId = useId();
+
+ return (
+ <div className={cn('w-full', className)} data-expanded={expanded || undefined} {...rest}>
+ {React.Children.map(children, child => {
+ if (!React.isValidElement(child)) return child;
+ return React.cloneElement(child as React.ReactElement<Record<string, unknown>>, {
+ expanded,
+ onChange,
+ panelId,
+ });
+ })}
+ </div>
+ );
+}
+
+export type AccordionSummaryProps = {
+ children?: ReactNode;
+ className?: string;
+ expanded?: boolean;
+ onChange?: (event: unknown, expanded: boolean) => void;
+ panelId?: string;
+ hideIcon?: boolean;
+ disableRipple?: boolean;
+ sx?: unknown;
+};
+
+export function AccordionSummary({ children, className, expanded, onChange, panelId }: AccordionSummaryProps) {
+ return (
+ <button
+ type="button"
+ aria-expanded={expanded}
+ aria-controls={panelId}
+ className={cn('flex w-full cursor-pointer items-center text-left', className)}
+ onClick={event => onChange?.(event, !expanded)}
+ >
+ {children}
+ </button>
+ );
+}
+
+export type AccordionDetailsProps = {
+ children?: ReactNode;
+ className?: string;
+ expanded?: boolean;
+ panelId?: string;
+ sx?: unknown;
+};
+
+export function AccordionDetails({ children, className, expanded, panelId }: AccordionDetailsProps) {
+ if (!expanded) return null;
+ return (
+ <div id={panelId} role="region" className={cn(className)}>
+ {children}
+ </div>
+ );
+}
+
+type AccordionCtx = {
+ openItems: Set<string>;
+ toggle: (id: string) => void;
+};
+
+const Ctx = createContext<AccordionCtx>({ openItems: new Set(), toggle: () => {} });
+
+export function AccordionRoot({
+ type = 'single',
+ defaultValue,
+ className,
+ children,
+}: {
+ type?: 'single' | 'multiple';
+ defaultValue?: string;
+ className?: string;
+ children?: ReactNode;
+}) {
+ const [openItems, setOpenItems] = useState<Set<string>>(() => new Set(defaultValue ? [defaultValue] : []));
+ const toggle = (id: string) => {
+ setOpenItems(prev => {
+ const next = new Set(type === 'single' ? [] : prev);
+ if (prev.has(id)) next.delete(id);
+ else next.add(id);
+ return next;
+ });
+ };
+ return (
+ <Ctx.Provider value={{ openItems, toggle }}>
+ <div className={cn('divide-y divide-border', className)}>{children}</div>
+ </Ctx.Provider>
+ );
+}
+
+export function AccordionItem({
+ value,
+ className,
+ children,
+}: {
+ value: string;
+ className?: string;
+ children?: ReactNode;
+}) {
+ const { openItems } = useContext(Ctx);
+ return (
+ <div className={className} data-open={openItems.has(value) || undefined}>
+ {React.Children.map(children, child =>
+ React.isValidElement(child)
+ ? React.cloneElement(child as React.ReactElement<{ itemId?: string; isOpen?: boolean }>, {
+ itemId: value,
+ isOpen: openItems.has(value),
+ })
+ : child,
+ )}
+ </div>
+ );
+}
+
+export function AccordionTrigger({
+ className,
+ children,
+ itemId,
+ isOpen,
+ ...rest
+}: React.ButtonHTMLAttributes<HTMLButtonElement> & { itemId?: string; isOpen?: boolean }) {
+ const { toggle } = useContext(Ctx);
+ const panelId = itemId ? `aui-accordion-panel-${itemId}` : undefined;
+ return (
+ <button
+ type="button"
+ aria-expanded={isOpen}
+ aria-controls={panelId}
+ className={cn('flex w-full cursor-pointer items-center justify-between py-3 text-sm font-medium', className)}
+ onClick={() => itemId && toggle(itemId)}
+ {...rest}
+ >
+ {children}
+ </button>
+ );
+}
+
+export function AccordionContent({
+ className,
+ children,
+ isOpen,
+ itemId,
+}: {
+ className?: string;
+ children?: ReactNode;
+ isOpen?: boolean;
+ itemId?: string;
+}) {
+ if (!isOpen) return null;
+ return (
+ <div
+ id={itemId ? `aui-accordion-panel-${itemId}` : undefined}
+ role="region"
+ className={cn('pb-4 text-sm', className)}
+ >
+ {children}
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/primitives/Avatar.tsx b/packages/trueforge-ui-sdk/src/atoms/primitives/Avatar.tsx
new file mode 100644
index 000000000..2cfe20b61
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/primitives/Avatar.tsx
@@ -0,0 +1,69 @@
+import React, { useState } from 'react';
+
+import { cn } from '../lib/cn.js';
+
+const sizeClasses = {
+ sm: 'h-6 w-6 text-xs',
+ default: 'h-8 w-8 text-sm',
+ lg: 'h-10 w-10 text-base',
+};
+
+export type AvatarProps = React.HTMLAttributes<HTMLDivElement> & {
+ size?: 'default' | 'sm' | 'lg';
+};
+
+export function Avatar({ className, size = 'default', ...props }: AvatarProps) {
+ return (
+ <div
+ data-slot="avatar"
+ data-size={size}
+ className={cn('relative flex shrink-0 overflow-hidden rounded-full', sizeClasses[size], className)}
+ {...props}
+ />
+ );
+}
+
+export type AvatarImageProps = React.ImgHTMLAttributes<HTMLImageElement>;
+
+export function AvatarImage({ className, src, alt = '', onError, ...props }: AvatarImageProps) {
+ const [failed, setFailed] = useState(false);
+
+ if (failed || !src) return null;
+
+ return (
+ <img
+ data-slot="avatar-image"
+ src={src}
+ alt={alt}
+ className={cn('aspect-square h-full w-full object-cover', className)}
+ onError={e => {
+ setFailed(true);
+ onError?.(e);
+ }}
+ {...props}
+ />
+ );
+}
+
+export type AvatarFallbackProps = React.HTMLAttributes<HTMLDivElement>;
+
+export function AvatarFallback({ className, ...props }: AvatarFallbackProps) {
+ return (
+ <div
+ data-slot="avatar-fallback"
+ className={cn(
+ 'flex h-full w-full items-center justify-center rounded-full bg-muted font-medium text-muted-foreground',
+ className,
+ )}
+ {...props}
+ />
+ );
+}
+
+// declare module "../../theme/SlotsProvider.js" {
+// interface AtomSlots {
+// Avatar: typeof Avatar;
+// AvatarImage: typeof AvatarImage;
+// AvatarFallback: typeof AvatarFallback;
+// }
+// }
diff --git a/packages/trueforge-ui-sdk/src/atoms/primitives/BottomSheet.test.tsx b/packages/trueforge-ui-sdk/src/atoms/primitives/BottomSheet.test.tsx
new file mode 100644
index 000000000..0b5616c9b
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/primitives/BottomSheet.test.tsx
@@ -0,0 +1,29 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { BottomSheet } from './BottomSheet.js';
+
+HTMLDialogElement.prototype.showModal = function showModal() {
+ this.setAttribute('open', '');
+};
+
+describe('BottomSheet', () => {
+ it('handles Escape without closing a parent dialog', () => {
+ const onOpenChange = vi.fn();
+ const onParentCancel = vi.fn();
+
+ render(
+ <dialog open onCancel={onParentCancel}>
+ <BottomSheet open onOpenChange={onOpenChange} aria-label="Picker">
+ Content
+ </BottomSheet>
+ </dialog>,
+ );
+
+ fireEvent(screen.getByRole('dialog', { name: 'Picker' }), new Event('cancel', { bubbles: true }));
+
+ expect(onOpenChange).toHaveBeenCalledWith(false);
+ expect(onParentCancel).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/atoms/primitives/BottomSheet.tsx b/packages/trueforge-ui-sdk/src/atoms/primitives/BottomSheet.tsx
new file mode 100644
index 000000000..87d8b330e
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/primitives/BottomSheet.tsx
@@ -0,0 +1,74 @@
+'use client';
+
+import { useEffect, useRef, type MouseEvent, type ReactNode } from 'react';
+
+import { useCompactLayout } from '../lib/CompactLayoutContext.js';
+import { cn } from '../lib/cn.js';
+import { useCompactOverlayStyle } from '../lib/useCompactOverlayStyle.js';
+
+export type BottomSheetProps = {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ children: ReactNode;
+ className?: string;
+ id?: string;
+ 'aria-label': string;
+};
+
+export function BottomSheet({
+ open,
+ onOpenChange,
+ children,
+ className,
+ id,
+ 'aria-label': ariaLabel,
+}: BottomSheetProps) {
+ const ref = useRef<HTMLDialogElement>(null);
+ const compact = useCompactLayout();
+ const compactStyle = useCompactOverlayStyle(ref, compact);
+
+ useEffect(() => {
+ const dialog = ref.current;
+ if (!dialog) return;
+ if (open && !dialog.open) dialog.showModal();
+ else if (!open && dialog.open) dialog.close();
+ }, [open]);
+
+ useEffect(() => {
+ const dialog = ref.current;
+ if (!dialog) return;
+ const handleClose = () => onOpenChange(false);
+ dialog.addEventListener('close', handleClose);
+ return () => dialog.removeEventListener('close', handleClose);
+ }, [onOpenChange]);
+
+ const handleBackdropClick = (event: MouseEvent<HTMLDialogElement>) => {
+ if (event.target === ref.current) onOpenChange(false);
+ };
+
+ return (
+ <dialog
+ ref={ref}
+ id={id}
+ aria-label={ariaLabel}
+ onClick={handleBackdropClick}
+ onCancel={event => {
+ event.preventDefault();
+ event.stopPropagation();
+ onOpenChange(false);
+ }}
+ style={compactStyle ?? { height: 'min(70dvh, 30rem)', maxHeight: '85dvh' }}
+ className={cn(
+ 'aui-bottom-sheet bg-popover text-popover-foreground m-0 mt-auto w-full max-w-none overflow-hidden rounded-t-xl border border-b-0 border-border p-0 pb-[env(safe-area-inset-bottom)] shadow-xl',
+ 'backdrop:bg-black/40 backdrop:backdrop-blur-[2px]',
+ 'open:flex open:flex-col',
+ className,
+ )}
+ >
+ <div className="flex h-5 shrink-0 items-center justify-center" aria-hidden>
+ <span className="h-1 w-10 rounded-full bg-muted-foreground/30" />
+ </div>
+ {children}
+ </dialog>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/primitives/Button.tsx b/packages/trueforge-ui-sdk/src/atoms/primitives/Button.tsx
new file mode 100644
index 000000000..b9f73b488
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/primitives/Button.tsx
@@ -0,0 +1,20 @@
+import React from 'react';
+
+import { auiButtonClass, type AuiButtonSize, type AuiButtonVariant } from '../lib/buttonClasses.js';
+
+export type ButtonVariant = AuiButtonVariant;
+export type ButtonSize = AuiButtonSize;
+
+export type ButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
+ variant?: ButtonVariant;
+ size?: ButtonSize;
+ asChild?: never;
+};
+
+export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
+ ({ className, variant = 'default', size = 'default', ...props }, ref) => {
+ return <button ref={ref} className={auiButtonClass({ variant, size, className })} {...props} />;
+ },
+);
+
+Button.displayName = 'Button';
diff --git a/packages/trueforge-ui-sdk/src/atoms/primitives/CenteredModal.tsx b/packages/trueforge-ui-sdk/src/atoms/primitives/CenteredModal.tsx
new file mode 100644
index 000000000..a55a2d24b
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/primitives/CenteredModal.tsx
@@ -0,0 +1,120 @@
+'use client';
+
+import { useEffect, useId, useRef, type MouseEvent, type ReactNode } from 'react';
+
+import { Icon } from '../../icons/Icon.js';
+import { auiButtonClass } from '../lib/buttonClasses.js';
+import { cn } from '../lib/cn.js';
+import { useCompactLayout } from '../lib/CompactLayoutContext.js';
+import { useCompactOverlayStyle } from '../lib/useCompactOverlayStyle.js';
+
+export type CenteredModalProps = {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ title: string;
+ description?: string;
+ headerIcon?: ReactNode;
+ children: ReactNode;
+ className?: string;
+ contentSized?: boolean;
+ 'aria-label'?: string;
+};
+
+/**
+ * Responsive modal chrome: centered dialog on `md+`, bottom sheet below `md`.
+ * One content tree for both breakpoints (native `<dialog>`).
+ */
+export function CenteredModal({
+ open,
+ onOpenChange,
+ title,
+ description,
+ headerIcon,
+ children,
+ className,
+ contentSized = false,
+ 'aria-label': ariaLabel,
+}: CenteredModalProps) {
+ const ref = useRef<HTMLDialogElement>(null);
+ const titleId = useId();
+ const descriptionId = useId();
+ const compact = useCompactLayout();
+ const compactStyle = useCompactOverlayStyle(ref, compact, contentSized);
+
+ useEffect(() => {
+ const el = ref.current;
+ if (!el) return;
+ if (open && !el.open) {
+ el.showModal();
+ } else if (!open && el.open) {
+ el.close();
+ }
+ }, [open]);
+
+ useEffect(() => {
+ const el = ref.current;
+ if (!el) return;
+ const handler = () => onOpenChange(false);
+ el.addEventListener('close', handler);
+ return () => el.removeEventListener('close', handler);
+ }, [onOpenChange]);
+
+ const handleBackdropClick = (e: MouseEvent<HTMLDialogElement>) => {
+ if (e.target === ref.current) onOpenChange(false);
+ };
+
+ return (
+ <dialog
+ ref={ref}
+ aria-label={ariaLabel ?? title}
+ aria-labelledby={titleId}
+ aria-describedby={description ? descriptionId : undefined}
+ onClick={handleBackdropClick}
+ onCancel={event => {
+ event.preventDefault();
+ event.stopPropagation();
+ onOpenChange(false);
+ }}
+ style={compactStyle ?? (contentSized ? { height: 'fit-content', maxHeight: '85dvh' } : undefined)}
+ className={cn(
+ 'bg-background text-foreground border-border open:flex open:flex-col overflow-hidden p-0 shadow-xl',
+ 'backdrop:bg-black/40 backdrop:backdrop-blur-[2px]',
+ compact
+ ? 'm-0 mt-auto max-w-none rounded-t-xl rounded-b-none border-t pb-[env(safe-area-inset-bottom)]'
+ : contentSized
+ ? 'm-0 mt-auto h-auto max-h-[85dvh] w-full max-w-none rounded-t-xl rounded-b-none border-t pb-[env(safe-area-inset-bottom)] md:m-auto md:h-auto md:w-[min(28rem,calc(100%-3rem))] md:max-w-md md:rounded-xl md:border md:pb-0'
+ : cn(
+ // Mobile: bottom sheet
+ 'm-0 mt-auto h-[min(85dvh,40rem)] w-full max-w-none rounded-t-xl rounded-b-none border-t pb-[env(safe-area-inset-bottom)]',
+ // Desktop: large centered modal (MCP-tools inspired)
+ 'md:m-auto md:h-[min(80dvh,40rem)] md:w-[min(72rem,calc(100%-3rem))] md:max-w-5xl md:rounded-xl md:border md:pb-0',
+ ),
+ className,
+ )}
+ >
+ <header className="flex shrink-0 items-center gap-3 border-b border-border px-5 py-4">
+ {headerIcon}
+ <div className="min-w-0 flex-1">
+ <h2 id={titleId} className="text-foreground text-lg font-semibold tracking-tight">
+ {title}
+ </h2>
+ {description ? (
+ <p id={descriptionId} className="text-muted-foreground mt-1 text-sm">
+ {description}
+ </p>
+ ) : null}
+ </div>
+ <button
+ type="button"
+ aria-label="Close"
+ title="Close"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={() => onOpenChange(false)}
+ >
+ <Icon name="xmark" />
+ </button>
+ </header>
+ <div className="flex min-h-0 flex-1 flex-col overflow-y-auto">{children}</div>
+ </dialog>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/primitives/Dialog.tsx b/packages/trueforge-ui-sdk/src/atoms/primitives/Dialog.tsx
new file mode 100644
index 000000000..ed90c64a7
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/primitives/Dialog.tsx
@@ -0,0 +1,165 @@
+import React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type DialogProps = {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ children: React.ReactNode;
+ className?: string;
+ 'aria-label'?: string;
+ 'aria-labelledby'?: string;
+};
+
+export function Dialog({
+ open,
+ onOpenChange,
+ children,
+ className,
+ 'aria-label': ariaLabel,
+ 'aria-labelledby': ariaLabelledBy,
+}: DialogProps) {
+ const ref = React.useRef<HTMLDialogElement>(null);
+
+ React.useEffect(() => {
+ const el = ref.current;
+ if (!el) return;
+ if (open && !el.open) {
+ el.showModal();
+ } else if (!open && el.open) {
+ el.close();
+ }
+ }, [open]);
+
+ React.useEffect(() => {
+ const el = ref.current;
+ if (!el) return;
+ const handler = () => onOpenChange(false);
+ el.addEventListener('close', handler);
+ return () => el.removeEventListener('close', handler);
+ }, [onOpenChange]);
+
+ const handleBackdropClick = (e: React.MouseEvent<HTMLDialogElement>) => {
+ if (e.target === ref.current) onOpenChange(false);
+ };
+
+ return (
+ <dialog
+ ref={ref}
+ aria-label={ariaLabel}
+ aria-labelledby={ariaLabelledBy}
+ onClick={handleBackdropClick}
+ className={cn(
+ 'm-auto max-h-[90dvh] w-full max-w-lg rounded-lg bg-background p-0 text-foreground shadow-lg',
+ 'backdrop:bg-black/50',
+ 'open:flex open:flex-col',
+ className,
+ )}
+ >
+ {children}
+ </dialog>
+ );
+}
+
+export type DialogContentProps = React.HTMLAttributes<HTMLDivElement>;
+
+export function DialogContent({ className, children, ...props }: DialogContentProps) {
+ return (
+ <div className={cn('flex flex-col gap-4 p-6', className)} {...props}>
+ {children}
+ </div>
+ );
+}
+
+export type DialogHeaderProps = React.HTMLAttributes<HTMLDivElement>;
+
+export function DialogHeader({ className, ...props }: DialogHeaderProps) {
+ return <div className={cn('flex flex-col gap-1.5', className)} {...props} />;
+}
+
+export type DialogTitleProps = React.HTMLAttributes<HTMLHeadingElement>;
+
+export function DialogTitle({ className, ...props }: DialogTitleProps) {
+ return <h2 className={cn('text-lg font-semibold leading-none tracking-tight', className)} {...props} />;
+}
+
+export type DialogFooterProps = React.HTMLAttributes<HTMLDivElement>;
+
+export function DialogFooter({ className, ...props }: DialogFooterProps) {
+ return (
+ <div className={cn('flex flex-col-reverse gap-2 px-6 pb-6 sm:flex-row sm:justify-end', className)} {...props} />
+ );
+}
+
+/**
+ * Accessible backdrop modal (Escape, focus restore, labelled dialog).
+ * Prefer {@link Dialog} (native `<dialog>`) for new call sites.
+ */
+export function Modal({
+ open,
+ onClose,
+ children,
+ 'aria-label': ariaLabel = 'Dialog',
+}: {
+ open?: boolean;
+ onClose?: () => void;
+ children?: React.ReactNode;
+ 'aria-label'?: string;
+}) {
+ const dialogRef = React.useRef<HTMLDivElement>(null);
+ const previousFocusRef = React.useRef<HTMLElement | null>(null);
+
+ React.useEffect(() => {
+ if (!open) return;
+ previousFocusRef.current = document.activeElement as HTMLElement | null;
+ const dialog = dialogRef.current;
+ const focusable = dialog?.querySelector<HTMLElement>(
+ 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
+ );
+ focusable?.focus();
+
+ const onKeyDown = (e: KeyboardEvent) => {
+ if (e.key === 'Escape') {
+ e.preventDefault();
+ onClose?.();
+ return;
+ }
+ if (e.key !== 'Tab' || !dialog) return;
+ const nodes = Array.from(
+ dialog.querySelectorAll<HTMLElement>(
+ 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])',
+ ),
+ ).filter(el => !el.hasAttribute('disabled') && el.tabIndex !== -1);
+ if (nodes.length === 0) return;
+ const first = nodes[0]!;
+ const last = nodes[nodes.length - 1]!;
+ if (e.shiftKey && document.activeElement === first) {
+ e.preventDefault();
+ last.focus();
+ } else if (!e.shiftKey && document.activeElement === last) {
+ e.preventDefault();
+ first.focus();
+ }
+ };
+
+ document.addEventListener('keydown', onKeyDown);
+ return () => {
+ document.removeEventListener('keydown', onKeyDown);
+ previousFocusRef.current?.focus?.();
+ };
+ }, [open, onClose]);
+
+ if (!open) return null;
+
+ return (
+ <div
+ role="presentation"
+ className="fixed inset-0 z-50 flex items-center justify-center bg-black/50 p-4"
+ onClick={onClose}
+ >
+ <div ref={dialogRef} role="dialog" aria-modal="true" aria-label={ariaLabel} onClick={e => e.stopPropagation()}>
+ {children}
+ </div>
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/primitives/DropdownMenu.tsx b/packages/trueforge-ui-sdk/src/atoms/primitives/DropdownMenu.tsx
new file mode 100644
index 000000000..b89362113
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/primitives/DropdownMenu.tsx
@@ -0,0 +1,131 @@
+import React, { useEffect, useId, useRef, useState } from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type DropdownMenuProps = {
+ trigger: React.ReactNode;
+ children: React.ReactNode;
+ align?: 'start' | 'end';
+ className?: string;
+};
+
+export function DropdownMenu({ trigger, children, align = 'end', className }: DropdownMenuProps) {
+ const [open, setOpen] = useState(false);
+ const containerRef = useRef<HTMLDivElement>(null);
+ const menuRef = useRef<HTMLDivElement>(null);
+ const menuId = useId();
+
+ useEffect(() => {
+ if (!open) return;
+ const handler = (e: MouseEvent) => {
+ if (containerRef.current && !containerRef.current.contains(e.target as Node)) {
+ setOpen(false);
+ }
+ };
+ document.addEventListener('mousedown', handler);
+ return () => document.removeEventListener('mousedown', handler);
+ }, [open]);
+
+ useEffect(() => {
+ if (!open) return;
+ const first = menuRef.current?.querySelector<HTMLElement>('[role="menuitem"]:not([disabled])');
+ first?.focus();
+ }, [open]);
+
+ useEffect(() => {
+ if (!open) return;
+ const handler = (e: KeyboardEvent) => {
+ if (e.key === 'Escape') {
+ e.preventDefault();
+ setOpen(false);
+ const triggerBtn = containerRef.current?.querySelector<HTMLElement>("[aria-haspopup='menu']");
+ triggerBtn?.focus();
+ return;
+ }
+
+ if (e.key !== 'ArrowDown' && e.key !== 'ArrowUp' && e.key !== 'Home' && e.key !== 'End') {
+ return;
+ }
+
+ const items = Array.from(
+ menuRef.current?.querySelectorAll<HTMLElement>('[role="menuitem"]:not([disabled])') ?? [],
+ );
+ if (items.length === 0) return;
+
+ e.preventDefault();
+ const currentIndex = items.indexOf(document.activeElement as HTMLElement);
+ let nextIndex = currentIndex;
+ if (e.key === 'ArrowDown') nextIndex = (currentIndex + 1) % items.length;
+ else if (e.key === 'ArrowUp') nextIndex = (currentIndex - 1 + items.length) % items.length;
+ else if (e.key === 'Home') nextIndex = 0;
+ else if (e.key === 'End') nextIndex = items.length - 1;
+ items[nextIndex]?.focus();
+ };
+ document.addEventListener('keydown', handler);
+ return () => document.removeEventListener('keydown', handler);
+ }, [open]);
+
+ const triggerEl = React.isValidElement(trigger)
+ ? React.cloneElement(trigger as React.ReactElement<Record<string, unknown>>, {
+ 'aria-haspopup': 'menu',
+ 'aria-expanded': open,
+ 'aria-controls': open ? menuId : undefined,
+ onKeyDown: (e: React.KeyboardEvent) => {
+ const existing = (trigger as React.ReactElement<{ onKeyDown?: (ev: React.KeyboardEvent) => void }>).props
+ .onKeyDown;
+ existing?.(e);
+ if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') {
+ e.preventDefault();
+ setOpen(true);
+ }
+ },
+ })
+ : trigger;
+
+ return (
+ <div ref={containerRef} className="relative inline-flex">
+ <div onClick={() => setOpen(v => !v)}>{triggerEl}</div>
+ {open && (
+ <div
+ ref={menuRef}
+ id={menuId}
+ role="menu"
+ className={cn(
+ 'absolute top-full z-50 mt-1 min-w-[8rem] rounded-md border border-border bg-popover p-1',
+ 'text-popover-foreground shadow-md',
+ align === 'end' ? 'right-0' : 'left-0',
+ className,
+ )}
+ onClick={() => setOpen(false)}
+ >
+ {children}
+ </div>
+ )}
+ </div>
+ );
+}
+
+export type DropdownMenuItemProps = React.ButtonHTMLAttributes<HTMLButtonElement>;
+
+export function DropdownMenuItem({ className, ...props }: DropdownMenuItemProps) {
+ return (
+ <button
+ role="menuitem"
+ type="button"
+ className={cn(
+ 'flex w-full cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none',
+ 'transition-colors hover:bg-accent hover:text-accent-foreground',
+ 'focus:bg-accent focus:text-accent-foreground',
+ 'disabled:pointer-events-none disabled:opacity-50',
+ className,
+ )}
+ {...props}
+ />
+ );
+}
+
+export type DropdownMenuSeparatorProps = React.HTMLAttributes<HTMLDivElement>;
+
+export function DropdownMenuSeparator({ className, ...props }: DropdownMenuSeparatorProps) {
+ return <div role="separator" className={cn('-mx-1 my-1 h-px bg-border', className)} {...props} />;
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/primitives/IconButton.tsx b/packages/trueforge-ui-sdk/src/atoms/primitives/IconButton.tsx
new file mode 100644
index 000000000..3128113ef
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/primitives/IconButton.tsx
@@ -0,0 +1,21 @@
+import React from 'react';
+
+import { Button, type ButtonProps } from './Button.js';
+
+export type IconButtonProps = Omit<ButtonProps, 'size' | 'children'> & {
+ 'aria-label': string;
+ tooltip?: string;
+ children: React.ReactNode;
+};
+
+export const IconButton = React.forwardRef<HTMLButtonElement, IconButtonProps>(
+ ({ tooltip, children, ...props }, ref) => {
+ return (
+ <Button ref={ref} size="icon" title={tooltip} {...props}>
+ {children}
+ </Button>
+ );
+ },
+);
+
+IconButton.displayName = 'IconButton';
diff --git a/packages/trueforge-ui-sdk/src/atoms/primitives/SearchInput.tsx b/packages/trueforge-ui-sdk/src/atoms/primitives/SearchInput.tsx
new file mode 100644
index 000000000..b0197089a
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/primitives/SearchInput.tsx
@@ -0,0 +1,28 @@
+import { Icon } from '../../icons/Icon.js';
+
+type SearchInputProps = {
+ query: string;
+ setQuery: (query: string) => void;
+ placeholder?: string;
+};
+
+const SearchInput = ({ query, setQuery, placeholder = 'Search' }: SearchInputProps) => {
+ return (
+ <label className="relative block">
+ <Icon
+ name="search"
+ className="text-muted-foreground pointer-events-none absolute top-1/2 left-2.5 size-3.5 -translate-y-1/2"
+ />
+ <input
+ type="search"
+ value={query}
+ onChange={e => setQuery(e.target.value)}
+ placeholder={placeholder}
+ className="border-input bg-background placeholder:text-muted-foreground/70 h-9 w-full rounded-md border py-1 pr-3 pl-8 text-sm outline-none"
+ autoFocus
+ />
+ </label>
+ );
+};
+
+export default SearchInput;
diff --git a/packages/trueforge-ui-sdk/src/atoms/primitives/Skeleton.tsx b/packages/trueforge-ui-sdk/src/atoms/primitives/Skeleton.tsx
new file mode 100644
index 000000000..5d1864af5
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/primitives/Skeleton.tsx
@@ -0,0 +1,9 @@
+import React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type SkeletonProps = React.HTMLAttributes<HTMLDivElement>;
+
+export function Skeleton({ className, ...props }: SkeletonProps) {
+ return <div className={cn('animate-pulse rounded-md bg-muted', className)} {...props} />;
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/primitives/Spinner.tsx b/packages/trueforge-ui-sdk/src/atoms/primitives/Spinner.tsx
new file mode 100644
index 000000000..746bce06a
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/primitives/Spinner.tsx
@@ -0,0 +1,37 @@
+import React from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type SpinnerProps = React.SVGProps<SVGSVGElement> & {
+ size?: number;
+};
+
+export function Spinner({ size = 16, className, ...props }: SpinnerProps) {
+ const r = (size / 2) * 0.75;
+ const cx = size / 2;
+ const circumference = 2 * Math.PI * r;
+
+ return (
+ <svg
+ role="status"
+ aria-label="Loading"
+ width={size}
+ height={size}
+ viewBox={`0 0 ${size} ${size}`}
+ fill="none"
+ className={cn('animate-spin', className)}
+ {...props}
+ >
+ <circle
+ cx={cx}
+ cy={cx}
+ r={r}
+ stroke="currentColor"
+ strokeWidth={2}
+ strokeLinecap="round"
+ strokeDasharray={`${circumference * 0.75} ${circumference * 0.25}`}
+ opacity={0.8}
+ />
+ </svg>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/atoms/primitives/Tooltip.tsx b/packages/trueforge-ui-sdk/src/atoms/primitives/Tooltip.tsx
new file mode 100644
index 000000000..c7f146ba0
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/primitives/Tooltip.tsx
@@ -0,0 +1,70 @@
+import React, { cloneElement, isValidElement, useRef, useState } from 'react';
+
+import { cn } from '../lib/cn.js';
+
+export type TooltipProps = {
+ content: React.ReactNode;
+ children: React.ReactElement;
+ className?: string;
+};
+
+export function Tooltip({ content, children, className }: TooltipProps) {
+ const [visible, setVisible] = useState(false);
+ const ref = useRef<HTMLSpanElement>(null);
+
+ if (!isValidElement(children)) return children;
+
+ type AnyProps = React.HTMLAttributes<Element>;
+ const p = children.props as AnyProps;
+ const child = cloneElement(children as React.ReactElement<AnyProps>, {
+ onMouseEnter(e: React.MouseEvent<Element>) {
+ setVisible(true);
+ (p.onMouseEnter as ((e: React.MouseEvent<Element>) => void) | undefined)?.(e);
+ },
+ onMouseLeave(e: React.MouseEvent<Element>) {
+ setVisible(false);
+ (p.onMouseLeave as ((e: React.MouseEvent<Element>) => void) | undefined)?.(e);
+ },
+ onFocus(e: React.FocusEvent<Element>) {
+ setVisible(true);
+ (p.onFocus as ((e: React.FocusEvent<Element>) => void) | undefined)?.(e);
+ },
+ onBlur(e: React.FocusEvent<Element>) {
+ setVisible(false);
+ (p.onBlur as ((e: React.FocusEvent<Element>) => void) | undefined)?.(e);
+ },
+ });
+
+ return (
+ <span ref={ref} className="relative inline-flex">
+ {child}
+ {visible && content != null && (
+ <span
+ role="tooltip"
+ className={cn(
+ 'pointer-events-none absolute bottom-full left-1/2 z-50 mb-1.5 -translate-x-1/2',
+ 'whitespace-nowrap rounded bg-foreground px-2 py-1 text-xs text-background shadow-md',
+ className,
+ )}
+ >
+ {content}
+ </span>
+ )}
+ </span>
+ );
+}
+
+export type LightTooltipProps = {
+ title: React.ReactNode;
+ children: React.ReactElement;
+ className?: string;
+ size?: string;
+};
+
+export function LightTooltip({ title, children, className, size: _size }: LightTooltipProps) {
+ return (
+ <Tooltip content={title} className={className}>
+ {children}
+ </Tooltip>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/build-styles.css b/packages/trueforge-ui-sdk/src/build-styles.css
new file mode 100644
index 000000000..f1c692bf7
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/build-styles.css
@@ -0,0 +1,12 @@
+/*
+ * Build-only entry point for the published stylesheet.
+ *
+ * Import Tailwind's theme and utilities, but omit preflight so the SDK does
+ * not reset global consumer styles. `styles.css` supplies the SDK's sources,
+ * dependencies, and semantic-token bridge.
+ */
+@import "tailwindcss/theme" layer(tfy-agent-ui-theme);
+@import "tailwindcss/utilities" layer(tfy-agent-ui-utilities);
+@import "./styles.css";
+
+@custom-variant dark (&:is(.dark *));
diff --git a/packages/trueforge-ui-sdk/src/constants/attachments.ts b/packages/trueforge-ui-sdk/src/constants/attachments.ts
new file mode 100644
index 000000000..de33afd67
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/constants/attachments.ts
@@ -0,0 +1,2 @@
+/** Fixed preview bounds for attachments rendered in user message bubbles. */
+export const USER_MESSAGE_ATTACHMENT_PREVIEW_REM = 12;
diff --git a/packages/trueforge-ui-sdk/src/containers/AgentStepsContainer.tsx b/packages/trueforge-ui-sdk/src/containers/AgentStepsContainer.tsx
new file mode 100644
index 000000000..3605933a9
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/AgentStepsContainer.tsx
@@ -0,0 +1,46 @@
+'use client';
+
+import { useEffect, useRef, useState, type PropsWithChildren, type ReactNode } from 'react';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+
+export interface AgentStepsContainerProps {
+ toolCount: number;
+ thinkingCount: number;
+ hasFinal: boolean;
+}
+
+/**
+ * Container for "Agent steps" section — groups reasoning, intermediate text, and tools
+ * in a collapsible accordion that auto-collapses once final answer is confirmed.
+ */
+export function AgentStepsContainer({
+ children,
+ toolCount,
+ thinkingCount,
+ hasFinal,
+}: PropsWithChildren<AgentStepsContainerProps>) {
+ const AgentStepsCard = useSlot('AgentStepsCard');
+
+ const [expanded, setExpanded] = useState(true);
+ const collapsedByFinal = useRef(false);
+
+ // Auto-collapse once when hasFinal becomes true (matches AgentTimeline behavior)
+ useEffect(() => {
+ if (hasFinal && !collapsedByFinal.current) {
+ collapsedByFinal.current = true;
+ setExpanded(false);
+ }
+ }, [hasFinal]);
+
+ return (
+ <AgentStepsCard
+ toolCount={toolCount}
+ thinkingCount={thinkingCount}
+ expanded={expanded}
+ onToggle={() => setExpanded(prev => !prev)}
+ >
+ {children as ReactNode}
+ </AgentStepsCard>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/AskUserContainer.tsx b/packages/trueforge-ui-sdk/src/containers/AskUserContainer.tsx
new file mode 100644
index 000000000..5847e111f
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/AskUserContainer.tsx
@@ -0,0 +1,99 @@
+'use client';
+
+import { useThreadIsRunning } from '@assistant-ui/core/react';
+import { useTrueFoundryToolResponses } from '@truefoundry/assistant-ui-runtime';
+import { useCallback, useEffect, useMemo, useState } from 'react';
+import {
+ ASK_USER_CUSTOM_OPTION,
+ type AskUserAnswerDraft,
+ type Question,
+} from '../atoms/adapters/AskUserPromptAdapter.js';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+
+const EMPTY_ANSWER: AskUserAnswerDraft = { radioValue: '', custom: '' };
+
+export function AskUserContainer() {
+ const AskUserPrompt = useSlot('AskUserPrompt');
+ const { pending, respond } = useTrueFoundryToolResponses();
+ const isRunning = useThreadIsRunning();
+ const item = pending[0];
+
+ const questions = useMemo<Question[]>(
+ () =>
+ item == null
+ ? []
+ : [
+ {
+ id: item.toolCallId,
+ question: item.question ?? 'Answer required',
+ options: item.options ?? [],
+ },
+ ],
+ [item],
+ );
+ const [currentQuestionIndex, setCurrentQuestionIndex] = useState(0);
+ const [answers, setAnswers] = useState<Record<string, AskUserAnswerDraft>>({});
+
+ useEffect(() => {
+ setCurrentQuestionIndex(0);
+ setAnswers({});
+ }, [item?.toolCallId]);
+
+ const safeIndex = Math.min(currentQuestionIndex, Math.max(questions.length - 1, 0));
+ const currentQuestion = questions[safeIndex];
+ const currentAnswer = currentQuestion == null ? EMPTY_ANSWER : (answers[currentQuestion.id] ?? EMPTY_ANSWER);
+ const getResponseForQuestion = useCallback(
+ (questionId: string) => {
+ const answer = answers[questionId] ?? EMPTY_ANSWER;
+ return answer.radioValue === ASK_USER_CUSTOM_OPTION ? answer.custom.trim() : answer.radioValue.trim();
+ },
+ [answers],
+ );
+ const allQuestionsAnswered = useMemo(
+ () => questions.every(question => getResponseForQuestion(question.id)),
+ [getResponseForQuestion, questions],
+ );
+ const selectedResponse =
+ currentAnswer.radioValue === ASK_USER_CUSTOM_OPTION ? currentAnswer.custom.trim() : currentAnswer.radioValue.trim();
+ const isSubmitDisabled = isRunning || currentQuestion == null || selectedResponse.length === 0;
+ const isSubmitAllDisabled = isSubmitDisabled || !allQuestionsAnswered;
+
+ const onCurrentAnswerChange = useCallback((questionId: string, update: Partial<AskUserAnswerDraft>) => {
+ setAnswers(previous => ({
+ ...previous,
+ [questionId]: {
+ ...(previous[questionId] ?? EMPTY_ANSWER),
+ ...update,
+ },
+ }));
+ }, []);
+
+ const onSubmit = useCallback(() => {
+ if (item == null || !allQuestionsAnswered) return;
+ const content = getResponseForQuestion(item.toolCallId);
+ if (!content) return;
+ respond({ toolCallId: item.toolCallId, content });
+ }, [allQuestionsAnswered, getResponseForQuestion, item, respond]);
+
+ if (item == null || currentQuestion == null) return null;
+
+ return (
+ <AskUserPrompt
+ questions={questions}
+ readOnly={isRunning}
+ currentQuestion={currentQuestion}
+ currentQuestionIndex={safeIndex}
+ currentAnswer={currentAnswer}
+ totalQuestions={questions.length}
+ isMultiQuestion={questions.length > 1}
+ isLastQuestion={safeIndex === questions.length - 1}
+ allQuestionsAnswered={allQuestionsAnswered}
+ isSubmitDisabled={isSubmitDisabled}
+ isSubmitAllDisabled={isSubmitAllDisabled}
+ onCurrentQuestionIndexChange={setCurrentQuestionIndex}
+ onCurrentAnswerChange={onCurrentAnswerChange}
+ onSubmit={onSubmit}
+ />
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/AssistantMessageContainer.test.tsx b/packages/trueforge-ui-sdk/src/containers/AssistantMessageContainer.test.tsx
new file mode 100644
index 000000000..ae2a66049
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/AssistantMessageContainer.test.tsx
@@ -0,0 +1,64 @@
+// @vitest-environment jsdom
+import { ThreadPrimitive, type ThreadMessageLike } from '@assistant-ui/react';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { AssistantMessageContainer } from './AssistantMessageContainer.js';
+import { RuntimeHarness } from './RuntimeHarness.js';
+
+function renderAssistantMessage(messages: ThreadMessageLike[], options?: { isRunning?: boolean }) {
+ return render(
+ <RuntimeHarness messages={messages} isRunning={options?.isRunning}>
+ <ThreadPrimitive.Messages>{() => <AssistantMessageContainer />}</ThreadPrimitive.Messages>
+ </RuntimeHarness>,
+ );
+}
+
+describe('AssistantMessageContainer', () => {
+ it('renders assistant text through the Markdown atom', () => {
+ renderAssistantMessage([{ role: 'assistant', content: 'hello world' }]);
+ expect(screen.getByText('hello world')).toBeInTheDocument();
+ });
+
+ it('passes the message error to MessageErrorBanner when the message failed', () => {
+ renderAssistantMessage([
+ {
+ role: 'assistant',
+ content: 'partial',
+ status: { type: 'incomplete', reason: 'error', error: 'boom' },
+ },
+ ]);
+ expect(screen.getByRole('alert')).toHaveTextContent('boom');
+ });
+
+ it('does not render an error banner for a healthy message', () => {
+ renderAssistantMessage([{ role: 'assistant', content: 'all good' }]);
+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+ });
+
+ it('hides the action bar while the thread is running (streaming state)', () => {
+ renderAssistantMessage([{ role: 'assistant', content: 'typing...' }], { isRunning: true });
+ expect(screen.queryByRole('button', { name: 'Copy' })).not.toBeInTheDocument();
+ });
+
+ it('shows the action bar once the thread is idle', () => {
+ renderAssistantMessage(
+ [
+ {
+ role: 'assistant',
+ content: 'done',
+ createdAt: new Date('2026-07-09T14:06:04'),
+ },
+ ],
+ { isRunning: false },
+ );
+ expect(screen.getByRole('button', { name: 'Copy' })).toBeInTheDocument();
+ expect(screen.getByText(/\d{1,2}:\d{2}:\d{2}/)).toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'More' })).not.toBeInTheDocument();
+ });
+
+ it('hides the branch indicator when there is only a single branch', () => {
+ renderAssistantMessage([{ role: 'assistant', content: 'hi' }]);
+ expect(screen.queryByText(/^\d+ \/ \d+$/)).not.toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/AssistantMessageContainer.tsx b/packages/trueforge-ui-sdk/src/containers/AssistantMessageContainer.tsx
new file mode 100644
index 000000000..42f967d41
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/AssistantMessageContainer.tsx
@@ -0,0 +1,114 @@
+'use client';
+
+import { useActionBarCopy, useMessageError, useThreadIsRunning, type PartState } from '@assistant-ui/core/react';
+import { MessagePrimitive, useAuiState, type EnrichedPartState, type GroupByContext } from '@assistant-ui/react';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+import { computeAgentStepsSplit } from '../utils/computeAgentStepsSplit.js';
+import { AgentStepsContainer } from './AgentStepsContainer.js';
+import { AssistantTextContainer } from './AssistantTextContainer.js';
+import { MessageImageContainer } from './MessageImageContainer.js';
+import { ReasoningContainer } from './ReasoningContainer.js';
+import { ToolCallContainer } from './ToolCallContainer.js';
+import type { ThreadGroupPart } from './ToolGroupContainer.js';
+
+/**
+ * Dispatches a leaf message part to its renderer. "data" parts (generative
+ * UI) are out of scope for this SDK entirely.
+ */
+function AssistantLeafPartContainer({ part }: { part: EnrichedPartState }) {
+ switch (part.type) {
+ case 'text':
+ case 'reasoning':
+ return <AssistantTextContainer />;
+ case 'image':
+ return <MessageImageContainer />;
+ case 'tool-call':
+ return <ToolCallContainer {...part} />;
+ default:
+ return null;
+ }
+}
+
+export function AssistantMessageContainer() {
+ const AssistantMessageBubble = useSlot('AssistantMessageBubble');
+ const MessageActionBar = useSlot('MessageActionBar');
+ const MessageErrorBanner = useSlot('MessageErrorBanner');
+ const MessageIndicator = useSlot('MessageIndicator');
+ const isThreadRunning = useThreadIsRunning();
+ const error = useMessageError();
+ const createdAt = useAuiState(s => s.message.createdAt);
+ const isMessageRunning = useAuiState(s => s.message.status?.type === 'running');
+ const { copy, isCopied } = useActionBarCopy({
+ copyToClipboard: text => navigator.clipboard.writeText(text),
+ });
+
+ const parts = useAuiState(s => s.message.parts);
+
+ const { cutIndex, hasFinal, toolCount, thinkingCount } = computeAgentStepsSplit(parts, isMessageRunning);
+
+ const groupBy = (part: PartState, _context: GroupByContext): readonly `group-${string}`[] | null => {
+ const index = parts.findIndex(p => p === part);
+ if (index === -1) return null;
+
+ if (part.type === 'text' && index >= cutIndex) {
+ return null;
+ }
+
+ if (index < cutIndex) {
+ if (part.type === 'reasoning') {
+ return ['group-agentSteps', 'group-reasoning'];
+ }
+ return ['group-agentSteps'];
+ }
+
+ return null;
+ };
+
+ return (
+ <MessagePrimitive.Root data-role="assistant">
+ <AssistantMessageBubble
+ error={error !== undefined ? <MessageErrorBanner message={String(error)} /> : undefined}
+ actionBar={
+ !isThreadRunning ? <MessageActionBar isCopied={isCopied} onCopy={copy} createdAt={createdAt} /> : undefined
+ }
+ >
+ <MessagePrimitive.GroupedParts groupBy={groupBy}>
+ {({ part, children }) => {
+ switch (part.type) {
+ case 'group-agentSteps':
+ return (
+ <AgentStepsContainer toolCount={toolCount} thinkingCount={thinkingCount} hasFinal={hasFinal}>
+ {children}
+ </AgentStepsContainer>
+ );
+ case 'group-reasoning':
+ return <ReasoningContainer group={part as ThreadGroupPart} />;
+ case 'text': {
+ const index = parts.findIndex(p => p === part);
+ // Intermediate text inside Agent steps: muted + indented vs final answer
+ if (index >= 0 && index < cutIndex) {
+ return (
+ <div className="mb-2 ml-[1.75rem] text-xs text-gray-600 dark:text-gray-400 [&_.markdown-body]:text-inherit">
+ <AssistantTextContainer />
+ </div>
+ );
+ }
+ return <AssistantTextContainer />;
+ }
+ case 'reasoning':
+ case 'tool-call':
+ case 'image':
+ case 'data':
+ return <AssistantLeafPartContainer part={part} />;
+ case 'indicator':
+ return <MessageIndicator />;
+ default:
+ return null;
+ }
+ }}
+ </MessagePrimitive.GroupedParts>
+ </AssistantMessageBubble>
+ </MessagePrimitive.Root>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/AssistantTextContainer.test.tsx b/packages/trueforge-ui-sdk/src/containers/AssistantTextContainer.test.tsx
new file mode 100644
index 000000000..6207e1813
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/AssistantTextContainer.test.tsx
@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+import { ThreadPrimitive, type ThreadMessageLike } from '@assistant-ui/react';
+import { render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import type { MarkdownProps } from '../atoms/Markdown.js';
+import { SlotsProvider } from '../theme/SlotsProvider.js';
+import { AssistantMessageContainer } from './AssistantMessageContainer.js';
+import { RuntimeHarness } from './RuntimeHarness.js';
+
+function renderAssistantMessage(messages: ThreadMessageLike[]) {
+ return render(
+ <RuntimeHarness messages={messages}>
+ <ThreadPrimitive.Messages>{() => <AssistantMessageContainer />}</ThreadPrimitive.Messages>
+ </RuntimeHarness>,
+ );
+}
+
+describe('AssistantTextContainer', () => {
+ it('renders markdown formatting from the live text part', () => {
+ renderAssistantMessage([{ role: 'assistant', content: '**bold** text' }]);
+ const strong = screen.getByText('bold');
+ expect(strong.tagName).toBe('STRONG');
+ });
+
+ it('renders plain streaming text as it grows', () => {
+ renderAssistantMessage([{ role: 'assistant', content: 'partial toke' }]);
+ expect(screen.getByText('partial toke')).toBeInTheDocument();
+ });
+
+ it('renders openui fenced blocks via OpenUiFenceBlock instead of a code pre', async () => {
+ renderAssistantMessage([
+ {
+ role: 'assistant',
+ content: '```openui\nCard() { title: "Sales" }\n```',
+ },
+ ]);
+ // Lazy import resolves asynchronously; wait for Suspense to settle.
+ await waitFor(() => {
+ expect(screen.getByTestId('aui-openui-renderer')).toBeInTheDocument();
+ });
+ expect(screen.getByTestId('aui-openui-renderer')).toHaveTextContent('Card() { title: "Sales" }');
+ expect(document.querySelector('.code-block-header')).not.toBeInTheDocument();
+ });
+
+ it('passes the runtime-backed artifact download handler to markdown', () => {
+ function Markdown({ onDownloadArtifact }: MarkdownProps) {
+ return <div data-testid="artifact-download-handler">{typeof onDownloadArtifact}</div>;
+ }
+
+ render(
+ <RuntimeHarness messages={[{ role: 'assistant', content: 'artifact' }]}>
+ <SlotsProvider overrides={{ Markdown }}>
+ <ThreadPrimitive.Messages>{() => <AssistantMessageContainer />}</ThreadPrimitive.Messages>
+ </SlotsProvider>
+ </RuntimeHarness>,
+ );
+
+ expect(screen.getByTestId('artifact-download-handler')).toHaveTextContent('function');
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/AssistantTextContainer.tsx b/packages/trueforge-ui-sdk/src/containers/AssistantTextContainer.tsx
new file mode 100644
index 000000000..a0899e73f
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/AssistantTextContainer.tsx
@@ -0,0 +1,66 @@
+'use client';
+
+import {
+ useAuiState,
+ useSmooth,
+ type MessagePartState,
+ type ReasoningMessagePart,
+ type TextMessagePart,
+} from '@assistant-ui/react';
+import { useTrueFoundryDownloadSandboxFile } from '@truefoundry/assistant-ui-runtime';
+import { useCallback, useRef } from 'react';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+import { useErrorToasterOptional } from './ErrorToasterContainer.js';
+
+function filenameFromPath(path: string): string {
+ return path.split('/').pop() || 'download';
+}
+
+function triggerBrowserDownload(blob: Blob, filename: string) {
+ if (typeof document === 'undefined') return;
+ const url = URL.createObjectURL(blob);
+ const anchor = document.createElement('a');
+ anchor.href = url;
+ anchor.download = filename;
+ anchor.click();
+ URL.revokeObjectURL(url);
+}
+
+export function AssistantTextContainer() {
+ const Markdown = useSlot('Markdown');
+ // Runtime download fn is unstable; refs keep onDownloadArtifact stable so OpenUI doesn't remount.
+ const downloadSandboxFile = useTrueFoundryDownloadSandboxFile();
+ const errorToaster = useErrorToasterOptional();
+ const downloadSandboxFileRef = useRef(downloadSandboxFile);
+ const errorToasterRef = useRef(errorToaster);
+ downloadSandboxFileRef.current = downloadSandboxFile;
+ errorToasterRef.current = errorToaster;
+ const partState = useAuiState(s => s.part as MessagePartState & (TextMessagePart | ReasoningMessagePart));
+ const smoothedPart = useSmooth(partState, {
+ drainMs: 300,
+ maxCharIntervalMs: 6,
+ maxCharsPerFrame: 32,
+ minCommitMs: 48,
+ });
+ const text = smoothedPart.text;
+ // true while network stream is active OR while reveal is still catching up
+ const isStreaming = smoothedPart.status?.type === 'running';
+ const handleDownloadArtifact = useCallback(
+ (path: string) =>
+ downloadSandboxFileRef
+ .current(path)
+ .then(blob => triggerBrowserDownload(blob, filenameFromPath(path)))
+ .catch(error => {
+ const toaster = errorToasterRef.current;
+ if (toaster != null) {
+ toaster.showError(error);
+ } else {
+ console.error('Failed to download sandbox artifact', error);
+ }
+ }),
+ [],
+ );
+
+ return <Markdown content={text} isStreaming={isStreaming} onDownloadArtifact={handleDownloadArtifact} />;
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/AttachmentsContainer.tsx b/packages/trueforge-ui-sdk/src/containers/AttachmentsContainer.tsx
new file mode 100644
index 000000000..96dbcf0a0
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/AttachmentsContainer.tsx
@@ -0,0 +1,83 @@
+'use client';
+
+import { ComposerPrimitive, MessagePrimitive, useAui, useAuiState } from '@assistant-ui/react';
+
+import { USER_MESSAGE_ATTACHMENT_PREVIEW_REM } from '../constants/attachments.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+import { isImageAttachment, useAttachmentPreviewSrc } from './useAttachmentPreviewSrc.js';
+
+function ComposerAttachmentItem() {
+ const AttachmentPreviewDialog = useSlot('AttachmentPreviewDialog');
+ const AttachmentCard = useSlot('AttachmentCard');
+ const aui = useAui();
+ const name = useAuiState(s => s.attachment.name);
+ const contentType = useAuiState(s => s.attachment.contentType);
+ const type = useAuiState(s => s.attachment.type);
+ const isImage = isImageAttachment(type, contentType);
+ const previewSrc = useAttachmentPreviewSrc();
+
+ return (
+ <AttachmentPreviewDialog previewSrc={previewSrc}>
+ <AttachmentCard
+ name={name}
+ contentType={contentType}
+ previewSrc={previewSrc}
+ isImage={isImage}
+ size="chip"
+ onRemove={() => void aui.attachment().remove()}
+ />
+ </AttachmentPreviewDialog>
+ );
+}
+
+function MessageAttachmentItem() {
+ const AttachmentPreviewDialog = useSlot('AttachmentPreviewDialog');
+ const AttachmentCard = useSlot('AttachmentCard');
+ const name = useAuiState(s => s.attachment.name);
+ const contentType = useAuiState(s => s.attachment.contentType);
+ const type = useAuiState(s => s.attachment.type);
+ const isImage = isImageAttachment(type, contentType);
+ const previewSrc = useAttachmentPreviewSrc();
+
+ const card = (
+ <AttachmentCard
+ name={name}
+ contentType={contentType}
+ previewSrc={previewSrc}
+ isImage={isImage}
+ size={isImage ? 'preview' : 'chip'}
+ previewRem={USER_MESSAGE_ATTACHMENT_PREVIEW_REM}
+ />
+ );
+
+ if (isImage && previewSrc) {
+ return <AttachmentPreviewDialog previewSrc={previewSrc}>{card}</AttachmentPreviewDialog>;
+ }
+
+ return card;
+}
+
+export function ComposerAttachmentsContainer() {
+ return (
+ <div className="aui-composer-attachments flex w-full flex-row flex-wrap items-center gap-2 empty:hidden">
+ <ComposerPrimitive.Attachments>{() => <ComposerAttachmentItem />}</ComposerPrimitive.Attachments>
+ </div>
+ );
+}
+
+export function MessageAttachmentsContainer() {
+ return (
+ <div className="aui-user-message-attachments-end col-span-full col-start-1 row-start-1 flex w-full flex-row justify-end gap-2">
+ <MessagePrimitive.Attachments>{() => <MessageAttachmentItem />}</MessagePrimitive.Attachments>
+ </div>
+ );
+}
+
+export function ComposerAttachmentPickerContainer() {
+ const AttachmentPickerButton = useSlot('AttachmentPickerButton');
+ return (
+ <ComposerPrimitive.AddAttachment asChild>
+ <AttachmentPickerButton />
+ </ComposerPrimitive.AddAttachment>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/ComposerContainer.test.tsx b/packages/trueforge-ui-sdk/src/containers/ComposerContainer.test.tsx
new file mode 100644
index 000000000..f5a569778
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ComposerContainer.test.tsx
@@ -0,0 +1,96 @@
+// @vitest-environment jsdom
+import type { AppendMessage } from '@assistant-ui/react';
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ComposerBusyProvider } from '../hooks/useComposerBusyState.js';
+import { ShellModeProvider } from '../server/ShellModeContext.js';
+import { SlotsProvider } from '../theme/SlotsProvider.js';
+import { ComposerContainer } from './ComposerContainer.js';
+import { RuntimeHarness } from './RuntimeHarness.js';
+
+vi.mock('@truefoundry/assistant-ui-runtime', () => ({
+ useTrueFoundryCancel: () => vi.fn(),
+ useTrueFoundryToolResponses: () => ({ pending: [] }),
+}));
+
+function renderComposer(onNew?: (message: AppendMessage) => Promise<void>) {
+ return render(
+ <RuntimeHarness messages={[]} onNew={onNew}>
+ <ComposerBusyProvider>
+ <ComposerContainer />
+ </ComposerBusyProvider>
+ </RuntimeHarness>,
+ );
+}
+
+describe('ComposerContainer', () => {
+ it('wraps the composer in an attachment dropzone by default', () => {
+ renderComposer();
+ const dropzone = document.querySelector('[data-slot="aui_composer-attachment-dropzone"]');
+ expect(dropzone).toBeInTheDocument();
+ expect(screen.getByRole('textbox', { name: 'Message input' })).toBeInTheDocument();
+ });
+
+ it('marks the dropzone as dragging on drag enter', () => {
+ renderComposer();
+ const dropzone = document.querySelector('[data-slot="aui_composer-attachment-dropzone"]');
+ expect(dropzone).not.toBeNull();
+ fireEvent.dragEnter(dropzone!);
+ expect(dropzone).toHaveAttribute('data-dragging', 'true');
+ });
+
+ it('keeps the caret in place when text is inserted mid-string', () => {
+ renderComposer();
+ const input = screen.getByRole('textbox', { name: 'Message input' }) as HTMLTextAreaElement;
+
+ fireEvent.change(input, { target: { value: 'hello world' } });
+ fireEvent.change(input, {
+ target: { value: 'hello Xworld', selectionStart: 7, selectionEnd: 7 },
+ });
+
+ expect(input.value).toBe('hello Xworld');
+ expect(input.selectionStart).toBe(7);
+ });
+
+ it('submits once on Enter and inserts a newline on Shift+Enter', async () => {
+ const onNew = vi.fn(async () => {});
+ renderComposer(onNew);
+ const input = screen.getByRole('textbox', { name: 'Message input' }) as HTMLTextAreaElement;
+
+ fireEvent.change(input, { target: { value: 'hi' } });
+ fireEvent.keyDown(input, { key: 'Enter', shiftKey: true });
+ expect(onNew).not.toHaveBeenCalled();
+
+ fireEvent.keyDown(input, { key: 'Enter' });
+ await waitFor(() => expect(input.value).toBe(''));
+ expect(onNew).toHaveBeenCalledTimes(1);
+ });
+
+ it('preserves consumer section overrides in draft mode', () => {
+ render(
+ <SlotsProvider
+ overrides={{
+ ComposerLeftSection: () => <div>Custom left</div>,
+ ComposerRightSection: () => <div>Custom right</div>,
+ }}
+ >
+ <ShellModeProvider
+ agentConfig={{
+ mode: 'AgentComposer',
+ defaultAgentSpec: { model: { name: 'test/model' } },
+ }}
+ >
+ <RuntimeHarness messages={[]}>
+ <ComposerBusyProvider>
+ <ComposerContainer />
+ </ComposerBusyProvider>
+ </RuntimeHarness>
+ </ShellModeProvider>
+ </SlotsProvider>,
+ );
+
+ expect(screen.getByText('Custom left')).toBeInTheDocument();
+ expect(screen.getByText('Custom right')).toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/ComposerContainer.tsx b/packages/trueforge-ui-sdk/src/containers/ComposerContainer.tsx
new file mode 100644
index 000000000..abc1eb359
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ComposerContainer.tsx
@@ -0,0 +1,141 @@
+'use client';
+
+import { ComposerPrimitive, useAui, useAuiState } from '@assistant-ui/react';
+import { useTrueFoundryCancel } from '@truefoundry/assistant-ui-runtime';
+import { useRef } from 'react';
+
+import {
+ ComposerLeftSection as DefaultComposerLeftSection,
+ ComposerRightSection as DefaultComposerRightSection,
+} from '../atoms/ComposerSections.js';
+import { DraftCatalogProvider } from '../atoms/draft/DraftCatalogProvider.js';
+import { DraftComposerLeftSection, DraftComposerRightSection } from '../atoms/draft/DraftComposerSections.js';
+import { useComposerBusyState } from '../hooks/useComposerBusyState.js';
+import { useComposerPauseView } from '../hooks/useComposerPauseView.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import { SlotsProvider, useSlot } from '../theme/SlotsProvider.js';
+import { AskUserContainer } from './AskUserContainer.js';
+import { ComposerAttachmentsContainer } from './AttachmentsContainer.js';
+import { McpAuthContainer } from './McpAuthContainer.js';
+
+export type ComposerContainerProps = {
+ placeholder?: string;
+};
+
+/**
+ * Use draft UI only when the host did not override the slot.
+ * Example: host overrides LeftSection → keep host; else → DraftComposerLeftSection.
+ */
+function preferHostSlotOverride<T>(parentSlot: T, stockDefault: T, draftDefault: T): T {
+ return parentSlot === stockDefault ? draftDefault : parentSlot;
+}
+
+function ComposerBody({ placeholder }: { placeholder: string }) {
+ const ComposerShell = useSlot('ComposerShell');
+ const aui = useAui();
+ const hasText = useAuiState(s => s.composer.text.trim().length > 0);
+ const { isBusy, send, resetBusy } = useComposerBusyState();
+ const cancel = useTrueFoundryCancel();
+ const fileInputRef = useRef<HTMLInputElement>(null);
+ const submit = () => send(() => aui.composer().send());
+
+ return (
+ <>
+ <input
+ ref={fileInputRef}
+ type="file"
+ multiple
+ hidden
+ onChange={event => {
+ const files = event.target.files;
+ if (files) {
+ for (const file of files) {
+ void aui.composer().addAttachment(file);
+ }
+ }
+ event.target.value = '';
+ }}
+ />
+ <ComposerPrimitive.AttachmentDropzone
+ disabled={isBusy}
+ data-slot="aui_composer-attachment-dropzone"
+ className="w-full rounded-[var(--composer-radius,1.5rem)] transition-[box-shadow] data-[dragging=true]:ring-ring/20 data-[dragging=true]:ring-3"
+ >
+ <ComposerPrimitive.Root
+ data-slot="aui_composer-root"
+ className="w-full"
+ onSubmit={event => {
+ // Suppresses the primitive's own send so submits route through the busy-state wrapper.
+ event.preventDefault();
+ submit();
+ }}
+ >
+ <ComposerShell
+ attachments={<ComposerAttachmentsContainer />}
+ input={
+ <ComposerPrimitive.Input
+ data-slot="aui_composer-input"
+ placeholder={placeholder}
+ disabled={isBusy}
+ submitMode="enter"
+ aria-label="Message input"
+ className="text-foreground placeholder:text-muted-foreground/80 max-h-[10lh] min-h-10 w-full resize-none overflow-y-auto rounded-lg border-none bg-transparent px-1 py-1 text-base leading-normal shadow-none outline-none"
+ />
+ }
+ disabled={isBusy}
+ canSubmit={!isBusy && hasText}
+ isRunning={isBusy}
+ onSubmit={submit}
+ onCancel={() => {
+ resetBusy();
+ void cancel();
+ }}
+ onAttach={() => fileInputRef.current?.click()}
+ />
+ </ComposerPrimitive.Root>
+ </ComposerPrimitive.AttachmentDropzone>
+ </>
+ );
+}
+
+export function ComposerContainer({
+ placeholder = 'Ask anything... (Shift+Enter for new line)',
+}: ComposerContainerProps) {
+ const pauseView = useComposerPauseView();
+ const shell = useOptionalShellMode();
+ const parentLeftSection = useSlot('ComposerLeftSection');
+ const parentRightSection = useSlot('ComposerRightSection');
+ const isDraft = shell?.mode.type === 'draft';
+
+ if (pauseView.kind === 'mcp') {
+ return <McpAuthContainer />;
+ }
+ if (pauseView.kind === 'ask-user') {
+ return <AskUserContainer />;
+ }
+
+ if (isDraft) {
+ return (
+ <DraftCatalogProvider>
+ <SlotsProvider
+ overrides={{
+ ComposerLeftSection: preferHostSlotOverride(
+ parentLeftSection,
+ DefaultComposerLeftSection,
+ DraftComposerLeftSection,
+ ),
+ ComposerRightSection: preferHostSlotOverride(
+ parentRightSection,
+ DefaultComposerRightSection,
+ DraftComposerRightSection,
+ ),
+ }}
+ >
+ <ComposerBody placeholder={placeholder} />
+ </SlotsProvider>
+ </DraftCatalogProvider>
+ );
+ }
+
+ return <ComposerBody placeholder={placeholder} />;
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/ErrorToasterContainer.test.tsx b/packages/trueforge-ui-sdk/src/containers/ErrorToasterContainer.test.tsx
new file mode 100644
index 000000000..d7d25eabd
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ErrorToasterContainer.test.tsx
@@ -0,0 +1,83 @@
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { Toast } from '../atoms/Toast.js';
+import { SlotsProvider } from '../theme/SlotsProvider.js';
+import { ErrorToasterProvider, useErrorToaster } from './ErrorToasterContainer.js';
+
+function Trigger({ errors }: { errors: unknown[] }) {
+ const { showError } = useErrorToaster();
+ return (
+ <button
+ type="button"
+ onClick={() => {
+ for (const error of errors) showError(error);
+ }}
+ >
+ boom
+ </button>
+ );
+}
+
+describe('ErrorToasterProvider', () => {
+ beforeEach(() => {
+ vi.spyOn(console, 'error').mockImplementation(() => {});
+ });
+
+ it('stacks multiple error toasts', async () => {
+ render(
+ <SlotsProvider>
+ <ErrorToasterProvider>
+ <Trigger errors={[new Error('first'), new Error('second')]} />
+ </ErrorToasterProvider>
+ </SlotsProvider>,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'boom' }));
+
+ expect(await screen.findByText('first')).toBeTruthy();
+ expect(screen.getByText('second')).toBeTruthy();
+ expect(screen.getAllByRole('alert')).toHaveLength(2);
+ });
+
+ it('dismisses one toast without removing the other', async () => {
+ render(
+ <SlotsProvider>
+ <ErrorToasterProvider>
+ <Trigger errors={[new Error('keep-me'), new Error('drop-me')]} />
+ </ErrorToasterProvider>
+ </SlotsProvider>,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'boom' }));
+ expect(await screen.findByText('drop-me')).toBeTruthy();
+
+ const dropToast = screen.getByText('drop-me').closest("[role='alert']");
+ expect(dropToast).toBeTruthy();
+ fireEvent.click(dropToast!.querySelector('[aria-label="Close"]')!);
+
+ await waitFor(() => {
+ expect(screen.queryByText('drop-me')).toBeNull();
+ });
+ expect(screen.getByText('keep-me')).toBeTruthy();
+ });
+});
+
+describe('Toast copy', () => {
+ it('copies title and description', async () => {
+ const writeText = vi.fn().mockResolvedValue(undefined);
+ Object.assign(navigator, { clipboard: { writeText } });
+
+ render(
+ <SlotsProvider>
+ <Toast title="Request failed" description="body detail" open onOpenChange={() => {}} />
+ </SlotsProvider>,
+ );
+
+ await act(async () => {
+ fireEvent.click(screen.getByRole('button', { name: 'Copy' }));
+ });
+
+ expect(writeText).toHaveBeenCalledWith('Request failed\nbody detail');
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/ErrorToasterContainer.tsx b/packages/trueforge-ui-sdk/src/containers/ErrorToasterContainer.tsx
new file mode 100644
index 000000000..61da63c03
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ErrorToasterContainer.tsx
@@ -0,0 +1,114 @@
+'use client';
+
+import { createContext, useCallback, useContext, useMemo, useState, type ReactNode } from 'react';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+
+const MAX_TOAST_DESCRIPTION_CHARS = 480;
+const MAX_VISIBLE_TOASTS = 5;
+
+type ErrorToastContent = { title: string; description: string };
+
+type ErrorToastItem = ErrorToastContent & { id: string };
+
+type ErrorToasterContextValue = { showError: (error: unknown) => void };
+
+const ErrorToasterContext = createContext<ErrorToasterContextValue | null>(null);
+
+let toastId = 0;
+function nextToastId(): string {
+ toastId += 1;
+ return `error-toast-${toastId}`;
+}
+
+function truncateDescription(text: string): string {
+ if (text.length <= MAX_TOAST_DESCRIPTION_CHARS) return text;
+ return `${text.slice(0, MAX_TOAST_DESCRIPTION_CHARS - 1)}…`;
+}
+
+function formatErrorBody(body: unknown): string | undefined {
+ if (body == null) return undefined;
+ if (typeof body === 'string') return body;
+ try {
+ return JSON.stringify(body, null, 2);
+ } catch {
+ return String(body);
+ }
+}
+
+function isHttpLikeError(error: unknown): error is Error & { statusCode?: number; body?: unknown } {
+ return error instanceof Error && ('statusCode' in error || 'body' in error);
+}
+
+function normalizeError(error: unknown): ErrorToastContent {
+ if (isHttpLikeError(error)) {
+ const statusCode = error.statusCode;
+ if (statusCode != null || error.body != null) {
+ const title = statusCode != null ? `Request failed (${statusCode})` : 'Request failed';
+ const raw = formatErrorBody(error.body) ?? (error.message || 'The server returned an error.');
+ return { title, description: truncateDescription(raw) };
+ }
+ }
+
+ if (error instanceof Error) {
+ return {
+ title: 'Something went wrong',
+ description: truncateDescription(error.message || 'An unexpected error occurred.'),
+ };
+ }
+
+ return {
+ title: 'Something went wrong',
+ description: truncateDescription(String(error)),
+ };
+}
+
+export function ErrorToasterProvider({ children }: { children: ReactNode }) {
+ const Toast = useSlot('Toast');
+ const ToastStack = useSlot('ToastStack');
+ const [toasts, setToasts] = useState<ErrorToastItem[]>([]);
+
+ const showError = useCallback((error: unknown) => {
+ console.error('[trueforge-ui]', error);
+ const item: ErrorToastItem = { id: nextToastId(), ...normalizeError(error) };
+ setToasts(prev => [...prev, item].slice(-MAX_VISIBLE_TOASTS));
+ }, []);
+
+ const dismiss = useCallback((id: string) => {
+ setToasts(prev => prev.filter(t => t.id !== id));
+ }, []);
+
+ const value = useMemo(() => ({ showError }), [showError]);
+
+ return (
+ <ErrorToasterContext.Provider value={value}>
+ {children}
+ <ToastStack>
+ {toasts.map(toast => (
+ <Toast
+ key={toast.id}
+ title={toast.title}
+ description={toast.description}
+ open
+ onOpenChange={open => {
+ if (!open) dismiss(toast.id);
+ }}
+ />
+ ))}
+ </ToastStack>
+ </ErrorToasterContext.Provider>
+ );
+}
+
+export function useErrorToaster(): ErrorToasterContextValue {
+ const context = useContext(ErrorToasterContext);
+ if (context == null) {
+ throw new Error('useErrorToaster must be used within ErrorToasterProvider');
+ }
+ return context;
+}
+
+/** Same as `useErrorToaster`, but returns `null` instead of throwing outside `ErrorToasterProvider`. */
+export function useErrorToasterOptional(): ErrorToasterContextValue | null {
+ return useContext(ErrorToasterContext);
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/HistoryLoaderContainer.test.tsx b/packages/trueforge-ui-sdk/src/containers/HistoryLoaderContainer.test.tsx
new file mode 100644
index 000000000..308dd1c0c
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/HistoryLoaderContainer.test.tsx
@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+import { AssistantRuntimeProvider, useExternalStoreRuntime, type ThreadMessageLike } from '@assistant-ui/react';
+import { render, screen, waitFor } from '@testing-library/react';
+import { trueFoundryExtras } from '@truefoundry/assistant-ui-runtime';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { HistoryLoaderContainer } from './HistoryLoaderContainer.js';
+
+type ObserverCallback = (entries: Array<{ isIntersecting: boolean }>) => void;
+
+let observerCallbacks: ObserverCallback[] = [];
+
+class IntersectionObserverStub {
+ constructor(callback: ObserverCallback) {
+ observerCallbacks.push(callback);
+ }
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+
+beforeEach(() => {
+ observerCallbacks = [];
+ globalThis.IntersectionObserver = IntersectionObserverStub as unknown as typeof IntersectionObserver;
+});
+
+afterEach(() => {
+ // @ts-expect-error jsdom has no IntersectionObserver; remove the stub.
+ delete globalThis.IntersectionObserver;
+});
+
+function Harness({
+ hasOlderHistory,
+ isLoadingOlderHistory = false,
+ loadOlderHistory = async () => {},
+}: {
+ hasOlderHistory: boolean;
+ isLoadingOlderHistory?: boolean;
+ loadOlderHistory?: () => Promise<void>;
+}) {
+ const messages: ThreadMessageLike[] = [];
+ const runtime = useExternalStoreRuntime({
+ messages,
+ isRunning: false,
+ convertMessage: (m: ThreadMessageLike) => m,
+ onNew: async () => {},
+ extras: trueFoundryExtras.provide({
+ pendingApprovals: [],
+ pendingToolResponses: [],
+ pendingMcpAuth: null,
+ sandboxId: undefined,
+ respondToToolApproval: () => {},
+ respondToToolResponse: () => {},
+ resumeMcpAuth: async () => {},
+ downloadSandboxFile: async () => new Blob(),
+ cancel: async () => {},
+ resetFromTurn: async () => {},
+ reload: () => {},
+ hasOlderHistory,
+ isLoadingOlderHistory,
+ loadOlderHistory,
+ draft: null,
+ }),
+ });
+
+ return (
+ <AssistantRuntimeProvider runtime={runtime}>
+ <HistoryLoaderContainer />
+ </AssistantRuntimeProvider>
+ );
+}
+
+describe('HistoryLoaderContainer', () => {
+ it('renders nothing when there is no older history', () => {
+ render(<Harness hasOlderHistory={false} />);
+ expect(screen.queryByRole('status')).not.toBeInTheDocument();
+ });
+
+ it('renders the sentinel when older history is available', () => {
+ render(<Harness hasOlderHistory={true} />);
+ expect(screen.getByRole('status', { name: 'Scroll up to load older messages' })).toBeInTheDocument();
+ });
+
+ it('shows the spinner while a page is being fetched', () => {
+ render(<Harness hasOlderHistory={true} isLoadingOlderHistory={true} />);
+ expect(screen.getByRole('status', { name: 'Loading older messages' })).toBeInTheDocument();
+ });
+
+ it('loads older history when the sentinel intersects the viewport', async () => {
+ const loadOlderHistory = vi.fn().mockResolvedValue(undefined);
+ render(<Harness hasOlderHistory={true} loadOlderHistory={loadOlderHistory} />);
+
+ expect(observerCallbacks.length).toBeGreaterThan(0);
+ observerCallbacks.forEach(cb => cb([{ isIntersecting: true }]));
+
+ await waitFor(() => expect(loadOlderHistory).toHaveBeenCalledTimes(1));
+ });
+
+ it('ignores intersection entries that are not intersecting', async () => {
+ const loadOlderHistory = vi.fn().mockResolvedValue(undefined);
+ render(<Harness hasOlderHistory={true} loadOlderHistory={loadOlderHistory} />);
+
+ observerCallbacks.forEach(cb => cb([{ isIntersecting: false }]));
+
+ await new Promise(resolve => setTimeout(resolve, 0));
+ expect(loadOlderHistory).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/HistoryLoaderContainer.tsx b/packages/trueforge-ui-sdk/src/containers/HistoryLoaderContainer.tsx
new file mode 100644
index 000000000..11d95a48a
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/HistoryLoaderContainer.tsx
@@ -0,0 +1,73 @@
+'use client';
+
+import { useTrueFoundryHistoryPagination } from '@truefoundry/assistant-ui-runtime';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+
+/** How close to the viewport top (px) before the next older page is fetched. */
+const TOP_THRESHOLD_PX = 200;
+
+const VIEWPORT_SELECTOR = '[data-slot="aui_thread-viewport"]';
+
+/**
+ * Renders `HistoryLoader` at the top of the message list and fetches
+ * the next older history page when the user scrolls near it. Scroll position
+ * is preserved across the prepend so the list doesn't jump.
+ *
+ * Must be rendered inside `ThreadViewportShell` (it locates the scroll root
+ * via the `aui_thread-viewport` data-slot on its nearest scrollable ancestor).
+ */
+export function HistoryLoaderContainer() {
+ const HistoryLoader = useSlot('HistoryLoader');
+ const { hasOlderHistory, isLoadingOlderHistory, loadOlderHistory } = useTrueFoundryHistoryPagination();
+
+ const [sentinel, setSentinel] = useState<HTMLDivElement | null>(null);
+ const inflightRef = useRef(false);
+
+ const maybeLoadOlder = useCallback(async () => {
+ if (inflightRef.current) return;
+ inflightRef.current = true;
+
+ const viewport = sentinel?.closest<HTMLElement>(VIEWPORT_SELECTOR) ?? null;
+ const prevScrollHeight = viewport?.scrollHeight ?? 0;
+ const prevScrollTop = viewport?.scrollTop ?? 0;
+
+ try {
+ await loadOlderHistory();
+ // Wait for React to commit the prepended messages, then restore the
+ // user's anchor so the list doesn't jump to the oldest message.
+ requestAnimationFrame(() => {
+ if (viewport == null) return;
+ const delta = viewport.scrollHeight - prevScrollHeight;
+ if (delta > 0) {
+ viewport.scrollTo({ top: prevScrollTop + delta, behavior: 'instant' });
+ }
+ });
+ } catch {
+ // Runtime surfaces the error via onError; the sentinel stays retryable.
+ } finally {
+ inflightRef.current = false;
+ }
+ }, [sentinel, loadOlderHistory]);
+
+ useEffect(() => {
+ if (sentinel == null || !hasOlderHistory) return;
+
+ const viewport = sentinel.closest<HTMLElement>(VIEWPORT_SELECTOR);
+ const observer = new IntersectionObserver(
+ entries => {
+ if (entries.some(entry => entry.isIntersecting)) {
+ void maybeLoadOlder();
+ }
+ },
+ { root: viewport, rootMargin: `${TOP_THRESHOLD_PX}px 0px 0px 0px` },
+ );
+ observer.observe(sentinel);
+ return () => observer.disconnect();
+ }, [sentinel, hasOlderHistory, maybeLoadOlder]);
+
+ if (!hasOlderHistory) return null;
+
+ return <HistoryLoader ref={setSentinel} isLoading={isLoadingOlderHistory} />;
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/McpAuthContainer.test.tsx b/packages/trueforge-ui-sdk/src/containers/McpAuthContainer.test.tsx
new file mode 100644
index 000000000..217cdadfd
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/McpAuthContainer.test.tsx
@@ -0,0 +1,91 @@
+// @vitest-environment jsdom
+import { AssistantRuntimeProvider, useExternalStoreRuntime, type ThreadMessageLike } from '@assistant-ui/react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { trueFoundryExtras, type TrueFoundryRuntimeExtras } from '@truefoundry/assistant-ui-runtime';
+import { describe, expect, it, vi } from 'vitest';
+
+import { McpAuthContainer } from './McpAuthContainer.js';
+
+const SERVERS = [
+ { id: 'srv-1', name: 'github', authUrl: 'https://example.com/auth/github' },
+ { id: 'srv-2', name: 'slack', authUrl: 'https://example.com/auth/slack' },
+];
+const PENDING = { mcpServers: SERVERS };
+
+function McpAuthHarness({
+ pendingMcpAuth,
+ resumeMcpAuth,
+ isRunning = false,
+}: {
+ pendingMcpAuth: TrueFoundryRuntimeExtras['pendingMcpAuth'];
+ resumeMcpAuth: TrueFoundryRuntimeExtras['resumeMcpAuth'];
+ isRunning?: boolean;
+}) {
+ const messages: ThreadMessageLike[] = [];
+ const runtime = useExternalStoreRuntime({
+ messages,
+ isRunning,
+ convertMessage: (m: ThreadMessageLike) => m,
+ onNew: async () => {},
+ extras: trueFoundryExtras.provide({
+ pendingApprovals: [],
+ pendingToolResponses: [],
+ pendingMcpAuth,
+ sandboxId: undefined,
+ respondToToolApproval: () => {},
+ respondToToolResponse: () => {},
+ resumeMcpAuth,
+ downloadSandboxFile: async () => new Blob(),
+ cancel: async () => {},
+ resetFromTurn: async () => {},
+ reload: () => {},
+ hasOlderHistory: false,
+ isLoadingOlderHistory: false,
+ loadOlderHistory: async () => {},
+ draft: null,
+ }),
+ });
+
+ return (
+ <AssistantRuntimeProvider runtime={runtime}>
+ <McpAuthContainer />
+ </AssistantRuntimeProvider>
+ );
+}
+
+describe('McpAuthContainer', () => {
+ it('renders nothing when there is no pending MCP auth', () => {
+ render(<McpAuthHarness pendingMcpAuth={null} resumeMcpAuth={vi.fn()} />);
+ expect(screen.queryByRole('button', { name: /continue/i })).not.toBeInTheDocument();
+ });
+
+ it('renders a Connect button per server that opens auth in a new tab', () => {
+ const openSpy = vi.spyOn(window, 'open').mockImplementation(() => null);
+ render(<McpAuthHarness pendingMcpAuth={PENDING} resumeMcpAuth={vi.fn().mockResolvedValue(undefined)} />);
+ expect(screen.getByText('github')).toBeInTheDocument();
+ expect(screen.getByText('slack')).toBeInTheDocument();
+
+ const connectButtons = screen.getAllByRole('button', { name: /connect/i });
+ expect(connectButtons).toHaveLength(2);
+
+ fireEvent.click(connectButtons[0]!);
+ fireEvent.click(connectButtons[1]!);
+
+ expect(openSpy).toHaveBeenCalledWith('https://example.com/auth/github', '_blank', 'noopener,noreferrer');
+ expect(openSpy).toHaveBeenCalledWith('https://example.com/auth/slack', '_blank', 'noopener,noreferrer');
+ openSpy.mockRestore();
+ });
+
+ it('calls resume when Continue is clicked', () => {
+ const resumeMcpAuth = vi.fn().mockResolvedValue(undefined);
+ render(<McpAuthHarness pendingMcpAuth={PENDING} resumeMcpAuth={resumeMcpAuth} isRunning={false} />);
+
+ fireEvent.click(screen.getByRole('button', { name: /continue/i }));
+ expect(resumeMcpAuth).toHaveBeenCalledTimes(1);
+ });
+
+ it('disables Continue while the thread is running', () => {
+ render(<McpAuthHarness pendingMcpAuth={PENDING} resumeMcpAuth={vi.fn()} isRunning={true} />);
+ expect(screen.getByRole('button', { name: /continue/i })).toBeDisabled();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/McpAuthContainer.tsx b/packages/trueforge-ui-sdk/src/containers/McpAuthContainer.tsx
new file mode 100644
index 000000000..35be2d792
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/McpAuthContainer.tsx
@@ -0,0 +1,30 @@
+'use client';
+
+import { useThreadIsRunning } from '@assistant-ui/core/react';
+import { useTrueFoundryMcpAuth } from '@truefoundry/assistant-ui-runtime';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+
+export function McpAuthContainer() {
+ const McpAuthPrompt = useSlot('McpAuthPrompt');
+ const { pending, resume } = useTrueFoundryMcpAuth();
+ const isRunning = useThreadIsRunning();
+
+ if (!pending) return null;
+
+ const handleConnect = (serverId: string) => {
+ const server = pending.mcpServers.find(s => s.id === serverId);
+ if (server?.authUrl) {
+ window.open(server.authUrl, '_blank', 'noopener,noreferrer');
+ }
+ };
+
+ return (
+ <McpAuthPrompt
+ servers={pending.mcpServers}
+ onConnect={handleConnect}
+ onContinue={() => void resume()}
+ readOnly={isRunning}
+ />
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/McpOauthContainer/PostMcpOauthScreen.tsx b/packages/trueforge-ui-sdk/src/containers/McpOauthContainer/PostMcpOauthScreen.tsx
new file mode 100644
index 000000000..b7ba363fa
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/McpOauthContainer/PostMcpOauthScreen.tsx
@@ -0,0 +1,70 @@
+'use client';
+
+import { CheckCircle2, LoaderCircle, XCircle } from 'lucide-react';
+import { useEffect, useState } from 'react';
+
+import { MCP_AUTH_POPUP_CHANNEL, type McpAuthPopupMessage } from '../../hooks/useMcpAuth.js';
+
+const BROADCAST_RETRY_DELAY_MS = 1000;
+const WINDOW_CLOSE_DELAY_MS = 2000;
+
+const PostMcpOauthScreen = () => {
+ const [result, setResult] = useState<McpAuthPopupMessage | null>();
+
+ useEffect(() => {
+ const searchParams = new URLSearchParams(window.location.search);
+ const popupUid = searchParams.get('pUid');
+ const isSuccess = searchParams.get('isSuccess')?.toLowerCase() === 'true';
+ setResult(popupUid ? { popupUid, isSuccess } : null);
+
+ const broadcastResult = () => {
+ if (!popupUid) return;
+
+ const channel = new BroadcastChannel(MCP_AUTH_POPUP_CHANNEL);
+ const message: McpAuthPopupMessage = { popupUid, isSuccess };
+ channel.postMessage(message);
+ channel.close();
+ };
+
+ broadcastResult();
+ const retryTimeout = window.setTimeout(broadcastResult, BROADCAST_RETRY_DELAY_MS);
+ const closeTimeout = window.setTimeout(() => {
+ window.close();
+ }, WINDOW_CLOSE_DELAY_MS);
+
+ return () => {
+ window.clearTimeout(retryTimeout);
+ window.clearTimeout(closeTimeout);
+ };
+ }, []);
+
+ const isSuccess = !!result?.isSuccess;
+ const title =
+ result === undefined ? 'Completing authorization' : isSuccess ? 'Authorization successful' : 'Authorization failed';
+ const description =
+ result === undefined
+ ? 'Please wait while the authorization result is confirmed.'
+ : result === null
+ ? 'The authorization result is invalid. You can close this window and try again.'
+ : isSuccess
+ ? 'The MCP server is now connected. This window will close automatically.'
+ : 'The MCP server could not be authorized. You can close this window and try again.';
+
+ return (
+ <main className="flex min-h-screen items-center justify-center bg-background p-6">
+ <div className="flex w-full max-w-md flex-col items-center gap-3 rounded-2xl border border-border bg-card p-8 text-center shadow-sm">
+ {result === undefined ? (
+ <LoaderCircle className="size-16 animate-spin text-muted-foreground" aria-hidden />
+ ) : isSuccess ? (
+ <CheckCircle2 className="size-16 text-green-600" aria-hidden />
+ ) : (
+ <XCircle className="size-16 text-destructive" aria-hidden />
+ )}
+ <h1 className="text-2xl font-semibold text-foreground">{title}</h1>
+ <p className="text-sm leading-6 text-muted-foreground">{description}</p>
+ </div>
+ </main>
+ );
+};
+
+export default PostMcpOauthScreen;
diff --git a/packages/trueforge-ui-sdk/src/containers/MessageImageContainer.tsx b/packages/trueforge-ui-sdk/src/containers/MessageImageContainer.tsx
new file mode 100644
index 000000000..4dfae436a
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/MessageImageContainer.tsx
@@ -0,0 +1,33 @@
+'use client';
+
+import { useAuiState } from '@assistant-ui/react';
+
+import { USER_MESSAGE_ATTACHMENT_PREVIEW_REM } from '../constants/attachments.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+
+export function MessageImageContainer() {
+ const AttachmentCard = useSlot('AttachmentCard');
+ const AttachmentPreviewDialog = useSlot('AttachmentPreviewDialog');
+ const image = useAuiState(s => (s.part.type === 'image' ? s.part.image : ''));
+ const filename = useAuiState(s => (s.part.type === 'image' ? s.part.filename : undefined));
+
+ if (!image) {
+ return null;
+ }
+
+ const card = (
+ <AttachmentCard
+ name={filename ?? 'image'}
+ previewSrc={image}
+ isImage
+ size="preview"
+ previewRem={USER_MESSAGE_ATTACHMENT_PREVIEW_REM}
+ />
+ );
+
+ return (
+ <AttachmentPreviewDialog previewSrc={image}>
+ <div className="aui-message-image">{card}</div>
+ </AttachmentPreviewDialog>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/ReasoningContainer.tsx b/packages/trueforge-ui-sdk/src/containers/ReasoningContainer.tsx
new file mode 100644
index 000000000..546edd2c1
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ReasoningContainer.tsx
@@ -0,0 +1,73 @@
+'use client';
+
+import { useAuiState } from '@assistant-ui/react';
+import { useCallback, useRef, useState } from 'react';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+import type { ThreadGroupPart } from './ToolGroupContainer.js';
+
+export function ReasoningContainer({ group }: { group: ThreadGroupPart }) {
+ const ReasoningCard = useSlot('ReasoningCard');
+
+ const content = useAuiState(s =>
+ group.indices
+ .map(i => s.message.parts[i])
+ .filter((p): p is NonNullable<typeof p> => p != null && p.type === 'reasoning')
+ .map(p => (p as { text?: string }).text ?? '')
+ .join(''),
+ );
+
+ const streaming = useAuiState(s => {
+ if (s.message.status?.type !== 'running') return false;
+ const lastIndex = s.message.parts.length - 1;
+ if (lastIndex < 0) return false;
+ if (s.message.parts[lastIndex]?.type !== 'reasoning') return false;
+ const lastGroupIndex = group.indices[group.indices.length - 1];
+ return lastGroupIndex !== undefined && lastIndex >= group.indices[0]! && lastIndex <= lastGroupIndex;
+ });
+
+ const [expanded, setExpanded] = useState(streaming);
+ const [prevStreaming, setPrevStreaming] = useState(streaming);
+ const [isMultiLine, setIsMultiLine] = useState(false);
+ const observerRef = useRef<ResizeObserver | null>(null);
+ if (streaming !== prevStreaming) {
+ setPrevStreaming(streaming);
+ if (streaming) setExpanded(true);
+ }
+
+ const contentRef = useCallback(
+ (node: HTMLDivElement | null) => {
+ observerRef.current?.disconnect();
+ observerRef.current = null;
+ if (node == null || streaming) return;
+
+ const check = () => {
+ const lineHeight = Number.parseFloat(getComputedStyle(node).lineHeight) || 24;
+ setIsMultiLine(node.scrollHeight > lineHeight * 1.5);
+ };
+
+ check();
+ observerRef.current = new ResizeObserver(check);
+ observerRef.current.observe(node);
+ },
+ [streaming],
+ );
+ const reasoningTimeText = null;
+ const previewText = content.replace(/\s+/g, ' ').trim();
+ const isShortText = !streaming && content.length > 0 && !isMultiLine;
+ const headingText = 'Reasoning';
+
+ return (
+ <ReasoningCard
+ content={content}
+ isStreaming={streaming}
+ expanded={expanded}
+ isMultiLine={isMultiLine}
+ reasoningTimeText={reasoningTimeText}
+ previewText={previewText}
+ headingText={headingText}
+ contentRef={isShortText ? contentRef : undefined}
+ onToggle={() => setExpanded(prev => !prev)}
+ />
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/RuntimeHarness.tsx b/packages/trueforge-ui-sdk/src/containers/RuntimeHarness.tsx
new file mode 100644
index 000000000..d182e3d8c
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/RuntimeHarness.tsx
@@ -0,0 +1,41 @@
+'use client';
+
+import {
+ AssistantRuntimeProvider,
+ useExternalStoreRuntime,
+ type AppendMessage,
+ type RespondToToolApprovalOptions,
+ type ThreadMessageLike,
+} from '@assistant-ui/react';
+import type { ReactNode } from 'react';
+
+/** Test-only harness driving a real assistant-ui runtime from plain message fixtures. */
+export function RuntimeHarness({
+ messages,
+ isRunning = false,
+ isLoading = false,
+ onRespondToToolApproval,
+ onEdit,
+ onNew = async () => {},
+ children,
+}: {
+ messages: ThreadMessageLike[];
+ isRunning?: boolean;
+ isLoading?: boolean;
+ onRespondToToolApproval?: (options: RespondToToolApprovalOptions) => void;
+ onEdit?: (message: AppendMessage) => Promise<void>;
+ onNew?: (message: AppendMessage) => Promise<void>;
+ children: ReactNode;
+}) {
+ const runtime = useExternalStoreRuntime<ThreadMessageLike>({
+ messages,
+ isRunning,
+ isLoading,
+ convertMessage: message => message,
+ onNew,
+ onEdit,
+ onRespondToToolApproval,
+ });
+
+ return <AssistantRuntimeProvider runtime={runtime}>{children}</AssistantRuntimeProvider>;
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/SandboxToolCallContainer.tsx b/packages/trueforge-ui-sdk/src/containers/SandboxToolCallContainer.tsx
new file mode 100644
index 000000000..f535c5a70
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SandboxToolCallContainer.tsx
@@ -0,0 +1,19 @@
+'use client';
+
+import { useMemo, useState } from 'react';
+
+import type { SandboxToolCallCardProps } from '../atoms/SandboxToolCallCard.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+
+export function SandboxToolCallContainer(
+ props: Omit<SandboxToolCallCardProps, 'viewMode' | 'hasContent' | 'onViewModeChange'>,
+) {
+ const SandboxToolCallCard = useSlot('SandboxToolCallCard');
+ const [viewMode, setViewMode] = useState<'terminal' | 'code'>('terminal');
+ const hasContent = useMemo(() => {
+ if (viewMode === 'code') return Boolean(props.argsJson || props.resultJson);
+ return Boolean(props.command || props.resultText || props.resultJson);
+ }, [props.argsJson, props.command, props.resultJson, props.resultText, viewMode]);
+
+ return <SandboxToolCallCard {...props} viewMode={viewMode} hasContent={hasContent} onViewModeChange={setViewMode} />;
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/AddMcpServerForm.tsx b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/AddMcpServerForm.tsx
new file mode 100644
index 000000000..95f9b4250
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/AddMcpServerForm.tsx
@@ -0,0 +1,227 @@
+'use client';
+
+import { useState, type FormEvent } from 'react';
+
+import { Button } from '../../atoms/primitives/Button.js';
+import { CenteredModal } from '../../atoms/primitives/CenteredModal.js';
+import { Icon } from '../../icons/Icon.js';
+import type { ConnectorAuth, ConnectorAuthType } from '../../server/types.js';
+
+export type McpAuthType = ConnectorAuthType;
+
+export type AddMcpServerDraft = {
+ name: string;
+ url: string;
+ auth: ConnectorAuth;
+};
+
+type AddMcpServerFormProps = {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ onAdd: (draft: AddMcpServerDraft) => void | Promise<void>;
+ busy?: boolean;
+};
+
+const AUTH_OPTIONS: Array<{ value: McpAuthType; label: string }> = [
+ { value: 'oauth', label: 'OAuth' },
+ { value: 'none', label: 'None' },
+ { value: 'apiKey', label: 'API Key' },
+];
+
+const inputClassName =
+ 'h-11 w-full rounded-md border border-input bg-background px-3 text-sm text-foreground shadow-sm outline-none placeholder:text-muted-foreground/70 focus-visible:ring-2 focus-visible:ring-ring/40';
+
+const RequiredMark = () => (
+ <span className="ml-0.5 text-destructive" aria-hidden>
+ *
+ </span>
+);
+
+const AddMcpServerForm = ({ open, onOpenChange, onAdd, busy = false }: AddMcpServerFormProps) => {
+ const [name, setName] = useState('');
+ const [url, setUrl] = useState('');
+ const [authType, setAuthType] = useState<McpAuthType>('oauth');
+ const [apiKey, setApiKey] = useState('');
+ const [headerName, setHeaderName] = useState('');
+
+ const resetForm = () => {
+ setName('');
+ setUrl('');
+ setAuthType('oauth');
+ setApiKey('');
+ setHeaderName('');
+ };
+
+ const handleOpenChange = (nextOpen: boolean) => {
+ if (!nextOpen) resetForm();
+ onOpenChange(nextOpen);
+ };
+
+ const isValid = !!name.trim() && !!url.trim() && (authType !== 'apiKey' || !!apiKey.trim());
+
+ const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+ event.preventDefault();
+ if (!isValid || busy) return;
+
+ const auth: ConnectorAuth =
+ authType === 'apiKey'
+ ? {
+ type: 'apiKey',
+ apiKey: apiKey.trim(),
+ ...(headerName.trim() ? { headerName: headerName.trim() } : {}),
+ }
+ : { type: authType };
+
+ try {
+ await onAdd({
+ name: name.trim(),
+ url: url.trim(),
+ auth,
+ });
+ resetForm();
+ onOpenChange(false);
+ } catch {
+ // Parent surfaces error; keep form open.
+ }
+ };
+
+ return (
+ <CenteredModal
+ open={open}
+ onOpenChange={handleOpenChange}
+ title="Add MCP server"
+ description="Point at a remote MCP endpoint. It then behaves like any other connector."
+ contentSized
+ headerIcon={
+ <span
+ className="flex size-11 shrink-0 items-center justify-center rounded-lg border border-border bg-muted text-foreground"
+ aria-hidden
+ >
+ <Icon name="mcp-server" className="size-6" />
+ </span>
+ }
+ >
+ <form className="flex flex-col overflow-y-auto p-5 md:p-6" onSubmit={e => void handleSubmit(e)}>
+ <div className="space-y-4">
+ <div>
+ <label htmlFor="mcp-server-name" className="mb-1.5 block text-sm font-medium text-foreground">
+ Name
+ <RequiredMark />
+ </label>
+ <input
+ id="mcp-server-name"
+ type="text"
+ required
+ value={name}
+ onChange={event => {
+ setName(event.target.value);
+ }}
+ placeholder="analytics-postgres-mcp"
+ autoFocus
+ className={inputClassName}
+ />
+ </div>
+
+ <div>
+ <label htmlFor="mcp-server-url" className="mb-1.5 block text-sm font-medium text-foreground">
+ URL
+ <RequiredMark />
+ </label>
+ <input
+ id="mcp-server-url"
+ type="url"
+ required
+ value={url}
+ onChange={event => {
+ setUrl(event.target.value);
+ }}
+ placeholder="https://mcp.example.com/mcp"
+ className={inputClassName}
+ />
+ </div>
+
+ <fieldset>
+ <legend className="mb-1.5 text-sm font-medium text-foreground">
+ Auth type
+ <RequiredMark />
+ </legend>
+ <div className="flex w-full flex-row rounded-md border border-border bg-muted/30 p-1">
+ {AUTH_OPTIONS.map(option => (
+ <label
+ key={option.value}
+ className={`flex h-8 flex-1 cursor-pointer items-center justify-center rounded-sm text-sm font-medium transition-colors ${
+ authType === option.value
+ ? 'bg-background text-foreground shadow-sm'
+ : 'text-muted-foreground hover:text-foreground'
+ }`}
+ >
+ <input
+ type="radio"
+ name="mcp-auth-type"
+ value={option.value}
+ checked={authType === option.value}
+ onChange={() => {
+ setAuthType(option.value);
+ }}
+ className="sr-only"
+ />
+ {option.label}
+ </label>
+ ))}
+ </div>
+ </fieldset>
+
+ {authType === 'oauth' ? (
+ <p className="text-sm leading-6 text-muted-foreground">
+ You&apos;ll be sent to the provider to authorise this server after adding it.
+ </p>
+ ) : null}
+
+ {authType === 'apiKey' ? (
+ <>
+ <div>
+ <label htmlFor="mcp-server-api-key" className="mb-1.5 block text-sm font-medium text-foreground">
+ API key
+ <RequiredMark />
+ </label>
+ <input
+ id="mcp-server-api-key"
+ type="password"
+ required
+ value={apiKey}
+ onChange={event => {
+ setApiKey(event.target.value);
+ }}
+ placeholder="Paste the server token"
+ className={inputClassName}
+ />
+ </div>
+
+ <div>
+ <label htmlFor="mcp-server-header-name" className="mb-1.5 block text-sm font-medium text-foreground">
+ Header name <span className="font-normal text-muted-foreground">(optional)</span>
+ </label>
+ <input
+ id="mcp-server-header-name"
+ type="text"
+ value={headerName}
+ onChange={event => {
+ setHeaderName(event.target.value);
+ }}
+ placeholder="Authorization"
+ className={inputClassName}
+ />
+ </div>
+ </>
+ ) : null}
+ </div>
+
+ <Button type="submit" size="lg" disabled={!isValid || busy} className="mt-6 w-full shrink-0">
+ Add
+ </Button>
+ </form>
+ </CenteredModal>
+ );
+};
+
+export default AddMcpServerForm;
diff --git a/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ConfigureSandboxForm.tsx b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ConfigureSandboxForm.tsx
new file mode 100644
index 000000000..7291dc282
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ConfigureSandboxForm.tsx
@@ -0,0 +1,258 @@
+'use client';
+
+import { useEffect, useState, type FormEvent } from 'react';
+
+import { Button } from '../../atoms/primitives/Button.js';
+import { CenteredModal } from '../../atoms/primitives/CenteredModal.js';
+import { Icon } from '../../icons/Icon.js';
+import type { SandboxConfig } from '../../server/types.js';
+
+export type SandboxConfigDraft = SandboxConfig & {
+ apiKey: string;
+};
+
+type ConfigureSandboxFormProps = {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ onSave: (draft: SandboxConfigDraft) => void | Promise<void>;
+ title: string;
+ description?: string;
+ /** Prefills config fields; apiKey is never autofilled. */
+ initialConfig?: SandboxConfig | null;
+ /** When false (updates), empty apiKey means keep the existing key. */
+ requireApiKey?: boolean;
+ busy?: boolean;
+};
+
+const EMPTY_CONFIG: SandboxConfig = {
+ snapshotName: '',
+ execTimeoutMs: 0,
+ autoStopIntervalInMinutes: 0,
+ autoArchiveIntervalInMinutes: 0,
+ autoDeleteIntervalInMinutes: 0,
+};
+
+const inputClassName =
+ 'h-11 w-full rounded-md border border-input bg-background px-3 text-sm text-foreground shadow-sm outline-none placeholder:text-muted-foreground/70 focus-visible:ring-2 focus-visible:ring-ring/40';
+
+function parseNonNegInt(raw: string): number | null {
+ if (raw.trim() === '') return null;
+ const n = Number(raw);
+ if (!Number.isFinite(n) || n < 0) return null;
+ return n;
+}
+
+const ConfigureSandboxForm = ({
+ open,
+ onOpenChange,
+ onSave,
+ title,
+ description,
+ initialConfig = null,
+ requireApiKey = true,
+ busy = false,
+}: ConfigureSandboxFormProps) => {
+ const [snapshotName, setSnapshotName] = useState('');
+ const [execTimeoutMs, setExecTimeoutMs] = useState('');
+ const [autoStopIntervalInMinutes, setAutoStopIntervalInMinutes] = useState('');
+ const [autoArchiveIntervalInMinutes, setAutoArchiveIntervalInMinutes] = useState('');
+ const [autoDeleteIntervalInMinutes, setAutoDeleteIntervalInMinutes] = useState('');
+ const [apiKey, setApiKey] = useState('');
+
+ const resetForm = () => {
+ setSnapshotName('');
+ setExecTimeoutMs('');
+ setAutoStopIntervalInMinutes('');
+ setAutoArchiveIntervalInMinutes('');
+ setAutoDeleteIntervalInMinutes('');
+ setApiKey('');
+ };
+
+ useEffect(() => {
+ if (!open) return;
+ const config = initialConfig ?? EMPTY_CONFIG;
+ setSnapshotName(config.snapshotName);
+ setExecTimeoutMs(String(config.execTimeoutMs));
+ setAutoStopIntervalInMinutes(String(config.autoStopIntervalInMinutes));
+ setAutoArchiveIntervalInMinutes(String(config.autoArchiveIntervalInMinutes));
+ setAutoDeleteIntervalInMinutes(String(config.autoDeleteIntervalInMinutes));
+ setApiKey('');
+ }, [open, initialConfig]);
+
+ const handleOpenChange = (nextOpen: boolean) => {
+ if (!nextOpen) resetForm();
+ onOpenChange(nextOpen);
+ };
+
+ const execTimeout = parseNonNegInt(execTimeoutMs);
+ const autoStop = parseNonNegInt(autoStopIntervalInMinutes);
+ const autoArchive = parseNonNegInt(autoArchiveIntervalInMinutes);
+ const autoDelete = parseNonNegInt(autoDeleteIntervalInMinutes);
+ const trimmedKey = apiKey.trim();
+
+ const isValid =
+ !!snapshotName.trim() &&
+ (!requireApiKey || !!trimmedKey) &&
+ execTimeout != null &&
+ autoStop != null &&
+ autoArchive != null &&
+ autoDelete != null;
+
+ const handleSubmit = async (event: FormEvent<HTMLFormElement>) => {
+ event.preventDefault();
+ if (!isValid || busy || execTimeout == null || autoStop == null || autoArchive == null || autoDelete == null) {
+ return;
+ }
+
+ try {
+ await onSave({
+ snapshotName: snapshotName.trim(),
+ execTimeoutMs: execTimeout,
+ autoStopIntervalInMinutes: autoStop,
+ autoArchiveIntervalInMinutes: autoArchive,
+ autoDeleteIntervalInMinutes: autoDelete,
+ apiKey: trimmedKey,
+ });
+ resetForm();
+ onOpenChange(false);
+ } catch {
+ // Parent surfaces error; keep form open.
+ }
+ };
+
+ return (
+ <CenteredModal
+ open={open}
+ onOpenChange={handleOpenChange}
+ title={title}
+ description={description}
+ contentSized
+ headerIcon={
+ <span
+ className="flex size-11 shrink-0 items-center justify-center rounded-lg border border-border bg-muted text-foreground"
+ aria-hidden
+ >
+ <Icon name="cube" className="size-6" />
+ </span>
+ }
+ >
+ <form className="flex flex-col overflow-y-auto p-5 md:p-6" onSubmit={handleSubmit}>
+ <div className="space-y-4">
+ <div>
+ <label htmlFor="sandbox-snapshot-name" className="mb-1.5 block text-sm font-medium text-foreground">
+ Snapshot name
+ </label>
+ <input
+ id="sandbox-snapshot-name"
+ type="text"
+ required
+ value={snapshotName}
+ onChange={event => {
+ setSnapshotName(event.target.value);
+ }}
+ placeholder="daytona-default"
+ autoFocus
+ className={inputClassName}
+ />
+ </div>
+
+ <div>
+ <label htmlFor="sandbox-exec-timeout" className="mb-1.5 block text-sm font-medium text-foreground">
+ Exec timeout (ms)
+ </label>
+ <input
+ id="sandbox-exec-timeout"
+ type="number"
+ min={0}
+ required
+ value={execTimeoutMs}
+ onChange={event => {
+ setExecTimeoutMs(event.target.value);
+ }}
+ placeholder="300000"
+ className={inputClassName}
+ />
+ </div>
+
+ <div>
+ <label htmlFor="sandbox-auto-stop" className="mb-1.5 block text-sm font-medium text-foreground">
+ Auto-stop interval (minutes)
+ </label>
+ <input
+ id="sandbox-auto-stop"
+ type="number"
+ min={0}
+ required
+ value={autoStopIntervalInMinutes}
+ onChange={event => {
+ setAutoStopIntervalInMinutes(event.target.value);
+ }}
+ placeholder="15"
+ className={inputClassName}
+ />
+ </div>
+
+ <div>
+ <label htmlFor="sandbox-auto-archive" className="mb-1.5 block text-sm font-medium text-foreground">
+ Auto-archive interval (minutes)
+ </label>
+ <input
+ id="sandbox-auto-archive"
+ type="number"
+ min={0}
+ required
+ value={autoArchiveIntervalInMinutes}
+ onChange={event => {
+ setAutoArchiveIntervalInMinutes(event.target.value);
+ }}
+ placeholder="10080"
+ className={inputClassName}
+ />
+ </div>
+
+ <div>
+ <label htmlFor="sandbox-auto-delete" className="mb-1.5 block text-sm font-medium text-foreground">
+ Auto-delete interval (minutes)
+ </label>
+ <input
+ id="sandbox-auto-delete"
+ type="number"
+ min={0}
+ required
+ value={autoDeleteIntervalInMinutes}
+ onChange={event => {
+ setAutoDeleteIntervalInMinutes(event.target.value);
+ }}
+ placeholder="43200"
+ className={inputClassName}
+ />
+ </div>
+
+ <div>
+ <label htmlFor="sandbox-api-key" className="mb-1.5 block text-sm font-medium text-foreground">
+ API key
+ {!requireApiKey ? <span className="font-normal text-muted-foreground"> (optional)</span> : null}
+ </label>
+ <input
+ id="sandbox-api-key"
+ type="password"
+ required={requireApiKey}
+ value={apiKey}
+ onChange={event => {
+ setApiKey(event.target.value);
+ }}
+ placeholder={requireApiKey ? 'dtn_...' : 'Leave blank to keep existing'}
+ className={inputClassName}
+ />
+ </div>
+ </div>
+
+ <Button type="submit" size="lg" disabled={!isValid || busy} className="mt-6 w-full shrink-0">
+ Save
+ </Button>
+ </form>
+ </CenteredModal>
+ );
+};
+
+export default ConfigureSandboxForm;
diff --git a/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ConnectorDetails.tsx b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ConnectorDetails.tsx
new file mode 100644
index 000000000..5401bc66c
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ConnectorDetails.tsx
@@ -0,0 +1,127 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { Button } from '../../atoms/primitives/Button.js';
+import { Icon } from '../../icons/Icon.js';
+import { useCatalogServer } from '../../server/ServerContext.js';
+import type { ConnectorBase, ToolBase } from '../../server/types.js';
+
+type ConnectorDetailsProps = {
+ connector: ConnectorBase;
+ onBack: () => void;
+ onDisconnect: () => void;
+ busy?: boolean;
+};
+
+const ConnectorDetails = ({ connector, onBack, onDisconnect, busy = false }: ConnectorDetailsProps) => {
+ const { connectorCatalog } = useCatalogServer();
+ const [tools, setTools] = useState<ToolBase[]>([]);
+ const [toolsLoading, setToolsLoading] = useState(true);
+ const [toolsError, setToolsError] = useState<string | null>(null);
+
+ useEffect(() => {
+ let cancelled = false;
+ setTools([]);
+ setToolsError(null);
+ setToolsLoading(true);
+
+ void connectorCatalog
+ .getToolsByConnectorId({ id: connector.id })
+ .then(result => {
+ if (!cancelled) setTools(result);
+ })
+ .catch((err: unknown) => {
+ if (!cancelled) {
+ setToolsError(err instanceof Error ? err.message : 'Failed to load connector tools');
+ }
+ })
+ .finally(() => {
+ if (!cancelled) setToolsLoading(false);
+ });
+
+ return () => {
+ cancelled = true;
+ };
+ }, [connector.id, connectorCatalog]);
+
+ return (
+ <div className="flex h-full flex-col overflow-hidden">
+ <button
+ type="button"
+ onClick={onBack}
+ className="mb-3 inline-flex w-fit items-center gap-1 rounded-md py-1 pr-2 text-sm text-muted-foreground hover:text-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+ >
+ <Icon name="chevron-left" className="size-3.5" />
+ Connectors
+ </button>
+
+ <div className="flex flex-1 flex-col overflow-y-auto pb-1">
+ <header className="flex items-start gap-3">
+ <span
+ className="flex size-10 shrink-0 items-center justify-center overflow-hidden rounded-lg border border-border bg-muted"
+ aria-hidden
+ >
+ <Icon name="mcp-server" className="size-5 text-foreground" />
+ </span>
+
+ <div className="min-w-0 flex-1">
+ <h4 className="text-lg font-semibold text-foreground">{connector.name}</h4>
+ <div className="mt-0.5 flex flex-wrap items-center gap-x-2 gap-y-1 text-sm">
+ <span className="flex items-center gap-1.5 text-xs font-medium text-foreground">
+ <span className="h-1.5 w-1.5 rounded-full bg-primary"></span>
+ {connector.authenticated ? 'Connected' : 'Not authenticated'}
+ </span>
+ <span className="text-muted-foreground">· {connector.description}</span>
+ </div>
+ <p className="mt-1 break-all font-mono text-xs text-muted-foreground">{connector.url}</p>
+ <p className="mt-1 text-xs text-muted-foreground">Auth · {connector.auth.type}</p>
+ </div>
+
+ {connector.requiresAuth ? null : (
+ <Button variant="outline" size="sm" type="button" disabled={busy} onClick={onDisconnect}>
+ Disconnect
+ </Button>
+ )}
+ </header>
+
+ <section className="mt-6" aria-labelledby="connector-tools-heading">
+ {toolsLoading ? (
+ <div className="rounded-xl border border-dashed border-border p-6 text-center text-sm text-muted-foreground">
+ Loading tools…
+ </div>
+ ) : toolsError ? (
+ <div className="rounded-xl border border-destructive/30 bg-destructive/10 p-6 text-center text-sm text-destructive">
+ {toolsError}
+ </div>
+ ) : tools.length > 0 ? (
+ <>
+ <h5 id="connector-tools-heading" className="mb-2 text-[0.8125rem] font-semibold text-foreground">
+ Tools <span className="font-normal text-muted-foreground">· {tools.length}</span>
+ </h5>
+ <div className="overflow-hidden rounded-xl border border-border bg-card">
+ {tools.map(tool => (
+ <article
+ key={tool.id}
+ className="flex min-h-12 items-start gap-3 border-b border-border px-3 py-2 last:border-b-0"
+ >
+ <div className="min-w-0 flex-1">
+ <h6 className="text-sm font-medium text-foreground">{tool.name}</h6>
+ <p className="mt-0.5 font-mono text-xs text-muted-foreground">{tool.id}</p>
+ </div>
+ </article>
+ ))}
+ </div>
+ </>
+ ) : (
+ <div className="rounded-xl border border-dashed border-border p-6 text-center text-sm text-muted-foreground">
+ No tools reported for this connector.
+ </div>
+ )}
+ </section>
+ </div>
+ </div>
+ );
+};
+
+export default ConnectorDetails;
diff --git a/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ConnectorSettings.tsx b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ConnectorSettings.tsx
new file mode 100644
index 000000000..e88cd5ed3
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ConnectorSettings.tsx
@@ -0,0 +1,457 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useState, type FormEvent } from 'react';
+
+import { Icon } from '@/icons/Icon.js';
+import { Button } from '../../atoms/primitives/Button.js';
+import { CenteredModal } from '../../atoms/primitives/CenteredModal.js';
+import SearchInput from '../../atoms/primitives/SearchInput.js';
+import { useMCPAuth } from '../../hooks/useMcpAuth.js';
+import { useCatalogServer } from '../../server/ServerContext.js';
+import type { ConnectorAuth, ConnectorBase, ConnectorCatalogEntry } from '../../server/types.js';
+import AddMcpServerForm, { type AddMcpServerDraft } from './AddMcpServerForm.js';
+import ConnectorDetails from './ConnectorDetails.js';
+
+const AUTH_TYPE_LABELS: Record<string, string> = {
+ oauth: 'OAuth2',
+ apiKey: 'API Key',
+ none: 'No Auth',
+};
+
+const ConnectorSettings = () => {
+ const { connectorCatalog } = useCatalogServer();
+ const { handleAuthorize, isOAuthLoading } = useMCPAuth();
+
+ const [query, setQuery] = useState('');
+ const [addedMcpServers, setAddedMcpServers] = useState<ConnectorBase[]>([]);
+ const [connected, setConnected] = useState<ConnectorBase[]>([]);
+ const [catalog, setCatalog] = useState<ConnectorCatalogEntry[]>([]);
+ const [loading, setLoading] = useState(true);
+ const [error, setError] = useState<string | null>(null);
+ const [busy, setBusy] = useState(false);
+
+ const [addMcpServerFormOpen, setAddMcpServerFormOpen] = useState(false);
+ const [connectorAwaitingKey, setConnectorAwaitingKey] = useState<ConnectorCatalogEntry | null>(null);
+ const [selectedConnector, setSelectedConnector] = useState<ConnectorBase | null>(null);
+ const [apiKey, setApiKey] = useState('');
+
+ const refresh = useCallback(async () => {
+ setLoading(true);
+ setError(null);
+ try {
+ const [listed, available] = await Promise.all([
+ connectorCatalog.listConnectors(),
+ connectorCatalog.getConnectorCatalog(),
+ ]);
+ setAddedMcpServers(listed ?? []);
+ setConnected((listed ?? []).filter(connector => connector.authenticated || !connector.requiresAuth));
+ setCatalog(available);
+ setSelectedConnector(current => (current ? (listed.find(item => item.id === current.id) ?? null) : null));
+ } catch (err) {
+ setError(err instanceof Error ? err.message : 'Failed to load connectors');
+ } finally {
+ setLoading(false);
+ }
+ }, [connectorCatalog]);
+
+ useEffect(() => {
+ void refresh();
+ }, [refresh]);
+
+ const normalizedQuery = query.trim().toLowerCase();
+
+ const matchingConnected = useMemo(() => {
+ if (!normalizedQuery) return connected;
+ return connected.filter(
+ connector =>
+ connector.name.toLowerCase().includes(normalizedQuery) ||
+ connector.description.toLowerCase().includes(normalizedQuery) ||
+ connector.url.toLowerCase().includes(normalizedQuery),
+ );
+ }, [connected, normalizedQuery]);
+
+ const availableConnectors = useMemo(() => {
+ const eligibleAddedServers = addedMcpServers.filter(
+ connector => !connector.authenticated && connector.requiresAuth,
+ );
+ const addedServerNames = new Set(eligibleAddedServers.map(connector => connector.name));
+ const seenNames = new Set<string>();
+ const uniqueConnectors = [
+ ...catalog.filter(entry => {
+ const alreadyConnected = connected.some(connector => connector.id === entry.id || connector.url === entry.url);
+ if (alreadyConnected || addedServerNames.has(entry.name) || seenNames.has(entry.name)) {
+ return false;
+ }
+ seenNames.add(entry.name);
+ return true;
+ }),
+ ...eligibleAddedServers.filter(connector => {
+ if (seenNames.has(connector.name)) return false;
+ seenNames.add(connector.name);
+ return true;
+ }),
+ ];
+
+ if (!normalizedQuery) return uniqueConnectors;
+ return uniqueConnectors.filter(
+ connector =>
+ connector.name.toLowerCase().includes(normalizedQuery) ||
+ (connector.description?.toLowerCase().includes(normalizedQuery) ?? false) ||
+ connector.url.toLowerCase().includes(normalizedQuery),
+ );
+ }, [catalog, connected, addedMcpServers, normalizedQuery]);
+
+ const runMutation = async (fn: () => Promise<void>) => {
+ setBusy(true);
+ setError(null);
+ try {
+ await fn();
+ await refresh();
+ } catch (err) {
+ setError(err instanceof Error ? err.message : 'Request failed');
+ throw err;
+ } finally {
+ setBusy(false);
+ }
+ };
+
+ const closeApiKeyModal = () => {
+ setConnectorAwaitingKey(null);
+ setApiKey('');
+ };
+
+ const authorizeOAuthConnector = async (integrationId: string) => {
+ await handleAuthorize(integrationId, isSuccess => {
+ if (isSuccess) void refresh();
+ });
+ };
+
+ const createFromCatalog = async (entry: ConnectorCatalogEntry, authOverride?: ConnectorAuth) => {
+ const auth: ConnectorAuth =
+ authOverride ??
+ (entry.auth.type === 'apiKey'
+ ? {
+ type: 'apiKey',
+ ...(entry.auth.headerName ? { headerName: entry.auth.headerName } : {}),
+ }
+ : entry.auth.type === 'oauth'
+ ? { type: 'oauth' }
+ : { type: 'none' });
+ const created = await connectorCatalog.createConnector({
+ name: entry.name,
+ url: entry.url,
+ auth,
+ });
+ if (auth.type === 'oauth') {
+ await authorizeOAuthConnector(created.id);
+ }
+ };
+
+ const handleConnect = (entry: ConnectorCatalogEntry) => {
+ if (entry.auth.type === 'apiKey') {
+ setApiKey('');
+ setConnectorAwaitingKey(entry);
+ return;
+ }
+
+ void runMutation(async () => {
+ const existingConnector = addedMcpServers.find(connector => connector.id === entry.id);
+ if (existingConnector) {
+ await authorizeOAuthConnector(existingConnector.id);
+ } else {
+ await createFromCatalog(entry);
+ }
+ }).catch(() => {});
+ };
+
+ const handleApiKeySubmit = (event: FormEvent<HTMLFormElement>) => {
+ event.preventDefault();
+ if (!connectorAwaitingKey || !apiKey.trim()) return;
+
+ const entry = connectorAwaitingKey;
+ void runMutation(async () => {
+ const auth: ConnectorAuth = {
+ type: 'apiKey',
+ apiKey: apiKey.trim(),
+ ...(entry.auth.type === 'apiKey' && entry.auth.headerName ? { headerName: entry.auth.headerName } : {}),
+ };
+ const existingConnector = addedMcpServers.find(connector => connector.id === entry.id);
+ if (existingConnector) {
+ await connectorCatalog.updateConnector({
+ id: existingConnector.id,
+ name: existingConnector.name,
+ url: existingConnector.url,
+ auth,
+ });
+ } else {
+ await createFromCatalog(entry, auth);
+ }
+ closeApiKeyModal();
+ }).catch(() => {});
+ };
+
+ const handleAddMcpServer = async (draft: AddMcpServerDraft) => {
+ await runMutation(async () => {
+ const created = await connectorCatalog.createConnector({
+ name: draft.name,
+ url: draft.url,
+ auth: draft.auth,
+ });
+ if (draft.auth.type === 'oauth') {
+ await authorizeOAuthConnector(created.id);
+ }
+ });
+ };
+
+ const handleDisconnect = (connector: ConnectorBase) => {
+ void runMutation(async () => {
+ await connectorCatalog.disconnectConnector({ id: connector.id });
+ setSelectedConnector(null);
+ }).catch(() => {});
+ };
+
+ const renderConnector = (connector: ConnectorBase, isConnected: boolean) => {
+ const content = (
+ <>
+ <span
+ className="flex size-9 shrink-0 items-center justify-center overflow-hidden rounded-lg border border-border bg-muted"
+ aria-hidden
+ >
+ <Icon name="mcp-server" className="size-4.5 text-foreground" />
+ </span>
+
+ <div className="min-w-0 flex-1">
+ <h5 className="truncate text-sm font-medium text-foreground">{connector.name}</h5>
+ <p className="mt-0.5 line-clamp-2 text-sm text-muted-foreground sm:truncate">{connector.description}</p>
+ </div>
+
+ {isConnected ? (
+ <div className="flex items-center gap-2">
+ <span className="flex items-center gap-1.5 rounded-full border border-border bg-muted/40 px-2 py-0.5 text-xs font-medium text-foreground">
+ <span className="h-1.5 w-1.5 rounded-full bg-primary"></span>
+ {connector.authenticated ? 'Connected' : 'Added'}
+ </span>
+ <Icon name="chevron-right" className="size-4" />
+ </div>
+ ) : null}
+ </>
+ );
+
+ const rowClassName = 'flex min-h-16 w-full items-center gap-3 border-b border-border p-3 text-left last:border-b-0';
+
+ if (isConnected) {
+ return (
+ <button
+ key={connector.id}
+ type="button"
+ aria-label={`View ${connector.name} connector`}
+ className={`${rowClassName} cursor-pointer transition-colors hover:bg-accent/40 focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-inset focus-visible:ring-ring`}
+ onClick={() => {
+ setSelectedConnector(connector);
+ }}
+ >
+ {content}
+ </button>
+ );
+ }
+
+ return (
+ <article key={connector.id} className={rowClassName}>
+ {content}
+ </article>
+ );
+ };
+
+ const renderCatalogEntry = (entry: ConnectorCatalogEntry) => (
+ <article
+ key={entry.id}
+ className="flex min-h-16 w-full items-center gap-3 border-b border-border p-3 text-left last:border-b-0"
+ >
+ <span
+ className="flex size-9 shrink-0 items-center justify-center overflow-hidden rounded-lg border border-border bg-muted"
+ aria-hidden
+ >
+ <Icon name="mcp-server" className="size-4.5 text-foreground" />
+ </span>
+
+ <div className="min-w-0 flex-1">
+ <h5 className="truncate text-sm font-medium text-foreground">{entry.name}</h5>
+ <p className="mt-0.5 line-clamp-2 text-sm text-muted-foreground sm:truncate">
+ {entry.description ?? entry.url}
+ </p>
+ </div>
+
+ <div className="flex shrink-0 items-center gap-2">
+ <span className="hidden text-xs text-muted-foreground sm:inline">
+ {AUTH_TYPE_LABELS[entry.auth.type] ?? AUTH_TYPE_LABELS.none}
+ </span>
+ <Button
+ variant="secondary"
+ size="sm"
+ type="button"
+ disabled={busy || isOAuthLoading}
+ onClick={() => {
+ handleConnect(entry);
+ }}
+ >
+ Connect
+ </Button>
+ </div>
+ </article>
+ );
+
+ if (selectedConnector) {
+ return (
+ <ConnectorDetails
+ connector={selectedConnector}
+ busy={busy}
+ onBack={() => {
+ setSelectedConnector(null);
+ }}
+ onDisconnect={() => {
+ handleDisconnect(selectedConnector);
+ }}
+ />
+ );
+ }
+
+ const hasMatches = matchingConnected.length > 0 || availableConnectors.length > 0;
+
+ return (
+ <>
+ <h3 className="text-xl font-semibold tracking-tight text-foreground">Connectors</h3>
+ <p className="mt-1 text-sm text-muted-foreground">Enable the tools agents may call.</p>
+
+ {error ? (
+ <p className="mt-3 rounded-md border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive">
+ {error}
+ </p>
+ ) : null}
+
+ <div className="mt-4 flex-1 overflow-y-hidden">
+ <div className="flex h-full flex-col gap-3">
+ <div className="flex gap-2">
+ <div className="flex-1">
+ <SearchInput query={query} setQuery={setQuery} placeholder="Search connectors" />
+ </div>
+ <Button
+ variant="secondary"
+ type="button"
+ onClick={() => {
+ setAddMcpServerFormOpen(true);
+ }}
+ >
+ <Icon name="plus" size="1rem" className="mr-1" />
+ Add MCP Server
+ </Button>
+ </div>
+
+ <div className="flex flex-1 flex-col gap-5 overflow-y-auto pb-1">
+ {loading ? <p className="py-8 text-center text-sm text-muted-foreground">Loading…</p> : null}
+
+ {!loading && matchingConnected.length > 0 ? (
+ <section aria-labelledby="connected-connectors-heading">
+ <h4
+ id="connected-connectors-heading"
+ className="mb-2 text-[0.8125rem] font-semibold uppercase text-muted-foreground"
+ >
+ Connected · {matchingConnected.length}
+ </h4>
+ <div className="overflow-hidden rounded-xl border border-border bg-card">
+ {matchingConnected.map(connector => renderConnector(connector, true))}
+ </div>
+ </section>
+ ) : null}
+
+ {!loading && availableConnectors.length > 0 ? (
+ <section aria-labelledby="available-connectors-heading">
+ <h4
+ id="available-connectors-heading"
+ className="mb-2 text-[0.8125rem] font-semibold uppercase text-muted-foreground"
+ >
+ Available · {availableConnectors.length}
+ </h4>
+ <div className="overflow-hidden rounded-xl border border-border bg-card">
+ {availableConnectors.map(entry => renderCatalogEntry(entry))}
+ </div>
+ </section>
+ ) : null}
+
+ {!loading && !hasMatches ? (
+ <div className="flex flex-1 items-center justify-center rounded-xl border border-dashed border-border p-8 text-center text-sm text-muted-foreground">
+ {query.trim() ? `No connectors match “${query.trim()}”.` : 'No connectors yet.'}
+ </div>
+ ) : null}
+ </div>
+
+ <CenteredModal
+ open={connectorAwaitingKey !== null}
+ onOpenChange={open => {
+ if (!open) closeApiKeyModal();
+ }}
+ title={`Connect ${connectorAwaitingKey?.name ?? 'connector'}`}
+ description={connectorAwaitingKey?.url}
+ contentSized
+ className="md:max-w-xl"
+ >
+ <form onSubmit={handleApiKeySubmit}>
+ <div className="space-y-5 px-5 py-5">
+ <div className="flex items-center gap-3">
+ <span
+ className="flex size-12 shrink-0 items-center justify-center overflow-hidden rounded-xl border border-border bg-muted"
+ aria-hidden
+ >
+ <Icon name="mcp-server" className="size-6 text-foreground" />
+ </span>
+ <div className="min-w-0">
+ <p className="font-medium text-foreground">{connectorAwaitingKey?.name}</p>
+ <p className="truncate text-sm text-muted-foreground">{connectorAwaitingKey?.description}</p>
+ </div>
+ </div>
+
+ <div>
+ <label
+ htmlFor="connector-api-key"
+ className="mb-2 block text-xs font-semibold uppercase tracking-wide text-muted-foreground"
+ >
+ API key / token
+ </label>
+ <input
+ id="connector-api-key"
+ type="password"
+ value={apiKey}
+ onChange={event => {
+ setApiKey(event.target.value);
+ }}
+ placeholder={`Paste the token from ${connectorAwaitingKey?.name ?? 'the provider'}`}
+ autoFocus
+ required
+ className="h-11 w-full rounded-md border border-input bg-background px-3 text-sm text-foreground outline-none placeholder:text-muted-foreground/70 focus-visible:ring-2 focus-visible:ring-ring/40"
+ />
+ </div>
+ </div>
+
+ <footer className="flex justify-end gap-2 border-t border-border px-5 py-4">
+ <Button variant="ghost" type="button" onClick={closeApiKeyModal} disabled={busy || isOAuthLoading}>
+ Cancel
+ </Button>
+ <Button type="submit" disabled={!apiKey.trim() || busy || isOAuthLoading}>
+ Connect
+ </Button>
+ </footer>
+ </form>
+ </CenteredModal>
+
+ <AddMcpServerForm
+ open={addMcpServerFormOpen}
+ onOpenChange={setAddMcpServerFormOpen}
+ onAdd={handleAddMcpServer}
+ busy={busy || isOAuthLoading}
+ />
+ </div>
+ </div>
+ </>
+ );
+};
+
+export default ConnectorSettings;
diff --git a/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/CustomModelProviderForm.tsx b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/CustomModelProviderForm.tsx
new file mode 100644
index 000000000..1907794a8
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/CustomModelProviderForm.tsx
@@ -0,0 +1,217 @@
+'use client';
+
+import { useState } from 'react';
+
+import { Button } from '../../atoms/primitives/Button.js';
+import { CenteredModal } from '../../atoms/primitives/CenteredModal.js';
+import { Icon } from '../../icons/Icon.js';
+import type { ModelEntry } from '../../server/types.js';
+
+export type CustomProviderDraft = {
+ name: string;
+ baseUrl: string;
+ apiKey: string;
+ models: ModelEntry[];
+};
+
+type CustomModelProviderFormProps = {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ onAdd: (draft: CustomProviderDraft) => void | Promise<void>;
+ busy?: boolean;
+};
+
+type ModelRow = { id: string; name: string };
+
+const EMPTY_MODEL_ROW: ModelRow = { id: '', name: '' };
+
+const inputClassName =
+ 'h-10 w-full rounded-md border border-input bg-background px-3 text-sm text-foreground outline-none placeholder:text-muted-foreground focus-visible:ring-2 focus-visible:ring-ring/40';
+
+const RequiredMark = () => (
+ <span className="ml-0.5 text-destructive" aria-hidden>
+ *
+ </span>
+);
+
+const CustomModelProviderForm = ({ open, onOpenChange, onAdd, busy = false }: CustomModelProviderFormProps) => {
+ const [name, setName] = useState('');
+ const [baseUrl, setBaseUrl] = useState('');
+ const [apiKey, setApiKey] = useState('');
+ const [models, setModels] = useState<ModelRow[]>([EMPTY_MODEL_ROW]);
+
+ const resetForm = () => {
+ setName('');
+ setBaseUrl('');
+ setApiKey('');
+ setModels([EMPTY_MODEL_ROW]);
+ };
+
+ const handleOpenChange = (nextOpen: boolean) => {
+ if (!nextOpen) resetForm();
+ onOpenChange(nextOpen);
+ };
+
+ const isValid =
+ !!name.trim() && !!baseUrl.trim() && !!apiKey.trim() && models.every(model => model.id.trim() && model.name.trim());
+
+ const updateModel = (index: number, patch: Partial<ModelRow>) => {
+ setModels(current => current.map((model, i) => (i === index ? { ...model, ...patch } : model)));
+ };
+
+ const handleSubmit = async () => {
+ if (!isValid || busy) return;
+ try {
+ await onAdd({
+ name: name.trim(),
+ baseUrl: baseUrl.trim(),
+ apiKey: apiKey.trim(),
+ models: models.map(model => ({
+ id: model.id.trim(),
+ name: model.name.trim(),
+ })),
+ });
+ resetForm();
+ onOpenChange(false);
+ } catch {
+ // Parent surfaces error; keep form open.
+ }
+ };
+
+ return (
+ <CenteredModal
+ open={open}
+ onOpenChange={handleOpenChange}
+ title="Add custom provider"
+ description="Any OpenAI-compatible endpoint. Each one stays its own provider."
+ contentSized
+ >
+ <form
+ className="flex min-h-0 flex-1 flex-col gap-4 p-5"
+ onSubmit={event => {
+ event.preventDefault();
+ void handleSubmit();
+ }}
+ >
+ <div>
+ <label htmlFor="custom-provider-name" className="mb-1.5 block text-sm font-medium text-foreground">
+ Name
+ <RequiredMark />
+ </label>
+ <input
+ id="custom-provider-name"
+ type="text"
+ required
+ value={name}
+ onChange={event => {
+ setName(event.target.value);
+ }}
+ placeholder="Local Llama"
+ autoFocus
+ className={inputClassName}
+ />
+ </div>
+
+ <div>
+ <label htmlFor="custom-provider-base-url" className="mb-1.5 block text-sm font-medium text-foreground">
+ Base URL
+ <RequiredMark />
+ </label>
+ <input
+ id="custom-provider-base-url"
+ type="text"
+ required
+ value={baseUrl}
+ onChange={event => {
+ setBaseUrl(event.target.value);
+ }}
+ placeholder="http://localhost:11434/v1"
+ className={inputClassName}
+ />
+ </div>
+
+ <div>
+ <label htmlFor="custom-provider-api-key" className="mb-1.5 block text-sm font-medium text-foreground">
+ API key
+ <RequiredMark />
+ </label>
+ <input
+ id="custom-provider-api-key"
+ type="password"
+ required
+ value={apiKey}
+ onChange={event => {
+ setApiKey(event.target.value);
+ }}
+ placeholder="sk-..."
+ className={inputClassName}
+ />
+ </div>
+
+ <fieldset>
+ <legend className="mb-1.5 block text-sm font-medium text-foreground">
+ Models
+ <RequiredMark />
+ </legend>
+ <div className="flex flex-col gap-2">
+ {models.map((model, index) => (
+ <div key={index} className="flex items-center gap-2">
+ <input
+ type="text"
+ required
+ aria-label={`Model ${index + 1} ID`}
+ value={model.id}
+ onChange={event => {
+ updateModel(index, { id: event.target.value });
+ }}
+ placeholder="llama3.1:70b"
+ className={`${inputClassName} font-mono`}
+ />
+ <input
+ type="text"
+ required
+ aria-label={`Model ${index + 1} display name`}
+ value={model.name}
+ onChange={event => {
+ updateModel(index, { name: event.target.value });
+ }}
+ placeholder="Llama 3.1 70B"
+ className={inputClassName}
+ />
+ <Button
+ variant="outline"
+ size="icon"
+ type="button"
+ aria-label={`Remove model ${index + 1}`}
+ disabled={models.length === 1 || busy}
+ className="size-10 shrink-0"
+ onClick={() => {
+ setModels(current => current.filter((_, i) => i !== index));
+ }}
+ >
+ <Icon name="trash" className="size-3.5" />
+ </Button>
+ </div>
+ ))}
+ </div>
+ <button
+ type="button"
+ className="mt-2 inline-flex shrink-0 cursor-pointer items-center gap-1 rounded-sm text-sm font-medium text-primary hover:underline focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+ onClick={() => {
+ setModels(current => [...current, EMPTY_MODEL_ROW]);
+ }}
+ >
+ <Icon name="plus" className="size-3.5" />
+ Add model
+ </button>
+ </fieldset>
+
+ <Button type="submit" size="lg" disabled={!isValid || busy} className="w-full shrink-0">
+ Add provider
+ </Button>
+ </form>
+ </CenteredModal>
+ );
+};
+
+export default CustomModelProviderForm;
diff --git a/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ImportGithubSkillForm.test.tsx b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ImportGithubSkillForm.test.tsx
new file mode 100644
index 000000000..d4b819f39
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ImportGithubSkillForm.test.tsx
@@ -0,0 +1,46 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { beforeAll, describe, expect, it, vi } from 'vitest';
+
+import ImportGithubSkillForm from './ImportGithubSkillForm.js';
+
+beforeAll(() => {
+ HTMLDialogElement.prototype.showModal = function showModal() {
+ this.setAttribute('open', '');
+ };
+});
+
+describe('ImportGithubSkillForm', () => {
+ it('submits the complete create skill request', async () => {
+ const onImport = vi.fn(async () => undefined);
+
+ render(<ImportGithubSkillForm open onOpenChange={() => undefined} onImport={onImport} />);
+
+ fireEvent.change(screen.getByLabelText('Name'), {
+ target: { value: ' Release notes ' },
+ });
+ fireEvent.change(screen.getByLabelText('Description'), {
+ target: { value: ' Generate release notes ' },
+ });
+ fireEvent.change(screen.getByLabelText('Repository URL'), {
+ target: { value: ' https://github.com/org/repo ' },
+ });
+ fireEvent.change(screen.getByLabelText('Path'), {
+ target: { value: ' skills/release-notes ' },
+ });
+ fireEvent.change(screen.getByLabelText('Ref'), {
+ target: { value: ' main ' },
+ });
+ fireEvent.click(screen.getByRole('button', { name: 'Import' }));
+
+ await waitFor(() => {
+ expect(onImport).toHaveBeenCalledWith({
+ name: 'Release notes',
+ description: 'Generate release notes',
+ repoURL: 'https://github.com/org/repo',
+ path: 'skills/release-notes',
+ ref: 'main',
+ });
+ });
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ImportGithubSkillForm.tsx b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ImportGithubSkillForm.tsx
new file mode 100644
index 000000000..42d2f2623
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ImportGithubSkillForm.tsx
@@ -0,0 +1,167 @@
+'use client';
+
+import { useState, type SyntheticEvent } from 'react';
+
+import { Button } from '@/atoms/primitives/Button.js';
+import { CenteredModal } from '@/atoms/primitives/CenteredModal.js';
+import { Icon } from '@/icons/Icon.js';
+import type { SkillConfigBase } from '../../server/types.js';
+
+type ImportGithubSkillFormProps = {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ onImport: (draft: SkillConfigBase) => void | Promise<void>;
+ busy?: boolean;
+};
+
+const ImportGithubSkillForm = ({ open, onOpenChange, onImport, busy = false }: ImportGithubSkillFormProps) => {
+ const [name, setName] = useState('');
+ const [description, setDescription] = useState('');
+ const [repoURL, setRepoURL] = useState('');
+ const [path, setPath] = useState('');
+ const [ref, setRef] = useState('');
+
+ const reset = () => {
+ setName('');
+ setDescription('');
+ setRepoURL('');
+ setPath('');
+ setRef('');
+ };
+
+ const close = () => {
+ reset();
+ onOpenChange(false);
+ };
+
+ const handleSubmit = async (event: SyntheticEvent<HTMLFormElement, SubmitEvent>) => {
+ event.preventDefault();
+ if (!name.trim() || !description.trim() || !repoURL.trim() || !path.trim() || !ref.trim() || busy) return;
+
+ try {
+ await onImport({
+ name: name.trim(),
+ description: description.trim(),
+ repoURL: repoURL.trim(),
+ path: path.trim(),
+ ref: ref.trim(),
+ });
+ close();
+ } catch {
+ // Parent surfaces error; keep form open.
+ }
+ };
+
+ const canImport = Boolean(name.trim() && description.trim() && repoURL.trim() && path.trim() && ref.trim()) && !busy;
+
+ return (
+ <CenteredModal
+ open={open}
+ onOpenChange={nextOpen => {
+ if (!nextOpen) close();
+ }}
+ title="Import from GitHub"
+ description="Import a skill from a SKILL.md file in a GitHub repository."
+ headerIcon={
+ <span className="flex size-11 shrink-0 items-center justify-center rounded-lg border border-border bg-muted text-foreground">
+ <Icon name="github" className="size-5" />
+ </span>
+ }
+ contentSized
+ className="md:max-w-2xl"
+ >
+ <form onSubmit={e => void handleSubmit(e)}>
+ <div className="space-y-5 px-5 py-5 md:px-6">
+ <div>
+ <label htmlFor="skill-name" className="mb-2 block text-sm font-semibold text-foreground">
+ Name
+ </label>
+ <input
+ id="skill-name"
+ value={name}
+ onChange={event => {
+ setName(event.target.value);
+ }}
+ placeholder="Release notes"
+ autoFocus
+ required
+ className="h-11 w-full rounded-md border border-input bg-background px-3 text-sm text-foreground outline-none placeholder:text-muted-foreground/70 focus-visible:ring-2 focus-visible:ring-ring/40"
+ />
+ </div>
+
+ <div>
+ <label htmlFor="skill-description" className="mb-2 block text-sm font-semibold text-foreground">
+ Description
+ </label>
+ <textarea
+ id="skill-description"
+ value={description}
+ onChange={event => {
+ setDescription(event.target.value);
+ }}
+ placeholder="Generate release notes from merged pull requests"
+ required
+ rows={3}
+ className="w-full resize-y rounded-md border border-input bg-background px-3 py-2.5 text-sm text-foreground outline-none placeholder:text-muted-foreground/70 focus-visible:ring-2 focus-visible:ring-ring/40"
+ />
+ </div>
+
+ <div>
+ <label htmlFor="skill-repo-url" className="mb-2 block text-sm font-semibold text-foreground">
+ Repository URL
+ </label>
+ <input
+ id="skill-repo-url"
+ type="url"
+ value={repoURL}
+ onChange={event => {
+ setRepoURL(event.target.value);
+ }}
+ placeholder="https://github.com/org/repo"
+ required
+ className="h-11 w-full rounded-md border border-input bg-background px-3 text-sm text-foreground outline-none placeholder:text-muted-foreground/70 focus-visible:ring-2 focus-visible:ring-ring/40"
+ />
+ </div>
+
+ <div>
+ <label htmlFor="skill-path" className="mb-2 block text-sm font-semibold text-foreground">
+ Path
+ </label>
+ <input
+ id="skill-path"
+ value={path}
+ onChange={event => {
+ setPath(event.target.value);
+ }}
+ placeholder="skills/release-notes"
+ required
+ className="h-11 w-full rounded-md border border-input bg-background px-3 text-sm text-foreground outline-none placeholder:text-muted-foreground/70 focus-visible:ring-2 focus-visible:ring-ring/40"
+ />
+ </div>
+
+ <div>
+ <label htmlFor="skill-ref" className="mb-2 block text-sm font-semibold text-foreground">
+ Ref
+ </label>
+ <input
+ id="skill-ref"
+ value={ref}
+ onChange={event => {
+ setRef(event.target.value);
+ }}
+ placeholder="main"
+ required
+ className="h-11 w-full rounded-md border border-input bg-background px-3 text-sm text-foreground outline-none placeholder:text-muted-foreground/70 focus-visible:ring-2 focus-visible:ring-ring/40"
+ />
+ </div>
+
+ <Button type="submit" disabled={!canImport} className="w-full">
+ Import
+ </Button>
+ </div>
+ </form>
+ </CenteredModal>
+ );
+};
+
+export default ImportGithubSkillForm;
diff --git a/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ModelSettings.tsx b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ModelSettings.tsx
new file mode 100644
index 000000000..cd214e743
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/ModelSettings.tsx
@@ -0,0 +1,448 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { Button } from '../../atoms/primitives/Button.js';
+import SearchInput from '../../atoms/primitives/SearchInput.js';
+import { Icon } from '../../icons/Icon.js';
+import { useCatalogServer } from '../../server/ServerContext.js';
+import type { ModelEntry, ModelProviderBase, ModelProviderCatalogEntry } from '../../server/types.js';
+import CustomModelProviderForm, { type CustomProviderDraft } from './CustomModelProviderForm.js';
+
+const ModelSettings = () => {
+ const { modelCatalog } = useCatalogServer();
+
+ const [query, setQuery] = useState('');
+ const [configured, setConfigured] = useState<ModelProviderBase[]>([]);
+ const [catalog, setCatalog] = useState<ModelProviderCatalogEntry[]>([]);
+ const [loading, setLoading] = useState(true);
+ const [error, setError] = useState<string | null>(null);
+ const [busy, setBusy] = useState(false);
+
+ const [editingProviderId, setEditingProviderId] = useState<string | null>(null);
+ const [editingCatalogType, setEditingCatalogType] = useState<string | null>(null);
+ const [apiKey, setApiKey] = useState('');
+ const [customProviderOpen, setCustomProviderOpen] = useState(false);
+
+ const normalizedQuery = query.trim().toLowerCase();
+
+ const refresh = useCallback(async () => {
+ setLoading(true);
+ setError(null);
+ try {
+ const [listed, available] = await Promise.all([
+ modelCatalog.listModelProviders(),
+ modelCatalog.getModelProviderCatalog(),
+ ]);
+ setConfigured(listed);
+ setCatalog(available);
+ } catch (err) {
+ setError(err instanceof Error ? err.message : 'Failed to load model providers');
+ } finally {
+ setLoading(false);
+ }
+ }, [modelCatalog]);
+
+ useEffect(() => {
+ void refresh();
+ }, [refresh]);
+
+ const configuredTypes = useMemo(() => new Set(configured.map(provider => provider.type)), [configured]);
+
+ const matchingConfigured = useMemo(
+ () =>
+ configured.filter(
+ provider =>
+ provider.name.toLowerCase().includes(normalizedQuery) ||
+ provider.models.some(
+ model =>
+ model.name.toLowerCase().includes(normalizedQuery) || model.id.toLowerCase().includes(normalizedQuery),
+ ),
+ ),
+ [configured, normalizedQuery],
+ );
+
+ const matchingAvailable = useMemo(
+ () =>
+ catalog.filter(
+ provider =>
+ provider.type !== 'custom' &&
+ !configuredTypes.has(provider.type) &&
+ (provider.name.toLowerCase().includes(normalizedQuery) ||
+ provider.models.some(
+ model =>
+ model.name.toLowerCase().includes(normalizedQuery) || model.id.toLowerCase().includes(normalizedQuery),
+ )),
+ ),
+ [catalog, configuredTypes, normalizedQuery],
+ );
+
+ const catalogModelsByType = useMemo(() => {
+ const map = new Map<string, ModelEntry[]>();
+ for (const entry of catalog) {
+ map.set(entry.type, entry.models);
+ }
+ return map;
+ }, [catalog]);
+
+ const closeKeyEditor = () => {
+ setEditingProviderId(null);
+ setEditingCatalogType(null);
+ setApiKey('');
+ };
+
+ const runMutation = async (fn: () => Promise<void>) => {
+ setBusy(true);
+ setError(null);
+ try {
+ await fn();
+ await refresh();
+ closeKeyEditor();
+ } catch (err) {
+ setError(err instanceof Error ? err.message : 'Request failed');
+ throw err;
+ } finally {
+ setBusy(false);
+ }
+ };
+
+ const handleCreateFromCatalog = (providerType: string) => {
+ const entry = catalog.find(item => item.type === providerType);
+ if (!entry || !apiKey.trim()) return;
+
+ void runMutation(async () => {
+ await modelCatalog.createModelProvider({
+ type: entry.type,
+ name: entry.name,
+ apiKey: apiKey.trim(),
+ models: entry.models,
+ });
+ }).catch(() => {});
+ };
+
+ const handleReplaceKey = (provider: ModelProviderBase) => {
+ if (!apiKey.trim()) return;
+
+ void runMutation(async () => {
+ await modelCatalog.updateModelProvider({
+ id: provider.id,
+ type: provider.type,
+ name: provider.name,
+ ...(provider.baseUrl ? { baseUrl: provider.baseUrl } : {}),
+ apiKey: apiKey.trim(),
+ models: provider.models,
+ });
+ }).catch(() => {});
+ };
+
+ const handleRemoveProvider = (provider: ModelProviderBase) => {
+ if (!modelCatalog.deleteModelProvider) return;
+
+ void runMutation(async () => {
+ await modelCatalog.deleteModelProvider!({ id: provider.id });
+ }).catch(() => {});
+ };
+
+ const handleUpdateModels = (provider: ModelProviderBase, models: ModelEntry[]) => {
+ void runMutation(async () => {
+ // apiKey required on update; empty means "keep existing" for hosts that support it.
+ await modelCatalog.updateModelProvider({
+ id: provider.id,
+ type: provider.type,
+ name: provider.name,
+ ...(provider.baseUrl ? { baseUrl: provider.baseUrl } : {}),
+ apiKey: '',
+ models,
+ });
+ }).catch(() => {});
+ };
+
+ const handleAddCustomProvider = async (draft: CustomProviderDraft) => {
+ await runMutation(async () => {
+ await modelCatalog.createModelProvider({
+ type: 'custom',
+ name: draft.name,
+ baseUrl: draft.baseUrl,
+ apiKey: draft.apiKey,
+ models: draft.models,
+ });
+ });
+ };
+
+ const renderKeyEditor = (opts: { id: string; submitLabel: string; onSave: () => void }) => (
+ <form
+ className="mt-4 rounded-lg border border-border bg-muted/20 p-4"
+ onSubmit={event => {
+ event.preventDefault();
+ opts.onSave();
+ }}
+ >
+ <label
+ htmlFor={`api-key-${opts.id}`}
+ className="mb-2 block text-xs font-semibold uppercase tracking-wide text-muted-foreground"
+ >
+ API key
+ </label>
+ <input
+ id={`api-key-${opts.id}`}
+ type="password"
+ value={apiKey}
+ onChange={event => {
+ setApiKey(event.target.value);
+ }}
+ placeholder="sk-..."
+ autoFocus
+ className="h-10 w-full rounded-md border border-input bg-background px-3 text-sm text-foreground outline-none placeholder:text-muted-foreground focus-visible:ring-2 focus-visible:ring-ring/40"
+ />
+ <div className="mt-3 flex justify-end gap-2">
+ <Button variant="ghost" size="sm" type="button" onClick={closeKeyEditor} disabled={busy}>
+ Cancel
+ </Button>
+ <Button size="sm" type="submit" disabled={!apiKey.trim() || busy}>
+ {opts.submitLabel}
+ </Button>
+ </div>
+ </form>
+ );
+
+ return (
+ <>
+ <h3 className="text-xl font-semibold tracking-tight text-foreground">Models</h3>
+ <p className="mt-1 text-sm text-muted-foreground">Connect providers and choose which models are available.</p>
+
+ {error ? (
+ <p className="mt-3 rounded-md border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive">
+ {error}
+ </p>
+ ) : null}
+
+ <div className="mt-4 flex-1 overflow-y-hidden">
+ <div className="flex h-full flex-col gap-3">
+ <div className="flex gap-2">
+ <div className="flex-1">
+ <SearchInput query={query} setQuery={setQuery} placeholder="Search providers and models" />
+ </div>
+ <Button
+ variant="secondary"
+ type="button"
+ onClick={() => {
+ setCustomProviderOpen(true);
+ }}
+ >
+ <Icon name="plus" size="1rem" className="mr-1" />
+ Add Custom Provider
+ </Button>
+ </div>
+
+ <div className="flex flex-1 flex-col gap-2 overflow-y-auto">
+ {loading ? <p className="py-8 text-center text-sm text-muted-foreground">Loading…</p> : null}
+
+ {!loading && matchingConfigured.length > 0 ? (
+ <section aria-labelledby="configured-providers-heading">
+ <div
+ id="configured-providers-heading"
+ className="mb-2 text-[0.8125rem] font-semibold uppercase text-muted-foreground"
+ >
+ Configured
+ </div>
+
+ <div className="overflow-hidden rounded-xl border border-border bg-card">
+ {matchingConfigured.map(provider => {
+ const catalogModels = catalogModelsByType.get(provider.type) ?? [];
+ const configuredIds = new Set(provider.models.map(model => model.id));
+ const availableModels = catalogModels.filter(model => !configuredIds.has(model.id));
+
+ return (
+ <article key={provider.id} className="border-b border-border p-3 last:border-b-0">
+ <header className="flex flex-col gap-3 sm:flex-row sm:items-center">
+ <div className="flex min-w-0 flex-1 items-center gap-3">
+ <div
+ className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg border border-border bg-muted text-foreground"
+ aria-hidden
+ >
+ <Icon name="cpu" className="size-4.5" />
+ </div>
+ <h5 className="truncate text-base font-medium text-foreground">{provider.name}</h5>
+ </div>
+
+ <div className="flex flex-wrap items-center gap-2.5 sm:justify-end">
+ <span className="flex items-center gap-1.5 text-[13px] font-medium text-foreground">
+ <span className="h-1.5 w-1.5 rounded-full bg-primary"></span>
+ Connected
+ </span>
+ <Button
+ variant="secondary"
+ size="sm"
+ className="text-[0.8125rem]"
+ type="button"
+ disabled={busy}
+ onClick={() => {
+ setEditingCatalogType(null);
+ setEditingProviderId(provider.id);
+ setApiKey('');
+ }}
+ >
+ <Icon name="wrench" className="size-3.5" />
+ Replace key
+ </Button>
+ {modelCatalog.deleteModelProvider ? (
+ <Button
+ variant="outline"
+ size="sm"
+ className="transition-colors hover:bg-destructive/10 hover:text-destructive"
+ type="button"
+ disabled={busy}
+ onClick={() => {
+ handleRemoveProvider(provider);
+ }}
+ >
+ Remove
+ </Button>
+ ) : null}
+ </div>
+ </header>
+
+ {editingProviderId === provider.id
+ ? renderKeyEditor({
+ id: provider.id,
+ submitLabel: 'Update',
+ onSave: () => {
+ handleReplaceKey(provider);
+ },
+ })
+ : null}
+
+ <div className="mt-3 overflow-hidden rounded-lg border border-border bg-secondary/30">
+ {provider.models.map(model => (
+ <div
+ key={model.id}
+ className="flex min-h-10 items-center gap-3 border-b border-border px-3 py-2 text-sm text-foreground last:border-b-0"
+ >
+ <span className="min-w-0 flex-1 truncate">{model.name}</span>
+ <button
+ type="button"
+ aria-label={`Remove ${model.name}`}
+ disabled={busy}
+ className="inline-flex size-7 shrink-0 items-center justify-center rounded-md text-muted-foreground hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:opacity-50"
+ onClick={() => {
+ handleUpdateModels(
+ provider,
+ provider.models.filter(item => item.id !== model.id),
+ );
+ }}
+ >
+ <Icon name="trash" className="size-3.5" />
+ </button>
+ </div>
+ ))}
+
+ {availableModels.length > 0 ? (
+ <section>
+ <div className="border-b border-border bg-muted/40 px-3 py-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+ Available to add · {availableModels.length}
+ </div>
+ {availableModels.map(model => (
+ <div
+ key={model.id}
+ className="flex min-h-12 items-center gap-3 border-b border-border px-3 py-2 text-sm text-foreground last:border-b-0"
+ >
+ <span className="min-w-0 flex-1 truncate">{model.name}</span>
+ <Button
+ variant="outline"
+ size="sm"
+ type="button"
+ disabled={busy}
+ onClick={() => {
+ handleUpdateModels(provider, [...provider.models, model]);
+ }}
+ >
+ Add
+ </Button>
+ </div>
+ ))}
+ </section>
+ ) : null}
+ </div>
+ </article>
+ );
+ })}
+ </div>
+ </section>
+ ) : null}
+
+ {!loading && matchingAvailable.length > 0 ? (
+ <section aria-labelledby="available-providers-heading" className="mt-2">
+ <div
+ id="available-providers-heading"
+ className="mb-2 text-[0.8125rem] font-semibold uppercase text-muted-foreground"
+ >
+ Available
+ </div>
+
+ <div className="overflow-hidden rounded-xl border border-border bg-card">
+ {matchingAvailable.map(provider => (
+ <article key={provider.type} className="border-b border-border p-3 last:border-b-0">
+ <header className="flex flex-col gap-3 sm:flex-row sm:items-center">
+ <div className="flex min-w-0 flex-1 items-center gap-3">
+ <span
+ className="flex size-9 shrink-0 items-center justify-center rounded-lg border border-border bg-muted text-foreground"
+ aria-hidden
+ >
+ <Icon name="cpu" className="size-4.5" />
+ </span>
+ <div className="min-w-0">
+ <h5 className="truncate text-base font-medium text-foreground">{provider.name}</h5>
+ <p className="truncate text-sm text-muted-foreground">
+ {provider.models.map(model => model.name).join(' · ')}
+ </p>
+ </div>
+ </div>
+ <Button
+ variant="secondary"
+ type="button"
+ disabled={busy}
+ onClick={() => {
+ setEditingProviderId(null);
+ setEditingCatalogType(provider.type);
+ setApiKey('');
+ }}
+ >
+ <Icon name="wrench" className="size-4" />
+ Configure
+ </Button>
+ </header>
+ {editingCatalogType === provider.type
+ ? renderKeyEditor({
+ id: provider.type,
+ submitLabel: 'Create',
+ onSave: () => {
+ handleCreateFromCatalog(provider.type);
+ },
+ })
+ : null}
+ </article>
+ ))}
+ </div>
+ </section>
+ ) : null}
+
+ {!loading && matchingConfigured.length === 0 && matchingAvailable.length === 0 ? (
+ <div className="flex flex-1 items-center justify-center rounded-xl border border-dashed border-border p-8 text-center text-sm text-muted-foreground">
+ {normalizedQuery ? `No providers match “${query.trim()}”.` : 'No model providers yet.'}
+ </div>
+ ) : null}
+ </div>
+
+ <CustomModelProviderForm
+ open={customProviderOpen}
+ onOpenChange={setCustomProviderOpen}
+ onAdd={handleAddCustomProvider}
+ busy={busy}
+ />
+ </div>
+ </div>
+ </>
+ );
+};
+
+export default ModelSettings;
diff --git a/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/SandboxSettings.test.tsx b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/SandboxSettings.test.tsx
new file mode 100644
index 000000000..b9e3578db
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/SandboxSettings.test.tsx
@@ -0,0 +1,185 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { ServerProvider } from '../../server/ServerContext.js';
+import type {
+ AgentUIServer,
+ CreateSandboxRequest,
+ SandboxBase,
+ SandboxCatalogEntry,
+ UpdateSandboxRequest,
+} from '../../server/types.js';
+import SandboxSettings from './SandboxSettings.js';
+
+beforeAll(() => {
+ HTMLDialogElement.prototype.showModal = function showModal() {
+ this.setAttribute('open', '');
+ };
+ HTMLDialogElement.prototype.close = function close() {
+ this.removeAttribute('open');
+ };
+});
+
+const catalogEntry: SandboxCatalogEntry = {
+ id: 'cat-daytona',
+ name: 'Daytona',
+ type: 'daytona',
+ snapshotName: 'daytona-default',
+ execTimeoutMs: 300000,
+ autoStopIntervalInMinutes: 15,
+ autoArchiveIntervalInMinutes: 10080,
+ autoDeleteIntervalInMinutes: 43200,
+};
+
+function createFakeHost(initial: SandboxBase[] = []) {
+ let sandboxes = [...initial];
+ const created: CreateSandboxRequest[] = [];
+ const updated: UpdateSandboxRequest[] = [];
+
+ const sandboxCatalog = {
+ getSandboxCatalog: async () => [catalogEntry],
+ listSandboxes: async () => sandboxes,
+ createSandbox: async (req: CreateSandboxRequest) => {
+ created.push(req);
+ const sandbox: SandboxBase = {
+ id: `sb-${req.catalogId}`,
+ name: req.name,
+ catalogId: req.catalogId,
+ isConnected: true,
+ snapshotName: req.snapshotName,
+ execTimeoutMs: req.execTimeoutMs,
+ autoStopIntervalInMinutes: req.autoStopIntervalInMinutes,
+ autoArchiveIntervalInMinutes: req.autoArchiveIntervalInMinutes,
+ autoDeleteIntervalInMinutes: req.autoDeleteIntervalInMinutes,
+ };
+ sandboxes = [...sandboxes, sandbox];
+ return sandbox;
+ },
+ updateSandbox: async (req: UpdateSandboxRequest) => {
+ updated.push(req);
+ sandboxes = sandboxes.map(sandbox =>
+ sandbox.id === req.id
+ ? {
+ ...sandbox,
+ snapshotName: req.snapshotName,
+ execTimeoutMs: req.execTimeoutMs,
+ autoStopIntervalInMinutes: req.autoStopIntervalInMinutes,
+ autoArchiveIntervalInMinutes: req.autoArchiveIntervalInMinutes,
+ autoDeleteIntervalInMinutes: req.autoDeleteIntervalInMinutes,
+ }
+ : sandbox,
+ );
+ return sandboxes.find(sandbox => sandbox.id === req.id)!;
+ },
+ deleteSandbox: async ({ id }: { id: string }) => {
+ sandboxes = sandboxes.filter(sandbox => sandbox.id !== id);
+ },
+ };
+
+ const server = { catalog: { sandboxCatalog } } as unknown as AgentUIServer;
+
+ return {
+ created,
+ updated,
+ getSandboxes: () => sandboxes,
+ wrapper: ({ children }: { children: ReactNode }) => <ServerProvider server={server}>{children}</ServerProvider>,
+ };
+}
+
+describe('SandboxSettings', () => {
+ it('autofills create form from catalog except apiKey', async () => {
+ const host = createFakeHost();
+ const { wrapper: Wrapper } = host;
+ render(
+ <Wrapper>
+ <SandboxSettings />
+ </Wrapper>,
+ );
+
+ await waitFor(() => {
+ expect(screen.getByText('Daytona')).toBeTruthy();
+ });
+
+ fireEvent.click(screen.getByRole('button', { name: 'Configure' }));
+
+ await waitFor(() => {
+ expect(screen.getByLabelText('Snapshot name')).toHaveProperty('value', 'daytona-default');
+ });
+ expect(screen.getByLabelText('Exec timeout (ms)')).toHaveProperty('value', '300000');
+ expect(screen.getByLabelText('Auto-stop interval (minutes)')).toHaveProperty('value', '15');
+ expect(screen.getByLabelText('Auto-archive interval (minutes)')).toHaveProperty('value', '10080');
+ expect(screen.getByLabelText('Auto-delete interval (minutes)')).toHaveProperty('value', '43200');
+ expect(screen.getByLabelText('API key')).toHaveProperty('value', '');
+
+ fireEvent.change(screen.getByLabelText('API key'), {
+ target: { value: 'dtn_secret' },
+ });
+ fireEvent.click(screen.getByRole('button', { name: 'Save' }));
+
+ await waitFor(() => {
+ expect(host.created).toHaveLength(1);
+ });
+ expect(host.created[0]).toMatchObject({
+ catalogId: 'cat-daytona',
+ name: 'Daytona',
+ type: 'daytona',
+ snapshotName: 'daytona-default',
+ execTimeoutMs: 300000,
+ autoStopIntervalInMinutes: 15,
+ autoArchiveIntervalInMinutes: 10080,
+ autoDeleteIntervalInMinutes: 43200,
+ apiKey: 'dtn_secret',
+ });
+ });
+
+ it('prefills update form and allows saving without re-entering apiKey', async () => {
+ const existing: SandboxBase = {
+ id: 'sb-1',
+ name: 'Daytona',
+ catalogId: 'cat-daytona',
+ isConnected: true,
+ snapshotName: 'custom-snap',
+ execTimeoutMs: 60000,
+ autoStopIntervalInMinutes: 30,
+ autoArchiveIntervalInMinutes: 1440,
+ autoDeleteIntervalInMinutes: 10080,
+ };
+ const host = createFakeHost([existing]);
+ const { wrapper: Wrapper } = host;
+ render(
+ <Wrapper>
+ <SandboxSettings />
+ </Wrapper>,
+ );
+
+ await waitFor(() => {
+ expect(screen.getByRole('button', { name: 'Update' })).toBeTruthy();
+ });
+
+ fireEvent.click(screen.getByRole('button', { name: 'Update' }));
+
+ await waitFor(() => {
+ expect(screen.getByLabelText('Snapshot name')).toHaveProperty('value', 'custom-snap');
+ });
+ expect(screen.getByLabelText('Exec timeout (ms)')).toHaveProperty('value', '60000');
+ expect(screen.getByLabelText('Auto-stop interval (minutes)')).toHaveProperty('value', '30');
+ expect(screen.getByLabelText(/API key/)).toHaveProperty('value', '');
+
+ fireEvent.click(screen.getByRole('button', { name: 'Save' }));
+
+ await waitFor(() => {
+ expect(host.updated).toHaveLength(1);
+ });
+ expect(host.updated[0]).toEqual({
+ id: 'sb-1',
+ snapshotName: 'custom-snap',
+ execTimeoutMs: 60000,
+ autoStopIntervalInMinutes: 30,
+ autoArchiveIntervalInMinutes: 1440,
+ autoDeleteIntervalInMinutes: 10080,
+ });
+ expect(host.updated[0]).not.toHaveProperty('apiKey');
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/SandboxSettings.tsx b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/SandboxSettings.tsx
new file mode 100644
index 000000000..dd0103c15
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/SandboxSettings.tsx
@@ -0,0 +1,283 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { Button } from '../../atoms/primitives/Button.js';
+import { Icon } from '../../icons/Icon.js';
+import { useCatalogServer } from '../../server/ServerContext.js';
+import type { SandboxBase, SandboxCatalogEntry, SandboxConfig } from '../../server/types.js';
+import ConfigureSandboxForm, { type SandboxConfigDraft } from './ConfigureSandboxForm.js';
+
+const configFrom = ({
+ snapshotName,
+ execTimeoutMs,
+ autoStopIntervalInMinutes,
+ autoArchiveIntervalInMinutes,
+ autoDeleteIntervalInMinutes,
+}: SandboxConfig): SandboxConfig => ({
+ snapshotName,
+ execTimeoutMs,
+ autoStopIntervalInMinutes,
+ autoArchiveIntervalInMinutes,
+ autoDeleteIntervalInMinutes,
+});
+
+const SandboxSettings = () => {
+ const { sandboxCatalog } = useCatalogServer();
+
+ const [sandboxes, setSandboxes] = useState<SandboxBase[]>([]);
+ const [catalog, setCatalog] = useState<SandboxCatalogEntry[]>([]);
+ const [loading, setLoading] = useState(true);
+ const [error, setError] = useState<string | null>(null);
+ const [busy, setBusy] = useState(false);
+
+ const [createEntry, setCreateEntry] = useState<SandboxCatalogEntry | null>(null);
+ const [updateSandbox, setUpdateSandbox] = useState<SandboxBase | null>(null);
+
+ const refresh = useCallback(
+ async ({ quiet = false }: { quiet?: boolean } = {}) => {
+ if (!sandboxCatalog) return;
+ if (!quiet) setLoading(true);
+ setError(null);
+ try {
+ const [listed, available] = await Promise.all([
+ sandboxCatalog.listSandboxes(),
+ sandboxCatalog.getSandboxCatalog(),
+ ]);
+ setSandboxes(listed);
+ setCatalog(available);
+ } catch (err) {
+ setError(err instanceof Error ? err.message : 'Failed to load sandboxes');
+ } finally {
+ if (!quiet) setLoading(false);
+ }
+ },
+ [sandboxCatalog],
+ );
+
+ useEffect(() => {
+ void refresh();
+ }, [refresh]);
+
+ const availableEntries = useMemo(() => {
+ const connectedCatalogIds = new Set(sandboxes.map(sandbox => sandbox.catalogId));
+ return catalog.filter(entry => !connectedCatalogIds.has(entry.id));
+ }, [catalog, sandboxes]);
+
+ const formInitialConfig = useMemo(
+ () => (updateSandbox ? configFrom(updateSandbox) : createEntry ? configFrom(createEntry) : null),
+ [updateSandbox, createEntry],
+ );
+
+ if (!sandboxCatalog) {
+ return <p className="text-sm text-muted-foreground">Sandbox catalog is not available.</p>;
+ }
+
+ const runMutation = async (fn: () => Promise<void>) => {
+ setBusy(true);
+ setError(null);
+ try {
+ await fn();
+ await refresh({ quiet: true });
+ } catch (err) {
+ setError(err instanceof Error ? err.message : 'Request failed');
+ throw err;
+ } finally {
+ setBusy(false);
+ }
+ };
+
+ const handleCreate = async (draft: SandboxConfigDraft) => {
+ if (!createEntry) return;
+ await runMutation(async () => {
+ await sandboxCatalog.createSandbox({
+ catalogId: createEntry.id,
+ name: createEntry.name,
+ type: createEntry.type,
+ ...configFrom(draft),
+ apiKey: draft.apiKey,
+ });
+ });
+ setCreateEntry(null);
+ };
+
+ const handleUpdate = async (draft: SandboxConfigDraft) => {
+ if (!updateSandbox) return;
+ await runMutation(async () => {
+ await sandboxCatalog.updateSandbox({
+ id: updateSandbox.id,
+ ...configFrom(draft),
+ ...(draft.apiKey ? { apiKey: draft.apiKey } : {}),
+ });
+ });
+ setUpdateSandbox(null);
+ };
+
+ const handleRemove = (sandbox: SandboxBase) => {
+ void runMutation(async () => {
+ await sandboxCatalog.deleteSandbox({ id: sandbox.id });
+ }).catch(() => {});
+ };
+
+ const formOpen = createEntry != null || updateSandbox != null;
+ const isUpdate = updateSandbox != null;
+ const formTitle = updateSandbox
+ ? `Update ${updateSandbox.name}`
+ : createEntry
+ ? `Configure ${createEntry.name}`
+ : 'Configure sandbox';
+
+ return (
+ <>
+ <h3 className="text-xl font-semibold tracking-tight text-foreground">Sandbox</h3>
+ <p className="mt-1 text-sm text-muted-foreground">
+ A secure, isolated environment for running code, files, and shell commands.
+ </p>
+
+ {error ? (
+ <p className="mt-3 rounded-md border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive">
+ {error}
+ </p>
+ ) : null}
+
+ <div className="mt-4 flex-1 overflow-y-auto">
+ {loading ? (
+ <p className="text-sm text-muted-foreground">Loading sandboxes…</p>
+ ) : (
+ <div className="space-y-6">
+ {sandboxes.length > 0 ? (
+ <section>
+ <h4 className="mb-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+ Connected · {sandboxes.length}
+ </h4>
+ <div className="overflow-hidden rounded-xl border border-border bg-card">
+ {sandboxes.map(sandbox => (
+ <article
+ key={sandbox.id}
+ className="flex flex-col gap-3 border-b border-border p-3 last:border-b-0 sm:flex-row sm:items-center"
+ >
+ <div className="flex min-w-0 flex-1 items-center gap-3">
+ <span
+ className="flex size-9 shrink-0 items-center justify-center rounded-lg border border-border bg-muted text-foreground"
+ aria-hidden
+ >
+ <Icon name="cube" className="size-4.5" />
+ </span>
+ <div className="min-w-0">
+ <h5 className="truncate text-sm font-medium text-foreground">{sandbox.name}</h5>
+ <p className="truncate text-[0.8125rem] text-muted-foreground">{sandbox.snapshotName}</p>
+ </div>
+ </div>
+
+ <div className="flex flex-wrap items-center gap-2.5 sm:justify-end">
+ {sandbox.isConnected ? (
+ <span className="flex items-center gap-1.5 text-[13px] font-medium text-foreground">
+ <span className="h-1.5 w-1.5 rounded-full bg-primary"></span>
+ Connected
+ </span>
+ ) : null}
+ <Button
+ variant="secondary"
+ size="sm"
+ type="button"
+ disabled={busy}
+ onClick={() => {
+ setCreateEntry(null);
+ setUpdateSandbox(sandbox);
+ }}
+ >
+ Update
+ </Button>
+ <Button
+ variant="ghost"
+ size="sm"
+ className="text-muted-foreground"
+ type="button"
+ disabled={busy}
+ onClick={() => {
+ handleRemove(sandbox);
+ }}
+ >
+ Remove
+ </Button>
+ </div>
+ </article>
+ ))}
+ </div>
+ </section>
+ ) : null}
+
+ <section>
+ <h4 className="mb-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+ Available · {availableEntries.length}
+ </h4>
+ {availableEntries.length === 0 ? (
+ <p className="text-sm text-muted-foreground">
+ {sandboxes.length > 0 ? 'All catalog sandboxes are configured.' : 'No sandboxes in the catalog.'}
+ </p>
+ ) : (
+ <div className="overflow-hidden rounded-xl border border-border bg-card">
+ {availableEntries.map(entry => (
+ <article
+ key={entry.id}
+ className="flex flex-col gap-3 border-b border-border p-3 last:border-b-0 sm:flex-row sm:items-center"
+ >
+ <div className="flex min-w-0 flex-1 items-center gap-3">
+ <span
+ className="flex size-9 shrink-0 items-center justify-center rounded-lg border border-border bg-muted text-foreground"
+ aria-hidden
+ >
+ <Icon name="cube" className="size-4.5" />
+ </span>
+ <div className="min-w-0">
+ <h5 className="truncate text-sm font-medium text-foreground">{entry.name}</h5>
+ <p className="truncate text-[0.8125rem] text-muted-foreground">
+ {entry.snapshotName} · {entry.type}
+ </p>
+ </div>
+ </div>
+
+ <Button
+ variant="secondary"
+ type="button"
+ disabled={busy}
+ onClick={() => {
+ setUpdateSandbox(null);
+ setCreateEntry(entry);
+ }}
+ >
+ Configure
+ </Button>
+ </article>
+ ))}
+ </div>
+ )}
+ </section>
+ </div>
+ )}
+ </div>
+
+ <ConfigureSandboxForm
+ open={formOpen}
+ onOpenChange={open => {
+ if (!open) {
+ setCreateEntry(null);
+ setUpdateSandbox(null);
+ }
+ }}
+ onSave={isUpdate ? handleUpdate : handleCreate}
+ title={formTitle}
+ description={
+ isUpdate
+ ? 'Update sandbox settings. Leave API key blank to keep the existing key.'
+ : 'Managed sandbox settings. API key is never stored in the catalog.'
+ }
+ initialConfig={formInitialConfig}
+ requireApiKey={!isUpdate}
+ busy={busy}
+ />
+ </>
+ );
+};
+
+export default SandboxSettings;
diff --git a/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/SkillSettings.test.tsx b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/SkillSettings.test.tsx
new file mode 100644
index 000000000..d77e14aec
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/SkillSettings.test.tsx
@@ -0,0 +1,183 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { beforeAll, describe, expect, it } from 'vitest';
+
+import { ServerProvider } from '../../server/ServerContext.js';
+import type { AgentUIServer, CreateSkillRequest, DefinedSkill, SkillCatalogEntry } from '../../server/types.js';
+import SkillSettings from './SkillSettings.js';
+
+beforeAll(() => {
+ HTMLDialogElement.prototype.showModal = function showModal() {
+ this.setAttribute('open', '');
+ };
+ HTMLDialogElement.prototype.close = function close() {
+ this.removeAttribute('open');
+ };
+});
+
+const catalogEntry: SkillCatalogEntry = {
+ id: 'cat-code-review',
+ name: 'Code Review',
+ description: 'Review a diff for correctness, risk and style.',
+ repoURL: 'https://github.com/truefoundry/skills',
+ path: 'skills/code-review',
+ ref: 'main',
+};
+
+/** In-memory host: catalog is fixed, defined skills live in a mutable list. */
+function createFakeHost(initial: DefinedSkill[] = []) {
+ let defined = [...initial];
+ const created: CreateSkillRequest[] = [];
+
+ const skillCatalog = {
+ getSkillCatalog: async () => [catalogEntry],
+ listSkills: async () => defined,
+ createSkill: async (req: CreateSkillRequest) => {
+ created.push(req);
+ const skill: DefinedSkill =
+ 'catalogId' in req
+ ? {
+ id: `db-${req.catalogId}`,
+ name: req.name,
+ description: req.description,
+ catalogId: req.catalogId,
+ }
+ : {
+ id: `db-${req.name}`,
+ name: req.name,
+ description: req.description,
+ };
+ defined = [...defined, skill];
+ return skill;
+ },
+ deleteSkill: async ({ id }: { id: string }) => {
+ defined = defined.filter(skill => skill.id !== id);
+ },
+ };
+
+ const server = { catalog: { skillCatalog } } as unknown as AgentUIServer;
+
+ return {
+ created,
+ getDefined: () => defined,
+ wrapper: ({ children }: { children: ReactNode }) => <ServerProvider server={server}>{children}</ServerProvider>,
+ };
+}
+
+describe('SkillSettings', () => {
+ it('selects a catalog skill and moves it out of Available', async () => {
+ const host = createFakeHost();
+ const { wrapper: Wrapper } = host;
+
+ render(
+ <Wrapper>
+ <SkillSettings />
+ </Wrapper>,
+ );
+
+ fireEvent.click(await screen.findByRole('button', { name: 'Select Code Review' }));
+
+ await waitFor(() => {
+ expect(screen.getByRole('button', { name: 'Remove Code Review' })).toBeTruthy();
+ });
+ expect(screen.queryByRole('button', { name: 'Select Code Review' })).toBeNull();
+ expect(host.created).toEqual([
+ {
+ catalogId: catalogEntry.id,
+ name: catalogEntry.name,
+ description: catalogEntry.description,
+ repoURL: catalogEntry.repoURL,
+ path: catalogEntry.path,
+ ref: catalogEntry.ref,
+ },
+ ]);
+ });
+
+ it('returns a removed registry skill to Available', async () => {
+ const { wrapper: Wrapper } = createFakeHost([
+ {
+ id: 'db-cat-code-review',
+ name: catalogEntry.name,
+ description: catalogEntry.description,
+ catalogId: catalogEntry.id,
+ },
+ ]);
+
+ render(
+ <Wrapper>
+ <SkillSettings />
+ </Wrapper>,
+ );
+
+ fireEvent.click(await screen.findByRole('button', { name: 'Remove Code Review' }));
+
+ await waitFor(() => {
+ expect(screen.getByRole('button', { name: 'Select Code Review' })).toBeTruthy();
+ });
+ });
+
+ it('removes an imported github skill entirely', async () => {
+ const host = createFakeHost([
+ {
+ id: 'db-house-style',
+ name: 'House Style',
+ description: 'Writing rules and tone-of-voice for external copy.',
+ },
+ ]);
+ const { wrapper: Wrapper } = host;
+
+ render(
+ <Wrapper>
+ <SkillSettings />
+ </Wrapper>,
+ );
+
+ fireEvent.click(await screen.findByRole('button', { name: 'Remove House Style' }));
+
+ await waitFor(() => {
+ expect(screen.queryByText('House Style')).toBeNull();
+ });
+ expect(host.getDefined()).toEqual([]);
+ });
+
+ it('imports a github skill without a type discriminant', async () => {
+ const host = createFakeHost();
+ const { wrapper: Wrapper } = host;
+
+ render(
+ <Wrapper>
+ <SkillSettings />
+ </Wrapper>,
+ );
+
+ fireEvent.click(await screen.findByRole('button', { name: /Import from GitHub/ }));
+
+ fireEvent.change(screen.getByLabelText('Name'), {
+ target: { value: 'House Style' },
+ });
+ fireEvent.change(screen.getByLabelText('Description'), {
+ target: { value: 'Writing rules' },
+ });
+ fireEvent.change(screen.getByLabelText('Repository URL'), {
+ target: { value: 'https://github.com/org/repo' },
+ });
+ fireEvent.change(screen.getByLabelText('Path'), {
+ target: { value: 'skills/house-style' },
+ });
+ fireEvent.change(screen.getByLabelText('Ref'), { target: { value: 'main' } });
+ fireEvent.click(screen.getByRole('button', { name: 'Import' }));
+
+ await waitFor(() => {
+ expect(host.created).toEqual([
+ {
+ name: 'House Style',
+ description: 'Writing rules',
+ repoURL: 'https://github.com/org/repo',
+ path: 'skills/house-style',
+ ref: 'main',
+ },
+ ]);
+ });
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/SkillSettings.tsx b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/SkillSettings.tsx
new file mode 100644
index 000000000..dc326d716
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/SkillSettings.tsx
@@ -0,0 +1,266 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+
+import { Button } from '@/atoms/primitives/Button.js';
+import SearchInput from '@/atoms/primitives/SearchInput.js';
+import { Icon } from '@/icons/Icon.js';
+import { useCatalogServer } from '../../server/ServerContext.js';
+import type { RegistrySkill, SkillBase, SkillCatalogEntry, SkillConfigBase } from '../../server/types.js';
+import ImportGithubSkillForm from './ImportGithubSkillForm.js';
+
+const matchesQuery = (query: string, name: string, description: string) =>
+ !query || name.toLowerCase().includes(query) || description.toLowerCase().includes(query);
+
+const isRegistrySkill = (skill: SkillBase): skill is RegistrySkill => 'catalogId' in skill;
+
+const SkillSettings = () => {
+ const { skillCatalog } = useCatalogServer();
+
+ const [query, setQuery] = useState('');
+ const [skills, setSkills] = useState<SkillBase[]>([]);
+ const [catalog, setCatalog] = useState<SkillCatalogEntry[]>([]);
+ const [loading, setLoading] = useState(true);
+ const [error, setError] = useState<string | null>(null);
+ const [busy, setBusy] = useState(false);
+ const [importOpen, setImportOpen] = useState(false);
+
+ const refresh = useCallback(async () => {
+ if (!skillCatalog) return;
+ setLoading(true);
+ setError(null);
+ try {
+ const [defined, available] = await Promise.all([skillCatalog.listSkills(), skillCatalog.getSkillCatalog()]);
+ setSkills(defined);
+ setCatalog(available);
+ } catch (err) {
+ setError(err instanceof Error ? err.message : 'Failed to load skills');
+ } finally {
+ setLoading(false);
+ }
+ }, [skillCatalog]);
+
+ useEffect(() => {
+ void refresh();
+ }, [refresh]);
+
+ const normalizedQuery = query.trim().toLowerCase();
+
+ const selectedSkills = useMemo(
+ () => skills.filter(skill => matchesQuery(normalizedQuery, skill.name, skill.description)),
+ [skills, normalizedQuery],
+ );
+
+ const availableSkills = useMemo(() => {
+ const selectedCatalogIds = new Set(skills.flatMap(skill => (isRegistrySkill(skill) ? [skill.catalogId] : [])));
+ return catalog.filter(
+ entry => !selectedCatalogIds.has(entry.id) && matchesQuery(normalizedQuery, entry.name, entry.description),
+ );
+ }, [catalog, skills, normalizedQuery]);
+
+ const runMutation = async (fn: () => Promise<void>) => {
+ setBusy(true);
+ setError(null);
+ try {
+ await fn();
+ await refresh();
+ } catch (err) {
+ setError(err instanceof Error ? err.message : 'Request failed');
+ throw err;
+ } finally {
+ setBusy(false);
+ }
+ };
+
+ if (!skillCatalog) {
+ return <p className="text-sm text-muted-foreground">Skills catalog is not available.</p>;
+ }
+
+ const handleSelect = (entry: SkillCatalogEntry) => {
+ void runMutation(async () => {
+ await skillCatalog.createSkill({
+ catalogId: entry.id,
+ name: entry.name,
+ description: entry.description,
+ repoURL: entry.repoURL,
+ path: entry.path,
+ ref: entry.ref,
+ });
+ }).catch(() => {});
+ };
+
+ const handleRemove = (skill: SkillBase) => {
+ const deleteSkill = skillCatalog.deleteSkill;
+ if (!deleteSkill) return;
+ void runMutation(async () => {
+ await deleteSkill({ id: skill.id });
+ }).catch(() => {});
+ };
+
+ const handleImport = async (draft: SkillConfigBase) => {
+ await runMutation(async () => {
+ await skillCatalog.createSkill(draft);
+ });
+ };
+
+ const renderRow = ({
+ key,
+ name,
+ description,
+ source,
+ action,
+ }: {
+ key: string;
+ name: string;
+ description: string;
+ source: 'registry' | 'github';
+ action: ReactNode;
+ }) => (
+ <article key={key} className="flex min-h-16 items-center gap-3 border-b border-border p-3 last:border-b-0">
+ <span
+ className="flex size-9 shrink-0 items-center justify-center rounded-lg border border-border bg-muted"
+ aria-hidden
+ >
+ <Icon name="lightbulb" className="size-4.5 text-foreground" />
+ </span>
+
+ <div className="min-w-0 flex-1">
+ <div className="flex items-center gap-2">
+ <h5 className="truncate text-sm font-medium text-foreground">{name}</h5>
+ <span className="inline-flex shrink-0 items-center gap-1 rounded-full border border-border bg-muted/40 px-2 py-0.5 text-xs font-medium text-muted-foreground">
+ {source === 'github' ? (
+ <>
+ <Icon name="github" className="size-3" />
+ GitHub
+ </>
+ ) : (
+ 'Registry'
+ )}
+ </span>
+ </div>
+ {description ? <p className="mt-0.5 truncate text-sm text-muted-foreground">{description}</p> : null}
+ </div>
+
+ {action}
+ </article>
+ );
+
+ const hasMatches = selectedSkills.length > 0 || availableSkills.length > 0;
+
+ return (
+ <>
+ <h3 className="text-xl font-semibold tracking-tight text-foreground">Skills</h3>
+ <p className="mt-1 text-sm text-muted-foreground">Use built-in skills or import custom skills from GitHub.</p>
+
+ {error ? (
+ <p className="mt-3 rounded-md border border-destructive/30 bg-destructive/10 px-3 py-2 text-sm text-destructive">
+ {error}
+ </p>
+ ) : null}
+
+ <div className="mt-4 flex min-h-0 flex-1 flex-col gap-3">
+ <div className="flex flex-col gap-2 sm:flex-row">
+ <div className="min-w-0 flex-1">
+ <SearchInput query={query} setQuery={setQuery} placeholder="Search skills" />
+ </div>
+ <Button
+ variant="secondary"
+ type="button"
+ className="shrink-0"
+ disabled={busy}
+ onClick={() => {
+ setImportOpen(true);
+ }}
+ >
+ <Icon name="github" className="size-4" />
+ Import from GitHub
+ </Button>
+ </div>
+
+ <div className="flex flex-1 flex-col gap-5 overflow-y-auto pb-1">
+ {loading ? <p className="py-8 text-center text-sm text-muted-foreground">Loading…</p> : null}
+
+ {!loading && selectedSkills.length > 0 ? (
+ <section aria-labelledby="selected-skills-heading">
+ <h4
+ id="selected-skills-heading"
+ className="mb-2 text-[0.8125rem] font-semibold uppercase text-muted-foreground"
+ >
+ Selected · {selectedSkills.length}
+ </h4>
+ <div className="overflow-hidden rounded-xl border border-border bg-card">
+ {selectedSkills.map(skill =>
+ renderRow({
+ key: skill.id,
+ name: skill.name,
+ description: skill.description,
+ source: isRegistrySkill(skill) ? 'registry' : 'github',
+ action: skillCatalog.deleteSkill ? (
+ <Button
+ variant="outline"
+ size="sm"
+ type="button"
+ disabled={busy}
+ aria-label={`Remove ${skill.name}`}
+ onClick={() => {
+ handleRemove(skill);
+ }}
+ >
+ Remove
+ </Button>
+ ) : null,
+ }),
+ )}
+ </div>
+ </section>
+ ) : null}
+
+ {!loading && availableSkills.length > 0 ? (
+ <section aria-labelledby="available-skills-heading">
+ <h4
+ id="available-skills-heading"
+ className="mb-2 text-[0.8125rem] font-semibold uppercase text-muted-foreground"
+ >
+ Available · {availableSkills.length}
+ </h4>
+ <div className="overflow-hidden rounded-xl border border-border bg-card">
+ {availableSkills.map(entry =>
+ renderRow({
+ key: entry.id,
+ name: entry.name,
+ description: entry.description,
+ source: 'registry',
+ action: (
+ <Button
+ variant="outline"
+ size="sm"
+ type="button"
+ disabled={busy}
+ aria-label={`Select ${entry.name}`}
+ onClick={() => {
+ handleSelect(entry);
+ }}
+ >
+ Select
+ </Button>
+ ),
+ }),
+ )}
+ </div>
+ </section>
+ ) : null}
+
+ {!loading && !hasMatches ? (
+ <div className="flex flex-1 items-center justify-center rounded-xl border border-dashed border-border p-8 text-center text-sm text-muted-foreground">
+ {normalizedQuery ? `No skills match “${query.trim()}”.` : 'No skills yet.'}
+ </div>
+ ) : null}
+ </div>
+ </div>
+
+ <ImportGithubSkillForm open={importOpen} onOpenChange={setImportOpen} onImport={handleImport} busy={busy} />
+ </>
+ );
+};
+
+export default SkillSettings;
diff --git a/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/index.tsx b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/index.tsx
new file mode 100644
index 000000000..2acf28540
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/SettingsBuilder/index.tsx
@@ -0,0 +1,125 @@
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+
+import { auiButtonClass } from '@/atoms/lib/buttonClasses.js';
+import { cn } from '@/atoms/lib/cn.js';
+import { Icon } from '@/icons/Icon.js';
+import { useOptionalCatalogServer } from '@/server/ServerContext.js';
+import { useShellMode } from '@/server/ShellModeContext.js';
+import ConnectorSettings from './ConnectorSettings.js';
+import ModelSettings from './ModelSettings.js';
+import SandboxSettings from './SandboxSettings.js';
+import SkillSettings from './SkillSettings.js';
+
+type SettingsSection = 'models' | 'connectors' | 'skills' | 'sandbox';
+
+const TruefoundrySettingsBuilder = () => {
+ const { settingsOpen, setSettingsOpen } = useShellMode();
+ const catalog = useOptionalCatalogServer();
+ const [section, setSection] = useState<SettingsSection>('models');
+
+ const hasSkills = catalog?.skillCatalog != null;
+ const hasSandbox = catalog?.sandboxCatalog != null;
+
+ useEffect(() => {
+ if (!hasSkills && section === 'skills') {
+ setSection('models');
+ }
+ if (!hasSandbox && section === 'sandbox') {
+ setSection('models');
+ }
+ }, [hasSkills, hasSandbox, section]);
+
+ useEffect(() => {
+ if (!settingsOpen) return;
+ const onKeyDown = (event: KeyboardEvent) => {
+ if (event.key !== 'Escape') return;
+ event.stopImmediatePropagation();
+ setSettingsOpen(false);
+ };
+ // Capture so layout Escape handlers (sessions drawer / widget) do not also fire.
+ window.addEventListener('keydown', onKeyDown, true);
+ return () => window.removeEventListener('keydown', onKeyDown, true);
+ }, [settingsOpen, setSettingsOpen]);
+
+ const sections = useMemo<
+ Array<{
+ id: SettingsSection;
+ label: string;
+ icon: 'cpu' | 'plug' | 'lightbulb' | 'cube';
+ }>
+ >(() => {
+ const baseSections: Array<{
+ id: SettingsSection;
+ label: string;
+ icon: 'cpu' | 'plug' | 'lightbulb' | 'cube';
+ }> = [
+ { id: 'models', label: 'Models', icon: 'cpu' },
+ { id: 'connectors', label: 'Connectors', icon: 'plug' },
+ ];
+ if (hasSkills) {
+ baseSections.push({ id: 'skills', label: 'Skills', icon: 'lightbulb' });
+ }
+ if (hasSandbox) {
+ baseSections.push({ id: 'sandbox', label: 'Sandbox', icon: 'cube' });
+ }
+ return baseSections;
+ }, [hasSkills, hasSandbox]);
+
+ if (!settingsOpen || !catalog) return null;
+
+ return (
+ <div className="flex h-full min-h-0 w-full flex-col bg-background">
+ <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={() => setSettingsOpen(false)}
+ >
+ <Icon name="arrow-left" />
+ </button>
+ <h1 className="text-lg font-semibold tracking-tight text-foreground">Settings</h1>
+ </header>
+
+ <div className="flex min-h-0 flex-1 flex-col md:flex-row">
+ <nav
+ aria-label="Settings sections"
+ className="flex w-full justify-center gap-1 border-b border-border bg-muted/30 p-2 md:w-48 md:flex-col md:justify-start md:border-b-0 md:border-r"
+ >
+ {sections.map(item => (
+ <button
+ key={item.id}
+ type="button"
+ aria-current={section === item.id ? 'page' : undefined}
+ className={cn(
+ 'flex min-h-9 shrink-0 items-center gap-2 rounded-md px-3 text-sm font-medium transition-colors',
+ 'focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring',
+ section === item.id
+ ? 'bg-accent text-accent-foreground'
+ : 'text-muted-foreground hover:bg-accent/50 hover:text-foreground',
+ )}
+ onClick={() => {
+ setSection(item.id);
+ }}
+ >
+ <Icon name={item.icon} className="h-4 w-4" />
+ {item.label}
+ </button>
+ ))}
+ </nav>
+
+ <section className="flex h-full flex-1 flex-col overflow-y-hidden px-6 py-4">
+ {section === 'models' && <ModelSettings />}
+ {section === 'connectors' && <ConnectorSettings />}
+ {section === 'skills' && hasSkills ? <SkillSettings /> : null}
+ {section === 'sandbox' && hasSandbox ? <SandboxSettings /> : null}
+ </section>
+ </div>
+ </div>
+ );
+};
+
+export default TruefoundrySettingsBuilder;
diff --git a/packages/trueforge-ui-sdk/src/containers/Thread.tsx b/packages/trueforge-ui-sdk/src/containers/Thread.tsx
new file mode 100644
index 000000000..7c00a6949
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/Thread.tsx
@@ -0,0 +1,9 @@
+'use client';
+
+import { ComposerContainer } from './ComposerContainer.js';
+import { ThreadContainer } from './ThreadContainer.js';
+
+/** The full assembled thread view: message list + composer. */
+export function Thread() {
+ return <ThreadContainer composer={<ComposerContainer />} />;
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/ThreadContainer.test.tsx b/packages/trueforge-ui-sdk/src/containers/ThreadContainer.test.tsx
new file mode 100644
index 000000000..e718a196c
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ThreadContainer.test.tsx
@@ -0,0 +1,109 @@
+// @vitest-environment jsdom
+import type { AssistantState, ThreadMessageLike } from '@assistant-ui/react';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { ShellModeProvider } from '../server/ShellModeContext.js';
+import { RuntimeHarness } from './RuntimeHarness.js';
+import { isNewChatView, ThreadContainer } from './ThreadContainer.js';
+
+function renderThread(
+ messages: ThreadMessageLike[],
+ options?: { isLoading?: boolean; composer?: React.ReactNode; agentName?: string },
+) {
+ const thread = (
+ <RuntimeHarness messages={messages} isLoading={options?.isLoading}>
+ <ThreadContainer composer={options?.composer} />
+ </RuntimeHarness>
+ );
+ return render(
+ options?.agentName != null ? (
+ <ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: options.agentName }}>{thread}</ShellModeProvider>
+ ) : (
+ thread
+ ),
+ );
+}
+
+function emptyThreadState(
+ overrides: {
+ isLoading?: boolean;
+ threadsIsLoading?: boolean;
+ remoteId?: string | undefined;
+ } = {},
+): AssistantState {
+ return {
+ thread: {
+ messages: [],
+ isLoading: overrides.isLoading ?? false,
+ },
+ threads: {
+ isLoading: overrides.threadsIsLoading ?? false,
+ },
+ threadListItem: {
+ remoteId: overrides.remoteId,
+ },
+ } as unknown as AssistantState;
+}
+
+describe('isNewChatView', () => {
+ it('is true for a brand-new empty thread with no session', () => {
+ expect(isNewChatView(emptyThreadState())).toBe(true);
+ });
+
+ it('is false while an established session briefly has zero messages (first-turn edit/retry rewind)', () => {
+ expect(isNewChatView(emptyThreadState({ remoteId: 'sess-1' }))).toBe(false);
+ });
+
+ it('is false while thread history is loading (and threads list is idle)', () => {
+ expect(isNewChatView(emptyThreadState({ isLoading: true }))).toBe(false);
+ });
+});
+
+describe('ThreadContainer', () => {
+ it('renders the welcome screen for a new, empty thread', () => {
+ renderThread([]);
+ expect(screen.getByText('How can I help you today?')).toBeInTheDocument();
+ });
+
+ it('shows the agent name on the empty named-agent welcome screen', () => {
+ renderThread([], { agentName: 'support-agent' });
+ expect(screen.getByText('support-agent')).toBeInTheDocument();
+ expect(screen.queryByText('How can I help you today?')).not.toBeInTheDocument();
+ });
+
+ it('renders the loading skeleton while thread history is loading', () => {
+ renderThread([], { isLoading: true });
+ expect(screen.getByRole('status', { name: 'Loading conversation' })).toBeInTheDocument();
+ expect(screen.queryByText('How can I help you today?')).not.toBeInTheDocument();
+ });
+
+ it('renders the message list once loaded and non-empty', () => {
+ renderThread([
+ { role: 'user', content: 'hi' },
+ { role: 'assistant', content: 'hello there' },
+ ]);
+ expect(screen.getByText('hello there')).toBeInTheDocument();
+ expect(screen.queryByText('How can I help you today?')).not.toBeInTheDocument();
+ });
+
+ it('renders the supplied composer slot', () => {
+ renderThread([{ role: 'user', content: 'hi' }], {
+ composer: <div data-testid="composer-slot" />,
+ });
+ expect(screen.getByTestId('composer-slot')).toBeInTheDocument();
+ });
+
+ it('centers the composer in the viewport on an empty thread', () => {
+ renderThread([], { composer: <div data-testid="composer-slot" /> });
+ const composer = screen.getByTestId('composer-slot');
+ expect(composer).toBeInTheDocument();
+ expect(composer.closest('[data-slot="aui_thread-viewport"]')).not.toBeNull();
+ expect(composer.closest('[data-slot="aui_thread-composer"]')).toBeNull();
+ });
+
+ it('omits the composer area entirely while loading', () => {
+ renderThread([], { isLoading: true, composer: <div data-testid="composer-slot" /> });
+ expect(screen.queryByTestId('composer-slot')).not.toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/ThreadContainer.tsx b/packages/trueforge-ui-sdk/src/containers/ThreadContainer.tsx
new file mode 100644
index 000000000..15fededcd
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ThreadContainer.tsx
@@ -0,0 +1,103 @@
+'use client';
+
+import { ThreadPrimitive, useAuiState, type AssistantState } from '@assistant-ui/react';
+import { useEffect, type ReactNode } from 'react';
+import { preloadMarkdownOpenUI } from '../atoms/Markdown.js';
+import { ComposerBusyProvider } from '../hooks/useComposerBusyState.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+import { AssistantMessageContainer } from './AssistantMessageContainer.js';
+import { HistoryLoaderContainer } from './HistoryLoaderContainer.js';
+import { UserEditComposerContainer } from './UserEditComposerContainer.js';
+import { UserMessageContainer } from './UserMessageContainer.js';
+
+// Startup exposes a loading placeholder thread; treat it as a new chat so the
+// composer mounts centered. Loads after startup keep the docked layout.
+//
+// `remoteId == null` keeps welcome off during first-turn edit/retry: the
+// runtime briefly rewinds to an empty snapshot before applying pendingUser,
+// and messages.length===0 alone would flash the welcome screen.
+export const isNewChatView = (s: AssistantState) =>
+ s.thread.messages.length === 0 && (!s.thread.isLoading || s.threads.isLoading) && s.threadListItem.remoteId == null;
+
+/** Mount-only lift. Keyed by message.id via ThreadPrimitive.Messages — not content (streaming). */
+function AnimatedMessageShell({ children }: { children: ReactNode }) {
+ return <div className="animate-in fade-in slide-in-from-bottom-1 fill-mode-both duration-200">{children}</div>;
+}
+
+function ThreadMessage({ isEditing }: { isEditing: boolean }) {
+ const role = useAuiState(s => s.message.role);
+ if (role === 'user') {
+ if (isEditing) {
+ return <UserEditComposerContainer />;
+ }
+ return <UserMessageContainer />;
+ }
+ return <AssistantMessageContainer />;
+}
+
+export type ThreadContainerProps = {
+ /** Composer for the empty-welcome and docked bottom areas. `<Thread />` passes `<ComposerContainer />`. */
+ composer?: ReactNode;
+};
+
+export function ThreadContainer({ composer }: ThreadContainerProps) {
+ useEffect(() => {
+ void preloadMarkdownOpenUI();
+ }, []);
+
+ const shell = useOptionalShellMode();
+ const WelcomeScreen = useSlot('WelcomeScreen');
+ const MessageListSkeleton = useSlot('MessageListSkeleton');
+ const ScrollToBottomButton = useSlot('ScrollToBottomButton');
+ const MessageGroup = useSlot('MessageGroup');
+ const ThreadComposerAreaShell = useSlot('ThreadComposerAreaShell');
+ const ThreadRootShell = useSlot('ThreadRootShell');
+ const ThreadViewportShell = useSlot('ThreadViewportShell');
+
+ const isEmpty = useAuiState(isNewChatView);
+ const isLoading = useAuiState(s => s.thread.isLoading);
+ const welcomeHeading = shell?.mode.type === 'named' ? shell.mode.agentName : undefined;
+
+ return (
+ <ComposerBusyProvider>
+ <ThreadPrimitive.Root asChild>
+ <ThreadRootShell>
+ <ThreadPrimitive.Viewport asChild autoScroll>
+ <ThreadViewportShell isEmpty={isEmpty}>
+ {isEmpty && <WelcomeScreen heading={welcomeHeading} />}
+ {isEmpty && !isLoading && composer}
+ {isLoading ? (
+ <MessageListSkeleton />
+ ) : (
+ !isEmpty && (
+ <>
+ <HistoryLoaderContainer />
+ <MessageGroup>
+ <ThreadPrimitive.Messages>
+ {({ message }) => (
+ <AnimatedMessageShell>
+ <ThreadMessage isEditing={message.role === 'user' && message.composer.isEditing} />
+ </AnimatedMessageShell>
+ )}
+ </ThreadPrimitive.Messages>
+ </MessageGroup>
+ </>
+ )
+ )}
+ </ThreadViewportShell>
+ </ThreadPrimitive.Viewport>
+
+ {!isLoading && !isEmpty && (
+ <ThreadComposerAreaShell isEmpty={isEmpty}>
+ <ThreadPrimitive.ScrollToBottom asChild>
+ <ScrollToBottomButton />
+ </ThreadPrimitive.ScrollToBottom>
+ {composer}
+ </ThreadComposerAreaShell>
+ )}
+ </ThreadRootShell>
+ </ThreadPrimitive.Root>
+ </ComposerBusyProvider>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/ThreadListContainer.tsx b/packages/trueforge-ui-sdk/src/containers/ThreadListContainer.tsx
new file mode 100644
index 000000000..4ad333e38
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ThreadListContainer.tsx
@@ -0,0 +1,210 @@
+'use client';
+
+import {
+ ThreadListItemMorePrimitive,
+ ThreadListItemPrimitive,
+ ThreadListPrimitive,
+ useAui,
+ useAuiState,
+} from '@assistant-ui/react';
+import { useEffect, useRef, useState, type ReactNode } from 'react';
+
+import { auiButtonClass } from '../atoms/lib/buttonClasses.js';
+import { cn } from '../atoms/lib/cn.js';
+import { useCompactLayout } from '../atoms/lib/CompactLayoutContext.js';
+import { useIsMobile } from '../atoms/lib/useIsMobile.js';
+import { BottomSheet } from '../atoms/primitives/BottomSheet.js';
+import { Icon } from '../icons/Icon.js';
+import { useOptionalServer } from '../server/ServerContext.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+
+/**
+ * Simplified relative to the reference: renders threads in a single flat list
+ * rather than grouping them by Today/Yesterday/Earlier.
+ *
+ * Delete uses assistant-ui ThreadListItemPrimitive.Delete / ThreadListItemMorePrimitive
+ * (adapter.delete → server.deleteSession). Mobile/compact keeps a BottomSheet chrome.
+ */
+export type ThreadListContainerProps = {
+ /** Called after New chat or selecting a row — used by stack/drawer chrome. */
+ onThreadOpen?: () => void;
+};
+
+const deleteItemClass =
+ 'flex w-full cursor-pointer select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none text-destructive hover:bg-accent hover:text-destructive focus:bg-accent focus:text-destructive data-[highlighted]:bg-accent data-[highlighted]:text-destructive';
+
+function ThreadListItemDeleteMenu() {
+ const compact = useCompactLayout();
+ const isMobile = useIsMobile();
+ const [sheetOpen, setSheetOpen] = useState(false);
+ const useSheet = isMobile || compact;
+
+ const moreButtonClass = auiButtonClass({
+ variant: 'ghost',
+ size: 'icon',
+ className: cn(
+ 'size-7 shrink-0 text-muted-foreground hover:bg-transparent hover:text-foreground',
+ 'opacity-100 transition-opacity',
+ !compact && 'md:opacity-0 md:group-hover:opacity-100 md:group-focus-within:opacity-100',
+ 'focus-visible:opacity-100 data-[state=open]:opacity-100',
+ ),
+ });
+
+ if (useSheet) {
+ return (
+ <>
+ <button
+ type="button"
+ aria-label="Session actions"
+ title="Session actions"
+ aria-haspopup="dialog"
+ aria-expanded={sheetOpen}
+ className={moreButtonClass}
+ onClick={() => setSheetOpen(true)}
+ >
+ <Icon name="ellipsis" className="size-3.5" />
+ </button>
+ {sheetOpen ? (
+ <BottomSheet open onOpenChange={setSheetOpen} aria-label="Session actions">
+ <div className="flex flex-col gap-1 p-2" role="menu">
+ <ThreadListItemPrimitive.Delete className={deleteItemClass} onClick={() => setSheetOpen(false)}>
+ <Icon name="trash" className="size-3.5" />
+ Delete
+ </ThreadListItemPrimitive.Delete>
+ </div>
+ </BottomSheet>
+ ) : null}
+ </>
+ );
+ }
+
+ return (
+ <ThreadListItemMorePrimitive.Root sharedFocusGroup>
+ <ThreadListItemMorePrimitive.Trigger
+ aria-label="Session actions"
+ title="Session actions"
+ className={moreButtonClass}
+ >
+ <Icon name="ellipsis" className="size-3.5" />
+ </ThreadListItemMorePrimitive.Trigger>
+ <ThreadListItemMorePrimitive.Content
+ align="end"
+ sideOffset={4}
+ className="z-50 min-w-[8rem] rounded-md border border-border bg-popover p-1 text-popover-foreground shadow-md"
+ >
+ <ThreadListItemPrimitive.Delete asChild>
+ <ThreadListItemMorePrimitive.Item className={deleteItemClass}>
+ <Icon name="trash" className="size-3.5" />
+ Delete
+ </ThreadListItemMorePrimitive.Item>
+ </ThreadListItemPrimitive.Delete>
+ </ThreadListItemMorePrimitive.Content>
+ </ThreadListItemMorePrimitive.Root>
+ );
+}
+
+function ThreadListItemRow({ onThreadOpen, showDelete }: { onThreadOpen?: () => void; showDelete: boolean }) {
+ const aui = useAui();
+ const ThreadListRow = useSlot('ThreadListRow');
+ const id = useAuiState(s => s.threadListItem.id);
+ const title = useAuiState(s => s.threadListItem.title);
+ const mainThreadId = useAuiState(s => s.threads.mainThreadId);
+
+ return (
+ <ThreadListItemPrimitive.Root className="min-w-0">
+ <ThreadListRow
+ title={title ?? 'New Chat'}
+ active={id === mainThreadId}
+ onSelect={() => {
+ onThreadOpen?.();
+ void Promise.resolve(aui.threads().switchToThread(id)).catch(() => undefined);
+ }}
+ actions={showDelete ? <ThreadListItemDeleteMenu /> : undefined}
+ />
+ </ThreadListItemPrimitive.Root>
+ );
+}
+
+export function ThreadListContainer({ onThreadOpen }: ThreadListContainerProps = {}) {
+ const aui = useAui();
+ const server = useOptionalServer();
+ const isLoading = useAuiState(s => s.threads.isLoading);
+ const isLoadingMore = useAuiState(s => s.threads.isLoadingMore);
+ const hasMore = useAuiState(s => s.threads.hasMore);
+ const threadIds = useAuiState(s => s.threads.threadIds);
+ const shell = useOptionalShellMode();
+
+ const ThreadListShell = useSlot('ThreadListShell');
+ const ThreadListNewButton = useSlot('ThreadListNewButton');
+ const AgentsLibraryButton = useSlot('AgentsLibraryButton');
+ const ThreadListRowSkeleton = useSlot('ThreadListRowSkeleton');
+ const ThreadListEmptyState = useSlot('ThreadListEmptyState');
+
+ const sentinelRef = useRef<HTMLDivElement>(null);
+ const showNewChat = shell?.isNewChatEnabled !== false;
+ const isIdle = shell?.mode.type === 'idle';
+ const canDeleteSession = typeof server?.deleteSession === 'function';
+
+ useEffect(() => {
+ const node = sentinelRef.current;
+ if (!node || !hasMore || isIdle) return;
+
+ const observer = new IntersectionObserver(entries => {
+ if (entries.some(e => e.isIntersecting) && hasMore && !isLoadingMore) {
+ void aui.threads().loadMore();
+ }
+ });
+ observer.observe(node);
+ return () => observer.disconnect();
+ }, [aui, hasMore, isLoadingMore, isIdle]);
+
+ const handleNewChat = () => {
+ onThreadOpen?.();
+ if (shell?.isComposerEnabled) {
+ shell.openDraft();
+ return;
+ }
+ void Promise.resolve(aui.threads().switchToNewThread()).catch(() => undefined);
+ };
+
+ let listBody: ReactNode;
+ if (isIdle) {
+ listBody = <ThreadListEmptyState />;
+ } else if (isLoading) {
+ listBody = <ThreadListRowSkeleton />;
+ } else if (threadIds.length === 0) {
+ listBody = <ThreadListEmptyState />;
+ } else {
+ listBody = (
+ <ThreadListPrimitive.Root className="flex min-h-0 flex-col gap-0.5">
+ <ThreadListPrimitive.Items>
+ {({ threadListItem }) => (
+ <ThreadListItemRow
+ onThreadOpen={onThreadOpen}
+ showDelete={canDeleteSession && threadListItem.remoteId != null}
+ />
+ )}
+ </ThreadListPrimitive.Items>
+ </ThreadListPrimitive.Root>
+ );
+ }
+
+ return (
+ <ThreadListShell
+ header={
+ <div className="flex flex-col gap-1">
+ {showNewChat ? <ThreadListNewButton onClick={handleNewChat} /> : null}
+ <AgentsLibraryButton
+ onSelectAgent={() => {
+ onThreadOpen?.();
+ }}
+ />
+ </div>
+ }
+ >
+ {listBody}
+ {!isIdle && hasMore ? <div ref={sentinelRef} className="h-4 shrink-0" aria-hidden /> : null}
+ </ThreadListShell>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/ToolApprovalContainer.tsx b/packages/trueforge-ui-sdk/src/containers/ToolApprovalContainer.tsx
new file mode 100644
index 000000000..ff698477e
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ToolApprovalContainer.tsx
@@ -0,0 +1,90 @@
+'use client';
+
+import { useCallback, useMemo, useState } from 'react';
+
+import type { ApprovalOption } from '../atoms/ToolApprovalBar.js';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+
+export type ToolApprovalOption = {
+ id: string;
+ label: string;
+ isAllow: boolean;
+ grants?: readonly string[];
+ confirm?: {
+ title?: string;
+ description?: string;
+ };
+};
+
+type ToolApprovalContainerProps = {
+ toolName?: string;
+ options: ToolApprovalOption[];
+ onSelectOption: (optionId: string, reason?: string) => void;
+};
+
+export function ToolApprovalContainer({ toolName = '', options, onSelectOption }: ToolApprovalContainerProps) {
+ const ToolApprovalBar = useSlot('ToolApprovalBar');
+ const [selectedDenyOptionId, setSelectedDenyOptionId] = useState<string | null>(null);
+ const [denialReason, setDenialReason] = useState('');
+ const [showReasonError, setShowReasonError] = useState(false);
+ const approveOptions = useMemo<ApprovalOption[]>(
+ () =>
+ options
+ .filter(option => option.isAllow)
+ .map((option, index) => ({
+ ...option,
+ variant: index === 0 ? 'primary' : 'secondary',
+ requiresReason: false,
+ })),
+ [options],
+ );
+ const denyOptions = useMemo<ApprovalOption[]>(
+ () =>
+ options
+ .filter(option => !option.isAllow)
+ .map(option => ({
+ ...option,
+ variant: 'secondary',
+ requiresReason: option.confirm != null,
+ })),
+ [options],
+ );
+ const selectedDenyOption = denyOptions.find(option => option.id === selectedDenyOptionId);
+
+ const onDenyOptionChange = useCallback((optionId: string | null) => {
+ setSelectedDenyOptionId(optionId);
+ setDenialReason('');
+ setShowReasonError(false);
+ }, []);
+ const onDenialReasonChange = useCallback((reason: string) => {
+ setDenialReason(reason);
+ setShowReasonError(false);
+ }, []);
+ const onReasonSubmit = useCallback(() => {
+ const reason = denialReason.trim();
+ if (!reason) {
+ setShowReasonError(true);
+ return;
+ }
+ if (selectedDenyOptionId) {
+ onSelectOption(selectedDenyOptionId, reason);
+ onDenyOptionChange(null);
+ }
+ }, [denialReason, onDenyOptionChange, onSelectOption, selectedDenyOptionId]);
+
+ return (
+ <ToolApprovalBar
+ toolName={toolName}
+ approveOptions={approveOptions.length > 0 ? approveOptions : undefined}
+ denyOptions={denyOptions.length > 0 ? denyOptions : undefined}
+ selectedDenyOption={selectedDenyOption}
+ denialReason={denialReason}
+ showReasonError={showReasonError}
+ onSelect={onSelectOption}
+ onDenyOptionChange={onDenyOptionChange}
+ onDenialReasonChange={onDenialReasonChange}
+ onReasonSubmit={onReasonSubmit}
+ />
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/ToolCallContainer.test.tsx b/packages/trueforge-ui-sdk/src/containers/ToolCallContainer.test.tsx
new file mode 100644
index 000000000..f35a13fe0
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ToolCallContainer.test.tsx
@@ -0,0 +1,246 @@
+// @vitest-environment jsdom
+import { ThreadPrimitive, type ThreadMessageLike } from '@assistant-ui/react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { AssistantMessageContainer } from './AssistantMessageContainer.js';
+import { RuntimeHarness } from './RuntimeHarness.js';
+
+function renderToolCallMessage(content: ThreadMessageLike['content']) {
+ const message: ThreadMessageLike = { role: 'assistant', content };
+ return render(
+ <RuntimeHarness messages={[message]}>
+ <ThreadPrimitive.Messages>{() => <AssistantMessageContainer />}</ThreadPrimitive.Messages>
+ </RuntimeHarness>,
+ );
+}
+
+/** Pending approvals only surface part-level "requires-action" when the whole message is flagged too. */
+function renderPendingApprovalMessage(
+ content: ThreadMessageLike['content'],
+ options?: { onRespondToToolApproval?: (o: unknown) => void },
+) {
+ const message: ThreadMessageLike = {
+ role: 'assistant',
+ content,
+ status: { type: 'requires-action', reason: 'tool-calls' },
+ };
+ return render(
+ <RuntimeHarness messages={[message]} onRespondToToolApproval={options?.onRespondToToolApproval}>
+ <ThreadPrimitive.Messages>{() => <AssistantMessageContainer />}</ThreadPrimitive.Messages>
+ </RuntimeHarness>,
+ );
+}
+
+describe('ToolCallContainer', () => {
+ it('renders a running tool call without a result', () => {
+ renderToolCallMessage([{ type: 'tool-call', toolCallId: '1', toolName: 'search_docs', args: {} }]);
+ expect(screen.getByText('search_docs')).toBeInTheDocument();
+ expect(screen.queryByText('Result:')).not.toBeInTheDocument();
+ });
+
+ it('renders args and result for a completed tool call once expanded', () => {
+ renderToolCallMessage([
+ {
+ type: 'tool-call',
+ toolCallId: '1',
+ toolName: 'get_current_datetime',
+ args: {},
+ argsText: '{"tz":"UTC"}',
+ result: '2026-07-01T00:00:00Z',
+ },
+ ]);
+ fireEvent.click(screen.getByText('get_current_datetime'));
+ const blocks = screen.getAllByTestId('tfy-tool-call-content-block');
+ expect(blocks[0]).toHaveAttribute('data-content', expect.stringContaining('"tz"'));
+ expect(blocks[1]).toHaveAttribute('data-content', '2026-07-01T00:00:00Z');
+ });
+
+ it('renders an error result once expanded', () => {
+ renderToolCallMessage([
+ {
+ type: 'tool-call',
+ toolCallId: '1',
+ toolName: 'flaky_tool',
+ args: {},
+ result: 'boom',
+ isError: true,
+ },
+ ]);
+ fireEvent.click(screen.getByText('flaky_tool'));
+ const blocks = screen.getAllByTestId('tfy-tool-call-content-block');
+ expect(blocks[1]).toHaveTextContent('boom');
+ });
+
+ it('auto-expands and shows the approval bar while an approval is pending', () => {
+ renderPendingApprovalMessage([
+ {
+ type: 'tool-call',
+ toolCallId: '1',
+ toolName: 'delete_file',
+ args: {},
+ interrupt: { type: 'human', payload: {} },
+ approval: { id: 'approval-1', approved: undefined },
+ },
+ ]);
+ expect(screen.getByRole('button', { name: 'Allow' })).toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Deny' })).toBeInTheDocument();
+ });
+
+ it('calls onRespondToToolApproval when Allow is clicked', () => {
+ const onRespondToToolApproval = vi.fn();
+ renderPendingApprovalMessage(
+ [
+ {
+ type: 'tool-call',
+ toolCallId: '1',
+ toolName: 'delete_file',
+ args: {},
+ interrupt: { type: 'human', payload: {} },
+ approval: { id: 'approval-1', approved: undefined },
+ },
+ ],
+ { onRespondToToolApproval },
+ );
+ fireEvent.click(screen.getByRole('button', { name: 'Allow' }));
+ expect(onRespondToToolApproval).toHaveBeenCalledWith(
+ expect.objectContaining({ approvalId: 'approval-1', approved: true }),
+ );
+ });
+
+ it('includes the denial reason when Deny is submitted', () => {
+ const onRespondToToolApproval = vi.fn();
+ renderPendingApprovalMessage(
+ [
+ {
+ type: 'tool-call',
+ toolCallId: '1',
+ toolName: 'delete_file',
+ args: {},
+ interrupt: { type: 'human', payload: {} },
+ approval: { id: 'approval-1', approved: undefined },
+ },
+ ],
+ { onRespondToToolApproval },
+ );
+ fireEvent.click(screen.getByRole('button', { name: 'Deny' }));
+ fireEvent.change(screen.getByPlaceholderText('Enter reason for denial'), {
+ target: { value: 'Denied by user' },
+ });
+ fireEvent.click(screen.getByRole('button', { name: 'Submit' }));
+ expect(onRespondToToolApproval).toHaveBeenCalledWith(
+ expect.objectContaining({
+ approvalId: 'approval-1',
+ approved: false,
+ reason: 'Denied by user',
+ }),
+ );
+ });
+
+ it('renders declared approval options with their labels', () => {
+ renderPendingApprovalMessage([
+ {
+ type: 'tool-call',
+ toolCallId: '1',
+ toolName: 'run_migration',
+ args: {},
+ interrupt: { type: 'human', payload: {} },
+ approval: {
+ id: 'approval-1',
+ approved: undefined,
+ options: [
+ { id: 'opt-allow', kind: 'allow-once' },
+ { id: 'opt-deny', kind: 'reject-once' },
+ ],
+ },
+ },
+ ]);
+ expect(screen.getByRole('button', { name: 'Allow' })).toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Deny' })).toBeInTheDocument();
+ });
+
+ it('forwards confirmation copy and grants to the denial option', () => {
+ renderPendingApprovalMessage([
+ {
+ type: 'tool-call',
+ toolCallId: '1',
+ toolName: 'run_migration',
+ args: {},
+ interrupt: { type: 'human', payload: {} },
+ approval: {
+ id: 'approval-1',
+ approved: undefined,
+ options: [
+ { id: 'opt-allow', kind: 'allow-once' },
+ {
+ id: 'opt-deny',
+ kind: 'reject-once',
+ grants: ['database:write'],
+ confirm: {
+ title: 'Confirm denial',
+ description: 'The migration will not run.',
+ },
+ },
+ ],
+ },
+ },
+ ]);
+ fireEvent.click(screen.getByRole('button', { name: 'Deny' }));
+ expect(screen.getByText('Confirm denial')).toBeInTheDocument();
+ expect(screen.getByText('The migration will not run.')).toBeInTheDocument();
+ expect(screen.getByText('database:write')).toBeInTheDocument();
+ });
+
+ it('passes mcpServerName for list_tools', () => {
+ renderToolCallMessage([
+ {
+ type: 'tool-call',
+ toolCallId: '1',
+ toolName: 'list_tools',
+ args: {},
+ argsText: '{"mcp_server":"github-team"}',
+ },
+ ]);
+ // Verify the card is rendered (actual prop checking would require slot mocking)
+ expect(screen.getByText(/Listing tools/)).toBeInTheDocument();
+ });
+
+ it('passes mcpServerName for call_tool', () => {
+ renderToolCallMessage([
+ {
+ type: 'tool-call',
+ toolCallId: '1',
+ toolName: 'call_tool',
+ args: {},
+ argsText: '{"mcp_server":"slack-workspace","tool_name":"send_message","input":{}}',
+ },
+ ]);
+ expect(screen.getByText(/call_tool: send_message/)).toBeInTheDocument();
+ });
+
+ it('passes mcpServerName for get_tool_info', () => {
+ renderToolCallMessage([
+ {
+ type: 'tool-call',
+ toolCallId: '1',
+ toolName: 'get_tool_info',
+ args: {},
+ argsText: '{"mcp_server":"linear-integration","tool_name":"create_issue"}',
+ },
+ ]);
+ expect(screen.getByText(/get_tool_info: create_issue/)).toBeInTheDocument();
+ });
+
+ it('does not pass mcpServerName for non-MCP tools', () => {
+ renderToolCallMessage([
+ {
+ type: 'tool-call',
+ toolCallId: '1',
+ toolName: 'search_docs',
+ args: {},
+ argsText: '{"query":"example"}',
+ },
+ ]);
+ expect(screen.getByText('search_docs')).toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/ToolCallContainer.tsx b/packages/trueforge-ui-sdk/src/containers/ToolCallContainer.tsx
new file mode 100644
index 000000000..30525b317
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ToolCallContainer.tsx
@@ -0,0 +1,290 @@
+'use client';
+
+import {
+ MessagePartPrimitive,
+ MessagePrimitive,
+ useToolCallElapsed,
+ type ToolApprovalResponse,
+ type ToolCallMessagePartComponent,
+ type ToolCallMessagePartProps,
+} from '@assistant-ui/react';
+import { useTrueFoundryRespondToToolApproval } from '@truefoundry/assistant-ui-runtime';
+import { useState } from 'react';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+import {
+ ASK_USER_TOOL_NAME,
+ MCP_META_TOOLS,
+ SANDBOX_TOOL_NAMES,
+ SUB_AGENT_TOOL_NAME,
+ buildApprovalOptions,
+ formatDuration,
+ getAskUserAnswerResult,
+ getJsonDisplayValue,
+ getToolResultContent,
+ hasPendingAskUserResponse,
+ hasPendingToolApproval,
+ mcpDisplayName,
+ parseAskUserQuestionArgs,
+ parseMcpToolArgs,
+ parseSandboxArgs,
+ parseSandboxResult,
+ resolveSubAgentMeta,
+ toStatus,
+} from '../utils/toolCallParsing.js';
+import { AssistantTextContainer } from './AssistantTextContainer.js';
+import { NestedApprovalBridgeContext, useNestedApprovalBridge } from './nestedApprovalBridge.js';
+import { SandboxToolCallContainer } from './SandboxToolCallContainer.js';
+import { ToolApprovalContainer } from './ToolApprovalContainer.js';
+import { ToolCallContentBlockContainer } from './ToolCallContentBlockContainer.js';
+
+function NestedSubAgentAssistantMessage() {
+ const AssistantMessageBubble = useSlot('AssistantMessageBubble');
+
+ return (
+ <div className="mb-3 min-w-0">
+ <MessagePrimitive.Root data-role="assistant">
+ <AssistantMessageBubble>
+ <MessagePrimitive.Parts
+ components={{
+ Text: AssistantTextContainer,
+ Reasoning: AssistantTextContainer,
+ tools: { Fallback: ToolCallContainer },
+ }}
+ />
+ </AssistantMessageBubble>
+ </MessagePrimitive.Root>
+ </div>
+ );
+}
+
+function ToolApprovalSlot({ part }: { part: ToolCallMessagePartProps }) {
+ const nestedBridge = useNestedApprovalBridge();
+
+ const respond = (response: ToolApprovalResponse) => {
+ if (nestedBridge) {
+ nestedBridge(response);
+ return;
+ }
+ part.respondToApproval(response);
+ };
+
+ const onSelectOption = (optionId: string, reason?: string) => {
+ if (optionId === '__allow') return respond({ approved: true });
+ if (optionId === '__deny') return respond({ approved: false, reason });
+ return respond({ optionId, reason });
+ };
+
+ return (
+ <ToolApprovalContainer
+ toolName={part.toolName}
+ options={
+ buildApprovalOptions(part.approval?.options) as import('./ToolApprovalContainer.js').ToolApprovalOption[]
+ }
+ onSelectOption={onSelectOption}
+ />
+ );
+}
+
+function RequestResponseSlots({
+ request,
+ response,
+}: {
+ request: { value: string; isJson: boolean };
+ response: { data: string; isJson: boolean };
+}) {
+ return {
+ requestSlot: request.value ? (
+ <ToolCallContentBlockContainer
+ title="Request"
+ content={request.value}
+ isJson={request.isJson}
+ maxHeight="10.5rem"
+ />
+ ) : response.data ? (
+ <ToolCallContentBlockContainer title="Request" content="{}" isJson maxHeight="10.5rem" />
+ ) : undefined,
+ responseSlot: response.data ? (
+ <ToolCallContentBlockContainer title="Response" content={response.data} isJson={response.isJson} resizable />
+ ) : undefined,
+ };
+}
+
+export const ToolCallContainer: ToolCallMessagePartComponent = part => {
+ const ToolCallCard = useSlot('ToolCallCard');
+ const SubAgentCard = useSlot('SubAgentCard');
+ const AskUserPrompt = useSlot('AskUserPrompt');
+ const respondToNestedApproval = useTrueFoundryRespondToToolApproval();
+ const elapsedMs = useToolCallElapsed();
+ const isRequiresAction = part.status?.type === 'requires-action';
+ const isSubAgent = part.toolName === SUB_AGENT_TOOL_NAME;
+ const isSandbox = SANDBOX_TOOL_NAMES.has(part.toolName);
+ const [expanded, setExpanded] = useState(isRequiresAction);
+ const [prevRequiresAction, setPrevRequiresAction] = useState(isRequiresAction);
+ if (isRequiresAction !== prevRequiresAction) {
+ setPrevRequiresAction(isRequiresAction);
+ if (isRequiresAction) setExpanded(true);
+ }
+
+ const showApproval = isRequiresAction && hasPendingToolApproval(part.approval);
+
+ const durationText = elapsedMs === undefined ? undefined : formatDuration(elapsedMs);
+ const status = toStatus(part.status?.type);
+ const onToggle = () => setExpanded(prev => !prev);
+
+ if (part.toolName === ASK_USER_TOOL_NAME) {
+ if (hasPendingAskUserResponse(part)) {
+ return null;
+ }
+ const answer = getAskUserAnswerResult(part.result);
+ if (answer == null) {
+ return null;
+ }
+ const { question, options = [] } = parseAskUserQuestionArgs(part.argsText);
+ const isCustom = options.length > 0 && !options.includes(answer);
+ return (
+ <AskUserPrompt
+ questions={[]}
+ answeredQuestions={[
+ {
+ id: part.toolCallId,
+ question: question ?? 'Question',
+ options,
+ answer,
+ isCustom,
+ },
+ ]}
+ onSubmit={() => {}}
+ readOnly
+ />
+ );
+ }
+
+ if (isSubAgent) {
+ const { agentName, instruction, stepCount } = resolveSubAgentMeta(part);
+
+ const bridge = (response: ToolApprovalResponse) => {
+ if (part.approval == null) return;
+ const approved = 'approved' in response ? response.approved : undefined;
+ if (approved === undefined) return;
+ respondToNestedApproval({ approvalId: part.approval.id, approved });
+ };
+
+ return (
+ <div data-slot="tool-call-card" data-variant="sub-agent" className="w-full">
+ <SubAgentCard
+ status={status}
+ expanded={expanded}
+ onToggle={onToggle}
+ durationText={durationText}
+ agentName={agentName}
+ instruction={instruction}
+ stepCount={stepCount}
+ >
+ <NestedApprovalBridgeContext.Provider value={bridge}>
+ <MessagePartPrimitive.Messages
+ components={{
+ AssistantMessage: NestedSubAgentAssistantMessage,
+ UserMessage: () => null,
+ }}
+ />
+ </NestedApprovalBridgeContext.Provider>
+ </SubAgentCard>
+ </div>
+ );
+ }
+
+ const resultString =
+ part.result === undefined
+ ? undefined
+ : typeof part.result === 'string'
+ ? part.result
+ : JSON.stringify(part.result, null, 2);
+
+ if (isSandbox) {
+ const { command, intent, argsJson } = parseSandboxArgs(part.argsText);
+ const { exitCode, resultText, resultJson } = parseSandboxResult(resultString);
+ return (
+ <SandboxToolCallContainer
+ name={part.toolName}
+ intent={intent}
+ status={status}
+ expanded={expanded}
+ onToggle={onToggle}
+ durationText={durationText}
+ command={command}
+ exitCode={exitCode}
+ argsJson={argsJson}
+ resultText={resultText}
+ resultJson={resultJson}
+ />
+ );
+ }
+
+ if (MCP_META_TOOLS.has(part.toolName)) {
+ const { mcpServer, innerToolName, input } = parseMcpToolArgs(part.argsText);
+ const argsDisplay = getJsonDisplayValue(part.argsText);
+ const resultDisplay = getToolResultContent(part.result);
+
+ if (part.toolName === 'list_tools' && mcpServer) {
+ const slots = RequestResponseSlots({
+ request: argsDisplay,
+ response: resultDisplay,
+ });
+ return (
+ <ToolCallCard
+ toolName={`Listing tools · ${mcpServer}`}
+ icon="mcp-server"
+ expanded={expanded}
+ onToggle={onToggle}
+ awaiting={status === 'running'}
+ awaitingText={durationText ?? 'Awaiting Response…'}
+ showResponseLine={status !== 'running' && !!resultDisplay.data}
+ mcpServerName={mcpServer}
+ {...slots}
+ />
+ );
+ }
+
+ const inputDisplay = input !== undefined ? getJsonDisplayValue(JSON.stringify(input, null, 2)) : argsDisplay;
+ const slots = RequestResponseSlots({
+ request: inputDisplay,
+ response: resultDisplay,
+ });
+
+ return (
+ <ToolCallCard
+ toolName={mcpDisplayName(part.toolName, mcpServer, innerToolName)}
+ icon="mcp-server"
+ expanded={expanded}
+ onToggle={onToggle}
+ awaiting={status === 'running'}
+ awaitingText={durationText ?? 'Awaiting Response…'}
+ showResponseLine={status !== 'running' && resultDisplay.data !== undefined}
+ mcpServerName={mcpServer}
+ {...slots}
+ approvalSlot={showApproval ? <ToolApprovalSlot part={part} /> : undefined}
+ />
+ );
+ }
+
+ const argsDisplay = getJsonDisplayValue(part.argsText);
+ const resultDisplay = getToolResultContent(part.result);
+ const slots = RequestResponseSlots({
+ request: argsDisplay,
+ response: resultDisplay,
+ });
+
+ return (
+ <ToolCallCard
+ toolName={part.toolName}
+ expanded={expanded}
+ onToggle={onToggle}
+ awaiting={status === 'running'}
+ awaitingText={durationText ?? 'Awaiting Response…'}
+ showResponseLine={status !== 'running' && resultDisplay.data !== undefined}
+ {...slots}
+ approvalSlot={showApproval ? <ToolApprovalSlot part={part} /> : undefined}
+ />
+ );
+};
diff --git a/packages/trueforge-ui-sdk/src/containers/ToolCallContentBlockContainer.tsx b/packages/trueforge-ui-sdk/src/containers/ToolCallContentBlockContainer.tsx
new file mode 100644
index 000000000..168fe349c
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ToolCallContentBlockContainer.tsx
@@ -0,0 +1,44 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { ToolCallContentBlockProps } from '../atoms/ToolCallContentBlock.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+
+export function ToolCallContentBlockContainer(props: ToolCallContentBlockProps) {
+ const ToolCallContentBlock = useSlot('ToolCallContentBlock');
+ const [fullscreen, setFullscreen] = useState(false);
+ const [contentHeightRem, setContentHeightRem] = useState(1.5);
+ const observerRef = useRef<ResizeObserver | null>(null);
+
+ const contentRef = useCallback(
+ (node: HTMLDivElement | null) => {
+ observerRef.current?.disconnect();
+ observerRef.current = null;
+ if (!props.resizable || node == null) return;
+
+ const updateHeight = () => setContentHeightRem(node.scrollHeight / 16);
+ updateHeight();
+ observerRef.current = new ResizeObserver(updateHeight);
+ observerRef.current.observe(node);
+ },
+ [props.resizable],
+ );
+
+ useEffect(
+ () => () => {
+ observerRef.current?.disconnect();
+ },
+ [],
+ );
+
+ return (
+ <ToolCallContentBlock
+ {...props}
+ fullscreen={fullscreen}
+ onFullscreenChange={setFullscreen}
+ contentHeightRem={contentHeightRem}
+ contentRef={contentRef}
+ />
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/ToolGroupContainer.test.tsx b/packages/trueforge-ui-sdk/src/containers/ToolGroupContainer.test.tsx
new file mode 100644
index 000000000..9bd1b0432
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ToolGroupContainer.test.tsx
@@ -0,0 +1,67 @@
+// @vitest-environment jsdom
+import { ThreadPrimitive, type ThreadMessageLike } from '@assistant-ui/react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { AssistantMessageContainer } from './AssistantMessageContainer.js';
+import { RuntimeHarness } from './RuntimeHarness.js';
+
+function renderMultiToolMessage(content: ThreadMessageLike['content'], isRunning = false) {
+ const message: ThreadMessageLike = { role: 'assistant', content };
+ return render(
+ <RuntimeHarness messages={[message]} isRunning={isRunning}>
+ <ThreadPrimitive.Messages>{() => <AssistantMessageContainer />}</ThreadPrimitive.Messages>
+ </RuntimeHarness>,
+ );
+}
+
+describe('AgentSteps grouping', () => {
+ it('groups consecutive tool calls under the Agent steps accordion', () => {
+ renderMultiToolMessage([
+ { type: 'tool-call', toolCallId: '1', toolName: 'first_tool', args: {}, result: 'a' },
+ { type: 'tool-call', toolCallId: '2', toolName: 'second_tool', args: {}, result: 'b' },
+ ]);
+ expect(screen.getByText('Agent steps')).toBeInTheDocument();
+ expect(screen.getByText(/2 tool calls/)).toBeInTheDocument();
+ });
+
+ it('renders both nested tool calls once expanded (defaultOpen)', () => {
+ renderMultiToolMessage([
+ { type: 'tool-call', toolCallId: '1', toolName: 'first_tool', args: {} },
+ { type: 'tool-call', toolCallId: '2', toolName: 'second_tool', args: {} },
+ ]);
+ expect(screen.getByText('first_tool')).toBeInTheDocument();
+ expect(screen.getByText('second_tool')).toBeInTheDocument();
+ });
+
+ it('collapses the group when the trigger is toggled', () => {
+ renderMultiToolMessage([
+ { type: 'tool-call', toolCallId: '1', toolName: 'first_tool', args: {} },
+ { type: 'tool-call', toolCallId: '2', toolName: 'second_tool', args: {} },
+ ]);
+ fireEvent.click(screen.getByText('Agent steps'));
+ expect(screen.queryByText('first_tool')).not.toBeInTheDocument();
+ });
+
+ it('uses singular label for exactly one tool call in the group', () => {
+ renderMultiToolMessage([{ type: 'tool-call', toolCallId: '1', toolName: 'first_tool', args: {} }]);
+ expect(screen.getByText('Agent steps')).toBeInTheDocument();
+ expect(screen.getByText(/1 tool call/)).toBeInTheDocument();
+ expect(screen.queryByText(/1 tool calls/)).not.toBeInTheDocument();
+ });
+
+ it('styles intermediate agent-step text muted and indented', () => {
+ renderMultiToolMessage([
+ { type: 'text', text: "I'll delegate this to a sub-agent." },
+ { type: 'tool-call', toolCallId: '1', toolName: 'first_tool', args: {}, result: 'a' },
+ { type: 'text', text: 'Here is the final answer.' },
+ ]);
+ // Auto-collapses once final answer is confirmed — expand to inspect step text
+ fireEvent.click(screen.getByText('Agent steps'));
+ const intermediate = screen.getByText("I'll delegate this to a sub-agent.");
+ const stepTextWrap = intermediate.closest("[class*='ml-[1.75rem]']");
+ expect(stepTextWrap).toHaveClass('mb-2', 'text-gray-600', 'dark:text-gray-400');
+ const finalAnswer = screen.getByText('Here is the final answer.');
+ expect(finalAnswer.closest("[class*='ml-[1.75rem]']")).toBeNull();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/ToolGroupContainer.tsx b/packages/trueforge-ui-sdk/src/containers/ToolGroupContainer.tsx
new file mode 100644
index 000000000..4c70b3e30
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/ToolGroupContainer.tsx
@@ -0,0 +1,41 @@
+'use client';
+
+import { useAuiState, type MessagePrimitive } from '@assistant-ui/react';
+import { useState, type PropsWithChildren, type ReactNode } from 'react';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+
+export type ThreadGroupPart = MessagePrimitive.GroupedParts.GroupPart;
+
+export function ToolGroupContainer({ children, group }: PropsWithChildren<{ group: ThreadGroupPart }>) {
+ const ToolGroupCard = useSlot('ToolGroupCard');
+
+ const toolCallCount = group.indices.length;
+
+ const active = useAuiState(s => {
+ if (s.message.status?.type !== 'running') return false;
+ const lastIndex = s.message.parts.length - 1;
+ if (lastIndex < 0) return false;
+ if (s.message.parts[lastIndex]?.type !== 'tool-call') return false;
+ const lastGroupIndex = group.indices[group.indices.length - 1];
+ return lastGroupIndex !== undefined && lastIndex >= group.indices[0]! && lastIndex <= lastGroupIndex;
+ });
+
+ const [expanded, setExpanded] = useState(true);
+ const [prevActive, setPrevActive] = useState(active);
+ if (active !== prevActive) {
+ setPrevActive(active);
+ if (active) setExpanded(true);
+ }
+
+ return (
+ <ToolGroupCard
+ toolCallCount={toolCallCount}
+ expanded={expanded}
+ active={active}
+ onToggle={() => setExpanded(prev => !prev)}
+ >
+ {children as ReactNode}
+ </ToolGroupCard>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/TrueFoundryChatProvider.test.tsx b/packages/trueforge-ui-sdk/src/containers/TrueFoundryChatProvider.test.tsx
new file mode 100644
index 000000000..9ebe89fb3
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/TrueFoundryChatProvider.test.tsx
@@ -0,0 +1,50 @@
+// @vitest-environment jsdom
+import { useExternalStoreRuntime, type ThreadMessageLike } from '@assistant-ui/react';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { AgentUIServer } from '../server/types.js';
+
+vi.mock('@truefoundry/assistant-ui-runtime', () => ({
+ trueFoundryAttachmentAdapter: {},
+ useTrueFoundryAgentRuntime: () =>
+ // Called from ChatRuntimeScope (a React component), so hooks are valid here.
+ useExternalStoreRuntime<ThreadMessageLike>({
+ messages: [],
+ isRunning: false,
+ convertMessage: (message: ThreadMessageLike) => message,
+ onNew: async () => {},
+ }),
+}));
+
+import { TrueFoundryChatProvider } from './TrueFoundryChatProvider.js';
+
+function mockServer(): AgentUIServer {
+ return {
+ createSession: vi.fn(),
+ listSessions: vi.fn(),
+ getSession: vi.fn(),
+ updateSession: vi.fn(),
+ createTurn: vi.fn(),
+ cancelSession: vi.fn(),
+ listTurns: vi.fn(),
+ getTurn: vi.fn(),
+ listEvents: vi.fn(),
+ getModels: vi.fn(async () => []),
+ getSkills: vi.fn(async () => []),
+ getMcp: vi.fn(async () => []),
+ searchAgents: vi.fn(async () => []),
+ saveAgent: vi.fn(async () => ({})),
+ } as unknown as AgentUIServer;
+}
+
+describe('TrueFoundryChatProvider', () => {
+ it('mounts children under the chat provider with a mock server', () => {
+ render(
+ <TrueFoundryChatProvider server={mockServer()} agentName="my-agent">
+ <div>chat-child</div>
+ </TrueFoundryChatProvider>,
+ );
+
+ expect(screen.getByText('chat-child')).toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/TrueFoundryChatProvider.tsx b/packages/trueforge-ui-sdk/src/containers/TrueFoundryChatProvider.tsx
new file mode 100644
index 000000000..4d69f6a1a
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/TrueFoundryChatProvider.tsx
@@ -0,0 +1,87 @@
+'use client';
+
+import { AssistantRuntimeProvider } from '@assistant-ui/react';
+import {
+ trueFoundryAttachmentAdapter,
+ useTrueFoundryAgentRuntime,
+ type TrueFoundryAgentConfig,
+ type UseTrueFoundryAgentRuntimeOptions,
+} from '@truefoundry/assistant-ui-runtime';
+import { useMemo, type ReactNode } from 'react';
+
+import type { AgentUIServer } from '../server/types.js';
+import { ErrorToasterProvider, useErrorToaster } from './ErrorToasterContainer.js';
+
+type RuntimeAdapters = NonNullable<UseTrueFoundryAgentRuntimeOptions['adapters']>;
+
+export type TrueFoundryChatProviderProps = {
+ server: AgentUIServer;
+ initialSessionId?: string;
+ adapters?: RuntimeAdapters;
+ onError?: (error: unknown) => void;
+ children: ReactNode;
+ /** Discriminated agent source. Prefer over legacy `agentName`. */
+ agent?: TrueFoundryAgentConfig;
+ /** Legacy named-agent shorthand. Prefer `agent: { mode: "named", agentName }`. */
+ agentName?: string;
+};
+
+function ChatRuntimeScope({
+ server,
+ agent,
+ agentName,
+ initialSessionId,
+ adapters,
+ onError,
+ children,
+}: {
+ server: AgentUIServer;
+ agent?: TrueFoundryAgentConfig;
+ agentName?: string;
+ initialSessionId?: string;
+ adapters?: RuntimeAdapters;
+ onError?: (error: unknown) => void;
+ children: ReactNode;
+}) {
+ const { showError } = useErrorToaster();
+ const resolvedOnError = onError ?? showError;
+
+ const runtime = useTrueFoundryAgentRuntime({
+ server: server as never,
+ agent,
+ agentName,
+ initialSessionId,
+ onError: resolvedOnError,
+ adapters: {
+ ...adapters,
+ attachments: adapters?.attachments ?? trueFoundryAttachmentAdapter,
+ },
+ });
+
+ return <AssistantRuntimeProvider runtime={runtime}>{children}</AssistantRuntimeProvider>;
+}
+
+/**
+ * Chat shell: wires `useTrueFoundryAgentRuntime` from `server` and provides
+ * assistant-ui + error toasts.
+ */
+export function TrueFoundryChatProvider(props: TrueFoundryChatProviderProps) {
+ const { server, initialSessionId, adapters, onError, children, agent, agentName } = props;
+
+ const stableServer = useMemo(() => server, [server]);
+
+ return (
+ <ErrorToasterProvider>
+ <ChatRuntimeScope
+ server={stableServer}
+ agent={agent}
+ agentName={agentName}
+ initialSessionId={initialSessionId}
+ adapters={adapters}
+ onError={onError}
+ >
+ {children}
+ </ChatRuntimeScope>
+ </ErrorToasterProvider>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/TrueforgeUI.test.tsx b/packages/trueforge-ui-sdk/src/containers/TrueforgeUI.test.tsx
new file mode 100644
index 000000000..d330a7d3d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/TrueforgeUI.test.tsx
@@ -0,0 +1,412 @@
+// @vitest-environment jsdom
+import { useExternalStoreRuntime, type ThreadMessageLike } from '@assistant-ui/react';
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { AgentUIServer, CatalogServer } from '../server/types.js';
+
+vi.mock('@truefoundry/assistant-ui-runtime', () => ({
+ trueFoundryAttachmentAdapter: {},
+ useTrueFoundryAgentRuntime: () =>
+ useExternalStoreRuntime<ThreadMessageLike>({
+ messages: [],
+ isRunning: false,
+ convertMessage: (message: ThreadMessageLike) => message,
+ onNew: async () => {},
+ }),
+ useTrueFoundryCancel: () => vi.fn(),
+ useTrueFoundryToolResponses: () => ({ pending: [] }),
+ useTrueFoundryRespondToToolApproval: () => vi.fn(),
+ useTrueFoundryMcpAuth: () => ({ pending: [], connect: vi.fn(), continue: vi.fn() }),
+ useTrueFoundryHistoryPagination: () => ({
+ isLoadingMore: false,
+ hasMore: false,
+ loadMore: vi.fn(),
+ }),
+ useTrueFoundryDownloadSandboxFile: () => vi.fn(),
+ useTrueFoundryAgentSpec: () => ({
+ agentSpec: { model: { name: 'openai-main/gpt-4.1' } },
+ }),
+ useTrueFoundryUpdateAgentSpec: () => vi.fn(),
+}));
+
+vi.mock('@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter', () => ({
+ createTrueFoundryAgentUIServer: vi.fn(
+ () =>
+ new Promise(() => {
+ /* never resolves — keep init loader visible */
+ }),
+ ),
+}));
+
+import { DrawerLayout } from '../layouts/DrawerLayout.js';
+import { SidebarLayout } from '../layouts/SidebarLayout.js';
+import { StackChatPanel } from '../layouts/StackChatPanel.js';
+import { WidgetLayout } from '../layouts/WidgetLayout.js';
+import { ServerProvider } from '../server/ServerContext.js';
+import { ShellModeProvider } from '../server/ShellModeContext.js';
+import { SlotsProvider } from '../theme/SlotsProvider.js';
+import { RuntimeHarness } from './RuntimeHarness.js';
+import { TrueforgeUI, type ChatLayout } from './TrueforgeUI.js';
+
+function mockServer(catalog?: CatalogServer): AgentUIServer {
+ return {
+ createSession: vi.fn(),
+ listSessions: vi.fn(),
+ getSession: vi.fn(),
+ updateSession: vi.fn(),
+ createTurn: vi.fn(),
+ cancelSession: vi.fn(),
+ listTurns: vi.fn(),
+ getTurn: vi.fn(),
+ listEvents: vi.fn(),
+ getModels: vi.fn(async () => []),
+ getSkills: vi.fn(async () => []),
+ getMcp: vi.fn(async () => []),
+ searchAgents: vi.fn(async () => []),
+ saveAgent: vi.fn(async () => ({})),
+ ...(catalog != null ? { catalog } : {}),
+ } as unknown as AgentUIServer;
+}
+
+/** Minimal catalog stub — ShellActions only checks presence. */
+const stubCatalog = {} as CatalogServer;
+
+describe('TrueforgeUI', () => {
+ const server = mockServer();
+ const layouts: ChatLayout[] = ['sidebar', 'drawer', 'dock', 'widget'];
+
+ it.each(layouts)('mounts layout=%s without crashing', async layout => {
+ const { container } = render(
+ <TrueforgeUI
+ server={server}
+ agentConfig={{ mode: 'SingleAgent', name: 'my-agent' }}
+ layout={layout}
+ className="h-96"
+ />,
+ );
+ await waitFor(() => {
+ expect(container.querySelector('.h-96')).toBeTruthy();
+ });
+ });
+
+ it('mounts a custom layout component inside providers', async () => {
+ function CustomLayout({ className }: { className?: string }) {
+ return (
+ <div data-testid="custom-layout" className={className}>
+ custom chrome
+ </div>
+ );
+ }
+
+ render(
+ <TrueforgeUI
+ server={server}
+ agentConfig={{ mode: 'SingleAgent', name: 'my-agent' }}
+ layout={CustomLayout}
+ className="h-96"
+ />,
+ );
+
+ await waitFor(() => {
+ expect(screen.getByTestId('custom-layout')).toHaveTextContent('custom chrome');
+ });
+ });
+
+ it('renders only the MCP authorization screen when requested by the URL', async () => {
+ const originalUrl = window.location.href;
+ const postMessage = vi.fn();
+ const close = vi.fn();
+ vi.stubGlobal(
+ 'BroadcastChannel',
+ class {
+ postMessage = postMessage;
+ close = close;
+ },
+ );
+ window.history.replaceState(null, '', '/?screenType=mcp-auth&pUid=popup-1&isSuccess=true');
+
+ const { unmount } = render(
+ <TrueforgeUI
+ server={server}
+ agentConfig={{ mode: 'SingleAgent', name: 'my-agent' }}
+ layout={() => <div data-testid="regular-layout">regular chrome</div>}
+ />,
+ );
+
+ expect(await screen.findByText('Authorization successful')).toBeInTheDocument();
+ expect(screen.queryByTestId('regular-layout')).not.toBeInTheDocument();
+
+ unmount();
+ window.history.replaceState(null, '', originalUrl);
+ vi.unstubAllGlobals();
+ });
+
+ it('surfaces trueforge-not-implemented as an alert', async () => {
+ const onError = vi.fn();
+ render(
+ <TrueforgeUI server={{ type: 'trueforge', apiKey: 'k' }} layout="sidebar" className="h-96" onError={onError} />,
+ );
+
+ await waitFor(() => {
+ expect(screen.getByRole('alert')).toHaveTextContent(/trueforge.*not implemented/i);
+ });
+ expect(onError).toHaveBeenCalled();
+ });
+
+ it('shows a loader while truefoundry server init is pending', () => {
+ render(
+ <TrueforgeUI
+ server={{
+ type: 'truefoundry',
+ apiKey: 'k',
+ controlPlaneURL: 'https://cp.example',
+ }}
+ layout="sidebar"
+ className="h-96"
+ />,
+ );
+
+ expect(screen.getByRole('status', { name: 'Loading' })).toBeInTheDocument();
+ });
+});
+
+describe('StackChatPanel', () => {
+ it('starts on a new chat and opens the session list from history', () => {
+ render(
+ <SlotsProvider>
+ <RuntimeHarness messages={[]}>
+ <div className="h-96">
+ <StackChatPanel />
+ </div>
+ </RuntimeHarness>
+ </SlotsProvider>,
+ );
+
+ expect(screen.getByLabelText('Sessions')).toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'Start new chat' })).not.toBeInTheDocument();
+
+ fireEvent.click(screen.getByLabelText('Sessions'));
+
+ expect(screen.getByRole('button', { name: 'Start new chat' })).toBeInTheDocument();
+ expect(screen.queryByLabelText('Sessions')).not.toBeInTheDocument();
+ });
+});
+
+describe('SidebarLayout', () => {
+ it('shows the app brand in the mobile sessions drawer', () => {
+ render(
+ <SlotsProvider theme={{ brand: { name: 'Acme', icon: { src: '/acme.svg', alt: 'Acme logo' } } }}>
+ <RuntimeHarness messages={[]}>
+ <div className="h-96">
+ <SidebarLayout />
+ </div>
+ </RuntimeHarness>
+ </SlotsProvider>,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'Sessions' }));
+
+ const drawer = screen.getByRole('dialog', { name: 'Sessions' });
+ expect(within(drawer).getByText('Acme')).toBeInTheDocument();
+ expect(within(drawer).getByAltText('Acme logo')).toBeInTheDocument();
+ });
+
+ it('shows the brand and toggles the desktop sidebar rail', () => {
+ const { unmount } = render(
+ <SlotsProvider theme={{ brand: { name: 'Acme' } }}>
+ <RuntimeHarness messages={[]}>
+ <div className="h-96">
+ <SidebarLayout />
+ </div>
+ </RuntimeHarness>
+ </SlotsProvider>,
+ );
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ fireEvent.click(screen.getByRole('button', { name: 'Collapse sidebar' }));
+
+ expect(screen.queryByText('Acme')).not.toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Expand sidebar' })).toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Start new chat' })).toBeInTheDocument();
+
+ // New Chat / Agents remount ChatProvider via runtimeKey; collapse must survive.
+ unmount();
+ render(
+ <SlotsProvider theme={{ brand: { name: 'Acme' } }}>
+ <RuntimeHarness messages={[]}>
+ <div className="h-96">
+ <SidebarLayout />
+ </div>
+ </RuntimeHarness>
+ </SlotsProvider>,
+ );
+ expect(screen.getByRole('button', { name: 'Expand sidebar' })).toBeInTheDocument();
+ });
+
+ it('toggles theme from the footer and shows settings only when catalog is provided', () => {
+ const { rerender } = render(
+ <SlotsProvider theme={{ brand: { name: 'Acme' } }}>
+ <ServerProvider server={mockServer(stubCatalog)}>
+ <ShellModeProvider>
+ <RuntimeHarness messages={[]}>
+ <div className="h-96">
+ <SidebarLayout />
+ </div>
+ </RuntimeHarness>
+ </ShellModeProvider>
+ </ServerProvider>
+ </SlotsProvider>,
+ );
+
+ expect(screen.getAllByRole('button', { name: 'Settings' })).toHaveLength(2);
+ const themeBtn = screen.getAllByRole('button', { name: /Switch to (light|dark) theme/ })[0]!;
+ fireEvent.click(themeBtn);
+ expect(screen.getAllByRole('button', { name: /Switch to (light|dark) theme/ })).toHaveLength(2);
+
+ // Settings stays available with a locked agentName when catalog is present.
+ rerender(
+ <SlotsProvider theme={{ brand: { name: 'Acme' } }}>
+ <ServerProvider server={mockServer(stubCatalog)}>
+ <ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: 'locked-agent' }}>
+ <RuntimeHarness messages={[]}>
+ <div className="h-96">
+ <SidebarLayout />
+ </div>
+ </RuntimeHarness>
+ </ShellModeProvider>
+ </ServerProvider>
+ </SlotsProvider>,
+ );
+ expect(screen.getAllByRole('button', { name: 'Settings' })).toHaveLength(2);
+
+ // No catalog → no Settings button.
+ rerender(
+ <SlotsProvider theme={{ brand: { name: 'Acme' } }}>
+ <ServerProvider server={mockServer()}>
+ <ShellModeProvider>
+ <RuntimeHarness messages={[]}>
+ <div className="h-96">
+ <SidebarLayout />
+ </div>
+ </RuntimeHarness>
+ </ShellModeProvider>
+ </ServerProvider>
+ </SlotsProvider>,
+ );
+ expect(screen.queryByRole('button', { name: 'Settings' })).not.toBeInTheDocument();
+ expect(screen.getAllByRole('button', { name: /Switch to (light|dark) theme/ })).toHaveLength(2);
+ });
+});
+
+describe('DrawerLayout a11y', () => {
+ it('opens sessions panel, focuses dialog, and restores focus on Escape', async () => {
+ render(
+ <SlotsProvider>
+ <RuntimeHarness messages={[]}>
+ <div className="h-96">
+ <DrawerLayout />
+ </div>
+ </RuntimeHarness>
+ </SlotsProvider>,
+ );
+
+ const sessionsBtn = screen.getByRole('button', { name: 'Sessions' });
+ expect(sessionsBtn).toHaveAttribute('aria-expanded', 'false');
+
+ fireEvent.click(sessionsBtn);
+ expect(sessionsBtn).toHaveAttribute('aria-expanded', 'true');
+ const dialog = screen.getByRole('dialog', { name: 'Sessions' });
+ expect(dialog).toBeInTheDocument();
+ await waitFor(() => {
+ expect(dialog).toHaveFocus();
+ });
+
+ fireEvent.keyDown(window, { key: 'Escape' });
+ expect(screen.queryByRole('dialog', { name: 'Sessions' })).not.toBeInTheDocument();
+ expect(sessionsBtn).toHaveAttribute('aria-expanded', 'false');
+ await waitFor(() => {
+ expect(sessionsBtn).toHaveFocus();
+ });
+ });
+
+ it('closes sessions panel when backdrop is clicked', () => {
+ render(
+ <SlotsProvider>
+ <RuntimeHarness messages={[]}>
+ <div className="h-96">
+ <DrawerLayout />
+ </div>
+ </RuntimeHarness>
+ </SlotsProvider>,
+ );
+
+ fireEvent.click(screen.getByRole('button', { name: 'Sessions' }));
+ expect(screen.getByRole('dialog', { name: 'Sessions' })).toBeInTheDocument();
+
+ fireEvent.click(screen.getByRole('button', { name: 'Close sessions' }));
+ expect(screen.queryByRole('dialog', { name: 'Sessions' })).not.toBeInTheDocument();
+ });
+});
+
+describe('layout slot overrides', () => {
+ function CustomClearChat() {
+ return <button type="button">custom clear</button>;
+ }
+
+ // dock and widget render their header through StackChatPanel.
+ const hosts = [
+ ['sidebar', SidebarLayout],
+ ['drawer', DrawerLayout],
+ ['dock/widget', StackChatPanel],
+ ] as const;
+
+ it.each(hosts)('%s honors overrides.ClearChatButton', (_name, Layout) => {
+ render(
+ <SlotsProvider overrides={{ ClearChatButton: CustomClearChat }}>
+ <ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: 'a' }}>
+ <RuntimeHarness messages={[]}>
+ <div className="h-96">
+ <Layout />
+ </div>
+ </RuntimeHarness>
+ </ShellModeProvider>
+ </SlotsProvider>,
+ );
+
+ expect(screen.getByRole('button', { name: 'custom clear' })).toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: 'Clear chat' })).not.toBeInTheDocument();
+ });
+});
+
+describe('WidgetLayout a11y', () => {
+ it('opens chat dialog, focuses it, and restores FAB focus on Escape', async () => {
+ render(
+ <SlotsProvider>
+ <RuntimeHarness messages={[]}>
+ <div className="h-96">
+ <WidgetLayout />
+ </div>
+ </RuntimeHarness>
+ </SlotsProvider>,
+ );
+
+ const fab = screen.getByRole('button', { name: 'Open chat' });
+ expect(fab).toHaveAttribute('aria-expanded', 'false');
+
+ fireEvent.click(fab);
+ const dialog = screen.getByRole('dialog', { name: 'Chat' });
+ expect(dialog).toBeInTheDocument();
+ await waitFor(() => {
+ expect(dialog).toHaveFocus();
+ });
+ expect(screen.getByRole('button', { name: 'Close chat' })).toHaveAttribute('aria-expanded', 'true');
+
+ fireEvent.keyDown(window, { key: 'Escape' });
+ expect(screen.queryByRole('dialog', { name: 'Chat' })).not.toBeInTheDocument();
+ const openFab = screen.getByRole('button', { name: 'Open chat' });
+ expect(openFab).toHaveAttribute('aria-expanded', 'false');
+ await waitFor(() => {
+ expect(openFab).toHaveFocus();
+ });
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/TrueforgeUI.tsx b/packages/trueforge-ui-sdk/src/containers/TrueforgeUI.tsx
new file mode 100644
index 000000000..a226219a3
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/TrueforgeUI.tsx
@@ -0,0 +1,210 @@
+'use client';
+
+import type { TrueFoundryAgentConfig, UseTrueFoundryAgentRuntimeOptions } from '@truefoundry/assistant-ui-runtime';
+import { lazy, Suspense, useMemo, type ReactNode } from 'react';
+
+import { cn } from '../atoms/lib/cn.js';
+import { Spinner } from '../atoms/primitives/Spinner.js';
+import { ServerProvider } from '../server/ServerContext.js';
+import { DEFAULT_AGENT_CONFIG, ShellModeProvider, useShellMode, type AgentConfig } from '../server/ShellModeContext.js';
+import type { TrueforgeServerConfig } from '../server/TrueforgeServerConfig.js';
+import { SlotsProvider, type SlotOverrides } from '../theme/SlotsProvider.js';
+import type { LayoutProp, ThemeConfig } from '../theme/types.js';
+import PostMcpOauthScreen from './McpOauthContainer/PostMcpOauthScreen.js';
+import { TrueFoundryChatProvider, type TrueFoundryChatProviderProps } from './TrueFoundryChatProvider.js';
+import { useResolvedServer } from './useResolvedServer.js';
+
+const SidebarLayout = lazy(() => import('../layouts/SidebarLayout.js').then(m => ({ default: m.SidebarLayout })));
+const DrawerLayout = lazy(() => import('../layouts/DrawerLayout.js').then(m => ({ default: m.DrawerLayout })));
+const DockLayout = lazy(() => import('../layouts/DockLayout.js').then(m => ({ default: m.DockLayout })));
+const WidgetLayout = lazy(() => import('../layouts/WidgetLayout.js').then(m => ({ default: m.WidgetLayout })));
+
+export type ChatLayout = 'sidebar' | 'drawer' | 'dock' | 'widget';
+export type { AgentConfig } from '../server/ShellModeContext.js';
+export type { TrueforgeBuiltInServerConfig, TrueforgeServerConfig } from '../server/TrueforgeServerConfig.js';
+export type { LayoutProp } from '../theme/types.js';
+
+type RuntimeAdapters = NonNullable<UseTrueFoundryAgentRuntimeOptions['adapters']>;
+
+export type TrueforgeUIProps = {
+ server: TrueforgeServerConfig;
+ layout: LayoutProp;
+ overrides?: SlotOverrides;
+ theme?: ThemeConfig;
+ className?: string;
+ initialSessionId?: string;
+ adapters?: RuntimeAdapters;
+ onError?: (error: unknown) => void;
+ /**
+ * Agent / library / composer shell mode.
+ * Defaults to `{ mode: "AgentLibraryWithComposer" }`.
+ */
+ agentConfig?: AgentConfig;
+};
+
+function LayoutFallback({ className }: { className?: string }) {
+ return (
+ <div
+ className={className}
+ style={{
+ height: '100%',
+ minHeight: '12rem',
+ background:
+ 'linear-gradient(90deg, color-mix(in oklab, var(--muted, #e5e5e5) 55%, transparent) 25%, color-mix(in oklab, var(--muted, #e5e5e5) 25%, transparent) 50%, color-mix(in oklab, var(--muted, #e5e5e5) 55%, transparent) 75%)',
+ backgroundSize: '200% 100%',
+ animation: 'tfy-aui-pulse 1.2s ease-in-out infinite',
+ }}
+ aria-hidden
+ />
+ );
+}
+
+/** Shown while `type: "truefoundry"` resolves the agent UI server. */
+function ServerInitLoader({ className }: { className?: string }) {
+ return (
+ <div
+ role="status"
+ aria-live="polite"
+ aria-busy="true"
+ className={cn(
+ 'flex h-full min-h-48 w-full flex-1 items-center justify-center bg-background text-muted-foreground',
+ className,
+ )}
+ >
+ <Spinner size={28} className="text-foreground" />
+ <span className="sr-only">Loading</span>
+ </div>
+ );
+}
+
+function ServerInitError({ error, className }: { error: unknown; className?: string }) {
+ const message = error instanceof Error ? error.message : 'Failed to initialize server';
+ return (
+ <div
+ role="alert"
+ className={cn(
+ 'flex h-full min-h-48 items-center justify-center bg-background px-6 text-center text-sm text-destructive',
+ className,
+ )}
+ >
+ {message}
+ </div>
+ );
+}
+
+function isBuiltInLayout(layout: LayoutProp): layout is ChatLayout {
+ return layout === 'sidebar' || layout === 'drawer' || layout === 'dock' || layout === 'widget';
+}
+
+function BuiltInLayoutView({ layout, className }: { layout: ChatLayout; className?: string }) {
+ switch (layout) {
+ case 'sidebar':
+ return <SidebarLayout className={className} />;
+ case 'drawer':
+ return <DrawerLayout className={className} />;
+ case 'dock':
+ return <DockLayout className={className} />;
+ case 'widget':
+ return <WidgetLayout className={className} />;
+ }
+}
+
+function LayoutChildren({ layout, className }: { layout: LayoutProp; className?: string }) {
+ if (isBuiltInLayout(layout)) {
+ return (
+ <Suspense fallback={<LayoutFallback className={className} />}>
+ <BuiltInLayoutView layout={layout} className={className} />
+ </Suspense>
+ );
+ }
+ const HostLayout = layout;
+ return <HostLayout className={className} />;
+}
+
+function ChatProviderFromShell({
+ children,
+ ...providerRest
+}: {
+ children: ReactNode;
+} & Omit<TrueFoundryChatProviderProps, 'agent' | 'agentName' | 'children'>) {
+ const { mode, runtimeKey } = useShellMode();
+
+ const agent: TrueFoundryAgentConfig = useMemo(() => {
+ if (mode.type === 'named') {
+ return { mode: 'named', agentName: mode.agentName };
+ }
+ // idle uses a placeholder draft so layout chrome (useAui) still mounts;
+ // layouts render an empty CTA instead of the thread.
+ if (mode.type === 'idle') {
+ return {
+ mode: 'draft',
+ defaultAgentSpec: { model: { name: 'openai-main/gpt-4.1' } },
+ };
+ }
+ return { mode: 'draft', defaultAgentSpec: mode.defaultAgentSpec };
+ }, [mode]);
+
+ return (
+ <TrueFoundryChatProvider key={runtimeKey} {...providerRest} agent={agent}>
+ {children}
+ </TrueFoundryChatProvider>
+ );
+}
+
+/**
+ * Quick-start assistant UI: slots + runtime + a built-in or custom layout.
+ * Pass a built-in `server` config, a ready `AgentUIServer`, and optional `agentConfig`.
+ */
+export function TrueforgeUI(props: TrueforgeUIProps) {
+ const isMcpAuthScreen =
+ typeof window !== 'undefined' && new URLSearchParams(window.location.search).get('screenType') === 'mcp-auth';
+
+ // Kept in a wrapper so the OAuth callback screen renders without resolving a server.
+ return isMcpAuthScreen ? <PostMcpOauthScreen /> : <TrueforgeUIShell {...props} />;
+}
+
+function TrueforgeUIShell(props: TrueforgeUIProps) {
+ const {
+ layout,
+ overrides,
+ theme,
+ className,
+ agentConfig = DEFAULT_AGENT_CONFIG,
+ server: serverConfig,
+ onError,
+ ...providerRest
+ } = props;
+
+ const resolved = useResolvedServer(serverConfig, onError);
+
+ if (resolved.status === 'loading') {
+ return (
+ <SlotsProvider overrides={overrides} theme={theme}>
+ <ServerInitLoader className={className} />
+ </SlotsProvider>
+ );
+ }
+
+ if (resolved.status === 'error') {
+ return (
+ <SlotsProvider overrides={overrides} theme={theme}>
+ <ServerInitError error={resolved.error} className={className} />
+ </SlotsProvider>
+ );
+ }
+
+ const server = resolved.server;
+ const layoutTree = <LayoutChildren layout={layout} className={className} />;
+
+ return (
+ <SlotsProvider overrides={overrides} theme={theme}>
+ <ServerProvider server={server}>
+ <ShellModeProvider agentConfig={agentConfig}>
+ <ChatProviderFromShell server={server} onError={onError} {...providerRest}>
+ {layoutTree}
+ </ChatProviderFromShell>
+ </ShellModeProvider>
+ </ServerProvider>
+ </SlotsProvider>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/UserEditComposerContainer.test.tsx b/packages/trueforge-ui-sdk/src/containers/UserEditComposerContainer.test.tsx
new file mode 100644
index 000000000..ce2bf07cb
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/UserEditComposerContainer.test.tsx
@@ -0,0 +1,66 @@
+// @vitest-environment jsdom
+import { ThreadPrimitive, type ThreadMessageLike } from '@assistant-ui/react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { RuntimeHarness } from './RuntimeHarness.js';
+import { UserEditComposerContainer } from './UserEditComposerContainer.js';
+
+function renderEditComposer(messages: ThreadMessageLike[]) {
+ return render(
+ <RuntimeHarness messages={messages}>
+ <ThreadPrimitive.Messages>{() => <UserEditComposerContainer />}</ThreadPrimitive.Messages>
+ </RuntimeHarness>,
+ );
+}
+
+describe('UserEditComposerContainer', () => {
+ it('renders a text input with cancel and save & rerun actions', () => {
+ renderEditComposer([{ role: 'user', content: 'edit me', id: 'turn-1-user' }]);
+ expect(screen.getByRole('textbox')).toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Cancel' })).toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Save & Rerun' })).toBeInTheDocument();
+ expect(screen.getByRole('textbox').closest('form')).toBeTruthy();
+ });
+
+ it('submits the edit form on Enter', () => {
+ renderEditComposer([{ role: 'user', content: 'edit me', id: 'turn-1-user' }]);
+
+ const input = screen.getByRole('textbox');
+ const form = input.closest('form');
+ expect(form).toBeTruthy();
+ const requestSubmit = vi.spyOn(form!, 'requestSubmit');
+
+ fireEvent.keyDown(input, { key: 'Enter' });
+
+ expect(requestSubmit).toHaveBeenCalled();
+ });
+
+ it('shows read-only attachments without remove controls', () => {
+ renderEditComposer([
+ {
+ role: 'user',
+ content: 'What is this?',
+ id: 'turn-1-user',
+ attachments: [
+ {
+ id: 'att-1',
+ type: 'image',
+ name: 'logo.png',
+ contentType: 'image/png',
+ status: { type: 'complete' },
+ content: [
+ {
+ type: 'image',
+ image: 'data:image/png;base64,iVBORw0KGgo=',
+ filename: 'logo.png',
+ },
+ ],
+ },
+ ],
+ },
+ ]);
+ expect(screen.getByAltText('logo.png')).toBeInTheDocument();
+ expect(screen.queryByRole('button', { name: /remove/i })).not.toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/UserEditComposerContainer.tsx b/packages/trueforge-ui-sdk/src/containers/UserEditComposerContainer.tsx
new file mode 100644
index 000000000..c757429e1
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/UserEditComposerContainer.tsx
@@ -0,0 +1,66 @@
+'use client';
+
+import { useComposerCancel, useComposerSend, useThreadIsRunning } from '@assistant-ui/core/react';
+import { ComposerPrimitive, MessagePrimitive, useAuiState } from '@assistant-ui/react';
+
+import { Button } from '../atoms/primitives/Button.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+import { MessageAttachmentsContainer } from './AttachmentsContainer.js';
+
+function ReadOnlyMessageAttachments() {
+ const hasAttachments = useAuiState(s => (s.message.attachments?.length ?? 0) > 0);
+ if (!hasAttachments) {
+ return null;
+ }
+ return (
+ <div className="pointer-events-none mb-2 opacity-90">
+ <MessageAttachmentsContainer />
+ </div>
+ );
+}
+
+export function UserEditComposerContainer() {
+ const UserMessageEdit = useSlot('UserMessageEdit');
+ const MessageTimestamp = useSlot('MessageTimestamp');
+ const isRunning = useThreadIsRunning();
+ const createdAt = useAuiState(s => s.message.createdAt);
+ const { cancel, disabled: cancelDisabled } = useComposerCancel();
+ const { disabled: sendDisabled } = useComposerSend();
+
+ return (
+ <MessagePrimitive.Root data-role="user">
+ <ComposerPrimitive.Root
+ data-slot="aui_user-edit-composer-root"
+ className="fade-in slide-in-from-bottom-1 animate-in flex w-full justify-end px-2 duration-150"
+ >
+ <UserMessageEdit
+ timestamp={<MessageTimestamp createdAt={createdAt} className="text-gray-500" />}
+ attachments={<ReadOnlyMessageAttachments />}
+ input={
+ <div className="mt-1 rounded border border-gray-250 bg-gray-100 p-2 text-gray-750 dark:border-gray-275 dark:bg-gray-275">
+ <ComposerPrimitive.Input
+ data-slot="aui_user-edit-input"
+ disabled={isRunning}
+ submitMode="enter"
+ aria-label="Edit message"
+ className="max-h-32 min-h-10 w-full resize-none border-none bg-transparent p-0 text-base leading-[1.34] outline-none focus:shadow-none"
+ />
+ </div>
+ }
+ footer={
+ <div className="flex items-center justify-end gap-2">
+ <Button variant="secondary" type="button" disabled={cancelDisabled} onClick={cancel}>
+ Cancel
+ </Button>
+ <ComposerPrimitive.Send asChild>
+ <Button type="submit" disabled={sendDisabled || isRunning}>
+ Save &amp; Rerun
+ </Button>
+ </ComposerPrimitive.Send>
+ </div>
+ }
+ />
+ </ComposerPrimitive.Root>
+ </MessagePrimitive.Root>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/UserMessageContainer.test.tsx b/packages/trueforge-ui-sdk/src/containers/UserMessageContainer.test.tsx
new file mode 100644
index 000000000..758cdc77e
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/UserMessageContainer.test.tsx
@@ -0,0 +1,107 @@
+// @vitest-environment jsdom
+import { ThreadPrimitive, type ThreadMessageLike } from '@assistant-ui/react';
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { RuntimeHarness } from './RuntimeHarness.js';
+import { UserMessageContainer } from './UserMessageContainer.js';
+
+function renderUserMessage(messages: ThreadMessageLike[], options?: { isRunning?: boolean }) {
+ return render(
+ <RuntimeHarness messages={messages} isRunning={options?.isRunning}>
+ <ThreadPrimitive.Messages>{() => <UserMessageContainer />}</ThreadPrimitive.Messages>
+ </RuntimeHarness>,
+ );
+}
+
+describe('UserMessageContainer', () => {
+ it('renders user text content through UserMessageBubble', () => {
+ renderUserMessage([{ role: 'user', content: 'what is the capital of France?' }]);
+ expect(screen.getByText('what is the capital of France?')).toHaveStyle({
+ borderRadius: 'var(--composer-radius, 1.5rem)',
+ });
+ });
+
+ it('renders an image attachment preview above the text bubble', () => {
+ renderUserMessage([
+ {
+ role: 'user',
+ content: 'What is this?',
+ attachments: [
+ {
+ id: 'att-1',
+ type: 'image',
+ name: 'logo.png',
+ contentType: 'image/png',
+ status: { type: 'complete' },
+ content: [
+ {
+ type: 'image',
+ image: 'data:image/png;base64,iVBORw0KGgo=',
+ filename: 'logo.png',
+ },
+ ],
+ },
+ ],
+ },
+ ]);
+ expect(screen.getByText('What is this?')).toBeInTheDocument();
+ const preview = screen.getByAltText('logo.png');
+ expect(preview).toBeInTheDocument();
+ expect(preview.parentElement).toHaveStyle({ width: '12rem', height: '12rem' });
+ });
+
+ it('renders a file attachment chip above the text bubble', () => {
+ renderUserMessage([
+ {
+ role: 'user',
+ content: 'See attached',
+ attachments: [
+ {
+ id: 'att-1',
+ type: 'file',
+ name: 'report.pdf',
+ contentType: 'application/pdf',
+ status: { type: 'complete' },
+ content: [
+ {
+ type: 'file',
+ mimeType: 'application/pdf',
+ filename: 'report.pdf',
+ data: 'data:application/pdf;base64,AAAA',
+ },
+ ],
+ },
+ ],
+ },
+ ]);
+ expect(screen.getByText('See attached')).toBeInTheDocument();
+ const chip = screen.getByText('report.pdf').closest("[data-slot='aui_attachment-chip']");
+ expect(chip).toHaveStyle({ maxWidth: '12rem' });
+ });
+
+ it('shows the action bar when the thread is idle', () => {
+ renderUserMessage(
+ [
+ {
+ role: 'user',
+ content: 'hello',
+ id: 'turn-1-user',
+ createdAt: new Date('2026-07-09T14:05:42'),
+ },
+ ],
+ { isRunning: false },
+ );
+ expect(screen.getByRole('button', { name: 'Try again' })).toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Edit' })).toBeInTheDocument();
+ expect(screen.getByRole('button', { name: 'Copy' })).toBeInTheDocument();
+ expect(screen.getByText(/\d{1,2}:\d{2}:\d{2}/)).toBeInTheDocument();
+ });
+
+ it('hides the action bar while the thread is running', () => {
+ renderUserMessage([{ role: 'user', content: 'hello', id: 'turn-1-user' }], {
+ isRunning: true,
+ });
+ expect(screen.queryByRole('button', { name: 'Edit' })).not.toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/UserMessageContainer.tsx b/packages/trueforge-ui-sdk/src/containers/UserMessageContainer.tsx
new file mode 100644
index 000000000..611ebbbe9
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/UserMessageContainer.tsx
@@ -0,0 +1,49 @@
+'use client';
+
+import { useActionBarCopy, useActionBarEdit, useThreadIsRunning } from '@assistant-ui/core/react';
+import { MessagePrimitive, useAui, useAuiState } from '@assistant-ui/react';
+
+import { useSlot } from '../theme/SlotsProvider.js';
+import { MessageAttachmentsContainer } from './AttachmentsContainer.js';
+
+export function UserMessageContainer() {
+ const UserMessageBubble = useSlot('UserMessageBubble');
+ const UserMessageActionBar = useSlot('UserMessageActionBar');
+ const isRunning = useThreadIsRunning();
+ const aui = useAui();
+ const createdAt = useAuiState(s => s.message.createdAt);
+ const text = useAuiState(s =>
+ s.message.content
+ .filter((part): part is { type: 'text'; text: string } => part.type === 'text')
+ .map(part => part.text)
+ .join('\n'),
+ );
+ const { edit, disabled: editDisabled } = useActionBarEdit();
+ const { copy, isCopied } = useActionBarCopy({
+ copyToClipboard: value => navigator.clipboard.writeText(value),
+ });
+
+ return (
+ <MessagePrimitive.Root data-role="user">
+ <UserMessageBubble
+ text={text}
+ attachments={<MessageAttachmentsContainer />}
+ editAction={
+ !isRunning ? (
+ <UserMessageActionBar
+ isCopied={isCopied}
+ editDisabled={editDisabled}
+ createdAt={createdAt}
+ onCopy={copy}
+ onEdit={edit}
+ onRetry={() => {
+ aui.message().composer().beginEdit();
+ aui.message().composer().send({ startRun: true });
+ }}
+ />
+ ) : undefined
+ }
+ />
+ </MessagePrimitive.Root>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/nestedApprovalBridge.ts b/packages/trueforge-ui-sdk/src/containers/nestedApprovalBridge.ts
new file mode 100644
index 000000000..755cf8a22
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/nestedApprovalBridge.ts
@@ -0,0 +1,18 @@
+'use client';
+
+import type { ToolApprovalResponse } from '@assistant-ui/react';
+import { createContext, useContext } from 'react';
+
+/**
+ * Sub-agent tool calls render inside a read-only nested thread context
+ * (`MessagePartPrimitive.Messages`), so the standard `respondToApproval` prop
+ * on their parts doesn't route back to the gateway. `ToolCallContainer` uses
+ * this bridge instead when rendering nested calls, translating the response
+ * through `useTrueFoundryRespondToToolApproval()` -- mirrors the reference's
+ * `nestedToolCallMessageComponents` override.
+ */
+export const NestedApprovalBridgeContext = createContext<((response: ToolApprovalResponse) => void) | null>(null);
+
+export function useNestedApprovalBridge(): ((response: ToolApprovalResponse) => void) | null {
+ return useContext(NestedApprovalBridgeContext);
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/useAttachmentPreviewSrc.ts b/packages/trueforge-ui-sdk/src/containers/useAttachmentPreviewSrc.ts
new file mode 100644
index 000000000..fefe4967b
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/useAttachmentPreviewSrc.ts
@@ -0,0 +1,42 @@
+'use client';
+
+import { useAuiState } from '@assistant-ui/react';
+import { useEffect, useState } from 'react';
+
+export function isImageAttachment(type: string, contentType?: string): boolean {
+ return type === 'image' || (contentType?.startsWith('image/') ?? false);
+}
+
+function useFileObjectUrl(file: File | undefined): string | undefined {
+ const [src, setSrc] = useState<string | undefined>(undefined);
+
+ useEffect(() => {
+ if (!file) {
+ setSrc(undefined);
+ return;
+ }
+ const objectUrl = URL.createObjectURL(file);
+ setSrc(objectUrl);
+ return () => URL.revokeObjectURL(objectUrl);
+ }, [file]);
+
+ return src;
+}
+
+/** Preview URL for staged composer files (object URL) or sent message attachments (data URI). */
+export function useAttachmentPreviewSrc(): string | undefined {
+ const type = useAuiState(s => s.attachment.type);
+ const contentType = useAuiState(s => s.attachment.contentType);
+ const file = useAuiState(s => ('file' in s.attachment ? s.attachment.file : undefined));
+ const contentSrc = useAuiState(s => {
+ if (!isImageAttachment(s.attachment.type, s.attachment.contentType)) return undefined;
+ const imagePart = s.attachment.content?.find(part => part.type === 'image');
+ if (imagePart?.type === 'image' && imagePart.image) return imagePart.image;
+ return undefined;
+ });
+
+ const image = isImageAttachment(type, contentType);
+ const fileSrc = useFileObjectUrl(image ? file : undefined);
+ if (!image) return undefined;
+ return fileSrc ?? contentSrc;
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/useResolvedServer.test.tsx b/packages/trueforge-ui-sdk/src/containers/useResolvedServer.test.tsx
new file mode 100644
index 000000000..e97938c66
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/useResolvedServer.test.tsx
@@ -0,0 +1,79 @@
+// @vitest-environment jsdom
+import { renderHook, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { AgentUIServer } from '../server/types.js';
+import { useResolvedServer } from './useResolvedServer.js';
+
+vi.mock('@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter', () => ({
+ createTrueFoundryAgentUIServer: vi.fn(async () => ({
+ createSession: vi.fn(),
+ getModels: vi.fn(async () => []),
+ })),
+}));
+
+function mockServer(): AgentUIServer {
+ return { saveAgent: vi.fn() } as unknown as AgentUIServer;
+}
+
+describe('useResolvedServer', () => {
+ it('passes through AgentUIServer synchronously', () => {
+ const server = mockServer();
+ const { result } = renderHook(() => useResolvedServer(server));
+ expect(result.current).toEqual({
+ status: 'ready',
+ server,
+ error: null,
+ });
+ });
+
+ it('errors for trueforge until the adapter exists', async () => {
+ const onError = vi.fn();
+ const { result } = renderHook(() => useResolvedServer({ type: 'trueforge', apiKey: 'k' }, onError));
+
+ await waitFor(() => {
+ expect(result.current.status).toBe('error');
+ });
+ expect(String(result.current.error)).toMatch(/not implemented/i);
+ expect(onError).toHaveBeenCalled();
+ });
+
+ it('loads truefoundry via createTrueFoundryAgentUIServer', async () => {
+ const { createTrueFoundryAgentUIServer } =
+ await import('@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter');
+ const { result } = renderHook(() =>
+ useResolvedServer({
+ type: 'truefoundry',
+ apiKey: 'k',
+ controlPlaneURL: 'https://cp.example',
+ gatewayPlaneURL: 'https://gw.example',
+ }),
+ );
+
+ await waitFor(() => {
+ expect(result.current.status).toBe('ready');
+ });
+ expect(createTrueFoundryAgentUIServer).toHaveBeenCalledWith({
+ apiKey: 'k',
+ cpURL: 'https://cp.example',
+ gatewayURL: 'https://gw.example',
+ });
+ });
+
+ it('attaches an optional catalog onto the truefoundry server', async () => {
+ const catalog = { skillCatalog: {} } as never;
+ const { result } = renderHook(() =>
+ useResolvedServer({
+ type: 'truefoundry',
+ apiKey: 'k',
+ controlPlaneURL: 'https://cp.example',
+ catalog,
+ }),
+ );
+
+ await waitFor(() => {
+ expect(result.current.status).toBe('ready');
+ });
+ expect(result.current.server?.catalog).toBe(catalog);
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/containers/useResolvedServer.ts b/packages/trueforge-ui-sdk/src/containers/useResolvedServer.ts
new file mode 100644
index 000000000..16048e7f9
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/containers/useResolvedServer.ts
@@ -0,0 +1,97 @@
+'use client';
+
+import { createTrueFoundryAgentUIServer } from '@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter';
+import { useEffect, useState } from 'react';
+
+import type { TrueforgeBuiltInServerConfig, TrueforgeServerConfig } from '../server/TrueforgeServerConfig.js';
+import type { AgentUIServer } from '../server/types.js';
+
+export type ResolvedServerState =
+ | { status: 'loading'; server: null; error: null }
+ | { status: 'ready'; server: AgentUIServer; error: null }
+ | { status: 'error'; server: null; error: unknown };
+
+function isBuiltInConfig(config: TrueforgeServerConfig): config is TrueforgeBuiltInServerConfig {
+ return (
+ typeof config === 'object' &&
+ config !== null &&
+ 'type' in config &&
+ (config.type === 'truefoundry' || config.type === 'trueforge')
+ );
+}
+
+/**
+ * Resolves a {@link TrueforgeServerConfig} to an {@link AgentUIServer}.
+ * - `AgentUIServer` — sync passthrough
+ * - `truefoundry` — async via `createTrueFoundryAgentUIServer`
+ * - `trueforge` — not implemented yet (error state)
+ */
+export function useResolvedServer(
+ config: TrueforgeServerConfig,
+ onError?: (error: unknown) => void,
+): ResolvedServerState {
+ const builtIn = isBuiltInConfig(config) ? config : null;
+ const directServer: AgentUIServer | null = isBuiltInConfig(config) ? null : config;
+ const type = builtIn?.type;
+ const apiKey = builtIn?.apiKey ?? '';
+ const controlPlaneURL = builtIn?.type === 'truefoundry' ? builtIn.controlPlaneURL : '';
+ const gatewayPlaneURL = builtIn?.type === 'truefoundry' ? (builtIn.gatewayPlaneURL ?? '') : '';
+ const catalog = builtIn?.catalog;
+
+ const [state, setState] = useState<ResolvedServerState>(() => {
+ if (directServer) {
+ return { status: 'ready', server: directServer, error: null };
+ }
+ if (type === 'trueforge') {
+ return {
+ status: 'error',
+ server: null,
+ error: new Error('TrueforgeUI: type "trueforge" is not implemented yet'),
+ };
+ }
+ return { status: 'loading', server: null, error: null };
+ });
+
+ useEffect(() => {
+ if (directServer) {
+ setState({ status: 'ready', server: directServer, error: null });
+ return;
+ }
+
+ if (type === 'trueforge') {
+ const error = new Error('TrueforgeUI: type "trueforge" is not implemented yet');
+ onError?.(error);
+ setState({ status: 'error', server: null, error });
+ return;
+ }
+
+ let cancelled = false;
+ setState({ status: 'loading', server: null, error: null });
+
+ void createTrueFoundryAgentUIServer({
+ apiKey,
+ cpURL: controlPlaneURL,
+ ...(gatewayPlaneURL ? { gatewayURL: gatewayPlaneURL } : {}),
+ })
+ .then(server => {
+ if (cancelled) return;
+ const resolved = server as unknown as AgentUIServer;
+ setState({
+ status: 'ready',
+ server: catalog != null ? ({ ...resolved, catalog } as AgentUIServer) : resolved,
+ error: null,
+ });
+ })
+ .catch((error: unknown) => {
+ if (cancelled) return;
+ onError?.(error);
+ setState({ status: 'error', server: null, error });
+ });
+
+ return () => {
+ cancelled = true;
+ };
+ }, [type, directServer, apiKey, controlPlaneURL, gatewayPlaneURL, catalog, onError]);
+
+ return state;
+}
diff --git a/packages/trueforge-ui-sdk/src/github-markdown-bridge.css b/packages/trueforge-ui-sdk/src/github-markdown-bridge.css
new file mode 100644
index 000000000..cfa397dea
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/github-markdown-bridge.css
@@ -0,0 +1,155 @@
+/*
+ * Bridge github-markdown-css theme vars to the SDK's class / data-theme
+ * mode. The package auto file only flips vars inside prefers-color-scheme
+ * media queries, so controlled ThemeProvider mode would otherwise disagree
+ * with the OS.
+ *
+ * Source: github-markdown-css (auto theme variable blocks).
+ */
+.dark .markdown-body,
+[data-theme="dark"] .markdown-body {
+ /*dark */
+ color-scheme: dark;
+ --fgColor-accent: #4493f8;
+ --bgColor-attention-muted: #bb800926;
+ --bgColor-default: #0d1117;
+ --bgColor-muted: #151b23;
+ --bgColor-neutral-muted: #656c7633;
+ --borderColor-accent-emphasis: #1f6feb;
+ --borderColor-attention-emphasis: #9e6a03;
+ --borderColor-danger-emphasis: #da3633;
+ --borderColor-default: #3d444d;
+ --borderColor-done-emphasis: #8957e5;
+ --borderColor-success-emphasis: #238636;
+ --color-prettylights-syntax-brackethighlighter-angle: #9198a1;
+ --color-prettylights-syntax-brackethighlighter-unmatched: #f85149;
+ --color-prettylights-syntax-carriage-return-bg: #b62324;
+ --color-prettylights-syntax-carriage-return-text: #f0f6fc;
+ --color-prettylights-syntax-comment: #9198a1;
+ --color-prettylights-syntax-constant: #79c0ff;
+ --color-prettylights-syntax-constant-other-reference-link: #a5d6ff;
+ --color-prettylights-syntax-entity: #d2a8ff;
+ --color-prettylights-syntax-entity-tag: #7ee787;
+ --color-prettylights-syntax-keyword: #ff7b72;
+ --color-prettylights-syntax-markup-bold: #f0f6fc;
+ --color-prettylights-syntax-markup-changed-bg: #5a1e02;
+ --color-prettylights-syntax-markup-changed-text: #ffdfb6;
+ --color-prettylights-syntax-markup-deleted-bg: #67060c;
+ --color-prettylights-syntax-markup-deleted-text: #ffdcd7;
+ --color-prettylights-syntax-markup-heading: #1f6feb;
+ --color-prettylights-syntax-markup-ignored-bg: #1158c7;
+ --color-prettylights-syntax-markup-ignored-text: #f0f6fc;
+ --color-prettylights-syntax-markup-inserted-bg: #033a16;
+ --color-prettylights-syntax-markup-inserted-text: #aff5b4;
+ --color-prettylights-syntax-markup-italic: #f0f6fc;
+ --color-prettylights-syntax-markup-list: #f2cc60;
+ --color-prettylights-syntax-meta-diff-range: #d2a8ff;
+ --color-prettylights-syntax-storage-modifier-import: #f0f6fc;
+ --color-prettylights-syntax-string: #a5d6ff;
+ --color-prettylights-syntax-string-regexp: #7ee787;
+ --color-prettylights-syntax-sublimelinter-gutter-mark: #3d444d;
+ --color-prettylights-syntax-variable: #ffa657;
+ --fgColor-attention: #d29922;
+ --fgColor-danger: #f85149;
+ --fgColor-default: #f0f6fc;
+ --fgColor-done: #ab7df8;
+ --fgColor-muted: #9198a1;
+ --fgColor-success: #3fb950;
+ --borderColor-muted: #3d444db3;
+ --color-prettylights-syntax-invalid-illegal-bg: var(--bgColor-danger-muted);
+ --color-prettylights-syntax-invalid-illegal-text: var(--fgColor-danger);
+ --focus-outlineColor: var(--borderColor-accent-emphasis);
+ --borderColor-neutral-muted: var(--borderColor-muted);
+}
+
+:root:not(.dark) .markdown-body,
+[data-theme="light"] .markdown-body {
+ /*light */
+ color-scheme: light;
+ --fgColor-danger: #d1242f;
+ --bgColor-attention-muted: #fff8c5;
+ --bgColor-muted: #f6f8fa;
+ --bgColor-neutral-muted: #818b981f;
+ --borderColor-accent-emphasis: #0969da;
+ --borderColor-attention-emphasis: #9a6700;
+ --borderColor-danger-emphasis: #cf222e;
+ --borderColor-default: #d1d9e0;
+ --borderColor-done-emphasis: #8250df;
+ --borderColor-success-emphasis: #1a7f37;
+ --color-prettylights-syntax-brackethighlighter-angle: #59636e;
+ --color-prettylights-syntax-brackethighlighter-unmatched: #82071e;
+ --color-prettylights-syntax-carriage-return-bg: #cf222e;
+ --color-prettylights-syntax-carriage-return-text: #f6f8fa;
+ --color-prettylights-syntax-comment: #59636e;
+ --color-prettylights-syntax-constant: #0550ae;
+ --color-prettylights-syntax-constant-other-reference-link: #0a3069;
+ --color-prettylights-syntax-entity: #6639ba;
+ --color-prettylights-syntax-entity-tag: #0550ae;
+ --color-prettylights-syntax-invalid-illegal-text: var(--fgColor-danger);
+ --color-prettylights-syntax-keyword: #cf222e;
+ --color-prettylights-syntax-markup-changed-bg: #ffd8b5;
+ --color-prettylights-syntax-markup-changed-text: #953800;
+ --color-prettylights-syntax-markup-deleted-bg: #ffebe9;
+ --color-prettylights-syntax-markup-deleted-text: #82071e;
+ --color-prettylights-syntax-markup-heading: #0550ae;
+ --color-prettylights-syntax-markup-ignored-bg: #0550ae;
+ --color-prettylights-syntax-markup-ignored-text: #d1d9e0;
+ --color-prettylights-syntax-markup-inserted-bg: #dafbe1;
+ --color-prettylights-syntax-markup-inserted-text: #116329;
+ --color-prettylights-syntax-markup-list: #3b2300;
+ --color-prettylights-syntax-meta-diff-range: #8250df;
+ --color-prettylights-syntax-string: #0a3069;
+ --color-prettylights-syntax-string-regexp: #116329;
+ --color-prettylights-syntax-sublimelinter-gutter-mark: #818b98;
+ --color-prettylights-syntax-variable: #953800;
+ --fgColor-accent: #0969da;
+ --fgColor-attention: #9a6700;
+ --fgColor-done: #8250df;
+ --fgColor-muted: #59636e;
+ --fgColor-success: #1a7f37;
+ --bgColor-default: #ffffff;
+ --borderColor-muted: #d1d9e0b3;
+ --color-prettylights-syntax-invalid-illegal-bg: var(--bgColor-danger-muted);
+ --color-prettylights-syntax-markup-bold: #1f2328;
+ --color-prettylights-syntax-markup-italic: #1f2328;
+ --color-prettylights-syntax-storage-modifier-import: #1f2328;
+ --fgColor-default: #1f2328;
+ --focus-outlineColor: var(--borderColor-accent-emphasis);
+ --borderColor-neutral-muted: var(--borderColor-muted);
+}
+
+/* Chat host: don't paint GitHub's page background behind message bubbles. */
+.aui-markdown.markdown-body {
+ background-color: transparent;
+ font-family: inherit;
+ font-size: inherit;
+}
+
+/* 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(
+ --fontStack-monospace,
+ ui-monospace,
+ SFMono-Regular,
+ "SF Mono",
+ Menlo,
+ Consolas,
+ "Liberation Mono",
+ monospace
+ );
+}
+
+/* Tables: transparent cells, theme borders (not GitHub page chrome). */
+.aui-markdown.markdown-body table tr,
+.aui-markdown.markdown-body table tr:nth-child(2n) {
+ background-color: transparent;
+}
+
+.aui-markdown.markdown-body table th,
+.aui-markdown.markdown-body table td {
+ border-color: var(--border);
+}
+
+.aui-markdown.markdown-body table tr {
+ border-top-color: var(--border);
+}
diff --git a/packages/trueforge-ui-sdk/src/hooks/useComposerBusyState.test.ts b/packages/trueforge-ui-sdk/src/hooks/useComposerBusyState.test.ts
new file mode 100644
index 000000000..46f8b1fea
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/hooks/useComposerBusyState.test.ts
@@ -0,0 +1,78 @@
+// @vitest-environment jsdom
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { createElement, type ReactNode } from 'react';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const useThreadIsRunning = vi.fn(() => false);
+
+vi.mock('@assistant-ui/core/react', () => ({
+ useThreadIsRunning: () => useThreadIsRunning(),
+}));
+
+import { ComposerBusyProvider, useComposerBusyState } from './useComposerBusyState.js';
+
+function wrapper({ children }: { children: ReactNode }) {
+ return createElement(ComposerBusyProvider, null, children);
+}
+
+describe('useComposerBusyState', () => {
+ beforeEach(() => {
+ useThreadIsRunning.mockReturnValue(false);
+ });
+
+ it('starts busy immediately on send before the thread is running', () => {
+ const { result } = renderHook(() => useComposerBusyState(), { wrapper });
+
+ act(() => {
+ result.current.send(() => undefined);
+ });
+
+ expect(result.current.isBusy).toBe(true);
+ expect(result.current.isSubmitting).toBe(true);
+ expect(result.current.isRunning).toBe(false);
+ });
+
+ it('clears submitting when the thread stops running', async () => {
+ useThreadIsRunning.mockReturnValue(true);
+ const { result, rerender } = renderHook(() => useComposerBusyState(), { wrapper });
+
+ act(() => {
+ result.current.send(() => undefined);
+ });
+
+ useThreadIsRunning.mockReturnValue(false);
+ rerender();
+
+ await waitFor(() => {
+ expect(result.current.isBusy).toBe(false);
+ });
+ });
+
+ it('clears submitting when send rejects', async () => {
+ const { result } = renderHook(() => useComposerBusyState(), { wrapper });
+
+ act(() => {
+ result.current.send(() => Promise.reject(new Error('send failed')));
+ });
+
+ expect(result.current.isBusy).toBe(true);
+
+ await waitFor(() => {
+ expect(result.current.isBusy).toBe(false);
+ });
+ });
+
+ it('resetBusy clears optimistic submitting state', () => {
+ const { result } = renderHook(() => useComposerBusyState(), { wrapper });
+
+ act(() => {
+ result.current.send(() => undefined);
+ });
+ expect(result.current.isBusy).toBe(true);
+
+ act(() => {
+ result.current.resetBusy();
+ });
+ expect(result.current.isBusy).toBe(false);
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/hooks/useComposerBusyState.ts b/packages/trueforge-ui-sdk/src/hooks/useComposerBusyState.ts
new file mode 100644
index 000000000..7e802fcc0
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/hooks/useComposerBusyState.ts
@@ -0,0 +1,69 @@
+'use client';
+
+import { useThreadIsRunning } from '@assistant-ui/core/react';
+import { createContext, createElement, useCallback, useContext, useEffect, useState, type ReactNode } from 'react';
+
+export type ComposerBusyState = {
+ /** True while submitting or while the turn stream is active. */
+ isBusy: boolean;
+ isRunning: boolean;
+ isSubmitting: boolean;
+ send: (sendFn: () => void | Promise<void>) => void;
+ resetBusy: () => void;
+};
+
+const ComposerBusyContext = createContext<ComposerBusyState | null>(null);
+
+function useComposerBusyStateValue(): ComposerBusyState {
+ const isRunning = useThreadIsRunning();
+ const [isSubmitting, setIsSubmitting] = useState(false);
+
+ useEffect(() => {
+ if (!isRunning) {
+ setIsSubmitting(false);
+ }
+ }, [isRunning]);
+
+ const isBusy = isRunning || isSubmitting;
+
+ const resetBusy = useCallback(() => {
+ setIsSubmitting(false);
+ }, []);
+
+ const send = useCallback((sendFn: () => void | Promise<void>) => {
+ setIsSubmitting(true);
+ try {
+ const result = sendFn();
+ if (result != null && typeof result.then === 'function') {
+ void result.catch(() => {
+ setIsSubmitting(false);
+ });
+ }
+ } catch {
+ setIsSubmitting(false);
+ }
+ }, []);
+
+ return { isBusy, isRunning, isSubmitting, send, resetBusy };
+}
+
+export function ComposerBusyProvider({ children }: { children: ReactNode }) {
+ const value = useComposerBusyStateValue();
+ return createElement(ComposerBusyContext.Provider, { value }, children);
+}
+
+/**
+ * Optimistic composer busy state shared across the thread. `useThreadIsRunning()`
+ * only becomes true once the turn stream starts; this hook flips to busy
+ * immediately on submit so the send button shows loading before session setup /
+ * turn API work finishes.
+ *
+ * Must be used within `<ComposerBusyProvider>` (wired by default in `<Thread />`).
+ */
+export function useComposerBusyState(): ComposerBusyState {
+ const value = useContext(ComposerBusyContext);
+ if (value == null) {
+ throw new Error('useComposerBusyState must be used within ComposerBusyProvider');
+ }
+ return value;
+}
diff --git a/packages/trueforge-ui-sdk/src/hooks/useComposerPauseView.ts b/packages/trueforge-ui-sdk/src/hooks/useComposerPauseView.ts
new file mode 100644
index 000000000..1b28f4114
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/hooks/useComposerPauseView.ts
@@ -0,0 +1,39 @@
+'use client';
+
+import { useAuiState } from '@assistant-ui/react';
+import { useTrueFoundryToolResponses } from '@truefoundry/assistant-ui-runtime';
+
+export type ThreadPauseState = {
+ thread: {
+ messages: readonly {
+ role: string;
+ status?: { type: string };
+ metadata?: { custom?: unknown };
+ }[];
+ };
+};
+
+/** Returns true when the latest assistant message is paused for MCP authorization. */
+export function threadHasPendingMcpAuth(s: ThreadPauseState): boolean {
+ const messages = s.thread.messages;
+ const last = messages[messages.length - 1];
+ if (last?.role !== 'assistant') return false;
+ if (last.status?.type !== 'requires-action') return false;
+ return (last.metadata?.custom as { pendingMcpAuth?: boolean } | undefined)?.pendingMcpAuth === true;
+}
+
+export type ComposerPauseView = { kind: 'mcp' } | { kind: 'ask-user' } | { kind: 'compose' };
+
+/** Shared composer pause detection for default and custom composer containers. */
+export function useComposerPauseView(): ComposerPauseView {
+ const mcpPending = useAuiState(threadHasPendingMcpAuth);
+ const { pending: toolResponsesPending } = useTrueFoundryToolResponses();
+
+ if (mcpPending) {
+ return { kind: 'mcp' };
+ }
+ if (toolResponsesPending.length > 0) {
+ return { kind: 'ask-user' };
+ }
+ return { kind: 'compose' };
+}
diff --git a/packages/trueforge-ui-sdk/src/hooks/useMcpAuth.ts b/packages/trueforge-ui-sdk/src/hooks/useMcpAuth.ts
new file mode 100644
index 000000000..d55b550ac
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/hooks/useMcpAuth.ts
@@ -0,0 +1,119 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import { useErrorToasterOptional } from '../containers/ErrorToasterContainer.js';
+import { useCatalogServer } from '../server/ServerContext.js';
+
+export const MCP_AUTH_POPUP_CHANNEL = 'truefoundry-mcp-auth-popup';
+
+export type McpAuthPopupMessage = {
+ popupUid: string;
+ isSuccess: boolean;
+};
+
+export type McpAuthCallback = (isSuccess: boolean) => void;
+
+export type UseMCPAuthOptions = {
+ callbackPath?: string;
+};
+
+const generatePopupUid = () => `mcp-oauth-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+
+const isPopupMessage = (value: unknown): value is McpAuthPopupMessage => {
+ if (typeof value !== 'object' || value === null) return false;
+ const message = value as Partial<McpAuthPopupMessage>;
+ return typeof message.popupUid === 'string' && typeof message.isSuccess === 'boolean';
+};
+
+export const useMCPAuth = ({ callbackPath }: UseMCPAuthOptions = {}) => {
+ const { connectorCatalog } = useCatalogServer();
+ const errorToaster = useErrorToasterOptional();
+ const [isOAuthLoading, setIsOAuthLoading] = useState(false);
+ const popupUid = useMemo(() => generatePopupUid(), []);
+ const listenerCleanupRef = useRef<(() => void) | null>(null);
+
+ const clearPopupListener = useCallback(() => {
+ listenerCleanupRef.current?.();
+ listenerCleanupRef.current = null;
+ }, []);
+
+ useEffect(() => clearPopupListener, [clearPopupListener]);
+
+ const openAuthPopup = useCallback(
+ (authorizationEndpoint: string, callback: McpAuthCallback) => {
+ clearPopupListener();
+
+ const channel = new BroadcastChannel(MCP_AUTH_POPUP_CHANNEL);
+ let popup: Window | null = null;
+ const cleanup = () => {
+ channel.close();
+ popup?.close();
+ };
+
+ channel.onmessage = (event: MessageEvent<unknown>) => {
+ if (!isPopupMessage(event.data) || event.data.popupUid !== popupUid) return;
+ try {
+ callback(event.data.isSuccess);
+ } finally {
+ clearPopupListener();
+ }
+ };
+ listenerCleanupRef.current = cleanup;
+
+ popup = window.open(authorizationEndpoint, '_blank', 'popup=true');
+ if (!popup) {
+ clearPopupListener();
+ throw new Error('Popup blocked. Please allow pop-ups to authorize the MCP server.');
+ }
+
+ popup.focus();
+ },
+ [clearPopupListener, popupUid],
+ );
+
+ const handleAuthorize = useCallback(
+ async (integrationId: string, callback: McpAuthCallback) => {
+ if (!integrationId) return;
+
+ try {
+ setIsOAuthLoading(true);
+ const callbackUrl = callbackPath
+ ? new URL(callbackPath, window.location.origin)
+ : new URL(window.location.href);
+ callbackUrl.searchParams.set('screenType', 'mcp-auth');
+ callbackUrl.searchParams.set('integrationId', integrationId);
+ callbackUrl.searchParams.set('pUid', popupUid);
+
+ const result = await connectorCatalog.authenticateConnector({
+ id: integrationId,
+ redirectURL: callbackUrl.toString(),
+ });
+
+ if (
+ ('status' in result && result.status?.toUpperCase() === 'AUTHENTICATED') ||
+ ('authenticated' in result && result.authenticated)
+ ) {
+ callback(true);
+ return;
+ }
+
+ const authorizationEndpoint = 'authorization_endpoint' in result ? result.authorization_endpoint : undefined;
+ if (!authorizationEndpoint) {
+ throw new Error('The MCP server did not return an authorization URL.');
+ }
+
+ openAuthPopup(authorizationEndpoint, callback);
+ } catch (error: unknown) {
+ errorToaster?.showError(error);
+ callback(false);
+ } finally {
+ setIsOAuthLoading(false);
+ }
+ },
+ [callbackPath, connectorCatalog, errorToaster, openAuthPopup, popupUid],
+ );
+
+ return {
+ handleAuthorize,
+ isOAuthLoading,
+ };
+};
diff --git a/packages/trueforge-ui-sdk/src/icons/Icon.tsx b/packages/trueforge-ui-sdk/src/icons/Icon.tsx
new file mode 100644
index 000000000..e177eb7d1
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/icons/Icon.tsx
@@ -0,0 +1,68 @@
+import {
+ createElement,
+ isValidElement,
+ useContext,
+ type ComponentType,
+ type CSSProperties,
+ type ReactNode,
+} from 'react';
+
+import { cn } from '../atoms/lib/cn.js';
+import { ThemeContext } from '../theme/ThemeProvider.js';
+import type { IconProps as ThemeIconProps } from '../theme/types.js';
+import { lookupIcon, resolveIconName, type IconEntry } from './IconRegistry.js';
+
+export type IconProps = ThemeIconProps & {
+ name: string | readonly string[];
+};
+
+type IconRenderProps = {
+ className?: string;
+ style?: CSSProperties;
+ size?: string | number;
+ width?: string | number;
+ height?: string | number;
+ role?: string;
+} & Pick<IconProps, 'aria-hidden' | 'aria-label'>;
+
+function isComponent(entry: IconEntry): boolean {
+ if (typeof entry === 'function') return true;
+ // Lucide (and other) icons are forwardRef objects, not functions
+ return (
+ typeof entry === 'object' &&
+ entry !== null &&
+ !isValidElement(entry) &&
+ !Array.isArray(entry) &&
+ '$$typeof' in entry
+ );
+}
+
+function renderEntry(entry: IconEntry, props: IconRenderProps): ReactNode {
+ if (isComponent(entry)) {
+ const { size, className, style, ...aria } = props;
+ return createElement(entry as ComponentType<IconRenderProps>, {
+ className: cn('inline-block shrink-0', className),
+ style,
+ size,
+ width: size,
+ height: size,
+ 'aria-hidden': aria['aria-label'] ? undefined : (aria['aria-hidden'] ?? true),
+ 'aria-label': aria['aria-label'],
+ role: aria['aria-label'] ? 'img' : undefined,
+ });
+ }
+ return entry as ReactNode;
+}
+
+export function Icon({ name, className, style, size = '1em', ...aria }: IconProps) {
+ const themeIcons = useContext(ThemeContext)?.icons;
+ const resolved = resolveIconName(name);
+ const entry = lookupIcon(resolved, themeIcons);
+ if (!entry) return null;
+ return <>{renderEntry(entry, { className, style, size, ...aria })}</>;
+}
+
+export function useIcon(name: string | readonly string[]): IconEntry | undefined {
+ const themeIcons = useContext(ThemeContext)?.icons;
+ return lookupIcon(resolveIconName(name), themeIcons);
+}
diff --git a/packages/trueforge-ui-sdk/src/icons/IconRegistry.tsx b/packages/trueforge-ui-sdk/src/icons/IconRegistry.tsx
new file mode 100644
index 000000000..9b103bed4
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/icons/IconRegistry.tsx
@@ -0,0 +1,139 @@
+import type { LucideIcon } from 'lucide-react';
+import {
+ Archive,
+ ArrowDown,
+ ArrowLeft,
+ ArrowUp,
+ Bot,
+ Box,
+ Brain,
+ Check,
+ ChevronDown,
+ ChevronLeft,
+ ChevronRight,
+ CircleAlert,
+ CircleCheck,
+ CircleX,
+ Clock,
+ Code2,
+ Copy,
+ Cpu,
+ Download,
+ Ellipsis,
+ ExternalLink,
+ File,
+ Github,
+ History,
+ Lightbulb,
+ ListChecks,
+ ListOrdered,
+ Loader2,
+ Maximize2,
+ Menu,
+ Minimize2,
+ Moon,
+ PanelLeftClose,
+ PanelLeftOpen,
+ Paperclip,
+ Pencil,
+ Plug,
+ Plus,
+ RotateCw,
+ Search,
+ Settings,
+ Sun,
+ Terminal,
+ Trash2,
+ Wrench,
+ X,
+} from 'lucide-react';
+import type { FC, ReactNode, SVGProps } from 'react';
+
+import type { IconMap, IconProps } from '../theme/types.js';
+
+export type IconEntry = LucideIcon | ReactNode | ((props: IconProps) => ReactNode) | FC<SVGProps<SVGSVGElement>>;
+
+const registry = new Map<string, IconEntry>();
+
+export function registerIcon(name: string, icon: IconEntry): void {
+ registry.set(name, icon);
+}
+
+export function registerIcons(icons: Record<string, IconEntry>): void {
+ for (const [name, icon] of Object.entries(icons)) {
+ registry.set(name, icon);
+ }
+}
+
+export function getIcon(name: string): IconEntry | undefined {
+ return registry.get(name);
+}
+
+export function resolveIconName(icon: string | readonly string[]): string {
+ if (typeof icon === 'string') return icon;
+ // e.g. ["far", "clone"] → "clone"
+ return icon[icon.length - 1] ?? '';
+}
+
+const defaults: Record<string, LucideIcon> = {
+ paperclip: Paperclip,
+ 'arrow-up': ArrowUp,
+ 'arrow-down': ArrowDown,
+ 'arrow-left': ArrowLeft,
+ xmark: X,
+ check: Check,
+ pencil: Pencil,
+ 'rotate-right': RotateCw,
+ ellipsis: Ellipsis,
+ trash: Trash2,
+ 'box-archive': Archive,
+ 'clock-rotate-left': History,
+ 'circle-exclamation': CircleAlert,
+ 'chevron-down': ChevronDown,
+ 'chevron-left': ChevronLeft,
+ 'chevron-right': ChevronRight,
+ loader: Loader2,
+ file: File,
+ clone: Copy,
+ copy: Copy,
+ bars: Menu,
+ 'panel-left-close': PanelLeftClose,
+ 'panel-left-open': PanelLeftOpen,
+ plus: Plus,
+ sun: Sun,
+ moon: Moon,
+ settings: Settings,
+ search: Search,
+ clock: Clock,
+ 'circle-check': CircleCheck,
+ 'circle-xmark': CircleX,
+ robot: Bot,
+ plug: Plug,
+ 'list-check': ListChecks,
+ lightbulb: Lightbulb,
+ wrench: Wrench,
+ cpu: Cpu,
+ cube: Box,
+ 'list-ol': ListOrdered,
+ download: Download,
+ brain: Brain,
+ terminal: Terminal,
+ code: Code2,
+ expand: Maximize2,
+ 'expand-alt': Maximize2,
+ compress: Minimize2,
+ 'external-link': ExternalLink,
+ github: Github,
+};
+
+for (const [name, icon] of Object.entries(defaults)) {
+ registry.set(name, icon);
+}
+
+/** Merge host `theme.icons` over the registry for a single lookup (does not mutate). */
+export function lookupIcon(name: string, themeIcons?: IconMap): IconEntry | undefined {
+ if (themeIcons && name in themeIcons) {
+ return themeIcons[name] as IconEntry;
+ }
+ return registry.get(name);
+}
diff --git a/packages/trueforge-ui-sdk/src/icons/agent-2.svg b/packages/trueforge-ui-sdk/src/icons/agent-2.svg
new file mode 100644
index 000000000..18b5546b5
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/icons/agent-2.svg
@@ -0,0 +1,3 @@
+<svg width="16" height="14" viewBox="0 0 16 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M8 0C8.40158 8.28071e-05 8.72754 0.325937 8.72754 0.727539V2.90918H12.3623C13.5671 2.90921 14.5437 3.88607 14.5439 5.09082V7.27246H15.2725C15.6741 7.27253 16 7.59839 16 8C15.9999 8.40155 15.674 8.72747 15.2725 8.72754H14.5439V10.9092C14.5437 12.1139 13.5671 13.0908 12.3623 13.0908H3.63477C2.43015 13.0906 1.45334 12.1138 1.45312 10.9092V8.72754H0.727539C0.325964 8.7275 7.21982e-05 8.40157 0 8C0 7.59837 0.32592 7.2725 0.727539 7.27246H1.45312V5.09082C1.45335 3.8862 2.43015 2.90942 3.63477 2.90918H7.27246V1.45508H5.09082C4.68943 1.4549 4.36346 1.12893 4.36328 0.727539C4.36328 0.325997 4.68932 0.00017902 5.09082 0H8ZM3.63477 4.36426C3.23346 4.3645 2.90843 4.68951 2.9082 5.09082V7.99023C2.90824 7.99344 2.90918 7.99678 2.90918 8C2.90918 8.00326 2.90825 8.00651 2.9082 8.00977V10.9092C2.90841 11.3105 3.23345 11.6365 3.63477 11.6367H12.3623C12.7638 11.6367 13.0896 11.3106 13.0898 10.9092V5.09082C13.0896 4.68937 12.7638 4.36428 12.3623 4.36426H3.63477ZM5.81738 6.54492C6.21902 6.54492 6.54489 6.87084 6.54492 7.27246V8.72656C6.54492 9.12822 6.21904 9.4541 5.81738 9.4541C5.41587 9.45393 5.08984 9.12811 5.08984 8.72656V7.27246C5.08988 6.87094 5.41589 6.54509 5.81738 6.54492ZM10.1816 6.54492C10.5831 6.54514 10.9091 6.87097 10.9092 7.27246V8.72656C10.9092 9.12808 10.5831 9.45388 10.1816 9.4541C9.77999 9.4541 9.4541 9.12822 9.4541 8.72656V7.27246C9.45413 6.87084 9.78001 6.54492 10.1816 6.54492Z" fill="#000"/>
+</svg>
diff --git a/packages/trueforge-ui-sdk/src/icons/ai.svg b/packages/trueforge-ui-sdk/src/icons/ai.svg
new file mode 100644
index 000000000..e71a2864d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/icons/ai.svg
@@ -0,0 +1,9 @@
+<svg width="16" height="17" viewBox="0 0 16 17" fill="none" xmlns="http://www.w3.org/2000/svg">
+<g opacity="0.9">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M15.4419 9.43023C15.7501 9.43023 16 9.68012 16 9.98837V10.0304C16 11.398 16 12.4813 15.886 13.329C15.7687 14.2015 15.5216 14.9077 14.9647 15.4647C14.4077 16.0216 13.7015 16.2687 12.829 16.386C11.9813 16.5 10.898 16.5 9.53035 16.5H9.48837C9.18012 16.5 8.93023 16.2501 8.93023 15.9419C8.93023 15.6336 9.18012 15.3837 9.48837 15.3837C10.9074 15.3837 11.9155 15.3825 12.6803 15.2797C13.429 15.1791 13.8604 14.9903 14.1753 14.6753C14.4903 14.3604 14.6791 13.929 14.7797 13.1803C14.8825 12.4155 14.8837 11.4074 14.8837 9.98837C14.8837 9.68012 15.1336 9.43023 15.4419 9.43023Z" fill="#000"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M0.55814 9.43023C0.866392 9.43023 1.11628 9.68012 1.11628 9.98837C1.11628 11.4074 1.11747 12.4155 1.22029 13.1803C1.32095 13.929 1.50973 14.3604 1.82467 14.6753C2.13962 14.9903 2.57098 15.1791 3.3197 15.2797C4.08448 15.3825 5.0926 15.3837 6.51163 15.3837C6.81988 15.3837 7.06977 15.6336 7.06977 15.9419C7.06977 16.2501 6.81988 16.5 6.51163 16.5H6.46965C5.10201 16.5 4.01875 16.5 3.17096 16.386C2.29846 16.2687 1.59227 16.0216 1.03534 15.4647C0.478423 14.9077 0.231266 14.2015 0.113961 13.329C-2.0957e-05 12.4813 -1.15596e-05 11.398 2.3934e-07 10.0304C3.72411e-07 10.0164 5.05482e-07 10.0024 5.05482e-07 9.98837C5.05482e-07 9.68012 0.249888 9.43023 0.55814 9.43023Z" fill="#000"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M6.46964 0.5L6.51163 0.500001C6.81988 0.500001 7.06977 0.749888 7.06977 1.05814C7.06977 1.36639 6.81988 1.61628 6.51163 1.61628C5.0926 1.61628 4.08448 1.61747 3.3197 1.72029C2.57098 1.82095 2.13962 2.00973 1.82467 2.32467C1.50973 2.63962 1.32095 3.07098 1.22029 3.8197C1.11747 4.58448 1.11628 5.5926 1.11628 7.01163C1.11628 7.31988 0.866392 7.56977 0.55814 7.56977C0.249888 7.56977 5.05482e-07 7.31988 5.05482e-07 7.01163L2.3934e-07 6.96964C-1.15596e-05 5.60201 -2.0957e-05 4.51875 0.113961 3.67096C0.231266 2.79846 0.478423 2.09227 1.03534 1.53534C1.59227 0.978423 2.29846 0.731266 3.17096 0.613961C4.01875 0.499979 5.10201 0.499988 6.46964 0.5Z" fill="#000"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M12.6803 1.72029C11.9155 1.61747 10.9074 1.61628 9.48837 1.61628C9.18012 1.61628 8.93023 1.36639 8.93023 1.05814C8.93023 0.749888 9.18012 0.500001 9.48837 0.500001C9.5024 0.500001 9.51639 0.5 9.53036 0.5C10.898 0.499988 11.9813 0.499979 12.829 0.613961C13.7015 0.731266 14.4077 0.978423 14.9647 1.53534C15.5216 2.09227 15.7687 2.79846 15.886 3.67096C16 4.51875 16 5.60201 16 6.96965V7.01163C16 7.31988 15.7501 7.56977 15.4419 7.56977C15.1336 7.56977 14.8837 7.31988 14.8837 7.01163C14.8837 5.5926 14.8825 4.58448 14.7797 3.8197C14.6791 3.07098 14.4903 2.63962 14.1753 2.32467C13.8604 2.00973 13.429 1.82095 12.6803 1.72029Z" fill="#000"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M2.70041 3.20041C2.04651 3.85431 2.04651 4.90675 2.04651 7.01163V9.98837C2.04651 12.0933 2.04651 13.1457 2.70041 13.7996C3.35431 14.4535 4.40675 14.4535 6.51163 14.4535H9.48837C11.5933 14.4535 12.6457 14.4535 13.2996 13.7996C13.9535 13.1457 13.9535 12.0933 13.9535 9.98837V7.01163C13.9535 4.90675 13.9535 3.85431 13.2996 3.20041C12.6457 2.54651 11.5933 2.54651 9.48837 2.54651H6.51163C4.40675 2.54651 3.35431 2.54651 2.70041 3.20041ZM5.65417 10.5348C5.81478 10.3181 6.12065 10.2726 6.33733 10.4332C6.8116 10.7848 7.38407 10.9884 8 10.9884C8.61593 10.9884 9.1884 10.7848 9.66267 10.4332C9.87936 10.2726 10.1852 10.3181 10.3458 10.5348C10.5064 10.7514 10.461 11.0573 10.2443 11.2179C9.61111 11.6873 8.83673 11.9651 8 11.9651C7.16327 11.9651 6.38889 11.6873 5.75569 11.2179C5.53901 11.0573 5.49356 10.7514 5.65417 10.5348ZM10.6047 7.24419C10.6047 7.78363 10.3131 8.22093 9.95349 8.22093C9.59386 8.22093 9.30233 7.78363 9.30233 7.24419C9.30233 6.70475 9.59386 6.26744 9.95349 6.26744C10.3131 6.26744 10.6047 6.70475 10.6047 7.24419ZM6.04651 8.22093C6.40614 8.22093 6.69767 7.78363 6.69767 7.24419C6.69767 6.70475 6.40614 6.26744 6.04651 6.26744C5.68688 6.26744 5.39535 6.70475 5.39535 7.24419C5.39535 7.78363 5.68688 8.22093 6.04651 8.22093Z" fill="#000"/>
+</g>
+</svg>
diff --git a/packages/trueforge-ui-sdk/src/icons/brain-regular.svg b/packages/trueforge-ui-sdk/src/icons/brain-regular.svg
new file mode 100644
index 000000000..1b3e2ab03
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/icons/brain-regular.svg
@@ -0,0 +1,3 @@
+<svg width="12" height="12" viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M0 6.9375C0 6.30469 0.234375 5.69531 0.609375 5.25C0.5625 5.0625 0.5625 4.875 0.5625 4.6875C0.5625 3.9375 0.9375 3.25781 1.52344 2.85938C1.61719 2.17969 2.01562 1.59375 2.60156 1.26562C2.90625 0.515625 3.63281 0 4.5 0C5.08594 0 5.60156 0.257812 6 0.65625C6.375 0.257812 6.89062 0 7.5 0C8.34375 0 9.07031 0.515625 9.375 1.26562C9.96094 1.59375 10.3594 2.17969 10.4531 2.85938C11.0391 3.25781 11.4375 3.9375 11.4375 4.6875C11.4375 4.875 11.4141 5.0625 11.3672 5.25C11.7422 5.69531 12 6.30469 12 6.9375C12 7.66406 11.6953 8.32031 11.2266 8.78906L11.25 8.8125C11.25 9.9375 10.4297 10.8516 9.375 11.0391C9 11.625 8.34375 12 7.59375 12C6.96094 12 6.375 11.7422 6 11.2969C5.60156 11.7422 5.01562 12 4.40625 12C3.63281 12 2.97656 11.625 2.60156 11.0391C1.54688 10.8516 0.75 9.9375 0.75 8.8125V8.78906C0.28125 8.32031 0 7.66406 0 6.9375ZM5.41406 9.9375H5.4375V2.0625C5.4375 1.54688 5.01562 1.125 4.5 1.125C3.96094 1.125 3.5625 1.54688 3.5625 2.0625V2.08594C3.07031 2.17969 2.69531 2.55469 2.625 3.04688C2.625 3.09375 2.625 3.14062 2.625 3.1875C2.625 3.32812 2.625 3.46875 2.67188 3.58594C2.50781 3.60938 2.32031 3.65625 2.17969 3.75C1.89844 3.9375 1.71094 4.24219 1.6875 4.57031C1.6875 4.61719 1.6875 4.66406 1.6875 4.6875C1.6875 5.03906 1.82812 5.34375 2.0625 5.55469C1.71094 5.69531 1.40625 5.97656 1.24219 6.32812C1.17188 6.51562 1.10156 6.72656 1.10156 6.9375C1.10156 7.5 1.42969 7.99219 1.875 8.25C1.92188 8.27344 1.94531 8.29688 1.99219 8.32031C1.96875 8.34375 1.96875 8.36719 1.94531 8.39062C1.89844 8.53125 1.875 8.67188 1.875 8.8125C1.875 9.32812 2.20312 9.77344 2.67188 9.91406C2.76562 9.9375 2.88281 9.9375 3 9.9375C3.11719 9.9375 3.25781 9.91406 3.375 9.89062C3.375 10.1016 3.44531 10.3125 3.58594 10.4766C3.77344 10.7344 4.05469 10.875 4.40625 10.875C4.92188 10.875 5.36719 10.4766 5.41406 9.9375ZM8.41406 2.08594L8.4375 2.0625C8.4375 1.54688 8.01562 1.125 7.5 1.125C6.96094 1.125 6.5625 1.54688 6.5625 2.0625V9.9375C6.60938 10.4766 7.05469 10.875 7.59375 10.875C7.92188 10.875 8.20312 10.7344 8.39062 10.4766C8.53125 10.3125 8.60156 10.1016 8.60156 9.89062C8.71875 9.91406 8.85938 9.9375 9 9.9375C9.09375 9.9375 9.21094 9.9375 9.30469 9.91406C9.77344 9.77344 10.125 9.32812 10.125 8.8125C10.125 8.67188 10.0781 8.53125 10.0312 8.39062C10.0078 8.36719 10.0078 8.34375 9.98438 8.32031C10.0312 8.29688 10.0547 8.27344 10.1016 8.25C10.5469 7.99219 10.875 7.5 10.875 6.9375C10.875 6.72656 10.8047 6.51562 10.7344 6.32812C10.5703 5.97656 10.2656 5.69531 9.91406 5.55469C10.1484 5.34375 10.3125 5.03906 10.3125 4.6875C10.3125 4.66406 10.2891 4.61719 10.2891 4.57031C10.2656 4.24219 10.0781 3.9375 9.79688 3.75C9.65625 3.65625 9.46875 3.60938 9.30469 3.58594C9.35156 3.46875 9.375 3.32812 9.375 3.1875C9.375 3.14062 9.35156 3.09375 9.35156 3.04688C9.28125 2.55469 8.90625 2.17969 8.41406 2.08594Z" fill="#000"/>
+</svg>
diff --git a/packages/trueforge-ui-sdk/src/icons/compare.svg b/packages/trueforge-ui-sdk/src/icons/compare.svg
new file mode 100644
index 000000000..eabdaab7d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/icons/compare.svg
@@ -0,0 +1,3 @@
+<svg width="14" height="17" viewBox="0 0 14 17" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M5.09091 16.5V15.0455H1.45455C1.05455 15.0455 0.712121 14.903 0.427273 14.6182C0.142424 14.3333 0 13.9909 0 13.5909V3.40909C0 3.00909 0.142424 2.66667 0.427273 2.38182C0.712121 2.09697 1.05455 1.95455 1.45455 1.95455H5.09091V0.5H6.54545V16.5H5.09091ZM8 15.0455V13.5909L11.6364 13.5909V3.40909H8V1.95455H11.6364C12.0364 1.95455 12.3788 2.09697 12.6636 2.38182C12.9485 2.66667 13.0909 3.00909 13.0909 3.40909V13.5909C13.0909 13.9909 12.9485 14.3333 12.6636 14.6182C12.3788 14.903 12.0364 15.0455 11.6364 15.0455H8Z" fill="#000"/>
+</svg>
diff --git a/packages/trueforge-ui-sdk/src/icons/mcp-server.svg b/packages/trueforge-ui-sdk/src/icons/mcp-server.svg
new file mode 100644
index 000000000..4ecd2770c
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/icons/mcp-server.svg
@@ -0,0 +1,11 @@
+<svg width="14" height="14" viewBox="0 0 14 14" fill="#000" xmlns="http://www.w3.org/2000/svg">
+<g clip-path="url(#clip0_5446_3655)">
+<path fill-rule="evenodd" clip-rule="evenodd" d="M9.15174 1.36702C8.86989 1.09272 8.49212 0.939234 8.09883 0.939234C7.70553 0.939234 7.32776 1.09272 7.04591 1.36702L1.43074 6.87369C1.33678 6.96502 1.21091 7.01611 1.07987 7.01611C0.948831 7.01611 0.822958 6.96502 0.728994 6.87369C0.68299 6.82895 0.646423 6.77544 0.621453 6.71633C0.596483 6.65721 0.583618 6.59369 0.583618 6.52952C0.583618 6.46535 0.596483 6.40183 0.621453 6.34272C0.646423 6.2836 0.68299 6.23009 0.728994 6.18536L6.34416 0.678689C6.81387 0.221585 7.44341 -0.0341797 8.09883 -0.0341797C8.75424 -0.0341797 9.38379 0.221585 9.85349 0.678689C10.1253 0.943 10.3306 1.26791 10.4527 1.62683C10.5748 1.98575 10.6101 2.36848 10.5558 2.74369C10.936 2.68962 11.3235 2.72356 11.6885 2.8429C12.0535 2.96224 12.3863 3.16379 12.6611 3.43202L12.6902 3.46119C12.9203 3.68489 13.1031 3.95243 13.2279 4.248C13.3528 4.54357 13.4171 4.86117 13.4171 5.18202C13.4171 5.50288 13.3528 5.82048 13.2279 6.11605C13.1031 6.41162 12.9203 6.67916 12.6902 6.90286L7.61174 11.8828C7.59642 11.8977 7.58423 11.9155 7.57591 11.9352C7.56759 11.9549 7.5633 11.976 7.5633 11.9974C7.5633 12.0188 7.56759 12.0399 7.57591 12.0596C7.58423 12.0793 7.59642 12.0971 7.61174 12.112L8.65474 13.1352C8.70075 13.1799 8.73731 13.2334 8.76228 13.2926C8.78725 13.3517 8.80012 13.4152 8.80012 13.4794C8.80012 13.5435 8.78725 13.607 8.76228 13.6662C8.73731 13.7253 8.70075 13.7788 8.65474 13.8235C8.56078 13.9149 8.43491 13.9659 8.30387 13.9659C8.17283 13.9659 8.04696 13.9149 7.95299 13.8235L6.90999 12.8009C6.80257 12.6966 6.71717 12.5717 6.65886 12.4337C6.60054 12.2957 6.5705 12.1475 6.5705 11.9977C6.5705 11.8479 6.60054 11.6996 6.65886 11.5617C6.71717 11.4237 6.80257 11.2988 6.90999 11.1944L11.9885 6.21394C12.1264 6.07968 12.2361 5.91914 12.3109 5.74181C12.3858 5.56447 12.4244 5.37393 12.4244 5.18144C12.4244 4.98895 12.3858 4.79841 12.3109 4.62107C12.2361 4.44374 12.1264 4.2832 11.9885 4.14894L11.9593 4.12036C11.6778 3.84634 11.3005 3.69287 10.9076 3.69254C10.5148 3.69222 10.1372 3.84506 9.85524 4.11861L5.67158 8.22177L5.67041 8.22294L5.61324 8.27952C5.51925 8.37103 5.39326 8.42223 5.26208 8.42223C5.1309 8.42223 5.0049 8.37103 4.91091 8.27952C4.86491 8.23478 4.82834 8.18128 4.80337 8.12216C4.7784 8.06305 4.76553 7.99953 4.76553 7.93536C4.76553 7.87118 4.7784 7.80766 4.80337 7.74855C4.82834 7.68944 4.86491 7.63593 4.91091 7.59119L9.15349 3.43027C9.29105 3.29592 9.40033 3.1354 9.47488 2.95816C9.54943 2.78093 9.58776 2.59056 9.58759 2.39828C9.58743 2.206 9.54878 2.0157 9.47393 1.83859C9.39907 1.66147 9.28953 1.50114 9.15174 1.36702Z" fill="#000"/>
+<path fill-rule="evenodd" clip-rule="evenodd" d="M8.44964 2.74425C8.49564 2.69951 8.53221 2.646 8.55718 2.58689C8.58215 2.52777 8.59501 2.46425 8.59501 2.40008C8.59501 2.33591 8.58215 2.27239 8.55718 2.21328C8.53221 2.15416 8.49564 2.10066 8.44964 2.05592C8.35564 1.96441 8.22965 1.91321 8.09847 1.91321C7.96729 1.91321 7.84129 1.96441 7.7473 2.05592L3.59455 6.12875C3.36454 6.35245 3.1817 6.61999 3.05685 6.91556C2.932 7.21113 2.86768 7.52873 2.86768 7.84958C2.86768 8.17044 2.932 8.48804 3.05685 8.78361C3.1817 9.07918 3.36454 9.34672 3.59455 9.57042C4.06433 10.0274 4.69385 10.2831 5.34922 10.2831C6.00459 10.2831 6.63411 10.0274 7.10389 9.57042L11.2572 5.49758C11.3032 5.45284 11.3398 5.39934 11.3648 5.34022C11.3897 5.28111 11.4026 5.21759 11.4026 5.15342C11.4026 5.08925 11.3897 5.02573 11.3648 4.96661C11.3398 4.9075 11.3032 4.85399 11.2572 4.80925C11.1632 4.71774 11.0372 4.66654 10.9061 4.66654C10.7749 4.66654 10.6489 4.71774 10.5549 4.80925L6.40214 8.88208C6.12029 9.15639 5.74252 9.30987 5.34922 9.30987C4.95592 9.30987 4.57815 9.15639 4.2963 8.88208C4.15836 8.74782 4.04873 8.58729 3.97386 8.40995C3.899 8.23261 3.86043 8.04207 3.86043 7.84958C3.86043 7.65709 3.899 7.46655 3.97386 7.28922C4.04873 7.11188 4.15836 6.95134 4.2963 6.81708L8.44964 2.74425Z" fill="#000"/>
+</g>
+<defs>
+<clipPath id="clip0_5446_3655">
+<rect width="14" height="14" fill="white"/>
+</clipPath>
+</defs>
+</svg>
diff --git a/packages/trueforge-ui-sdk/src/icons/registerAgentIcons.ts b/packages/trueforge-ui-sdk/src/icons/registerAgentIcons.ts
new file mode 100644
index 000000000..99b6f476e
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/icons/registerAgentIcons.ts
@@ -0,0 +1,21 @@
+import type React from 'react';
+
+import { registerIcons } from './IconRegistry.js';
+
+import Agent2Icon from './agent-2.svg';
+import AiIcon from './ai.svg';
+import BrainRegularIcon from './brain-regular.svg';
+import CompareIcon from './compare.svg';
+import McpServerIcon from './mcp-server.svg';
+import SearchGlobeIcon from './search-globe.svg';
+
+type SvgIcon = React.FC<React.SVGProps<SVGSVGElement>>;
+
+registerIcons({
+ 'mcp-server': McpServerIcon as unknown as SvgIcon,
+ 'agent-2': Agent2Icon as unknown as SvgIcon,
+ compare: CompareIcon as unknown as SvgIcon,
+ ai: AiIcon as unknown as SvgIcon,
+ searchGlobe: SearchGlobeIcon as unknown as SvgIcon,
+ 'brain-regular': BrainRegularIcon as unknown as SvgIcon,
+});
diff --git a/packages/trueforge-ui-sdk/src/icons/search-globe.svg b/packages/trueforge-ui-sdk/src/icons/search-globe.svg
new file mode 100644
index 000000000..7e00b8a74
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/icons/search-globe.svg
@@ -0,0 +1,3 @@
+<svg width="14" height="14" viewBox="0 0 14 14" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M7 0C10.8555 0 14 3.14453 14 7C14 10.8828 10.8555 14 7 14C3.11719 14 0 10.8828 0 7C0 3.14453 3.11719 0 7 0ZM7 12.6875C7.19141 12.6875 7.71094 12.4961 8.28516 11.375C8.53125 10.8828 8.72266 10.3086 8.88672 9.625H5.08594C5.25 10.3086 5.44141 10.8828 5.6875 11.375C6.26172 12.4961 6.78125 12.6875 7 12.6875ZM4.86719 8.3125H9.10547C9.16016 7.90234 9.1875 7.46484 9.1875 7C9.1875 6.5625 9.16016 6.125 9.10547 5.6875H4.86719C4.8125 6.125 4.8125 6.5625 4.8125 7C4.8125 7.46484 4.8125 7.90234 4.86719 8.3125ZM8.88672 4.375C8.72266 3.71875 8.53125 3.14453 8.28516 2.65234C7.71094 1.53125 7.19141 1.3125 7 1.3125C6.78125 1.3125 6.26172 1.53125 5.6875 2.65234C5.44141 3.14453 5.25 3.71875 5.08594 4.375H8.88672ZM10.418 5.6875C10.4727 6.125 10.5 6.5625 10.5 7C10.5 7.46484 10.4727 7.90234 10.418 8.3125H12.5234C12.6328 7.90234 12.6875 7.46484 12.6875 7C12.6875 6.5625 12.6328 6.125 12.5234 5.6875H10.418ZM9.35156 1.83203C9.73438 2.54297 10.0352 3.41797 10.2266 4.375H12.0312C11.457 3.25391 10.5 2.35156 9.35156 1.83203ZM4.62109 1.83203C3.47266 2.35156 2.51562 3.25391 1.94141 4.375H3.74609C3.9375 3.41797 4.23828 2.54297 4.62109 1.83203ZM1.3125 7C1.3125 7.46484 1.33984 7.90234 1.44922 8.3125H3.55469C3.5 7.90234 3.5 7.46484 3.5 7C3.5 6.5625 3.5 6.125 3.55469 5.6875H1.44922C1.33984 6.125 1.3125 6.5625 1.3125 7ZM12.0312 9.625H10.2266C10.0352 10.6094 9.73438 11.4844 9.35156 12.1953C10.5 11.6758 11.457 10.7734 12.0312 9.625ZM3.74609 9.625H1.94141C2.51562 10.7734 3.47266 11.6758 4.62109 12.1953C4.23828 11.4844 3.9375 10.6094 3.74609 9.625Z" fill="#000"/>
+</svg>
diff --git a/packages/trueforge-ui-sdk/src/index.ts b/packages/trueforge-ui-sdk/src/index.ts
new file mode 100644
index 000000000..d80af35b0
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/index.ts
@@ -0,0 +1,333 @@
+'use client';
+
+import './icons/registerAgentIcons.js';
+
+export { BrandIcon, BrandLogo } from './theme/brand.js';
+export { defaultSlots } from './theme/defaultSlots.js';
+export { PRESETS, resolvePresetTokens } from './theme/presets/index.js';
+export { SlotsProvider, useSlot, useThemeMode } from './theme/SlotsProvider.js';
+export type { AtomSlots, SlotOverrides, ThemeMode } from './theme/SlotsProvider.js';
+export {
+ ThemeProvider,
+ useBrand,
+ useContentClassNames,
+ useOptionalContentClassNames,
+ useThemeIcons,
+} from './theme/ThemeProvider.js';
+export type {
+ BrandConfig,
+ BrandImage,
+ ContentClassNames,
+ IconMap,
+ LayoutProp,
+ SemanticTokens,
+ ThemeConfig,
+ IconProps as ThemeIconProps,
+ ThemePreset,
+} from './theme/types.js';
+
+export { BottomSheet } from './atoms/primitives/BottomSheet.js';
+export type { BottomSheetProps } from './atoms/primitives/BottomSheet.js';
+export type { ButtonProps, ButtonSize, ButtonVariant } from './atoms/primitives/Button.js';
+export { CenteredModal } from './atoms/primitives/CenteredModal.js';
+export type { CenteredModalProps } from './atoms/primitives/CenteredModal.js';
+export type { IconButtonProps } from './atoms/primitives/IconButton.js';
+export { Icon } from './icons/Icon.js';
+export type { IconProps } from './icons/Icon.js';
+
+export { Avatar, AvatarFallback, AvatarImage } from './atoms/primitives/Avatar.js';
+export type { AvatarFallbackProps, AvatarImageProps, AvatarProps } from './atoms/primitives/Avatar.js';
+
+export { AssistantMessageBubble } from './atoms/AssistantMessageBubble.js';
+export type { AssistantMessageBubbleProps } from './atoms/AssistantMessageBubble.js';
+export { ChatFileDownload } from './atoms/ChatFileDownload.js';
+export type { ChatFileDownloadFile, ChatFileDownloadProps } from './atoms/ChatFileDownload.js';
+export { CodeEditor } from './atoms/CodeEditor.js';
+export type { CodeEditorProps } from './atoms/CodeEditor.js';
+export { HistoryLoader } from './atoms/HistoryLoader.js';
+export type { HistoryLoaderProps } from './atoms/HistoryLoader.js';
+export { Markdown, preloadMarkdownOpenUI } from './atoms/Markdown.js';
+export type { MarkdownProps } from './atoms/Markdown.js';
+export { MessageActionBar } from './atoms/MessageActionBar.js';
+export type { MessageActionBarProps } from './atoms/MessageActionBar.js';
+export { MessageErrorBanner } from './atoms/MessageErrorBanner.js';
+export type { MessageErrorBannerProps } from './atoms/MessageErrorBanner.js';
+export { MessageIndicator } from './atoms/MessageIndicator.js';
+export type { MessageIndicatorProps } from './atoms/MessageIndicator.js';
+export { MessageTimestamp } from './atoms/MessageTimestamp.js';
+export type { MessageTimestampProps } from './atoms/MessageTimestamp.js';
+export { MonacoEditorCore } from './atoms/MonacoEditorCore.js';
+export type { MonacoEditorCoreProps } from './atoms/MonacoEditorCore.js';
+export { OpenUiFenceBlock } from './atoms/OpenUiFenceBlock.js';
+export type { OpenUiFenceBlockProps } from './atoms/OpenUiFenceBlock.js';
+export { SandboxArtifactDownload } from './atoms/SandboxArtifactDownload.js';
+export type { SandboxArtifactDownloadProps } from './atoms/SandboxArtifactDownload.js';
+export { ScrollToBottomButton } from './atoms/ScrollToBottomButton.js';
+export type { ScrollToBottomButtonProps } from './atoms/ScrollToBottomButton.js';
+export { MessageListSkeleton } from './atoms/Skeletons.js';
+export type { MessageListSkeletonProps } from './atoms/Skeletons.js';
+export { SyntaxHighlighter } from './atoms/SyntaxHighlighter.js';
+export type { SyntaxHighlighterProps } from './atoms/SyntaxHighlighter.js';
+export { MessageGroup, ThreadComposerAreaShell, ThreadRootShell, ThreadViewportShell } from './atoms/ThreadShell.js';
+export type {
+ MessageGroupProps,
+ ThreadComposerAreaShellProps,
+ ThreadRootShellProps,
+ ThreadViewportShellProps,
+} from './atoms/ThreadShell.js';
+export { UserMessageActionBar } from './atoms/UserMessageActionBar.js';
+export type { UserMessageActionBarProps } from './atoms/UserMessageActionBar.js';
+export { UserMessageBubble } from './atoms/UserMessageBubble.js';
+export type { UserMessageBubbleProps } from './atoms/UserMessageBubble.js';
+export { UserMessageEdit } from './atoms/UserMessageEdit.js';
+export type { UserMessageEditProps } from './atoms/UserMessageEdit.js';
+export { WelcomeScreen } from './atoms/WelcomeScreen.js';
+export type { WelcomeScreenProps } from './atoms/WelcomeScreen.js';
+
+export { AgentStepsCard } from './atoms/adapters/AgentStepsCardAdapter.js';
+export type { AgentStepsCardProps } from './atoms/adapters/AgentStepsCardAdapter.js';
+export type {
+ AskUserAnswerDraft,
+ AnsweredQuestion as AskUserAnsweredQuestion,
+ AskUserPromptProps,
+ Question as AskUserQuestion,
+ AskUserPromptProps as AskUserQuestionCardProps,
+} from './atoms/adapters/AskUserPromptAdapter.js';
+export type {
+ McpAuthPromptProps as McpAuthCardProps,
+ McpAuthPromptProps,
+ McpServer as McpAuthServer,
+} from './atoms/adapters/McpAuthPromptAdapter.js';
+export type { ReasoningCardProps } from './atoms/adapters/ReasoningCardAdapter.js';
+export { AttachmentCard, USER_MESSAGE_ATTACHMENT_PREVIEW_REM } from './atoms/AttachmentCard.js';
+export type { AttachmentCardProps, AttachmentCardSize } from './atoms/AttachmentCard.js';
+export { AttachmentPickerButton } from './atoms/AttachmentPickerButton.js';
+export type { AttachmentPickerButtonProps } from './atoms/AttachmentPickerButton.js';
+export { AttachmentPreviewDialog } from './atoms/AttachmentPreviewDialog.js';
+export type { AttachmentPreviewDialogProps } from './atoms/AttachmentPreviewDialog.js';
+export { ComposerLeftSection, ComposerRightSection, ComposerSendButton } from './atoms/ComposerSections.js';
+export type {
+ ComposerLeftSectionProps,
+ ComposerRightSectionProps,
+ ComposerSendButtonProps,
+} from './atoms/ComposerSections.js';
+export { ComposerShell } from './atoms/ComposerShell.js';
+export type { ComposerShellProps } from './atoms/ComposerShell.js';
+export { SandboxToolCallCard } from './atoms/SandboxToolCallCard.js';
+export type { SandboxToolCallCardProps } from './atoms/SandboxToolCallCard.js';
+export { SubAgentCard } from './atoms/SubAgentCard.js';
+export type { SubAgentCardProps } from './atoms/SubAgentCard.js';
+export {
+ ThreadListEmptyState,
+ ThreadListNewButton,
+ ThreadListRowSkeleton,
+ ThreadListShell,
+} from './atoms/ThreadListMisc.js';
+export type {
+ ThreadListEmptyStateProps,
+ ThreadListNewButtonProps,
+ ThreadListRowSkeletonProps,
+ ThreadListShellProps,
+} from './atoms/ThreadListMisc.js';
+export { ThreadListRow } from './atoms/ThreadListRow.js';
+export type { ThreadListRowProps } from './atoms/ThreadListRow.js';
+export { Toast, ToastStack } from './atoms/Toast.js';
+export type { ToastProps, ToastStackProps } from './atoms/Toast.js';
+export { ToolApprovalBar } from './atoms/ToolApprovalBar.js';
+export type { ToolApprovalBarProps } from './atoms/ToolApprovalBar.js';
+export { ToolCallCard } from './atoms/ToolCallCard.js';
+export type { ToolCallCardProps, ToolCallStatus } from './atoms/ToolCallCard.js';
+export { ToolCallContentBlock } from './atoms/ToolCallContentBlock.js';
+export type { ToolCallContentBlockProps } from './atoms/ToolCallContentBlock.js';
+export { ToolGroupCard } from './atoms/ToolGroupCard.js';
+export type { ToolGroupCardProps } from './atoms/ToolGroupCard.js';
+export { AgentStepsContainer } from './containers/AgentStepsContainer.js';
+export type { AgentStepsContainerProps } from './containers/AgentStepsContainer.js';
+export { AskUserContainer } from './containers/AskUserContainer.js';
+export { AssistantMessageContainer } from './containers/AssistantMessageContainer.js';
+export { AssistantTextContainer } from './containers/AssistantTextContainer.js';
+export {
+ ComposerAttachmentPickerContainer,
+ ComposerAttachmentsContainer,
+ MessageAttachmentsContainer,
+} from './containers/AttachmentsContainer.js';
+export { ComposerContainer } from './containers/ComposerContainer.js';
+export type { ComposerContainerProps } from './containers/ComposerContainer.js';
+export { ErrorToasterProvider, useErrorToaster, useErrorToasterOptional } from './containers/ErrorToasterContainer.js';
+export { HistoryLoaderContainer } from './containers/HistoryLoaderContainer.js';
+export { McpAuthContainer } from './containers/McpAuthContainer.js';
+export { default as PostMcpOauthScreen } from './containers/McpOauthContainer/PostMcpOauthScreen.js';
+export { ReasoningContainer } from './containers/ReasoningContainer.js';
+export { Thread } from './containers/Thread.js';
+export { ThreadContainer } from './containers/ThreadContainer.js';
+export type { ThreadContainerProps } from './containers/ThreadContainer.js';
+export { ThreadListContainer } from './containers/ThreadListContainer.js';
+export type { ThreadListContainerProps } from './containers/ThreadListContainer.js';
+export { ToolApprovalContainer } from './containers/ToolApprovalContainer.js';
+export type { ToolApprovalOption } from './containers/ToolApprovalContainer.js';
+export { ToolCallContainer } from './containers/ToolCallContainer.js';
+export { ToolCallContentBlockContainer } from './containers/ToolCallContentBlockContainer.js';
+export { ToolGroupContainer } from './containers/ToolGroupContainer.js';
+export type { ThreadGroupPart } from './containers/ToolGroupContainer.js';
+export { TrueforgeUI } from './containers/TrueforgeUI.js';
+export type {
+ ChatLayout,
+ TrueforgeBuiltInServerConfig,
+ TrueforgeServerConfig,
+ TrueforgeUIProps,
+} from './containers/TrueforgeUI.js';
+export { TrueFoundryChatProvider } from './containers/TrueFoundryChatProvider.js';
+export type { TrueFoundryChatProviderProps } from './containers/TrueFoundryChatProvider.js';
+export { UserEditComposerContainer } from './containers/UserEditComposerContainer.js';
+export { UserMessageContainer } from './containers/UserMessageContainer.js';
+export { ComposerBusyProvider, useComposerBusyState } from './hooks/useComposerBusyState.js';
+export type { ComposerBusyState } from './hooks/useComposerBusyState.js';
+export { threadHasPendingMcpAuth, useComposerPauseView } from './hooks/useComposerPauseView.js';
+export type { ComposerPauseView, ThreadPauseState } from './hooks/useComposerPauseView.js';
+export { MCP_AUTH_POPUP_CHANNEL, useMCPAuth } from './hooks/useMcpAuth.js';
+export type { McpAuthCallback, McpAuthPopupMessage, UseMCPAuthOptions } from './hooks/useMcpAuth.js';
+
+// Curated chrome hooks (same instance as the SDK runtime). Deep primitives: install @assistant-ui/react.
+export { useAui, useAuiState } from './assistant-ui.js';
+export type { AssistantState } from './assistant-ui.js';
+export { useTheme } from './theme/useTheme.js';
+
+// Runtime / server — consumer surface.
+export {
+ mergeAgentSpec,
+ trueFoundryAttachmentAdapter,
+ useTrueFoundryAgentRuntime,
+ useTrueFoundryAgentSpec,
+ useTrueFoundryCancel,
+ useTrueFoundryDownloadSandboxFile,
+ useTrueFoundryHistoryPagination,
+ useTrueFoundryMcpAuth,
+ useTrueFoundryRespondToToolApproval,
+ useTrueFoundryToolResponses,
+ useTrueFoundryUpdateAgentSpec,
+} from '@truefoundry/assistant-ui-runtime';
+export type {
+ DraftAgentConfig,
+ NamedAgentConfig,
+ TrueFoundryAgentConfig,
+ UseTrueFoundryAgentRuntimeOptions,
+} from '@truefoundry/assistant-ui-runtime';
+
+// Server port types + factory
+export { ClearChatButton } from './atoms/ClearChatButton.js';
+export { SelectAgentEmptyState } from './atoms/SelectAgentEmptyState.js';
+export { createTrueFoundryServer } from './server/createTrueFoundryServer.js';
+export type { CreateTrueFoundryServerOptions, TrueFoundryServer } from './server/createTrueFoundryServer.js';
+export {
+ ServerProvider,
+ useCatalogServer,
+ useOptionalCatalogServer,
+ useOptionalServer,
+ useServer,
+} from './server/ServerContext.js';
+export {
+ DEFAULT_AGENT_CONFIG,
+ ShellModeProvider,
+ useOptionalShellMode,
+ useShellMode,
+} from './server/ShellModeContext.js';
+export type { AgentConfig, ShellMode } from './server/ShellModeContext.js';
+export type {
+ AgentBuilderServer,
+ AgentChatServer,
+ AgentLibraryEntry,
+ AgentSkill,
+ AgentSpec,
+ AgentUIServer,
+ ApprovalDecision,
+ AuthenticateConnectorRequest,
+ CatalogServer,
+ ConnectorAuth,
+ ConnectorAuthApiKey,
+ ConnectorAuthNone,
+ ConnectorAuthOAuth,
+ ConnectorAuthPublic,
+ ConnectorAuthPublicApiKey,
+ ConnectorAuthPublicNone,
+ ConnectorAuthPublicOAuth,
+ ConnectorAuthType,
+ ConnectorAuthenticationResult,
+ ConnectorBase,
+ ConnectorCatalogEntry,
+ ConnectorCatalogServer,
+ ConnectorConfigBase,
+ ConnectorState,
+ CreateConnectorRequest,
+ CreateModelProviderRequest,
+ CreateSandboxRequest,
+ CreateSessionRequest,
+ CreateSkillRequest,
+ CreateSkillRequestBase,
+ DefinedSkill,
+ GithubSkill,
+ ImportGithubSkillRequest,
+ ListSessionEventsResponse,
+ ListSessionsOrder,
+ ListSessionsParams,
+ ListSessionsResponse,
+ ListTurnsResponse,
+ McpServerMount,
+ Model,
+ ModelCatalogServer,
+ ModelEntry,
+ ModelParams,
+ ModelProviderBase,
+ ModelProviderCatalogEntry,
+ ModelProviderConfigBase,
+ ModelSelection,
+ PageParams,
+ PageResult,
+ PreviousTurnIdInput,
+ ProviderType,
+ RegistrySkill,
+ SandboxBase,
+ SandboxCatalogEntry,
+ SandboxCatalogServer,
+ SandboxConfig,
+ SearchAgentsParams,
+ SelectRegistrySkillRequest,
+ Session,
+ SessionEvent,
+ SessionEventItem,
+ SkillBase,
+ SkillCatalogEntry,
+ SkillCatalogServer,
+ SkillConfigBase,
+ SkillMount,
+ TokenPagination,
+ ToolBase,
+ Turn,
+ TurnInputItem,
+ TurnState,
+ TurnStreamData,
+ TurnStreamingEvent,
+ UpdateConnectorRequest,
+ UpdateModelProviderRequest,
+ UpdateSandboxRequest,
+ UpdateSessionRequest,
+ UserMessage,
+ UserMessageContent,
+ UserToolApprovalEvent,
+ UserToolResponseEvent,
+} from './server/types.js';
+
+// Utils
+export { computeAgentStepsSplit } from './utils/computeAgentStepsSplit.js';
+export type { AgentStepsSplitResult } from './utils/computeAgentStepsSplit.js';
+
+export { AgentsLibrary } from './atoms/AgentsLibrary.js';
+export type { AgentsLibraryProps } from './atoms/AgentsLibrary.js';
+export { AgentsLibraryButton } from './atoms/AgentsLibraryButton.js';
+export type { AgentsLibraryButtonProps } from './atoms/AgentsLibraryButton.js';
+export { DraftCatalogProvider, useDraftCatalog } from './atoms/draft/DraftCatalogProvider.js';
+export { DraftComposerLeftSection, DraftComposerRightSection } from './atoms/draft/DraftComposerSections.js';
+export { DraftCompositeSelector } from './atoms/draft/DraftCompositeSelector.js';
+export type { DraftCompositeSelectorProps } from './atoms/draft/DraftCompositeSelector.js';
+export { DraftModelSelector } from './atoms/draft/DraftModelSelector.js';
+export type { DraftModelSelectorProps } from './atoms/draft/DraftModelSelector.js';
+export { SaveAgentButton } from './atoms/SaveAgentButton.js';
diff --git a/packages/trueforge-ui-sdk/src/layouts/DockLayout.tsx b/packages/trueforge-ui-sdk/src/layouts/DockLayout.tsx
new file mode 100644
index 000000000..941315688
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/layouts/DockLayout.tsx
@@ -0,0 +1,22 @@
+'use client';
+
+import { cn } from '../atoms/lib/cn.js';
+import { CompactLayoutProvider } from '../atoms/lib/CompactLayoutContext.js';
+import { StackChatPanel } from './StackChatPanel.js';
+
+/** Fixed-width right panel with list ↔ thread stack navigation. */
+export function DockLayout({ className }: { className?: string }) {
+ return (
+ <CompactLayoutProvider>
+ <div
+ data-aui-compact-layout
+ className={cn(
+ 'ml-auto flex h-full w-full max-w-[min(400px,100%)] min-h-0 min-w-0 flex-col border-l border-border bg-background shadow-[-4px_0_24px_color-mix(in_oklab,#000_6%,transparent)]',
+ className,
+ )}
+ >
+ <StackChatPanel />
+ </div>
+ </CompactLayoutProvider>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/layouts/DrawerLayout.tsx b/packages/trueforge-ui-sdk/src/layouts/DrawerLayout.tsx
new file mode 100644
index 000000000..d2dbcad36
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/layouts/DrawerLayout.tsx
@@ -0,0 +1,117 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+import { useAui } from '../assistant-ui.js';
+import { SaveAgentButton } from '../atoms/SaveAgentButton.js';
+import { SelectAgentEmptyState } from '../atoms/SelectAgentEmptyState.js';
+import { ShellActions } from '../atoms/ShellActions.js';
+import { auiButtonClass } from '../atoms/lib/buttonClasses.js';
+import { cn } from '../atoms/lib/cn.js';
+import TruefoundrySettingsBuilder from '../containers/SettingsBuilder/index.js';
+import { Thread } from '../containers/Thread.js';
+import { ThreadListContainer } from '../containers/ThreadListContainer.js';
+import { Icon } from '../icons/Icon.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+
+export function DrawerLayout({ className }: { className?: string }) {
+ const aui = useAui();
+ const shell = useOptionalShellMode();
+ const ClearChatButton = useSlot('ClearChatButton');
+ const [threadsOpen, setThreadsOpen] = useState(false);
+ const threadsBtnRef = useRef<HTMLButtonElement>(null);
+ const dialogRef = useRef<HTMLDivElement>(null);
+ const mainRef = useRef<HTMLDivElement>(null);
+ const wasOpen = useRef(false);
+ const isIdle = shell?.mode.type === 'idle';
+ const settingsOpen = shell?.settingsOpen === true;
+
+ useEffect(() => {
+ if (!threadsOpen) return;
+ const onKeyDown = (event: KeyboardEvent) => {
+ if (event.key === 'Escape') setThreadsOpen(false);
+ };
+ window.addEventListener('keydown', onKeyDown);
+ return () => window.removeEventListener('keydown', onKeyDown);
+ }, [threadsOpen]);
+
+ useEffect(() => {
+ const main = mainRef.current;
+ if (threadsOpen) {
+ wasOpen.current = true;
+ if (main) main.inert = true;
+ dialogRef.current?.focus();
+ return;
+ }
+ if (wasOpen.current) {
+ if (main) main.inert = false;
+ threadsBtnRef.current?.focus();
+ wasOpen.current = false;
+ }
+ }, [threadsOpen]);
+
+ const handleNewChat = () => {
+ if (shell?.isComposerEnabled) {
+ shell.openDraft();
+ } else {
+ aui.threads().switchToNewThread();
+ }
+ setThreadsOpen(false);
+ };
+
+ return (
+ <div className={cn('relative flex h-full min-h-0 w-full flex-col', className)}>
+ {!settingsOpen ? (
+ <header className="flex shrink-0 items-center justify-end gap-1 border-b border-border bg-background px-2 py-1.5">
+ <SaveAgentButton />
+ <ClearChatButton />
+ <ShellActions />
+ {shell?.isNewChatEnabled !== false ? (
+ <button
+ type="button"
+ aria-label="New chat"
+ title="New chat"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={handleNewChat}
+ >
+ <Icon name="plus" />
+ </button>
+ ) : null}
+ <button
+ ref={threadsBtnRef}
+ type="button"
+ aria-label="Sessions"
+ aria-expanded={threadsOpen}
+ className="text-muted-foreground hover:text-foreground inline-flex size-8 cursor-pointer items-center justify-center rounded-md"
+ onClick={() => setThreadsOpen(v => !v)}
+ >
+ <Icon name="clock-rotate-left" />
+ </button>
+ </header>
+ ) : null}
+ <div ref={mainRef} className="min-h-0 min-w-0 flex-1">
+ {settingsOpen ? <TruefoundrySettingsBuilder /> : isIdle ? <SelectAgentEmptyState /> : <Thread />}
+ </div>
+ {threadsOpen ? (
+ <>
+ <button
+ type="button"
+ aria-label="Close sessions"
+ className="absolute inset-0 z-[9] cursor-pointer bg-black/20"
+ onClick={() => setThreadsOpen(false)}
+ />
+ <div
+ ref={dialogRef}
+ className="absolute inset-y-0 right-0 z-10 flex w-full max-w-80 flex-col border-l border-border bg-background shadow-lg outline-none"
+ role="dialog"
+ aria-label="Sessions"
+ tabIndex={-1}
+ >
+ <ThreadListContainer onThreadOpen={() => setThreadsOpen(false)} />
+ </div>
+ </>
+ ) : null}
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx b/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx
new file mode 100644
index 000000000..87a72b812
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx
@@ -0,0 +1,197 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+import { useAui } from '../assistant-ui.js';
+import { auiButtonClass } from '../atoms/lib/buttonClasses.js';
+import { cn } from '../atoms/lib/cn.js';
+import { SaveAgentButton } from '../atoms/SaveAgentButton.js';
+import { SelectAgentEmptyState } from '../atoms/SelectAgentEmptyState.js';
+import { ShellActions } from '../atoms/ShellActions.js';
+import TruefoundrySettingsBuilder from '../containers/SettingsBuilder/index.js';
+import { Thread } from '../containers/Thread.js';
+import { ThreadListContainer } from '../containers/ThreadListContainer.js';
+import { Icon } from '../icons/Icon.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import { BrandIcon } from '../theme/brand.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+import { useBrand } from '../theme/ThemeProvider.js';
+
+// Survives ChatProvider remounts when openDraft / selectAgent bumps runtimeKey.
+let desktopCollapsed = false;
+
+export function SidebarLayout({ className }: { className?: string }) {
+ const aui = useAui();
+ const shell = useOptionalShellMode();
+ const brand = useBrand();
+ const AgentsLibraryButton = useSlot('AgentsLibraryButton');
+ const ClearChatButton = useSlot('ClearChatButton');
+ const [collapsed, setCollapsed] = useState(desktopCollapsed);
+ const setDesktopCollapsed = (value: boolean | ((prev: boolean) => boolean)) => {
+ setCollapsed(prev => {
+ const next = typeof value === 'function' ? value(prev) : value;
+ desktopCollapsed = next;
+ return next;
+ });
+ };
+ const [mobileNavOpen, setMobileNavOpen] = useState(false);
+ const menuBtnRef = useRef<HTMLButtonElement>(null);
+ const dialogRef = useRef<HTMLDivElement>(null);
+ const mainRef = useRef<HTMLDivElement>(null);
+ const wasOpen = useRef(false);
+ const isIdle = shell?.mode.type === 'idle';
+ const settingsOpen = shell?.settingsOpen === true;
+
+ useEffect(() => {
+ if (!mobileNavOpen) return;
+ const onKeyDown = (event: KeyboardEvent) => {
+ if (event.key === 'Escape') setMobileNavOpen(false);
+ };
+ window.addEventListener('keydown', onKeyDown);
+ return () => window.removeEventListener('keydown', onKeyDown);
+ }, [mobileNavOpen]);
+
+ useEffect(() => {
+ const main = mainRef.current;
+ if (mobileNavOpen) {
+ wasOpen.current = true;
+ if (main) main.inert = true;
+ dialogRef.current?.focus();
+ return;
+ }
+ if (wasOpen.current) {
+ if (main) main.inert = false;
+ menuBtnRef.current?.focus();
+ wasOpen.current = false;
+ }
+ }, [mobileNavOpen]);
+
+ const handleNewChat = () => {
+ if (shell?.isComposerEnabled) {
+ shell.openDraft();
+ return;
+ }
+ void Promise.resolve(aui.threads().switchToNewThread()).catch(() => undefined);
+ };
+
+ return (
+ <div className={cn('relative flex h-full min-h-0 w-full min-w-0', className)}>
+ {/* Desktop sidebar */}
+ <aside
+ className={cn(
+ 'hidden min-h-0 shrink-0 flex-col border-r border-border bg-background transition-[width] duration-300 ease-in-out md:flex',
+ collapsed ? 'w-16' : 'w-64',
+ )}
+ >
+ <div
+ className={cn('flex shrink-0 items-center px-3 py-3', collapsed ? 'flex-col gap-3' : 'justify-between gap-2')}
+ >
+ <div className={cn('flex min-w-0 items-center text-foreground', collapsed ? 'justify-center' : 'gap-2')}>
+ <BrandIcon className="size-6 shrink-0 object-contain" />
+ {!collapsed ? (
+ <span className="truncate text-lg font-semibold tracking-tight">{brand.name ?? 'TrueFoundry'}</span>
+ ) : null}
+ </div>
+ <button
+ type="button"
+ aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+ title={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+ aria-expanded={!collapsed}
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={() => setDesktopCollapsed(value => !value)}
+ >
+ <Icon name={collapsed ? 'panel-left-open' : 'panel-left-close'} />
+ </button>
+ </div>
+
+ {collapsed ? (
+ <nav className="flex min-h-0 flex-1 flex-col items-center gap-2 px-3" aria-label="Sidebar">
+ {shell?.isNewChatEnabled !== false ? (
+ <button
+ type="button"
+ aria-label="Start new chat"
+ title="New chat"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={handleNewChat}
+ >
+ <Icon name="pencil" />
+ </button>
+ ) : null}
+ <AgentsLibraryButton compact />
+ </nav>
+ ) : (
+ <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
+ <ThreadListContainer />
+ </div>
+ )}
+
+ <footer
+ className={cn(
+ 'flex shrink-0 border-t border-border px-3 py-2',
+ collapsed ? 'flex-col items-center gap-2' : 'items-center gap-1',
+ )}
+ >
+ <ShellActions className={collapsed ? 'flex-col' : undefined} />
+ </footer>
+ </aside>
+
+ <div className="flex min-h-0 min-w-0 flex-1 flex-col">
+ {/* Thread header: always on mobile; on desktop when Clear Chat / Save are relevant. Hidden while Settings owns the pane. */}
+ {!settingsOpen ? (
+ <header
+ className={cn(
+ 'flex shrink-0 items-center gap-1 border-b border-border bg-background px-2 py-1.5',
+ isIdle && 'md:hidden',
+ )}
+ >
+ <button
+ ref={menuBtnRef}
+ type="button"
+ aria-label="Sessions"
+ aria-expanded={mobileNavOpen}
+ className={cn(auiButtonClass({ variant: 'ghost', size: 'icon' }), 'md:hidden')}
+ onClick={() => setMobileNavOpen(true)}
+ >
+ <Icon name="bars" />
+ </button>
+ <span className="min-w-0 flex-1" />
+ <SaveAgentButton />
+ <ClearChatButton />
+ <div className="md:hidden">
+ <ShellActions />
+ </div>
+ </header>
+ ) : null}
+
+ <div ref={mainRef} className="min-h-0 min-w-0 flex-1">
+ {settingsOpen ? <TruefoundrySettingsBuilder /> : isIdle ? <SelectAgentEmptyState /> : <Thread />}
+ </div>
+ </div>
+
+ {/* Mobile sessions drawer */}
+ {mobileNavOpen ? (
+ <>
+ <button
+ type="button"
+ aria-label="Close sessions"
+ className="absolute inset-0 z-[9] cursor-pointer bg-black/20 md:hidden"
+ onClick={() => setMobileNavOpen(false)}
+ />
+ <div
+ ref={dialogRef}
+ className="absolute inset-y-0 left-0 z-10 flex w-full max-w-80 flex-col border-r border-border bg-background shadow-lg outline-none md:hidden"
+ role="dialog"
+ aria-label="Sessions"
+ tabIndex={-1}
+ >
+ <div className="flex shrink-0 items-center gap-2 border-b border-border px-3 py-3 text-foreground">
+ <BrandIcon className="size-6 shrink-0 object-contain" />
+ <span className="truncate text-lg font-semibold tracking-tight">{brand.name ?? 'TrueFoundry'}</span>
+ </div>
+ <ThreadListContainer onThreadOpen={() => setMobileNavOpen(false)} />
+ </div>
+ </>
+ ) : null}
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/layouts/StackChatPanel.tsx b/packages/trueforge-ui-sdk/src/layouts/StackChatPanel.tsx
new file mode 100644
index 000000000..7b8c90d4e
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/layouts/StackChatPanel.tsx
@@ -0,0 +1,81 @@
+'use client';
+
+import { useEffect, useState, type ReactNode } from 'react';
+
+import { useAui } from '../assistant-ui.js';
+import { SaveAgentButton } from '../atoms/SaveAgentButton.js';
+import { SelectAgentEmptyState } from '../atoms/SelectAgentEmptyState.js';
+import { ShellActions } from '../atoms/ShellActions.js';
+import { auiButtonClass } from '../atoms/lib/buttonClasses.js';
+import { cn } from '../atoms/lib/cn.js';
+import TruefoundrySettingsBuilder from '../containers/SettingsBuilder/index.js';
+import { Thread } from '../containers/Thread.js';
+import { ThreadListContainer } from '../containers/ThreadListContainer.js';
+import { Icon } from '../icons/Icon.js';
+import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import { useSlot } from '../theme/SlotsProvider.js';
+
+export type StackChatPanelProps = {
+ className?: string;
+ /** Extra actions in the thread header (e.g. close for widget). */
+ threadHeaderEnd?: ReactNode;
+};
+
+/**
+ * List XOR thread stack used by `dock` and `widget` layouts.
+ * Starts on a new chat; history icon opens the session list; New / select opens the thread.
+ */
+export function StackChatPanel({ className, threadHeaderEnd }: StackChatPanelProps) {
+ const [view, setView] = useState<'list' | 'thread'>('thread');
+ const aui = useAui();
+ const shell = useOptionalShellMode();
+ const ClearChatButton = useSlot('ClearChatButton');
+ const isIdle = shell?.mode.type === 'idle';
+ const settingsOpen = shell?.settingsOpen === true;
+
+ useEffect(() => {
+ if (isIdle) return;
+ void Promise.resolve(aui.threads().switchToNewThread()).catch(() => undefined);
+ }, [aui, isIdle]);
+
+ if (settingsOpen) {
+ return (
+ <div className={cn('flex h-full min-h-0 flex-col', className)}>
+ <TruefoundrySettingsBuilder />
+ </div>
+ );
+ }
+
+ if (view === 'list') {
+ return (
+ <div className={cn('flex h-full min-h-0 flex-col', className)}>
+ <ThreadListContainer onThreadOpen={() => setView('thread')} />
+ <footer className="flex shrink-0 justify-end border-t border-border px-2 py-1.5">
+ <ShellActions />
+ </footer>
+ </div>
+ );
+ }
+
+ return (
+ <div className={cn('flex h-full min-h-0 flex-col', className)}>
+ <header className="flex shrink-0 items-center gap-1 border-b border-border px-2 py-1.5">
+ <button
+ type="button"
+ aria-label="Sessions"
+ title="Sessions"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={() => setView('list')}
+ >
+ <Icon name="clock-rotate-left" />
+ </button>
+ <span className="min-w-0 flex-1" />
+ <SaveAgentButton />
+ <ClearChatButton />
+ <ShellActions />
+ {threadHeaderEnd}
+ </header>
+ <div className="min-h-0 flex-1">{isIdle ? <SelectAgentEmptyState /> : <Thread />}</div>
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/layouts/WidgetLayout.tsx b/packages/trueforge-ui-sdk/src/layouts/WidgetLayout.tsx
new file mode 100644
index 000000000..97e004888
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/layouts/WidgetLayout.tsx
@@ -0,0 +1,94 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+import { auiButtonClass } from '../atoms/lib/buttonClasses.js';
+import { cn } from '../atoms/lib/cn.js';
+import { CompactLayoutProvider } from '../atoms/lib/CompactLayoutContext.js';
+import { Icon } from '../icons/Icon.js';
+import { BrandIcon } from '../theme/brand.js';
+import { StackChatPanel } from './StackChatPanel.js';
+
+/** FAB-anchored panel with the same list ↔ thread stack as `dock`. */
+export function WidgetLayout({ className }: { className?: string }) {
+ const [open, setOpen] = useState(false);
+ const fabRef = useRef<HTMLButtonElement>(null);
+ const dialogRef = useRef<HTMLDivElement>(null);
+ const wasOpen = useRef(false);
+
+ useEffect(() => {
+ if (!open) return;
+ const onKeyDown = (event: KeyboardEvent) => {
+ if (event.key === 'Escape' && !dialogRef.current?.querySelector('dialog[open]')) {
+ setOpen(false);
+ }
+ };
+ window.addEventListener('keydown', onKeyDown);
+ return () => window.removeEventListener('keydown', onKeyDown);
+ }, [open]);
+
+ useEffect(() => {
+ if (open) {
+ wasOpen.current = true;
+ dialogRef.current?.focus();
+ return;
+ }
+ if (wasOpen.current) {
+ fabRef.current?.focus();
+ wasOpen.current = false;
+ }
+ }, [open]);
+
+ return (
+ <div className={cn('pointer-events-none relative h-full min-h-0 w-full', className)}>
+ {open ? (
+ <div
+ ref={dialogRef}
+ data-aui-compact-layout
+ className="pointer-events-auto absolute right-[max(1.25rem,env(safe-area-inset-right,0px))] bottom-[calc(5.25rem+env(safe-area-inset-bottom,0px))] z-[19] flex h-[min(560px,calc(100%-6.5rem-env(safe-area-inset-bottom,0px)))] max-h-[calc(100%-6.5rem)] w-[min(380px,calc(100%-2.5rem))] flex-col overflow-hidden rounded-xl border border-border bg-background shadow-[0_16px_48px_color-mix(in_oklab,#000_14%,transparent)] outline-none"
+ role="dialog"
+ aria-modal={true}
+ aria-label="Chat"
+ tabIndex={-1}
+ >
+ <CompactLayoutProvider>
+ <StackChatPanel
+ threadHeaderEnd={
+ <button
+ type="button"
+ aria-label="Close"
+ title="Close"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={() => setOpen(false)}
+ >
+ <Icon name="xmark" />
+ </button>
+ }
+ />
+ </CompactLayoutProvider>
+ </div>
+ ) : null}
+ {/* Native FAB: inline colors beat host unlayered Tailwind (SDK utilities are layered). */}
+ <button
+ ref={fabRef}
+ type="button"
+ className="pointer-events-auto absolute right-[max(1.25rem,env(safe-area-inset-right,0px))] bottom-[max(1.25rem,env(safe-area-inset-bottom,0px))] z-20 flex size-14 cursor-pointer items-center justify-center rounded-full text-sm font-medium shadow-[0_8px_24px_color-mix(in_oklab,var(--primary)_45%,transparent)]"
+ style={{
+ backgroundColor: 'var(--primary)',
+ color: 'var(--primary-foreground)',
+ }}
+ aria-expanded={open}
+ aria-label={open ? 'Close chat' : 'Open chat'}
+ onClick={() => setOpen(v => !v)}
+ >
+ {open ? (
+ <span aria-hidden className="text-xl leading-none">
+ ×
+ </span>
+ ) : (
+ <BrandIcon className="size-6" />
+ )}
+ </button>
+ </div>
+ );
+}
diff --git a/packages/trueforge-ui-sdk/src/openui.css b/packages/trueforge-ui-sdk/src/openui.css
new file mode 100644
index 000000000..4d79f4d2a
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/openui.css
@@ -0,0 +1,40 @@
+@import "@openuidev/react-ui/defaults.css";
+@import "@openuidev/react-ui/styles/index.css";
+@source ".";
+
+/*
+ * Keep OpenUI embeds inside the chat column. GenUI widgets (charts, tables)
+ * often assume a wide host; without min-w-0 / max-w-full they expand the
+ * flex parent and the Markdown shell shows a horizontal scrollbar.
+ */
+.aui-openui,
+.markdown-openui-scope {
+ box-sizing: border-box;
+ width: 100%;
+ max-width: 100%;
+ min-width: 0;
+}
+
+.aui-openui *,
+.markdown-openui-scope * {
+ box-sizing: border-box;
+}
+
+.aui-openui .recharts-responsive-container,
+.aui-openui .recharts-wrapper,
+.aui-openui [class*="openui-card"],
+.aui-openui [class*="openui-chart"],
+.aui-openui [class*="openui-table"],
+.aui-openui [class*="openui-scrollable"] {
+ max-width: 100%;
+}
+
+.markdown-openui-scope .openui-scrollable-table-wrapper {
+ overflow: hidden;
+ max-width: 100%;
+}
+
+.markdown-openui-scope .openui-table-container {
+ max-width: 100%;
+ overflow-x: auto;
+}
diff --git a/packages/trueforge-ui-sdk/src/server/ServerContext.test.tsx b/packages/trueforge-ui-sdk/src/server/ServerContext.test.tsx
new file mode 100644
index 000000000..da541afd8
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/server/ServerContext.test.tsx
@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+import { renderHook } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { ServerProvider, useCatalogServer, useOptionalCatalogServer } from './ServerContext.js';
+import type { AgentUIServer, CatalogServer } from './types.js';
+
+const catalog: CatalogServer = {
+ modelCatalog: {
+ getModelProviderCatalog: vi.fn(async () => []),
+ listModelProviders: vi.fn(async () => []),
+ createModelProvider: vi.fn(async req => ({
+ id: 'p1',
+ type: req.type,
+ name: req.name,
+ models: req.models,
+ })),
+ updateModelProvider: vi.fn(async req => ({
+ id: req.id,
+ type: req.type,
+ name: req.name,
+ models: req.models,
+ })),
+ },
+ connectorCatalog: {
+ getConnectorCatalog: vi.fn(async () => []),
+ listConnectors: vi.fn(async () => []),
+ getToolsByConnectorId: vi.fn(async () => []),
+ createConnector: vi.fn(async req => ({
+ id: 'c1',
+ name: req.name,
+ description: '',
+ url: req.url,
+ auth:
+ req.auth.type === 'oauth'
+ ? { type: 'oauth' as const, authUrl: 'https://example.com/oauth' }
+ : req.auth.type === 'apiKey'
+ ? { type: 'apiKey' as const }
+ : { type: 'none' as const },
+ requiresAuth: req.auth.type === 'oauth',
+ authenticated: false,
+ })),
+ updateConnector: vi.fn(async req => ({
+ id: req.id,
+ name: req.name,
+ description: '',
+ url: req.url,
+ auth:
+ req.auth.type === 'oauth'
+ ? { type: 'oauth' as const, authUrl: 'https://example.com/oauth' }
+ : req.auth.type === 'apiKey'
+ ? { type: 'apiKey' as const }
+ : { type: 'none' as const },
+ requiresAuth: req.auth.type === 'oauth',
+ authenticated: false,
+ })),
+ authenticateConnector: vi.fn(async ({ id }) => ({
+ id,
+ name: '',
+ description: '',
+ url: '',
+ auth: { type: 'oauth' as const, authUrl: 'https://example.com/oauth' },
+ requiresAuth: true,
+ authenticated: true,
+ })),
+ disconnectConnector: vi.fn(async ({ id }) => ({
+ id,
+ name: '',
+ description: '',
+ url: '',
+ auth: { type: 'none' as const },
+ requiresAuth: false,
+ authenticated: false,
+ })),
+ },
+};
+
+function wrap(server: AgentUIServer) {
+ return function Wrapper({ children }: { children: ReactNode }) {
+ return <ServerProvider server={server}>{children}</ServerProvider>;
+ };
+}
+
+describe('useCatalogServer', () => {
+ it('returns server.catalog when present', () => {
+ const server = { catalog } as unknown as AgentUIServer;
+ const { result } = renderHook(() => useCatalogServer(), {
+ wrapper: wrap(server),
+ });
+ expect(result.current).toBe(catalog);
+ });
+
+ it('throws when catalog is omitted', () => {
+ const server = {} as unknown as AgentUIServer;
+ expect(() => renderHook(() => useCatalogServer(), { wrapper: wrap(server) })).toThrow(
+ /requires AgentUIServer\.catalog/,
+ );
+ });
+
+ it('useOptionalCatalogServer returns null when omitted', () => {
+ const server = {} as unknown as AgentUIServer;
+ const { result } = renderHook(() => useOptionalCatalogServer(), {
+ wrapper: wrap(server),
+ });
+ expect(result.current).toBeNull();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/server/ServerContext.tsx b/packages/trueforge-ui-sdk/src/server/ServerContext.tsx
new file mode 100644
index 000000000..017674593
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/server/ServerContext.tsx
@@ -0,0 +1,35 @@
+'use client';
+
+import { createContext, useContext, type ReactNode } from 'react';
+
+import type { AgentUIServer, CatalogServer } from './types.js';
+
+const ServerContext = createContext<AgentUIServer | null>(null);
+
+export function ServerProvider({ server, children }: { server: AgentUIServer; children: ReactNode }) {
+ return <ServerContext.Provider value={server}>{children}</ServerContext.Provider>;
+}
+
+export function useServer(): AgentUIServer {
+ const server = useContext(ServerContext);
+ if (server == null) {
+ throw new Error('useServer must be used within a ServerProvider.');
+ }
+ return server;
+}
+
+export function useOptionalServer(): AgentUIServer | null {
+ return useContext(ServerContext);
+}
+
+export function useCatalogServer(): CatalogServer {
+ const server = useServer();
+ if (server.catalog == null) {
+ throw new Error('useCatalogServer requires AgentUIServer.catalog. Pass catalog to createTrueFoundryServer.');
+ }
+ return server.catalog;
+}
+
+export function useOptionalCatalogServer(): CatalogServer | null {
+ return useOptionalServer()?.catalog ?? null;
+}
diff --git a/packages/trueforge-ui-sdk/src/server/ShellModeContext.test.tsx b/packages/trueforge-ui-sdk/src/server/ShellModeContext.test.tsx
new file mode 100644
index 000000000..50b688970
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/server/ShellModeContext.test.tsx
@@ -0,0 +1,112 @@
+// @vitest-environment jsdom
+import { act, renderHook } from '@testing-library/react';
+import type { ReactNode } from 'react';
+import { describe, expect, it } from 'vitest';
+
+import { ShellModeProvider, useShellMode, type AgentConfig } from './ShellModeContext.js';
+
+function wrap(agentConfig?: AgentConfig) {
+ return function Wrapper({ children }: { children: ReactNode }) {
+ return <ShellModeProvider agentConfig={agentConfig}>{children}</ShellModeProvider>;
+ };
+}
+
+describe('ShellModeProvider', () => {
+ it('defaults to AgentLibraryWithComposer (draft + library)', () => {
+ const { result } = renderHook(() => useShellMode(), { wrapper: wrap() });
+ expect(result.current.mode.type).toBe('draft');
+ expect(result.current.isLibraryEnabled).toBe(true);
+ expect(result.current.isComposerEnabled).toBe(true);
+ expect(result.current.isNewChatEnabled).toBe(true);
+ });
+
+ it('locks SingleAgent and ignores selectAgent / openDraft', () => {
+ const { result } = renderHook(() => useShellMode(), {
+ wrapper: wrap({ mode: 'SingleAgent', name: 'locked' }),
+ });
+ expect(result.current.mode).toEqual({
+ type: 'named',
+ agentName: 'locked',
+ locked: true,
+ });
+ expect(result.current.isLibraryEnabled).toBe(false);
+ expect(result.current.isComposerEnabled).toBe(false);
+
+ act(() => result.current.selectAgent('other'));
+ act(() => result.current.openDraft());
+ expect(result.current.mode).toEqual({
+ type: 'named',
+ agentName: 'locked',
+ locked: true,
+ });
+ });
+
+ it('starts AgentLibrary idle, then selectAgent → named', () => {
+ const { result } = renderHook(() => useShellMode(), {
+ wrapper: wrap({ mode: 'AgentLibrary' }),
+ });
+ expect(result.current.mode.type).toBe('idle');
+ expect(result.current.isNewChatEnabled).toBe(false);
+ expect(result.current.isComposerEnabled).toBe(false);
+ expect(result.current.isLibraryEnabled).toBe(true);
+
+ act(() => result.current.selectAgent('alpha'));
+ expect(result.current.mode).toEqual({
+ type: 'named',
+ agentName: 'alpha',
+ locked: false,
+ });
+
+ const keyBefore = result.current.runtimeKey;
+ act(() => result.current.clearChat());
+ expect(result.current.mode.type).toBe('named');
+ expect(result.current.runtimeKey).not.toBe(keyBefore);
+ });
+
+ it('re-picking the current agent still changes runtimeKey', () => {
+ const { result } = renderHook(() => useShellMode(), {
+ wrapper: wrap({ mode: 'AgentLibrary' }),
+ });
+
+ act(() => result.current.selectAgent('alpha'));
+ const keyBefore = result.current.runtimeKey;
+
+ act(() => result.current.selectAgent('alpha'));
+ expect(result.current.mode).toEqual({
+ type: 'named',
+ agentName: 'alpha',
+ locked: false,
+ });
+ expect(result.current.runtimeKey).not.toBe(keyBefore);
+ });
+
+ it('AgentComposer stays draft; clearChat bumps draft epoch', () => {
+ const { result } = renderHook(() => useShellMode(), {
+ wrapper: wrap({
+ mode: 'AgentComposer',
+ defaultAgentSpec: { model: { name: 'openai-main/gpt-4.1' } },
+ }),
+ });
+ expect(result.current.mode.type).toBe('draft');
+ expect(result.current.isLibraryEnabled).toBe(false);
+ expect(result.current.isComposerEnabled).toBe(true);
+
+ act(() => result.current.selectAgent('nope'));
+ expect(result.current.mode.type).toBe('draft');
+
+ const keyBefore = result.current.runtimeKey;
+ act(() => result.current.clearChat());
+ expect(result.current.mode.type).toBe('draft');
+ expect(result.current.runtimeKey).not.toBe(keyBefore);
+ });
+
+ it('clearChat is a no-op while idle', () => {
+ const { result } = renderHook(() => useShellMode(), {
+ wrapper: wrap({ mode: 'AgentLibrary' }),
+ });
+ const key = result.current.runtimeKey;
+ act(() => result.current.clearChat());
+ expect(result.current.runtimeKey).toBe(key);
+ expect(result.current.mode.type).toBe('idle');
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/server/ShellModeContext.tsx b/packages/trueforge-ui-sdk/src/server/ShellModeContext.tsx
new file mode 100644
index 000000000..a9d0aee6a
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/server/ShellModeContext.tsx
@@ -0,0 +1,174 @@
+'use client';
+
+import { createContext, useCallback, useContext, useMemo, useRef, useState, type ReactNode } from 'react';
+
+import type { AgentSpec } from './types.js';
+
+/** Host-facing shell configuration for agent / library / composer chrome. */
+export type AgentConfig =
+ | { mode: 'SingleAgent'; name: string }
+ | { mode: 'AgentLibrary' }
+ | { mode: 'AgentComposer'; defaultAgentSpec?: AgentSpec }
+ | { mode: 'AgentLibraryWithComposer'; defaultAgentSpec?: AgentSpec };
+
+export const DEFAULT_AGENT_CONFIG: AgentConfig = {
+ mode: 'AgentLibraryWithComposer',
+};
+
+export type ShellMode =
+ | { type: 'idle' }
+ | { type: 'named'; agentName: string; locked: boolean }
+ | { type: 'draft'; defaultAgentSpec: AgentSpec };
+
+type ShellModeContextValue = {
+ mode: ShellMode;
+ /** Host agentConfig mode (capabilities source). */
+ agentConfigMode: AgentConfig['mode'];
+ /** Agents Library chrome. */
+ isLibraryEnabled: boolean;
+ /** Draft composer / Save Agent chrome. */
+ isComposerEnabled: boolean;
+ /** Sidebar / list New Chat control. */
+ isNewChatEnabled: boolean;
+ settingsOpen: boolean;
+ setSettingsOpen: (open: boolean) => void;
+ selectAgent: (agentName: string) => void;
+ openDraft: () => void;
+ /** Reset current named or draft chat; no-op when idle. */
+ clearChat: () => void;
+ /** Remount key for the chat runtime when mode/agent changes. */
+ runtimeKey: string;
+};
+
+const ShellModeContext = createContext<ShellModeContextValue | null>(null);
+
+const FALLBACK_DRAFT_SPEC: AgentSpec = {
+ model: { name: 'openai-main/gpt-4.1' },
+};
+
+function draftSeedFromConfig(config: AgentConfig): AgentSpec {
+ if (config.mode === 'AgentComposer' || config.mode === 'AgentLibraryWithComposer') {
+ return config.defaultAgentSpec ?? FALLBACK_DRAFT_SPEC;
+ }
+ return FALLBACK_DRAFT_SPEC;
+}
+
+function initialMode(config: AgentConfig, draftSeed: AgentSpec): ShellMode {
+ switch (config.mode) {
+ case 'SingleAgent':
+ return { type: 'named', agentName: config.name, locked: true };
+ case 'AgentLibrary':
+ return { type: 'idle' };
+ case 'AgentComposer':
+ case 'AgentLibraryWithComposer':
+ return { type: 'draft', defaultAgentSpec: draftSeed };
+ }
+}
+
+export function ShellModeProvider({
+ agentConfig = DEFAULT_AGENT_CONFIG,
+ children,
+}: {
+ agentConfig?: AgentConfig;
+ children: ReactNode;
+}) {
+ const draftSeedRef = useRef(draftSeedFromConfig(agentConfig));
+ if (
+ (agentConfig.mode === 'AgentComposer' || agentConfig.mode === 'AgentLibraryWithComposer') &&
+ agentConfig.defaultAgentSpec != null
+ ) {
+ draftSeedRef.current = agentConfig.defaultAgentSpec;
+ }
+ const draftSeed = draftSeedRef.current;
+
+ const isLibraryEnabled = agentConfig.mode === 'AgentLibrary' || agentConfig.mode === 'AgentLibraryWithComposer';
+ const isComposerEnabled = agentConfig.mode === 'AgentComposer' || agentConfig.mode === 'AgentLibraryWithComposer';
+ const isNewChatEnabled = agentConfig.mode !== 'AgentLibrary';
+ const locked = agentConfig.mode === 'SingleAgent';
+
+ const [mode, setMode] = useState<ShellMode>(() => initialMode(agentConfig, draftSeed));
+ const [draftEpoch, setDraftEpoch] = useState(0);
+ const [clearEpoch, setClearEpoch] = useState(0);
+ const [settingsOpen, setSettingsOpen] = useState(false);
+
+ const lockedAgentName = agentConfig.mode === 'SingleAgent' ? agentConfig.name : '';
+ const effectiveMode: ShellMode = useMemo(
+ () => (locked ? { type: 'named', agentName: lockedAgentName, locked: true } : mode),
+ [locked, lockedAgentName, mode],
+ );
+
+ const selectAgent = useCallback(
+ (name: string) => {
+ if (!isLibraryEnabled) return;
+ setMode({ type: 'named', agentName: name, locked: false });
+ // Re-picking the current agent must still remount the runtime.
+ setClearEpoch(n => n + 1);
+ },
+ [isLibraryEnabled],
+ );
+
+ const openDraft = useCallback(() => {
+ if (!isComposerEnabled) return;
+ setMode({ type: 'draft', defaultAgentSpec: draftSeedRef.current });
+ setDraftEpoch(n => n + 1);
+ }, [isComposerEnabled]);
+
+ const clearChat = useCallback(() => {
+ if (effectiveMode.type === 'idle') return;
+ if (effectiveMode.type === 'draft') {
+ setMode({ type: 'draft', defaultAgentSpec: draftSeedRef.current });
+ setDraftEpoch(n => n + 1);
+ return;
+ }
+ setClearEpoch(n => n + 1);
+ }, [effectiveMode]);
+
+ const runtimeKey =
+ effectiveMode.type === 'idle'
+ ? 'idle'
+ : effectiveMode.type === 'named'
+ ? `named:${effectiveMode.agentName}:${clearEpoch}`
+ : `draft:${effectiveMode.defaultAgentSpec.model.name}:${draftEpoch}`;
+
+ const value = useMemo<ShellModeContextValue>(
+ () => ({
+ mode: effectiveMode,
+ agentConfigMode: agentConfig.mode,
+ isLibraryEnabled,
+ isComposerEnabled,
+ isNewChatEnabled,
+ settingsOpen,
+ setSettingsOpen,
+ selectAgent,
+ openDraft,
+ clearChat,
+ runtimeKey,
+ }),
+ [
+ effectiveMode,
+ agentConfig.mode,
+ isLibraryEnabled,
+ isComposerEnabled,
+ isNewChatEnabled,
+ settingsOpen,
+ selectAgent,
+ openDraft,
+ clearChat,
+ runtimeKey,
+ ],
+ );
+
+ return <ShellModeContext.Provider value={value}>{children}</ShellModeContext.Provider>;
+}
+
+export function useShellMode(): ShellModeContextValue {
+ const ctx = useContext(ShellModeContext);
+ if (ctx == null) {
+ throw new Error('useShellMode must be used within a ShellModeProvider.');
+ }
+ return ctx;
+}
+
+export function useOptionalShellMode(): ShellModeContextValue | null {
+ return useContext(ShellModeContext);
+}
diff --git a/packages/trueforge-ui-sdk/src/server/TrueforgeServerConfig.ts b/packages/trueforge-ui-sdk/src/server/TrueforgeServerConfig.ts
new file mode 100644
index 000000000..111ffe880
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/server/TrueforgeServerConfig.ts
@@ -0,0 +1,25 @@
+import type { AgentUIServer, CatalogServer } from './types.js';
+
+/**
+ * Built-in backends init inside `<TrueforgeUI />`.
+ * Optional `catalog` is attached onto the resolved `AgentUIServer`.
+ */
+export type TrueforgeBuiltInServerConfig =
+ | {
+ type: 'truefoundry';
+ apiKey: string;
+ controlPlaneURL: string;
+ gatewayPlaneURL?: string;
+ catalog?: CatalogServer;
+ }
+ | ({
+ type: 'trueforge';
+ apiKey: string;
+ catalog?: CatalogServer;
+ } & Record<string, unknown>);
+
+/**
+ * `server` prop for `<TrueforgeUI />`: a built-in config, or a ready
+ * {@link AgentUIServer} passed directly (no `{ type: "custom" }` wrapper).
+ */
+export type TrueforgeServerConfig = TrueforgeBuiltInServerConfig | AgentUIServer;
diff --git a/packages/trueforge-ui-sdk/src/server/createTrueFoundryServer.test.ts b/packages/trueforge-ui-sdk/src/server/createTrueFoundryServer.test.ts
new file mode 100644
index 000000000..110a98714
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/server/createTrueFoundryServer.test.ts
@@ -0,0 +1,148 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { AgentChatServer, CatalogServer } from './types.js';
+
+import { createTrueFoundryServer } from './createTrueFoundryServer.js';
+
+describe('createTrueFoundryServer', () => {
+ it('composes chat server with builder callbacks', async () => {
+ const chatServer = {
+ createSession: vi.fn(),
+ listSessions: vi.fn(),
+ getSession: vi.fn(),
+ updateSession: vi.fn(),
+ createTurn: vi.fn(),
+ cancelSession: vi.fn(),
+ listTurns: vi.fn(),
+ getTurn: vi.fn(),
+ listEvents: vi.fn(),
+ } as unknown as AgentChatServer;
+
+ const getModels = vi.fn(async () => [{ name: 'm', provider: 'p', apiModel: 'p/m', modelId: 'm' }]);
+ const getSkills = vi.fn(async () => []);
+ const getMcp = vi.fn(async () => []);
+ const searchAgents = vi.fn(async () => [{ name: 'ask-ai-agent' }]);
+ const saveAgent = vi.fn(async () => ({ ok: true }));
+
+ const server = createTrueFoundryServer({
+ chatServer,
+ getModels,
+ getSkills,
+ getMcp,
+ searchAgents,
+ saveAgent,
+ });
+
+ expect(server.createSession).toBe(chatServer.createSession);
+ expect(server.listSessions).toBe(chatServer.listSessions);
+ expect(server.catalog).toBeUndefined();
+
+ await expect(server.getModels()).resolves.toHaveLength(1);
+ await expect(server.searchAgents({ query: 'ask' })).resolves.toEqual([{ name: 'ask-ai-agent' }]);
+ expect(searchAgents).toHaveBeenCalledWith({ query: 'ask' });
+
+ await server.saveAgent({
+ agentName: 'my-agent',
+ agentSpec: { model: { name: 'p/m' } },
+ });
+ expect(saveAgent).toHaveBeenCalled();
+ });
+
+ it('attaches optional catalog when provided', async () => {
+ const chatServer = {
+ createSession: vi.fn(),
+ listSessions: vi.fn(),
+ getSession: vi.fn(),
+ updateSession: vi.fn(),
+ createTurn: vi.fn(),
+ cancelSession: vi.fn(),
+ listTurns: vi.fn(),
+ getTurn: vi.fn(),
+ listEvents: vi.fn(),
+ } as unknown as AgentChatServer;
+
+ const catalog: CatalogServer = {
+ modelCatalog: {
+ getModelProviderCatalog: vi.fn(async () => []),
+ listModelProviders: vi.fn(async () => [{ id: 'openai', type: 'openai', name: 'OpenAI', models: [] }]),
+ createModelProvider: vi.fn(async req => ({
+ id: 'openai',
+ type: req.type,
+ name: req.name,
+ models: req.models,
+ })),
+ updateModelProvider: vi.fn(async req => ({
+ id: req.id,
+ type: req.type,
+ name: req.name,
+ models: req.models,
+ })),
+ },
+ connectorCatalog: {
+ getConnectorCatalog: vi.fn(async () => []),
+ listConnectors: vi.fn(async () => []),
+ getToolsByConnectorId: vi.fn(async () => []),
+ createConnector: vi.fn(async req => ({
+ id: 'c1',
+ name: req.name,
+ description: '',
+ url: req.url,
+ auth:
+ req.auth.type === 'oauth'
+ ? { type: 'oauth' as const, authUrl: 'https://example.com/oauth' }
+ : req.auth.type === 'apiKey'
+ ? { type: 'apiKey' as const }
+ : { type: 'none' as const },
+ requiresAuth: req.auth.type === 'oauth',
+ authenticated: false,
+ })),
+ updateConnector: vi.fn(async req => ({
+ id: req.id,
+ name: req.name,
+ description: '',
+ url: req.url,
+ auth:
+ req.auth.type === 'oauth'
+ ? { type: 'oauth' as const, authUrl: 'https://example.com/oauth' }
+ : req.auth.type === 'apiKey'
+ ? { type: 'apiKey' as const }
+ : { type: 'none' as const },
+ requiresAuth: req.auth.type === 'oauth',
+ authenticated: false,
+ })),
+ authenticateConnector: vi.fn(async ({ id }) => ({
+ id,
+ name: '',
+ description: '',
+ url: '',
+ auth: { type: 'oauth' as const, authUrl: 'https://example.com/oauth' },
+ requiresAuth: true,
+ authenticated: true,
+ })),
+ disconnectConnector: vi.fn(async ({ id }) => ({
+ id,
+ name: '',
+ description: '',
+ url: '',
+ auth: { type: 'none' as const },
+ requiresAuth: false,
+ authenticated: false,
+ })),
+ },
+ };
+
+ const server = createTrueFoundryServer({
+ chatServer,
+ getModels: async () => [],
+ getSkills: async () => [],
+ getMcp: async () => [],
+ searchAgents: async () => [],
+ saveAgent: async () => ({ ok: true }),
+ catalog,
+ });
+
+ expect(server.catalog).toBe(catalog);
+ await expect(server.catalog!.modelCatalog.listModelProviders()).resolves.toEqual([
+ { id: 'openai', type: 'openai', name: 'OpenAI', models: [] },
+ ]);
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/server/createTrueFoundryServer.ts b/packages/trueforge-ui-sdk/src/server/createTrueFoundryServer.ts
new file mode 100644
index 000000000..c3ea7d692
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/server/createTrueFoundryServer.ts
@@ -0,0 +1,103 @@
+import type {
+ AgentBuilderServer,
+ AgentChatServer,
+ AgentLibraryEntry,
+ AgentSkill,
+ AgentSpec,
+ AgentUIServer,
+ CatalogServer,
+ ConnectorState,
+ CreateSessionRequest,
+ ListSessionsParams,
+ ModelSelection,
+ SearchAgentsParams,
+ Session,
+ SessionEventItem,
+ Turn,
+ TurnStreamingEvent,
+ UpdateSessionRequest,
+} from './types.js';
+
+export type CreateTrueFoundryServerOptions<
+ TSpec extends AgentSpec = AgentSpec,
+ TModel extends ModelSelection = ModelSelection,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSave = unknown,
+ TCatalog extends CatalogServer = CatalogServer,
+> = {
+ /** Chat port — e.g. from `@truefoundry/agent-server-adapter`. */
+ chatServer: AgentChatServer<TSpec>;
+ getModels: () => Promise<TModel[]>;
+ getSkills: () => Promise<TSkill[]>;
+ getMcp: () => Promise<TMcp[]>;
+ searchAgents: (req?: SearchAgentsParams) => Promise<TAgent[]>;
+ saveAgent: (req: { agentName: string; agentSpec: TSpec }) => Promise<TSave>;
+ deleteAgent?: (req: { agentName: string }) => Promise<void>;
+ /** Settings catalog (models + connectors). Optional. */
+ catalog?: TCatalog;
+};
+
+export type TrueFoundryServer<
+ TSpec extends AgentSpec = AgentSpec,
+ TModel extends ModelSelection = ModelSelection,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSave = unknown,
+ TCatalog extends CatalogServer = CatalogServer,
+> = AgentUIServer<
+ TSpec,
+ Session<TSpec>,
+ CreateSessionRequest<TSpec>,
+ ListSessionsParams,
+ UpdateSessionRequest<TSpec>,
+ Turn,
+ SessionEventItem,
+ TurnStreamingEvent,
+ TModel,
+ TSkill,
+ TMcp,
+ TAgent,
+ TSave,
+ TCatalog
+>;
+
+/**
+ * Composes an `AgentChatServer` with host-provided builder catalog callbacks
+ * and an optional settings `catalog`.
+ * Gateway wiring lives in the host (or `@truefoundry/agent-server-adapter`).
+ */
+export function createTrueFoundryServer<
+ TSpec extends AgentSpec = AgentSpec,
+ TModel extends ModelSelection = ModelSelection,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSave = unknown,
+ TCatalog extends CatalogServer = CatalogServer,
+>(
+ opts: CreateTrueFoundryServerOptions<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCatalog>,
+): TrueFoundryServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCatalog> {
+ const builder: AgentBuilderServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave> = {
+ getModels: opts.getModels,
+ getSkills: opts.getSkills,
+ getMcp: opts.getMcp,
+ searchAgents: opts.searchAgents,
+ saveAgent: opts.saveAgent,
+ deleteAgent: async req => {
+ if (opts.deleteAgent) {
+ await opts.deleteAgent(req);
+ return;
+ }
+ throw new Error('deleteAgent is host-owned. Pass deleteAgent to createTrueFoundryServer.');
+ },
+ };
+
+ return {
+ ...opts.chatServer,
+ ...builder,
+ ...(opts.catalog != null ? { catalog: opts.catalog } : {}),
+ } as TrueFoundryServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave, TCatalog>;
+}
diff --git a/packages/trueforge-ui-sdk/src/server/types.ts b/packages/trueforge-ui-sdk/src/server/types.ts
new file mode 100644
index 000000000..782f010b7
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/server/types.ts
@@ -0,0 +1,684 @@
+/**
+ * FE-owned AgentUIServer contract.
+ *
+ * Rule: only methods/fields our UI calls or the runtime invokes.
+ * Hosts extend via `T extends Base` for system-specific extras.
+ *
+ * The runtime will accept `AgentChatServer` instead of gateway clients.
+ */
+
+// ---------------------------------------------------------------------------
+// Catalog — picker / library rows (SDK-minimal; host extends via generics)
+// ---------------------------------------------------------------------------
+
+/** Model picker row. Host extends for apiModel, modelId, pricing, etc. */
+export interface ModelSelection {
+ name: string;
+ provider: string;
+ /** When non-empty, UI shows a reasoning-effort picker beside the model selector. */
+ reasoningEfforts?: string[];
+}
+
+/** Skill picker row. Host extends for fqn, preload, etc. */
+export interface AgentSkill {
+ id: string;
+ name: string;
+ description?: string;
+}
+
+/** MCP picker row. Host extends for type, enableTools, url, etc. */
+export interface ConnectorState {
+ id: string;
+ name: string;
+ description?: string;
+}
+
+/** Agents library row — UI shows name only. Host extends for metadata. */
+export interface AgentLibraryEntry {
+ name: string;
+}
+
+export type SearchAgentsParams = {
+ query?: string;
+ limit?: number;
+ offset?: number;
+};
+
+// ---------------------------------------------------------------------------
+// Mounts — neutral SDK base (host extends with backend-specific fields)
+// ---------------------------------------------------------------------------
+
+/** Skill mount base written to AgentSpec.skills[]. Host extends for fqn, preload, etc. */
+export interface SkillMount {
+ id: string;
+ name: string;
+}
+
+/** MCP server mount base written to AgentSpec.mcpServers[]. Host extends for type, enableTools, etc. */
+export interface McpServerMount {
+ id: string;
+ name: string;
+}
+
+// ---------------------------------------------------------------------------
+// AgentSpec — each nested field + the spec itself are host-extendable
+// ---------------------------------------------------------------------------
+
+export interface ModelParams {
+ maxTokens?: number;
+ reasoningEffort?: string;
+}
+
+/** Model written to AgentSpec.model. Host extends for provider extras, etc. */
+export interface Model<TParams extends ModelParams = ModelParams> {
+ name: string;
+ params?: TParams;
+}
+
+/**
+ * SDK-owned agent definition — fields the FE reads/writes.
+ *
+ * - Nested slots are generic: host widens `Model` / `SkillMount` / `McpServerMount`.
+ * - The spec itself is extendable: `interface TfySpec extends AgentSpec<...> { instructions?: string }`.
+ *
+ * @example
+ * ```ts
+ * interface TfyModelParams extends ModelParams { temperature?: number }
+ * interface TfyModel extends Model<TfyModelParams> {}
+ * interface TfySkillMount extends SkillMount { fqn: string; preload: boolean }
+ * interface TfyMcpMount extends McpServerMount { type: string; enableTools: string[] }
+ *
+ * interface TfySpec extends AgentSpec<TfyModel, TfySkillMount, TfyMcpMount> {
+ * instructions?: string;
+ * config?: RuntimeConfig;
+ * }
+ * ```
+ */
+export interface AgentSpec<
+ TModel extends Model = Model,
+ TSkill extends SkillMount = SkillMount,
+ TMcp extends McpServerMount = McpServerMount,
+> {
+ model: TModel;
+ skills?: TSkill[];
+ mcpServers?: TMcp[];
+}
+
+// ---------------------------------------------------------------------------
+// Session — plain DTO, generic in TSpec so host's spec type flows through
+// ---------------------------------------------------------------------------
+
+export interface Session<TSpec extends AgentSpec = AgentSpec> {
+ id: string;
+ title?: string;
+ agentName?: string;
+ agentSpec?: TSpec;
+ /** true → mutable builder + updateSession(spec) allowed. */
+ isMutable: boolean;
+ createdAt: string;
+ updatedAt: string;
+}
+
+export interface CreateSessionRequest<TSpec extends AgentSpec = AgentSpec> {
+ agentName?: string;
+ agentSpec?: TSpec;
+}
+
+export interface UpdateSessionRequest<TSpec extends AgentSpec = AgentSpec> {
+ sessionId: string;
+ agentSpec?: TSpec;
+ title?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Pagination
+// ---------------------------------------------------------------------------
+
+export interface TokenPagination {
+ nextPageToken?: string;
+ previousPageToken?: string;
+ limit: number;
+}
+
+export interface PageResult<T, R = unknown> {
+ data: T[];
+ response: R;
+ hasNextPage(): boolean;
+ getNextPage(): Promise<PageResult<T, R>>;
+}
+
+export type ListSessionsOrder = 'asc' | 'desc';
+
+export type PageParams = {
+ limit?: number;
+ order?: ListSessionsOrder;
+ pageToken?: string;
+};
+
+export interface ListSessionsParams extends PageParams {
+ agentName?: string;
+}
+
+export interface ListSessionsResponse<
+ TSpec extends AgentSpec = AgentSpec,
+ TSession extends Session<TSpec> = Session<TSpec>,
+> {
+ data: TSession[];
+ pagination: TokenPagination;
+}
+
+export type PreviousTurnIdInput = 'auto' | string;
+
+// ---------------------------------------------------------------------------
+// Turn input / state — what runtime sends and reads
+// ---------------------------------------------------------------------------
+
+export type UserMessageContent =
+ string | Array<{ type: 'text'; text: string } | { type: 'file'; [key: string]: unknown }>;
+
+export interface UserMessage {
+ type: 'user.message';
+ content: UserMessageContent;
+}
+
+export type ApprovalDecision = { status: 'allow' } | { status: 'deny'; reason?: string };
+
+export interface UserToolApprovalEvent {
+ type: 'user.tool_approval';
+ threadId: string;
+ toolCallId: string;
+ approval: ApprovalDecision;
+}
+
+export interface UserToolResponseEvent {
+ type: 'user.tool_response';
+ threadId: string;
+ toolCallId: string;
+ content: string;
+}
+
+export type TurnInputItem = UserMessage | UserToolApprovalEvent | UserToolResponseEvent;
+
+export type TurnState =
+ | { status: 'running' }
+ | {
+ status: 'done';
+ output?: unknown;
+ requiredActions?: unknown[];
+ completedAt: string;
+ }
+ | { status: 'cancelled'; reason: string; completedAt: string }
+ | { status: 'error'; message: string; completedAt: string };
+
+export interface Turn {
+ id: string;
+ sessionId: string;
+ previousTurnId?: string;
+ input?: TurnInputItem[];
+ state: TurnState;
+ createdAt: string;
+}
+
+export interface ListTurnsResponse<TTurn extends Turn = Turn> {
+ data: TTurn[];
+ pagination: TokenPagination;
+}
+
+// ---------------------------------------------------------------------------
+// Stream / events — opaque; host narrows via generics
+// ---------------------------------------------------------------------------
+
+export type TurnStreamingEvent = { type: string; [key: string]: unknown };
+
+export interface TurnStreamData<TStreamEvent extends TurnStreamingEvent = TurnStreamingEvent> {
+ sequenceNumber: number;
+ event: TStreamEvent;
+}
+
+export type SessionEvent = { type: string; [key: string]: unknown };
+
+export interface SessionEventItem {
+ turnId: string;
+ event: SessionEvent;
+}
+
+export interface ListSessionEventsResponse<TEvent extends SessionEventItem = SessionEventItem> {
+ data: TEvent[];
+ pagination: TokenPagination;
+}
+
+// ---------------------------------------------------------------------------
+// Server ports — flat methods, no session-with-methods objects
+// ---------------------------------------------------------------------------
+
+/**
+ * Chat / session port — the runtime calls these.
+ *
+ * All session ops are flat (sessionId param). No gateway client dependency.
+ * `createTrueFoundryServer` is one possible implementation (TFY adapter).
+ *
+ * TSpec flows through Session, CreateSessionRequest, UpdateSessionRequest
+ * so the host's extended spec is type-safe end to end.
+ */
+export interface AgentChatServer<
+ TSpec extends AgentSpec = AgentSpec,
+ TSession extends Session<TSpec> = Session<TSpec>,
+ TCreate extends CreateSessionRequest<TSpec> = CreateSessionRequest<TSpec>,
+ TList extends ListSessionsParams = ListSessionsParams,
+ TUpdate extends UpdateSessionRequest<TSpec> = UpdateSessionRequest<TSpec>,
+ TTurn extends Turn = Turn,
+ TEvent extends SessionEventItem = SessionEventItem,
+ TStreamEvent extends TurnStreamingEvent = TurnStreamingEvent,
+> {
+ createSession(req: TCreate): Promise<TSession>;
+ listSessions(req?: TList): Promise<PageResult<TSession, ListSessionsResponse<TSpec, TSession>>>;
+ getSession(req: { sessionId: string }): Promise<TSession>;
+ updateSession(req: TUpdate): Promise<TSession>;
+
+ createTurn(req: {
+ sessionId: string;
+ input?: TurnInputItem[];
+ previousTurnId?: PreviousTurnIdInput;
+ }): AsyncIterable<TurnStreamData<TStreamEvent>>;
+
+ cancelSession(req: { sessionId: string }): Promise<void>;
+ /** Deletes a session; used by the session list Delete control. */
+ deleteSession?(req: { sessionId: string }): Promise<void>;
+
+ listTurns(req: {
+ sessionId: string;
+ limit?: number;
+ pageToken?: string;
+ }): Promise<PageResult<TTurn, ListTurnsResponse<TTurn>>>;
+ getTurn(req: { sessionId: string; turnId: string }): Promise<TTurn>;
+ listEvents(req: {
+ sessionId: string;
+ pageToken?: string;
+ lastTurnId?: string;
+ limit?: number;
+ }): Promise<PageResult<TEvent, ListSessionEventsResponse<TEvent>>>;
+
+ subscribeToTurn?(req: {
+ sessionId: string;
+ turnId: string;
+ afterSequenceNumber?: number;
+ }): AsyncIterable<TurnStreamData<TStreamEvent>>;
+
+ downloadSandboxFile?(sandboxId: string, req: { path: string }): Promise<unknown>;
+}
+
+/**
+ * Builder catalog + persist port — atoms call these.
+ *
+ * Generics let hosts type their catalog rows richer than SDK base.
+ */
+export interface AgentBuilderServer<
+ TSpec extends AgentSpec = AgentSpec,
+ TModel extends ModelSelection = ModelSelection,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSave = unknown,
+> {
+ getModels(): Promise<TModel[]>;
+ getSkills(): Promise<TSkill[]>;
+ getMcp(): Promise<TMcp[]>;
+ searchAgents(req?: SearchAgentsParams): Promise<TAgent[]>;
+ saveAgent(req: { agentName: string; agentSpec: TSpec }): Promise<TSave>;
+ deleteAgent?(req: { agentName: string }): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Catalog management — FE-minimal settings DTOs (host extends via generics)
+// ---------------------------------------------------------------------------
+
+/**
+ * Provider type id. Reserved literal: `"custom"` for user-defined providers;
+ * any other string is a builtin (e.g. `"openai"`, `"anthropic"`).
+ *
+ * Note: `string | "custom"` is useless in TypeScript (`"custom"` ⊆ `string`),
+ * so this stays `string` and `"custom"` is a documented convention.
+ */
+export type ProviderType = string;
+
+/**
+ * Model row — form "Model ID" + "Display name".
+ * Host extends for properties, etc.
+ */
+export interface ModelEntry {
+ id: string;
+ name: string;
+}
+
+/**
+ * Write config for create/update (custom form + catalog "Save key").
+ * Host extends. `baseUrl` present iff `type === "custom"`.
+ */
+export interface ModelProviderConfigBase<TModel extends ModelEntry = ModelEntry> {
+ type: ProviderType;
+ name: string;
+ /** Present iff `type === "custom"`. */
+ baseUrl?: string;
+ apiKey: string;
+ models: TModel[];
+}
+
+/**
+ * Configured provider card (list/read). No raw `apiKey`.
+ * Host extends for apiKeySet, timestamps, etc.
+ */
+export interface ModelProviderBase<TModel extends ModelEntry = ModelEntry> {
+ id: string;
+ type: ProviderType;
+ name: string;
+ /** Present iff `type === "custom"`. */
+ baseUrl?: string;
+ models: TModel[];
+}
+
+/**
+ * Discovery-only catalog provider (AVAILABLE list).
+ * `type` must not be `"custom"` — custom providers use the custom form.
+ * Host extends for richer model rows.
+ */
+export interface ModelProviderCatalogEntry<TModel extends ModelEntry = ModelEntry> {
+ type: ProviderType;
+ name: string;
+ models: TModel[];
+}
+
+/** Create — no `id`; server assigns it. Catalog path = entry + apiKey. */
+export type CreateModelProviderRequest<TModel extends ModelEntry = ModelEntry> = ModelProviderConfigBase<TModel>;
+
+/** Update — `id` required. */
+export type UpdateModelProviderRequest<TModel extends ModelEntry = ModelEntry> = ModelProviderConfigBase<TModel> & {
+ id: string;
+};
+
+export interface ModelCatalogServer<
+ TModel extends ModelEntry = ModelEntry,
+ TProvider extends ModelProviderBase<TModel> = ModelProviderBase<TModel>,
+ TCatalogProvider extends ModelProviderCatalogEntry<TModel> = ModelProviderCatalogEntry<TModel>,
+ TCreate extends CreateModelProviderRequest<TModel> = CreateModelProviderRequest<TModel>,
+ TUpdate extends UpdateModelProviderRequest<TModel> = UpdateModelProviderRequest<TModel>,
+> {
+ getModelProviderCatalog(): Promise<TCatalogProvider[]>;
+ listModelProviders(): Promise<TProvider[]>;
+ createModelProvider(req: TCreate): Promise<TProvider>;
+ /** Full replace update keyed by provider `id`. */
+ updateModelProvider(req: TUpdate): Promise<TProvider>;
+ deleteModelProvider?(req: { id: string }): Promise<void>;
+}
+
+/** Tool row on a connector detail. Host extends for schemas, etc. */
+export interface ToolBase {
+ id: string;
+ name: string;
+ description: string;
+}
+
+/** Strict auth type id. Hosts widen branches via intersection + re-union. */
+export type ConnectorAuthType = 'oauth' | 'apiKey' | 'none';
+
+// Write (create/update) — export branches so hosts can intersect extras
+export type ConnectorAuthOAuth = { type: 'oauth'; authUrl?: string };
+export type ConnectorAuthApiKey = {
+ type: 'apiKey';
+ apiKey?: string;
+ headerName?: string;
+};
+export type ConnectorAuthNone = { type: 'none' };
+export type ConnectorAuth = ConnectorAuthOAuth | ConnectorAuthApiKey | ConnectorAuthNone;
+
+// Public (list/detail) — no secrets; oauth requires authUrl
+export type ConnectorAuthPublicOAuth = { type: 'oauth'; authUrl: string };
+export type ConnectorAuthPublicApiKey = {
+ type: 'apiKey';
+ headerName?: string;
+};
+export type ConnectorAuthPublicNone = { type: 'none' };
+export type ConnectorAuthPublic = ConnectorAuthPublicOAuth | ConnectorAuthPublicApiKey | ConnectorAuthPublicNone;
+
+/**
+ * MCP / connector create-edit config. Host extends for extra fields, etc.
+ */
+export interface ConnectorConfigBase<TAuth extends ConnectorAuth = ConnectorAuth> {
+ name: string;
+ url: string;
+ auth: TAuth;
+}
+
+/**
+ * Connected connector row (settings/connectors). No raw `apiKey` or tools.
+ * Tools are fetched separately with `getToolsByConnectorId`.
+ * Host extends.
+ */
+export interface ConnectorBase<TAuth extends ConnectorAuthPublic = ConnectorAuthPublic> {
+ id: string;
+ name: string;
+ description: string;
+ url: string;
+ auth: TAuth;
+ /** When true, UI should not show Disconnect. */
+ requiresAuth: boolean;
+ authenticated: boolean;
+}
+
+/** Discovery catalog entry for "+ Add MCP server". Host extends. */
+export interface ConnectorCatalogEntry<TAuth extends ConnectorAuthPublic = ConnectorAuthPublic> {
+ id: string;
+ name: string;
+ description?: string;
+ url: string;
+ auth: TAuth;
+}
+
+/** Create connector — no `id`; server assigns it. Host extends. */
+export type CreateConnectorRequest<TAuth extends ConnectorAuth = ConnectorAuth> = ConnectorConfigBase<TAuth>;
+
+/** Update connector — `id` required. Host extends. */
+export type UpdateConnectorRequest<TAuth extends ConnectorAuth = ConnectorAuth> = ConnectorConfigBase<TAuth> & {
+ id: string;
+};
+
+export interface AuthenticateConnectorRequest {
+ id: string;
+ /** OAuth callback page owned by the host application. */
+ redirectURL?: string;
+}
+
+export interface ConnectorAuthenticationResult<TConnector extends ConnectorBase = ConnectorBase> {
+ connector?: TConnector;
+ status?: string;
+ authorization_endpoint?: string;
+}
+
+export interface ConnectorCatalogServer<
+ TTool extends ToolBase = ToolBase,
+ TAuthWrite extends ConnectorAuth = ConnectorAuth,
+ TAuthPublic extends ConnectorAuthPublic = ConnectorAuthPublic,
+ TConnector extends ConnectorBase<TAuthPublic> = ConnectorBase<TAuthPublic>,
+ TCatalogEntry extends ConnectorCatalogEntry<TAuthPublic> = ConnectorCatalogEntry<TAuthPublic>,
+ TCreate extends CreateConnectorRequest<TAuthWrite> = CreateConnectorRequest<TAuthWrite>,
+ TUpdate extends UpdateConnectorRequest<TAuthWrite> = UpdateConnectorRequest<TAuthWrite>,
+> {
+ getConnectorCatalog(): Promise<TCatalogEntry[]>;
+ listConnectors(req?: { query?: string }): Promise<TConnector[]>;
+ getToolsByConnectorId(req: { id: string }): Promise<TTool[]>;
+ createConnector(req: TCreate): Promise<TConnector>;
+ /** Full replace update keyed by connector `id`. */
+ updateConnector(req: TUpdate): Promise<TConnector>;
+ /**
+ * Start connector auth (e.g. OAuth).
+ * May return a connector (already authenticated / with `auth.authUrl`) or a
+ * result carrying `authorization_endpoint` for the popup flow.
+ */
+ authenticateConnector(
+ req: AuthenticateConnectorRequest,
+ ): Promise<TConnector | ConnectorAuthenticationResult<TConnector>>;
+ /** Clear connector auth. */
+ disconnectConnector(req: { id: string }): Promise<TConnector>;
+ deleteConnector?(req: { id: string }): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Skills catalog — FE-minimal settings DTOs (host extends via generics)
+// ---------------------------------------------------------------------------
+
+/** Skill row shown in settings/skills (list + delete). Host extends for fqn, etc. */
+export interface SkillBase {
+ id: string;
+ name: string;
+ description: string;
+}
+
+export interface RegistrySkill extends SkillBase {
+ /** `SkillCatalogEntry.id` this skill was created from. */
+ catalogId: string;
+}
+
+export interface GithubSkill extends SkillBase {}
+
+export type DefinedSkill = RegistrySkill | GithubSkill;
+
+/** Git source fields shared by catalog entries and create requests. */
+export interface SkillConfigBase {
+ name: string;
+ description: string;
+ repoURL: string;
+ path: string;
+ ref: string;
+}
+
+/** Catalog row for "Available" skills. Selecting one defines it in the host DB. */
+export interface SkillCatalogEntry extends SkillConfigBase {
+ id: string;
+}
+
+/** Create-skill base. Hosts may intersect extra fields and re-union. */
+export interface CreateSkillRequestBase extends SkillConfigBase {}
+
+export interface SelectRegistrySkillRequest extends CreateSkillRequestBase {
+ /** `SkillCatalogEntry.id`, persisted so the created skill links back to it. */
+ catalogId: string;
+}
+
+export interface ImportGithubSkillRequest extends CreateSkillRequestBase {}
+
+export type CreateSkillRequest = SelectRegistrySkillRequest | ImportGithubSkillRequest;
+
+export interface SkillCatalogServer<
+ TSkill extends SkillBase = SkillBase,
+ TCatalogEntry extends SkillCatalogEntry = SkillCatalogEntry,
+ TCreate extends CreateSkillRequest = CreateSkillRequest,
+> {
+ getSkillCatalog(): Promise<TCatalogEntry[]>;
+ listSkills(req?: { query?: string }): Promise<TSkill[]>;
+ createSkill(req: TCreate): Promise<TSkill>;
+ /**
+ * Removes the skill from the host DB. A registry skill (has `catalogId`) stays
+ * in the catalog and becomes selectable again; a github skill is gone for good.
+ */
+ deleteSkill?(req: { id: string }): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Sandboxes catalog — public rows omit credentials; writes accept them
+// ---------------------------------------------------------------------------
+
+/** Mutable sandbox settings shared by catalog rows, create, and update. */
+export interface SandboxConfig {
+ snapshotName: string;
+ execTimeoutMs: number;
+ autoStopIntervalInMinutes: number;
+ autoArchiveIntervalInMinutes: number;
+ autoDeleteIntervalInMinutes: number;
+}
+
+export interface SandboxCatalogEntry extends SandboxConfig {
+ id: string;
+ name: string;
+ type: string;
+}
+
+/**
+ * Connected sandbox row (settings/sandboxes). No raw `apiKey`.
+ * Includes last-saved config so update forms can show previous values.
+ */
+export interface SandboxBase extends SandboxConfig {
+ id: string;
+ name: string;
+ catalogId: string;
+ isConnected: boolean;
+}
+
+/**
+ * Create — catalog identity + config + apiKey.
+ * `catalogId` is `SandboxCatalogEntry.id`; the server assigns the sandbox instance `id`.
+ */
+export interface CreateSandboxRequest extends SandboxConfig {
+ catalogId: string;
+ name: string;
+ type: string;
+ apiKey: string;
+}
+
+/** Update — full replace of config keyed by sandbox instance `id`. */
+export interface UpdateSandboxRequest extends SandboxConfig {
+ id: string;
+ /** Omit to keep the existing key; send a value to rotate. */
+ apiKey?: string;
+}
+
+export interface SandboxCatalogServer<
+ TSandbox extends SandboxBase = SandboxBase,
+ TCatalogEntry extends SandboxCatalogEntry = SandboxCatalogEntry,
+ TCreate extends CreateSandboxRequest = CreateSandboxRequest,
+ TUpdate extends UpdateSandboxRequest = UpdateSandboxRequest,
+> {
+ getSandboxCatalog(): Promise<TCatalogEntry[]>;
+ listSandboxes(req?: { query?: string }): Promise<TSandbox[]>;
+ createSandbox(req: TCreate): Promise<TSandbox>;
+ updateSandbox(req: TUpdate): Promise<TSandbox>;
+ deleteSandbox(req: { id: string }): Promise<void>;
+}
+
+/**
+ * Settings management aggregate — modelCatalog + connectorCatalog + optional
+ * skill and sandbox catalogs.
+ * Hosts may pass the whole object to an app shell, or a focused sub-port to a page.
+ */
+export interface CatalogServer<
+ TModelCatalog extends ModelCatalogServer = ModelCatalogServer,
+ TConnectorCatalog extends ConnectorCatalogServer = ConnectorCatalogServer,
+ TSkillCatalog extends SkillCatalogServer = SkillCatalogServer,
+ TSandboxCatalog extends SandboxCatalogServer = SandboxCatalogServer,
+> {
+ modelCatalog: TModelCatalog;
+ connectorCatalog: TConnectorCatalog;
+ /** Optional — omit when the host has no skills settings surface. */
+ skillCatalog?: TSkillCatalog;
+ /** Optional — omit when the host has no sandboxes settings surface. */
+ sandboxCatalog?: TSandboxCatalog;
+}
+
+/** Combined port: runtime (chat) + atoms (builder) + optional settings catalog. */
+export type AgentUIServer<
+ TSpec extends AgentSpec = AgentSpec,
+ TSession extends Session<TSpec> = Session<TSpec>,
+ TCreate extends CreateSessionRequest<TSpec> = CreateSessionRequest<TSpec>,
+ TList extends ListSessionsParams = ListSessionsParams,
+ TUpdate extends UpdateSessionRequest<TSpec> = UpdateSessionRequest<TSpec>,
+ TTurn extends Turn = Turn,
+ TEvent extends SessionEventItem = SessionEventItem,
+ TStreamEvent extends TurnStreamingEvent = TurnStreamingEvent,
+ TModel extends ModelSelection = ModelSelection,
+ TSkill extends AgentSkill = AgentSkill,
+ TMcp extends ConnectorState = ConnectorState,
+ TAgent extends AgentLibraryEntry = AgentLibraryEntry,
+ TSave = unknown,
+ TCatalog extends CatalogServer = CatalogServer,
+> = AgentChatServer<TSpec, TSession, TCreate, TList, TUpdate, TTurn, TEvent, TStreamEvent> &
+ AgentBuilderServer<TSpec, TModel, TSkill, TMcp, TAgent, TSave> & {
+ catalog?: TCatalog;
+ };
diff --git a/packages/trueforge-ui-sdk/src/styles.css b/packages/trueforge-ui-sdk/src/styles.css
new file mode 100644
index 000000000..267b8d40e
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/styles.css
@@ -0,0 +1,321 @@
+/**
+ * Tailwind authoring source for @truefoundry/trueforge-ui.
+ *
+ * The package build compiles this file through `build-styles.css` into the
+ * public `dist/styles.css` artifact. Consumers must import that artifact,
+ * rather than compiling this source in their own Tailwind pipeline.
+ *
+ * ── Quick start ──────────────────────────────────────────────────────
+ *
+ * @import "@truefoundry/trueforge-ui/styles.css";
+ *
+ * That's the entire styling setup. Everything below is pulled in for you:
+ *
+ * 1. OpenUI stylesheet + Tailwind `@source` scanning for this SDK's own
+ * compiled components.
+ *
+ * 2. GitHub Markdown styles (`github-markdown-css`) for `.markdown-body`.
+ *
+ * 3. Owned palette + shadcn-style semantic tokens (`--background`,
+ * `--muted`, `--primary`, …) in light and dark.
+ *
+ * ── Overriding colours ───────────────────────────────────────────────
+ *
+ * Palette colours:
+ *
+ * :root { --color-indigo-500: #000; }
+ *
+ * Semantic tokens (used by this SDK's atoms):
+ *
+ * :root { --background: #fff; --primary: #e11d48; }
+ *
+ * Or via the theme object: `theme={{ tokens: { primary: "#e11d48" } }}`.
+ *
+ * Both work because the `@layer` block below has the lowest precedence —
+ * any plain `:root` / `.aui-root` declaration in the consumer's CSS wins.
+ */
+@import "./openui.css";
+
+/*
+ * GitHub Markdown styles (https://github.com/sindresorhus/github-markdown-css).
+ * Applied via `.markdown-body` on the Markdown atom. The bridge remaps light/dark
+ * CSS variables to the SDK ThemeProvider mode (class + data-theme).
+ */
+@import "github-markdown-css/github-markdown.css";
+@import "./github-markdown-bridge.css";
+
+/* ──────────────────────────────────────────────────────────────────────
+ * Owned palette (minimal set used by semantic tokens + gray utilities).
+ * Light values on :root; dark mode flips the same var names under .dark
+ * (matches prior tfy ThemeProvider injectThemes behaviour).
+ * ──────────────────────────────────────────────────────────────────── */
+@layer tfy-agent-ui-base {
+ :root {
+ --color-white: #ffffff;
+ --color-black: #09090b;
+ --color-gray-100: #f4f4f5;
+ --color-gray-125: #f1f1f2;
+ --color-gray-150: #eeeef0;
+ --color-gray-200: #e4e4e7;
+ --color-gray-250: #e4e4e7;
+ --color-gray-275: #f4f4f5;
+ --color-gray-300: #d4d4d8;
+ --color-gray-400: #a1a1aa;
+ --color-gray-500: #71717a;
+ --color-gray-550: #62626a;
+ --color-gray-600: #52525b;
+ --color-gray-650: #494950;
+ --color-gray-700: #3f3f46;
+ --color-gray-750: #303036;
+ --color-gray-800: #27272a;
+ --color-gray-1000: #09090b;
+ --color-indigo-500: #6366f1;
+ --color-red-500: #ef4444;
+
+ --background: var(--color-white);
+ --foreground: var(--color-gray-1000);
+ --card: var(--color-white);
+ --card-foreground: var(--color-gray-1000);
+ --popover: var(--color-white);
+ --popover-foreground: var(--color-gray-1000);
+ --primary: var(--color-black);
+ --primary-foreground: var(--color-white);
+ --secondary: var(--color-gray-100);
+ --secondary-foreground: var(--color-gray-1000);
+ --muted: var(--color-gray-100);
+ --muted-foreground: var(--color-gray-550);
+ --accent: var(--color-gray-125);
+ --accent-foreground: var(--color-gray-1000);
+ --destructive: var(--color-red-500);
+ --destructive-foreground: var(--color-white);
+ --border: var(--color-gray-250);
+ --input: var(--color-gray-250);
+ --ring: var(--color-black);
+ --radius: 0.5rem;
+ --composer-radius: 1.5rem;
+ --user-bubble: var(--color-black);
+ --user-bubble-foreground: var(--color-white);
+ --assistant-bubble: transparent;
+ --assistant-bubble-foreground: var(--foreground);
+ }
+
+ .dark {
+ --color-gray-100: #101013;
+ --color-gray-125: #141417;
+ --color-gray-150: #18181b;
+ --color-gray-200: #1f1f22;
+ --color-gray-250: #27272a;
+ --color-gray-275: #343439;
+ --color-gray-300: #3f3f46;
+ --color-gray-400: #52525b;
+ --color-gray-500: #71717a;
+ --color-gray-550: #8c8c92;
+ --color-gray-600: #a1a1aa;
+ --color-gray-650: #b8b8be;
+ --color-gray-700: #d4d4d8;
+ --color-gray-750: #dfdfe2;
+ --color-gray-800: #ececee;
+ --color-gray-1000: #fdfdfd;
+
+ --background: var(--color-gray-200);
+ --foreground: var(--color-gray-1000);
+ --card: var(--color-gray-150);
+ --card-foreground: var(--color-gray-1000);
+ --popover: var(--color-gray-150);
+ --popover-foreground: var(--color-gray-1000);
+ --primary: var(--color-indigo-500);
+ --primary-foreground: var(--color-white);
+ --secondary: var(--color-gray-250);
+ --secondary-foreground: var(--color-gray-1000);
+ --muted: var(--color-gray-250);
+ --muted-foreground: var(--color-gray-600);
+ --accent: var(--color-gray-275);
+ --accent-foreground: var(--color-gray-1000);
+ --destructive: var(--color-red-500);
+ --destructive-foreground: var(--color-white);
+ --border: var(--color-gray-275);
+ --input: var(--color-gray-275);
+ --ring: var(--color-indigo-500);
+ --user-bubble: var(--color-indigo-500);
+ --user-bubble-foreground: var(--color-white);
+ --assistant-bubble: transparent;
+ --assistant-bubble-foreground: var(--foreground);
+ }
+}
+
+/*
+ * Unlayered so it beats any @layer utilities rule (e.g. Tailwind's
+ * `.font-sans`) that might otherwise override the inherited font on
+ * descendant elements. `.aui-theme-root` covers all SDK chrome (including
+ * brand names and sidebars), while `.aui-root` covers standalone thread
+ * shells and consumer slot overrides. `.font-sans-flex` remains available
+ * for explicitly portaled surfaces. All three override `--font-sans`.
+ * Override `--font-agent-ui` in host CSS to brand the font (the SDK
+ * stylesheet does not load webfonts from a CDN).
+ */
+.aui-theme-root,
+.aui-root,
+.font-sans-flex {
+ --font-sans: var(
+ --font-agent-ui,
+ ui-sans-serif,
+ system-ui,
+ -apple-system,
+ "Segoe UI",
+ Roboto,
+ "Helvetica Neue",
+ Arial,
+ sans-serif
+ );
+ font-family: var(
+ --font-agent-ui,
+ ui-sans-serif,
+ system-ui,
+ -apple-system,
+ "Segoe UI",
+ Roboto,
+ "Helvetica Neue",
+ Arial,
+ sans-serif
+ );
+}
+
+/*
+ * Clone typography: conversation copy and composer text are regular weight;
+ * controls and headings keep their component-level medium/semibold utilities.
+ */
+.aui-theme-root:is(
+ [data-preset="claude"],
+ [data-preset="chatgpt"],
+ [data-preset="gemini"]
+ )
+ :is(
+ .aui-markdown,
+ [data-slot="aui_user-message-content"],
+ [data-slot="aui_composer-input"],
+ [data-slot="aui_user-edit-input"]
+ ) {
+ font-weight: 400;
+}
+
+/*
+ * Token-driven default color for every SDK surface, not just thread shells.
+ * Without this, chrome outside `.aui-root` (sidebar, headers, footers, icon
+ * buttons) inherits the host page color and goes unreadable in dark mode.
+ */
+.aui-theme-root {
+ --thread-list-item-radius: 0.5rem;
+ color: var(--foreground);
+}
+
+/* ──────────────────────────────────────────────────────────────────────
+ * Slim scrollbars.
+ * ──────────────────────────────────────────────────────────────────── */
+.aui-root {
+ color: var(--foreground);
+ scrollbar-width: thin;
+ scrollbar-color: var(--muted-foreground) transparent;
+}
+
+.aui-root ::-webkit-scrollbar {
+ width: 8px;
+ height: 8px;
+}
+
+.aui-root ::-webkit-scrollbar-track {
+ background: transparent;
+}
+
+.aui-root ::-webkit-scrollbar-thumb {
+ background-color: var(--muted-foreground);
+ border-radius: 9999px;
+ border: 2px solid transparent;
+ background-clip: content-box;
+}
+
+.aui-root ::-webkit-scrollbar-corner {
+ background: transparent;
+}
+
+/* ──────────────────────────────────────────────────────────────────────
+ * Tailwind v4 `@theme inline` registrations.
+ * ──────────────────────────────────────────────────────────────────── */
+@theme inline {
+ --color-background: var(--background);
+ --color-foreground: var(--foreground);
+ --color-card: var(--card);
+ --color-card-foreground: var(--card-foreground);
+ --color-popover: var(--popover);
+ --color-popover-foreground: var(--popover-foreground);
+ --color-primary: var(--primary);
+ --color-primary-foreground: var(--primary-foreground);
+ --color-secondary: var(--secondary);
+ --color-secondary-foreground: var(--secondary-foreground);
+ --color-muted: var(--muted);
+ --color-muted-foreground: var(--muted-foreground);
+ --color-accent: var(--accent);
+ --color-accent-foreground: var(--accent-foreground);
+ --color-destructive: var(--destructive);
+ --color-destructive-foreground: var(--destructive-foreground);
+ --color-border: var(--border);
+ --color-input: var(--input);
+ --color-ring: var(--ring);
+ --color-white: var(--color-white);
+ --color-black: var(--color-black);
+ --color-gray-100: var(--color-gray-100);
+ --color-gray-125: var(--color-gray-125);
+ --color-gray-150: var(--color-gray-150);
+ --color-gray-200: var(--color-gray-200);
+ --color-gray-250: var(--color-gray-250);
+ --color-gray-275: var(--color-gray-275);
+ --color-gray-300: var(--color-gray-300);
+ --color-gray-400: var(--color-gray-400);
+ --color-gray-500: var(--color-gray-500);
+ --color-gray-550: var(--color-gray-550);
+ --color-gray-600: var(--color-gray-600);
+ --color-gray-650: var(--color-gray-650);
+ --color-gray-700: var(--color-gray-700);
+ --color-gray-750: var(--color-gray-750);
+ --color-gray-800: var(--color-gray-800);
+ --color-gray-1000: var(--color-gray-1000);
+ --color-indigo-500: var(--color-indigo-500);
+ --color-red-500: var(--color-red-500);
+ --radius-sm: calc(var(--radius) - 4px);
+ --radius-md: calc(var(--radius) - 2px);
+ --radius-lg: var(--radius);
+ --radius-xl: calc(var(--radius) + 4px);
+}
+
+/* Monaco embeds: blend into surrounding cards (transparent editor chrome). */
+.aui-monaco .monaco-editor,
+.aui-monaco .monaco-editor-background,
+.aui-monaco .margin,
+.aui-monaco .monaco-editor .inputarea.ime-input {
+ background-color: transparent !important;
+}
+
+.aui-monaco .monaco-editor .overflow-guard {
+ border-radius: inherit;
+}
+
+/* ChatGPT dark: transparent composer border + inset white edge */
+.aui-theme-root[data-preset="chatgpt"][data-theme="dark"] [data-slot="aui_composer-shell"] {
+ box-shadow: inset 0 0 0 1px rgb(255 255 255 / 0.1);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+ .aui-bottom-sheet[open] {
+ animation: aui-bottom-sheet-enter 180ms ease-out;
+ }
+}
+
+.aui-bottom-sheet {
+ height: min(70dvh, 30rem);
+ max-height: 85dvh;
+}
+
+@keyframes aui-bottom-sheet-enter {
+ from {
+ transform: translateY(100%);
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/svg.d.ts b/packages/trueforge-ui-sdk/src/svg.d.ts
new file mode 100644
index 000000000..0565a1910
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/svg.d.ts
@@ -0,0 +1,6 @@
+declare module '*.svg' {
+ import type { FC, SVGProps } from 'react';
+
+ const ReactComponent: FC<SVGProps<SVGSVGElement>>;
+ export default ReactComponent;
+}
diff --git a/packages/trueforge-ui-sdk/src/testSetup.ts b/packages/trueforge-ui-sdk/src/testSetup.ts
new file mode 100644
index 000000000..215b60636
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/testSetup.ts
@@ -0,0 +1,52 @@
+import '@testing-library/jest-dom/vitest';
+import { createElement, type ReactNode } from 'react';
+import { vi } from 'vitest';
+
+// react-syntax-highlighter ships both CJS and ESM; refractor (its dependency)
+// is ESM-only and breaks when required via CJS. Mock in tests since it is
+// external in production anyway.
+vi.mock('react-syntax-highlighter', () => ({
+ Prism: ({
+ children,
+ language,
+ }: {
+ children?: string;
+ language?: string;
+ PreTag?: unknown;
+ CodeTag?: unknown;
+ style?: unknown;
+ showLineNumbers?: boolean;
+ }) =>
+ createElement(
+ 'pre',
+ { className: `language-${language ?? 'text'}`, 'data-testid': 'aui-syntax-highlighter' },
+ createElement('code', null, children),
+ ),
+}));
+
+vi.mock('react-syntax-highlighter/dist/esm/styles/prism', () => ({
+ oneDark: {},
+ oneLight: {},
+}));
+
+vi.mock('@openuidev/react-lang', () => ({
+ Renderer: ({ response, isStreaming }: { response?: string | null; isStreaming?: boolean }) =>
+ createElement('div', { 'data-testid': 'aui-openui-renderer', 'data-streaming': String(!!isStreaming) }, response),
+}));
+
+vi.mock('@openuidev/react-ui', () => ({
+ ThemeProvider: ({ children }: { children?: ReactNode }) => children,
+ openuiLibrary: {},
+}));
+
+// jsdom does not implement ResizeObserver; assistant-ui's viewport/scroll
+// tracking primitives use it, so tests need a no-op stand-in.
+class ResizeObserverStub {
+ observe() {}
+ unobserve() {}
+ disconnect() {}
+}
+
+if (typeof globalThis.ResizeObserver === 'undefined') {
+ globalThis.ResizeObserver = ResizeObserverStub as unknown as typeof ResizeObserver;
+}
diff --git a/packages/trueforge-ui-sdk/src/theme/SlotsProvider.test.tsx b/packages/trueforge-ui-sdk/src/theme/SlotsProvider.test.tsx
new file mode 100644
index 000000000..c7e22958e
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/theme/SlotsProvider.test.tsx
@@ -0,0 +1,75 @@
+// @vitest-environment jsdom
+import { render, screen } from '@testing-library/react';
+import type { ComponentProps } from 'react';
+import { describe, expect, it } from 'vitest';
+
+import { WelcomeScreen } from '../atoms/WelcomeScreen.js';
+import { SlotsProvider, useSlot, useThemeMode } from './SlotsProvider.js';
+
+function WelcomeConsumer() {
+ const SlotWelcome = useSlot('WelcomeScreen');
+ return <SlotWelcome heading="hello" />;
+}
+
+function ThemeModeConsumer() {
+ return <output>{useThemeMode()}</output>;
+}
+
+function CustomWelcome(_props: ComponentProps<typeof WelcomeScreen>) {
+ return <p data-testid="custom-welcome">custom</p>;
+}
+
+describe('SlotsProvider', () => {
+ it('resolves the default WelcomeScreen when no override is provided', () => {
+ render(<WelcomeConsumer />);
+ expect(screen.getByText('hello')).toBeInTheDocument();
+ });
+
+ it('resolves the default atom even without a wrapping SlotsProvider', () => {
+ render(<WelcomeConsumer />);
+ expect(screen.getByText('hello')).toBeInTheDocument();
+ });
+
+ it('resolves an overridden atom when wrapped in SlotsProvider', () => {
+ render(
+ <SlotsProvider overrides={{ WelcomeScreen }}>
+ <WelcomeConsumer />
+ </SlotsProvider>,
+ );
+ expect(screen.getByText('hello')).toBeInTheDocument();
+ });
+
+ it('provides the consumer-controlled theme mode', () => {
+ render(
+ <SlotsProvider theme={{ mode: 'dark' }}>
+ <ThemeModeConsumer />
+ </SlotsProvider>,
+ );
+
+ expect(screen.getByText('dark')).toBeInTheDocument();
+ });
+
+ it('replaces the resolved atom entirely with the override, not merging it', () => {
+ render(
+ <SlotsProvider overrides={{ WelcomeScreen: CustomWelcome }}>
+ <WelcomeConsumer />
+ </SlotsProvider>,
+ );
+ expect(screen.getByTestId('custom-welcome')).toBeInTheDocument();
+ expect(screen.queryByText('hello')).not.toBeInTheDocument();
+ });
+
+ it('nested SlotsProviders only override the slots they specify, inheriting the rest', () => {
+ function AccordionConsumer() {
+ const Accordion = useSlot('Accordion');
+ return <Accordion>nested-ok</Accordion>;
+ }
+
+ render(
+ <SlotsProvider overrides={{ WelcomeScreen: CustomWelcome }}>
+ <AccordionConsumer />
+ </SlotsProvider>,
+ );
+ expect(screen.getByText('nested-ok')).toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/theme/SlotsProvider.tsx b/packages/trueforge-ui-sdk/src/theme/SlotsProvider.tsx
new file mode 100644
index 000000000..8921b0657
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/theme/SlotsProvider.tsx
@@ -0,0 +1,96 @@
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+
+import type {
+ ComposerLeftSectionProps,
+ ComposerRightSectionProps,
+ ComposerSendButtonProps,
+} from '../atoms/ComposerSections.js';
+import { defaultSlots } from './defaultSlots.js';
+import { ThemeProvider, useOptionalThemeMode } from './ThemeProvider.js';
+import type { ThemeConfig } from './types.js';
+
+export type { ThemeConfig, ThemeMode } from './types.js';
+
+/**
+ * Registry of atom-name -> atom-implementation. Empty by default; each atom module
+ * augments this interface via `declare module "../theme/SlotsProvider"` when it is
+ * introduced, so adding an atom never requires editing this file or any container.
+ */
+export interface AtomSlots {
+ ComposerLeftSection: ComposerLeftSectionSlot;
+ ComposerRightSection: ComposerRightSectionSlot;
+ ComposerSendButton: ComposerSendButtonSlot;
+}
+
+export type ComposerLeftSectionSlot = (props: ComposerLeftSectionProps) => ReactNode;
+export type ComposerRightSectionSlot = (props: ComposerRightSectionProps) => ReactNode;
+export type ComposerSendButtonSlot = (props: ComposerSendButtonProps) => ReactNode;
+
+export type SlotOverrides = Partial<AtomSlots>;
+
+const SlotsContext = createContext<AtomSlots>(defaultSlots);
+const ThemeModeContext = createContext<'light' | 'dark' | undefined>(undefined);
+
+/** Merges `overrides` over parent/default slots. Containers resolve atoms via `useSlot`. */
+export function SlotsProvider({
+ overrides,
+ theme,
+ children,
+}: {
+ overrides?: SlotOverrides;
+ /** Theme config. Pass `mode` for controlled light/dark/system; omit `mode` for uncontrolled. */
+ theme?: ThemeConfig;
+ children: ReactNode;
+}) {
+ const parentSlots = useContext(SlotsContext);
+ const inheritedTheme = useContext(ThemeModeContext);
+ const resolved = useMemo(() => ({ ...parentSlots, ...overrides }) as AtomSlots, [parentSlots, overrides]);
+
+ const slotsTree = (
+ <SlotsProviderContents slots={resolved} inheritedTheme={inheritedTheme} theme={theme}>
+ {children}
+ </SlotsProviderContents>
+ );
+
+ // Nest ThemeProvider only when this SlotsProvider owns a theme config, or when
+ // there is no parent theme yet (outermost provider).
+ const hasParentTheme = inheritedTheme !== undefined;
+ if (theme !== undefined || !hasParentTheme) {
+ return <ThemeProvider theme={theme}>{slotsTree}</ThemeProvider>;
+ }
+
+ return slotsTree;
+}
+
+function SlotsProviderContents({
+ slots,
+ children,
+ inheritedTheme,
+ theme,
+}: {
+ slots: AtomSlots;
+ children: ReactNode;
+ inheritedTheme: 'light' | 'dark' | undefined;
+ theme?: ThemeConfig;
+}) {
+ const modeFromProvider = useOptionalThemeMode();
+ const controlledMode = theme?.mode === 'light' || theme?.mode === 'dark' ? theme.mode : undefined;
+ const resolvedTheme = controlledMode ?? inheritedTheme ?? modeFromProvider;
+
+ return (
+ <ThemeModeContext.Provider value={resolvedTheme}>
+ <SlotsContext.Provider value={slots}>{children}</SlotsContext.Provider>
+ </ThemeModeContext.Provider>
+ );
+}
+
+/** Resolves the atom implementation registered for `name` -- default unless overridden. */
+export function useSlot<K extends keyof AtomSlots>(name: K): AtomSlots[K] {
+ const slots = useContext(SlotsContext);
+ return slots[name];
+}
+
+/** Resolves the light or dark theme mode supplied by the SDK consumer. */
+export function useThemeMode(): 'light' | 'dark' {
+ return useContext(ThemeModeContext) ?? 'light';
+}
diff --git a/packages/trueforge-ui-sdk/src/theme/ThemeProvider.test.tsx b/packages/trueforge-ui-sdk/src/theme/ThemeProvider.test.tsx
new file mode 100644
index 000000000..e13ba67bb
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/theme/ThemeProvider.test.tsx
@@ -0,0 +1,228 @@
+// @vitest-environment jsdom
+import { act, render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+
+import { WelcomeScreen } from '../atoms/WelcomeScreen.js';
+import { BrandIcon, BrandLogo } from './brand.js';
+import { ThemeProvider, useBrand, useTheme } from './ThemeProvider.js';
+
+function ModeProbe() {
+ const { mode, preference, setTheme } = useTheme();
+ return (
+ <div>
+ <output data-testid="mode">{mode}</output>
+ <output data-testid="preference">{preference}</output>
+ <button type="button" onClick={() => setTheme('dark')}>
+ dark
+ </button>
+ <button type="button" onClick={() => setTheme('system')}>
+ system
+ </button>
+ </div>
+ );
+}
+
+function BrandProbe() {
+ const brand = useBrand();
+ return <output data-testid="brand-name">{brand.name ?? 'none'}</output>;
+}
+
+describe('ThemeProvider', () => {
+ it('applies controlled mode and ignores setTheme', () => {
+ render(
+ <ThemeProvider theme={{ mode: 'dark' }}>
+ <ModeProbe />
+ </ThemeProvider>,
+ );
+ expect(screen.getByTestId('mode')).toHaveTextContent('dark');
+ act(() => {
+ screen.getByRole('button', { name: 'system' }).click();
+ });
+ expect(screen.getByTestId('mode')).toHaveTextContent('dark');
+ });
+
+ it('toggles mode when uncontrolled', () => {
+ render(
+ <ThemeProvider>
+ <ModeProbe />
+ </ThemeProvider>,
+ );
+ act(() => {
+ screen.getByRole('button', { name: 'dark' }).click();
+ });
+ expect(screen.getByTestId('mode')).toHaveTextContent('dark');
+ expect(document.documentElement.classList.contains('dark')).toBe(true);
+ });
+
+ it('exposes brand config and BrandLogo / BrandIcon', () => {
+ render(
+ <ThemeProvider theme={{ brand: { name: 'Acme' } }}>
+ <BrandProbe />
+ <BrandLogo />
+ <BrandIcon className="size-4" />
+ </ThemeProvider>,
+ );
+ expect(screen.getByTestId('brand-name')).toHaveTextContent('Acme');
+ expect(screen.getAllByText('Acme').length).toBeGreaterThanOrEqual(1);
+ });
+
+ it('writes token CSS vars on the theme root', () => {
+ const { container } = render(
+ <ThemeProvider theme={{ tokens: { primary: '#e11d48' }, className: 'host-chat' }}>
+ <span>child</span>
+ </ThemeProvider>,
+ );
+ const root = container.querySelector('.aui-theme-root') as HTMLElement;
+ expect(root.classList.contains('host-chat')).toBe(true);
+ expect(root.style.getPropertyValue('--primary')).toBe('#e11d48');
+ });
+
+ it('applies preset tokens', () => {
+ const { container } = render(
+ <ThemeProvider theme={{ preset: 'chatgpt', mode: 'light' }}>
+ <span>child</span>
+ </ThemeProvider>,
+ );
+ const root = container.querySelector('.aui-theme-root') as HTMLElement;
+ expect(root.getAttribute('data-preset')).toBe('chatgpt');
+ expect(root.style.getPropertyValue('--primary')).toBe('#0d0d0d');
+ expect(root.style.getPropertyValue('--background')).toBe('#ffffff');
+ expect(root.style.getPropertyValue('--font-agent-ui')).toBe(
+ '"GeistSans", "GeistSans Fallback", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+ );
+ expect(root.style.fontFamily).toBe('');
+ expect(root.style.getPropertyValue('--radius')).toBe('1.5rem');
+ expect(root.style.getPropertyValue('--composer-radius')).toBe('1.75rem');
+ expect(root.style.getPropertyValue('--user-bubble')).toBe('#e9e9e980');
+ expect(root.style.getPropertyValue('--user-bubble-foreground')).toBe('#0d0d0d');
+ });
+
+ it('applies chatgpt dark palette', () => {
+ const { container } = render(
+ <ThemeProvider theme={{ preset: 'chatgpt', mode: 'dark' }}>
+ <span>child</span>
+ </ThemeProvider>,
+ );
+ const root = container.querySelector('.aui-theme-root') as HTMLElement;
+ expect(root.style.getPropertyValue('--background')).toBe('#000000');
+ expect(root.style.getPropertyValue('--card')).toBe('#212121');
+ expect(root.style.getPropertyValue('--primary')).toBe('#ffffff');
+ expect(root.style.getPropertyValue('--secondary')).toBe('#303030');
+ expect(root.style.getPropertyValue('--user-bubble')).toBe('#323232');
+ expect(root.style.getPropertyValue('--user-bubble-foreground')).toBe('#ffffff');
+ });
+
+ it('applies claude palette', () => {
+ const { container } = render(
+ <ThemeProvider theme={{ preset: 'claude', mode: 'light' }}>
+ <span>child</span>
+ </ThemeProvider>,
+ );
+ const root = container.querySelector('.aui-theme-root') as HTMLElement;
+ expect(root.getAttribute('data-preset')).toBe('claude');
+ expect(root.style.getPropertyValue('--background')).toBe('#f0ece0');
+ expect(root.style.getPropertyValue('--foreground')).toBe('#1a1a18');
+ expect(root.style.getPropertyValue('--card')).toBe('#ffffff');
+ expect(root.style.getPropertyValue('--primary')).toBe('#c96442');
+ expect(root.style.getPropertyValue('--font-agent-ui')).toBe(
+ 'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',
+ );
+ expect(root.style.getPropertyValue('--radius')).toBe('1rem');
+ expect(root.style.getPropertyValue('--composer-radius')).toBe('1rem');
+ expect(root.style.getPropertyValue('--user-bubble')).toBe('#e5e0d6');
+ expect(root.style.getPropertyValue('--user-bubble-foreground')).toBe('#1a1a18');
+ });
+
+ it('applies claude dark palette', () => {
+ const { container } = render(
+ <ThemeProvider theme={{ preset: 'claude', mode: 'dark' }}>
+ <span>child</span>
+ </ThemeProvider>,
+ );
+ const root = container.querySelector('.aui-theme-root') as HTMLElement;
+ expect(root.style.getPropertyValue('--background')).toBe('#2b2a27');
+ expect(root.style.getPropertyValue('--foreground')).toBe('#eeeeee');
+ expect(root.style.getPropertyValue('--card')).toBe('#1f1e1b');
+ expect(root.style.getPropertyValue('--primary')).toBe('#c96442');
+ expect(root.style.getPropertyValue('--user-bubble')).toBe('#3d3a35');
+ expect(root.style.getPropertyValue('--user-bubble-foreground')).toBe('#eeeeee');
+ });
+
+ it('applies gemini light palette', () => {
+ const { container } = render(
+ <ThemeProvider theme={{ preset: 'gemini', mode: 'light' }}>
+ <span>child</span>
+ </ThemeProvider>,
+ );
+ const root = container.querySelector('.aui-theme-root') as HTMLElement;
+ expect(root.style.getPropertyValue('--background')).toBe('#fdfcfc');
+ expect(root.style.getPropertyValue('--foreground')).toBe('#1f1f1f');
+ expect(root.style.getPropertyValue('--primary')).toBe('#1f3b9b');
+ expect(root.style.getPropertyValue('--font-agent-ui')).toBe(
+ '"GeistSans", "GeistSans Fallback", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+ );
+ expect(root.style.getPropertyValue('--radius')).toBe('1rem');
+ expect(root.style.getPropertyValue('--composer-radius')).toBe('2rem');
+ expect(root.style.getPropertyValue('--user-bubble')).toBe('#f3f6fc');
+ });
+
+ it('applies gemini dark palette', () => {
+ const { container } = render(
+ <ThemeProvider theme={{ preset: 'gemini', mode: 'dark' }}>
+ <span>child</span>
+ </ThemeProvider>,
+ );
+ const root = container.querySelector('.aui-theme-root') as HTMLElement;
+ expect(root.style.getPropertyValue('--background')).toBe('#0c0c0c');
+ expect(root.style.getPropertyValue('--card')).toBe('#1e1f20');
+ expect(root.style.getPropertyValue('--primary')).toBe('#a8c7fa');
+ expect(root.style.getPropertyValue('--primary-foreground')).toBe('#062e6f');
+ expect(root.style.getPropertyValue('--ring')).toBe('#a8c7fa');
+ expect(root.style.getPropertyValue('--user-bubble')).toBe('#222327');
+ });
+
+ it('preserves the semibold TrueFoundry welcome heading', () => {
+ render(
+ <ThemeProvider theme={{ preset: 'truefoundry', mode: 'light' }}>
+ <WelcomeScreen />
+ </ThemeProvider>,
+ );
+
+ expect(screen.getByRole('heading', { name: 'How can I help you today?' })).toHaveClass('font-semibold');
+ });
+
+ it('uses regular heading weight for the ChatGPT welcome', () => {
+ const { container } = render(
+ <ThemeProvider theme={{ preset: 'chatgpt', mode: 'light' }}>
+ <WelcomeScreen />
+ </ThemeProvider>,
+ );
+
+ expect(screen.getByRole('heading', { name: 'How can I help you today?' })).toHaveClass('font-normal');
+ expect(container.querySelector('.aui-thread-welcome-root')).toHaveAttribute('data-preset', 'chatgpt');
+ });
+
+ it("renders Claude's filled sparkle welcome icon", () => {
+ const { container } = render(
+ <ThemeProvider theme={{ preset: 'claude', mode: 'light' }}>
+ <WelcomeScreen />
+ </ThemeProvider>,
+ );
+
+ expect(container.querySelector('.aui-thread-welcome-root svg')).toHaveClass('fill-current');
+ });
+
+ it('renders the animated Gemini welcome glow', () => {
+ const { container } = render(
+ <ThemeProvider theme={{ preset: 'gemini', mode: 'dark' }}>
+ <WelcomeScreen />
+ </ThemeProvider>,
+ );
+
+ expect(screen.getByRole('heading', { name: 'How can I help you today?' })).toHaveClass(
+ 'font-normal',
+ 'duration-300',
+ );
+ expect(container.querySelector('[aria-hidden].motion-safe\\:animate-pulse')).toBeInTheDocument();
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/theme/ThemeProvider.tsx b/packages/trueforge-ui-sdk/src/theme/ThemeProvider.tsx
new file mode 100644
index 000000000..32e0e9db7
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/theme/ThemeProvider.tsx
@@ -0,0 +1,210 @@
+'use client';
+
+import {
+ createContext,
+ useCallback,
+ useContext,
+ useEffect,
+ useLayoutEffect,
+ useMemo,
+ useState,
+ type CSSProperties,
+ type ReactNode,
+} from 'react';
+
+import { cn } from '../atoms/lib/cn.js';
+import { resolvePresetTokens } from './presets/index.js';
+import {
+ TOKEN_CSS_VARS,
+ type BrandConfig,
+ type ContentClassNames,
+ type IconMap,
+ type SemanticTokens,
+ type ThemeConfig,
+ type ThemeMode,
+ type ThemePreset,
+} from './types.js';
+
+export type ThemeContextValue = {
+ preset: ThemePreset;
+ /** Resolved light/dark (never `"system"`). */
+ mode: 'light' | 'dark';
+ /** Preference including `"system"` when uncontrolled. */
+ preference: ThemeMode;
+ isDark: boolean;
+ setTheme: (mode: ThemeMode) => void;
+ brand: BrandConfig;
+ icons: IconMap;
+ classNames: ContentClassNames;
+ tokens: Partial<SemanticTokens>;
+};
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+export { ThemeContext };
+
+const STORAGE_KEY = 'aui-theme-preference';
+
+function getSystemTheme(): 'light' | 'dark' {
+ if (typeof window === 'undefined') return 'light';
+ try {
+ return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+ } catch {
+ return 'light';
+ }
+}
+
+function resolveMode(preference: ThemeMode): 'light' | 'dark' {
+ return preference === 'system' ? getSystemTheme() : preference;
+}
+
+function readStoredPreference(): ThemeMode {
+ if (typeof window === 'undefined') return 'system';
+ try {
+ const stored = localStorage.getItem(STORAGE_KEY);
+ if (stored === 'light' || stored === 'dark' || stored === 'system') return stored;
+ } catch {
+ /* ignore */
+ }
+ return 'system';
+}
+
+function applyDarkClass(mode: 'light' | 'dark') {
+ if (typeof document === 'undefined') return;
+ document.documentElement.classList.toggle('dark', mode === 'dark');
+}
+
+function tokensToStyle(tokens: Partial<SemanticTokens> | undefined): CSSProperties {
+ if (!tokens) return {};
+ const style: Record<string, string> = {};
+ for (const [key, value] of Object.entries(tokens) as [keyof SemanticTokens, string | undefined][]) {
+ if (value == null) continue;
+ style[TOKEN_CSS_VARS[key]] = value;
+ }
+ return style as CSSProperties;
+}
+
+export function ThemeProvider({ theme, children }: { theme?: ThemeConfig; children: ReactNode }) {
+ const isControlled = theme?.mode !== undefined;
+ const [preference, setPreference] = useState<ThemeMode>(() => theme?.mode ?? readStoredPreference());
+ const [mode, setMode] = useState<'light' | 'dark'>(() => resolveMode(theme?.mode ?? readStoredPreference()));
+
+ useLayoutEffect(() => {
+ if (theme?.mode !== undefined) {
+ setPreference(theme.mode);
+ const resolved = resolveMode(theme.mode);
+ setMode(resolved);
+ applyDarkClass(resolved);
+ return;
+ }
+ const stored = readStoredPreference();
+ const resolved = resolveMode(stored);
+ setPreference(stored);
+ setMode(resolved);
+ applyDarkClass(resolved);
+ }, [theme?.mode]);
+
+ useEffect(() => {
+ if (isControlled || typeof window === 'undefined' || typeof window.matchMedia !== 'function') {
+ return;
+ }
+ const mq = window.matchMedia('(prefers-color-scheme: dark)');
+ const onChange = () => {
+ if (preference !== 'system') return;
+ const resolved = getSystemTheme();
+ setMode(resolved);
+ applyDarkClass(resolved);
+ };
+ mq.addEventListener('change', onChange);
+ return () => mq.removeEventListener('change', onChange);
+ }, [isControlled, preference]);
+
+ const setTheme = useCallback(
+ (next: ThemeMode) => {
+ if (isControlled) return;
+ const resolved = resolveMode(next);
+ setPreference(next);
+ setMode(resolved);
+ applyDarkClass(resolved);
+ try {
+ localStorage.setItem(STORAGE_KEY, next);
+ } catch {
+ /* ignore */
+ }
+ },
+ [isControlled],
+ );
+
+ const value = useMemo<ThemeContextValue>(
+ () => ({
+ preset: theme?.preset ?? 'truefoundry',
+ mode,
+ preference,
+ isDark: mode === 'dark',
+ setTheme,
+ brand: theme?.brand ?? {},
+ icons: theme?.icons ?? {},
+ classNames: theme?.classNames ?? {},
+ tokens: theme?.tokens ?? {},
+ }),
+ [mode, preference, setTheme, theme?.preset, theme?.brand, theme?.icons, theme?.classNames, theme?.tokens],
+ );
+
+ const rootStyle = useMemo(() => {
+ const presetTokens = resolvePresetTokens(theme?.preset, mode);
+ return tokensToStyle({ ...presetTokens, ...theme?.tokens });
+ }, [theme?.preset, theme?.tokens, mode]);
+
+ return (
+ <ThemeContext.Provider value={value}>
+ <div
+ className={cn('aui-theme-root h-full min-h-0', theme?.className)}
+ data-theme={mode}
+ data-preset={theme?.preset ?? 'truefoundry'}
+ style={rootStyle}
+ >
+ {children}
+ </div>
+ </ThemeContext.Provider>
+ );
+}
+
+function useThemeContext(): ThemeContextValue {
+ const ctx = useContext(ThemeContext);
+ if (!ctx) {
+ throw new Error('useTheme must be used within a ThemeProvider');
+ }
+ return ctx;
+}
+
+export function useTheme(): Pick<ThemeContextValue, 'preset' | 'mode' | 'preference' | 'isDark' | 'setTheme'> {
+ const { preset, mode, preference, isDark, setTheme } = useThemeContext();
+ return { preset, mode, preference, isDark, setTheme };
+}
+
+export function useBrand(): BrandConfig {
+ return useThemeContext().brand;
+}
+
+export function useContentClassNames(): ContentClassNames {
+ return useThemeContext().classNames;
+}
+
+export function useThemeIcons(): IconMap {
+ return useThemeContext().icons;
+}
+
+/** Safe for trees that may sit outside ThemeProvider (falls back to light). */
+export function useOptionalThemeMode(): 'light' | 'dark' {
+ return useContext(ThemeContext)?.mode ?? 'light';
+}
+
+/** Safe for trees that may sit outside ThemeProvider (falls back to truefoundry). */
+export function useOptionalThemePreset(): ThemePreset {
+ return useContext(ThemeContext)?.preset ?? 'truefoundry';
+}
+
+/** Safe for trees that may sit outside ThemeProvider (falls back to {}). */
+export function useOptionalContentClassNames(): ContentClassNames {
+ return useContext(ThemeContext)?.classNames ?? {};
+}
diff --git a/packages/trueforge-ui-sdk/src/theme/brand.tsx b/packages/trueforge-ui-sdk/src/theme/brand.tsx
new file mode 100644
index 000000000..6b9f1060e
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/theme/brand.tsx
@@ -0,0 +1,57 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+import { useContext } from 'react';
+
+import { cn } from '../atoms/lib/cn.js';
+import { ThemeContext } from './ThemeProvider.js';
+import type { BrandConfig, BrandImage } from './types.js';
+
+function DefaultBrandIcon({ className }: { className?: string }) {
+ return (
+ <svg className={className} viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden>
+ <rect width="24" height="24" rx="6" fill="currentColor" opacity="0.12" />
+ <path
+ d="M7 12.5 10.2 16 17 8"
+ stroke="currentColor"
+ strokeWidth="2"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ />
+ </svg>
+ );
+}
+
+function DefaultBrandLogo({ className, name }: { className?: string; name: string }) {
+ return (
+ <span className={cn('inline-flex items-center gap-2 font-semibold tracking-tight', className)}>
+ <DefaultBrandIcon className="size-5" />
+ <span>{name}</span>
+ </span>
+ );
+}
+
+function renderBrandImage(image: BrandImage | undefined, fallback: ReactNode, className?: string): ReactNode {
+ if (image == null) return fallback;
+ if (typeof image === 'function') return image({ className });
+ if (typeof image === 'object' && image !== null && 'src' in image) {
+ return <img src={image.src} alt={image.alt ?? ''} className={className} />;
+ }
+ return image;
+}
+
+function useOptionalBrand(): BrandConfig {
+ return useContext(ThemeContext)?.brand ?? {};
+}
+
+export function BrandLogo({ className }: { className?: string }) {
+ const brand = useOptionalBrand();
+ const name = brand.name ?? 'TrueFoundry';
+ return <>{renderBrandImage(brand.logo, <DefaultBrandLogo className={className} name={name} />, className)}</>;
+}
+
+export function BrandIcon({ className }: { className?: string }) {
+ const brand = useOptionalBrand();
+ return <>{renderBrandImage(brand.icon, <DefaultBrandIcon className={className} />, className)}</>;
+}
diff --git a/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts b/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts
new file mode 100644
index 000000000..48c12c11d
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts
@@ -0,0 +1,114 @@
+import { Accordion, AccordionDetails, AccordionSummary } from '../atoms/primitives/Accordion.js';
+
+import { AgentStepsCard } from '../atoms/adapters/AgentStepsCardAdapter.js';
+import { AskUserPrompt } from '../atoms/adapters/AskUserPromptAdapter.js';
+import { McpAuthPrompt } from '../atoms/adapters/McpAuthPromptAdapter.js';
+import { ReasoningCard } from '../atoms/adapters/ReasoningCardAdapter.js';
+
+import { AgentsLibraryButton } from '../atoms/AgentsLibraryButton.js';
+import { AssistantMessageBubble } from '../atoms/AssistantMessageBubble.js';
+import { AttachmentCard } from '../atoms/AttachmentCard.js';
+import { AttachmentPickerButton } from '../atoms/AttachmentPickerButton.js';
+import { AttachmentPreviewDialog } from '../atoms/AttachmentPreviewDialog.js';
+import { ClearChatButton } from '../atoms/ClearChatButton.js';
+import { ComposerLeftSection, ComposerRightSection, ComposerSendButton } from '../atoms/ComposerSections.js';
+import { ComposerShell } from '../atoms/ComposerShell.js';
+import { HistoryLoader } from '../atoms/HistoryLoader.js';
+import { Markdown } from '../atoms/Markdown.js';
+import { MessageActionBar } from '../atoms/MessageActionBar.js';
+import { MessageErrorBanner } from '../atoms/MessageErrorBanner.js';
+import { MessageIndicator } from '../atoms/MessageIndicator.js';
+import { MessageTimestamp } from '../atoms/MessageTimestamp.js';
+import { OpenUiFenceBlock } from '../atoms/OpenUiFenceBlock.js';
+import { SandboxArtifactDownload } from '../atoms/SandboxArtifactDownload.js';
+import { SandboxToolCallCard } from '../atoms/SandboxToolCallCard.js';
+import { ScrollToBottomButton } from '../atoms/ScrollToBottomButton.js';
+import { MessageListSkeleton } from '../atoms/Skeletons.js';
+import { SubAgentCard } from '../atoms/SubAgentCard.js';
+import {
+ ThreadListEmptyState,
+ ThreadListNewButton,
+ ThreadListRowSkeleton,
+ ThreadListShell,
+} from '../atoms/ThreadListMisc.js';
+import { ThreadListRow } from '../atoms/ThreadListRow.js';
+import { MessageGroup, ThreadComposerAreaShell, ThreadRootShell, ThreadViewportShell } from '../atoms/ThreadShell.js';
+import { Toast, ToastStack } from '../atoms/Toast.js';
+import { ToolApprovalBar } from '../atoms/ToolApprovalBar.js';
+import { ToolCallCard } from '../atoms/ToolCallCard.js';
+import { ToolCallContentBlock } from '../atoms/ToolCallContentBlock.js';
+import { ToolGroupCard } from '../atoms/ToolGroupCard.js';
+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 type { AtomSlots } from './SlotsProvider.js';
+
+// 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";
+// import { IconButton } from "../atoms/primitives/IconButton.js";
+// import { Skeleton } from "../atoms/primitives/Skeleton.js";
+// import { LightTooltip } from "../atoms/primitives/Tooltip.js";
+// import { Avatar, AvatarFallback, AvatarImage } from "../atoms/primitives/Avatar.js";
+
+/** Default slot implementations. Feature atoms + chrome; primitives via theme/CSS. */
+export const defaultSlots: AtomSlots = {
+ Accordion,
+ AccordionSummary,
+ AccordionDetails,
+ ComposerShell,
+ ComposerLeftSection,
+ ComposerRightSection,
+ ComposerSendButton,
+ AssistantMessageBubble,
+ UserMessageBubble,
+ UserMessageEdit,
+ UserMessageActionBar,
+ MessageActionBar,
+ MessageErrorBanner,
+ MessageIndicator,
+ MessageTimestamp,
+ Markdown,
+ OpenUiFenceBlock,
+ SandboxArtifactDownload,
+ WelcomeScreen,
+ ToolCallCard,
+ ToolCallContentBlock,
+ ToolApprovalBar,
+ ToolGroupCard,
+ SubAgentCard,
+ SandboxToolCallCard,
+ AgentStepsCard,
+ ReasoningCard,
+ AskUserPrompt,
+ McpAuthPrompt,
+ AttachmentCard,
+ AttachmentPreviewDialog,
+ AttachmentPickerButton,
+ ScrollToBottomButton,
+ ThreadListRow,
+ ThreadListNewButton,
+ AgentsLibraryButton,
+ ClearChatButton,
+ ThreadListRowSkeleton,
+ ThreadListEmptyState,
+ ThreadListShell,
+ HistoryLoader,
+ MessageListSkeleton,
+ ThreadRootShell,
+ ThreadViewportShell,
+ ThreadComposerAreaShell,
+ MessageGroup,
+ Toast,
+ ToastStack,
+};
+
+declare module './SlotsProvider.js' {
+ interface AtomSlots {
+ Accordion: typeof Accordion;
+ AccordionSummary: typeof AccordionSummary;
+ AccordionDetails: typeof AccordionDetails;
+ OpenUiFenceBlock: typeof OpenUiFenceBlock;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/theme/presets/index.ts b/packages/trueforge-ui-sdk/src/theme/presets/index.ts
new file mode 100644
index 000000000..9a3fde439
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/theme/presets/index.ts
@@ -0,0 +1,240 @@
+import type { SemanticTokens, ThemePreset } from '../types.js';
+
+export type PresetTokens = {
+ light: SemanticTokens;
+ dark: SemanticTokens;
+};
+
+const truefoundry: PresetTokens = {
+ light: {
+ background: '#ffffff',
+ foreground: '#09090b',
+ card: '#ffffff',
+ cardForeground: '#09090b',
+ popover: '#ffffff',
+ popoverForeground: '#09090b',
+ primary: '#09090b',
+ primaryForeground: '#ffffff',
+ secondary: '#f4f4f5',
+ secondaryForeground: '#09090b',
+ muted: '#f4f4f5',
+ mutedForeground: '#62626a',
+ accent: '#f1f1f2',
+ accentForeground: '#09090b',
+ destructive: '#ef4444',
+ destructiveForeground: '#ffffff',
+ border: '#e4e4e7',
+ input: '#e4e4e7',
+ ring: '#09090b',
+ radius: '0.5rem',
+ fontSans: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+ composerRadius: '1.5rem',
+ userBubble: '#09090b',
+ userBubbleForeground: '#ffffff',
+ },
+ dark: {
+ background: '#1f1f22',
+ foreground: '#fdfdfd',
+ card: '#18181b',
+ cardForeground: '#fdfdfd',
+ popover: '#18181b',
+ popoverForeground: '#fdfdfd',
+ primary: '#6366f1',
+ primaryForeground: '#ffffff',
+ secondary: '#27272a',
+ secondaryForeground: '#fdfdfd',
+ muted: '#27272a',
+ mutedForeground: '#a1a1aa',
+ accent: '#343439',
+ accentForeground: '#fdfdfd',
+ destructive: '#ef4444',
+ destructiveForeground: '#ffffff',
+ border: '#343439',
+ input: '#343439',
+ ring: '#6366f1',
+ radius: '0.5rem',
+ fontSans: 'ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif',
+ composerRadius: '1.5rem',
+ userBubble: '#6366f1',
+ userBubbleForeground: '#ffffff',
+ },
+};
+
+/** assistant-ui's Claude clone: warm cream surfaces, serif type, and orange actions. */
+const claude: PresetTokens = {
+ light: {
+ background: '#f0ece0',
+ foreground: '#1a1a18',
+ card: '#ffffff',
+ cardForeground: '#1a1a18',
+ popover: '#ffffff',
+ popoverForeground: '#1a1a18',
+ primary: '#c96442',
+ primaryForeground: '#ffffff',
+ secondary: '#e5e0d6',
+ secondaryForeground: '#1a1a18',
+ muted: '#e5e0d6',
+ mutedForeground: '#5b5950',
+ accent: '#1a1a180d',
+ accentForeground: '#1a1a18',
+ destructive: '#d03b3b',
+ destructiveForeground: '#ffffff',
+ border: '#e5e0d6',
+ input: '#e5e0d6',
+ ring: '#c96442',
+ radius: '1rem',
+ fontSans: 'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',
+ composerRadius: '1rem',
+ userBubble: '#e5e0d6',
+ userBubbleForeground: '#1a1a18',
+ },
+ dark: {
+ background: '#2b2a27',
+ foreground: '#eeeeee',
+ card: '#1f1e1b',
+ cardForeground: '#eeeeee',
+ popover: '#1f1e1b',
+ popoverForeground: '#eeeeee',
+ primary: '#c96442',
+ primaryForeground: '#ffffff',
+ secondary: '#3d3a35',
+ secondaryForeground: '#eeeeee',
+ muted: '#1f1e1b',
+ mutedForeground: '#a3a098',
+ accent: '#ffffff0d',
+ accentForeground: '#eeeeee',
+ destructive: '#d03b3b',
+ destructiveForeground: '#ffffff',
+ border: '#3d3a35',
+ input: '#3d3a35',
+ ring: '#c96442',
+ radius: '1rem',
+ fontSans: 'ui-serif, Georgia, Cambria, "Times New Roman", Times, serif',
+ composerRadius: '1rem',
+ userBubble: '#3d3a35',
+ userBubbleForeground: '#eeeeee',
+ },
+};
+
+/** assistant-ui's ChatGPT clone: stark surfaces and high-contrast controls. */
+const chatgpt: PresetTokens = {
+ light: {
+ background: '#ffffff',
+ foreground: '#0d0d0d',
+ card: '#ffffff',
+ cardForeground: '#0d0d0d',
+ popover: '#ffffff',
+ popoverForeground: '#0d0d0d',
+ primary: '#0d0d0d',
+ primaryForeground: '#ffffff',
+ secondary: '#ececec',
+ secondaryForeground: '#0d0d0d',
+ muted: '#f9f9f9',
+ mutedForeground: '#5d5d5d',
+ accent: '#00000012',
+ accentForeground: '#0d0d0d',
+ destructive: '#ff002a',
+ destructiveForeground: '#ffffff',
+ border: '#e5e5e5',
+ input: '#e5e5e5',
+ ring: '#0d0d0d',
+ radius: '1.5rem',
+ fontSans: '"GeistSans", "GeistSans Fallback", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+ composerRadius: '1.75rem',
+ userBubble: '#e9e9e980',
+ userBubbleForeground: '#0d0d0d',
+ },
+ dark: {
+ background: '#000000',
+ foreground: '#ececec',
+ card: '#212121',
+ cardForeground: '#ececec',
+ popover: '#212121',
+ popoverForeground: '#ececec',
+ primary: '#ffffff',
+ primaryForeground: '#0d0d0d',
+ secondary: '#303030',
+ secondaryForeground: '#ffffff',
+ muted: '#303030',
+ mutedForeground: '#cdcdcd',
+ accent: '#ffffff26',
+ accentForeground: '#ffffff',
+ destructive: '#ff002a',
+ destructiveForeground: '#ffffff',
+ border: '#ffffff26',
+ input: '#ffffff26',
+ ring: '#ffffff',
+ radius: '1.5rem',
+ fontSans: '"GeistSans", "GeistSans Fallback", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+ composerRadius: '1.75rem',
+ userBubble: '#323232',
+ userBubbleForeground: '#ffffff',
+ },
+};
+
+/** Gemini's Material surfaces and blue action accents. */
+const gemini: PresetTokens = {
+ light: {
+ background: '#fdfcfc',
+ foreground: '#1f1f1f',
+ card: '#ffffff',
+ cardForeground: '#1f1f1f',
+ popover: '#f0f4f9',
+ popoverForeground: '#1f1f1f',
+ primary: '#1f3b9b',
+ primaryForeground: '#ffffff',
+ secondary: '#e8eaed',
+ secondaryForeground: '#1f1f1f',
+ muted: '#f8fafd',
+ mutedForeground: '#444746',
+ accent: '#e9eef6',
+ accentForeground: '#1f1f1f',
+ destructive: '#b3261e',
+ destructiveForeground: '#ffffff',
+ border: '#dadce0',
+ input: '#dadce0',
+ ring: '#1f3b9b',
+ radius: '1rem',
+ fontSans: '"GeistSans", "GeistSans Fallback", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+ composerRadius: '2rem',
+ userBubble: '#f3f6fc',
+ userBubbleForeground: '#1f1f1f',
+ },
+ dark: {
+ background: '#0c0c0c',
+ foreground: '#e3e3e3',
+ card: '#1e1f20',
+ cardForeground: '#e3e3e3',
+ popover: '#282a2c',
+ popoverForeground: '#e3e3e3',
+ primary: '#a8c7fa',
+ primaryForeground: '#062e6f',
+ secondary: '#2b2c2e',
+ secondaryForeground: '#e3e3e3',
+ muted: '#1b1b1b',
+ mutedForeground: '#c4c7c5',
+ accent: '#282a2c',
+ accentForeground: '#e3e3e3',
+ destructive: '#f2b8b5',
+ destructiveForeground: '#601410',
+ border: '#3c4043',
+ input: '#3c4043',
+ ring: '#a8c7fa',
+ radius: '1rem',
+ fontSans: '"GeistSans", "GeistSans Fallback", ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif',
+ composerRadius: '2rem',
+ userBubble: '#222327',
+ userBubbleForeground: '#e3e3e3',
+ },
+};
+
+export const PRESETS: Record<ThemePreset, PresetTokens> = {
+ truefoundry,
+ claude,
+ chatgpt,
+ gemini,
+};
+
+export function resolvePresetTokens(preset: ThemePreset | undefined, mode: 'light' | 'dark'): SemanticTokens {
+ return PRESETS[preset ?? 'truefoundry'][mode];
+}
diff --git a/packages/trueforge-ui-sdk/src/theme/types.ts b/packages/trueforge-ui-sdk/src/theme/types.ts
new file mode 100644
index 000000000..4d0c2e50b
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/theme/types.ts
@@ -0,0 +1,119 @@
+import type { LucideIcon } from 'lucide-react';
+import type { ComponentType, CSSProperties, FC, ReactNode, SVGProps } from 'react';
+
+export type ThemeMode = 'light' | 'dark' | 'system';
+
+export type ThemePreset = 'truefoundry' | 'claude' | 'chatgpt' | 'gemini';
+
+export type SemanticTokens = {
+ background: string;
+ foreground: string;
+ card: string;
+ cardForeground: string;
+ popover: string;
+ popoverForeground: string;
+ primary: string;
+ primaryForeground: string;
+ secondary: string;
+ secondaryForeground: string;
+ muted: string;
+ mutedForeground: string;
+ accent: string;
+ accentForeground: string;
+ destructive: string;
+ destructiveForeground: string;
+ border: string;
+ input: string;
+ ring: string;
+ radius: string;
+ fontSans: string;
+ composerRadius?: string;
+ userBubble?: string;
+ userBubbleForeground?: string;
+ assistantBubble?: string;
+ assistantBubbleForeground?: string;
+};
+
+export type IconProps = {
+ className?: string;
+ style?: CSSProperties;
+ size?: string | number;
+ 'aria-hidden'?: boolean | 'true' | 'false';
+ 'aria-label'?: string;
+};
+
+export type IconMap = Record<
+ string,
+ LucideIcon | ReactNode | ((props: IconProps) => ReactNode) | FC<SVGProps<SVGSVGElement>>
+>;
+
+export type BrandImage = { src: string; alt?: string } | ReactNode | ((props: { className?: string }) => ReactNode);
+
+export type BrandConfig = {
+ logo?: BrandImage;
+ icon?: BrandImage;
+ name?: string;
+};
+
+export type ContentClassNames = {
+ markdown?: string;
+ syntaxHighlighter?: {
+ root?: string;
+ pre?: string;
+ code?: string;
+ lineNumber?: string;
+ };
+ openui?: {
+ root?: string;
+ [key: string]: string | undefined;
+ };
+ monaco?: {
+ root?: string;
+ editor?: string;
+ monacoTheme?: string;
+ };
+};
+
+export type ThemeConfig = {
+ preset?: ThemePreset;
+ mode?: ThemeMode;
+ tokens?: Partial<SemanticTokens>;
+ brand?: BrandConfig;
+ className?: string;
+ icons?: IconMap;
+ classNames?: ContentClassNames;
+};
+
+export type BuiltInLayout = 'sidebar' | 'drawer' | 'dock' | 'widget';
+
+export type LayoutProp = BuiltInLayout | ComponentType<{ className?: string }>;
+
+/** camelCase SemanticTokens key → CSS custom property name */
+export const TOKEN_CSS_VARS: Record<keyof SemanticTokens, string> = {
+ background: '--background',
+ foreground: '--foreground',
+ card: '--card',
+ cardForeground: '--card-foreground',
+ popover: '--popover',
+ popoverForeground: '--popover-foreground',
+ primary: '--primary',
+ primaryForeground: '--primary-foreground',
+ secondary: '--secondary',
+ secondaryForeground: '--secondary-foreground',
+ muted: '--muted',
+ mutedForeground: '--muted-foreground',
+ accent: '--accent',
+ accentForeground: '--accent-foreground',
+ destructive: '--destructive',
+ destructiveForeground: '--destructive-foreground',
+ border: '--border',
+ input: '--input',
+ ring: '--ring',
+ radius: '--radius',
+ fontSans: '--font-agent-ui',
+ composerRadius: '--composer-radius',
+ userBubble: '--user-bubble',
+ userBubbleForeground: '--user-bubble-foreground',
+ assistantBubble: '--assistant-bubble',
+ assistantBubbleForeground: '--assistant-bubble-foreground',
+};
diff --git a/packages/trueforge-ui-sdk/src/theme/useTheme.ts b/packages/trueforge-ui-sdk/src/theme/useTheme.ts
new file mode 100644
index 000000000..02eb005a5
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/theme/useTheme.ts
@@ -0,0 +1 @@
+export { useBrand, useContentClassNames, useTheme, useThemeIcons } from './ThemeProvider.js';
diff --git a/packages/trueforge-ui-sdk/src/utils/computeAgentStepsSplit.test.ts b/packages/trueforge-ui-sdk/src/utils/computeAgentStepsSplit.test.ts
new file mode 100644
index 000000000..c30bff1b3
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/utils/computeAgentStepsSplit.test.ts
@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+
+import type { PartState } from '@assistant-ui/core/react';
+import { computeAgentStepsSplit } from './computeAgentStepsSplit.js';
+
+function text(content: string): PartState {
+ return { type: 'text', text: content } as PartState;
+}
+
+function tool(): PartState {
+ return { type: 'tool-call', toolCallId: '1', toolName: 't' } as PartState;
+}
+
+function reasoning(): PartState {
+ return { type: 'reasoning', text: 'thinking' } as PartState;
+}
+
+describe('computeAgentStepsSplit', () => {
+ it('treats pure text as final immediately while running', () => {
+ const parts = [text('hello world')];
+ const result = computeAgentStepsSplit(parts, true);
+ expect(result.cutIndex).toBe(0);
+ expect(result.hasFinal).toBe(true);
+ expect(result.toolCount).toBe(0);
+ });
+
+ it('holds back short trailing text while running when tools precede it', () => {
+ const parts = [tool(), text('hi')];
+ const result = computeAgentStepsSplit(parts, true);
+ expect(result.hasFinal).toBe(false);
+ expect(result.cutIndex).toBe(parts.length);
+ });
+
+ it('confirms final text once trailing content is long enough', () => {
+ const parts = [tool(), reasoning(), text('x'.repeat(500))];
+ const result = computeAgentStepsSplit(parts, true);
+ expect(result.hasFinal).toBe(true);
+ expect(result.cutIndex).toBe(2);
+ expect(result.toolCount).toBe(1);
+ expect(result.thinkingCount).toBe(1);
+ });
+
+ it('confirms final when not running', () => {
+ const parts = [tool(), text('done')];
+ const result = computeAgentStepsSplit(parts, false);
+ expect(result.hasFinal).toBe(true);
+ expect(result.cutIndex).toBe(1);
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/utils/computeAgentStepsSplit.ts b/packages/trueforge-ui-sdk/src/utils/computeAgentStepsSplit.ts
new file mode 100644
index 000000000..b5e82ea02
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/utils/computeAgentStepsSplit.ts
@@ -0,0 +1,63 @@
+import type { PartState } from '@assistant-ui/core/react';
+
+export interface AgentStepsSplitResult {
+ cutIndex: number;
+ hasFinal: boolean;
+ toolCount: number;
+ thinkingCount: number;
+}
+
+export function computeAgentStepsSplit(parts: readonly PartState[], isRunning: boolean): AgentStepsSplitResult {
+ const finalTexts: Array<{ index: number; content: string }> = [];
+ let cutIdx = parts.length;
+
+ for (let i = parts.length - 1; i >= 0; i--) {
+ const part = parts[i];
+ if (!part) continue;
+
+ if (part.type === 'text') {
+ const text = (part as { text?: string }).text ?? '';
+ const trimmed = text.trim();
+
+ if (trimmed) {
+ finalTexts.unshift({ index: i, content: text });
+ cutIdx = i;
+ } else {
+ cutIdx = i;
+ }
+ } else {
+ break;
+ }
+ }
+
+ const trailingChars = finalTexts.reduce((sum, t) => sum + t.content.length, 0);
+
+ // Only apply the 500-char holdback when there are actual agent steps (tool calls or
+ // reasoning) before the text. For pure-text responses the text is always the final
+ // answer and must stream directly, not be hidden inside the "Agent steps" accordion.
+ const hasAgentStepsBeforeCut = parts.slice(0, cutIdx).some(p => p.type === 'tool-call' || p.type === 'reasoning');
+
+ const finalConfirmed = finalTexts.length > 0 && (!isRunning || trailingChars >= 500 || !hasAgentStepsBeforeCut);
+
+ const actualCutIndex = finalConfirmed ? cutIdx : parts.length;
+
+ let toolCount = 0;
+ let thinkingCount = 0;
+ for (let i = 0; i < actualCutIndex; i++) {
+ const part = parts[i];
+ if (!part) continue;
+
+ if (part.type === 'tool-call') {
+ toolCount++;
+ } else if (part.type === 'reasoning') {
+ thinkingCount++;
+ }
+ }
+
+ return {
+ cutIndex: actualCutIndex,
+ hasFinal: finalConfirmed,
+ toolCount,
+ thinkingCount,
+ };
+}
diff --git a/packages/trueforge-ui-sdk/src/utils/toolCallParsing.test.ts b/packages/trueforge-ui-sdk/src/utils/toolCallParsing.test.ts
new file mode 100644
index 000000000..0e86636fd
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/utils/toolCallParsing.test.ts
@@ -0,0 +1,98 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+ buildApprovalOptions,
+ formatDuration,
+ getAskUserAnswerResult,
+ getJsonDisplayValue,
+ getToolResultContent,
+ mcpDisplayName,
+ parseAskUserQuestionArgs,
+ parseMcpToolArgs,
+ parseSandboxArgs,
+ parseSandboxResult,
+ toStatus,
+} from './toolCallParsing.js';
+
+describe('toolCallParsing', () => {
+ it('parses ask-user args', () => {
+ expect(parseAskUserQuestionArgs(JSON.stringify({ question: 'Pick one', options: ['a', 'b', 3] }))).toEqual({
+ question: 'Pick one',
+ options: ['a', 'b'],
+ });
+ expect(parseAskUserQuestionArgs('not-json')).toEqual({});
+ });
+
+ it('reads ask-user answers from string or content object', () => {
+ expect(getAskUserAnswerResult(' yes ')).toBe('yes');
+ expect(getAskUserAnswerResult({ content: 'no' })).toBe('no');
+ expect(getAskUserAnswerResult('')).toBeUndefined();
+ });
+
+ it('formats durations', () => {
+ expect(formatDuration(500)).toBe('<1s');
+ expect(formatDuration(1500)).toBe('1.5s');
+ expect(formatDuration(15000)).toBe('15s');
+ expect(formatDuration(125000)).toBe('2m 5s');
+ });
+
+ it('maps status types', () => {
+ expect(toStatus('complete')).toBe('success');
+ expect(toStatus('incomplete')).toBe('error');
+ expect(toStatus('running')).toBe('running');
+ });
+
+ it('parses sandbox args and results', () => {
+ expect(parseSandboxArgs(JSON.stringify({ command: 'ls', intent: 'list' }))).toMatchObject({
+ command: 'ls',
+ intent: 'list',
+ });
+ expect(parseSandboxResult(JSON.stringify({ response: { exitCode: 0, result: 'ok' } }))).toMatchObject({
+ exitCode: 0,
+ resultText: 'ok',
+ });
+ expect(parseSandboxResult('plain')).toEqual({ resultText: 'plain' });
+ });
+
+ it('parses mcp tool args and display names', () => {
+ expect(
+ parseMcpToolArgs(
+ JSON.stringify({
+ mcp_server: 'github',
+ tool_name: 'search',
+ input: { q: 'x' },
+ }),
+ ),
+ ).toEqual({
+ mcpServer: 'github',
+ innerToolName: 'search',
+ input: { q: 'x' },
+ });
+ expect(mcpDisplayName('call_tool', 'github', 'search')).toBe('call_tool: search (github)');
+ });
+
+ it('pretty-prints json display values', () => {
+ expect(getJsonDisplayValue('{"a":1}')).toEqual({
+ value: '{\n "a": 1\n}',
+ isJson: true,
+ });
+ expect(getJsonDisplayValue('hello')).toEqual({
+ value: 'hello',
+ isJson: false,
+ });
+ });
+
+ it('extracts tool result content arrays', () => {
+ expect(getToolResultContent({ content: [{ text: '{"ok":true}' }] })).toEqual({
+ data: '{\n "ok": true\n}',
+ isJson: true,
+ });
+ });
+
+ it('builds default approval options when none declared', () => {
+ expect(buildApprovalOptions(undefined)).toEqual([
+ { id: '__allow', label: 'Allow', isAllow: true },
+ { id: '__deny', label: 'Deny', isAllow: false, confirm: {} },
+ ]);
+ });
+});
diff --git a/packages/trueforge-ui-sdk/src/utils/toolCallParsing.ts b/packages/trueforge-ui-sdk/src/utils/toolCallParsing.ts
new file mode 100644
index 000000000..dbc84bbda
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/utils/toolCallParsing.ts
@@ -0,0 +1,264 @@
+import type { ToolApprovalOption as AuiToolApprovalOption, ToolCallMessagePartProps } from '@assistant-ui/react';
+
+import type { ToolCallStatus } from '../atoms/ToolCallCard.js';
+
+export type ApprovalOptionView = {
+ id: string;
+ label: string;
+ isAllow: boolean;
+ grants?: unknown;
+ confirm?: Record<string, unknown>;
+};
+
+export const SUB_AGENT_TOOL_NAME = 'create_sub_agent';
+export const ASK_USER_TOOL_NAME = 'ask_user_question';
+
+/** Tool names that should be rendered as a sandbox execution card. */
+export const SANDBOX_TOOL_NAMES = new Set(['exec', 'sandbox_exec']);
+
+/** MCP meta-tools that wrap actual tool calls. */
+export const MCP_META_TOOLS = new Set(['call_tool', 'list_tools', 'get_tool_info']);
+
+const APPROVAL_OPTION_DEFAULT_LABELS: Record<string, string> = {
+ 'allow-once': 'Allow',
+ 'allow-always': 'Always allow',
+ 'reject-once': 'Deny',
+ 'reject-always': 'Always deny',
+};
+
+const isAllowKind = (kind: string) => kind === 'allow-once' || kind === 'allow-always';
+
+export function parseAskUserQuestionArgs(argsText: string | undefined): {
+ question?: string;
+ options?: string[];
+} {
+ if (!argsText) return {};
+ try {
+ const parsed: unknown = JSON.parse(argsText);
+ if (parsed == null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+ return {};
+ }
+ const record = parsed as Record<string, unknown>;
+ const question = typeof record.question === 'string' ? record.question : undefined;
+ const options = Array.isArray(record.options)
+ ? record.options.filter((item): item is string => typeof item === 'string')
+ : undefined;
+ return { question, options };
+ } catch {
+ return {};
+ }
+}
+
+export function getAskUserAnswerResult(result: unknown): string | undefined {
+ if (result === undefined || result === null) return undefined;
+ if (typeof result === 'string') {
+ const trimmed = result.trim();
+ return trimmed.length > 0 ? trimmed : undefined;
+ }
+ if (typeof result === 'object' && 'content' in result) {
+ const content = (result as { content?: unknown }).content;
+ if (typeof content === 'string' && content.trim()) {
+ return content.trim();
+ }
+ }
+ return undefined;
+}
+
+export function hasPendingAskUserResponse(part: Pick<ToolCallMessagePartProps, 'interrupt' | 'result'>): boolean {
+ return part.interrupt != null && part.result === undefined;
+}
+
+export function hasPendingToolApproval(
+ approval: { approved?: boolean; resolution?: 'cancelled' | 'expired' } | undefined,
+) {
+ return approval != null && approval.approved === undefined && approval.resolution === undefined;
+}
+
+export function buildApprovalOptions(options: readonly AuiToolApprovalOption[] | undefined): ApprovalOptionView[] {
+ const declared = options?.filter(o => Object.hasOwn(APPROVAL_OPTION_DEFAULT_LABELS, o.kind));
+ if (declared && declared.length > 0) {
+ const allow = declared.filter(o => isAllowKind(o.kind));
+ const reject = declared.filter(o => !isAllowKind(o.kind));
+ const mapped: ApprovalOptionView[] = [...allow, ...reject].map(o => ({
+ id: o.id,
+ label: o.label ?? APPROVAL_OPTION_DEFAULT_LABELS[o.kind] ?? o.id,
+ isAllow: isAllowKind(o.kind),
+ grants: o.grants,
+ confirm: o.confirm != null ? (typeof o.confirm === 'object' ? o.confirm : {}) : undefined,
+ }));
+ if (reject.length === 0) {
+ mapped.push({ id: '__deny', label: 'Deny', isAllow: false, confirm: {} });
+ }
+ return mapped;
+ }
+ return [
+ { id: '__allow', label: 'Allow', isAllow: true },
+ { id: '__deny', label: 'Deny', isAllow: false, confirm: {} },
+ ];
+}
+
+export function formatDuration(ms: number): string {
+ if (ms < 1000) return '<1s';
+ const seconds = ms / 1000;
+ if (seconds < 10) return `${(Math.floor(seconds * 10) / 10).toFixed(1)}s`;
+ if (seconds < 60) return `${Math.floor(seconds)}s`;
+ return `${Math.floor(seconds / 60)}m ${Math.floor(seconds % 60)}s`;
+}
+
+export function toStatus(statusType: string | undefined): ToolCallStatus {
+ if (statusType === 'complete') return 'success';
+ if (statusType === 'incomplete') return 'error';
+ return 'running';
+}
+
+export function parseSandboxArgs(argsText: string | undefined): {
+ command?: string;
+ intent?: string;
+ argsJson?: string;
+} {
+ if (!argsText) return {};
+ try {
+ const parsed = JSON.parse(argsText) as {
+ command?: string;
+ intent?: string;
+ };
+ return {
+ command: parsed.command,
+ intent: parsed.intent,
+ argsJson: JSON.stringify(parsed, null, 2),
+ };
+ } catch {
+ return { argsJson: argsText };
+ }
+}
+
+export function parseSandboxResult(result: string | undefined): {
+ exitCode?: number | null;
+ resultText?: string;
+ resultJson?: string;
+} {
+ if (result === undefined) return {};
+ try {
+ const parsed = JSON.parse(result) as {
+ response?: { exitCode?: number; result?: string };
+ };
+ const exitCode = parsed.response?.exitCode ?? null;
+ const resultText = parsed.response?.result;
+ return {
+ exitCode,
+ resultText,
+ resultJson: JSON.stringify(parsed, null, 2),
+ };
+ } catch {
+ return { resultText: result };
+ }
+}
+
+export function parseMcpToolArgs(argsText: string | undefined): {
+ mcpServer?: string;
+ innerToolName?: string;
+ input?: unknown;
+} {
+ if (!argsText) return {};
+ try {
+ const parsed = JSON.parse(argsText) as {
+ mcp_server?: string;
+ tool_name?: string;
+ input?: unknown;
+ };
+ return {
+ mcpServer: parsed.mcp_server,
+ innerToolName: parsed.tool_name,
+ input: parsed.input,
+ };
+ } catch {
+ return {};
+ }
+}
+
+export function getJsonDisplayValue(content: string | undefined): {
+ value: string;
+ isJson: boolean;
+} {
+ if (!content?.trim()) return { value: '', isJson: false };
+ const trimmed = content.trim();
+ if (trimmed[0] !== '{' && trimmed[0] !== '[') {
+ return { value: content, isJson: false };
+ }
+ try {
+ const parsed = JSON.parse(content);
+ return { value: JSON.stringify(parsed, null, 2), isJson: true };
+ } catch {
+ return { value: content, isJson: false };
+ }
+}
+
+export function getToolResultContent(content: unknown): {
+ data: string;
+ isJson: boolean;
+} {
+ try {
+ if (!content) return { isJson: false, data: '' };
+
+ const parsedResult = typeof content === 'string' && content.trim().startsWith('{') ? JSON.parse(content) : content;
+
+ if (
+ typeof parsedResult === 'object' &&
+ parsedResult != null &&
+ Array.isArray((parsedResult as { content?: unknown }).content)
+ ) {
+ const text = (parsedResult as { content: Array<{ text?: unknown }> }).content[0]?.text || '';
+ const display = getJsonDisplayValue(typeof text === 'string' ? text : JSON.stringify(text));
+ return { data: display.value, isJson: display.isJson };
+ }
+ const display = getJsonDisplayValue(typeof parsedResult === 'string' ? parsedResult : JSON.stringify(parsedResult));
+ return { data: display.value, isJson: display.isJson };
+ } catch {
+ return { data: String(content), isJson: false };
+ }
+}
+
+export function resolveSubAgentMeta(part: ToolCallMessagePartProps): {
+ agentName: string;
+ instruction: string;
+ stepCount: number;
+} {
+ const artifactSubAgent = (
+ part as {
+ artifact?: {
+ subAgents?: Array<{
+ title?: string;
+ agentInfo?: { name?: string; input?: string };
+ }>;
+ };
+ }
+ ).artifact?.subAgents?.[0];
+ const firstNested = part.messages?.[0];
+ const subAgent = (
+ firstNested?.metadata?.custom as { subAgent?: { title?: string; name?: string; input?: string } } | undefined
+ )?.subAgent;
+ return {
+ agentName:
+ subAgent?.title ??
+ subAgent?.name ??
+ artifactSubAgent?.title ??
+ artifactSubAgent?.agentInfo?.name ??
+ part.toolName,
+ instruction: subAgent?.input ?? artifactSubAgent?.agentInfo?.input ?? '',
+ stepCount: part.messages?.length ?? 0,
+ };
+}
+
+export function mcpDisplayName(
+ toolName: string,
+ mcpServer: string | undefined,
+ innerToolName: string | undefined,
+): string {
+ if (toolName === 'call_tool' && innerToolName) {
+ return mcpServer ? `call_tool: ${innerToolName} (${mcpServer})` : `call_tool: ${innerToolName}`;
+ }
+ if (toolName === 'get_tool_info' && innerToolName && mcpServer) {
+ return `get_tool_info: ${innerToolName} (${mcpServer})`;
+ }
+ return toolName;
+}
diff --git a/packages/trueforge-ui-sdk/tsconfig.json b/packages/trueforge-ui-sdk/tsconfig.json
new file mode 100644
index 000000000..6ee628623
--- /dev/null
+++ b/packages/trueforge-ui-sdk/tsconfig.json
@@ -0,0 +1,26 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "lib": ["ES2023", "DOM", "DOM.Iterable"],
+ "module": "NodeNext",
+ "moduleResolution": "NodeNext",
+ "jsx": "react-jsx",
+ "strict": true,
+ "skipLibCheck": true,
+ "declaration": true,
+ "declarationMap": true,
+ "sourceMap": true,
+ "rootDir": "src",
+ "outDir": "dist",
+ "baseUrl": ".",
+ "paths": {
+ "@/*": ["src/*"]
+ },
+ "noEmit": true,
+ "isolatedModules": true,
+ "verbatimModuleSyntax": true,
+ "noUncheckedIndexedAccess": true,
+ "types": ["node"]
+ },
+ "include": ["src"]
+}
diff --git a/packages/trueforge-ui-sdk/tsup.config.ts b/packages/trueforge-ui-sdk/tsup.config.ts
new file mode 100644
index 000000000..9a67fad28
--- /dev/null
+++ b/packages/trueforge-ui-sdk/tsup.config.ts
@@ -0,0 +1,42 @@
+/**
+ * tsup build configuration for @truefoundry/trueforge-ui.
+ *
+ * Produces an ESM-only bundle at `dist/index.js` (+ `.d.ts` + sourcemap).
+ */
+import svgr from 'esbuild-plugin-svgr';
+import { defineConfig } from 'tsup';
+
+export default defineConfig({
+ entry: ['src/index.ts', 'src/assistant-ui.ts'],
+ format: ['esm'],
+ dts: true,
+ sourcemap: true,
+ clean: true,
+ target: 'es2022',
+ esbuildPlugins: [
+ svgr({
+ icon: true,
+ replaceAttrValues: {
+ '#000': 'currentColor',
+ '#000000': 'currentColor',
+ },
+ }),
+ ],
+ external: [
+ 'react',
+ 'react-dom',
+ '@assistant-ui/react',
+ '@assistant-ui/core',
+ '@openuidev/react-headless',
+ '@openuidev/react-lang',
+ '@openuidev/react-ui',
+ '@openuidev/react-ui/genui-lib',
+ '@truefoundry/assistant-ui-runtime',
+ 'lucide-react',
+ 'react-markdown',
+ 'remark-gfm',
+ 'react-syntax-highlighter',
+ 'react-syntax-highlighter/dist/esm/styles/prism',
+ 'monaco-editor',
+ ],
+});
diff --git a/packages/trueforge-ui-sdk/vitest.config.ts b/packages/trueforge-ui-sdk/vitest.config.ts
new file mode 100644
index 000000000..e2b66ef79
--- /dev/null
+++ b/packages/trueforge-ui-sdk/vitest.config.ts
@@ -0,0 +1,30 @@
+/** Vitest: jsdom for React containers; MUI alias for CJS/ESM dual-package quirk. */
+import { fileURLToPath } from 'node:url';
+
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+ resolve: {
+ alias: {
+ '@': fileURLToPath(new URL('./src', import.meta.url)),
+ '@mui/material/styles/styled': '@mui/material/styles/styled.js',
+ },
+ },
+ test: {
+ environment: 'jsdom',
+ include: ['src/**/*.test.{ts,tsx}'],
+ globals: true,
+ setupFiles: ['./src/testSetup.ts'],
+ coverage: {
+ provider: 'v8',
+ include: ['src/**/*.{ts,tsx}'],
+ exclude: ['src/**/*.test.{ts,tsx}', 'src/testSetup.ts', 'src/svg.d.ts'],
+ thresholds: {
+ // Floor just under measured baseline (~70/67/56) so CI stays green.
+ lines: 65,
+ functions: 60,
+ branches: 50,
+ },
+ },
+ },
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 2329fcf4c..a1d68c871 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -7,6 +7,8 @@ settings:
overrides:
'@assistant-ui/store': 0.2.21
'@assistant-ui/core': 0.2.22
+ '@assistant-ui/tap': 0.9.5
+ zustand: ^5.0.14
resolve: 1.22.11
importers:
@@ -15,16 +17,16 @@ importers:
devDependencies:
'@eslint-react/eslint-plugin':
specifier: ^5.18.0
'@eslint/js':
specifier: ^10.0.1
eslint:
specifier: ^10.7.0
eslint-plugin-react-hooks:
specifier: ^7.1.1
husky:
specifier: ^9.1.7
version: 9.1.7
@@ -39,25 +41,25 @@ importers:
typescript-eslint:
specifier: ^8.65.0
packages/frontend:
dependencies:
'@assistant-ui/core':
specifier: 0.2.22
'@assistant-ui/react':
specifier: ^0.14.24
'@assistant-ui/store':
specifier: 0.2.21
- '@truefoundry/agent-ui-sdk':
- specifier: ^0.1.3
- version: 0.1.3(2258b7d3a6c75cf9484a74ef844b7ab2)
'@truefoundry/assistant-ui-runtime':
specifier: ^0.1.7
+ '@truefoundry/trueforge-ui':
+ specifier: workspace:*
+ version: link:../trueforge-ui-sdk
monaco-editor:
specifier: ^0.52.0
version: 0.52.2
@@ -79,7 +81,7 @@ importers:
version: 19.2.3(@types/[email protected])
'@vitejs/plugin-react':
specifier: ^4.7.0
playwright-core:
specifier: ^1.61.1
version: 1.61.1
@@ -94,7 +96,7 @@ importers:
version: 5.9.3
vite:
specifier: ^6.3.5
vite-plugin-compression2:
specifier: ^2.5.3
version: 2.5.3([email protected])
@@ -194,7 +196,7 @@ importers:
version: 5.12.1(@opentelemetry/[email protected])
tsup:
specifier: ^8.5.0
typescript:
specifier: ^7.0.2
version: 7.0.2
@@ -273,7 +275,7 @@ importers:
tsup:
specifier: ^8.5.0
tsx:
specifier: ^4.16.2
version: 4.23.1
@@ -281,8 +283,132 @@ importers:
specifier: ^7.0.2
version: 7.0.2
+ packages/trueforge-ui-sdk:
+ dependencies:
+ '@assistant-ui/core':
+ specifier: 0.2.22
+ '@assistant-ui/react':
+ specifier: ^0.14.24
+ '@openuidev/react-headless':
+ specifier: ^0.9.4
+ '@openuidev/react-lang':
+ specifier: ^0.2.9
+ '@openuidev/react-ui':
+ specifier: ^0.13.2
+ '@truefoundry/assistant-ui-runtime':
+ specifier: ^0.1.9
+ clsx:
+ specifier: ^2.1.1
+ version: 2.1.1
+ lucide-react:
+ specifier: ^0.562.0
+ version: 0.562.0([email protected])
+ monaco-editor:
+ specifier: ^0.56.0
+ version: 0.56.0
+ react-markdown:
+ specifier: ^10.1.0
+ react-syntax-highlighter:
+ specifier: ^16.1.1
+ version: 16.1.1([email protected])
+ remark-gfm:
+ specifier: ^4.0.1
+ version: 4.0.1([email protected])
+ tailwind-merge:
+ specifier: ^3.6.0
+ version: 3.6.0
+ truefoundry-gateway-sdk:
+ specifier: ^0.4.0-rc.6
+ version: 0.4.0
+ zod:
+ specifier: ^4.4.3
+ version: 4.4.3
+ devDependencies:
+ '@eslint/js':
+ specifier: ^9.39.0
+ version: 9.39.5
+ '@tailwindcss/cli':
+ specifier: ^4.3.2
+ version: 4.3.3
+ '@testing-library/dom':
+ specifier: ^10.0.0
+ version: 10.4.1
+ '@testing-library/jest-dom':
+ specifier: ^6.6.3
+ version: 6.10.0(@testing-library/[email protected])
+ '@testing-library/react':
+ specifier: ^16.3.2
+ '@types/node':
+ specifier: ^20
+ version: 20.19.43
+ '@types/react':
+ specifier: ^19.2.17
+ version: 19.2.17
+ '@types/react-dom':
+ specifier: ^19.2.0
+ version: 19.2.3(@types/[email protected])
+ '@types/react-syntax-highlighter':
+ specifier: ^15.5.13
+ version: 15.5.13
+ '@vitest/coverage-v8':
+ specifier: ^4.1.10
+ version: 4.1.10([email protected])
+ esbuild-plugin-svgr:
+ specifier: 3.1.1
+ eslint:
+ specifier: ^9.39.0
+ eslint-plugin-react-hooks:
+ specifier: ^7.0.0
+ github-markdown-css:
+ specifier: ^5.9.0
+ version: 5.9.0
+ globals:
+ specifier: ^16.4.0
+ version: 16.5.0
+ jsdom:
+ specifier: ^24.1.3
+ version: 24.1.3([email protected])
+ prettier:
+ specifier: ^3.6.2
+ version: 3.9.6
+ react:
+ specifier: ^19.2.4
+ version: 19.2.8
+ react-dom:
+ specifier: ^19.2.4
+ version: 19.2.8([email protected])
+ tailwindcss:
+ specifier: ^4.3.2
+ version: 4.3.3
+ tsup:
+ specifier: ^8.5.0
+ typescript:
+ specifier: ^5.9.3
+ version: 5.9.3
+ typescript-eslint:
+ specifier: ^8.46.0
+ vitest:
+ specifier: ^4.1.9
+
packages:
+ '@adobe/[email protected]':
+ resolution: {integrity: sha512-6OzddxPio9UiWTCemp4N8cYLV2ZN1ncRnV1cVGtve7dhPOtRkleRyx32GQCYSwDYgaHU3USMm84tNsvKzRCa1Q==}
+
resolution: {integrity: sha512-11UocR7fFdMWw503bWCX2IOK15vbWfxT11Mn9xOiPBVO/UVcn57ywGrlLL4UaBlPgmUTvuzr2yYR2ElSqiN2wQ==}
@@ -338,15 +464,18 @@ packages:
resolution: {integrity: sha512-9WAerTaPU2jcVi8dh8x27tySEuLur1Kfg7Go74GuCmsC/2MDSvrTkrK8ZrXWjryEevKfcPPmO1enveE7eqlzoA==}
engines: {node: '>=22'}
+ '@asamuzakjp/[email protected]':
+ resolution: {integrity: sha512-K1A6z8tS3XsmCMM86xoWdn7Fkdn9m6RSVtocUrJYIwZnFVkng/PvkEoWtOWmP+Scc6saYWHWZYbndEEXxl24jw==}
+
'@assistant-ui/[email protected]':
resolution: {integrity: sha512-6BzW6yFEMpojaS6Oj4VSLIb0hMaRh+chZzv4e08SuNmJ+ed+UTsPbVHlvJT/EY587AlNLB2DRSKW21+vrsfUzA==}
peerDependencies:
'@assistant-ui/store': 0.2.21
- '@assistant-ui/tap': ^0.9.0
+ '@assistant-ui/tap': 0.9.5
'@types/react': '*'
assistant-cloud: ^0.1.31
react: ^18 || ^19
- zustand: ^5.0.11
+ zustand: ^5.0.14
peerDependenciesMeta:
'@types/react':
optional: true
@@ -373,15 +502,15 @@ packages:
'@assistant-ui/[email protected]':
resolution: {integrity: sha512-on2xIqLRsMij1J9WXBjKHW2XeVckypicXo7z3Fam6C9DVThZvWIevwJl962uargqq8DKNQxMySQ6Z7Z83+I5nA==}
peerDependencies:
- '@assistant-ui/tap': ^0.9.0
+ '@assistant-ui/tap': 0.9.5
'@types/react': '*'
react: ^18 || ^19
peerDependenciesMeta:
'@types/react':
optional: true
- '@assistant-ui/[email protected]':
- resolution: {integrity: sha512-l44CfXvWrokaXQWBGsFGf574rlM9h5ii9mbcSJ8VoPV6KIpK5zlRqhkSxWWKuke4Q70tQygLaZm1BdiPwIP0bA==}
+ '@assistant-ui/[email protected]':
+ resolution: {integrity: sha512-xmj8pbZD3QX6VB1kSq1WGIhZOpaSUbD1HuAtYDJFN/oj/Oae9uEs7c5MeoGUrlB7rytxVXKovsqh9hxtNt4u2g==}
peerDependencies:
'@types/react': '*'
react: ^18 || ^19
@@ -653,10 +782,42 @@ packages:
resolution: {integrity: sha512-0hYQ8SB4Db5zvZB4axdMHGwEaQjkZzFjQiN9LVYvIFB2nSUHW9tYpxWriPrWDASIxiaXax83REcLxuSdnGPZtw==}
+ resolution: {integrity: sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==}
+ engines: {node: '>=18'}
+
'@colors/[email protected]':
resolution: {integrity: sha512-Ir+AOibqzrIsL6ajt3Rz3LskB7OiMVHqltZmspbW/TJuTVuyOMirVqAkjfY6JISiLHgyNqicAC8AyHHGzNd/dA==}
engines: {node: '>=0.1.90'}
+ '@csstools/[email protected]':
+ resolution: {integrity: sha512-S11EXWJyy0Mz5SYvRmY8nJYTFFd1LCNV+7cXyAgQtOOuzb4EsgfqDufL+9esx72/eLhsRdGZwaldu/h+E4t4BA==}
+ engines: {node: '>=18'}
+
+ '@csstools/[email protected]':
+ resolution: {integrity: sha512-3N8oaj+0juUw/1H3YwmDDJXCgTB1gKU6Hc/bB502u9zR0q2vd786XJH9QfrKIEgFlZmhZiq6epXl4rHqhzsIgQ==}
+ engines: {node: '>=18'}
+ peerDependencies:
+ '@csstools/css-parser-algorithms': ^3.0.5
+ '@csstools/css-tokenizer': ^3.0.4
+
+ '@csstools/[email protected]':
+ resolution: {integrity: sha512-nbtKwh3a6xNVIp/VRuXV64yTKnb1IjTAEEh3irzS+HkKjAOYLTGNb9pmVNntZ8iVBHcWDA2Dof0QtPgFI1BaTA==}
+ engines: {node: '>=18'}
+ peerDependencies:
+ '@csstools/css-parser-algorithms': ^3.0.5
+ '@csstools/css-tokenizer': ^3.0.4
+
+ '@csstools/[email protected]':
+ resolution: {integrity: sha512-DaDeUkXZKjdGhgYaHNJTV9pV7Y9B3b644jCLs9Upc3VeNGg6LWARAT6O+Q+/COo+2gg/bM5rhpMAtf70WqfBdQ==}
+ engines: {node: '>=18'}
+ peerDependencies:
+ '@csstools/css-tokenizer': ^3.0.4
+
+ '@csstools/[email protected]':
+ resolution: {integrity: sha512-Vd/9EVDiu6PPJt9yAh6roZP6El1xHrdvIVGjyBsHR0RYwNHgL7FJPyIIW4fANJNG6FtyZfvlRPpFI4ZM/lubvw==}
+ engines: {node: '>=18'}
+
resolution: {integrity: sha512-R4MSXTVnuMzGD7bzHdW2ZhhdPC/igELENcq5IjEverBvq5hn1SXCWcsi6eSsdWP0/Ur+SItRRjAktmdoX/8R/Q==}
@@ -1199,18 +1360,34 @@ packages:
eslint: '*'
typescript: '*'
+ '@eslint/[email protected]':
+ resolution: {integrity: sha512-nJl2KGTlrf9GjLimgIru+V/mzgSK0ABCDQRvxw5BjURL7WfH5uoWmizbH7QB6MmnMBd8cIC9uceWnezL1VZWWw==}
+ engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
'@eslint/[email protected]':
resolution: {integrity: sha512-Y3kKLvC1dvTOT+oGlqNQ1XLqK6D1HU2YXPc52NmAlJZbMMWDzGYXMiPRJ8TYD39muD/OTjlZmNJ4ib7dvSrMBA==}
engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+ '@eslint/[email protected]':
+ resolution: {integrity: sha512-gBrxN88gOIf3R7ja5K9slwNayVcZgK6SOUORm2uBzTeIEfeVaIhOpCtTox3P6R7o2jLFwLFTLnC7kU/RGcYEgw==}
+ engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
'@eslint/[email protected]':
resolution: {integrity: sha512-ii6Bw9jJ2zi2cWA2Z+9/QZ/+3DX6kwaV5Q986D/CdP3Lap3w/pgQZ373FV7byY/i7L4IRH/G43I5dz1ClsCbpA==}
engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+ '@eslint/[email protected]':
+ resolution: {integrity: sha512-yL/sLrpmtDaFEiUj1osRP4TI2MDz1AddJL+jZ7KSqvBuliN4xqYY54IfdN8qD8Toa6g1iloph1fxQNkjOxrrpQ==}
+ engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
'@eslint/[email protected]':
resolution: {integrity: sha512-MwcE1P+AZ4C6DWlpin/OmOA54mmIZ/+xZuJiQd4SyB29oAJjN30UW9wkKNptW2ctp4cEsvhlLY/CsQ1uoHDloQ==}
engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+ '@eslint/[email protected]':
+ resolution: {integrity: sha512-l2Ul9PrHsPCKcEY/ac7VgFj9D80C7S68sOKc618SyHDPK36s1XcFebXY0iTzUVn4Yq+YbwvSnDmCz9yxjX+QrA==}
+ engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
'@eslint/[email protected]':
resolution: {integrity: sha512-zeR9k5pd4gxjZ0abRoIaxdc7I3nDktoXZk2qOv9gCNWx3mVwEn32VRhyLaRsDiJjTs0xq/T8mfPtyuXu7GWBcA==}
engines: {node: ^20.19.0 || ^22.13.0 || >=24}
@@ -1220,10 +1397,22 @@ packages:
eslint:
optional: true
+ '@eslint/[email protected]':
+ resolution: {integrity: sha512-QywQuszQh77pIXCsq998c8hbhSTI/azTty1Z6N53dmAudKHhy573j3yvRLsX2BSp8YpLtoCEG8E9DJe+8zUh4A==}
+ engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+ '@eslint/[email protected]':
+ resolution: {integrity: sha512-VtAOaymWVfZcmZbp6E2mympDIHvyjXs/12LqWYjVw6qjrfF+VK+fyG33kChz3nnK+SU5/NeHOqrTEHS8sXO3OA==}
+ engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
'@eslint/[email protected]':
resolution: {integrity: sha512-vqTaUEgxzm+YDSdElad6PiRoX4t8VGDjCtt05zn4nU810UIx/uNEV7/lZJ6KwFThKZOzOxzXy48da+No7HZaMw==}
engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+ '@eslint/[email protected]':
+ resolution: {integrity: sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA==}
+ engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
'@eslint/[email protected]':
resolution: {integrity: sha512-+CNAzxglkrpNf/kKywqQfk74QjtceuOE7Qm+AF8miRvPF/wmmK5+OJOgVh3AVTT3RP2mH3+FOaxlE5v72owk0A==}
engines: {node: ^20.19.0 || ^22.13.0 || >=24}
@@ -1665,7 +1854,7 @@ packages:
resolution: {integrity: sha512-GCcvSJ8ZHY2yxyp2eCyYxP4zB4CmDvyVR/04DmXyGdIZJNTYJ/HAOU0xPI3wUYXO/3JT2UduPh0V4TM/GF7rCA==}
peerDependencies:
react: ^18.3.1 || ^19.0.0
- zustand: ^4.5.5
+ zustand: ^5.0.14
'@openuidev/[email protected]':
resolution: {integrity: sha512-pQd4goMYHBfq2Df1kq3MOh0QbZiBIhBkD3K/0UfTY86a/N7EC/ydo1xW1IjjOSU0qHycF5z5Yw/UGs2BDllGjA==}
@@ -1685,7 +1874,95 @@ packages:
react: ^18.3.1 || ^19.0.0
react-dom: ^18.0.0 || ^19.0.0
zod: ^3.25.0 || ^4.0.0
- zustand: ^4.5.5
+ zustand: ^5.0.14
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-KF8+j9nNbUN8vzOFDpRMsaKBHZ/mcjEjMToVMJOhTozkDonQFFrRcfdLWn6yWKCmJKmdVxSgHiYvTCef4/qcBA==}
+ engines: {node: '>= 10.0.0'}
+ cpu: [arm64]
+ os: [android]
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-eAzPv5osDmZyBhou8PoF4i6RQXAfeKL9tjb3QzYuccXFMQU0ruIc/POh30ePnaOyD1UXdlKguHBmsTs53tVoPw==}
+ engines: {node: '>= 10.0.0'}
+ cpu: [arm64]
+ os: [darwin]
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-1ZXDthrnNmwv10A0/3AJNZ9JGlzrF82i3gNQcWOzd7nJ8aj+ILyW1MTxVk35Db0u91oD5Nlk9MBiujMlwmeXZg==}
+ engines: {node: '>= 10.0.0'}
+ cpu: [x64]
+ os: [darwin]
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-SI4eljM7Flp9yPuKi8W0ird8TI/JK6CSxju3NojVI6BjHsTyK7zxA9urjVjEKJ5MBYC+bLmMcbAWlZ+rFkLpJQ==}
+ engines: {node: '>= 10.0.0'}
+ cpu: [x64]
+ os: [freebsd]
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-RCdZlEyTs8geyBkkcnPWvtXLY44BCeZKmGYRtSgtwwnHR4dxfHRG3gR99XdMEdQ7KeiDdasJwwvNSF5jKtDwdA==}
+ engines: {node: '>= 10.0.0'}
+ cpu: [arm]
+ os: [linux]
+ libc: [glibc]
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-6E+m/Mm1t1yhB8X412stiKFG3XykmgdIOqhjWj+VL8oHkKABfu/gjFj8DvLrYVHSBNC+/u5PeNrujiSQ1zwd1Q==}
+ engines: {node: '>= 10.0.0'}
+ cpu: [arm]
+ os: [linux]
+ libc: [musl]
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-LrGp+f02yU3BN9A+DGuY3v3bmnFUggAITBGriZHUREfNEzZh/GO06FF5u2kx8x+GBEUYfyTGamol4j3m9ANe8w==}
+ engines: {node: '>= 10.0.0'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [glibc]
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-cFOjABi92pMYRXS7AcQv9/M1YuKRw8SZniCDw0ssQb/noPkRzA+HBDkwmyOJYp5wXcsTrhxO0zq1U11cK9jsFg==}
+ engines: {node: '>= 10.0.0'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [musl]
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-GcESn8NZySmfwlTsIur+49yDqSny2IhPeZfXunQi48DMugKeZ7uy1FX83pO0X22sHntJ4Ub+9k34XQCX+oHt2A==}
+ engines: {node: '>= 10.0.0'}
+ cpu: [x64]
+ os: [linux]
+ libc: [glibc]
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-n0E2EQbatQ3bXhcH2D1XIAANAcTZkQICBPVaxMeaCVBtOpBZpWJuf7LwyWPSBDITb7In8mqQgJ7gH8CILCURXg==}
+ engines: {node: '>= 10.0.0'}
+ cpu: [x64]
+ os: [linux]
+ libc: [musl]
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-RFzklRvmc3PkjKjry3hLF9wD7ppR4AKcWNzH7kXR7GUe0Igb3Nz8fyPwtZCSquGrhU5HhUNDr/mKBqj7tqA2Vw==}
+ engines: {node: '>= 10.0.0'}
+ cpu: [arm64]
+ os: [win32]
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-c2KkcVN+NJmuA7CGlaGD1qJh1cLfDnQsHjE89E60vUEMlqduHGCdCLJCID5geFVM0dOtA3ZiIO8BoEQmzQVfpQ==}
+ engines: {node: '>= 10.0.0'}
+ cpu: [ia32]
+ os: [win32]
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-9lHBdJITeNR++EvSQVUcaZoWupyHfXe1jZvGZ06O/5MflPcuPLtEphScIBL+AiCWBO46tDSHzWyD0uDmmZqsgA==}
+ engines: {node: '>= 10.0.0'}
+ cpu: [x64]
+ os: [win32]
+
+ '@parcel/[email protected]':
+ resolution: {integrity: sha512-dfUnCxiN9H4ap84DvD2ubjw+3vUNpstxa0TneY/Paat8a3R4uQZDLSvWjmznAY/DoahqTHl9V46HF/Zs3F29pg==}
+ engines: {node: '>= 10.0.0'}
'@protobufjs/[email protected]':
resolution: {integrity: sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==}
@@ -2639,6 +2916,74 @@ packages:
'@standard-schema/[email protected]':
resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
+ resolution: {integrity: sha512-b9MIk7yhdS1pMCZM8VeNfUlSKVRhsHZNMl5O9SfaX0l0t5wjdgu4IDzGB8bpnGBBOjGST3rRFVsaaEtI4W6f7g==}
+ engines: {node: '>=14'}
+ peerDependencies:
+ '@babel/core': ^7.0.0-0
+
+ resolution: {integrity: sha512-BcCkm/STipKvbCl6b7QFrMh/vx00vIP63k2eM66MfHJzPr6O2U0jYEViXkHJWqXqQYjdeA9cuCl5KWmlwjDvbA==}
+ engines: {node: '>=14'}
+ peerDependencies:
+ '@babel/core': ^7.0.0-0
+
+ resolution: {integrity: sha512-5BcGCBfBxB5+XSDSWnhTThfI9jcO5f0Ai2V24gZpG+wXF14BzwxxdDb4g6trdOux0rhibGs385BeFMSmxtS3uA==}
+ engines: {node: '>=14'}
+ peerDependencies:
+ '@babel/core': ^7.0.0-0
+
+ resolution: {integrity: sha512-KVQ+PtIjb1BuYT3ht8M5KbzWBhdAjjUPdlMtpuw/VjT8coTrItWX6Qafl9+ji831JaJcu6PJNKCV0bp01lBNzQ==}
+ engines: {node: '>=14'}
+ peerDependencies:
+ '@babel/core': ^7.0.0-0
+
+ resolution: {integrity: sha512-omNiKqwjNmOQJ2v6ge4SErBbkooV2aAWwaPFs2vUY7p7GhVkzRkJ00kILXQvRhA6miHnNpXv7MRnnSjdRjK8og==}
+ engines: {node: '>=14'}
+ peerDependencies:
+ '@babel/core': ^7.0.0-0
+
+ resolution: {integrity: sha512-mURHYnu6Iw3UBTbhGwE/vsngtCIbHE43xCRK7kCw4t01xyGqb2Pd+WXekRRoFOBIY29ZoOhUCTEweDMdrjfi9g==}
+ engines: {node: '>=14'}
+ peerDependencies:
+ '@babel/core': ^7.0.0-0
+
+ resolution: {integrity: sha512-Tx8T58CHo+7nwJ+EhUwx3LfdNSG9R2OKfaIXXs5soiy5HtgoAEkDay9LIimLOcG8dJQH1wPZp/cnAv6S9CrR1Q==}
+ engines: {node: '>=14'}
+ peerDependencies:
+ '@babel/core': ^7.0.0-0
+
+ resolution: {integrity: sha512-DFx8xa3cZXTdb/k3kfPeaixecQLgKh5NVBMwD0AQxOzcZawK4oo1Jh9LbrcACUivsCA7TLG8eeWgrDXjTMhRmw==}
+ engines: {node: '>=12'}
+ peerDependencies:
+ '@babel/core': ^7.0.0-0
+
+ resolution: {integrity: sha512-7EYDbHE7MxHpv4sxvnVPngw5fuR6pw79SkcrILHJ/iMpuKySNCl5W1qcwPEpU+LgyRXOaAFgH0KhwD18wwg6ug==}
+ engines: {node: '>=14'}
+ peerDependencies:
+ '@babel/core': ^7.0.0-0
+
+ resolution: {integrity: sha512-8QqtOQT5ACVlmsvKOJNEaWmRPmcojMOzCz4Hs2BGG/toAp/K38LcsMRyLp349glq5AzJbCEeimEoxaX6v/fLrA==}
+ engines: {node: '>=14'}
+
+ resolution: {integrity: sha512-EbDKwO9GpfWP4jN9sGdYwPBU0kdomaPIL2Eu4YwmgP+sJeXT+L7bMwJUBnhzfH8Q2qMBqZ4fJwpCyYsAN3mt2Q==}
+ engines: {node: '>=14'}
+
+ resolution: {integrity: sha512-0xiIyBsLlr8quN+WyuxooNW9RJ0Dpr8uOnH/xrCVO8GLUcwHISwj1AG0k+LFzteTkAA0GbX0kj9q6Dk70PTiPA==}
+ engines: {node: '>=14'}
+ peerDependencies:
+ '@svgr/core': '*'
+
resolution: {integrity: sha512-IsISIT22EfktVJrlvIpnAxG2u/A9aob9l99HMlx80x72WlFmFPk1V3UhkEzx86eJP8hw049KTFv/RISho2cq2Q==}
engines: {node: '>=10'}
@@ -2742,21 +3087,124 @@ packages:
resolution: {integrity: sha512-r5bClKrcIusDoo049dSL8CawnHR6mRdDwhlQuIgZRNty68q0x8k3Lf1BtPAMxRf/GgnHBnIO4ujd3+GQdLWzxQ==}
engines: {node: '>=16.0.0'}
- '@truefoundry/[email protected]':
- resolution: {integrity: sha512-IDeWJhf3tRS1O28dNr8SFGpdF/g3drumc4YHR2nUl2dewnMoxJmoI5nAuQJ9Nr0bXnjeWEvZtEyY5Lf2sq373Q==}
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-ZvS/n1ZHOBKcVlhkt8l5NNr1EDXk1NboYO5CYDOs6NUmvT9z6bzkwsosaJftY57T/3gWNzWMJzIXLodZC8ssdw==}
+ hasBin: true
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-/T8IKEsf9VTU6tLjgC7+sv2mOPtQxzE2jMw7u4Tt40Tx+QSZxpzh95/H6cMKoja9XuW7iMdLJYBB0o9G1CaAgg==}
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-Y85A2gmPSkl5Ve5qR86GL4HT509cFqQh1aes9p3sSkyTPwt0Pppf3GkwGe4JPACcRYjgJIEhQgM6dBClnr0NYw==}
+ engines: {node: '>= 20'}
+ cpu: [arm64]
+ os: [android]
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-BiaWatpBcERQFDlOjRDpIVXuFK5PJez5SA4JMg6VYZdBYU+qKfV/vqjcIs+IYmtitf1xYQZTwXvU/8y4lfZUGw==}
+ engines: {node: '>= 20'}
+ cpu: [arm64]
+ os: [darwin]
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-fAeUqfV5ndhxRwai8cXGzdLvul9utWOmeTkv69unv4ZXixjn61Z+p9lCWdwOwA3TYboG3BwdVuN/RDjhBRl0mw==}
+ engines: {node: '>= 20'}
+ cpu: [x64]
+ os: [darwin]
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-iyf5bV6+wnAlflVeEy7R25dupxTNECZN5QMI0qNT6eT+EgaGdZcKhGkr5SdoaWiLJ3spLqIY9VCeSGrwmtg4kw==}
+ engines: {node: '>= 20'}
+ cpu: [x64]
+ os: [freebsd]
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-aAYUprJAJQWWbRrPvtjdroZ56Md+JM8pMiopS6xGEwDfLhqj+2ver2p4nU4Mb3CRqcMmNBjo8KkUgcxhkzVQGQ==}
+ engines: {node: '>= 20'}
+ cpu: [arm]
+ os: [linux]
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-nDxldcEENOxZRzC2uu9jrutZdAAQtb+8WWDCSnWL1zvBk1+FN+x6MtDViPB5AJMfttVCUhehGWus3XBPgatM/w==}
+ engines: {node: '>= 20'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [glibc]
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-Md44bD6veX/PC5iyF8cDVnw4HBIANZepRZZ7a8DQOvkfo5WUBwcp6iAuCUz23u+4SUkhJlD3eL7hNdW8ezd/kA==}
+ engines: {node: '>= 20'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [musl]
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-tx7us1muwOKAKWao2v/GaafFeQboE6aj88vC6ziN2NCGcRm8gWUhwjzg+YdVB1e4boAtdtma4L43onunI6NS4w==}
+ engines: {node: '>= 20'}
+ cpu: [x64]
+ os: [linux]
+ libc: [glibc]
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-SJxX60smvHgasZoBy11dX6YRjXJFovwWBoedhbQPOBzgFWBHGB+TVPWB9BxzR7TTxU8FQZAI2AyiNCMzFm8Img==}
+ engines: {node: '>= 20'}
+ cpu: [x64]
+ os: [linux]
+ libc: [musl]
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-jx1+rPhY/5Ympkktd656HBWEBLxP7dH06losBLjjf5vgCODXvi9KhtftWcMIwTFIDqBr7cRnQkdLnAG+IOlGvQ==}
+ engines: {node: '>=14.0.0'}
+ cpu: [wasm32]
+ bundledDependencies:
+ - '@napi-rs/wasm-runtime'
+ - '@emnapi/core'
+ - '@emnapi/runtime'
+ - '@tybys/wasm-util'
+ - '@emnapi/wasi-threads'
+ - tslib
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-3rc292Ca2ceK6Ulcc/bAVnTs/3nDtoPhyEKlgPv+yQJQi/JS/AMJlqzxvlDacL1nekbrcf6bTqp/jV4qgnPxNQ==}
+ engines: {node: '>= 20'}
+ cpu: [arm64]
+ os: [win32]
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-yJ0pwIVc/nYeGoV02WtsN8KYyLQv7kyI2wDnkezyJlGGjkd4QLwDGAwl47YpPJeuI0M0ObaXGSPjvWDPeTPggw==}
+ engines: {node: '>= 20'}
+ cpu: [x64]
+ os: [win32]
+
+ '@tailwindcss/[email protected]':
+ resolution: {integrity: sha512-krXjAikiaFSPaK/FkAQT5UTx3VormQaiZ5hBFlJZ9UFQGB/rwg1MZIhHAG9smMQRTdyJxP6Qt5MwMtdyU5FWrA==}
+ engines: {node: '>= 20'}
+
+ '@testing-library/[email protected]':
+ resolution: {integrity: sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==}
+ engines: {node: '>=18'}
+
+ '@testing-library/[email protected]':
+ resolution: {integrity: sha512-HQwu0KaB2zyT0iLzBL+8CLyZDL3KlZlZJ+2iyc9uCUnlJVskJU/UlPuVCyIPhtukjPQdT2QNoR5nCP5FqTmmDQ==}
+ engines: {node: '>=22', npm: '>=6', yarn: '>=1'}
+ deprecated: Incorrect minor release with breaking changes (Node >=22 and required @testing-library/dom peer). Use 6.9.1 for the 6.x line, or upgrade to 7.0.0.
peerDependencies:
- '@assistant-ui/core': 0.2.22
- '@assistant-ui/react': ^0.14.24
- '@types/react': '*'
- react: ^18 || ^19
- react-dom: ^18 || ^19
+ '@testing-library/dom': '>=10 <11'
+
+ '@testing-library/[email protected]':
+ resolution: {integrity: sha512-XU5/SytQM+ykqMnAnvB2umaJNIOsLF3PVv//1Ew4CTcpz0/BRyy/af40qqrt7SjKpDdT1saBMc42CUok5gaw+g==}
+ engines: {node: '>=18'}
+ peerDependencies:
+ '@testing-library/dom': ^10.0.0
+ '@types/react': ^18.0.0 || ^19.0.0
+ '@types/react-dom': ^18.0.0 || ^19.0.0
+ react: ^18.0.0 || ^19.0.0
+ react-dom: ^18.0.0 || ^19.0.0
peerDependenciesMeta:
- '@assistant-ui/core':
- optional: true
- '@assistant-ui/react':
- optional: true
'@types/react':
optional: true
+ '@types/react-dom':
+ optional: true
'@truefoundry/[email protected]':
resolution: {integrity: sha512-Gy0QWdsbTwPV3SkLPI2OXUh9RqxgBOmK7Hv8/+WnjReHZw0KtwvAHAKSvzf/O1Fgyw3Sr5WzQjkPWKP7HmcPwQ==}
@@ -2770,6 +3218,21 @@ packages:
truefoundry-gateway-sdk:
optional: true
+ '@truefoundry/[email protected]':
+ resolution: {integrity: sha512-2LjsIHbWOtJI+oSF28SvgcJ8WpUUr74/LYJ84UyKfOLnFutgJZPAwFp9a3uYmIdwVahnwk9pF6FD3zFyVVDB/Q==}
+ peerDependencies:
+ '@types/react': '*'
+ react: ^18 || ^19
+ truefoundry-gateway-sdk: ^0.4.0-rc.6
+ peerDependenciesMeta:
+ '@types/react':
+ optional: true
+ truefoundry-gateway-sdk:
+ optional: true
+
+ '@types/[email protected]':
+ resolution: {integrity: sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==}
+
resolution: {integrity: sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==}
@@ -2785,6 +3248,9 @@ packages:
resolution: {integrity: sha512-NMv9ASNARoKksWtsq/SHakpYAYnhBrQgGD8zkLYk/jaK8jUGn08CfEdTRgYhMypUQAfzSP8W6gNLe0q19/t4VA==}
+ '@types/[email protected]':
+ resolution: {integrity: sha512-Mw558oeA9fFbv65/y4mHtXDs9bPnFMZAL/jxdPFUpOHHIXX91mcgEHbS5Lahr+pwZFR8A7GQleRWeI6cGFC2UA==}
+
resolution: {integrity: sha512-hOLWVbm7uRza0BYXpIIW5pxfrKe0W+D5lrFiAEYR+pb6w3N2SwSMaJbXdUfSEv+dT4MfHBLtn5js0LAWaO6otw==}
@@ -2815,6 +3281,9 @@ packages:
resolution: {integrity: sha512-KSVgmQmzMwPlmtljOomayoR89W4FynCAi3E8PPs7vmDVPe84hT+vGPKkJfThkmXs0x0jAaa9U8uW8bbfyS2fWw==}
+ '@types/[email protected]':
+ resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
+
resolution: {integrity: sha512-xJBAbDifo5hpffDBuHl0Y8ywswbiAp/Wi7Y/GtAgSlZyIABppyurxVueOPE8LUQOxdlgi6Zqce7uoEpqNTeiUw==}
@@ -2854,6 +3323,9 @@ packages:
resolution: {integrity: sha512-GsCCIZDE/p3i96vtEqx+7dBUGXrc7zeSK3wwPHIaRThS+9OhWIXRqzs4d6k1SVU8g91DrNRWxWUGhp5KXQb2VA==}
+ '@types/[email protected]':
+ resolution: {integrity: sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==}
+
resolution: {integrity: sha512-Dh8vAsV36ig5wa9OX4pXvMc9D3Veibfw2wix0CUwYODLD8nkj9UsLjASr49nPg+2eKzxhBV+v7L8pXvT4e639Q==}
@@ -2871,6 +3343,9 @@ packages:
peerDependencies:
'@types/react': ^19.2.0
+ '@types/[email protected]':
+ resolution: {integrity: sha512-uLGJ87j6Sz8UaBAooU0T6lWJ0dBmjZgN1PZTrj05TNql2/XpC6+4HhMT5syIdFUUt+FASfCeLLv4kBygNU+8qA==}
+
resolution: {integrity: sha512-MXfmqaVPEVgkBT/aY0aGCkRWWtByiYQXo3xdQ8r5RzuFrPiRn8Gar2tQdXSUQ2GKV3bkXckek89V8wQBY2Q/Aw==}
@@ -3090,15 +3565,53 @@ packages:
peerDependencies:
vite: ^4.2.0 || ^5.0.0 || ^6.0.0 || ^7.0.0
- '@workflow/[email protected]':
- resolution: {integrity: sha512-pav4F2BoirECWR7Nf1TKt+2eETcBj7jj4cBefQ8VXQCA6NPkaKeLfj/zMgi+3zYV5ZIBT4GuUiphsj0/b9hPQQ==}
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-IM49HmthevbgAO4anp1hwtoT9wYe59w0LR00gr+eagHE+ZJ5lK4sLPeO0ubgoJcwLk6dehU3R24N+FbEEKDc8g==}
+ peerDependencies:
+ '@vitest/browser': 4.1.10
+ vitest: 4.1.10
+ peerDependenciesMeta:
+ '@vitest/browser':
+ optional: true
- resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
- engines: {node: '>= 0.6'}
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-YsCn+qAk1GWjQOWFEsEcL2gNQ0zmVmQu3T03qP6UyjhtmdtwtbuI+DASn/7iQB3HGTXkdBwGddzxPlmiql5vlA==}
- resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-v0xaezt+DKEmKfaxg133ldzADrwLGd7Ze1MfQQTYfvs8OqZIwbxyxaYURivwV7sWy5fqn3rH5uOrSp07bp44Ow==}
+ peerDependencies:
+ msw: ^2.4.9
+ vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+ peerDependenciesMeta:
+ msw:
+ optional: true
+ vite:
+ optional: true
+
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-W1HsjSH4MXQ9YfmmhLAoIYf1HRfekQCGngeIgcei6MP5QQGWUe0gkopdZQaVCFO+JDJMrAJGwa5pRpNpvy4P8Q==}
+
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-IKI6kpIH+LmpROplyLwBBaCfMgOZOMsygVa6BARD6ahA04VRuJSa6OaVG7kRvSEMD870Vd91rSSw0eegtWyLGg==}
+
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-xRkfOT1qpTAi/Ti4Y1LtfRc3kEuqxGw59eN2jN9pRWMtS/XDevekhcFSqvQqjUNGksfjMJu3Y+oJ+4Ypn2OaJw==}
+
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-PLf/Ugvoq5wO/b4rwYCR1h2PSIdXz7wnkQFMiUpLdtM7l6pqVFcQIBEHyT1+l+cj7mNwAfZHzqXqDyjvOuwbDw==}
+
+ '@vitest/[email protected]':
+ resolution: {integrity: sha512-fy9am/HWxbaGt/Sawrp90vt6Y6jQwf1RX77cz3uwoJwJVMli/e1IEwRPnMNJ7vKfPTwo0diXifkpPvwH9v7nGA==}
+
+ '@workflow/[email protected]':
+ resolution: {integrity: sha512-pav4F2BoirECWR7Nf1TKt+2eETcBj7jj4cBefQ8VXQCA6NPkaKeLfj/zMgi+3zYV5ZIBT4GuUiphsj0/b9hPQQ==}
+
+ resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
+ engines: {node: '>= 0.6'}
+
+ resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
peerDependencies:
acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
@@ -3111,6 +3624,10 @@ packages:
resolution: {integrity: sha512-RZNwNclF7+MS/8bDg70amg32dyeZGZxiDuQmZxKLAlQjr3jGyLx+4Kkk58UO7D2QdgFIQCovuSuZESne6RG6XQ==}
engines: {node: '>= 6.0.0'}
+ resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
+ engines: {node: '>= 14'}
+
resolution: {integrity: sha512-yyxSDZmlpTZs2oepyjzHMXrPk0mJ2ITpw8TfXYiF53yo0WkQJ1qm6MbpUiYclh640D35nNJ8bq57RffSrX+Qzg==}
engines: {node: '>=22'}
@@ -3169,10 +3686,24 @@ packages:
resolution: {integrity: sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==}
+ resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
+
resolution: {integrity: sha512-ik3ZgC9dY/lYVVM++OISsaYDeg1tb0VtP5uL3ouh1koGOaUMDPpbFIei4JkFimWUFPn90sbMNMXQAIVOlnYKJA==}
engines: {node: '>=10'}
+ resolution: {integrity: sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==}
+
+ resolution: {integrity: sha512-COROpnaoap1E2F000S62r6A60uHZnmlvomhfyT2DlTcrY1OrBKn2UhH7qn5wTC9zMvD0AY7csdPSNwKP+7WiQw==}
+ engines: {node: '>= 0.4'}
+
+ resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
+ engines: {node: '>=12'}
+
resolution: {integrity: sha512-SiMvAXalCwM9GcnyIiJfQTZda00E2VE/jZWqSdX4WPxQyHeVNK7uBzw3AaFpBQT1vXbS1UYdKVlZdUJ3vRftCg==}
@@ -3198,6 +3729,9 @@ packages:
redis:
optional: true
+ resolution: {integrity: sha512-UPAgKJFSEGMWSDr3LX4tqnAb4f7KGT8O40Tyx8wbYmmZ/yn58lNCm8h3svs3eXgiGd5AXxz8NDOvXWvicq+rJA==}
+
resolution: {integrity: sha512-htCUDlxyyCLMgaM3xXg0C0LW2xqfuQ6p05pCEIsXuyQ+a1koYKTuBMzRNwmybfLgvJDMd0r1LTn4+E0Ti6C2AA==}
@@ -3337,6 +3871,10 @@ packages:
resolution: {integrity: sha512-eyrF0jiFpY+3drT6383f1qhkbGsLSifNAjA61IUjZjmLCWjItY6LB9ft9YhoDgwfmclB2zhu51Lc7+95b8NRAg==}
+ resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
+ engines: {node: '>=18'}
+
resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
engines: {node: '>=10'}
@@ -3491,6 +4029,15 @@ packages:
resolution: {integrity: sha512-AdmX6xUzdNASswsFtmwSt7Vj8po9IuqXm0UXz7QKPuEUmPB4XyjGfaAr2PSuELMwkRMVH1EpIkX5bTZGRB3eCA==}
engines: {node: '>=10'}
+ resolution: {integrity: sha512-kcZ6+W5QzcJ3P1Mt+83OUv/oHFqZHIx8DuxG6eZ5RGMERoLqp4BuGjhHLYGK+Kf5XVkQvqBSmAy/nGWN3qDgEA==}
+ engines: {node: '>=14'}
+ peerDependencies:
+ typescript: '>=4.9.5'
+ peerDependenciesMeta:
+ typescript:
+ optional: true
+
resolution: {integrity: sha512-Adz2bdH0Vq3F53KEMJOoftQFutWCukm6J24wbPWRO4k1kMY7gS7ds/uoJkNuV8wDCtWWnuwGcJwpWcih+zEW1Q==}
engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0}
@@ -3500,6 +4047,13 @@ packages:
resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
engines: {node: '>= 8'}
+ resolution: {integrity: sha512-YUifsXXuknHlUsmlgyY0PKzgPOr7/FjCePfHNt0jxm83wHZi44VDMQ7/fGNkjY3/jV1MC+1CmZbaHzugyeRtpg==}
+
+ resolution: {integrity: sha512-2z+rWdzbbSZv6/rhtvzvqeZQHrBaqgogqt85sqFNbabZOuFbCVFb8kPeEtZjiKkbrm395irpNKiYeFeLiQnFPg==}
+ engines: {node: '>=18'}
+
resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
@@ -3547,6 +4101,10 @@ packages:
resolution: {integrity: sha512-ndfJ/JxxMd3nw31uyKoY2naivF+r29V+Lc0svZxe1JvvIRmi8hUsrMvdOwgS1o6uBHmiz91geQ0ylPP0aj1VUA==}
engines: {node: '>=12'}
+ resolution: {integrity: sha512-ZYP5VBHshaDAiVZxjbRVcFJpc+4xGgT0bK3vzy1HLN8jTO975HEbuYzZJcHoQEY5K1a0z8YayJkyVETa08eNTg==}
+ engines: {node: '>=18'}
+
resolution: {integrity: sha512-hTIP/z+t+qKwBDcmmsnmjWTduxCg+5KfdqWQvb2X/8C9+knYY6epN/pfxdDuyVlSVeFz0sM5eEfwIUQ70U4ckg==}
@@ -3565,6 +4123,9 @@ packages:
resolution: {integrity: sha512-qIMFpTMZmny+MMIitAB6D7iVPEorVw6YQRWkvarTkT4tBeSLLiHzcwj6q0MmYSFCiVpiqPJTJEYIrpcPzVEIvg==}
+ resolution: {integrity: sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==}
+
resolution: {integrity: sha512-GtpQYB283KrPp6nRw50q3U9/VfOutZOe103qlN7BPP6Ad27xYnOIWv4lPzo8HCAL+mMZofJ9KEy30fq6MfaK6Q==}
@@ -3595,6 +4156,15 @@ packages:
resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==}
engines: {node: '>=6'}
+ resolution: {integrity: sha512-pGjwhsmsp4kL2RTz08wcOlGN83otlqHeD/Z5T8GXZB+/YcpQ/dgo+lbU8ZsGxV0HIvqqxo9l7mqYwyYMD9bKDg==}
+ engines: {node: '>=0.10'}
+ hasBin: true
+
+ resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+ engines: {node: '>=8'}
+
resolution: {integrity: sha512-TLz+x/vEXm/Y7P7wn1EJFNLxYpUD4TgMosxY6fAVJUnJMbupHBOncxyWUG9OpTaH9EBD7uFI5LfEgmMOc54DsA==}
engines: {node: '>=8'}
@@ -3609,12 +4179,21 @@ packages:
resolution: {integrity: sha512-EjePK1srD3P08o2j4f0ExnylqRs5B9tJjcp9t1krH2qRi8CCdsYfwe9JgSLurFBWwq4uOlipzfk5fHNvwFKr8Q==}
engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0}
+ resolution: {integrity: sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==}
+
+ resolution: {integrity: sha512-7ZgogeTnjuHbo+ct10G9Ffp0mif17idi0IyWNVA/wcwcm7NPOD/WEHVP3n7n3MhXqxoIYm8d6MuZohYWIZ4T3w==}
+
resolution: {integrity: sha512-nRCa7CK3VTrM2NmGkIy4cbK7IZlgBE/PYMn55rrXefr5xXDP0LdtfPnblFDoVdcAfslJ7or6iqAUnx0CCGIWQA==}
resolution: {integrity: sha512-yb1cEmaOum7wFvOCSQxyfgVlv5D47Rc30iZWoMpbDIWTnJ6grDDQyu2KFJzB2k7u0pMuJcQ1zphH//fFnw2tjQ==}
+ resolution: {integrity: sha512-Kv5nKlh6yRrdrGvxeJ2e5y2eRUpkUosIW4A2AS38zwSz27zu7ufDwQPi5Jhs3XAlGNetl3bmnGhQsMtkKJnj3w==}
+
resolution: {integrity: sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==}
engines: {node: '>=12'}
@@ -3652,6 +4231,14 @@ packages:
resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==}
engines: {node: '>= 0.8'}
+ resolution: {integrity: sha512-L1l8TNvomm6UVW5B253AGxQagSQr+vGwhMlrrfRS2qmhx46AMpMVJKQYLvWYbysTMY8VoicOvzHzoHMbyzB+4A==}
+ engines: {node: '>=10.13.0'}
+
+ resolution: {integrity: sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==}
+ engines: {node: '>=0.12'}
+
resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==}
engines: {node: '>=0.12'}
@@ -3690,6 +4277,11 @@ packages:
resolution: {integrity: sha512-lNjylaAsJMprYg28zjUyBivP3y0ms9b7RJZ5tdhDUFLa3sCbqZw4wDnbFUSmnyZYWhCYDPxxp7KkXM2TXGw3PQ==}
engines: {node: '>=v14.0.0', npm: '>=7.0.0'}
+ resolution: {integrity: sha512-P0GVOTvmCMFUktRuIyjrUkx5C1VDZZH7VOFvtboQpWUG93eAvYyXPFf90kUMW9HMaTsRGpRrRoUmJ29PlQ0kLw==}
+ peerDependencies:
+ esbuild: ^0.25.2
+
resolution: {integrity: sha512-bbPBYYrtZbkt6Os6FiTLCTFxvq4tt3JKall1vRwshA3fdVztsLAatFaZobhkBC8/BrPetoa0oksYoKXoG4ryJg==}
engines: {node: '>=18'}
@@ -3772,6 +4364,10 @@ packages:
eslint: '*'
typescript: '*'
+ resolution: {integrity: sha512-sNXOfKCn74rt8RICKMvJS7XKV/Xk9kA7DyJr8mJik3S7Cwgy3qlkkmyS2uQB3jiJg6VNdZd/pDBJu0nvG2NlTg==}
+ engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
resolution: {integrity: sha512-xS90H51cKw0jltxmvmHy2Iai1LIqrfbw57b79w/J7MfvDfkIkFZ+kj6zC3BjtUwh150HsSSdxXZcsuv72miDFQ==}
engines: {node: ^20.19.0 || ^22.13.0 || >=24}
@@ -3780,6 +4376,10 @@ packages:
resolution: {integrity: sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag==}
engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
+ resolution: {integrity: sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==}
+ engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
resolution: {integrity: sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==}
engines: {node: ^20.19.0 || ^22.13.0 || >=24}
@@ -3794,6 +4394,20 @@ packages:
jiti:
optional: true
+ resolution: {integrity: sha512-DgZS62aPLXKlnxILS/AYCoRvHaZeXceIzlXPkkGGzJWSow1aEk0lbTlxUSlyjC8jcaKxAdOnTDz+o1JFSBsyjw==}
+ engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+ hasBin: true
+ peerDependencies:
+ jiti: '*'
+ peerDependenciesMeta:
+ jiti:
+ optional: true
+
+ resolution: {integrity: sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ==}
+ engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
resolution: {integrity: sha512-7p3DrVEIopW1B1avAGLuCSh1jubc01H2JHc8B4qqGblmg5gI9yumBgACjWo4JlIc04ufug4xJ3SQI8HkS/Rgzw==}
engines: {node: ^20.19.0 || ^22.13.0 || >=24}
@@ -3821,6 +4435,9 @@ packages:
resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==}
+ resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
+
resolution: {integrity: sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==}
engines: {node: '>=0.10.0'}
@@ -3859,6 +4476,10 @@ packages:
resolution: {integrity: sha512-A5EmesHW6rfnZ9ysHQjPdJRni0SRar0tjtG5MNtm9n5TUvsYU8oozprtRD4AqHxcZWWlVuAmQo2nWKfN9oyjTw==}
engines: {node: '>=0.10.0'}
+ resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==}
+ engines: {node: '>=12.0.0'}
+
resolution: {integrity: sha512-2Zks0hf1VLFYI1kbh0I5jP3KHHyCHpkfyHBzsSXRFgl/Bg9mWYfMW8oD+PdMPlEwy5HNsR9JutYy6pMeOh61nw==}
engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0}
@@ -4021,6 +4642,10 @@ packages:
resolution: {integrity: sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==}
engines: {node: '>=10'}
+ resolution: {integrity: sha512-tmT5sY+zvg2302XLYEfH2mtkViIM1SWf2nvYoF5N1ZsO0V6B2qZTiw3GOzw4vpjLygK/KG35qRlPFweHqfzz5w==}
+ engines: {node: '>=10'}
+
resolution: {integrity: sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==}
engines: {node: '>= 6'}
@@ -4033,6 +4658,14 @@ packages:
resolution: {integrity: sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==}
deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting [email protected]
+ resolution: {integrity: sha512-oahGvuMGQlPw/ivIYBjVSrWAfWLBeku5tpPE2fOPLi+WHffIWbuh2tCjhyQhTBPMf5E9jDEH4FOmTYgYwbKwtQ==}
+ engines: {node: '>=18'}
+
+ resolution: {integrity: sha512-c/c15i26VrJ4IRt5Z89DnIzCGDn9EcebibhAOjw5ibqEHsE1wLUgkPn9RDmNcUKyU87GeaL633nyJ+pplFR2ZQ==}
+ engines: {node: '>=18'}
+
resolution: {integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==}
engines: {node: '>= 0.4'}
@@ -4106,6 +4739,10 @@ packages:
resolution: {integrity: sha512-jhunvfHWxd7J5EFfSgH4xsYJzSe/lfqbUCxiyyeaQasUsXeEHXtzVid+7EOGByc5JnFa23SSFL3Y2RV/z1T+eQ==}
engines: {node: '>=16.9.0'}
+ resolution: {integrity: sha512-Y22oTqIU4uuPgEemfz7NDJz6OeKf12Lsu+QC+s3BVpda64lTiMYCyGwg5ki4vFxkMwQdeZDl2adZoqUgdFuTgQ==}
+ engines: {node: '>=18'}
+
resolution: {integrity: sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==}
@@ -4116,10 +4753,18 @@ packages:
resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
engines: {node: '>= 0.8'}
+ resolution: {integrity: sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==}
+ engines: {node: '>= 14'}
+
resolution: {integrity: sha512-dFcAjpTQFgoLMzC2VwU+C/CbS7uRL0lWmxDITmqm7C+7F0Odmj6s9l6alZc6AELXhrnggM2CeWSXHGOdX2YtwA==}
engines: {node: '>= 6'}
+ resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==}
+ engines: {node: '>= 14'}
+
resolution: {integrity: sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw==}
engines: {node: '>=10.17.0'}
@@ -4129,6 +4774,10 @@ packages:
engines: {node: '>=18'}
hasBin: true
+ resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==}
+ engines: {node: '>=0.10.0'}
+
resolution: {integrity: sha512-IKXpvIzjnC9XTAUbVBcMfGS0EPaIXtW6v+zr+RRp+hqULEpo0owZax6wyRwPOJbWbzjYspQwusTsfVr0ifh4uQ==}
engines: {node: '>=0.10.0'}
@@ -4161,6 +4810,10 @@ packages:
resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
engines: {node: '>=0.8.19'}
+ resolution: {integrity: sha512-EdDDZu4A2OyIK7Lr/2zG+w5jmbuk1DVBnEwREQvBzspBJkCEbRa8GxU1lghYcaGJCnRWibjDXlq779X1/y5xwg==}
+ engines: {node: '>=8'}
+
resolution: {integrity: sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==}
deprecated: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.
@@ -4230,6 +4883,9 @@ packages:
resolution: {integrity: sha512-+Pgi+vMuUNkJyExiMBt5IlFoMyKnr5zhJ4Uspz58WOhBF5QoIZkFyNHIbBAtHwzVAgk5RtndVNsDRN61/mmDqg==}
engines: {node: '>=12'}
+ resolution: {integrity: sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==}
+
resolution: {integrity: sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==}
@@ -4406,8 +5062,8 @@ packages:
node-notifier:
optional: true
- resolution: {integrity: sha512-/imKNG4EbWNrVjoNC/1H5/9GFy+tqjGBHCaSsN+P2RnPqjsLmv6UD3Ej+Kj8nBWaRAwyk7kK5ZUc+OEatnTR3A==}
+ resolution: {integrity: sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==}
hasBin: true
@@ -4417,6 +5073,9 @@ packages:
resolution: {integrity: sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==}
engines: {node: '>=10'}
+ resolution: {integrity: sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==}
+
resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
@@ -4424,6 +5083,19 @@ packages:
resolution: {integrity: sha512-ttBQIIQPDeLjpPOohtUdXuXUVoA2uIB6fEH9HyJ7234s5mBJ5wTx20njxplLZQgLaOfpmPQA7X2t5AX6tIPbog==}
hasBin: true
+ resolution: {integrity: sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==}
+ hasBin: true
+
+ resolution: {integrity: sha512-MyL55p3Ut3cXbeBEG7Hcv0mVM8pp8PBNWxRqchZnSfAiES1v1mRnMeFfaHWIPULpwsYfvO+ZmMZz5tGCnjzDUQ==}
+ engines: {node: '>=18'}
+ peerDependencies:
+ canvas: ^2.11.2
+ peerDependenciesMeta:
+ canvas:
+ optional: true
+
resolution: {integrity: sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==}
engines: {node: '>=6'}
@@ -4484,6 +5156,80 @@ packages:
resolution: {integrity: sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==}
engines: {node: '>= 0.8.0'}
+ resolution: {integrity: sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [arm64]
+ os: [android]
+
+ resolution: {integrity: sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [arm64]
+ os: [darwin]
+
+ resolution: {integrity: sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [x64]
+ os: [darwin]
+
+ resolution: {integrity: sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [x64]
+ os: [freebsd]
+
+ resolution: {integrity: sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [arm]
+ os: [linux]
+
+ resolution: {integrity: sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [glibc]
+
+ resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [arm64]
+ os: [linux]
+ libc: [musl]
+
+ resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [x64]
+ os: [linux]
+ libc: [glibc]
+
+ resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [x64]
+ os: [linux]
+ libc: [musl]
+
+ resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [arm64]
+ os: [win32]
+
+ resolution: {integrity: sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==}
+ engines: {node: '>= 12.0.0'}
+ cpu: [x64]
+ os: [win32]
+
+ resolution: {integrity: sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==}
+ engines: {node: '>= 12.0.0'}
+
resolution: {integrity: sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==}
engines: {node: '>=14'}
@@ -4518,6 +5264,9 @@ packages:
resolution: {integrity: sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA==}
+ resolution: {integrity: sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==}
+
resolution: {integrity: sha512-dMInicTPVE8d1e5otfwmmjlxkZoUpiVLwyeTdUsi/Caj/gfzzblBcCE5sRHV/AsjuCmxWrte2TNGSYuCeCq+0Q==}
@@ -4539,9 +5288,15 @@ packages:
resolution: {integrity: sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==}
hasBin: true
+ resolution: {integrity: sha512-7fm3l3NAF9WfN6W3JOmf5drwpVqX78JtoGJ3A6W0a6ZnldM41w2fV5D490psKFTpMds8TJse/eHLFFsNHHjHgg==}
+
resolution: {integrity: sha512-8Ktj+prEb1RoCPkEOrPMYUN/nCggB7qAWe3a7OpMjWQkh3l2RD5wKRQ+o8Q8YuI9RG/xs95waaI/E6ym/7NsTw==}
+ resolution: {integrity: sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==}
+
resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
@@ -4550,9 +5305,16 @@ packages:
peerDependencies:
react: ^16.5.1 || ^17.0.0 || ^18.0.0 || ^19.0.0
+ resolution: {integrity: sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==}
+ hasBin: true
+
resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
+ resolution: {integrity: sha512-llBEhWm1SacoRwgHUoQJYtwp4PBLF4faQi5TCpIGyGs9n4y5+juI0tDgyKIfpqxckRHaHzouUEph3THklWh03w==}
+
resolution: {integrity: sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==}
engines: {node: '>=10'}
@@ -4753,6 +5515,10 @@ packages:
resolution: {integrity: sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==}
engines: {node: '>=18'}
+ resolution: {integrity: sha512-I9jwMn07Sy/IwOj3zVkVik2JTvgpaykDZEigL6Rx6N9LbMywwUSMtxET+7lVoDLLd3O3IXwJwvuuns8UB/HeAg==}
+ engines: {node: '>=4'}
+
resolution: {integrity: sha512-MULkVLfKGYDFYejP07QOurDLLQpcjk7Fw+7jXS2R2czRQzR56yHRveU5NDJEOviH+hETZKSkIk5c+T23GjFUMg==}
engines: {node: 18 || 20 || >=22}
@@ -4780,6 +5546,10 @@ packages:
resolution: {integrity: sha512-sXboRm3BeBeLm938eaiyLMe0OxzfXIlZvbv4ir/jVgQy1zDhWjgmny0WoN45fuDKhCCQsYMbBJrv/A6jd8aCUg==}
+ resolution: {integrity: sha512-tzzskb3bG8LvYGFF/mDTpq3jpI6Q9wc3LEmBaghu+DdCssd1FakN7Bc0hVNmEyGq1bq3RgfkCb3cmQLpNPOroA==}
+ engines: {node: '>=4'}
+
resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
@@ -4803,6 +5573,12 @@ packages:
resolution: {integrity: sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==}
engines: {node: '>= 0.6'}
+ resolution: {integrity: sha512-fgAN3jGAh+RoxUGZHTSOLJIqUc2wmoBwGR4tbpNAKmmovFoWq0OdRkb0VkldReO2a2iBT/OEulG9XSUc10r3zg==}
+
+ resolution: {integrity: sha512-5m3bsyrjFWE1xf7nz7YXdN4udnVtXK6/Yfgn5qnahL6bCkf2yKt4k3nuTKAtT4r3IG8JNR2ncsIMdZuAzJjHQQ==}
+
resolution: {integrity: sha512-4eUQWVPCUUUiBjLnHS3cXWeC6ryoPUc0U3rP7IuzapoGbzMqd/r6KKO0clr0b+snQhsrueFEhCZDdK+LK7hxKg==}
engines: {node: ^18 || ^20 || >= 21}
@@ -4826,6 +5602,9 @@ packages:
resolution: {integrity: sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw==}
engines: {node: '>=8'}
+ resolution: {integrity: sha512-7YRhZ3jS45LwmSCT4b2sVFHt/WuovaktDU07QrtOBY2PXskss5a9jfmR9jptyumwXST+rFjrmppMY1KT/yn35A==}
+
resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
engines: {node: '>=0.10.0'}
@@ -4834,6 +5613,10 @@ packages:
resolution: {integrity: sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==}
engines: {node: '>= 0.4'}
+ resolution: {integrity: sha512-4a+OsYv9UktOJKE+l1A4OufDgdRF9PifWj+tJnHURo/P+WOxpG4GzUFL9qCalmWauao6ogiG+QvnCovwPoyAWA==}
+ engines: {node: '>=12.20.0'}
+
resolution: {integrity: sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==}
engines: {node: '>= 0.8'}
@@ -5069,6 +5852,10 @@ packages:
engines: {node: '>=14'}
hasBin: true
+ resolution: {integrity: sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==}
+ engines: {node: ^10.13.0 || ^12.13.0 || ^14.15.0 || >=15.0.0}
+
resolution: {integrity: sha512-Pdlw/oPxN+aXdmM9R00JVC9WVFoCLTKJvDVLgmJ+qAffBMxsV85l/Lu7sNx4zSzPyoL2euImuEwHhOXdEgNFZQ==}
engines: {node: ^14.15.0 || ^16.10.0 || >=18.0.0}
@@ -5103,6 +5890,9 @@ packages:
resolution: {integrity: sha512-cJ+oHTW1VAEa8cJslgmUZrc+sjRKgAKl3Zyse6+PV38hZe/V6Z14TbCuXcan9F9ghlz4QrFr2c92TNF82UkYHA==}
engines: {node: '>=10'}
+ resolution: {integrity: sha512-JZd3gMVBAVQkSs6HdNZo9Sdo0LNcQeMNP3CozBJb3JYC/QUYZTnKxP+f8oWRX4rHP5EurWxqAHTSwUCjlNKa1w==}
+
resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
engines: {node: '>=6'}
@@ -5114,6 +5904,9 @@ packages:
resolution: {integrity: sha512-O9gl3zCl5h5blw1KGUzQKhA5oUXSl8rwUIM5o0S3nCXMliSvy5Dzx7/DJcI+SwgICv+IneSZwhBh1oSyEHA71A==}
engines: {node: '>=0.6'}
+ resolution: {integrity: sha512-FIqgj2EUvTa7R50u0rGsyTftzjYmv/a3hO345bZNrqabNqjtgiDMgmo4mkUjd+nzU5oF3dClKqFIPUKybUyqoQ==}
+
resolution: {integrity: sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==}
@@ -5152,6 +5945,9 @@ packages:
resolution: {integrity: sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ==}
+ resolution: {integrity: sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==}
+
resolution: {integrity: sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==}
@@ -5242,6 +6038,10 @@ packages:
react: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
react-dom: ^16.0.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+ resolution: {integrity: sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==}
+ engines: {node: '>=8'}
+
resolution: {integrity: sha512-LDsoVvb/CpoV9EN3FXvgvSHNJWuCIzl9MiO3ppOevuGLpSGJhwfQjpEwfFJcQvNSddHADDdZaWx0HnmMxRXG7g==}
engines: {node: '>= 18.19.0'}
@@ -5286,6 +6086,9 @@ packages:
resolution: {integrity: sha512-QT7FVMXfWOYFbeRBF6nu+I6tr2Tf3u0q8RIEjNob/heKY/nh7drD/k7eeMFmSQgnTtCzLDcCu/XEnpW2wk4xCQ==}
engines: {node: '>=9.3.0 || >=8.10.0 <9.0.0'}
+ resolution: {integrity: sha512-KigOCHcocU3XODJxsu8i/j8T9tzT4adHiecwORRQ0ZZFcp7ahwXuRU1m+yuO90C5ZUyGeGfocHDI14M3L3yDAQ==}
+
resolution: {integrity: sha512-OrZaX2Mb+rJCpH/6CpSqt9xFVpN++x01XnN2ie9g6P5/3xelLAkXWVADpdz1IHD/KFfEXyE6V0U01OQ3UO2rEg==}
engines: {node: '>=8'}
@@ -5327,6 +6130,12 @@ packages:
resolution: {integrity: sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==}
engines: {node: '>= 18'}
+ resolution: {integrity: sha512-TrEMa7JGdVm0UThDJSx7ddw5nVm3UJS9o9CCIZ72B1vSyEZoziDqBYP3XIoi/12lKrJR8rE3jeFHMok2F/Mnsg==}
+
+ resolution: {integrity: sha512-guoltQEx+9aMf2gDZ0s62EcV8lsXR+0w8915TC3ITdn2YueuNjdAYh/levpU9nFaoChh9RUS5ZdQMrKfVEN9tw==}
+
resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
@@ -5343,6 +6152,10 @@ packages:
resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
+ resolution: {integrity: sha512-xAg7SOnEhrm5zI3puOOKyy1OMcMlIJZYNJY7xLBwSze0UjhPLnWfj2GF2EpT0jmzaJKIWKHLsaSSajf35bcYnA==}
+ engines: {node: '>=v12.22.7'}
+
resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}
@@ -5397,6 +6210,9 @@ packages:
resolution: {integrity: sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ==}
engines: {node: '>= 0.4'}
+ resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==}
+
resolution: {integrity: sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==}
@@ -5423,6 +6239,9 @@ packages:
resolution: {integrity: sha512-stxByr12oeeOyY2BlviTNQlYV5xOj47GirPr4yA1hE9JCtxfQN0+tVbkxwCtYDQWhEKWFHsEK48ORg5jrouCAg==}
engines: {node: '>=20'}
+ resolution: {integrity: sha512-LAOh4z89bGQvl9pFfNF8V146i7o7/CqFPbqzYgP+yYzDIDeS9HaNFtXABamRW+AQzEVODcvE79ljJ+8a9YSdMg==}
+
resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
engines: {node: '>=0.10.0'}
@@ -5455,10 +6274,16 @@ packages:
resolution: {integrity: sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ==}
engines: {node: '>=10'}
+ resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
+
resolution: {integrity: sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==}
engines: {node: '>= 0.8'}
+ resolution: {integrity: sha512-oCUKSupKTHX53EyjDtuZQ64pjLJ6yYCtpmEw0goYxtjG9KpbRe8KAsl2tBUGU9DyMcJ0RwJ8GqJAFzMXcXW1Rw==}
+
resolution: {integrity: sha512-H73RAHsVBapbim0tU2JwwOiXUj+fikfiaoYAKHF3VJfA0pe2BCzkhAHBlLG6REzE+2WNZcxOXjK7lkso+9euLA==}
@@ -5511,6 +6336,10 @@ packages:
resolution: {integrity: sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA==}
engines: {node: '>=6'}
+ resolution: {integrity: sha512-laJTa3Jb+VQpaC6DseHhF7dXVqHTfJPCRDaEbid/drOhgitgYku/letMUqOXFoWV0zIIUbjpdH2t+tYj4bQMRQ==}
+ engines: {node: '>=8'}
+
resolution: {integrity: sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==}
engines: {node: '>=8'}
@@ -5538,12 +6367,22 @@ packages:
resolution: {integrity: sha512-ot0WnXS9fgdkgIcePe6RHNk1WA8+muPa6cSjeR3V8K27q9BB1rTE3R1p7Hv0z1ZyAc8s6Vvv8DIyWf681MAt0w==}
engines: {node: '>= 0.4'}
+ resolution: {integrity: sha512-e4hG1hRwoOdRb37cIMSgzNsxyzKfayW6VOflrwvR+/bzrkyxY/31WkbgnQpgtrNp1SdpJvpUAGTa/ZoiPNDuRQ==}
+
+ resolution: {integrity: sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==}
+
resolution: {integrity: sha512-uxL7qAVQriqRQPAyK3pj66VqskWqoZ37PW94jwOTwNfq/z9oyu1V+eqrZqtR2+fCiXdYOZe/Modt8GtvqNzu+w==}
resolution: {integrity: sha512-gOhV3P7ufE62QDGg1zVaTgCR+EtPv92k2nIhVcVKcLmxT1sUBsQGhnZj175j+MqRt4zLF7ic+sCYjfhxMxj7YQ==}
+ resolution: {integrity: sha512-uxc/zpqFg6x7C8vOE7lh6Lbda8eEL9zmVm/PLeTPBRhh1xCgdWaQ+J1CUieGpIfm2HdtsUpRv+HshiasBMcc6A==}
+ engines: {node: '>=6'}
+
resolution: {integrity: sha512-+qfUHz700DWnRutdUsxRRVZ38G1Qr27OetwaMYTdg8hcPxf46U0S1Zf76dQMWRBmusOt2ZCK5kbIaiLkoGO7WQ==}
@@ -5568,6 +6407,9 @@ packages:
resolution: {integrity: sha512-+FbBPE1o9QAYvviau/qC5SE3caw21q3xkvWKBtja5vgqOWIHHJ3ioaq1VPfn/Szqctz2bU/oYeKd9/z5BL+PVg==}
+ resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
+
resolution: {integrity: sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==}
@@ -5579,6 +6421,10 @@ packages:
resolution: {integrity: sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==}
engines: {node: '>=12.0.0'}
+ resolution: {integrity: sha512-yau8yJdTt989Mm0Bd/236QnzEiPf2xLLTqUZRUJOo/3CB078LSwzei343DgtJVmfJKJE3TMINY1u42SQsP6mXw==}
+ engines: {node: '>=14.0.0'}
+
resolution: {integrity: sha512-3f0uOEAQwIqGuWW2MVzYg8fV/QNnc/IpuJNG837rLuczAaLVHslWHZQj4IGiEl5Hs3kkbhwL9Ab7Hrsmuj+Smw==}
@@ -5590,6 +6436,14 @@ packages:
resolution: {integrity: sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==}
engines: {node: '>=0.6'}
+ resolution: {integrity: sha512-Loo5UUvLD9ScZ6jh8beX1T6sO1w2/MpCRpEP7V280GKMVUQ0Jzar2U3UJPsrdbziLEMMhu3Ujnq//rhiFuIeag==}
+ engines: {node: '>=6'}
+
+ resolution: {integrity: sha512-hdF5ZgjTqgAntKkklYw0R03MG2x/bSzTtkxmIRw/sTNV8YXsCJ1tfLAX23lhxhHJlEf3CRCOCGGWw3vI3GaSPw==}
+ engines: {node: '>=18'}
+
resolution: {integrity: sha512-L0Orpi8qGpRG//Nd+H90vFB+3iHnue1zSSGmNOOCh1GLJ7rUKVwV2HvijphGQS2UmhUZewS9VgvxYIdgr+fG1A==}
hasBin: true
@@ -5695,6 +6549,9 @@ packages:
resolution: {integrity: sha512-yu26mwteFYzBAot7KVMqFGCVpsF6g8wXfJzQUHvu1no3+rRRSFcSV2nKeYvNPLD2J4b08jYBDhHUjeH0ygIl9w==}
hasBin: true
+ resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+
resolution: {integrity: sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==}
@@ -5730,6 +6587,10 @@ packages:
resolution: {integrity: sha512-m+vIdyeCOpdr/QeQCu2EzxX/ohgS8KbnPDgFni4dQsfSCtpz8UqDyY5GjRru8PDKuYn7Fq19j1CQ+nJSsGKOzg==}
+ resolution: {integrity: sha512-CJ1QgKmNg3CwvAv/kOFmtnEN05f0D/cn9QntgNOQlQF9dgvVTHj3t+8JPdjqawCHk7V/KA+fbUqzZ9XWhcqPUg==}
+ engines: {node: '>= 4.0.0'}
+
resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==}
engines: {node: '>= 0.8'}
@@ -5743,6 +6604,9 @@ packages:
resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==}
+ resolution: {integrity: sha512-WypcfiRhfeUP9vvF0j6rw0J3hrWrw6iZv3+22h6iRMJ/8z1Tj6XfLP4DsUix5MhMPnXpiHDoKyoZ/bdCkwBCiQ==}
+
resolution: {integrity: sha512-jQL3lRnocaFtu3V00JToYz/4QkNWswxijDaCVNZRiRTO3HQDLsdu1ZtmIUvV4yPp+rvWm5j0y0TG/S61cuijTg==}
engines: {node: '>=10'}
@@ -5871,17 +6735,84 @@ packages:
yaml:
optional: true
+ resolution: {integrity: sha512-R9jUTe5S4Qb0HCd4TNqpC7oGcrMssMRGXLW80ubjWsW9VH5GF8y1Y0SFLY9AbqSk6nt0PnOx4H4WNJYZ13GUPw==}
+ engines: {node: ^20.0.0 || ^22.0.0 || >=24.0.0}
+ hasBin: true
+ peerDependencies:
+ '@edge-runtime/vm': '*'
+ '@opentelemetry/api': ^1.9.0
+ '@types/node': ^20.0.0 || ^22.0.0 || >=24.0.0
+ '@vitest/browser-playwright': 4.1.10
+ '@vitest/browser-preview': 4.1.10
+ '@vitest/browser-webdriverio': 4.1.10
+ '@vitest/coverage-istanbul': 4.1.10
+ '@vitest/coverage-v8': 4.1.10
+ '@vitest/ui': 4.1.10
+ happy-dom: '*'
+ jsdom: '*'
+ vite: ^6.0.0 || ^7.0.0 || ^8.0.0
+ peerDependenciesMeta:
+ '@edge-runtime/vm':
+ optional: true
+ '@opentelemetry/api':
+ optional: true
+ '@types/node':
+ optional: true
+ '@vitest/browser-playwright':
+ optional: true
+ '@vitest/browser-preview':
+ optional: true
+ '@vitest/browser-webdriverio':
+ optional: true
+ '@vitest/coverage-istanbul':
+ optional: true
+ '@vitest/coverage-v8':
+ optional: true
+ '@vitest/ui':
+ optional: true
+ happy-dom:
+ optional: true
+ jsdom:
+ optional: true
+
+ resolution: {integrity: sha512-o8qghlI8NZHU1lLPrpi2+Uq7abh4GGPpYANlalzWxyWteJOCsr/P+oPBA49TOLu5FTZO4d3F9MnWJfiMo4BkmA==}
+ engines: {node: '>=18'}
+
resolution: {integrity: sha512-ts/8E8l5b7kY0vlWLewOkDXMmPdLcVV4GmOQLyxuSswIJsweeFZtAsMF7k1Nszz+TYBQrlYRmzOnr398y1JemQ==}
resolution: {integrity: sha512-bKr1DkiNa2krS7qxNtdrtHAmzuYGFQLiQ13TsorsdT6ULTkPLKuu5+GsFpDlg6JFjUTwX2DyhMPG2be8uPrqsQ==}
+ resolution: {integrity: sha512-VwddBukDzu71offAQR975unBIGqfKZpM+8ZX6ySk8nYhVoo5CYaZyzt3YBvYtRtO+aoGlqxPg/B87NGVZ/fu6g==}
+ engines: {node: '>=12'}
+
+ resolution: {integrity: sha512-6qN4hJdMwfYBtE3YBTTHhoeuUrDBPZmbQaxWAqSALV/MeEnR5z1xd8UKud2RAkFoPkmB+hli1TZSnyi84xz1vQ==}
+ engines: {node: '>=18'}
+ deprecated: Use @exodus/bytes instead for a more spec-conformant and faster implementation
+
+ resolution: {integrity: sha512-QaKxh0eNIi2mE9p2vEdzfagOKHCcj1pJ56EEHGQOVxp8r9/iszLUUV7v89x9O1p/T+NlTM5W7jW6+cz4Fq1YVg==}
+ engines: {node: '>=18'}
+
+ resolution: {integrity: sha512-De72GdQZzNTUBBChsXueQUnPKDkg/5A5zp7pFDuQAj5UFoENpiACU0wlCvzpAGnTkj++ihpKwKyYewn/XNUbKw==}
+ engines: {node: '>=18'}
+
resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
engines: {node: '>= 8'}
hasBin: true
+ resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==}
+ engines: {node: '>=8'}
+ hasBin: true
+
resolution: {integrity: sha512-8drMJ4rkgaPo1Me4zD/3WLfI/zPdA9o2IipKODunnGDcuqbHwjsbB79ylv04LCGGzU0xQ6vTznOMpQGaLhhm6A==}
engines: {node: '>= 12.0.0'}
@@ -5921,6 +6852,13 @@ packages:
utf-8-validate:
optional: true
+ resolution: {integrity: sha512-EvGK8EJ3DhaHfbRlETOWAS5pO9MZITeauHKJyb8wyajUfQUenkIg2MvLDTZ4T/TgIcm3HU0TFBgWWboAZ30UHg==}
+ engines: {node: '>=18'}
+
+ resolution: {integrity: sha512-JZnDKK8B0RCDw84FNdDAIpZK+JuJw+s7Lz8nksI7SIuU3UXJJslUthsi+uWBUYOwPFwW7W7PRLRfUKpxjtjFCw==}
+
resolution: {integrity: sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==}
engines: {node: '>=0.4'}
@@ -5997,6 +6935,8 @@ packages:
snapshots:
+ '@adobe/[email protected]': {}
+
dependencies:
zod: 3.25.76
@@ -6059,10 +6999,18 @@ snapshots:
dependencies:
json-schema: 0.4.0
+ '@asamuzakjp/[email protected]':
+ dependencies:
+ '@csstools/css-calc': 2.1.4(@csstools/[email protected](@csstools/[email protected]))(@csstools/[email protected])
+ '@csstools/css-color-parser': 3.1.0(@csstools/[email protected](@csstools/[email protected]))(@csstools/[email protected])
+ '@csstools/css-parser-algorithms': 3.0.5(@csstools/[email protected])
+ '@csstools/css-tokenizer': 3.0.4
+ lru-cache: 10.4.3
+
dependencies:
- '@assistant-ui/store': 0.2.21(@assistant-ui/[email protected](@types/[email protected])([email protected]))(@types/[email protected])([email protected])
- '@assistant-ui/tap': 0.9.4(@types/[email protected])([email protected])
+ '@assistant-ui/store': 0.2.21(@assistant-ui/[email protected](@types/[email protected])([email protected]))(@types/[email protected])([email protected])
+ '@assistant-ui/tap': 0.9.5(@types/[email protected])([email protected])
assistant-stream: 0.3.31([email protected](@opentelemetry/[email protected]))
nanoid: 6.0.0
optionalDependencies:
@@ -6076,9 +7024,9 @@ snapshots:
dependencies:
- '@assistant-ui/store': 0.2.21(@assistant-ui/[email protected](@types/[email protected])([email protected]))(@types/[email protected])([email protected])
- '@assistant-ui/tap': 0.9.4(@types/[email protected])([email protected])
+ '@assistant-ui/store': 0.2.21(@assistant-ui/[email protected](@types/[email protected])([email protected]))(@types/[email protected])([email protected])
+ '@assistant-ui/tap': 0.9.5(@types/[email protected])([email protected])
'@radix-ui/primitive': 1.1.7
'@radix-ui/react-compose-refs': 1.1.4(@types/[email protected])([email protected])
@@ -6106,15 +7054,15 @@ snapshots:
- redis
- use-sync-external-store
dependencies:
- '@assistant-ui/tap': 0.9.4(@types/[email protected])([email protected])
+ '@assistant-ui/tap': 0.9.5(@types/[email protected])([email protected])
react: 19.2.8
use-effect-event: 2.0.3([email protected])
optionalDependencies:
'@types/react': 19.2.17
dependencies:
react: 19.2.8
optionalDependencies:
@@ -6501,8 +7449,30 @@ snapshots:
'@bcoe/[email protected]': {}
+ '@bcoe/[email protected]': {}
+
'@colors/[email protected]': {}
+ '@csstools/[email protected]': {}
+
+ '@csstools/[email protected](@csstools/[email protected](@csstools/[email protected]))(@csstools/[email protected])':
+ dependencies:
+ '@csstools/css-parser-algorithms': 3.0.5(@csstools/[email protected])
+ '@csstools/css-tokenizer': 3.0.4
+
+ '@csstools/[email protected](@csstools/[email protected](@csstools/[email protected]))(@csstools/[email protected])':
+ dependencies:
+ '@csstools/color-helpers': 5.1.0
+ '@csstools/css-calc': 2.1.4(@csstools/[email protected](@csstools/[email protected]))(@csstools/[email protected])
+ '@csstools/css-parser-algorithms': 3.0.5(@csstools/[email protected])
+ '@csstools/css-tokenizer': 3.0.4
+
+ '@csstools/[email protected](@csstools/[email protected])':
+ dependencies:
+ '@csstools/css-tokenizer': 3.0.4
+
+ '@csstools/[email protected]': {}
+
dependencies:
'@so-ric/colorspace': 1.1.6
@@ -6789,99 +7759,112 @@ snapshots:
'@esbuild/[email protected]':
optional: true
+ dependencies:
+ eslint-visitor-keys: 3.4.3
+
dependencies:
eslint-visitor-keys: 3.4.3
'@eslint-community/[email protected]': {}
dependencies:
'@typescript-eslint/types': 8.65.0
'@typescript-eslint/typescript-estree': 8.65.0([email protected])([email protected])
string-ts: 2.3.1
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
dependencies:
'@typescript-eslint/scope-manager': 8.65.0
'@typescript-eslint/types': 8.65.0
ts-pattern: 5.9.0
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
dependencies:
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
dependencies:
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
dependencies:
'@typescript-eslint/types': 8.65.0
ts-pattern: 5.9.0
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
dependencies:
ts-pattern: 5.9.0
typescript: 6.0.3
zod: 4.4.3
transitivePeerDependencies:
- supports-color
dependencies:
'@typescript-eslint/scope-manager': 8.65.0
'@typescript-eslint/types': 8.65.0
ts-pattern: 5.9.0
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
+ dependencies:
+ '@eslint/object-schema': 2.1.7
+ debug: 4.4.3([email protected])
+ minimatch: 3.1.5
+ transitivePeerDependencies:
+ - supports-color
+
dependencies:
'@eslint/object-schema': 3.0.5
@@ -6890,21 +7873,52 @@ snapshots:
transitivePeerDependencies:
- supports-color
+ '@eslint/[email protected]':
+ dependencies:
+ '@eslint/core': 0.17.0
+
'@eslint/[email protected]':
dependencies:
'@eslint/core': 1.2.1
- '@eslint/[email protected]':
+ '@eslint/[email protected]':
dependencies:
'@types/json-schema': 7.0.15
- optionalDependencies:
-
- '@eslint/[email protected]': {}
+ '@eslint/[email protected]':
+ dependencies:
+ '@types/json-schema': 7.0.15
- '@eslint/[email protected]':
+ dependencies:
+ ajv: 6.15.0
+ debug: 4.4.3([email protected])
+ espree: 10.4.0
+ globals: 14.0.0
+ ignore: 5.3.2
+ import-fresh: 3.3.1
+ js-yaml: 4.3.1
+ minimatch: 3.1.5
+ strip-json-comments: 3.1.1
+ transitivePeerDependencies:
+ - supports-color
+
+ optionalDependencies:
+
+ '@eslint/[email protected]': {}
+
+ '@eslint/[email protected]': {}
+
+ '@eslint/[email protected]': {}
+
+ '@eslint/[email protected]':
+ dependencies:
+ '@eslint/core': 0.17.0
+ levn: 0.4.1
+
+ '@eslint/[email protected]':
dependencies:
'@eslint/core': 1.2.1
levn: 0.4.1
@@ -7586,6 +8600,66 @@ snapshots:
- '@types/react-dom'
- supports-color
+ '@parcel/[email protected]':
+ optional: true
+
+ '@parcel/[email protected]':
+ optional: true
+
+ '@parcel/[email protected]':
+ optional: true
+
+ '@parcel/[email protected]':
+ optional: true
+
+ '@parcel/[email protected]':
+ optional: true
+
+ '@parcel/[email protected]':
+ optional: true
+
+ '@parcel/[email protected]':
+ optional: true
+
+ '@parcel/[email protected]':
+ optional: true
+
+ '@parcel/[email protected]':
+ optional: true
+
+ '@parcel/[email protected]':
+ optional: true
+
+ '@parcel/[email protected]':
+ optional: true
+
+ '@parcel/[email protected]':
+ optional: true
+
+ '@parcel/[email protected]':
+ optional: true
+
+ '@parcel/[email protected]':
+ dependencies:
+ detect-libc: 1.0.3
+ is-glob: 4.0.3
+ micromatch: 4.0.8
+ node-addon-api: 7.1.1
+ optionalDependencies:
+ '@parcel/watcher-android-arm64': 2.5.1
+ '@parcel/watcher-darwin-arm64': 2.5.1
+ '@parcel/watcher-darwin-x64': 2.5.1
+ '@parcel/watcher-freebsd-x64': 2.5.1
+ '@parcel/watcher-linux-arm-glibc': 2.5.1
+ '@parcel/watcher-linux-arm-musl': 2.5.1
+ '@parcel/watcher-linux-arm64-glibc': 2.5.1
+ '@parcel/watcher-linux-arm64-musl': 2.5.1
+ '@parcel/watcher-linux-x64-glibc': 2.5.1
+ '@parcel/watcher-linux-x64-musl': 2.5.1
+ '@parcel/watcher-win32-arm64': 2.5.1
+ '@parcel/watcher-win32-ia32': 2.5.1
+ '@parcel/watcher-win32-x64': 2.5.1
+
'@protobufjs/[email protected]': {}
'@protobufjs/[email protected]': {}
@@ -8518,6 +9592,76 @@ snapshots:
'@standard-schema/[email protected]': {}
+ dependencies:
+ '@babel/core': 7.29.7([email protected])
+
+ dependencies:
+ '@babel/core': 7.29.7([email protected])
+
+ dependencies:
+ '@babel/core': 7.29.7([email protected])
+
+ dependencies:
+ '@babel/core': 7.29.7([email protected])
+
+ dependencies:
+ '@babel/core': 7.29.7([email protected])
+
+ dependencies:
+ '@babel/core': 7.29.7([email protected])
+
+ dependencies:
+ '@babel/core': 7.29.7([email protected])
+
+ dependencies:
+ '@babel/core': 7.29.7([email protected])
+
+ dependencies:
+ '@babel/core': 7.29.7([email protected])
+ '@svgr/babel-plugin-add-jsx-attribute': 8.0.0(@babel/[email protected]([email protected]))
+ '@svgr/babel-plugin-remove-jsx-attribute': 8.0.0(@babel/[email protected]([email protected]))
+ '@svgr/babel-plugin-remove-jsx-empty-expression': 8.0.0(@babel/[email protected]([email protected]))
+ '@svgr/babel-plugin-replace-jsx-attribute-value': 8.0.0(@babel/[email protected]([email protected]))
+ '@svgr/babel-plugin-svg-dynamic-title': 8.0.0(@babel/[email protected]([email protected]))
+ '@svgr/babel-plugin-svg-em-dimensions': 8.0.0(@babel/[email protected]([email protected]))
+ '@svgr/babel-plugin-transform-react-native-svg': 8.1.0(@babel/[email protected]([email protected]))
+ '@svgr/babel-plugin-transform-svg-component': 8.0.0(@babel/[email protected]([email protected]))
+
+ dependencies:
+ '@babel/core': 7.29.7([email protected])
+ '@svgr/babel-preset': 8.1.0(@babel/[email protected]([email protected]))
+ camelcase: 6.3.0
+ cosmiconfig: 8.3.6([email protected])
+ snake-case: 3.0.4
+ transitivePeerDependencies:
+ - supports-color
+ - typescript
+
+ dependencies:
+ '@babel/types': 7.29.7
+ entities: 4.5.0
+
+ dependencies:
+ '@babel/core': 7.29.7([email protected])
+ '@svgr/babel-preset': 8.1.0(@babel/[email protected]([email protected]))
+ '@svgr/core': 8.1.0([email protected])([email protected])
+ '@svgr/hast-util-to-babel-ast': 8.0.0
+ svg-parser: 2.0.4
+ transitivePeerDependencies:
+ - supports-color
+
optional: true
@@ -8587,41 +9731,127 @@ snapshots:
'@tabby_ai/[email protected]': {}
- '@truefoundry/[email protected](2258b7d3a6c75cf9484a74ef844b7ab2)':
+ '@tailwindcss/[email protected]':
dependencies:
- '@openuidev/react-lang': 0.2.9(@modelcontextprotocol/[email protected]([email protected])([email protected]))([email protected])([email protected])
- clsx: 2.1.1
- lucide-react: 0.562.0([email protected])
- monaco-editor: 0.56.0
+ '@parcel/watcher': 2.5.1
+ '@tailwindcss/node': 4.3.3
+ '@tailwindcss/oxide': 4.3.3
+ enhanced-resolve: 5.24.5
+ mri: 1.2.0
+ picocolors: 1.1.1
+ tailwindcss: 4.3.3
+
+ '@tailwindcss/[email protected]':
+ dependencies:
+ '@jridgewell/remapping': 2.3.5
+ enhanced-resolve: 5.24.5
+ jiti: 2.7.0
+ lightningcss: 1.32.0
+ magic-string: 0.30.21
+ source-map-js: 1.2.1
+ tailwindcss: 4.3.3
+
+ '@tailwindcss/[email protected]':
+ optional: true
+
+ '@tailwindcss/[email protected]':
+ optional: true
+
+ '@tailwindcss/[email protected]':
+ optional: true
+
+ '@tailwindcss/[email protected]':
+ optional: true
+
+ '@tailwindcss/[email protected]':
+ optional: true
+
+ '@tailwindcss/[email protected]':
+ optional: true
+
+ '@tailwindcss/[email protected]':
+ optional: true
+
+ '@tailwindcss/[email protected]':
+ optional: true
+
+ '@tailwindcss/[email protected]':
+ optional: true
+
+ '@tailwindcss/[email protected]':
+ optional: true
+
+ '@tailwindcss/[email protected]':
+ optional: true
+
+ '@tailwindcss/[email protected]':
+ optional: true
+
+ '@tailwindcss/[email protected]':
+ optionalDependencies:
+ '@tailwindcss/oxide-android-arm64': 4.3.3
+ '@tailwindcss/oxide-darwin-arm64': 4.3.3
+ '@tailwindcss/oxide-darwin-x64': 4.3.3
+ '@tailwindcss/oxide-freebsd-x64': 4.3.3
+ '@tailwindcss/oxide-linux-arm-gnueabihf': 4.3.3
+ '@tailwindcss/oxide-linux-arm64-gnu': 4.3.3
+ '@tailwindcss/oxide-linux-arm64-musl': 4.3.3
+ '@tailwindcss/oxide-linux-x64-gnu': 4.3.3
+ '@tailwindcss/oxide-linux-x64-musl': 4.3.3
+ '@tailwindcss/oxide-wasm32-wasi': 4.3.3
+ '@tailwindcss/oxide-win32-arm64-msvc': 4.3.3
+ '@tailwindcss/oxide-win32-x64-msvc': 4.3.3
+
+ '@testing-library/[email protected]':
+ dependencies:
+ '@babel/code-frame': 7.29.7
+ '@babel/runtime': 7.29.7
+ '@types/aria-query': 5.0.4
+ aria-query: 5.3.0
+ dom-accessibility-api: 0.5.16
+ lz-string: 1.5.0
+ picocolors: 1.1.1
+ pretty-format: 27.5.1
+
+ '@testing-library/[email protected](@testing-library/[email protected])':
+ dependencies:
+ '@adobe/css-tools': 4.5.0
+ '@testing-library/dom': 10.4.1
+ aria-query: 5.3.2
+ css.escape: 1.5.1
+ dom-accessibility-api: 0.6.3
+ picocolors: 1.1.1
+ redent: 3.0.0
+
+ dependencies:
+ '@babel/runtime': 7.29.7
+ '@testing-library/dom': 10.4.1
react: 19.2.8
react-dom: 19.2.8([email protected])
- react-markdown: 10.1.0(@types/[email protected])([email protected])([email protected])
- react-syntax-highlighter: 16.1.1([email protected])
- remark-gfm: 4.0.1([email protected])
- tailwind-merge: 3.6.0
- truefoundry-gateway-sdk: 0.4.0
- zod: 4.4.3
optionalDependencies:
'@types/react': 19.2.17
+ '@types/react-dom': 19.2.3(@types/[email protected])
+
+ dependencies:
+ '@assistant-ui/store': 0.2.21(@assistant-ui/[email protected](@types/[email protected])([email protected]))(@types/[email protected])([email protected])
+ react: 19.2.8
+ optionalDependencies:
+ '@types/react': 19.2.17
+ truefoundry-gateway-sdk: 0.4.0
transitivePeerDependencies:
- '@assistant-ui/tap'
- - '@modelcontextprotocol/sdk'
- - '@types/react-dom'
- assistant-cloud
- ioredis
- redis
- - supports-color
- zustand
dependencies:
- '@assistant-ui/store': 0.2.21(@assistant-ui/[email protected](@types/[email protected])([email protected]))(@types/[email protected])([email protected])
+ '@assistant-ui/store': 0.2.21(@assistant-ui/[email protected](@types/[email protected])([email protected]))(@types/[email protected])([email protected])
react: 19.2.8
optionalDependencies:
'@types/react': 19.2.17
@@ -8633,6 +9863,8 @@ snapshots:
- redis
- zustand
+ '@types/[email protected]': {}
+
dependencies:
'@babel/parser': 7.29.7
@@ -8658,6 +9890,11 @@ snapshots:
dependencies:
'@types/node': 24.13.3
+ '@types/[email protected]':
+ dependencies:
+ '@types/deep-eql': 4.0.2
+ assertion-error: 2.0.1
+
'@types/[email protected]': {}
'@types/[email protected]': {}
@@ -8686,6 +9923,8 @@ snapshots:
dependencies:
'@types/ms': 2.1.0
+ '@types/[email protected]': {}
+
'@types/[email protected]': {}
@@ -8727,6 +9966,10 @@ snapshots:
'@types/[email protected]': {}
+ '@types/[email protected]':
+ dependencies:
+ undici-types: 6.21.0
+
dependencies:
undici-types: 7.18.2
@@ -8746,6 +9989,10 @@ snapshots:
dependencies:
'@types/react': 19.2.17
+ '@types/[email protected]':
+ dependencies:
+ '@types/react': 19.2.17
+
dependencies:
csstype: 3.2.3
@@ -8771,15 +10018,15 @@ snapshots:
dependencies:
'@types/yargs-parser': 21.0.3
dependencies:
'@eslint-community/regexpp': 4.12.2
'@typescript-eslint/scope-manager': 8.65.0
'@typescript-eslint/visitor-keys': 8.65.0
ignore: 7.0.6
natural-compare: 1.4.0
ts-api-utils: 2.5.0([email protected])
@@ -8787,18 +10034,55 @@ snapshots:
transitivePeerDependencies:
- supports-color
+ dependencies:
+ '@eslint-community/regexpp': 4.12.2
+ '@typescript-eslint/scope-manager': 8.65.0
+ '@typescript-eslint/visitor-keys': 8.65.0
+ ignore: 7.0.6
+ natural-compare: 1.4.0
+ ts-api-utils: 2.5.0([email protected])
+ typescript: 5.9.3
+ transitivePeerDependencies:
+ - supports-color
+
dependencies:
'@typescript-eslint/scope-manager': 8.65.0
'@typescript-eslint/types': 8.65.0
'@typescript-eslint/typescript-estree': 8.65.0([email protected])([email protected])
'@typescript-eslint/visitor-keys': 8.65.0
debug: 4.4.3([email protected])
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
+ dependencies:
+ '@typescript-eslint/scope-manager': 8.65.0
+ '@typescript-eslint/types': 8.65.0
+ '@typescript-eslint/typescript-estree': 8.65.0([email protected])([email protected])
+ '@typescript-eslint/visitor-keys': 8.65.0
+ debug: 4.4.3([email protected])
+ typescript: 5.9.3
+ transitivePeerDependencies:
+ - supports-color
+
+ dependencies:
+ '@typescript-eslint/tsconfig-utils': 8.65.0([email protected])
+ '@typescript-eslint/types': 8.65.0
+ debug: 4.4.3([email protected])
+ typescript: 5.9.3
+ transitivePeerDependencies:
+ - supports-color
+
dependencies:
'@typescript-eslint/tsconfig-utils': 8.65.0([email protected])
@@ -8813,24 +10097,55 @@ snapshots:
'@typescript-eslint/types': 8.65.0
'@typescript-eslint/visitor-keys': 8.65.0
+ '@typescript-eslint/[email protected]([email protected])':
+ dependencies:
+ typescript: 5.9.3
+
'@typescript-eslint/[email protected]([email protected])':
dependencies:
typescript: 6.0.3
dependencies:
'@typescript-eslint/types': 8.65.0
'@typescript-eslint/typescript-estree': 8.65.0([email protected])([email protected])
debug: 4.4.3([email protected])
ts-api-utils: 2.5.0([email protected])
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
+ dependencies:
+ '@typescript-eslint/types': 8.65.0
+ '@typescript-eslint/typescript-estree': 8.65.0([email protected])([email protected])
+ debug: 4.4.3([email protected])
+ ts-api-utils: 2.5.0([email protected])
+ typescript: 5.9.3
+ transitivePeerDependencies:
+ - supports-color
+
'@typescript-eslint/[email protected]': {}
+ dependencies:
+ '@typescript-eslint/project-service': 8.65.0([email protected])([email protected])
+ '@typescript-eslint/tsconfig-utils': 8.65.0([email protected])
+ '@typescript-eslint/types': 8.65.0
+ '@typescript-eslint/visitor-keys': 8.65.0
+ debug: 4.4.3([email protected])
+ minimatch: 10.2.5
+ semver: 7.8.5
+ tinyglobby: 0.2.17
+ ts-api-utils: 2.5.0([email protected])
+ typescript: 5.9.3
+ transitivePeerDependencies:
+ - supports-color
+
dependencies:
'@typescript-eslint/project-service': 8.65.0([email protected])([email protected])
@@ -8846,17 +10161,28 @@ snapshots:
transitivePeerDependencies:
- supports-color
dependencies:
- '@eslint-community/eslint-utils': 4.10.1([email protected]([email protected])([email protected]))
+ '@eslint-community/eslint-utils': 4.10.1([email protected]([email protected])([email protected]))
'@typescript-eslint/scope-manager': 8.65.0
'@typescript-eslint/types': 8.65.0
'@typescript-eslint/typescript-estree': 8.65.0([email protected])([email protected])
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
+ dependencies:
+ '@eslint-community/eslint-utils': 4.10.1([email protected]([email protected])([email protected]))
+ '@typescript-eslint/scope-manager': 8.65.0
+ '@typescript-eslint/types': 8.65.0
+ '@typescript-eslint/typescript-estree': 8.65.0([email protected])([email protected])
+ typescript: 5.9.3
+ transitivePeerDependencies:
+ - supports-color
+
'@typescript-eslint/[email protected]':
dependencies:
'@typescript-eslint/types': 8.65.0
@@ -8926,7 +10252,7 @@ snapshots:
'@vercel/[email protected]': {}
dependencies:
'@babel/core': 7.29.7([email protected])
'@babel/plugin-transform-react-jsx-self': 7.29.7(@babel/[email protected]([email protected]))
@@ -8934,10 +10260,65 @@ snapshots:
'@rolldown/pluginutils': 1.0.0-beta.27
'@types/babel__core': 7.20.5
react-refresh: 0.17.0
transitivePeerDependencies:
- supports-color
+ dependencies:
+ '@bcoe/v8-coverage': 1.0.2
+ '@vitest/utils': 4.1.10
+ ast-v8-to-istanbul: 1.0.5
+ istanbul-lib-coverage: 3.2.2
+ istanbul-lib-report: 3.0.1
+ istanbul-reports: 3.2.0
+ magicast: 0.5.4
+ obug: 2.1.4
+ std-env: 4.2.0
+ tinyrainbow: 3.1.1
+
+ '@vitest/[email protected]':
+ dependencies:
+ '@standard-schema/spec': 1.1.0
+ '@types/chai': 5.2.3
+ '@vitest/spy': 4.1.10
+ '@vitest/utils': 4.1.10
+ chai: 6.2.2
+ tinyrainbow: 3.1.1
+
+ dependencies:
+ '@vitest/spy': 4.1.10
+ estree-walker: 3.0.3
+ magic-string: 0.30.21
+ optionalDependencies:
+
+ '@vitest/[email protected]':
+ dependencies:
+ tinyrainbow: 3.1.1
+
+ '@vitest/[email protected]':
+ dependencies:
+ '@vitest/utils': 4.1.10
+ pathe: 2.0.3
+
+ '@vitest/[email protected]':
+ dependencies:
+ '@vitest/pretty-format': 4.1.10
+ '@vitest/utils': 4.1.10
+ magic-string: 0.30.21
+ pathe: 2.0.3
+
+ '@vitest/[email protected]': {}
+
+ '@vitest/[email protected]':
+ dependencies:
+ '@vitest/pretty-format': 4.1.10
+ convert-source-map: 2.0.0
+ tinyrainbow: 3.1.1
+
'@workflow/[email protected]': {}
@@ -8957,6 +10338,8 @@ snapshots:
transitivePeerDependencies:
- supports-color
+
dependencies:
'@ai-sdk/gateway': 4.0.40([email protected])
@@ -9013,10 +10396,20 @@ snapshots:
dependencies:
sprintf-js: 1.0.3
+
dependencies:
tslib: 2.8.1
+ dependencies:
+ dequal: 2.0.3
+
+
+
dependencies:
assistant-stream: 0.3.31([email protected](@opentelemetry/[email protected]))
@@ -9040,6 +10433,12 @@ snapshots:
optionalDependencies:
redis: 5.12.1(@opentelemetry/[email protected])
+ dependencies:
+ '@jridgewell/trace-mapping': 0.3.31
+ estree-walker: 3.0.3
+ js-tokens: 10.0.0
+
@@ -9213,6 +10612,8 @@ snapshots:
+
dependencies:
ansi-styles: 4.3.0
@@ -9332,6 +10733,15 @@ snapshots:
yaml: 1.10.3
optional: true
+ dependencies:
+ import-fresh: 3.3.1
+ js-yaml: 4.3.1
+ parse-json: 5.2.0
+ path-type: 4.0.0
+ optionalDependencies:
+ typescript: 5.9.3
+
dependencies:
'@jest/types': 29.6.3
@@ -9353,6 +10763,13 @@ snapshots:
shebang-command: 2.0.0
which: 2.0.2
+
+ dependencies:
+ '@asamuzakjp/css-color': 3.2.0
+ rrweb-cssom: 0.8.0
+
@@ -9393,6 +10810,11 @@ snapshots:
+ dependencies:
+ whatwg-mimetype: 4.0.0
+ whatwg-url: 14.2.0
+
@@ -9405,6 +10827,8 @@ snapshots:
+
dependencies:
character-entities: 2.0.2
@@ -9423,6 +10847,10 @@ snapshots:
+
+
@@ -9433,6 +10861,10 @@ snapshots:
+
+
dependencies:
'@babel/runtime': 7.29.7
@@ -9442,6 +10874,11 @@ snapshots:
optionalDependencies:
'@types/trusted-types': 2.0.7
+ dependencies:
+ no-case: 3.0.4
+ tslib: 2.8.1
+
@@ -9468,6 +10905,13 @@ snapshots:
+ dependencies:
+ graceful-fs: 4.2.11
+ tapable: 2.3.3
+
+
@@ -9499,6 +10943,15 @@ snapshots:
+ dependencies:
+ '@svgr/core': 8.1.0([email protected])([email protected])
+ esbuild: 0.25.12
+ transitivePeerDependencies:
+ - supports-color
+ - typescript
+
optionalDependencies:
'@esbuild/aix-ppc64': 0.25.12
@@ -9596,105 +11049,116 @@ snapshots:
dependencies:
'@typescript-eslint/types': 8.65.0
compare-versions: 6.1.1
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
+ dependencies:
+ '@babel/core': 7.29.7([email protected])
+ '@babel/parser': 7.29.7
+ hermes-parser: 0.25.1
+ zod: 3.25.76
+ zod-validation-error: 4.0.2([email protected])
+ transitivePeerDependencies:
+ - supports-color
+
dependencies:
'@babel/core': 7.29.7([email protected])
'@babel/parser': 7.29.7
hermes-parser: 0.25.1
zod: 3.25.76
zod-validation-error: 4.0.2([email protected])
transitivePeerDependencies:
- supports-color
dependencies:
'@typescript-eslint/types': 8.65.0
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
dependencies:
'@typescript-eslint/types': 8.65.0
ts-pattern: 5.9.0
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
dependencies:
'@typescript-eslint/types': 8.65.0
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
dependencies:
'@typescript-eslint/types': 8.65.0
birecord: 0.1.2
ts-pattern: 5.9.0
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
dependencies:
'@typescript-eslint/scope-manager': 8.65.0
'@typescript-eslint/types': 8.65.0
'@typescript-eslint/typescript-estree': 8.65.0([email protected])([email protected])
compare-versions: 6.1.1
string-ts: 2.3.1
ts-api-utils: 2.5.0([email protected])
ts-pattern: 5.9.0
@@ -9702,6 +11166,11 @@ snapshots:
transitivePeerDependencies:
- supports-color
+ dependencies:
+ esrecurse: 4.3.0
+ estraverse: 5.3.0
+
dependencies:
'@types/esrecurse': 4.3.1
@@ -9711,11 +11180,13 @@ snapshots:
+
dependencies:
- '@eslint-community/eslint-utils': 4.10.1([email protected]([email protected])([email protected]))
+ '@eslint-community/eslint-utils': 4.10.1([email protected]([email protected])([email protected]))
'@eslint-community/regexpp': 4.12.2
'@eslint/config-array': 0.23.5([email protected])
'@eslint/config-helpers': 0.6.0
@@ -9746,10 +11217,57 @@ snapshots:
natural-compare: 1.4.0
optionator: 0.9.4
optionalDependencies:
- jiti: 1.21.7
+ jiti: 2.7.0
+ transitivePeerDependencies:
+ - supports-color
+
+ dependencies:
+ '@eslint-community/eslint-utils': 4.10.1([email protected]([email protected])([email protected]))
+ '@eslint-community/regexpp': 4.12.2
+ '@eslint/config-array': 0.21.2([email protected])
+ '@eslint/config-helpers': 0.4.2
+ '@eslint/core': 0.17.0
+ '@eslint/eslintrc': 3.3.6([email protected])
+ '@eslint/js': 9.39.5
+ '@eslint/plugin-kit': 0.4.1
+ '@humanfs/node': 0.16.8
+ '@humanwhocodes/module-importer': 1.0.1
+ '@humanwhocodes/retry': 0.4.3
+ '@types/estree': 1.0.9
+ ajv: 6.15.0
+ chalk: 4.1.2
+ cross-spawn: 7.0.6
+ debug: 4.4.3([email protected])
+ escape-string-regexp: 4.0.0
+ eslint-scope: 8.4.0
+ eslint-visitor-keys: 4.2.1
+ espree: 10.4.0
+ esquery: 1.7.0
+ esutils: 2.0.3
+ fast-deep-equal: 3.1.3
+ file-entry-cache: 8.0.0
+ find-up: 5.0.0
+ glob-parent: 6.0.2
+ ignore: 5.3.2
+ imurmurhash: 0.1.4
+ is-glob: 4.0.3
+ json-stable-stringify-without-jsonify: 1.0.1
+ lodash.merge: 4.6.2
+ minimatch: 3.1.5
+ natural-compare: 1.4.0
+ optionator: 0.9.4
+ optionalDependencies:
+ jiti: 2.7.0
transitivePeerDependencies:
- supports-color
+ dependencies:
+ acorn: 8.17.0
+ acorn-jsx: 5.3.2([email protected])
+ eslint-visitor-keys: 4.2.1
+
dependencies:
acorn: 8.17.0
@@ -9772,6 +11290,10 @@ snapshots:
+ dependencies:
+ '@types/estree': 1.0.9
+
@@ -9806,6 +11328,8 @@ snapshots:
dependencies:
homedir-polyfill: 1.0.3
+
dependencies:
'@jest/expect-utils': 29.7.0
@@ -9994,6 +11518,8 @@ snapshots:
+
dependencies:
is-glob: 4.0.3
@@ -10011,6 +11537,10 @@ snapshots:
once: 1.4.0
path-is-absolute: 1.0.1
+
+
@@ -10123,6 +11653,10 @@ snapshots:
+ dependencies:
+ whatwg-encoding: 3.1.1
+
@@ -10135,6 +11669,13 @@ snapshots:
statuses: 2.0.2
toidentifier: 1.0.1
+ dependencies:
+ agent-base: 7.1.4
+ debug: 4.4.3([email protected])
+ transitivePeerDependencies:
+ - supports-color
+
dependencies:
agent-base: 6.0.2([email protected])
@@ -10142,10 +11683,21 @@ snapshots:
transitivePeerDependencies:
- supports-color
+ dependencies:
+ agent-base: 7.1.4
+ debug: 4.4.3([email protected])
+ transitivePeerDependencies:
+ - supports-color
+
+ dependencies:
+ safer-buffer: 2.1.2
+
dependencies:
safer-buffer: 2.1.2
@@ -10160,7 +11712,6 @@ snapshots:
dependencies:
parent-module: 1.0.1
resolve-from: 4.0.0
- optional: true
dependencies:
@@ -10175,6 +11726,8 @@ snapshots:
+
dependencies:
once: 1.4.0
@@ -10225,6 +11778,8 @@ snapshots:
+
@@ -10588,13 +12143,14 @@ snapshots:
- supports-color
- ts-node
- optional: true
+
@@ -10602,6 +12158,38 @@ snapshots:
argparse: 1.0.10
esprima: 4.0.1
+ dependencies:
+ argparse: 2.0.1
+
+ dependencies:
+ cssstyle: 4.6.0
+ data-urls: 5.0.0
+ decimal.js: 10.6.0
+ form-data: 4.0.6
+ html-encoding-sniffer: 4.0.0
+ http-proxy-agent: 7.0.2([email protected])
+ https-proxy-agent: 7.0.6([email protected])
+ is-potential-custom-element-name: 1.0.1
+ nwsapi: 2.2.24
+ parse5: 7.3.0
+ rrweb-cssom: 0.7.1
+ saxes: 6.0.0
+ symbol-tree: 3.2.4
+ tough-cookie: 4.1.4
+ w3c-xmlserializer: 5.0.0
+ webidl-conversions: 7.0.0
+ whatwg-encoding: 3.1.1
+ whatwg-mimetype: 4.0.0
+ whatwg-url: 14.2.0
+ ws: 8.21.1
+ xml-name-validator: 5.0.0
+ transitivePeerDependencies:
+ - bufferutil
+ - supports-color
+ - utf-8-validate
+
@@ -10643,6 +12231,55 @@ snapshots:
prelude-ls: 1.2.1
type-check: 0.4.0
+ optional: true
+
+ optional: true
+
+ optional: true
+
+ optional: true
+
+ optional: true
+
+ optional: true
+
+ optional: true
+
+ optional: true
+
+ optional: true
+
+ optional: true
+
+ optional: true
+
+ dependencies:
+ detect-libc: 2.1.2
+ optionalDependencies:
+ lightningcss-android-arm64: 1.32.0
+ lightningcss-darwin-arm64: 1.32.0
+ lightningcss-darwin-x64: 1.32.0
+ lightningcss-freebsd-x64: 1.32.0
+ lightningcss-linux-arm-gnueabihf: 1.32.0
+ lightningcss-linux-arm64-gnu: 1.32.0
+ lightningcss-linux-arm64-musl: 1.32.0
+ lightningcss-linux-x64-gnu: 1.32.0
+ lightningcss-linux-x64-musl: 1.32.0
+ lightningcss-win32-arm64-msvc: 1.32.0
+ lightningcss-win32-x64-msvc: 1.32.0
+
@@ -10679,6 +12316,8 @@ snapshots:
+
@@ -10706,11 +12345,17 @@ snapshots:
dependencies:
js-tokens: 4.0.0
+ dependencies:
+ tslib: 2.8.1
+
dependencies:
fault: 1.0.4
highlight.js: 10.7.3
+
dependencies:
yallist: 3.1.1
@@ -10719,10 +12364,18 @@ snapshots:
dependencies:
react: 19.2.8
+
dependencies:
'@jridgewell/sourcemap-codec': 1.5.5
+ dependencies:
+ '@babel/parser': 7.29.7
+ '@babel/types': 7.29.7
+ source-map-js: 1.2.1
+
dependencies:
semver: 7.8.5
@@ -11137,6 +12790,8 @@ snapshots:
+
dependencies:
brace-expansion: 5.0.7
@@ -11167,6 +12822,8 @@ snapshots:
dompurify: 3.4.8
marked: 14.0.0
+
@@ -11183,6 +12840,13 @@ snapshots:
+ dependencies:
+ lower-case: 2.0.2
+ tslib: 2.8.1
+
+
@@ -11202,10 +12866,14 @@ snapshots:
dependencies:
path-key: 3.1.1
+
+
dependencies:
ee-first: 1.1.1
@@ -11267,7 +12935,6 @@ snapshots:
dependencies:
callsites: 3.1.0
- optional: true
dependencies:
@@ -11304,8 +12971,7 @@ snapshots:
- optional: true
@@ -11366,11 +13032,11 @@ snapshots:
dependencies:
lilconfig: 3.1.3
optionalDependencies:
- jiti: 1.21.7
+ jiti: 2.7.0
postcss: 8.5.22
tsx: 4.23.1
yaml: 2.9.0
@@ -11400,6 +13066,12 @@ snapshots:
+ dependencies:
+ ansi-regex: 5.0.1
+ ansi-styles: 5.2.0
+ react-is: 17.0.2
+
dependencies:
'@jest/schemas': 29.6.3
@@ -11457,6 +13129,10 @@ snapshots:
+ dependencies:
+ punycode: 2.3.1
+
@@ -11466,6 +13142,8 @@ snapshots:
es-define-property: 1.0.1
side-channel: 1.1.1
+
@@ -11555,6 +13233,8 @@ snapshots:
+
@@ -11667,6 +13347,11 @@ snapshots:
tiny-invariant: 1.3.3
victory-vendor: 36.9.2
+ dependencies:
+ indent-string: 4.0.0
+ strip-indent: 3.0.0
+
dependencies:
'@redis/bloom': 5.12.1(@redis/[email protected](@opentelemetry/[email protected]))
@@ -11763,12 +13448,13 @@ snapshots:
transitivePeerDependencies:
- supports-color
+
dependencies:
resolve-from: 5.0.0
- optional: true
@@ -11830,6 +13516,10 @@ snapshots:
transitivePeerDependencies:
- supports-color
+
+
dependencies:
queue-microtask: 1.2.3
@@ -11842,6 +13532,10 @@ snapshots:
+ dependencies:
+ xmlchars: 2.2.0
+
@@ -11913,6 +13607,8 @@ snapshots:
side-channel-map: 1.0.1
side-channel-weakmap: 1.0.2
+
@@ -11935,6 +13631,11 @@ snapshots:
ansi-styles: 6.2.3
is-fullwidth-code-point: 5.1.0
+ dependencies:
+ dot-case: 3.0.4
+ tslib: 2.8.1
+
@@ -11958,8 +13659,12 @@ snapshots:
dependencies:
escape-string-regexp: 2.0.0
+
+
dependencies:
inherits: 2.0.4
@@ -12014,6 +13719,10 @@ snapshots:
+ dependencies:
+ min-indent: 1.0.1
+
@@ -12044,10 +13753,16 @@ snapshots:
+
+
+
@@ -12076,6 +13791,8 @@ snapshots:
+
@@ -12085,6 +13802,8 @@ snapshots:
fdir: 6.5.0([email protected])
picomatch: 4.0.5
+
@@ -12093,6 +13812,17 @@ snapshots:
+ dependencies:
+ psl: 1.15.0
+ punycode: 2.3.1
+ universalify: 0.2.0
+ url-parse: 1.5.10
+
+ dependencies:
+ punycode: 2.3.1
+
@@ -12103,6 +13833,10 @@ snapshots:
+ dependencies:
+ typescript: 5.9.3
+
dependencies:
typescript: 6.0.3
@@ -12113,7 +13847,7 @@ snapshots:
dependencies:
bundle-require: 5.1.0([email protected])
cac: 6.7.14
@@ -12124,7 +13858,36 @@ snapshots:
fix-dts-default-cjs-exports: 1.0.1
joycon: 3.1.1
picocolors: 1.1.1
+ resolve-from: 5.0.0
+ rollup: 4.62.2
+ source-map: 0.7.6
+ sucrase: 3.35.1
+ tinyexec: 0.3.2
+ tinyglobby: 0.2.17
+ tree-kill: 1.2.2
+ optionalDependencies:
+ '@swc/core': 1.15.46
+ postcss: 8.5.22
+ typescript: 5.9.3
+ transitivePeerDependencies:
+ - jiti
+ - supports-color
+ - tsx
+ - yaml
+
+ dependencies:
+ bundle-require: 5.1.0([email protected])
+ cac: 6.7.14
+ chokidar: 4.0.3
+ consola: 3.4.2
+ debug: 4.4.3([email protected])
+ esbuild: 0.27.7
+ fix-dts-default-cjs-exports: 1.0.1
+ joycon: 3.1.1
+ picocolors: 1.1.1
resolve-from: 5.0.0
rollup: 4.62.2
source-map: 0.7.6
@@ -12164,17 +13927,28 @@ snapshots:
media-typer: 1.1.0
mime-types: 3.0.2
dependencies:
'@typescript-eslint/typescript-estree': 8.65.0([email protected])([email protected])
typescript: 6.0.3
transitivePeerDependencies:
- supports-color
+ dependencies:
+ '@typescript-eslint/typescript-estree': 8.65.0([email protected])([email protected])
+ typescript: 5.9.3
+ transitivePeerDependencies:
+ - supports-color
+
@@ -12206,6 +13980,8 @@ snapshots:
+
@@ -12255,6 +14031,8 @@ snapshots:
unist-util-is: 6.0.1
unist-util-visit-parents: 6.0.2
+
@@ -12267,6 +14045,11 @@ snapshots:
dependencies:
punycode: 2.3.1
+ dependencies:
+ querystringify: 2.2.0
+ requires-port: 1.0.0
+
dependencies:
react: 19.2.8
@@ -12363,7 +14146,23 @@ snapshots:
dependencies:
monaco-editor: 0.52.2
+ dependencies:
+ esbuild: 0.25.12
+ fdir: 6.5.0([email protected])
+ picomatch: 4.0.5
+ postcss: 8.5.22
+ rollup: 4.62.2
+ tinyglobby: 0.2.17
+ optionalDependencies:
+ '@types/node': 20.19.43
+ fsevents: 2.3.3
+ jiti: 2.7.0
+ lightningcss: 1.32.0
+ tsx: 4.23.1
+ yaml: 2.9.0
+
dependencies:
esbuild: 0.25.12
fdir: 6.5.0([email protected])
@@ -12374,20 +14173,73 @@ snapshots:
optionalDependencies:
'@types/node': 24.13.3
fsevents: 2.3.3
- jiti: 1.21.7
+ jiti: 2.7.0
+ lightningcss: 1.32.0
tsx: 4.23.1
yaml: 2.9.0
+ dependencies:
+ '@vitest/expect': 4.1.10
+ '@vitest/pretty-format': 4.1.10
+ '@vitest/runner': 4.1.10
+ '@vitest/snapshot': 4.1.10
+ '@vitest/spy': 4.1.10
+ '@vitest/utils': 4.1.10
+ es-module-lexer: 2.3.1
+ expect-type: 1.4.0
+ magic-string: 0.30.21
+ obug: 2.1.4
+ pathe: 2.0.3
+ picomatch: 4.0.5
+ std-env: 4.2.0
+ tinybench: 2.9.0
+ tinyexec: 1.2.4
+ tinyglobby: 0.2.17
+ tinyrainbow: 3.1.1
+ why-is-node-running: 2.3.0
+ optionalDependencies:
+ '@opentelemetry/api': 1.9.1
+ '@types/node': 20.19.43
+ '@vitest/coverage-v8': 4.1.10([email protected])
+ jsdom: 24.1.3([email protected])
+ transitivePeerDependencies:
+ - msw
+
+ dependencies:
+ xml-name-validator: 5.0.0
+
dependencies:
makeerror: 1.0.12
+
+ dependencies:
+ iconv-lite: 0.6.3
+
+
+ dependencies:
+ tr46: 5.1.1
+ webidl-conversions: 7.0.0
+
dependencies:
isexe: 2.0.0
+ dependencies:
+ siginfo: 2.0.0
+ stackback: 0.0.2
+
dependencies:
logform: 2.7.0
@@ -12431,6 +14283,10 @@ snapshots:
+
+
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index dc0fac69b..7bd80657d 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -7,12 +7,13 @@ minimumReleaseAge: 0
trustLockfile: true
confirmModulesPurge: false
allowBuilds:
+ '@parcel/watcher': true
'@swc/core': true
better-sqlite3: true
esbuild: true
protobufjs: true
-# Silence peer mismatches between agent-ui-sdk peers and the versions we pin.
+# Silence peer mismatches between trueforge-ui peers and the versions we pin.
peerDependencyRules:
allowedVersions:
'@truefoundry/assistant-ui-runtime': '0.1.6-rc.2'
@@ -21,5 +22,7 @@ peerDependencyRules:
overrides:
'@assistant-ui/store': '0.2.21'
'@assistant-ui/core': '0.2.22'
+ '@assistant-ui/tap': '0.9.5'
+ zustand: '^5.0.14'
# [email protected] ships accidental .claude/ files that break installs under macOS sandbox.
resolve: '1.22.11'