Skip to content

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

feat(ui): remember draft composer preferences across new chats (#286)

Govinda Vashishtha2f08a999ee3b
diff --git a/.changeset/draft-spec-preferences.md b/.changeset/draft-spec-preferences.md
new file mode 100644
index 000000000..7b1d1f05e
--- /dev/null
+++ b/.changeset/draft-spec-preferences.md
@@ -0,0 +1,5 @@
+---
+'@truefoundry/trueforge-ui': minor
+---
+
+Remember plain-draft composer choices (model, skills, MCP connectors, config) across New Chat and reloads via localStorage. Edit-flow and immutable library agents are unchanged. `TrueforgeUI` `layout` is optional and defaults to `"sidebar"`.
diff --git a/packages/trueforge-ui-sdk/CHANGELOG.md b/packages/trueforge-ui-sdk/CHANGELOG.md
index b01e766c4..7befaeea5 100644
--- a/packages/trueforge-ui-sdk/CHANGELOG.md
+++ b/packages/trueforge-ui-sdk/CHANGELOG.md
@@ -52,6 +52,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
+- **Draft composer preferences** — plain-draft model, skills, MCP connectors, and
+ config choices are remembered (in-memory + `localStorage`) and seed the next
+ New Chat after reload. Stale catalog entries are pruned once catalogs load.
+ Edit-flow (`agentId` set) and immutable library agents are unchanged.
+- **Optional `layout`** — `<TrueforgeUI />` `layout` prop defaults to `"sidebar"`.
- **`type: "trueforge"` built-in server** — `<TrueforgeUI server={{ type: 'trueforge', baseUrl?, token?, fetch? }} />`
resolves a full Harness `AgentUIServer` via
`@truefoundry/trueforge-ui/plugins/trueforge-agent-server-adapter`
diff --git a/packages/trueforge-ui-sdk/src/atoms/draft/DraftCatalogProvider.tsx b/packages/trueforge-ui-sdk/src/atoms/draft/DraftCatalogProvider.tsx
index 14da9171a..7afd2aab4 100644
--- a/packages/trueforge-ui-sdk/src/atoms/draft/DraftCatalogProvider.tsx
+++ b/packages/trueforge-ui-sdk/src/atoms/draft/DraftCatalogProvider.tsx
@@ -10,6 +10,7 @@ type DraftCatalogValue = {
models: ModelSelection[];
skills: AgentSkill[];
connectors: ConnectorState[];
+ loaded: boolean;
loading: boolean;
error: string | null;
/** Kick off catalog fetch (idempotent). Call when a picker opens. */
@@ -43,6 +44,7 @@ function DraftCatalogStore({ server, children }: { server: AgentUIServer | null;
const [models, setModels] = useState<ModelSelection[]>([]);
const [skills, setSkills] = useState<AgentSkill[]>([]);
const [connectors, setConnectors] = useState<ConnectorState[]>([]);
+ const [completedEpoch, setCompletedEpoch] = useState<number | null>(null);
const [loading, setLoading] = useState(false);
const [error, setError] = useState<string | null>(null);
@@ -96,16 +98,20 @@ function DraftCatalogStore({ server, children }: { server: AgentUIServer | null;
setError(errors[0] ?? null);
})
.finally(() => {
- if (!cancelled) setLoading(false);
+ if (!cancelled) {
+ setCompletedEpoch(requestEpoch);
+ setLoading(false);
+ }
});
return () => {
cancelled = true;
};
}, [requestEpoch, server]);
+ const loaded = requestEpoch !== null && completedEpoch === requestEpoch;
const value = useMemo(
- () => ({ server, models, skills, connectors, loading, error, ensureLoaded, refresh, refreshConnectors }),
- [server, models, skills, connectors, loading, error, ensureLoaded, refresh, refreshConnectors],
+ () => ({ server, models, skills, connectors, loaded, loading, error, ensureLoaded, refresh, refreshConnectors }),
+ [server, models, skills, connectors, loaded, loading, error, ensureLoaded, refresh, refreshConnectors],
);
return <DraftCatalogContext.Provider value={value}>{children}</DraftCatalogContext.Provider>;
@@ -118,6 +124,7 @@ export function useDraftCatalog(): DraftCatalogValue {
models: [],
skills: [],
connectors: [],
+ loaded: false,
loading: false,
error: null,
ensureLoaded: IDLE_ENSURE,
diff --git a/packages/trueforge-ui-sdk/src/atoms/draft/DraftSpecPreferenceBridge.tsx b/packages/trueforge-ui-sdk/src/atoms/draft/DraftSpecPreferenceBridge.tsx
new file mode 100644
index 000000000..8da238b89
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/draft/DraftSpecPreferenceBridge.tsx
@@ -0,0 +1,121 @@
+'use client';
+
+import { useTrueFoundryAgentSpec, useTrueFoundryUpdateAgentSpec } from '@truefoundry/assistant-ui-runtime';
+import { useEffect } from 'react';
+
+import { useServerCapabilities } from '../../server/ServerContext.js';
+import { useShellMode } from '../../server/ShellModeContext.js';
+import type { AgentSkill, AgentSpec, ConnectorState, ModelSelection } from '../../server/types.js';
+import { useDraftCatalog } from './DraftCatalogProvider.js';
+import { modelPatchWithReasoningEffort } from './reasoningEffort.js';
+
+function mountName(mount: object): string | null {
+ const name = Reflect.get(mount, 'name');
+ return typeof name === 'string' ? name : null;
+}
+
+function filterMounts<T extends object>(mounts: T[] | undefined, availableNames: Set<string>): T[] | undefined {
+ if (mounts === undefined) return undefined;
+ const filtered = mounts.filter(mount => {
+ const name = mountName(mount);
+ return name !== null && availableNames.has(name);
+ });
+ return filtered.length === mounts.length ? mounts : filtered;
+}
+
+export function reconcileDraftSpecPreferences({
+ agentSpec,
+ models,
+ skills,
+ connectors,
+ skillsEnabled,
+}: {
+ agentSpec: AgentSpec;
+ models: ModelSelection[];
+ skills: AgentSkill[];
+ connectors: ConnectorState[];
+ skillsEnabled: boolean | undefined;
+}): Partial<AgentSpec> {
+ const update: Partial<AgentSpec> = {};
+ const selectedModel = agentSpec.model.name.trim();
+ if (!models.some(model => model.name === selectedModel)) {
+ const fallback = models[0];
+ if (fallback !== undefined) {
+ update.model = modelPatchWithReasoningEffort(
+ fallback.name,
+ agentSpec.model.params,
+ fallback.properties.reasoningEfforts,
+ );
+ }
+ }
+
+ const nextMcpServers = filterMounts(agentSpec.mcpServers, new Set(connectors.map(connector => connector.name)));
+ if (nextMcpServers !== agentSpec.mcpServers) {
+ update.mcpServers = nextMcpServers;
+ }
+
+ if (skillsEnabled === false) {
+ // Only clear when there is something to clear — a fresh `[]` each call would
+ // fail reference equality and loop `updateAgentSpec` forever.
+ if (agentSpec.skills !== undefined && agentSpec.skills.length > 0) {
+ update.skills = [];
+ }
+ } else {
+ const nextSkills = filterMounts(agentSpec.skills, new Set(skills.map(skill => skill.name)));
+ if (nextSkills !== agentSpec.skills) {
+ update.skills = nextSkills;
+ }
+ }
+
+ return update;
+}
+
+/**
+ * Mirrors plain-draft composer choices into the shell seed and removes catalog
+ * entries that disappeared since those choices were stored.
+ */
+export function DraftSpecPreferenceBridge() {
+ const { mode, pendingSessionId, rememberDraftSpec } = useShellMode();
+ const { agentSpec } = useTrueFoundryAgentSpec();
+ const updateAgentSpec = useTrueFoundryUpdateAgentSpec();
+ const capabilities = useServerCapabilities();
+ const { models, skills, connectors, loaded, error, ensureLoaded } = useDraftCatalog();
+ const isPlainDraft = mode.status === 'active' && mode.isMutable && mode.agentId == null && pendingSessionId == null;
+
+ useEffect(() => {
+ if (isPlainDraft) ensureLoaded();
+ }, [ensureLoaded, isPlainDraft]);
+
+ useEffect(() => {
+ if (isPlainDraft && agentSpec != null) {
+ rememberDraftSpec(agentSpec);
+ }
+ }, [agentSpec, isPlainDraft, rememberDraftSpec]);
+
+ useEffect(() => {
+ if (!isPlainDraft || agentSpec == null || updateAgentSpec == null || !loaded || error != null) return;
+
+ const update = reconcileDraftSpecPreferences({
+ agentSpec,
+ models,
+ skills,
+ connectors,
+ skillsEnabled: capabilities?.skill.enabled,
+ });
+ if (Object.keys(update).length > 0) {
+ updateAgentSpec(update);
+ }
+ }, [
+ agentSpec,
+ capabilities?.skill.enabled,
+ connectors,
+ error,
+ isPlainDraft,
+ loaded,
+ models,
+ skills,
+ updateAgentSpec,
+ ]);
+
+ return null;
+}
diff --git a/packages/trueforge-ui-sdk/src/containers/TrueforgeUI.tsx b/packages/trueforge-ui-sdk/src/containers/TrueforgeUI.tsx
index 7826477e1..8af97b1f0 100644
--- a/packages/trueforge-ui-sdk/src/containers/TrueforgeUI.tsx
+++ b/packages/trueforge-ui-sdk/src/containers/TrueforgeUI.tsx
@@ -4,6 +4,7 @@ import type { TrueFoundryAgentConfig, UseTrueFoundryAgentRuntimeOptions } from '
import { lazy, Suspense, useMemo, type ReactNode } from 'react';
import { DraftCatalogProvider } from '../atoms/draft/DraftCatalogProvider.js';
+import { DraftSpecPreferenceBridge } from '../atoms/draft/DraftSpecPreferenceBridge.js';
import { cn } from '../atoms/lib/cn.js';
import { Spinner } from '../atoms/primitives/Spinner.js';
import { ServerProvider } from '../server/ServerContext.js';
@@ -30,7 +31,8 @@ type RuntimeAdapters = NonNullable<UseTrueFoundryAgentRuntimeOptions['adapters']
export type TrueforgeUIProps = {
server: TrueforgeServerConfig;
- layout: LayoutProp;
+ /** Built-in layout string or a custom layout component. Defaults to `"sidebar"`. */
+ layout?: LayoutProp;
overrides?: SlotOverrides;
theme?: ThemeConfig;
className?: string;
@@ -180,7 +182,10 @@ function ChatProviderFromShell({
listSessionsAgentId={listSessionsAgentId}
initialSessionId={pendingSessionId ?? hostInitialSessionId}
>
- <DraftCatalogProvider>{children}</DraftCatalogProvider>
+ <DraftCatalogProvider>
+ <DraftSpecPreferenceBridge />
+ {children}
+ </DraftCatalogProvider>
</TrueFoundryChatProvider>
);
}
@@ -205,7 +210,7 @@ export function TrueforgeUI(props: TrueforgeUIProps) {
function TrueforgeUIShell(props: TrueforgeUIProps) {
const {
- layout,
+ layout = 'sidebar',
overrides,
theme,
className,
diff --git a/packages/trueforge-ui-sdk/src/server/ShellModeContext.tsx b/packages/trueforge-ui-sdk/src/server/ShellModeContext.tsx
index a6ede8d8b..a7da3c6a0 100644
--- a/packages/trueforge-ui-sdk/src/server/ShellModeContext.tsx
+++ b/packages/trueforge-ui-sdk/src/server/ShellModeContext.tsx
@@ -2,6 +2,11 @@
import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, type ReactNode } from 'react';
+import {
+ readDraftSpecPreferences,
+ selectDraftSpecPreferences,
+ writeDraftSpecPreferences,
+} from './draftSpecPreferences.js';
import { useOptionalRefreshServerCapabilities, useServerCapabilities } from './ServerContext.js';
import type { AgentLibraryEntry, AgentSpec } from './types.js';
@@ -71,6 +76,8 @@ type ShellModeContextValue = {
selectAgent: (agentName: string) => void;
/** @deprecated Prefer `selectLibraryAgent({ isMutable: true, agentSpec })`. */
openDraft: () => void;
+ /** Remember plain-draft composer choices as the seed for future new chats. */
+ rememberDraftSpec: (agentSpec: AgentSpec) => void;
/**
* Open a history session, remounting when mutability/identity changes.
* Prefer explicit `isMutable` from the session row; when omitted, agentName
@@ -152,8 +159,10 @@ export function ShellModeProvider({
}) {
const capabilities = useServerCapabilities();
const refreshCapabilities = useOptionalRefreshServerCapabilities();
- const mutableSeedRef = useRef(mutableSeedFromConfig(agentConfig));
+ const rememberedSpecRef = useRef<AgentSpec | null>(readDraftSpecPreferences());
+ const mutableSeedRef = useRef(rememberedSpecRef.current ?? mutableSeedFromConfig(agentConfig));
if (
+ rememberedSpecRef.current == null &&
(agentConfig.mode === 'AgentComposer' || agentConfig.mode === 'AgentLibraryWithComposer') &&
agentConfig.defaultAgentSpec != null
) {
@@ -284,6 +293,13 @@ export function ShellModeProvider({
selectLibraryAgent({ isMutable: true, agentSpec: mutableSeedRef.current });
}, [isComposerEnabled, refreshCapabilities, selectLibraryAgent]);
+ const rememberDraftSpec = useCallback((agentSpec: AgentSpec) => {
+ const preferences = selectDraftSpecPreferences(agentSpec);
+ rememberedSpecRef.current = preferences;
+ mutableSeedRef.current = preferences;
+ writeDraftSpecPreferences(preferences);
+ }, []);
+
const openHistorySession = useCallback(
({
sessionId,
@@ -369,6 +385,7 @@ export function ShellModeProvider({
bindMutableAgent,
selectAgent,
openDraft,
+ rememberDraftSpec,
openHistorySession,
clearChat,
runtimeKey,
@@ -392,6 +409,7 @@ export function ShellModeProvider({
bindMutableAgent,
selectAgent,
openDraft,
+ rememberDraftSpec,
openHistorySession,
clearChat,
runtimeKey,
diff --git a/packages/trueforge-ui-sdk/src/server/draftSpecPreferences.ts b/packages/trueforge-ui-sdk/src/server/draftSpecPreferences.ts
new file mode 100644
index 000000000..5c4849e60
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/server/draftSpecPreferences.ts
@@ -0,0 +1,71 @@
+import type { AgentSpec } from './types.js';
+
+export const DRAFT_SPEC_PREFERENCES_STORAGE_KEY = 'tfy-aui-draft-spec-preferences';
+
+type StoredDraftSpecPreferences = {
+ version: 1;
+ spec: AgentSpec;
+};
+
+function isObject(value: unknown): value is object {
+ return typeof value === 'object' && value !== null;
+}
+
+function isMountList(value: unknown): boolean {
+ return Array.isArray(value) && value.every(isObject);
+}
+
+function isAgentSpec(value: unknown): value is AgentSpec {
+ if (!isObject(value)) return false;
+ const model = Reflect.get(value, 'model');
+ if (!isObject(model) || typeof Reflect.get(model, 'name') !== 'string') return false;
+
+ const params = Reflect.get(model, 'params');
+ if (params !== undefined && !isObject(params)) return false;
+
+ const skills = Reflect.get(value, 'skills');
+ if (skills !== undefined && !isMountList(skills)) return false;
+
+ const mcpServers = Reflect.get(value, 'mcpServers');
+ if (mcpServers !== undefined && !isMountList(mcpServers)) return false;
+
+ const config = Reflect.get(value, 'config');
+ return config === undefined || isObject(config);
+}
+
+function isStoredDraftSpecPreferences(value: unknown): value is StoredDraftSpecPreferences {
+ return isObject(value) && Reflect.get(value, 'version') === 1 && isAgentSpec(Reflect.get(value, 'spec'));
+}
+
+/** Keep only composer choices that should seed future new chats. */
+export function selectDraftSpecPreferences(spec: AgentSpec): AgentSpec {
+ return {
+ model: spec.model,
+ ...(spec.skills !== undefined ? { skills: spec.skills } : {}),
+ ...(spec.mcpServers !== undefined ? { mcpServers: spec.mcpServers } : {}),
+ ...(spec.config !== undefined ? { config: spec.config } : {}),
+ };
+}
+
+export function readDraftSpecPreferences(): AgentSpec | null {
+ if (typeof window === 'undefined') return null;
+ try {
+ const stored: unknown = JSON.parse(window.localStorage.getItem(DRAFT_SPEC_PREFERENCES_STORAGE_KEY) ?? 'null');
+ return isStoredDraftSpecPreferences(stored) ? stored.spec : null;
+ } catch {
+ return null;
+ }
+}
+
+export function writeDraftSpecPreferences(spec: AgentSpec): void {
+ if (typeof window === 'undefined') return;
+ try {
+ const stored: StoredDraftSpecPreferences = {
+ version: 1,
+ spec: selectDraftSpecPreferences(spec),
+ };
+ window.localStorage.setItem(DRAFT_SPEC_PREFERENCES_STORAGE_KEY, JSON.stringify(stored));
+ } catch {
+ // Storage can be unavailable or full; in-memory carry-over still works.
+ }
+}
diff --git a/packages/trueforge-ui-sdk/test/atoms/draft/DraftCatalogProvider.test.tsx b/packages/trueforge-ui-sdk/test/atoms/draft/DraftCatalogProvider.test.tsx
index 239ce7414..c1ced2870 100644
--- a/packages/trueforge-ui-sdk/test/atoms/draft/DraftCatalogProvider.test.tsx
+++ b/packages/trueforge-ui-sdk/test/atoms/draft/DraftCatalogProvider.test.tsx
@@ -3,6 +3,7 @@ import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
import { describe, expect, it, vi } from 'vitest';
import { DraftCatalogProvider, useDraftCatalog } from '@/atoms/draft/DraftCatalogProvider.js';
+import { reconcileDraftSpecPreferences } from '@/atoms/draft/DraftSpecPreferenceBridge.js';
import { ServerProvider } from '@/server/ServerContext.js';
import type { AgentSkill, ConnectorState, ModelSelection } from '@/server/types.js';
import { createMockAgentUIServer } from '../../server/mockServer.js';
@@ -56,6 +57,64 @@ function deferred<T>() {
}
describe('DraftCatalogProvider', () => {
+ it('prunes unavailable remembered choices and falls back to the live model catalog', () => {
+ const update = reconcileDraftSpecPreferences({
+ agentSpec: {
+ model: { name: 'removed/model' },
+ skills: [{ name: 'Available skill' }, { name: 'Removed skill' }],
+ mcpServers: [{ name: 'Available MCP' }, { name: 'Removed MCP' }],
+ },
+ models: [
+ {
+ id: 'live/model',
+ name: 'live/model',
+ provider: { name: 'Live' },
+ properties: { reasoningEfforts: ['none', 'low'] },
+ },
+ ],
+ skills: [{ id: 'available-skill', name: 'Available skill' }],
+ connectors: [{ id: 'available-mcp', name: 'Available MCP' }],
+ skillsEnabled: true,
+ });
+
+ expect(update).toEqual({
+ model: { name: 'live/model', params: { reasoningEffort: 'low' } },
+ skills: [{ name: 'Available skill' }],
+ mcpServers: [{ name: 'Available MCP' }],
+ });
+ });
+
+ it('clears remembered skills when skills are unavailable', () => {
+ const update = reconcileDraftSpecPreferences({
+ agentSpec: {
+ model: { name: 'live/model' },
+ skills: [{ name: 'Skill' }],
+ },
+ models: [],
+ skills: [{ id: 'skill', name: 'Skill' }],
+ connectors: [],
+ skillsEnabled: false,
+ });
+
+ expect(update.skills).toEqual([]);
+ });
+
+ it('does not re-clear an already empty skills list when skills are unavailable', () => {
+ const emptySkills: object[] = [];
+ const update = reconcileDraftSpecPreferences({
+ agentSpec: {
+ model: { name: 'live/model' },
+ skills: emptySkills,
+ },
+ models: [],
+ skills: [],
+ connectors: [],
+ skillsEnabled: false,
+ });
+
+ expect(update).toEqual({});
+ });
+
it('exposes an empty, idle catalog when used without a provider', () => {
render(<CatalogProbe />);
diff --git a/packages/trueforge-ui-sdk/test/server/ShellModeContext.test.tsx b/packages/trueforge-ui-sdk/test/server/ShellModeContext.test.tsx
index 19bfcb265..cf676eac7 100644
--- a/packages/trueforge-ui-sdk/test/server/ShellModeContext.test.tsx
+++ b/packages/trueforge-ui-sdk/test/server/ShellModeContext.test.tsx
@@ -1,8 +1,9 @@
// @vitest-environment jsdom
import { act, renderHook } from '@testing-library/react';
import type { ReactNode } from 'react';
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it } from 'vitest';
+import { DRAFT_SPEC_PREFERENCES_STORAGE_KEY } from '@/server/draftSpecPreferences.js';
import { ShellModeProvider, useOptionalShellMode, useShellMode, type AgentConfig } from '@/server/ShellModeContext.js';
function wrap(agentConfig?: AgentConfig, initialSettingsOpen?: boolean) {
@@ -16,6 +17,10 @@ function wrap(agentConfig?: AgentConfig, initialSettingsOpen?: boolean) {
}
describe('ShellModeProvider', () => {
+ beforeEach(() => {
+ window.localStorage.removeItem(DRAFT_SPEC_PREFERENCES_STORAGE_KEY);
+ });
+
it('requires a provider for useShellMode', () => {
expect(() => renderHook(() => useShellMode())).toThrow('useShellMode must be used within a ShellModeProvider.');
});
@@ -399,4 +404,62 @@ describe('ShellModeProvider', () => {
expect(result.current.mode.status).toBe('idle');
});
+
+ it('uses remembered plain-draft preferences for the next chat', () => {
+ const { result } = renderHook(() => useShellMode(), {
+ wrapper: wrap({
+ mode: 'AgentLibraryWithComposer',
+ defaultAgentSpec: { model: { name: 'default/model' } },
+ }),
+ });
+
+ act(() =>
+ result.current.rememberDraftSpec({
+ model: { name: 'chosen/model' },
+ skills: [{ name: 'Research' }],
+ mcpServers: [{ name: 'GitHub' }],
+ instructions: 'Do not retain this.',
+ }),
+ );
+ act(() => result.current.selectAgent('saved-agent'));
+ act(() => result.current.openDraft());
+
+ expect(result.current.mode).toMatchObject({
+ status: 'active',
+ isMutable: true,
+ agentSpec: {
+ model: { name: 'chosen/model' },
+ skills: [{ name: 'Research' }],
+ mcpServers: [{ name: 'GitHub' }],
+ },
+ });
+ if (result.current.mode.status !== 'active') throw new Error('expected active mode');
+ expect(result.current.mode.agentSpec).not.toHaveProperty('instructions');
+ });
+
+ it('hydrates remembered preferences on first paint', () => {
+ window.localStorage.setItem(
+ DRAFT_SPEC_PREFERENCES_STORAGE_KEY,
+ JSON.stringify({
+ version: 1,
+ spec: {
+ model: { name: 'remembered/model' },
+ config: { sandbox: { enabled: true } },
+ },
+ }),
+ );
+
+ const { result } = renderHook(() => useShellMode(), {
+ wrapper: wrap({
+ mode: 'AgentComposer',
+ defaultAgentSpec: { model: { name: 'default/model' } },
+ }),
+ });
+
+ expect(result.current.mode).toMatchObject({
+ status: 'active',
+ isMutable: true,
+ agentSpec: { model: { name: 'remembered/model' } },
+ });
+ });
});