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

package/src/index.ts

@@ -0,0 +1,68 @@
+/// <reference types="@assistant-ui/core/react" />
+
+export { useTrueFoundryAgentRuntime } from "./useTrueFoundryAgentRuntime.js";
+export {
+    convertTurnsToThreadMessages,
+    buildUserMessageContent,
+    buildEditedUserMessageContent,
+    getTurnMessageContent,
+    parseTurnIdFromMessageId,
+    buildTurnAssistantContent,
+    repositoryItemsFromMessages,
+} from "./convertTurnMessages.js";
+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 {
+    useTrueFoundryAgentSpec,
+    useTrueFoundryUpdateAgentSpec,
+} from "./hooks.js";
+export type { TrueFoundryDraftRuntimeExtras } from "./truefoundryExtras.js";
+export type { SubAgentArtifact, SubAgentCustomMetadata } from "./foldPeerThreads.js";
+export type {
+    TrueFoundryMessageCustomMetadata,
+    SubAgentMessageCustomMetadata,
+    McpAuthMessageCustomMetadata,
+    SandboxMessageCustomMetadata,
+    ToolApprovalMessageCustomMetadata,
+    ToolResponseMessageCustomMetadata,
+} from "./messageCustomMetadata.js";
+export type { SandboxCreatedEvent } from "truefoundry-gateway-sdk/agents";
+export type { PendingApproval, PendingToolResponse } from "./collectPending.js";
+export type { TrueFoundryRuntimeExtras } from "./truefoundryExtras.js";
+export { trueFoundryExtras } from "./truefoundryExtras.js";
+export {
+    useTrueFoundryApprovals,
+    useTrueFoundryToolResponses,
+    useTrueFoundryMcpAuth,
+    useTrueFoundryRespondToToolApproval,
+    useTrueFoundryRespondToToolResponse,
+    useTrueFoundryResumeMcpAuth,
+    useTrueFoundrySandboxId,
+    useTrueFoundryDownloadSandboxFile,
+    useTrueFoundryCancel,
+    useTrueFoundryResetFromTurn,
+} from "./hooks.js";
+export {
+    collectApprovalInputs,
+    messageHasPendingApprovals,
+    toTrueFoundryApprovalInputs,
+} from "./toolApproval.js";
+export {
+    collectResponseInputs,
+    messageHasPendingResponses,
+    TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY,
+} from "./toolResponse.js";
+export {
+    collectRequiredActionInputs,
+    messageHasPendingRequiredActions,
+    findPausedAssistantMessage,
+} from "./requiredActionInputs.js";
+export { createTrueFoundryThreadListAdapter } from "./truefoundryThreadListAdapter.js";
+export { getSession } from "./sessions.js";
+export { trueFoundryAttachmentAdapter } from "./attachmentAdapter.js";

package/src/lastUserMessageText.ts

@@ -0,0 +1,19 @@
+import type { ThreadMessage } from "@assistant-ui/core";
+
+export function lastUserMessageText(messages: readonly ThreadMessage[]): string {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (message?.role !== "user") {
+            continue;
+        }
+        const text = message.content
+            .filter((part) => part.type === "text")
+            .map((part) => part.text)
+            .join("\n")
+            .trim();
+        if (text) {
+            return text;
+        }
+    }
+    throw new Error("No user message with text content found.");
+}

package/src/loadSessionSnapshot.test.ts

