@truefoundry/assistant-ui-runtime 0.1.0-rc.1 → 0.1.2

package/src/hooks.ts

@@ -98,6 +98,30 @@ export const useTrueFoundryCancel = () => {
     return () => trueFoundryExtras.get(aui).cancel();
 };
 
+/** Returns a function to reload (retry) the current session from any render context. */
+export const useTrueFoundryReload = () => {
+    const aui = useAui();
+    return () => trueFoundryExtras.get(aui).reload();
+};
+
+/** Older history pagination state plus a load-more action for scroll-up. */
+export const useTrueFoundryHistoryPagination = () => {
+    const extras = trueFoundryExtras.use((e) => e, undefined);
+
+    return useMemo(
+        () => ({
+            hasOlderHistory: extras?.hasOlderHistory ?? false,
+            isLoadingOlderHistory: extras?.isLoadingOlderHistory ?? false,
+            loadOlderHistory:
+                extras?.loadOlderHistory ??
+                (async () => {
+                    throw new Error("TrueFoundry runtime is not ready yet");
+                }),
+        }),
+        [extras],
+    );
+};
+
 /** Returns a function to reset (re-submit) a user turn from any render context. */
 export const useTrueFoundryResetFromTurn = () => {
     const aui = useAui();

package/src/index.ts

@@ -13,11 +13,11 @@ export {
 export type { ConvertTurnsResult, UserMessageContent } from "./convertTurnMessages.js";
 export { ROOT_THREAD_ID } from "./constants.js";
 export type { UseTrueFoundryAgentRuntimeOptions, NamedAgentConfig, DraftAgentConfig, TrueFoundryAgentConfig } from "./types.js";
-export type { AgentSpec, AgentSpecUpdate, DraftSession } from "./agentSpec.js";
-export { mergeAgentSpec, draftSessionTitle } from "./agentSpec.js";
-export { createTrueFoundryDraftThreadListAdapter } from "./truefoundryDraftThreadListAdapter.js";
-export { createDraftSessionBridge } from "./draftSessionBridge.js";
-export type { DraftSessionBridge } from "./draftSessionBridge.js";
+export type { AgentSpec, AgentSpecUpdate, DraftSession } from "./private/agentSpec.js";
+export { mergeAgentSpec, draftSessionTitle } from "./private/agentSpec.js";
+export { createTrueFoundryDraftThreadListAdapter } from "./private/truefoundryDraftThreadListAdapter.js";
+export { createDraftSessionBridge } from "./private/draftSessionBridge.js";
+export type { DraftSessionBridge } from "./private/draftSessionBridge.js";
 export {
     useTrueFoundryAgentSpec,
     useTrueFoundryUpdateAgentSpec,
@@ -47,6 +47,8 @@ export {
     useTrueFoundryDownloadSandboxFile,
     useTrueFoundryCancel,
     useTrueFoundryResetFromTurn,
+    useTrueFoundryReload,
+    useTrueFoundryHistoryPagination,
 } from "./hooks.js";
 export {
     collectApprovalInputs,

package/src/loadSessionSnapshot.test.ts

@@ -11,11 +11,11 @@ vi.mock("./convertTurnMessages.js", async (importOriginal) => {
     const actual = await importOriginal<typeof import("./convertTurnMessages.js")>();
     return {
         ...actual,
-        buildSnapshotFromSession: vi.fn(),
+        buildSnapshotFromSessionEvents: vi.fn(),
     };
 });
 
-import { buildSnapshotFromSession } from "./convertTurnMessages.js";
+import { buildSnapshotFromSessionEvents } from "./convertTurnMessages.js";
 import { loadSessionSnapshot } from "./loadSessionSnapshot.js";
 import { getSession } from "./sessions.js";
 
@@ -28,7 +28,7 @@ describe("loadSessionSnapshot", () => {
 
     it("deduplicates concurrent loads for the same session", async () => {
         vi.mocked(getSession).mockResolvedValue({} as never);
-        vi.mocked(buildSnapshotFromSession).mockResolvedValue(
+        vi.mocked(buildSnapshotFromSessionEvents).mockResolvedValue(
             createEmptySessionSnapshot(),
         );
 
@@ -39,12 +39,12 @@ describe("loadSessionSnapshot", () => {
 
         expect(first).toBe(second);
         expect(getSession).toHaveBeenCalledTimes(1);
-        expect(buildSnapshotFromSession).toHaveBeenCalledTimes(1);
+        expect(buildSnapshotFromSessionEvents).toHaveBeenCalledTimes(1);
     });
 
     it("allows a new load after the previous one settles", async () => {
         vi.mocked(getSession).mockResolvedValue({} as never);
-        vi.mocked(buildSnapshotFromSession).mockResolvedValue(
+        vi.mocked(buildSnapshotFromSessionEvents).mockResolvedValue(
             createEmptySessionSnapshot(),
         );
 
@@ -52,6 +52,21 @@ describe("loadSessionSnapshot", () => {
         await loadSessionSnapshot(mockClient, "session-1");
 
         expect(getSession).toHaveBeenCalledTimes(2);
-        expect(buildSnapshotFromSession).toHaveBeenCalledTimes(2);
+        expect(buildSnapshotFromSessionEvents).toHaveBeenCalledTimes(2);
+    });
+
+    it("forwards onProgress to buildSnapshotFromSessionEvents", async () => {
+        vi.mocked(getSession).mockResolvedValue({} as never);
+        vi.mocked(buildSnapshotFromSessionEvents).mockResolvedValue(
+            createEmptySessionSnapshot(),
+        );
+
+        const onProgress = vi.fn();
+        await loadSessionSnapshot(mockClient, "session-1", undefined, onProgress);
+
+        expect(buildSnapshotFromSessionEvents).toHaveBeenCalledWith(
+            {},
+            onProgress,
+        );
     });
 });

package/src/loadSessionSnapshot.ts

@@ -1,7 +1,6 @@
 import type { AgentSessionClient } from "truefoundry-gateway-sdk/agents";
-import type { TrueFoundryGateway } from "truefoundry-gateway-sdk";
 
-import { buildSnapshotFromSession } from "./convertTurnMessages.js";
+import { buildSnapshotFromSessionEvents } from "./convertTurnMessages.js";
 import { getSession, type GetSessionOptions } from "./sessions.js";
 import type { SessionSnapshot } from "./sessionSnapshot.js";
 
@@ -10,20 +9,25 @@ const inflightBySessionId = new Map<string, Promise<SessionSnapshot>>();
 /**
  * Loads a session snapshot once per concurrent burst for a given session id.
  * React Strict Mode and overlapping fetch/load paths share the same in-flight
- * request instead of duplicating getSession + listTurns calls.
+ * request instead of duplicating getSession + listEvents calls.
+ *
+ * `onProgress` is called after each complete turn is ingested so the caller
+ * can update the UI progressively while history is being processed.
  */
 export function loadSessionSnapshot(
     client: AgentSessionClient,
     sessionId: string,
-    concurrency?: number,
     sessionOptions?: GetSessionOptions,
+    onProgress?: (snap: SessionSnapshot) => void,
 ): Promise<SessionSnapshot> {
     const cacheKey =
         sessionOptions?.draftGateway != null ? `draft:${sessionId}` : sessionId;
     let inflight = inflightBySessionId.get(cacheKey);
     if (inflight == null) {
         inflight = getSession(client, sessionId, sessionOptions)
-            .then((session) => buildSnapshotFromSession(session, concurrency))
+            .then((session) =>
+                buildSnapshotFromSessionEvents(session, onProgress),
+            )
             .finally(() => {
                 if (inflightBySessionId.get(cacheKey) === inflight) {
                     inflightBySessionId.delete(cacheKey);

package/src/{bindDraftAgentSession.test.ts → private/bindDraftAgentSession.test.ts}

@@ -31,7 +31,7 @@ describe("bindDraftAgentSession", () => {
 });
 
 describe("createDraftSessionBridge", () => {
-    it("syncs agent spec via draftSessions.update", async () => {
+    it("syncs agent spec via draftSessions.update and returns updatedAt", async () => {
         const { createDraftSessionBridge } = await import("./draftSessionBridge.js");
         const update = vi.fn().mockResolvedValue({ data: draft });
         const gateway = {
@@ -46,10 +46,11 @@ describe("createDraftSessionBridge", () => {
         } as unknown as TrueFoundryGateway;
 
         const bridge = createDraftSessionBridge(gateway);
-        await bridge.syncAgentSpec("draft-1", draft.agentSpec);
+        const updatedAt = await bridge.syncAgentSpec("draft-1", draft.agentSpec);
 
         expect(update).toHaveBeenCalledWith("draft-1", {
             agentSpec: draft.agentSpec,
         });
+        expect(updatedAt).toBe(draft.updatedAt);
     });
 });

package/src/{draftSessionBridge.ts → private/draftSessionBridge.ts}

@@ -2,8 +2,10 @@ import type { TrueFoundryGateway } from "truefoundry-gateway-sdk";
 
 import type { AgentSpec } from "./agentSpec.js";
 
+export const DRAFT_SESSION_LAST_UPDATED_AT_HEADER = "x-tfy-session-last-updated-at";
+
 export type DraftSessionBridge = {
-    syncAgentSpec: (draftSessionId: string, agentSpec: AgentSpec) => Promise<void>;
+    syncAgentSpec: (draftSessionId: string, agentSpec: AgentSpec) => Promise<string>;
     getDraftAgentSpec: (draftSessionId: string) => Promise<AgentSpec>;
 };
 
@@ -22,7 +24,11 @@ export function createDraftSessionBridge(
         },
 
         async syncAgentSpec(draftSessionId, agentSpec) {
-            await gateway.agents.private.draftSessions.update(draftSessionId, { agentSpec });
+            const response = await gateway.agents.private.draftSessions.update(
+                draftSessionId,
+                { agentSpec },
+            );
+            return response.data.updatedAt;
         },
     };
 }

package/src/{truefoundryDraftThreadListAdapter.ts → private/truefoundryDraftThreadListAdapter.ts}

@@ -2,7 +2,7 @@ import type { RemoteThreadListAdapter } from "@assistant-ui/core";
 import type { TrueFoundryGateway } from "truefoundry-gateway-sdk";
 
 import { draftSessionTitle, type AgentSpec } from "./agentSpec.js";
-import { sessionListStartTimestamp } from "./sessionListStartTimestamp.js";
+import { sessionListStartTimestamp } from "../sessionListStartTimestamp.js";
 
 const THREAD_LIST_PAGE_SIZE = 20;
 

package/src/private/useDraftAgentSpec.test.tsx

@@ -0,0 +1,153 @@
+// @vitest-environment jsdom
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { DraftSessionBridge } from "./draftSessionBridge.js";
+import { useDraftAgentSpec } from "./useDraftAgentSpec.js";
+
+const defaultAgentSpec = { model: { name: "anthropic/claude-sonnet-4-6" } };
+
+async function flushMicrotasks() {
+    await act(async () => {
+        await Promise.resolve();
+        await Promise.resolve();
+    });
+}
+
+describe("useDraftAgentSpec", () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    it("stores updatedAt from sync and returns it once from takeTurnHeaderTimestamp", async () => {
+        const syncAgentSpec = vi
+            .fn()
+            .mockResolvedValue("2026-06-30T12:00:00.000Z");
+        const draftBridge: DraftSessionBridge = {
+            getDraftAgentSpec: vi.fn().mockResolvedValue(defaultAgentSpec),
+            syncAgentSpec,
+        };
+
+        const { result } = renderHook(() =>
+            useDraftAgentSpec({
+                draftSessionId: "draft-1",
+                draftBridge,
+                defaultAgentSpec,
+            }),
+        );
+
+        await flushMicrotasks();
+        expect(draftBridge.getDraftAgentSpec).toHaveBeenCalledWith("draft-1");
+
+        act(() => {
+            result.current.updateAgentSpec({ instructions: "be brief" });
+        });
+
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(400);
+        });
+        await flushMicrotasks();
+
+        expect(syncAgentSpec).toHaveBeenCalledOnce();
+
+        let first: string | undefined;
+        await act(async () => {
+            first = await result.current.takeTurnHeaderTimestamp();
+        });
+        expect(first).toBe("2026-06-30T12:00:00.000Z");
+
+        let second: string | undefined;
+        await act(async () => {
+            second = await result.current.takeTurnHeaderTimestamp();
+        });
+        expect(second).toBeUndefined();
+    });
+
+    it("flushes a pending debounced sync before returning the timestamp", async () => {
+        const syncAgentSpec = vi
+            .fn()
+            .mockResolvedValue("2026-06-30T13:00:00.000Z");
+        const draftBridge: DraftSessionBridge = {
+            getDraftAgentSpec: vi.fn().mockResolvedValue(defaultAgentSpec),
+            syncAgentSpec,
+        };
+
+        const { result } = renderHook(() =>
+            useDraftAgentSpec({
+                draftSessionId: "draft-1",
+                draftBridge,
+                defaultAgentSpec,
+            }),
+        );
+
+        await flushMicrotasks();
+        expect(draftBridge.getDraftAgentSpec).toHaveBeenCalledWith("draft-1");
+
+        act(() => {
+            result.current.updateAgentSpec({ instructions: "new" });
+        });
+        expect(syncAgentSpec).not.toHaveBeenCalled();
+
+        let timestamp: string | undefined;
+        await act(async () => {
+            timestamp = await result.current.takeTurnHeaderTimestamp();
+        });
+
+        expect(syncAgentSpec).toHaveBeenCalledOnce();
+        expect(timestamp).toBe("2026-06-30T13:00:00.000Z");
+    });
+
+    it("drops pending sync state and stored timestamp when draftSessionId changes", async () => {
+        const syncAgentSpec = vi
+            .fn()
+            .mockResolvedValue("2026-06-30T14:00:00.000Z");
+        const draftBridge: DraftSessionBridge = {
+            getDraftAgentSpec: vi.fn().mockResolvedValue(defaultAgentSpec),
+            syncAgentSpec,
+        };
+
+        const { result, rerender } = renderHook(
+            ({ draftSessionId }: { draftSessionId: string }) =>
+                useDraftAgentSpec({
+                    draftSessionId,
+                    draftBridge,
+                    defaultAgentSpec,
+                }),
+            { initialProps: { draftSessionId: "draft-1" } },
+        );
+
+        await flushMicrotasks();
+
+        // A completed sync stores a timestamp for draft-1...
+        act(() => {
+            result.current.updateAgentSpec({ instructions: "for draft-1" });
+        });
+        await act(async () => {
+            await vi.advanceTimersByTimeAsync(400);
+        });
+        await flushMicrotasks();
+        expect(syncAgentSpec).toHaveBeenCalledWith("draft-1", expect.anything());
+
+        // ...and another edit leaves a pending debounced flush for draft-1.
+        act(() => {
+            result.current.updateAgentSpec({ instructions: "pending for draft-1" });
+        });
+
+        rerender({ draftSessionId: "draft-2" });
+        await flushMicrotasks();
+
+        let timestamp: string | undefined;
+        await act(async () => {
+            timestamp = await result.current.takeTurnHeaderTimestamp();
+        });
+
+        // Neither draft-1's stored timestamp nor its pending flush leaks into draft-2.
+        expect(timestamp).toBeUndefined();
+        expect(syncAgentSpec).toHaveBeenCalledOnce();
+        expect(result.current.isSpecSyncing).toBe(false);
+    });
+});

package/src/{useDraftAgentSpec.ts → private/useDraftAgentSpec.ts}

@@ -19,13 +19,22 @@ export type UseDraftAgentSpecOptions = {
     onError?: ((error: unknown) => void) | undefined;
 };
 
+export type UseDraftAgentSpecResult = {
+    agentSpec: AgentSpec | null;
+    draftSessionId: string | undefined;
+    isSpecSyncing: boolean;
+    specError: unknown | null;
+    updateAgentSpec: (update: AgentSpecUpdate) => void;
+    takeTurnHeaderTimestamp: () => Promise<string | undefined>;
+};
+
 export function useDraftAgentSpec({
     draftSessionId,
     draftBridge,
     defaultAgentSpec,
     onAgentSpecChange,
     onError,
-}: UseDraftAgentSpecOptions) {
+}: UseDraftAgentSpecOptions): UseDraftAgentSpecResult {
     const enabled = draftBridge != null;
     const [agentSpec, setAgentSpec] = useState<AgentSpec>(defaultAgentSpec);
     const [isSpecSyncing, setIsSpecSyncing] = useState(false);
@@ -38,6 +47,35 @@ export function useDraftAgentSpec({
     const syncGenerationRef = useRef(0);
     const loadedDraftIdRef = useRef<string | undefined>(undefined);
     const localDirtyRef = useRef(false);
+    const lastUpdatedAtRef = useRef<string | undefined>(undefined);
+    const pendingFlushRef = useRef<(() => Promise<void>) | undefined>(undefined);
+    const inFlightFlushRef = useRef<Promise<void> | undefined>(undefined);
+    const activeDraftIdRef = useRef(draftSessionId);
+
+    // Invalidate sync state from the previous draft so a stale pending flush or
+    // stored updatedAt can't update the wrong draft or leak into the next
+    // turn's header. Bumping the generation makes any in-flight sync a no-op.
+    useEffect(() => {
+        const previousDraftId = activeDraftIdRef.current;
+        if (previousDraftId === draftSessionId) {
+            return;
+        }
+        activeDraftIdRef.current = draftSessionId;
+        syncGenerationRef.current++;
+        if (syncTimeoutRef.current != null) {
+            clearTimeout(syncTimeoutRef.current);
+            syncTimeoutRef.current = undefined;
+        }
+        pendingFlushRef.current = undefined;
+        inFlightFlushRef.current = undefined;
+        lastUpdatedAtRef.current = undefined;
+        setIsSpecSyncing(false);
+        // Dirty edits made against a previous draft must not be replayed onto
+        // the new one. Keep them only for lazy creation (undefined -> id).
+        if (previousDraftId != null) {
+            localDirtyRef.current = false;
+        }
+    }, [draftSessionId]);
 
     useEffect(() => {
         if (!enabled || draftBridge == null) {
@@ -93,10 +131,12 @@ export function useDraftAgentSpec({
             }
             setIsSpecSyncing(true);
             try {
-                await draftBridge.syncAgentSpec(draftId, spec);
+                const updatedAt = await draftBridge.syncAgentSpec(draftId, spec);
                 if (generation !== syncGenerationRef.current) {
                     return;
                 }
+                lastUpdatedAtRef.current =
+                    updatedAt || new Date().toISOString();
                 setSpecError(null);
                 onAgentSpecChange?.(spec);
             } catch (error) {
@@ -119,8 +159,20 @@ export function useDraftAgentSpec({
                 clearTimeout(syncTimeoutRef.current);
             }
             const generation = ++syncGenerationRef.current;
+            const flush = () => {
+                pendingFlushRef.current = undefined;
+                syncTimeoutRef.current = undefined;
+                const promise = flushSpecSync(draftId, spec, generation).finally(() => {
+                    if (inFlightFlushRef.current === promise) {
+                        inFlightFlushRef.current = undefined;
+                    }
+                });
+                inFlightFlushRef.current = promise;
+                return promise;
+            };
+            pendingFlushRef.current = flush;
             syncTimeoutRef.current = setTimeout(() => {
-                void flushSpecSync(draftId, spec, generation);
+                void flush();
             }, SPEC_SYNC_DEBOUNCE_MS);
         },
         [flushSpecSync],
@@ -129,6 +181,29 @@ export function useDraftAgentSpec({
     const scheduleSpecSyncRef = useRef(scheduleSpecSync);
     scheduleSpecSyncRef.current = scheduleSpecSync;
 
+    const flushPendingSpecSyncNow = useCallback(async () => {
+        if (syncTimeoutRef.current != null) {
+            clearTimeout(syncTimeoutRef.current);
+            syncTimeoutRef.current = undefined;
+        }
+        const pending = pendingFlushRef.current;
+        if (pending != null) {
+            pendingFlushRef.current = undefined;
+            await pending();
+            return;
+        }
+        if (inFlightFlushRef.current != null) {
+            await inFlightFlushRef.current;
+        }
+    }, []);
+
+    const takeTurnHeaderTimestamp = useCallback(async () => {
+        await flushPendingSpecSyncNow();
+        const updatedAt = lastUpdatedAtRef.current;
+        lastUpdatedAtRef.current = undefined;
+        return updatedAt;
+    }, [flushPendingSpecSyncNow]);
+
     useEffect(
         () => () => {
             if (syncTimeoutRef.current != null) {
@@ -160,6 +235,7 @@ export function useDraftAgentSpec({
             isSpecSyncing: enabled ? isSpecSyncing : false,
             specError: enabled ? specError : null,
             updateAgentSpec,
+            takeTurnHeaderTimestamp,
         }),
         [
             agentSpec,
@@ -167,6 +243,7 @@ export function useDraftAgentSpec({
             enabled,
             isSpecSyncing,
             specError,
+            takeTurnHeaderTimestamp,
             updateAgentSpec,
         ],
     );

package/src/sessionSnapshot.ts

@@ -1,4 +1,11 @@
-import type { McpAuthRequiredEvent, Turn, TurnInputItem } from "truefoundry-gateway-sdk/agents";
+import type {
+    McpAuthRequiredEvent,
+    Turn,
+    TurnCreatedEvent,
+    TurnDoneEvent,
+    TurnEvent,
+    TurnInputItem,
+} from "truefoundry-gateway-sdk/agents";
 
 import { extractTurnUserText } from "./extractTurnUserText.js";
 import { PeerThreadFoldState } from "./foldPeerThreads.js";
@@ -6,6 +13,19 @@ import type { StoredApprovalDecision } from "./toolApproval.js";
 import type { StoredToolResponse } from "./toolResponse.js";
 import type { TurnStreamUpdate } from "./turnStreamUpdate.js";
 
+/** Session-level event item from `AgentSession.listEvents`. */
+export type GatewaySessionEventItem = {
+    turnId: string;
+    event: TurnCreatedEvent | TurnDoneEvent | TurnEvent;
+};
+
+/** Cursor for fetching older `listEvents` pages (scroll-up history). */
+export type SessionHistoryPagination = {
+    /** Token for the next older page; omit when exhausted. */
+    olderPageToken?: string;
+    hasOlder: boolean;
+};
+
 /** Turn metadata retained for cross-turn projection and subsequent required-action replay. */
 export type SessionTurnRecord = Pick<
     Turn,
@@ -49,6 +69,12 @@ export type SessionSnapshot = {
     requiredActions: RequiredActionsOverlay;
     runningTurn?: Turn;
     unstable_resume?: boolean;
+    /**
+     * Chronological `listEvents` items loaded so far (for prepend-on-scroll rebuild).
+     * Live stream commits are not appended here — they live in `turns` / `fold`.
+     */
+    historyEvents?: readonly GatewaySessionEventItem[];
+    historyPagination?: SessionHistoryPagination;
 };
 
 export type ProjectSessionMessagesOptions = {
@@ -81,10 +107,30 @@ export function turnToSessionRecord(turn: Turn): SessionTurnRecord {
     };
 }
 
+/** Builds a SessionTurnRecord from session-level TurnCreatedEvent + TurnDoneEvent data. */
+export function sessionEventsToSessionRecord(
+    turnId: string,
+    createdEvent: TurnCreatedEvent,
+    doneEvent: TurnDoneEvent,
+    rootModelMessageIds: readonly string[],
+    sandboxId?: string,
+): SessionTurnRecord {
+    const userText = extractTurnUserText(createdEvent.input);
+    return {
+        id: turnId,
+        ...(userText ? { userText } : {}),
+        createdAt: createdEvent.createdAt,
+        state: doneEvent.state,
+        input: createdEvent.input,
+        rootModelMessageIds,
+        ...(sandboxId != null ? { sandboxId } : {}),
+    };
+}
+
 /** Returns a new snapshot wrapper; fold maps may be mutated in place before calling. */
 export function replaceSessionSnapshot(
     snapshot: SessionSnapshot,
-    patch: Partial<Omit<SessionSnapshot, "fold" | "requiredActions">> & {
+    patch: Partial<Omit<SessionSnapshot, "requiredActions">> & {
         requiredActions?: RequiredActionsOverlay;
     },
 ): SessionSnapshot {

package/src/sessions.ts

@@ -4,7 +4,7 @@ import type {
 } from "truefoundry-gateway-sdk/agents";
 import type { TrueFoundryGateway } from "truefoundry-gateway-sdk";
 
-import { bindDraftAgentSession } from "./bindDraftAgentSession.js";
+import { bindDraftAgentSession } from "./private/bindDraftAgentSession.js";
 
 const inflightBySessionId = new Map<string, Promise<AgentSession>>();
 

package/src/streamTurn.test.ts

@@ -193,6 +193,40 @@ describe("streamTurn", () => {
             expect(execute).not.toHaveBeenCalled();
             expect(updates).toEqual([]);
         });
+
+        it("forwards headers to turn.execute request options", async () => {
+            const execute = vi.fn(() => (async function* () {})());
+            const prepareTurn = vi.fn(() => ({ execute }));
+            const session = {
+                prepareTurn,
+                cancel: vi.fn().mockResolvedValue(undefined),
+            } as unknown as AgentSession;
+            const abortSignal = new AbortController().signal;
+
+            await collectUpdates(
+                streamTurnContent(
+                    session,
+                    new PeerThreadFoldState(),
+                    {
+                        userMessage: "hello",
+                        headers: {
+                            "x-tfy-session-last-updated-at": "2026-06-30T10:00:00.000Z",
+                        },
+                    },
+                    abortSignal,
+                ),
+            );
+
+            expect(execute).toHaveBeenCalledWith(
+                { stream: true },
+                {
+                    abortSignal,
+                    headers: {
+                        "x-tfy-session-last-updated-at": "2026-06-30T10:00:00.000Z",
+                    },
+                },
+            );
+        });
     });
 
     describe("resumeTurnStream", () => {

package/src/streamTurn.ts

@@ -21,6 +21,8 @@ export type StreamTurnOptions = {
      * root turn (no `previousTurnId` field).
      */
     previousTurnId?: string | null;
+    /** Extra headers for the createTurn request (`execute` request options). */
+    headers?: Record<string, string>;
 };
 
 function buildTurnInput(options: StreamTurnOptions): TurnInputItem[] {
@@ -68,7 +70,13 @@ export async function* streamTurnContent(
 
     try {
         yield* streamTurnEvents(
-            turn.execute({ stream: true }, { abortSignal }),
+            turn.execute(
+                { stream: true },
+                {
+                    abortSignal,
+                    ...(options.headers != null ? { headers: options.headers } : {}),
+                },
+            ),
             foldState,
             groupRootBaseline,
         );

package/src/truefoundryExtras.ts

@@ -1,7 +1,7 @@
 import { createRuntimeExtras } from "@assistant-ui/core/internal";
 import type { McpAuthRequiredEvent } from "truefoundry-gateway-sdk/agents";
 
-import type { AgentSpec, AgentSpecUpdate } from "./agentSpec.js";
+import type { AgentSpec, AgentSpecUpdate } from "./private/agentSpec.js";
 import type { PendingApproval, PendingToolResponse } from "./collectPending.js";
 import type { RespondToToolApprovalOptions } from "./toolApproval.js";
 import type { RespondToToolResponseOptions } from "./toolResponse.js";
@@ -27,6 +27,10 @@ export type TrueFoundryRuntimeExtras = {
     downloadSandboxFile: (path: string) => Promise<Blob>;
     cancel: () => Promise<void>;
     resetFromTurn: (turnId: string) => Promise<void>;
+    reload: () => void;
+    hasOlderHistory: boolean;
+    isLoadingOlderHistory: boolean;
+    loadOlderHistory: () => Promise<void>;
     draft: TrueFoundryDraftRuntimeExtras | null;
 };