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

package/src/truefoundryDraftThreadListAdapter.ts

@@ -0,0 +1,63 @@
+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";
+
+const THREAD_LIST_PAGE_SIZE = 20;
+
+export function createTrueFoundryDraftThreadListAdapter(options: {
+    gateway: TrueFoundryGateway;
+    defaultAgentSpec: AgentSpec;
+    getAgentSpec?: () => AgentSpec;
+}): RemoteThreadListAdapter {
+    const { gateway, defaultAgentSpec, getAgentSpec } = options;
+
+    return {
+        async list({ after } = {}) {
+            const page = await gateway.agents.private.draftSessions.list({
+                limit: THREAD_LIST_PAGE_SIZE,
+                pageToken: after,
+                startTimestamp: sessionListStartTimestamp(),
+            });
+            const threads = page.data.map((draft) => ({
+                status: "regular" as const,
+                remoteId: draft.id,
+                title: draftSessionTitle(draft),
+                lastMessageAt: new Date(draft.updatedAt),
+            }));
+            return {
+                threads,
+                nextCursor: page.response.pagination.nextPageToken ?? undefined,
+            };
+        },
+
+        async initialize(_threadId: string) {
+            const response = await gateway.agents.private.draftSessions.create({
+                agentSpec: getAgentSpec?.() ?? defaultAgentSpec,
+            });
+            const draft = response.data;
+            return { remoteId: draft.id, externalId: undefined };
+        },
+
+        async fetch(remoteId) {
+            const response = await gateway.agents.private.draftSessions.get(remoteId);
+            const draft = response.data;
+            return {
+                status: "regular" as const,
+                remoteId: draft.id,
+                title: draftSessionTitle(draft),
+                lastMessageAt: new Date(draft.updatedAt),
+            };
+        },
+
+        async rename() {},
+        async archive() {},
+        async unarchive() {},
+        async delete() {},
+
+        async generateTitle() {
+            return new ReadableStream();
+        },
+    };
+}

package/src/truefoundryExtras.ts

@@ -0,0 +1,45 @@
+import { createRuntimeExtras } from "@assistant-ui/core/internal";
+import type { McpAuthRequiredEvent } from "truefoundry-gateway-sdk/agents";
+
+import type { AgentSpec, AgentSpecUpdate } from "./agentSpec.js";
+import type { PendingApproval, PendingToolResponse } from "./collectPending.js";
+import type { RespondToToolApprovalOptions } from "./toolApproval.js";
+import type { RespondToToolResponseOptions } from "./toolResponse.js";
+
+export type { PendingApproval, PendingToolResponse };
+
+export type TrueFoundryDraftRuntimeExtras = {
+    agentSpec: AgentSpec | null;
+    draftSessionId: string | undefined;
+    isSpecSyncing: boolean;
+    specError: unknown | null;
+    updateAgentSpec: (update: AgentSpecUpdate) => void;
+};
+
+export type TrueFoundryRuntimeExtras = {
+    pendingApprovals: PendingApproval[];
+    pendingToolResponses: PendingToolResponse[];
+    pendingMcpAuth: { mcpServers: McpAuthRequiredEvent["mcpServers"] } | null;
+    sandboxId: string | undefined;
+    respondToToolApproval: (response: RespondToToolApprovalOptions) => void;
+    respondToToolResponse: (response: RespondToToolResponseOptions) => void;
+    resumeMcpAuth: () => Promise<void>;
+    downloadSandboxFile: (path: string) => Promise<Blob>;
+    cancel: () => Promise<void>;
+    resetFromTurn: (turnId: string) => Promise<void>;
+    draft: TrueFoundryDraftRuntimeExtras | null;
+};
+
+export const trueFoundryExtras = createRuntimeExtras<TrueFoundryRuntimeExtras>(
+    "useTrueFoundryAgentRuntime",
+);
+
+export const EMPTY_DRAFT_EXTRAS: TrueFoundryDraftRuntimeExtras = {
+    agentSpec: null,
+    draftSessionId: undefined,
+    isSpecSyncing: false,
+    specError: null,
+    updateAgentSpec: () => {
+        throw new Error("Draft agent extras are only available in draft mode.");
+    },
+};