@@ -0,0 +1,57 @@
+import type { AgentSessionClient } from "truefoundry-gateway-sdk/agents";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { createEmptySessionSnapshot } from "./sessionSnapshot.js";
+
+vi.mock("./sessions.js", () => ({
+    getSession: vi.fn(),
+}));
+
+vi.mock("./convertTurnMessages.js", async (importOriginal) => {
+    const actual = await importOriginal<typeof import("./convertTurnMessages.js")>();
+    return {
+        ...actual,
+        buildSnapshotFromSession: vi.fn(),
+    };
+});
+
+import { buildSnapshotFromSession } from "./convertTurnMessages.js";
+import { loadSessionSnapshot } from "./loadSessionSnapshot.js";
+import { getSession } from "./sessions.js";
+
+const mockClient = {} as AgentSessionClient;
+
+describe("loadSessionSnapshot", () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    it("deduplicates concurrent loads for the same session", async () => {
+        vi.mocked(getSession).mockResolvedValue({} as never);
+        vi.mocked(buildSnapshotFromSession).mockResolvedValue(
+            createEmptySessionSnapshot(),
+        );
+
+        const [first, second] = await Promise.all([
+            loadSessionSnapshot(mockClient, "session-1"),
+            loadSessionSnapshot(mockClient, "session-1"),
+        ]);
+
+        expect(first).toBe(second);
+        expect(getSession).toHaveBeenCalledTimes(1);
+        expect(buildSnapshotFromSession).toHaveBeenCalledTimes(1);
+    });
+
+    it("allows a new load after the previous one settles", async () => {
+        vi.mocked(getSession).mockResolvedValue({} as never);
+        vi.mocked(buildSnapshotFromSession).mockResolvedValue(
+            createEmptySessionSnapshot(),
+        );
+
+        await loadSessionSnapshot(mockClient, "session-1");
+        await loadSessionSnapshot(mockClient, "session-1");
+
+        expect(getSession).toHaveBeenCalledTimes(2);
+        expect(buildSnapshotFromSession).toHaveBeenCalledTimes(2);
+    });
+});

package/src/loadSessionSnapshot.ts

@@ -0,0 +1,35 @@
+import type { AgentSessionClient } from "truefoundry-gateway-sdk/agents";
+import type { TrueFoundryGateway } from "truefoundry-gateway-sdk";
+
+import { buildSnapshotFromSession } from "./convertTurnMessages.js";
+import { getSession, type GetSessionOptions } from "./sessions.js";
+import type { SessionSnapshot } from "./sessionSnapshot.js";
+
+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.
+ */
+export function loadSessionSnapshot(
+    client: AgentSessionClient,
+    sessionId: string,
+    concurrency?: number,
+    sessionOptions?: GetSessionOptions,
+): 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))
+            .finally(() => {
+                if (inflightBySessionId.get(cacheKey) === inflight) {
+                    inflightBySessionId.delete(cacheKey);
+                }
+            });
+        inflightBySessionId.set(cacheKey, inflight);
+    }
+    return inflight;
+}

package/src/mcpAuth.ts

@@ -0,0 +1,44 @@
+import type { MessageStatus } from "@assistant-ui/core";
+import type { McpAuthRequiredEvent, TurnStateDone } from "truefoundry-gateway-sdk/agents";
+
+import type { AssistantContentPart } from "./modelMessageContent.js";
+import type { McpAuthMessageCustomMetadata } from "./messageCustomMetadata.js";
+
+/** `runConfig.custom` flag: resume after MCP OAuth with an empty SDK turn input. */
+export const MCP_AUTH_RESUME_RUN_CUSTOM_KEY = "resumeMcpAuth";
+
+type McpServerAuthInfo = McpAuthRequiredEvent["mcpServers"][number];
+
+export function buildMcpAuthTextParts(
+    servers: readonly McpServerAuthInfo[],
+): AssistantContentPart[] {
+    const linkLines = servers.map(
+        (server) => `- [Authorize ${server.name}](${server.authUrl})`,
+    );
+    const text = [
+        "This agent needs access to external services before it can continue.",
+        "",
+        ...linkLines,
+        "",
+        "Open each link to sign in, then press **Continue** below.",
+    ].join("\n");
+    return [{ type: "text", text }];
+}
+
+export function findMcpAuthRequired(
+    requiredActions: TurnStateDone["requiredActions"] | undefined,
+): McpAuthRequiredEvent | undefined {
+    return requiredActions?.find(
+        (action): action is McpAuthRequiredEvent => action.type === "mcp.auth_required",
+    );
+}
+
+export function mcpAuthAssistantStatus(): MessageStatus {
+    return { type: "requires-action", reason: "interrupt" };
+}
+
+export function mcpAuthMessageCustom(
+    servers: readonly McpServerAuthInfo[],
+): McpAuthMessageCustomMetadata {
+    return { pendingMcpAuth: true, mcpServers: [...servers] };
+}

package/src/messageCustomMetadata.ts

