The open-source agent harness - the runtime layer that turns an LLM into a working agent.
bugfix: agent spec error when switching chats in chat history (#927)
harshil-2096b58c47e40128
diff --git a/.changeset/fix-draft-spec-immutable-sessions.md b/.changeset/fix-draft-spec-immutable-sessions.mdnew file mode 100644index 000000000..61b5f1de4--- /dev/null+++ b/.changeset/fix-draft-spec-immutable-sessions.md@@ -0,0 +1,5 @@+---+"@truefoundry/trueforge-assistant-ui-runtime": patch+---++Avoid throwing agentSpec error when switching chats or rendering immutable sessions in Chat History.diff --git a/packages/assistant-ui-runtime/src/draft/draftSessionBridge.ts b/packages/assistant-ui-runtime/src/draft/draftSessionBridge.tsindex 03fbf4ff0..ef9258bdb 100644--- a/packages/assistant-ui-runtime/src/draft/draftSessionBridge.ts+++ b/packages/assistant-ui-runtime/src/draft/draftSessionBridge.ts@@ -4,17 +4,16 @@ export const DRAFT_SESSION_LAST_UPDATED_AT_HEADER = 'x-tfy-session-last-updated-export interface DraftSessionBridge {syncAgentSpec: (draftSessionId: string, agentSpec: AgentSpec) => Promise<string>;- getDraftAgentSpec: (draftSessionId: string) => Promise<AgentSpec>;+ getDraftAgentSpec: (draftSessionId: string) => Promise<AgentSpec | null>;}export function createDraftSessionBridge(server: AgentChatServer): DraftSessionBridge {return {async getDraftAgentSpec(draftSessionId) {const session = await server.getSession({ sessionId: draftSessionId });- if (session.agentSpec == null) {- throw new Error(`Session ${draftSessionId} has no agentSpec (isMutable=${String(session.isMutable)}).`);- }- return session.agentSpec;+ // Sessions without an agentSpec (e.g. immutable/SDK chats) have no draft configuration.+ // Return null so callers gracefully fallback instead of crashing with a red error toast.+ return session.agentSpec ?? null;},async syncAgentSpec(draftSessionId, agentSpec) {diff --git a/packages/assistant-ui-runtime/src/draft/useDraftAgentSpec.ts b/packages/assistant-ui-runtime/src/draft/useDraftAgentSpec.tsindex 3c57d5309..3aed65a25 100644--- a/packages/assistant-ui-runtime/src/draft/useDraftAgentSpec.ts+++ b/packages/assistant-ui-runtime/src/draft/useDraftAgentSpec.ts@@ -105,7 +105,12 @@ export function useDraftAgentSpec({}loadedDraftIdRef.current = draftSessionId;- if (localDirtyRef.current) {+ if (loaded == null) {+ // A session without an agentSpec (e.g. named or immutable session) cannot accept+ // agent spec updates. Clear any unsaved draft edits so we never attempt to sync+ // draft changes against a named session.+ localDirtyRef.current = false;+ } else if (localDirtyRef.current) {scheduleSpecSyncRef.current(draftSessionId, agentSpecRef.current);localDirtyRef.current = false;setSpecError(null);@@ -113,7 +118,9 @@ export function useDraftAgentSpec({return;}- setAgentSpec(loaded);+ // If session has no custom draft spec (e.g. non-draft or immutable session),+ // keep the default draft spec rather than failing.+ setAgentSpec(loaded ?? defaultAgentSpec);setSpecError(null);setIsSpecLoading(false);} catch (error) {diff --git a/packages/assistant-ui-runtime/src/useTrueForgeAgentRuntime.ts b/packages/assistant-ui-runtime/src/useTrueForgeAgentRuntime.tsindex 23a29b534..14bfcaccc 100644--- a/packages/assistant-ui-runtime/src/useTrueForgeAgentRuntime.ts+++ b/packages/assistant-ui-runtime/src/useTrueForgeAgentRuntime.ts@@ -70,9 +70,20 @@ function useTrueForgeAgentRuntimeImpl(// bridge armed or a fresh `{ model: { name: '' } }` will retrigger spec sync.const draftBridge = agent.mode === 'draft' ? draftBridgeRef.current : null;- const draftSessionId = useAuiState(state =>- agent.mode === 'draft' ? (state.threadListItem.remoteId ?? undefined) : undefined,- );+ // Only attach a draftSessionId if the thread itself is mutable.+ // When browsing Chat History or switching to an immutable session, the shell+ // may still be in draft mode, but immutable chats have no draft spec to sync.+ const draftSessionId = useAuiState(state => {+ if (agent.mode !== 'draft') {+ return undefined;+ }+ const custom = state.threadListItem.custom;+ const isMutable = custom != null && typeof custom['isMutable'] === 'boolean' ? custom['isMutable'] : true;+ if (!isMutable) {+ return undefined;+ }+ return state.threadListItem.remoteId ?? undefined;+ });const sessionId = useAuiState(state => state.threadListItem.remoteId ?? undefined);const isMain = useAuiState(state => state.threads.mainThreadId === state.threadListItem.id);// On a hard refresh, the URL session runtime mounts before assistant-uidiff --git a/packages/assistant-ui-runtime/test/draft/draftSessionBridge.test.ts b/packages/assistant-ui-runtime/test/draft/draftSessionBridge.test.tsnew file mode 100644index 000000000..6fb7d857c--- /dev/null+++ b/packages/assistant-ui-runtime/test/draft/draftSessionBridge.test.ts@@ -0,0 +1,55 @@+import { describe, expect, it, vi } from 'vitest';++import { createDraftSessionBridge } from '../../src/draft/draftSessionBridge.js';+import type { AgentChatServer, Session } from '../../src/server/types.js';++describe('createDraftSessionBridge', () => {+ it('returns agentSpec when session has agentSpec', async () => {+ const mockSession: Session = {+ id: 'session-1',+ createdAt: '2026-09-01T00:00:00.000Z',+ updatedAt: '2026-09-01T00:00:00.000Z',+ isMutable: true,+ agentSpec: { model: { name: 'openai-main/gpt-4.1' } },+ };+ const server: AgentChatServer = {+ getSession: vi.fn().mockResolvedValue(mockSession),+ createSession: vi.fn(),+ updateSession: vi.fn(),+ createTurn: vi.fn(),+ cancelSession: vi.fn(),+ listSessions: vi.fn(),+ listTurns: vi.fn(),+ getTurn: vi.fn(),+ listEvents: vi.fn(),+ };++ const bridge = createDraftSessionBridge(server);+ const spec = await bridge.getDraftAgentSpec('session-1');+ expect(spec).toEqual({ model: { name: 'openai-main/gpt-4.1' } });+ });++ it('returns null without throwing when session has no agentSpec', async () => {+ const mockSession: Session = {+ id: 'session-immutable',+ createdAt: '2026-09-01T00:00:00.000Z',+ updatedAt: '2026-09-01T00:00:00.000Z',+ isMutable: false,+ };+ const server: AgentChatServer = {+ getSession: vi.fn().mockResolvedValue(mockSession),+ createSession: vi.fn(),+ updateSession: vi.fn(),+ createTurn: vi.fn(),+ cancelSession: vi.fn(),+ listSessions: vi.fn(),+ listTurns: vi.fn(),+ getTurn: vi.fn(),+ listEvents: vi.fn(),+ };++ const bridge = createDraftSessionBridge(server);+ const spec = await bridge.getDraftAgentSpec('session-immutable');+ expect(spec).toBeNull();+ });+});diff --git a/packages/assistant-ui-runtime/test/draft/useDraftAgentSpec.test.tsx b/packages/assistant-ui-runtime/test/draft/useDraftAgentSpec.test.tsxindex 0863c1906..93b4a42e9 100644--- a/packages/assistant-ui-runtime/test/draft/useDraftAgentSpec.test.tsx+++ b/packages/assistant-ui-runtime/test/draft/useDraftAgentSpec.test.tsx@@ -243,4 +243,58 @@ describe('useDraftAgentSpec', () => {await expect(result.current.takeTurnHeaderTimestamp()).resolves.toBe('2026-06-30T17:00:00.000Z');});++ it('falls back to defaultAgentSpec and does not error when getDraftAgentSpec resolves to null', async () => {+ const onError = vi.fn();+ const draftBridge: DraftSessionBridge = {+ getDraftAgentSpec: vi.fn().mockResolvedValue(null),+ syncAgentSpec: vi.fn().mockResolvedValue('2026-06-30T17:00:00.000Z'),+ };+ const { result } = renderHook(() =>+ useDraftAgentSpec({+ draftSessionId: 'session-no-spec',+ draftBridge,+ defaultAgentSpec,+ onError,+ }),+ );+ await flushMicrotasks();++ expect(draftBridge.getDraftAgentSpec).toHaveBeenCalledWith('session-no-spec');+ expect(onError).not.toHaveBeenCalled();+ expect(result.current.agentSpec).toEqual(defaultAgentSpec);+ expect(result.current.specError).toBeNull();+ expect(result.current.isSpecLoading).toBe(false);+ });++ it('does not sync dirty edits if the loaded session returns null agentSpec', async () => {+ const syncAgentSpec = vi.fn().mockResolvedValue('2026-06-30T17:00:00.000Z');+ const draftBridge: DraftSessionBridge = {+ getDraftAgentSpec: vi.fn().mockResolvedValue(null),+ syncAgentSpec,+ };+ const initialProps: { draftSessionId: string | undefined } = { draftSessionId: undefined };+ const { result, rerender } = renderHook(+ ({ draftSessionId }) =>+ useDraftAgentSpec({+ draftSessionId,+ draftBridge,+ defaultAgentSpec,+ }),+ { initialProps },+ );+ await flushMicrotasks();++ // User makes a local edit in New Chat (draftSessionId is undefined)+ act(() => {+ result.current.updateAgentSpec({ instructions: 'local edit' });+ });++ // Chat navigates or attaches to a named/immutable session where getDraftAgentSpec returns null+ rerender({ draftSessionId: 'immutable-session-1' });+ await flushMicrotasks();++ expect(draftBridge.getDraftAgentSpec).toHaveBeenCalledWith('immutable-session-1');+ expect(syncAgentSpec).not.toHaveBeenCalled();+ });});