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

package/src/convertTurnMessages.ts

@@ -10,12 +10,15 @@ import type {
     AgentSession,
     McpAuthRequiredEvent,
     Turn,
+    TurnCreatedEvent,
+    TurnDoneEvent,
     TurnEvent,
     TurnInputItem,
     TurnStreamData,
 } from "truefoundry-gateway-sdk/agents";
 
 import { ROOT_THREAD_ID } from "./constants.js";
+import { extractTurnUserText } from "./extractTurnUserText.js";
 import {
     buildRootAssistantContent,
     buildRootAssistantContentForIds,
@@ -24,6 +27,7 @@ import {
     ingestStreamEvent,
     ingestTurnEvent,
     PeerThreadFoldState,
+    type ThreadBucket,
 } from "./foldPeerThreads.js";
 import {
     appendMcpAuthToTurnContent,
@@ -39,9 +43,12 @@ import {
     type ProjectSessionMessagesOptions,
     type SessionTurnRecord,
     type RequiredActionsOverlay,
+    type GatewaySessionEventItem,
+    type SessionHistoryPagination,
     createEmptySessionSnapshot,
     emptyRequiredActionsOverlay,
     replaceSessionSnapshot,
+    sessionEventsToSessionRecord,
     turnToSessionRecord,
 } from "./sessionSnapshot.js";
 import {
@@ -186,12 +193,442 @@ import {
  *   `user.message`.
  * - Tool-call identity is stable via `toolCallId` across events, fold state, and
  *   assistant-ui parts.
- * - Reload (`buildSnapshotFromSession`) and live paths must produce the same
+ * - Reload (`buildSnapshotFromSessionEvents`) and live paths must produce the same
  *   per-group scoping; history uses cumulative `groupRootIds` per turn index,
  *   live uses `groupRootBaseline`.
  */
 
 const TURN_EVENTS_PAGE_SIZE = 25;
+const SESSION_EVENTS_PAGE_SIZE = 100;
+/** Cap how many event pages initial load / load-older may chain for a group boundary. */
+const MAX_HISTORY_BOUNDARY_PAGES = 10;
+
+type FetchSessionEventsOptions = {
+    /**
+     * Newest turn in the listing window (initial load only). Lists that turn and
+     * its ancestors. Omit to use the session last turn. Running-turn events are
+     * excluded by the API — subscribe to that turn for live events.
+     */
+    lastTurnId?: string;
+};
+
+type SessionEventsPageResult = {
+    /** Newest-first items from this request. */
+    itemsNewestFirst: GatewaySessionEventItem[];
+    olderPageToken?: string;
+    hasOlder: boolean;
+};
+
+/**
+ * Drops a leading incomplete turn (events before the first `turn.created`) that
+ * appears when a page boundary splits a turn.
+ */
+function trimIncompleteLeadingEvents(
+    itemsAsc: GatewaySessionEventItem[],
+): GatewaySessionEventItem[] {
+    const start = itemsAsc.findIndex((item) => item.event.type === "turn.created");
+    if (start === -1) {
+        return [];
+    }
+    return itemsAsc.slice(start);
+}
+
+/**
+ * Whether the oldest complete turn in a chronological window opens a user group.
+ * `incomplete` means we still lack a finished oldest turn (need an older page).
+ */
+function oldestCompleteTurnGroupState(
+    itemsAsc: GatewaySessionEventItem[],
+): "user-group" | "continuation" | "incomplete" {
+    const trimmed = trimIncompleteLeadingEvents(itemsAsc);
+    if (trimmed.length === 0) {
+        return "incomplete";
+    }
+    const created = trimmed[0];
+    if (created?.event.type !== "turn.created") {
+        return "incomplete";
+    }
+    const hasDone = trimmed.some(
+        (item) => item.turnId === created.turnId && item.event.type === "turn.done",
+    );
+    if (!hasDone) {
+        return "incomplete";
+    }
+    return extractTurnUserText(created.event.input) != null
+        ? "user-group"
+        : "continuation";
+}
+
+async function fetchSessionEventsPage(
+    session: AgentSession,
+    options?: FetchSessionEventsOptions & { pageToken?: string },
+): Promise<SessionEventsPageResult> {
+    const page = await session.listEvents({
+        limit: SESSION_EVENTS_PAGE_SIZE,
+        ...(options?.lastTurnId != null ? { lastTurnId: options.lastTurnId } : {}),
+        ...(options?.pageToken != null ? { pageToken: options.pageToken } : {}),
+    });
+    const response = page.response as {
+        pagination?: { nextPageToken?: string };
+    };
+    const olderPageToken = response.pagination?.nextPageToken;
+    const hasOlder =
+        typeof page.hasNextPage === "function"
+            ? page.hasNextPage()
+            : olderPageToken != null && olderPageToken !== "";
+    return {
+        itemsNewestFirst: page.data as GatewaySessionEventItem[],
+        ...(olderPageToken != null && olderPageToken !== ""
+            ? { olderPageToken }
+            : {}),
+        hasOlder,
+    };
+}
+
+/**
+ * Fetches pages until the chronological window starts on a complete user-message
+ * turn group (or history is exhausted).
+ */
+async function fetchSessionEventsWindow(
+    session: AgentSession,
+    options?: FetchSessionEventsOptions & { pageToken?: string },
+): Promise<{
+    itemsAsc: GatewaySessionEventItem[];
+    olderPageToken?: string;
+    hasOlder: boolean;
+}> {
+    let itemsNewestFirst: GatewaySessionEventItem[] = [];
+    let pageToken = options?.pageToken;
+    let olderPageToken: string | undefined;
+    let hasOlder = false;
+
+    for (let pageCount = 0; pageCount < MAX_HISTORY_BOUNDARY_PAGES; pageCount++) {
+        const page = await fetchSessionEventsPage(session, {
+            ...options,
+            ...(pageToken != null ? { pageToken } : {}),
+        });
+        itemsNewestFirst = [...itemsNewestFirst, ...page.itemsNewestFirst];
+        olderPageToken = page.olderPageToken;
+        hasOlder = page.hasOlder;
+
+        const itemsAsc = trimIncompleteLeadingEvents([...itemsNewestFirst].reverse());
+        const groupState = oldestCompleteTurnGroupState(itemsAsc);
+        if (groupState === "user-group" || !hasOlder) {
+            return {
+                itemsAsc,
+                ...(olderPageToken != null ? { olderPageToken } : {}),
+                hasOlder,
+            };
+        }
+
+        if (olderPageToken == null) {
+            return { itemsAsc, hasOlder: false };
+        }
+        pageToken = olderPageToken;
+    }
+
+    const itemsAsc = trimIncompleteLeadingEvents([...itemsNewestFirst].reverse());
+    return {
+        itemsAsc,
+        ...(olderPageToken != null ? { olderPageToken } : {}),
+        hasOlder,
+    };
+}
+
+/**
+ * Fetches session-level events via `session.listEvents()`. The API returns pages
+ * in desc order (newest first); the collected array is reversed before returning
+ * so callers receive events in chronological (asc) order.
+ *
+ * Used by rewind/edit paths that need the full ancestor window.
+ */
+async function fetchAllSessionEvents(
+    session: AgentSession,
+    options?: FetchSessionEventsOptions,
+): Promise<GatewaySessionEventItem[]> {
+    const items: GatewaySessionEventItem[] = [];
+    for await (const item of await session.listEvents({
+        limit: SESSION_EVENTS_PAGE_SIZE,
+        ...(options?.lastTurnId != null ? { lastTurnId: options.lastTurnId } : {}),
+    })) {
+        items.push(item as GatewaySessionEventItem);
+    }
+    items.reverse();
+    return items;
+}
+
+function cloneThreadBucket(bucket: ThreadBucket): ThreadBucket {
+    return {
+        events: new Map(bucket.events),
+        modelMessageIds: [...bucket.modelMessageIds],
+        toolResults: new Map(bucket.toolResults),
+        pendingApprovals: new Map(bucket.pendingApprovals),
+        approvalDecisions: new Map(bucket.approvalDecisions),
+        pendingResponses: new Map(bucket.pendingResponses),
+        done: bucket.done,
+        ...(bucket.title != null ? { title: bucket.title } : {}),
+        ...(bucket.agentInfo != null ? { agentInfo: bucket.agentInfo } : {}),
+    };
+}
+
+/** Prepends older fold state ahead of the currently loaded fold (scroll-up). */
+export function prependFoldState(
+    older: PeerThreadFoldState,
+    newer: PeerThreadFoldState,
+): PeerThreadFoldState {
+    const result = new PeerThreadFoldState();
+    const threadIds = new Set([...older.threads.keys(), ...newer.threads.keys()]);
+    for (const threadId of threadIds) {
+        const olderBucket = older.threads.get(threadId);
+        const newerBucket = newer.threads.get(threadId);
+        if (olderBucket == null && newerBucket != null) {
+            result.threads.set(threadId, cloneThreadBucket(newerBucket));
+            continue;
+        }
+        if (newerBucket == null && olderBucket != null) {
+            result.threads.set(threadId, cloneThreadBucket(olderBucket));
+            continue;
+        }
+        if (olderBucket == null || newerBucket == null) {
+            continue;
+        }
+        result.threads.set(threadId, {
+            events: new Map([...olderBucket.events, ...newerBucket.events]),
+            modelMessageIds: [
+                ...olderBucket.modelMessageIds,
+                ...newerBucket.modelMessageIds,
+            ],
+            toolResults: new Map([
+                ...olderBucket.toolResults,
+                ...newerBucket.toolResults,
+            ]),
+            pendingApprovals: new Map([
+                ...olderBucket.pendingApprovals,
+                ...newerBucket.pendingApprovals,
+            ]),
+            approvalDecisions: new Map([
+                ...olderBucket.approvalDecisions,
+                ...newerBucket.approvalDecisions,
+            ]),
+            pendingResponses: new Map([
+                ...olderBucket.pendingResponses,
+                ...newerBucket.pendingResponses,
+            ]),
+            done: newerBucket.done || olderBucket.done,
+            ...(newerBucket.title != null || olderBucket.title != null
+                ? { title: newerBucket.title ?? olderBucket.title }
+                : {}),
+            ...(newerBucket.agentInfo != null || olderBucket.agentInfo != null
+                ? { agentInfo: newerBucket.agentInfo ?? olderBucket.agentInfo }
+                : {}),
+        });
+    }
+    for (const [threadId, link] of older.threadParents) {
+        result.threadParents.set(threadId, link);
+    }
+    for (const [threadId, link] of newer.threadParents) {
+        result.threadParents.set(threadId, link);
+    }
+    return result;
+}
+
+/**
+ * Ingests a chronologically ordered list of session-level event items into the
+ * snapshot. `turn.created` marks the start of a turn (provides user input),
+ * content events are folded as usual, and `turn.done` finalises the turn record
+ * and pushes it to `snapshot.turns`.
+ *
+ * `onTurnComplete` is called after each `turn.done` with the partially-built
+ * snapshot so callers can update UI progressively. The fold state is correct at
+ * that point for every turn up to and including the just-completed one.
+ */
+function ingestSessionEventsIntoSnapshot(
+    snapshot: SessionSnapshot,
+    items: GatewaySessionEventItem[],
+    onTurnComplete?: (snap: SessionSnapshot) => void,
+): void {
+    let currentTurnId: string | null = null;
+    let currentCreatedEvent: TurnCreatedEvent | null = null;
+    let currentContentEvents: TurnEvent[] = [];
+    let beforeCount = 0;
+
+    for (const item of items) {
+        const { turnId, event } = item;
+
+        if (event.type === "turn.created") {
+            currentTurnId = turnId;
+            currentCreatedEvent = event;
+            currentContentEvents = [];
+            beforeCount =
+                snapshot.fold.threads.get(ROOT_THREAD_ID)?.modelMessageIds.length ?? 0;
+        } else if (event.type === "turn.done") {
+            if (currentTurnId == null || currentCreatedEvent == null) {
+                continue;
+            }
+
+            const afterBucket = snapshot.fold.threads.get(ROOT_THREAD_ID);
+            const rootModelMessageIds = (afterBucket?.modelMessageIds ?? []).slice(
+                beforeCount,
+            );
+
+            const sandboxEvent = currentContentEvents.find(
+                (ev): ev is Extract<TurnEvent, { type: "sandbox.created" }> =>
+                    ev.type === "sandbox.created",
+            );
+
+            applyUserToolResponsesToFold(
+                snapshot.fold,
+                currentCreatedEvent.input ?? [],
+            );
+            snapshot.turns.push(
+                sessionEventsToSessionRecord(
+                    currentTurnId,
+                    currentCreatedEvent,
+                    event,
+                    rootModelMessageIds,
+                    sandboxEvent?.sandboxId,
+                ),
+            );
+
+            // Pass a new object reference so React's Object.is check in
+            // useState sees a changed value and schedules a re-render.
+            // The snapshot is mutated in place throughout this loop, so
+            // passing `snapshot` directly would make every tick look identical
+            // to React after the first setSnapshot call.
+            onTurnComplete?.(replaceSessionSnapshot(snapshot, {}));
+
+            currentTurnId = null;
+            currentCreatedEvent = null;
+            currentContentEvents = [];
+        } else {
+            if (currentTurnId != null) {
+                ingestTurnEvent(snapshot.fold, event as TurnEvent);
+                currentContentEvents.push(event as TurnEvent);
+            }
+        }
+    }
+}
+
+function attachRunningTurn(
+    snapshot: SessionSnapshot,
+    runningTurn: Turn | undefined,
+): SessionSnapshot {
+    if (runningTurn == null) {
+        return snapshot;
+    }
+    const pendingUserText = extractTurnUserText(runningTurn.input);
+    return replaceSessionSnapshot(snapshot, {
+        runningTurn,
+        unstable_resume: true as const,
+        groupRootBaseline: computeGroupRootBaseline(snapshot.turns),
+        ...(pendingUserText
+            ? {
+                  pendingUser: {
+                      turnId: runningTurn.id,
+                      content: extractTurnUserMessageContent(runningTurn.input),
+                      createdAt: new Date(runningTurn.createdAt),
+                  },
+              }
+            : {}),
+    });
+}
+
+/**
+ * Builds a session snapshot using the session-level `listEvents` API.
+ *
+ * Loads the newest event page (extending only when a page boundary splits a
+ * turn group), then leaves older pages for `prependOlderSessionHistory`.
+ * Only `listTurns({ limit: 1 })` is called first to detect a currently-running
+ * turn (the session-level API does not return events for the running turn).
+ *
+ * `onProgress` is called after each complete turn is ingested so callers can
+ * update the UI progressively while the processing loop runs.
+ */
+export async function buildSnapshotFromSessionEvents(
+    session: AgentSession,
+    onProgress?: (snap: SessionSnapshot) => void,
+): Promise<SessionSnapshot> {
+    // Detect a running turn with a single listTurns page — do not drain pagination.
+    const turnsPage = await session.listTurns({ limit: 1 });
+    const newestTurn = turnsPage.data[0] as Turn | undefined;
+    const runningTurn =
+        newestTurn?.state?.status === "running" ? newestTurn : undefined;
+
+    const window = await fetchSessionEventsWindow(session);
+    const historyPagination: SessionHistoryPagination = {
+        hasOlder: window.hasOlder,
+        ...(window.olderPageToken != null
+            ? { olderPageToken: window.olderPageToken }
+            : {}),
+    };
+
+    const snapshot = createEmptySessionSnapshot();
+    ingestSessionEventsIntoSnapshot(snapshot, window.itemsAsc, onProgress);
+
+    const withHistory = replaceSessionSnapshot(snapshot, {
+        historyEvents: window.itemsAsc,
+        historyPagination,
+    });
+
+    return attachRunningTurn(withHistory, runningTurn);
+}
+
+/**
+ * Fetches the next older `listEvents` window and prepends it onto `snapshot`
+ * without tearing down live stream / pending UI state.
+ */
+export async function prependOlderSessionHistory(
+    session: AgentSession,
+    snapshot: SessionSnapshot,
+): Promise<SessionSnapshot> {
+    const pagination = snapshot.historyPagination;
+    if (pagination?.hasOlder !== true || pagination.olderPageToken == null) {
+        return snapshot;
+    }
+
+    const window = await fetchSessionEventsWindow(session, {
+        pageToken: pagination.olderPageToken,
+    });
+    if (window.itemsAsc.length === 0) {
+        return replaceSessionSnapshot(snapshot, {
+            historyPagination: { hasOlder: false },
+        });
+    }
+
+    const olderSnap = createEmptySessionSnapshot();
+    ingestSessionEventsIntoSnapshot(olderSnap, window.itemsAsc);
+
+    const existingIds = new Set(snapshot.turns.map((turn) => turn.id));
+    const olderTurns = olderSnap.turns.filter((turn) => !existingIds.has(turn.id));
+    const mergedFold = prependFoldState(olderSnap.fold, snapshot.fold);
+    const historyEvents = [
+        ...window.itemsAsc,
+        ...(snapshot.historyEvents ?? []),
+    ];
+    const olderRootIds = olderTurns.flatMap(
+        (turn) => turn.rootModelMessageIds ?? [],
+    );
+
+    return replaceSessionSnapshot(snapshot, {
+        fold: mergedFold,
+        turns: [...olderTurns, ...snapshot.turns],
+        historyEvents,
+        historyPagination: {
+            hasOlder: window.hasOlder,
+            ...(window.olderPageToken != null
+                ? { olderPageToken: window.olderPageToken }
+                : {}),
+        },
+        ...(snapshot.groupRootBaseline != null
+            ? {
+                  groupRootBaseline: [
+                      ...olderRootIds,
+                      ...snapshot.groupRootBaseline,
+                  ],
+              }
+            : {}),
+    });
+}
 
 export type ConvertTurnsResult = {
     messages: ThreadMessage[];
@@ -775,25 +1212,25 @@ export async function buildSnapshotFromSession(
     session: AgentSession,
     concurrency: number = DEFAULT_LIST_EVENTS_CONCURRENCY,
 ): Promise<SessionSnapshot> {
-    const turns: Turn[] = [];
-    for await (const turn of await session.listTurns()) {
-        turns.push(turn);
+    // Completed history comes from session-level listEvents. The session API
+    // excludes the running turn — hydrate that turn via turn.listEvents so
+    // convertTurnsToThreadMessages still surfaces in-flight content.
+    const snapshot = await buildSnapshotFromSessionEvents(session);
+    if (snapshot.runningTurn == null) {
+        return snapshot;
     }
-    turns.reverse();
 
-    const eventArrays = await fetchAllTurnEventsWithConcurrency(turns, concurrency);
-
-    const snapshot = createEmptySessionSnapshot();
-    const runningTurn = ingestTurnsIntoSnapshot(snapshot, turns, eventArrays);
+    const turn = snapshot.runningTurn;
+    const eventArrays = await fetchAllTurnEventsWithConcurrency([turn], concurrency);
+    ingestTurnsIntoSnapshot(snapshot, [turn], eventArrays);
 
+    // Hydrated in-flight content lives in `turns` / `fold` now — drop the
+    // reconnect seed so projection does not duplicate the user bubble.
     return replaceSessionSnapshot(snapshot, {
-        ...(runningTurn != null
-            ? {
-                  runningTurn,
-                  unstable_resume: true as const,
-                  groupRootBaseline: computeGroupRootBaseline(snapshot.turns),
-              }
-            : {}),
+        runningTurn: turn,
+        unstable_resume: true as const,
+        groupRootBaseline: computeGroupRootBaseline(snapshot.turns),
+        pendingUser: undefined,
     });
 }
 
@@ -803,11 +1240,7 @@ export async function buildSnapshotBeforeTurn(
     beforeTurnId: string,
     concurrency: number = DEFAULT_LIST_EVENTS_CONCURRENCY,
 ): Promise<SessionSnapshot> {
-    const turns: Turn[] = [];
-    for await (const turn of await session.listTurns()) {
-        turns.push(turn);
-    }
-    turns.reverse();
+    const turns = await listSessionTurnsOrdered(session);
 
     const beforeIndex = turns.findIndex((turn) => turn.id === beforeTurnId);
     if (beforeIndex === -1) {
@@ -821,7 +1254,7 @@ export async function buildSnapshotBeforeTurn(
 export async function buildSnapshotBeforeTurnIndex(
     session: AgentSession,
     turnIndex: number,
-    concurrency: number = DEFAULT_LIST_EVENTS_CONCURRENCY,
+    _concurrency: number = DEFAULT_LIST_EVENTS_CONCURRENCY,
     orderedTurns?: Turn[],
 ): Promise<SessionSnapshot> {
     if (turnIndex <= 0) {
@@ -830,16 +1263,16 @@ export async function buildSnapshotBeforeTurnIndex(
 
     const turns = orderedTurns ?? (await listSessionTurnsOrdered(session));
     const turnsToInclude = turns.slice(0, turnIndex);
-    if (turnsToInclude.length === 0) {
+    const lastTurnId = turnsToInclude.at(-1)?.id;
+    if (lastTurnId == null) {
         return createEmptySessionSnapshot();
     }
 
-    const eventArrays = await fetchAllTurnEventsWithConcurrency(
-        turnsToInclude,
-        concurrency,
-    );
+    // Anchor the session events window at the newest included turn so the
+    // ancestor chain matches `[turns[0], …, turns[turnIndex - 1]]`.
+    const items = await fetchAllSessionEvents(session, { lastTurnId });
     const snapshot = createEmptySessionSnapshot();
-    ingestTurnsIntoSnapshot(snapshot, turnsToInclude, eventArrays);
+    ingestSessionEventsIntoSnapshot(snapshot, items);
     return snapshot;
 }
 
@@ -856,6 +1289,16 @@ export async function resolveGatewayBranchPreviousTurnId(
     return turns[turnIndex - 1]?.id ?? null;
 }
 
+/** Resolves `previousTurnId` by turn id so partial history windows stay correct. */
+export async function resolveGatewayBranchPreviousTurnIdForTurn(
+    session: AgentSession,
+    turnId: string,
+): Promise<string | null> {
+    const turns = await listSessionTurnsOrdered(session);
+    const turnIndex = turns.findIndex((turn) => turn.id === turnId);
+    return resolveGatewayBranchPreviousTurnId(session, turnIndex, turns);
+}
+
 async function listSessionTurnsOrdered(session: AgentSession): Promise<Turn[]> {
     const turns: Turn[] = [];
     for await (const turn of await session.listTurns()) {

package/src/createSubAgent.ts

@@ -1,8 +1,16 @@
 import type { ToolCall } from "truefoundry-gateway-sdk/agents";
 
-export function isCreateSubAgentToolCall(toolCall: Pick<ToolCall, "toolInfo">): boolean {
-    return (
-        toolCall.toolInfo.type === "truefoundry-system" &&
-        toolCall.toolInfo.name === "create_sub_agent"
-    );
+export function isCreateSubAgentToolCall(
+    toolCall: Pick<ToolCall, "toolInfo" | "function">,
+): boolean {
+    // Gateway may attach truefoundry-system toolInfo on persisted turns, but streamed
+    // model.message tool calls often only carry function.name. Without the fallback,
+    // foldPeerThreads never nests child threads under the spawning tool call.
+    if (
+        toolCall.toolInfo?.type === "truefoundry-system" &&
+        toolCall.toolInfo?.name === "create_sub_agent"
+    ) {
+        return true;
+    }
+    return toolCall.function?.name === "create_sub_agent";
 }

package/src/draftAgentConfig.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 
-import { mergeAgentSpec } from "./agentSpec.js";
+import { mergeAgentSpec } from "./private/agentSpec.js";
 import { resolveTrueFoundryAgentConfig } from "./types.js";
 
 describe("resolveTrueFoundryAgentConfig", () => {

package/src/foldPeerThreads.test.ts

@@ -129,6 +129,62 @@ describe("foldPeerThreads", () => {
         });
     });
 
+    it("attaches sub-agent artifact from thread.created before child model messages arrive", () => {
+        const state = new PeerThreadFoldState();
+
+        ingestTurnEvent(
+            state,
+            modelMessage({
+                id: "root-msg",
+                threadId: ROOT_THREAD_ID,
+                toolCalls: [
+                    {
+                        id: "spawn-1",
+                        type: "function",
+                        function: { name: "create_sub_agent", arguments: "{}" },
+                    },
+                ],
+            }),
+        );
+
+        ingestTurnEvent(
+            state,
+            threadCreated({
+                id: "t-created",
+                threadId: "child-1",
+                title: "gateway-usage-7d",
+                agentInfo: {
+                    type: "dynamic",
+                    name: "gateway-usage-7d",
+                    input: "run queries",
+                },
+                parent: { threadId: ROOT_THREAD_ID, toolCallId: "spawn-1" },
+            }),
+        );
+
+        const parts = buildRootAssistantContent(state);
+        const spawn = parts.find((part) => part.type === "tool-call");
+        expect(spawn?.type).toBe("tool-call");
+        if (spawn?.type !== "tool-call") {
+            return;
+        }
+
+        expect(spawn.messages).toBeUndefined();
+        expect(spawn.artifact).toEqual({
+            subAgents: [
+                {
+                    threadId: "child-1",
+                    title: "gateway-usage-7d",
+                    agentInfo: {
+                        type: "dynamic",
+                        name: "gateway-usage-7d",
+                        input: "run queries",
+                    },
+                },
+            ],
+        });
+    });
+
     it("classifies stream events by thread id", () => {
         const state = new PeerThreadFoldState();
         expect(

package/src/foldPeerThreads.ts

@@ -389,11 +389,17 @@ function attachSubAgentMessages(
                 });
             }
         }
-        if (messages.length === 0) {
+        if (messages.length === 0 && subAgents.length === 0) {
             return part;
         }
 
         const artifact: SubAgentArtifact = { subAgents };
+        // thread.created (title, agentInfo) arrives before the child's first model.message.
+        // Attach artifact-only so UI can render the sub-agent header immediately; see README
+        // SubAgentArtifact / MessagePartPrimitive.Messages in agent-ui ToolCallContainer.
+        if (messages.length === 0) {
+            return { ...part, artifact };
+        }
         return { ...part, messages, artifact };
     });
 }