package/src/truefoundryThreadListAdapter.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { AgentSessionClient } from "truefoundry-gateway-sdk/agents";
+
+import { createTrueFoundryThreadListAdapter } from "./truefoundryThreadListAdapter.js";
+
+function mockSession(id: string, title: string, updatedAt: string) {
+    return {
+        id,
+        title,
+        updatedAt,
+    };
+}
+
+function mockListSessionsPage(
+    sessions: ReturnType<typeof mockSession>[],
+    nextPageToken?: string,
+) {
+    return {
+        data: sessions,
+        response: {
+            pagination: {
+                nextPageToken,
+                limit: 20,
+            },
+        },
+    };
+}
+
+describe("createTrueFoundryThreadListAdapter", () => {
+    it("lists the first page with limit and returns nextCursor", async () => {
+        const listSessions = vi.fn().mockResolvedValue(
+            mockListSessionsPage(
+                [mockSession("s1", "First", "2026-06-30T10:00:00.000Z")],
+                "page-2",
+            ),
+        );
+        const client = { listSessions } as unknown as AgentSessionClient;
+        const adapter = createTrueFoundryThreadListAdapter({
+            client,
+            agentName: "my-agent",
+        });
+
+        const result = await adapter.list();
+
+        expect(listSessions).toHaveBeenCalledWith(
+            expect.objectContaining({
+                agentName: "my-agent",
+                limit: 20,
+                pageToken: undefined,
+                startTimestamp: expect.any(String),
+            }),
+        );
+        expect(result.threads).toEqual([
+            {
+                status: "regular",
+                remoteId: "s1",
+                title: "First",
+                lastMessageAt: new Date("2026-06-30T10:00:00.000Z"),
+            },
+        ]);
+        expect(result.nextCursor).toBe("page-2");
+    });
+
+    it("forwards after as pageToken for subsequent pages", async () => {
+        const listSessions = vi.fn().mockResolvedValue(
+            mockListSessionsPage(
+                [mockSession("s2", "Second", "2026-06-29T10:00:00.000Z")],
+            ),
+        );
+        const client = { listSessions } as unknown as AgentSessionClient;
+        const adapter = createTrueFoundryThreadListAdapter({
+            client,
+            agentName: "my-agent",
+        });
+
+        const result = await adapter.list({ after: "page-2" });
+
+        expect(listSessions).toHaveBeenCalledWith(
+            expect.objectContaining({
+                agentName: "my-agent",
+                limit: 20,
+                pageToken: "page-2",
+            }),
+        );
+        expect(result.nextCursor).toBeUndefined();
+    });
+
+    it("omits nextCursor when the backend returns no next page token", async () => {
+        const listSessions = vi.fn().mockResolvedValue(
+            mockListSessionsPage([mockSession("s1", "Only", "2026-06-30T10:00:00.000Z")]),
+        );
+        const client = { listSessions } as unknown as AgentSessionClient;
+        const adapter = createTrueFoundryThreadListAdapter({
+            client,
+            agentName: "my-agent",
+        });
+
+        const result = await adapter.list();
+
+        expect(result.nextCursor).toBeUndefined();
+    });
+});

package/src/truefoundryThreadListAdapter.ts

@@ -0,0 +1,59 @@
+import type { RemoteThreadListAdapter } from "@assistant-ui/core";
+import type { AgentSessionClient } from "truefoundry-gateway-sdk/agents";
+
+import { getSession } from "./sessions.js";
+import { sessionListStartTimestamp } from "./sessionListStartTimestamp.js";
+
+const THREAD_LIST_PAGE_SIZE = 20;
+
+export function createTrueFoundryThreadListAdapter(options: {
+    client: AgentSessionClient;
+    agentName: string;
+}): RemoteThreadListAdapter {
+    const { client, agentName } = options;
+
+    return {
+        async list({ after } = {}) {
+            const page = await client.listSessions({
+                agentName,
+                limit: THREAD_LIST_PAGE_SIZE,
+                pageToken: after,
+                startTimestamp: sessionListStartTimestamp(),
+            });
+            const threads = page.data.map((session) => ({
+                status: "regular" as const,
+                remoteId: session.id,
+                title: session.title,
+                lastMessageAt: new Date(session.updatedAt),
+            }));
+            return {
+                threads,
+                nextCursor: page.response.pagination.nextPageToken ?? undefined,
+            };
+        },
+
+        async initialize(_threadId: string) {
+            const session = await client.createSession({ agentName });
+            return { remoteId: session.id, externalId: undefined };
+        },
+
+        async fetch(remoteId) {
+            const session = await getSession(client, remoteId);
+            return {
+                status: "regular" as const,
+                remoteId: session.id,
+                title: session.title,
+                lastMessageAt: new Date(session.updatedAt),
+            };
+        },
+
+        async rename() {},
+        async archive() {},
+        async unarchive() {},
+        async delete() {},
+
+        async generateTitle() {
+            return new ReadableStream();
+        },
+    };
+}

