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.mdnew file mode 100644index 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.mdindex 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.tsxindex 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.tsxnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsnew file mode 100644index 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.tsxindex 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.tsxindex 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 jsdomimport { 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' } },+ });+ });});