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

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@truefoundry/assistant-ui-runtime",
+  "version": "0.1.0-rc.1",
+  "description": "TrueFoundry Gateway agent runtime adapter for assistant-ui",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/truefoundry/truefoundry-agents-assistant-ui-runtime"
+  },
+  "homepage": "https://github.com/truefoundry/truefoundry-agents-assistant-ui-runtime#readme",
+  "keywords": [
+    "assistant-ui",
+    "truefoundry",
+    "ai",
+    "agent",
+    "react",
+    "llm",
+    "chat"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "prepare": "tsup",
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@assistant-ui/core": "^0.2.19",
+    "@assistant-ui/store": "^0.2.19"
+  },
+  "peerDependencies": {
+    "@types/react": "*",
+    "react": "^18 || ^19",
+    "truefoundry-gateway-sdk": "^0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@types/react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^20",
+    "@types/react": "^19.2.17",
+    "jsdom": "^29.1.1",
+    "react": "^19.2.4",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.9"
+  }
+}

package/src/agentSessionModule.d.ts

@@ -0,0 +1,25 @@
+declare module "truefoundry-gateway-sdk/dist/esm/agents/AgentSession.mjs" {
+    import type { TrueFoundryGateway } from "truefoundry-gateway-sdk";
+    import type * as TrueFoundryGatewayApi from "truefoundry-gateway-sdk";
+    import type { PreparedTurn } from "truefoundry-gateway-sdk/agents";
+    import type * as core from "truefoundry-gateway-sdk/core";
+
+    export class AgentSession implements TrueFoundryGatewayApi.Session {
+        readonly id: string;
+        readonly agentName: string;
+        readonly title?: string;
+        readonly createdBySubject: TrueFoundryGatewayApi.Subject;
+        readonly createdAt: string;
+        readonly updatedAt: string;
+        constructor(session: TrueFoundryGatewayApi.Session, client: TrueFoundryGateway);
+        prepareTurn(opts?: {
+            input?: TrueFoundryGatewayApi.TurnInputItem[];
+            previousTurnId?: TrueFoundryGatewayApi.PreviousTurnIdInput;
+        }): PreparedTurn;
+        listTurns(
+            opts?: TrueFoundryGatewayApi.agents.SessionsListTurnsRequest,
+        ): Promise<core.Page<unknown, TrueFoundryGatewayApi.ListTurnsResponse>>;
+        getTurn(opts: { turnId: string }): Promise<unknown>;
+        cancel(): Promise<void>;
+    }
+}

package/src/agentSpec.ts

@@ -0,0 +1,44 @@
+import type { TruefoundryGatewayApi } from "truefoundry-gateway-sdk";
+
+export type AgentSpec = TruefoundryGatewayApi.AgentSpec;
+export type DraftSession = TruefoundryGatewayApi.DraftSession;
+
+export type AgentSpecUpdate = {
+    instructions?: string;
+    model?: Partial<AgentSpec["model"]> & {
+        params?: Partial<NonNullable<AgentSpec["model"]["params"]>>;
+    };
+    mcpServers?: AgentSpec["mcpServers"];
+    skills?: AgentSpec["skills"];
+    messages?: AgentSpec["messages"];
+    variables?: AgentSpec["variables"];
+    responseFormat?: AgentSpec["responseFormat"];
+    config?: AgentSpec["config"];
+};
+
+export function mergeAgentSpec(base: AgentSpec, update: AgentSpecUpdate): AgentSpec {
+    const { model: modelUpdate, ...rest } = update;
+
+    const next: AgentSpec = {
+        ...base,
+        ...rest,
+    };
+
+    if (modelUpdate != null) {
+        next.model = {
+            ...base.model,
+            ...modelUpdate,
+            name: modelUpdate.name ?? base.model.name,
+            params:
+                modelUpdate.params != null
+                    ? { ...base.model.params, ...modelUpdate.params }
+                    : base.model.params,
+        };
+    }
+
+    return next;
+}
+
+export function draftSessionTitle(draft: DraftSession): string {
+    return draft.title ?? draft.agentSpec.model.name;
+}

package/src/askUserQuestion.ts