package/src/turnEventHelpers.ts

@@ -0,0 +1,98 @@
+import type { Turn } from "truefoundry-gateway-sdk/agents";
+
+import {
+    buildMcpAuthTextParts,
+    findMcpAuthRequired,
+    mcpAuthAssistantStatus,
+    mcpAuthMessageCustom,
+} from "./mcpAuth.js";
+import {
+    findApprovalRequiredInTurn,
+    toolApprovalMessageCustom,
+    toolApprovalStatus,
+} from "./toolApproval.js";
+import {
+    findResponseRequiredInTurn,
+    toolResponseMessageCustom,
+    toolResponseStatus,
+} from "./toolResponse.js";
+import type { AssistantContentPart } from "./modelMessageContent.js";
+import type { TurnStreamUpdate } from "./turnStreamUpdate.js";
+
+function buildToolApprovalUpdate(
+    content: AssistantContentPart[],
+    turn: Pick<Turn, "state">,
+): TurnStreamUpdate {
+    const pendingApproval = findApprovalRequiredInTurn(turn);
+    if (pendingApproval == null) {
+        return { content };
+    }
+    return {
+        content,
+        status: toolApprovalStatus(),
+        metadata: { custom: toolApprovalMessageCustom(pendingApproval.threadId) },
+    };
+}
+
+function buildToolResponseUpdate(
+    update: TurnStreamUpdate,
+    turn: Pick<Turn, "state">,
+): TurnStreamUpdate {
+    const pendingResponse = findResponseRequiredInTurn(turn);
+    if (pendingResponse == null) {
+        return update;
+    }
+    return {
+        ...update,
+        content: update.content,
+        status: toolResponseStatus(),
+        metadata: {
+            custom: {
+                ...update.metadata?.custom,
+                ...toolResponseMessageCustom(pendingResponse.threadId),
+            },
+        },
+    };
+}
+
+export function appendToolResponseToTurnContent(
+    update: TurnStreamUpdate,
+    turn: Pick<Turn, "state">,
+): TurnStreamUpdate {
+    if (update.status?.type === "requires-action") {
+        return update;
+    }
+    return buildToolResponseUpdate(update, turn);
+}
+
+export function appendToolApprovalToTurnContent(
+    update: TurnStreamUpdate,
+    turn: Pick<Turn, "state">,
+): TurnStreamUpdate {
+    if (update.status?.type === "requires-action") {
+        return update;
+    }
+    const approvalUpdate = buildToolApprovalUpdate(update.content, turn);
+    return appendToolResponseToTurnContent(approvalUpdate, turn);
+}
+
+export function appendMcpAuthToTurnContent(
+    content: AssistantContentPart[],
+    turn: Pick<Turn, "state">,
+): TurnStreamUpdate {
+    const pendingMcpAuth = findMcpAuthRequired(
+        turn.state.status === "done" ? turn.state.requiredActions : undefined,
+    );
+    if (pendingMcpAuth == null) {
+        return appendToolApprovalToTurnContent({ content }, turn);
+    }
+
+    return appendToolApprovalToTurnContent(
+        {
+            content: [...content, ...buildMcpAuthTextParts(pendingMcpAuth.mcpServers)],
+            status: mcpAuthAssistantStatus(),
+            metadata: { custom: mcpAuthMessageCustom(pendingMcpAuth.mcpServers) },
+        },
+        turn,
+    );
+}

package/src/turnStreamUpdate.ts

@@ -0,0 +1,11 @@
+import type { MessageStatus } from "@assistant-ui/core";
+
+import type { AssistantContentPart } from "./modelMessageContent.js";
+
+export type TurnStreamUpdate = {
+    content: AssistantContentPart[];
+    status?: MessageStatus;
+    metadata?: {
+        custom?: Record<string, unknown>;
+    };
+};

package/src/types.ts

