@truefoundry/assistant-ui-runtime 0.1.1 → 0.1.2

package/src/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/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/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/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

@@ -3,6 +3,7 @@ import type {
     Turn,
     TurnCreatedEvent,
     TurnDoneEvent,
+    TurnEvent,
     TurnInputItem,
 } from "truefoundry-gateway-sdk/agents";
 
@@ -12,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,
@@ -55,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 = {
@@ -110,7 +130,7 @@ export function sessionEventsToSessionRecord(
 /** 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/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

@@ -28,6 +28,9 @@ export type TrueFoundryRuntimeExtras = {
     cancel: () => Promise<void>;
     resetFromTurn: (turnId: string) => Promise<void>;
     reload: () => void;
+    hasOlderHistory: boolean;
+    isLoadingOlderHistory: boolean;
+    loadOlderHistory: () => Promise<void>;
     draft: TrueFoundryDraftRuntimeExtras | null;
 };
 

package/src/useTrueFoundryAgentMessages.test.tsx

@@ -329,6 +329,56 @@ describe("useTrueFoundryAgentMessages", () => {
         expect(loadSessionSnapshot).not.toHaveBeenCalled();
     });
 
+    it("sendTurn forwards getTurnHeaders only when they resolve to a value", async () => {
+        const getTurnHeaders = vi
+            .fn()
+            .mockResolvedValueOnce({
+                "x-tfy-session-last-updated-at": "2026-06-30T12:00:00.000Z",
+            })
+            .mockResolvedValueOnce(undefined);
+
+        const { result } = renderHook(() =>
+            useTrueFoundryAgentMessages({
+                client: mockClient,
+                sessionId: "session-1",
+                getTurnHeaders,
+            }),
+        );
+
+        await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+        await act(async () => {
+            await result.current.sendTurn({ userMessage: "first" });
+        });
+
+        expect(getTurnHeaders).toHaveBeenCalledTimes(1);
+        expect(streamTurnContent).toHaveBeenCalledWith(
+            expect.anything(),
+            expect.any(PeerThreadFoldState),
+            {
+                userMessage: "first",
+                headers: {
+                    "x-tfy-session-last-updated-at": "2026-06-30T12:00:00.000Z",
+                },
+            },
+            expect.any(AbortSignal),
+            expect.any(Array),
+        );
+
+        await act(async () => {
+            await result.current.sendTurn({ userMessage: "second" });
+        });
+
+        expect(getTurnHeaders).toHaveBeenCalledTimes(2);
+        expect(streamTurnContent).toHaveBeenLastCalledWith(
+            expect.anything(),
+            expect.any(PeerThreadFoldState),
+            { userMessage: "second" },
+            expect.any(AbortSignal),
+            expect.any(Array),
+        );
+    });
+
     it("loads converted session history on mount", async () => {
         vi.mocked(loadSessionSnapshot).mockResolvedValue(
             snapshotWithUserTurn("hello"),