@@ -0,0 +1,37 @@
+import type { ToolCall } from "truefoundry-gateway-sdk/agents";
+
+export function isAskUserQuestionToolCall(
+    toolCall: Pick<ToolCall, "toolInfo">,
+): boolean {
+    return (
+        toolCall.toolInfo.type === "truefoundry-system" &&
+        toolCall.toolInfo.name === "ask_user_question"
+    );
+}
+
+export type AskUserQuestionArgs = {
+    question?: string;
+    options?: string[];
+};
+
+export function parseAskUserQuestionArgs(
+    argsText: string | undefined,
+): AskUserQuestionArgs {
+    if (!argsText) {
+        return {};
+    }
+    try {
+        const parsed: unknown = JSON.parse(argsText);
+        if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+            return {};
+        }
+        const record = parsed as Record<string, unknown>;
+        const question = typeof record.question === "string" ? record.question : undefined;
+        const options = Array.isArray(record.options)
+            ? record.options.filter((item): item is string => typeof item === "string")
+            : undefined;
+        return { question, options };
+    } catch {
+        return {};
+    }
+}

package/src/attachmentAdapter.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import type { PendingAttachment } from "@assistant-ui/core";
+
+import { trueFoundryAttachmentAdapter } from "./attachmentAdapter.js";
+
+async function addFile(file: File): Promise<PendingAttachment> {
+    const result = await trueFoundryAttachmentAdapter.add({ file });
+    if (Symbol.asyncIterator in result) {
+        throw new Error("expected PendingAttachment");
+    }
+    return result;
+}
+
+describe("trueFoundryAttachmentAdapter", () => {
+    it("accepts all file types", () => {
+        expect(trueFoundryAttachmentAdapter.accept).toBe("*");
+    });
+
+    it("add returns a pending attachment awaiting composer send", async () => {
+        const file = new File(["hello"], "notes.txt", { type: "text/plain" });
+        const pending = await addFile(file);
+
+        expect(pending).toMatchObject({
+            type: "file",
+            name: "notes.txt",
+            contentType: "text/plain",
+            file,
+            content: [],
+            status: { type: "requires-action", reason: "composer-send" },
+        });
+        expect(pending.id).toBeTruthy();
+    });
+
+    it("send reads the file into a data URI file part", async () => {
+        const file = new File(["hello"], "notes.txt", { type: "text/plain" });
+        const pending = await addFile(file);
+        const complete = await trueFoundryAttachmentAdapter.send(pending);
+
+        expect(complete.status).toEqual({ type: "complete" });
+        expect(complete.content).toHaveLength(1);
+        expect(complete.content[0]).toMatchObject({
+            type: "file",
+            mimeType: "text/plain",
+            filename: "notes.txt",
+        });
+        expect(complete.content[0]).toMatchObject({
+            data: expect.stringMatching(/^data:text\/plain;base64,/),
+        });
+    });
+
+    it("remove is a no-op", async () => {
+        const file = new File(["hello"], "notes.txt", { type: "text/plain" });
+        const pending = await addFile(file);
+        await expect(trueFoundryAttachmentAdapter.remove(pending)).resolves.toBeUndefined();
+    });
+});

package/src/attachmentAdapter.ts

@@ -0,0 +1,58 @@
+import {
+    generateId,
+    type AttachmentAdapter,
+    type PendingAttachment,
+} from "@assistant-ui/core";
+
+const bytesToBase64 = (bytes: Uint8Array): string =>
+    globalThis.Buffer.from(bytes).toString("base64");
+
+const getFileDataURL = async (file: File): Promise<string> => {
+    if (typeof FileReader === "undefined") {
+        const buffer = await file.arrayBuffer();
+        return `data:${file.type};base64,${bytesToBase64(new Uint8Array(buffer))}`;
+    }
+    return new Promise((resolve, reject) => {
+        const reader = new FileReader();
+        reader.onload = () => resolve(reader.result as string);
+        reader.onerror = (error) => reject(error);
+        reader.readAsDataURL(file);
+    });
+};
+
+/**
+ * Reads composer files into `CompleteAttachment` `file` parts for send.
+ * Wire via `adapters: { attachments: trueFoundryAttachmentAdapter }`.
+ */
+export const trueFoundryAttachmentAdapter: AttachmentAdapter = {
+    accept: "*",
+    async add({ file }) {
+        return {
+            id: generateId(),
+            type: "file",
+            name: file.name,
+            file,
+            contentType: file.type,
+            content: [],
+            status: {
+                type: "requires-action",
+                reason: "composer-send",
+            },
+        };
+    },
+    async send(attachment: PendingAttachment) {
+        return {
+            ...attachment,
+            status: { type: "complete" },
+            content: [
+                {
+                    type: "file",
+                    mimeType: attachment.contentType ?? "",
+                    filename: attachment.name,
+                    data: await getFileDataURL(attachment.file),
+                },
+            ],
+        };
+    },
+    async remove() {},
+};