@@ -0,0 +1,92 @@
+import type {
+    AttachmentAdapter,
+    DictationAdapter,
+    ExternalStoreSharedOptions,
+    FeedbackAdapter,
+    RealtimeVoiceAdapter,
+    SpeechSynthesisAdapter,
+} from "@assistant-ui/core";
+import type { AgentSessionClient } from "truefoundry-gateway-sdk/agents";
+import type { TrueFoundryGateway } from "truefoundry-gateway-sdk";
+
+import type { AgentSpec } from "./agentSpec.js";
+
+export type NamedAgentConfig = {
+    mode: "named";
+    agentName: string;
+};
+
+export type DraftAgentConfig = {
+    mode: "draft";
+    defaultAgentSpec: AgentSpec;
+    onAgentSpecChange?: ((spec: AgentSpec) => void) | undefined;
+};
+
+export type TrueFoundryAgentConfig = NamedAgentConfig | DraftAgentConfig;
+
+type TrueFoundryAgentRuntimeBaseOptions = ExternalStoreSharedOptions & {
+    client: AgentSessionClient;
+    initialSessionId?: string | undefined;
+    threadId?: string | undefined;
+    onThreadIdChange?: ((threadId: string | undefined) => void) | undefined;
+    onError?: ((error: unknown) => void) | undefined;
+    listEventsConcurrency?: number | undefined;
+    adapters?:
+        | {
+              attachments?: AttachmentAdapter | undefined;
+              speech?: SpeechSynthesisAdapter | undefined;
+              dictation?: DictationAdapter | undefined;
+              voice?: RealtimeVoiceAdapter | undefined;
+              feedback?: FeedbackAdapter | undefined;
+          }
+        | undefined;
+};
+
+export type UseTrueFoundryAgentRuntimeOptions = TrueFoundryAgentRuntimeBaseOptions & {
+    /** Discriminated agent source. Omit when using legacy `agentName`. */
+    agent?: TrueFoundryAgentConfig | undefined;
+    /** Legacy named-agent shorthand. Prefer `agent: { mode: "named", agentName }`. */
+    agentName?: string | undefined;
+    /** Required when `agent.mode === "draft"`. */
+    gateway?: TrueFoundryGateway | undefined;
+};
+
+export type ResolvedTrueFoundryAgentRuntimeOptions = TrueFoundryAgentRuntimeBaseOptions & {
+    agent: TrueFoundryAgentConfig;
+    gateway?: TrueFoundryGateway | undefined;
+};
+
+export function resolveTrueFoundryAgentConfig(
+    options: Pick<UseTrueFoundryAgentRuntimeOptions, "agent" | "agentName">,
+): TrueFoundryAgentConfig {
+    if (options.agent != null) {
+        if (options.agent.mode === "named" && options.agentName != null) {
+            return { mode: "named", agentName: options.agentName };
+        }
+        return options.agent;
+    }
+    if (options.agentName != null) {
+        return { mode: "named", agentName: options.agentName };
+    }
+    throw new Error(
+        "useTrueFoundryAgentRuntime requires `agent` or legacy `agentName`.",
+    );
+}
+
+export function resolveTrueFoundryAgentRuntimeOptions(
+    options: UseTrueFoundryAgentRuntimeOptions,
+): ResolvedTrueFoundryAgentRuntimeOptions {
+    const agent = resolveTrueFoundryAgentConfig(options);
+
+    if (agent.mode === "draft" && options.gateway == null) {
+        throw new Error(
+            "Draft agent mode requires a `gateway` TrueFoundryGateway client.",
+        );
+    }
+
+    return {
+        ...options,
+        agent,
+        gateway: options.gateway,
+    };
+}

package/src/useDraftAgentSpec.ts

