Skip to content

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.md
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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-ui
diff --git a/packages/assistant-ui-runtime/test/draft/draftSessionBridge.test.ts b/packages/assistant-ui-runtime/test/draft/draftSessionBridge.test.ts
new file mode 100644
index 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.tsx
index 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();
+ });
});