package/src/bindDraftAgentSession.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { TrueFoundryGateway } from "truefoundry-gateway-sdk";
+import type { AgentSessionClient } from "truefoundry-gateway-sdk/agents";
+
+import { bindDraftAgentSession } from "./bindDraftAgentSession.js";
+
+const draft = {
+    id: "draft-1",
+    agentSpec: { model: { name: "anthropic/claude-sonnet-4-6" } },
+    createdBySubject: { type: "user" as const, id: "u1" },
+    createdAt: "2026-06-30T10:00:00.000Z",
+    updatedAt: "2026-06-30T10:00:00.000Z",
+};
+
+describe("bindDraftAgentSession", () => {
+    it("validates the draft and binds turns to the draft session id", async () => {
+        const get = vi.fn().mockResolvedValue({ data: draft });
+        const gateway = {
+            agents: { private: { draftSessions: { get } } },
+        } as unknown as TrueFoundryGateway;
+        const client = {
+            client: gateway,
+        } as unknown as AgentSessionClient;
+
+        const session = await bindDraftAgentSession(client, gateway, "draft-1");
+
+        expect(get).toHaveBeenCalledWith("draft-1");
+        expect(session.id).toBe("draft-1");
+    });
+});
+
+describe("createDraftSessionBridge", () => {
+    it("syncs agent spec via draftSessions.update", async () => {
+        const { createDraftSessionBridge } = await import("./draftSessionBridge.js");
+        const update = vi.fn().mockResolvedValue({ data: draft });
+        const gateway = {
+            agents: {
+                private: {
+                    draftSessions: {
+                        get: vi.fn().mockResolvedValue({ data: draft }),
+                        update,
+                    },
+                },
+            },
+        } as unknown as TrueFoundryGateway;
+
+        const bridge = createDraftSessionBridge(gateway);
+        await bridge.syncAgentSpec("draft-1", draft.agentSpec);
+
+        expect(update).toHaveBeenCalledWith("draft-1", {
+            agentSpec: draft.agentSpec,
+        });
+    });
+});

package/src/bindDraftAgentSession.ts

@@ -0,0 +1,66 @@
+import type { TrueFoundryGateway } from "truefoundry-gateway-sdk";
+import type { AgentSession, AgentSessionClient } from "truefoundry-gateway-sdk/agents";
+// SDK does not publicly export the AgentSession class; bind draft ids for turn routes.
+import { AgentSession as AgentSessionClass } from "truefoundry-gateway-sdk/dist/esm/agents/AgentSession.mjs";
+
+import type { DraftSession } from "./agentSpec.js";
+
+type SessionRecord = {
+    id: string;
+    agentName: string;
+    title?: string;
+    createdBySubject: DraftSession["createdBySubject"];
+    createdAt: string;
+    updatedAt: string;
+};
+
+const inflightByDraftId = new Map<string, Promise<AgentSession>>();
+
+export function getGatewayFromSessionClient(
+    client: AgentSessionClient,
+): TrueFoundryGateway {
+    const internal = client as unknown as { client: TrueFoundryGateway };
+    if (internal.client == null) {
+        throw new Error("AgentSessionClient is missing an internal gateway client.");
+    }
+    return internal.client;
+}
+
+function draftToSessionRecord(draft: DraftSession): SessionRecord {
+    return {
+        id: draft.id,
+        agentName: draft.agentName ?? "",
+        title: draft.title,
+        createdBySubject: draft.createdBySubject,
+        createdAt: draft.createdAt,
+        updatedAt: draft.updatedAt,
+    };
+}
+
+/**
+ * Binds an `AgentSession` for turn APIs at `/agents/sessions/{draftSessionId}/turns`
+ * after validating the draft via `GET draft-sessions/{draftSessionId}`.
+ * Does not call `GET` or `POST` on `/agents/sessions` root.
+ */
+export async function bindDraftAgentSession(
+    client: AgentSessionClient,
+    gateway: TrueFoundryGateway,
+    draftSessionId: string,
+): Promise<AgentSession> {
+    let inflight = inflightByDraftId.get(draftSessionId);
+    if (inflight == null) {
+        inflight = (async () => {
+            const response = await gateway.agents.private.draftSessions.get(draftSessionId);
+            return new AgentSessionClass(
+                draftToSessionRecord(response.data),
+                getGatewayFromSessionClient(client),
+            ) as AgentSession;
+        })().finally(() => {
+            if (inflightByDraftId.get(draftSessionId) === inflight) {
+                inflightByDraftId.delete(draftSessionId);
+            }
+        });
+        inflightByDraftId.set(draftSessionId, inflight);
+    }
+    return inflight;
+}