@@ -0,0 +1,173 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+
+import {
+    mergeAgentSpec,
+    type AgentSpec,
+    type AgentSpecUpdate,
+} from "./agentSpec.js";
+import type { DraftSessionBridge } from "./draftSessionBridge.js";
+
+const SPEC_SYNC_DEBOUNCE_MS = 400;
+
+export type UseDraftAgentSpecOptions = {
+    draftSessionId: string | undefined;
+    draftBridge: DraftSessionBridge | null;
+    defaultAgentSpec: AgentSpec;
+    onAgentSpecChange?: ((spec: AgentSpec) => void) | undefined;
+    onError?: ((error: unknown) => void) | undefined;
+};
+
+export function useDraftAgentSpec({
+    draftSessionId,
+    draftBridge,
+    defaultAgentSpec,
+    onAgentSpecChange,
+    onError,
+}: UseDraftAgentSpecOptions) {
+    const enabled = draftBridge != null;
+    const [agentSpec, setAgentSpec] = useState<AgentSpec>(defaultAgentSpec);
+    const [isSpecSyncing, setIsSpecSyncing] = useState(false);
+    const [specError, setSpecError] = useState<unknown | null>(null);
+
+    const agentSpecRef = useRef(agentSpec);
+    agentSpecRef.current = agentSpec;
+
+    const syncTimeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+    const syncGenerationRef = useRef(0);
+    const loadedDraftIdRef = useRef<string | undefined>(undefined);
+    const localDirtyRef = useRef(false);
+
+    useEffect(() => {
+        if (!enabled || draftBridge == null) {
+            return;
+        }
+        if (draftSessionId == null) {
+            loadedDraftIdRef.current = undefined;
+            setAgentSpec(defaultAgentSpec);
+            localDirtyRef.current = false;
+            setSpecError(null);
+            return;
+        }
+
+        if (loadedDraftIdRef.current === draftSessionId) {
+            return;
+        }
+
+        let cancelled = false;
+        void (async () => {
+            try {
+                const loaded = await draftBridge.getDraftAgentSpec(draftSessionId);
+                if (cancelled) {
+                    return;
+                }
+                loadedDraftIdRef.current = draftSessionId;
+
+                if (localDirtyRef.current) {
+                    scheduleSpecSyncRef.current?.(draftSessionId, agentSpecRef.current);
+                    localDirtyRef.current = false;
+                    setSpecError(null);
+                    return;
+                }
+
+                setAgentSpec(loaded);
+                setSpecError(null);
+            } catch (error) {
+                if (!cancelled) {
+                    onError?.(error);
+                    setSpecError(error);
+                }
+            }
+        })();
+
+        return () => {
+            cancelled = true;
+        };
+    }, [defaultAgentSpec, draftBridge, draftSessionId, enabled, onError]);
+
+    const flushSpecSync = useCallback(
+        async (draftId: string, spec: AgentSpec, generation: number) => {
+            if (draftBridge == null) {
+                return;
+            }
+            setIsSpecSyncing(true);
+            try {
+                await draftBridge.syncAgentSpec(draftId, spec);
+                if (generation !== syncGenerationRef.current) {
+                    return;
+                }
+                setSpecError(null);
+                onAgentSpecChange?.(spec);
+            } catch (error) {
+                if (generation === syncGenerationRef.current) {
+                    setSpecError(error);
+                    onError?.(error);
+                }
+            } finally {
+                if (generation === syncGenerationRef.current) {
+                    setIsSpecSyncing(false);
+                }
+            }
+        },
+        [draftBridge, onAgentSpecChange, onError],
+    );
+
+    const scheduleSpecSync = useCallback(
+        (draftId: string, spec: AgentSpec) => {
+            if (syncTimeoutRef.current != null) {
+                clearTimeout(syncTimeoutRef.current);
+            }
+            const generation = ++syncGenerationRef.current;
+            syncTimeoutRef.current = setTimeout(() => {
+                void flushSpecSync(draftId, spec, generation);
+            }, SPEC_SYNC_DEBOUNCE_MS);
+        },
+        [flushSpecSync],
+    );
+
+    const scheduleSpecSyncRef = useRef(scheduleSpecSync);
+    scheduleSpecSyncRef.current = scheduleSpecSync;
+
+    useEffect(
+        () => () => {
+            if (syncTimeoutRef.current != null) {
+                clearTimeout(syncTimeoutRef.current);
+            }
+        },
+        [],
+    );
+
+    const updateAgentSpec = useCallback(
+        (update: AgentSpecUpdate) => {
+            if (!enabled || draftBridge == null) {
+                return;
+            }
+            const next = mergeAgentSpec(agentSpecRef.current, update);
+            setAgentSpec(next);
+            localDirtyRef.current = true;
+            if (draftSessionId != null) {
+                scheduleSpecSync(draftSessionId, next);
+            }
+        },
+        [draftBridge, draftSessionId, enabled, scheduleSpecSync],
+    );
+
+    return useMemo(
+        () => ({
+            agentSpec: enabled ? agentSpec : null,
+            draftSessionId: enabled ? draftSessionId : undefined,
+            isSpecSyncing: enabled ? isSpecSyncing : false,
+            specError: enabled ? specError : null,
+            updateAgentSpec,
+        }),
+        [
+            agentSpec,
+            draftSessionId,
+            enabled,
+            isSpecSyncing,
+            specError,
+            updateAgentSpec,
+        ],
+    );
+}