@@ -0,0 +1,37 @@
+import type { McpAuthRequiredEvent } from "truefoundry-gateway-sdk/agents";
+
+import type { SubAgentCustomMetadata } from "./foldPeerThreads.js";
+import { TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY } from "./toolApproval.js";
+import { TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY } from "./toolResponse.js";
+
+/** Keys written to `ThreadMessage.metadata.custom` by this runtime adapter. */
+export type TrueFoundryMessageCustomMetadata = {
+    subAgent?: SubAgentCustomMetadata;
+    pendingMcpAuth?: true;
+    mcpServers?: McpAuthRequiredEvent["mcpServers"];
+    sandboxId?: string;
+    [TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY]?: string;
+    [TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY]?: string;
+};
+
+export type SubAgentMessageCustomMetadata = Pick<
+    TrueFoundryMessageCustomMetadata,
+    "subAgent"
+>;
+
+export type McpAuthMessageCustomMetadata = Pick<
+    TrueFoundryMessageCustomMetadata,
+    "pendingMcpAuth" | "mcpServers"
+>;
+
+export type SandboxMessageCustomMetadata = Pick<TrueFoundryMessageCustomMetadata, "sandboxId">;
+
+export type ToolApprovalMessageCustomMetadata = Pick<
+    TrueFoundryMessageCustomMetadata,
+    typeof TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY
+>;
+
+export type ToolResponseMessageCustomMetadata = Pick<
+    TrueFoundryMessageCustomMetadata,
+    typeof TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY
+>;

package/src/modelMessageContent.ts

@@ -0,0 +1,135 @@
+import type { ThreadAssistantMessagePart } from "@assistant-ui/core";
+import type { ModelMessageEvent } from "truefoundry-gateway-sdk/agents";
+import type { PendingResponseRef } from "./foldPeerThreads.js";
+import { extractImagePartsFromModelMessage } from "./modelMessageImageContent.js";
+
+export type AssistantContentPart = ThreadAssistantMessagePart;
+
+export type ToolCallContext = {
+    toolResults?: ReadonlyMap<string, string>;
+    pendingApprovals?: ReadonlyMap<string, { id: string }>;
+    approvalDecisions?: ReadonlyMap<
+        string,
+        { id: string; approved: boolean; reason?: string }
+    >;
+    pendingResponses?: ReadonlyMap<string, PendingResponseRef>;
+};
+
+export type SdkToolCall = NonNullable<ModelMessageEvent["toolCalls"]>[number];
+
+function parseToolArgs(argsText: string): Record<string, string | number | boolean | null> {
+    if (!argsText) {
+        return {};
+    }
+    try {
+        const parsed: unknown = JSON.parse(argsText);
+        if (parsed != null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed as Record<string, string | number | boolean | null>;
+        }
+        return {};
+    } catch {
+        return {};
+    }
+}
+
+type ToolCallPart = Extract<AssistantContentPart, { type: "tool-call" }>;
+
+function toolCallToPart(
+    toolCall: SdkToolCall,
+    context?: ToolCallContext,
+): ToolCallPart {
+    const argsText = toolCall.function.arguments ?? "";
+    const toolResult = context?.toolResults?.get(toolCall.id);
+    const pendingResponse = context?.pendingResponses?.get(toolCall.id);
+    const pendingApproval = context?.pendingApprovals?.get(toolCall.id);
+    const approvalDecision = context?.approvalDecisions?.get(toolCall.id);
+
+    let interrupt: ToolCallPart["interrupt"];
+    if (pendingResponse != null && toolResult === undefined) {
+        interrupt = {
+            type: "human",
+            payload: {
+                ...(pendingResponse.question != null
+                    ? { question: pendingResponse.question }
+                    : {}),
+                ...(pendingResponse.options != null
+                    ? { options: pendingResponse.options }
+                    : {}),
+            },
+        };
+    }
+
+    let approval: ToolCallPart["approval"];
+    if (approvalDecision != null) {
+        approval = {
+            id: approvalDecision.id,
+            approved: approvalDecision.approved,
+            ...(approvalDecision.reason != null
+                ? { reason: approvalDecision.reason }
+                : {}),
+        };
+    } else if (pendingApproval != null) {
+        approval = { id: pendingApproval.id };
+    }
+
+    let result: ToolCallPart["result"];
+    let isError = false;
+    if (toolResult !== undefined) {
+        result = toolResult;
+    } else if (approvalDecision?.approved === false) {
+        result = { error: approvalDecision.reason || "Tool approval denied" };
+        isError = true;
+    }
+
+    return {
+        type: "tool-call",
+        toolCallId: toolCall.id,
+        toolName: toolCall.function.name,
+        argsText,
+        args: parseToolArgs(argsText),
+        ...(result !== undefined ? { result } : {}),
+        ...(isError ? { isError: true } : {}),
+        ...(approval != null ? { approval } : {}),
+        ...(interrupt != null ? { interrupt } : {}),
+    };
+}
+
+function extractText(message: ModelMessageEvent): string {
+    const { content, refusal } = message;
+    if (content == null) {
+        return refusal ?? "";
+    }
+    if (typeof content === "string") {
+        return content;
+    }
+    return content
+        .map((part) => {
+            if (part.type === "text") {
+                return part.text;
+            }
+            if (part.type === "refusal") {
+                return part.refusal;
+            }
+            return "";
+        })
+        .join("");
+}
+
+export function buildAssistantContent(
+    message: ModelMessageEvent,
+    context?: ToolCallContext,
+): AssistantContentPart[] {
+    const parts: AssistantContentPart[] = [];
+    if (message.reasoningContent) {
+        parts.push({ type: "reasoning", text: message.reasoningContent });
+    }
+    const text = extractText(message);
+    if (text) {
+        parts.push({ type: "text", text });
+    }
+    parts.push(...extractImagePartsFromModelMessage(message));
+    for (const toolCall of message.toolCalls ?? []) {
+        parts.push(toolCallToPart(toolCall, context));
+    }
+    return parts;
+}