package/src/buildEditedUserMessageContent.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+
+import {
+    buildEditedUserMessageContent,
+    parseTurnIdFromMessageId,
+    resolveBranchPreviousTurnId,
+} from "./convertTurnMessages.js";
+import type { SessionTurnRecord } from "./sessionSnapshot.js";
+
+describe("user message branch helpers", () => {
+    it("parseTurnIdFromMessageId strips the user suffix", () => {
+        expect(parseTurnIdFromMessageId("turn-abc-user")).toBe("turn-abc");
+    });
+
+    it("resolveBranchPreviousTurnId returns null for the first turn", () => {
+        const turns: SessionTurnRecord[] = [
+            { id: "a", createdAt: "", state: { status: "done", requiredActions: [], completedAt: "" } },
+        ];
+        expect(resolveBranchPreviousTurnId(turns, "a")).toBeNull();
+    });
+
+    it("resolveBranchPreviousTurnId returns the prior turn id", () => {
+        const turns: SessionTurnRecord[] = [
+            { id: "a", createdAt: "", state: { status: "done", requiredActions: [], completedAt: "" } },
+            { id: "b", createdAt: "", state: { status: "done", requiredActions: [], completedAt: "" } },
+        ];
+        expect(resolveBranchPreviousTurnId(turns, "b")).toBe("a");
+    });
+});
+
+describe("buildEditedUserMessageContent", () => {
+    it("returns plain string when there are no attachments", () => {
+        expect(
+            buildEditedUserMessageContent("updated", [
+                { type: "user.message", content: "original" },
+            ]),
+        ).toBe("updated");
+    });
+
+    it("preserves file parts from the original turn input", () => {
+        const filePart = {
+            type: "file" as const,
+            name: "report.pdf",
+            data: "data:application/pdf;base64,AAAA",
+        };
+        expect(
+            buildEditedUserMessageContent("updated question", [
+                {
+                    type: "user.message",
+                    content: [
+                        { type: "text", text: "original question" },
+                        filePart,
+                    ],
+                },
+            ]),
+        ).toEqual([
+            { type: "text", text: "updated question" },
+            filePart,
+        ]);
+    });
+});

package/src/collectPending.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "vitest";
+import type { ThreadMessage } from "@assistant-ui/core";
+
+import { deriveSandboxId } from "./collectPending.js";
+
+function assistantMessage(
+    id: string,
+    custom: Record<string, unknown> = {},
+): ThreadMessage {
+    return {
+        id,
+        role: "assistant" as const,
+        content: [],
+        status: { type: "complete" as const, reason: "stop" as const },
+        createdAt: new Date(),
+        metadata: {
+            unstable_state: null,
+            unstable_annotations: [],
+            unstable_data: [],
+            steps: [],
+            custom,
+        },
+    };
+}
+
+function userMessage(id: string): ThreadMessage {
+    return {
+        id,
+        role: "user" as const,
+        content: [{ type: "text", text: "hi" }],
+        attachments: [],
+        createdAt: new Date(),
+        metadata: { custom: {} },
+    };
+}
+
+describe("deriveSandboxId", () => {
+    it("returns undefined when no message ever carried a sandboxId", () => {
+        const messages = [userMessage("u1"), assistantMessage("a1")];
+        expect(deriveSandboxId(messages)).toBeUndefined();
+    });
+
+    it("returns the sandboxId from the most recent message that has one", () => {
+        const messages = [
+            userMessage("u1"),
+            assistantMessage("a1", { sandboxId: "sbx-1" }),
+            userMessage("u2"),
+            assistantMessage("a2"),
+        ];
+        expect(deriveSandboxId(messages)).toBe("sbx-1");
+    });
+
+    it("prefers a later sandboxId over an earlier one", () => {
+        const messages = [
+            assistantMessage("a1", { sandboxId: "sbx-1" }),
+            assistantMessage("a2", { sandboxId: "sbx-2" }),
+        ];
+        expect(deriveSandboxId(messages)).toBe("sbx-2");
+    });
+
+    it("keeps returning the sandboxId from earlier turns even when later assistant messages lack it", () => {
+        const messages = [
+            assistantMessage("a1", { sandboxId: "sbx-1" }),
+            assistantMessage("a2"),
+            assistantMessage("a3"),
+        ];
+        expect(deriveSandboxId(messages)).toBe("sbx-1");
+    });
+});