@truefoundry/assistant-ui-runtime 0.1.3-rc.2 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truefoundry/assistant-ui-runtime",
-  "version": "0.1.3-rc.2",
+  "version": "0.1.4",
   "description": "TrueFoundry Gateway agent runtime adapter for assistant-ui",
   "license": "Apache-2.0",
   "repository": {
@@ -50,7 +50,7 @@
   "peerDependencies": {
     "@types/react": "*",
     "react": "^18 || ^19",
-    "truefoundry-gateway-sdk": "^0.3.2-rc.1"
+    "truefoundry-gateway-sdk": "^0.4.0-rc.1"
   },
   "peerDependenciesMeta": {
     "@types/react": {
@@ -63,7 +63,7 @@
     "@types/react": "^19.2.17",
     "jsdom": "^29.1.1",
     "react": "^19.2.4",
-    "truefoundry-gateway-sdk": "0.3.2-rc.1",
+    "truefoundry-gateway-sdk": "0.4.0-rc.1",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.9"

package/src/convertTurnMessages.test.ts

@@ -178,7 +178,7 @@ async function sessionEventItemsFromTurns(
                 turnId: turn.id,
                 input: turn.input,
                 state: { status: "running" },
-                createdBy: { subjectId: "u1", subjectType: "user" },
+                createdBy: { subjectId: "u1", subjectType: "user", subjectSlug: "u1" },
                 createdAt: turn.createdAt,
             },
         });
@@ -636,7 +636,7 @@ describe("convertTurnMessages", () => {
                 input: [{ type: "user.message", content: "run tool" }],
                 state: {
                     status: "done",
-                    output: null,
+                    output: undefined,
                     requiredActions: [
                         approvalRequired({
                             id: "approval-event",
@@ -703,7 +703,7 @@ describe("convertTurnMessages", () => {
                 input: [{ type: "user.message", content: "run tool" }],
                 state: {
                     status: "done",
-                    output: null,
+                    output: undefined,
                     requiredActions: [
                         approvalRequired({
                             id: "approval-event",
@@ -787,7 +787,7 @@ describe("convertTurnMessages", () => {
                 input: [{ type: "user.message", content: "ask me" }],
                 state: {
                     status: "done",
-                    output: null,
+                    output: undefined,
                     requiredActions: [
                         responseRequired({
                             id: "resp-req-1",
@@ -859,7 +859,7 @@ describe("convertTurnMessages", () => {
                 input: [{ type: "user.message", content: "ask me" }],
                 state: {
                     status: "done",
-                    output: null,
+                    output: undefined,
                     requiredActions: [
                         responseRequired({
                             id: "resp-req-1",
@@ -2186,7 +2186,7 @@ describe("buildSnapshotFromSessionEvents", () => {
                     turnId: "t1",
                     input: [{ type: "user.message", content: "hello" }],
                     state: { status: "running" },
-                    createdBy: { subjectId: "u1", subjectType: "user" },
+                    createdBy: { subjectId: "u1", subjectType: "user", subjectSlug: "u1" },
                     createdAt,
                 },
             },
@@ -2241,7 +2241,7 @@ describe("buildSnapshotFromSessionEvents", () => {
                     turnId: "t1",
                     input: [{ type: "user.message", content: "first" }],
                     state: { status: "running" },
-                    createdBy: { subjectId: "u1", subjectType: "user" },
+                    createdBy: { subjectId: "u1", subjectType: "user", subjectSlug: "u1" },
                     createdAt,
                 },
             },
@@ -2286,7 +2286,7 @@ describe("buildSnapshotFromSessionEvents", () => {
                     turnId: "t1",
                     input: [{ type: "user.message", content: "first" }],
                     state: { status: "running" },
-                    createdBy: { subjectId: "u1", subjectType: "user" },
+                    createdBy: { subjectId: "u1", subjectType: "user", subjectSlug: "u1" },
                     createdAt,
                 },
             },
@@ -2311,7 +2311,7 @@ describe("buildSnapshotFromSessionEvents", () => {
                     turnId: "t2",
                     input: [{ type: "user.message", content: "second" }],
                     state: { status: "running" },
-                    createdBy: { subjectId: "u1", subjectType: "user" },
+                    createdBy: { subjectId: "u1", subjectType: "user", subjectSlug: "u1" },
                     createdAt,
                 },
             },
@@ -2380,7 +2380,7 @@ describe("buildSnapshotFromSessionEvents", () => {
                     turnId: id,
                     input: [{ type: "user.message", content: text }],
                     state: { status: "running" },
-                    createdBy: { subjectId: "u1", subjectType: "user" },
+                    createdBy: { subjectId: "u1", subjectType: "user", subjectSlug: "u1" },
                     createdAt,
                 },
             },

package/src/draftAgentConfig.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { mergeAgentSpec } from "./private/agentSpec.js";
+import { mergeAgentSpec, type AgentSpec } from "./private/agentSpec.js";
 import {
     resolveTrueFoundryAgentConfig,
     resolveTrueFoundryAgentRuntimeOptions,
@@ -80,14 +80,14 @@ describe("mergeAgentSpec", () => {
     });
 
     it("replaces mcpServers array wholesale", () => {
-        const base = {
+        const base: AgentSpec = {
             model: { name: "openai/gpt-4o" },
-            mcpServers: [{ name: "github", enableTools: ["@all"] }],
+            mcpServers: [{ type: "truefoundry-mcp-registry", name: "github", enableTools: ["@all"] }],
         };
         const next = mergeAgentSpec(base, {
-            mcpServers: [{ name: "slack", enableTools: ["@all"] }],
+            mcpServers: [{ type: "truefoundry-mcp-registry", name: "slack", enableTools: ["@all"] }],
         });
-        expect(next.mcpServers).toEqual([{ name: "slack", enableTools: ["@all"] }]);
+        expect(next.mcpServers).toEqual([{ type: "truefoundry-mcp-registry", name: "slack", enableTools: ["@all"] }]);
     });
 
     it("replaces skills array wholesale", () => {
@@ -102,9 +102,9 @@ describe("mergeAgentSpec", () => {
     });
 
     it("model partial update does not clear mcpServers or skills", () => {
-        const base = {
+        const base: AgentSpec = {
             model: { name: "openai/gpt-4o", params: { maxTokens: 1024 } },
-            mcpServers: [{ name: "github", enableTools: ["@all"] }],
+            mcpServers: [{ type: "truefoundry-mcp-registry", name: "github", enableTools: ["@all"] }],
             skills: [{ fqn: "acme/skill-a:1", preload: false }],
         };
         const next = mergeAgentSpec(base, {

package/src/foldPeerThreads.test.ts

@@ -142,7 +142,7 @@ describe("foldPeerThreads", () => {
                         id: "spawn-1",
                         type: "function",
                         function: { name: "create_sub_agent", arguments: "{}" },
-                    },
+                    toolInfo: { type: "truefoundry-system", name: "create_sub_agent" }, },
                 ],
             }),
         );

package/src/modelMessageImageContent.ts

@@ -74,7 +74,9 @@ function ensureModelMessageContentArray(message: ModelMessageEvent): void {
     if (Array.isArray(message.content)) {
         return;
     }
-    message.content = normalizeModelMessageContent(message);
+    // Gateway may stream `image_url` content blocks that aren't in the SDK content union yet.
+    (message as { content?: ModelMessageContentPart[] }).content =
+        normalizeModelMessageContent(message);
 }
 
 function mergeContentBlockDeltas(

package/src/private/truefoundryDraftThreadListAdapter.test.ts

@@ -104,7 +104,7 @@ describe("createTrueFoundryDraftThreadListAdapter", () => {
         const liveAgentSpec: AgentSpec = {
             model: { name: "anthropic/claude-opus-4-8" },
             instructions: "You are helpful.",
-            mcpServers: [{ name: "github", enableTools: ["@all"] }],
+            mcpServers: [{ type: "truefoundry-mcp-registry", name: "github", enableTools: ["@all"] }],
             skills: [{ fqn: "acme/skill-a:1", preload: false }],
         };
         const createDraftSession = vi.fn().mockResolvedValue(

package/src/streamTurn.test.ts

@@ -13,9 +13,9 @@ const createdAt = new Date().toISOString();
 
 function streamData(
     sequenceNumber: number,
-    event: TurnStreamData["event"],
+    event: TurnStreamData["event"] | Record<string, unknown>,
 ): TurnStreamData {
-    return { sequenceNumber, event };
+    return { sequenceNumber, event: event as TurnStreamData["event"] };
 }
 
 async function collectUpdates(
@@ -150,7 +150,7 @@ describe("streamTurn", () => {
             });
         });
 
-        it("omits previousTurnId when branching from root", async () => {
+        it("forwards previousTurnId null when branching from root", async () => {
             const execute = vi.fn(() => (async function* () {})());
             const prepareTurn = vi.fn(() => ({ execute }));
             const session = {
@@ -169,6 +169,7 @@ describe("streamTurn", () => {
 
             expect(prepareTurn).toHaveBeenCalledWith({
                 input: [{ type: "user.message", content: "first" }],
+                previousTurnId: null,
             });
         });
 
@@ -227,6 +228,93 @@ describe("streamTurn", () => {
                 },
             );
         });
+
+        it("notifies gateway turn id when turn.done errors with no content yields", async () => {
+            const gatewayTurnId = "01ky6mqzmczwt6ssyd5r02gjjc";
+            const turn = {
+                id: undefined as string | undefined,
+                execute: vi.fn(() =>
+                    (async function* () {
+                        // SDK sets turn.id when turn.created is observed.
+                        turn.id = gatewayTurnId;
+                        yield streamData(1, {
+                            type: "turn.created",
+                            createdAt,
+                            input: [{ type: "user.message", content: "hello" }],
+                        });
+                        yield streamData(2, {
+                            type: "turn.done",
+                            createdAt,
+                            state: {
+                                status: "error",
+                                message:
+                                    "Publisher Model is not servable in region us-central1.",
+                                completedAt: createdAt,
+                            },
+                        });
+                    })(),
+                ),
+            };
+            const prepareTurn = vi.fn(() => turn);
+            const session = {
+                prepareTurn,
+                cancel: vi.fn().mockResolvedValue(undefined),
+            } as unknown as AgentSession;
+            const onTurnIdAvailable = vi.fn();
+
+            await expect(
+                collectUpdates(
+                    streamTurnContent(
+                        session,
+                        new PeerThreadFoldState(),
+                        { userMessage: "hello" },
+                        new AbortController().signal,
+                        undefined,
+                        onTurnIdAvailable,
+                    ),
+                ),
+            ).rejects.toThrow("Publisher Model is not servable in region us-central1.");
+
+            expect(onTurnIdAvailable).toHaveBeenCalledTimes(1);
+            expect(onTurnIdAvailable).toHaveBeenCalledWith(gatewayTurnId);
+        });
+
+        it("does not notify when an error stream never assigns turn.id", async () => {
+            const execute = vi.fn(() =>
+                (async function* () {
+                    yield streamData(1, {
+                        type: "turn.done",
+                        createdAt,
+                        state: {
+                            status: "error",
+                            completedAt: createdAt,
+                            message: "boom",
+                        },
+                    });
+                })(),
+            );
+            const prepareTurn = vi.fn(() => ({ id: undefined, execute }));
+            const session = {
+                prepareTurn,
+                cancel: vi.fn().mockResolvedValue(undefined),
+            } as unknown as AgentSession;
+            const onTurnIdAvailable = vi.fn();
+
+            await expect(
+                collectUpdates(
+                    streamTurnContent(
+                        session,
+                        new PeerThreadFoldState(),
+                        { userMessage: "hello" },
+                        new AbortController().signal,
+                        undefined,
+                        onTurnIdAvailable,
+                    ),
+                ),
+            ).rejects.toThrow("boom");
+
+            expect(onTurnIdAvailable).not.toHaveBeenCalled();
+        });
     });
 
     describe("resumeTurnStream", () => {

package/src/streamTurn.ts

@@ -1,8 +1,9 @@
-import {
-    type AgentSession,
-    type Turn,
-    type TurnInputItem,
+import type {
+    AgentSession,
+    Turn,
+    TurnInputItem,
 } from "truefoundry-gateway-sdk/agents";
+import type { TruefoundryGatewayApi } from "truefoundry-gateway-sdk";
 
 import {
     streamTurnEvents,
@@ -18,7 +19,7 @@ export type StreamTurnOptions = {
     inputs?: RequiredActionInput[];
     /**
      * Branch anchor for `prepareTurn`. Omit for `"auto"`. Pass `null` for a fresh
-     * root turn (no `previousTurnId` field).
+     * root turn — sent as `previous_turn_id: null` on the wire.
      */
     previousTurnId?: string | null;
     /** Extra headers for the createTurn request (`execute` request options). */
@@ -61,13 +62,18 @@ export async function* streamTurnContent(
      */
     onTurnIdAvailable?: (turnId: string) => void,
 ): AsyncGenerator<TurnStreamUpdate> {
-    const previousTurnId =
+    // When previousTurnId is explicitly null, pass it through to prepareTurn so the
+    // SDK serializer emits `previous_turn_id: null` on the wire (first turn in session).
+    // The SDK type doesn't admit null, but the Fern serializer handles it correctly.
+    const previousTurnId: TruefoundryGatewayApi.PreviousTurnIdInput | null | undefined =
         options.previousTurnId === null
-            ? undefined
+            ? null
             : (options.previousTurnId ?? "auto");
     const turn = session.prepareTurn({
         input: buildTurnInput(options),
-        ...(previousTurnId != null ? { previousTurnId } : {}),
+        ...(previousTurnId !== undefined
+            ? { previousTurnId: previousTurnId as TruefoundryGatewayApi.PreviousTurnIdInput }
+            : {}),
     });
 
     const onAbort = bindAbort(session, abortSignal);
@@ -75,8 +81,15 @@ export async function* streamTurnContent(
         return;
     }
 
+    let turnIdNotified = false;
+    const notifyTurnIdIfAvailable = () => {
+        if (!turnIdNotified && turn.id != null) {
+            onTurnIdAvailable?.(turn.id);
+            turnIdNotified = true;
+        }
+    };
+
     try {
-        let turnIdNotified = false;
         for await (const update of streamTurnEvents(
             turn.execute(
                 { stream: true },
@@ -91,17 +104,17 @@ export async function* streamTurnContent(
             // After the first `turn.created` event, `turn.id` is set.
             // Notify BEFORE yielding so the caller can update its tracking
             // before the snapshot is written with the stream update.
-            if (!turnIdNotified && turn.id != null) {
-                onTurnIdAvailable?.(turn.id);
-                turnIdNotified = true;
-            }
+            notifyTurnIdIfAvailable();
             yield update;
         }
         // Handle streams that complete without yielding any content.
-        if (!turnIdNotified && turn.id != null) {
-            onTurnIdAvailable?.(turn.id);
-        }
+        notifyTurnIdIfAvailable();
     } catch (error) {
+        // Error streams often throw on `turn.done` (status=error) without ever
+        // yielding content (e.g. model not servable). `turn.id` is still set
+        // after `turn.created` — notify so edit/retry can resolve the turn.
+        // Same for AbortError after create: keep local ids aligned with gateway.
+        notifyTurnIdIfAvailable();
         if (error instanceof Error && error.name === "AbortError") {
             return;
         }

package/src/useTrueFoundryAgentMessages.ts

@@ -596,6 +596,13 @@ export function useTrueFoundryAgentMessages({
                 isContinuation && continuationTurnId != null
                     ? continuationTurnId
                     : generateId();
+            // First turns must send previousTurnId: null.
+            const isFirstTurnInSession =
+                "userMessage" in options &&
+                options.previousTurnId === undefined &&
+                snapshotRef.current.turns.length === 0 &&
+                snapshotRef.current.pendingUser == null &&
+                snapshotRef.current.activeStream == null;
 
             // Mutable ref so runStream always reads the latest ID. For new
             // user-message turns the local `generateId()` value is replaced
@@ -689,7 +696,9 @@ export function useTrueFoundryAgentMessages({
                             userMessage: options.userMessage,
                             ...(options.previousTurnId !== undefined
                                 ? { previousTurnId: options.previousTurnId }
-                                : {}),
+                                : isFirstTurnInSession
+                                  ? { previousTurnId: null }
+                                  : {}),
                             ...streamHeaders,
                         },
                         signal,

package/src/useTrueFoundryAgentRuntime.ts

@@ -30,7 +30,6 @@ import {
     createDraftSessionBridge,
     DRAFT_SESSION_LAST_UPDATED_AT_HEADER,
 } from "./private/draftSessionBridge.js";
-import { getGatewayFromPrivateClient } from "./private/getGatewayFromPrivateClient.js";
 import { MCP_AUTH_RESUME_RUN_CUSTOM_KEY } from "./mcpAuth.js";
 import { createTrueFoundryDraftThreadListAdapter } from "./private/truefoundryDraftThreadListAdapter.js";
 import { trueFoundryExtras } from "./truefoundryExtras.js";
@@ -164,9 +163,7 @@ function useTrueFoundryAgentRuntimeImpl(
                 onError?.(error);
                 throw error;
             }
-            // Same gateway.agents.downloadSandboxFile path as before, via the wrapped client.
-            const gateway = getGatewayFromPrivateClient(privateClient);
-            const response = await gateway.agents.downloadSandboxFile(sandboxId, { path });
+            const response = await privateClient.downloadSandboxFile(sandboxId, { path });
             return await response.blob();
         },
         [privateClient, sandboxId, onError],