package/src/modelMessageImageContent.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+import type { ModelMessageEvent } from "truefoundry-gateway-sdk/agents";
+
+import { buildAssistantContent } from "./modelMessageContent.js";
+import { mergeStreamEventDelta } from "./modelMessageImageContent.js";
+import { PeerThreadFoldState, ingestStreamEvent } from "./foldPeerThreads.js";
+
+const imageDataUri = "data:image/jpeg;base64,/9j/4AAQ";
+
+function modelMessage(
+    event: Omit<ModelMessageEvent, "type" | "createdAt">,
+): ModelMessageEvent {
+    return {
+        type: "model.message",
+        createdAt: new Date().toISOString(),
+        ...event,
+    };
+}
+
+describe("modelMessageImageContent", () => {
+    it("merges content_blocks image_url deltas into the base model message", () => {
+        const base = modelMessage({
+            id: "m1",
+            threadId: "main",
+        });
+
+        mergeStreamEventDelta(base, {
+            type: "model.message.delta",
+            id: "m1",
+            threadId: "main",
+            content_blocks: [
+                {
+                    index: 0,
+                    delta: {
+                        type: "image_url",
+                        image_url: { url: imageDataUri },
+                    },
+                },
+            ],
+        } as never);
+
+        expect(base.content).toEqual([
+            {
+                type: "image_url",
+                image_url: { url: imageDataUri },
+            },
+        ]);
+    });
+
+    it("buildAssistantContent emits image parts for image_url content", () => {
+        const parts = buildAssistantContent(
+            modelMessage({
+                id: "m1",
+                threadId: "main",
+                content: [
+                    {
+                        type: "image_url",
+                        image_url: { url: imageDataUri },
+                    },
+                ] as never,
+            }),
+        );
+
+        expect(parts).toEqual([
+            {
+                type: "image",
+                image: imageDataUri,
+                filename: "image-1.jpeg",
+            },
+        ]);
+    });
+
+    it("ingests content_blocks deltas through the fold state", () => {
+        const fold = new PeerThreadFoldState();
+        ingestStreamEvent(
+            fold,
+            modelMessage({
+                id: "m1",
+                threadId: "main",
+            }),
+        );
+        ingestStreamEvent(fold, {
+            type: "model.message.delta",
+            id: "m1",
+            threadId: "main",
+            content_blocks: [
+                {
+                    index: 0,
+                    delta: {
+                        type: "image_url",
+                        image_url: { url: imageDataUri },
+                    },
+                },
+            ],
+        } as never);
+
+        const event = fold.threads.get("main")?.events.get("m1");
+        expect(event?.type).toBe("model.message");
+        if (event?.type !== "model.message") {
+            return;
+        }
+        expect(event.content).toEqual([
+            {
+                type: "image_url",
+                image_url: { url: imageDataUri },
+            },
+        ]);
+    });
+});