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

package/src/createSubAgent.ts

@@ -0,0 +1,8 @@
+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"
+    );
+}

package/src/draftAgentConfig.test.ts

@@ -0,0 +1,88 @@
+import { describe, expect, it } from "vitest";
+
+import { mergeAgentSpec } from "./agentSpec.js";
+import { resolveTrueFoundryAgentConfig } from "./types.js";
+
+describe("resolveTrueFoundryAgentConfig", () => {
+    it("supports legacy agentName", () => {
+        expect(resolveTrueFoundryAgentConfig({ agentName: "my-agent" })).toEqual({
+            mode: "named",
+            agentName: "my-agent",
+        });
+    });
+
+    it("prefers explicit agentName over named config", () => {
+        expect(
+            resolveTrueFoundryAgentConfig({
+                agent: { mode: "named", agentName: "ignored" },
+                agentName: "preferred",
+            }),
+        ).toEqual({
+            mode: "named",
+            agentName: "preferred",
+        });
+    });
+
+    it("returns draft config unchanged", () => {
+        const spec = { model: { name: "openai/gpt-4o" } };
+        expect(
+            resolveTrueFoundryAgentConfig({
+                agent: { mode: "draft", defaultAgentSpec: spec },
+            }),
+        ).toEqual({
+            mode: "draft",
+            defaultAgentSpec: spec,
+        });
+    });
+});
+
+describe("mergeAgentSpec", () => {
+    it("deep-merges model params", () => {
+        const base = {
+            model: {
+                name: "anthropic/claude-sonnet-4-6",
+                params: { maxTokens: 1024, temperature: 0.5 },
+            },
+        };
+        const next = mergeAgentSpec(base, {
+            model: { params: { temperature: 1.0 } },
+        });
+        expect(next.model.params).toEqual({ maxTokens: 1024, temperature: 1.0 });
+    });
+
+    it("replaces mcpServers array wholesale", () => {
+        const base = {
+            model: { name: "openai/gpt-4o" },
+            mcpServers: [{ name: "github", enableTools: ["@all"] }],
+        };
+        const next = mergeAgentSpec(base, {
+            mcpServers: [{ name: "slack", enableTools: ["@all"] }],
+        });
+        expect(next.mcpServers).toEqual([{ name: "slack", enableTools: ["@all"] }]);
+    });
+
+    it("replaces skills array wholesale", () => {
+        const base = {
+            model: { name: "openai/gpt-4o" },
+            skills: [{ fqn: "acme/skill-a:1", preload: false }],
+        };
+        const next = mergeAgentSpec(base, {
+            skills: [{ fqn: "acme/skill-b:2", preload: true }],
+        });
+        expect(next.skills).toEqual([{ fqn: "acme/skill-b:2", preload: true }]);
+    });
+
+    it("model partial update does not clear mcpServers or skills", () => {
+        const base = {
+            model: { name: "openai/gpt-4o", params: { maxTokens: 1024 } },
+            mcpServers: [{ name: "github", enableTools: ["@all"] }],
+            skills: [{ fqn: "acme/skill-a:1", preload: false }],
+        };
+        const next = mergeAgentSpec(base, {
+            model: { name: "anthropic/claude-sonnet-4-6" },
+        });
+        expect(next.model.name).toBe("anthropic/claude-sonnet-4-6");
+        expect(next.mcpServers).toEqual(base.mcpServers);
+        expect(next.skills).toEqual(base.skills);
+    });
+});

package/src/draftSessionBridge.ts

@@ -0,0 +1,28 @@
+import type { TrueFoundryGateway } from "truefoundry-gateway-sdk";
+
+import type { AgentSpec } from "./agentSpec.js";
+
+export type DraftSessionBridge = {
+    syncAgentSpec: (draftSessionId: string, agentSpec: AgentSpec) => Promise<void>;
+    getDraftAgentSpec: (draftSessionId: string) => Promise<AgentSpec>;
+};
+
+export function createDraftSessionBridge(
+    gateway: TrueFoundryGateway,
+): DraftSessionBridge {
+    async function getDraft(draftSessionId: string) {
+        const response = await gateway.agents.private.draftSessions.get(draftSessionId);
+        return response.data;
+    }
+
+    return {
+        async getDraftAgentSpec(draftSessionId) {
+            const draft = await getDraft(draftSessionId);
+            return draft.agentSpec;
+        },
+
+        async syncAgentSpec(draftSessionId, agentSpec) {
+            await gateway.agents.private.draftSessions.update(draftSessionId, { agentSpec });
+        },
+    };
+}

package/src/extractTurnUserText.ts

@@ -0,0 +1,21 @@
+import type { Turn } from "truefoundry-gateway-sdk/agents";
+
+export function extractTurnUserText(input: Turn["input"]): string {
+    const parts: string[] = [];
+    for (const item of input ?? []) {
+        if (item.type !== "user.message") {
+            continue;
+        }
+        const { content } = item;
+        if (typeof content === "string") {
+            parts.push(content);
+            continue;
+        }
+        for (const part of content) {
+            if (part.type === "text") {
+                parts.push(part.text);
+            }
+        }
+    }
+    return parts.join("\n").trim();
+}

package/src/foldPeerThreads.test.ts

@@ -0,0 +1,386 @@
+import { describe, expect, it } from "vitest";
+import type {
+    ModelMessageEvent,
+    ThreadCreatedEvent,
+    TurnEvent,
+} from "truefoundry-gateway-sdk/agents";
+
+import { ROOT_THREAD_ID } from "./constants.js";
+import {
+    buildRootAssistantContent,
+    ingestStreamEvent,
+    ingestTurnEvent,
+    PeerThreadFoldState,
+    recordToolApprovalInFold,
+    recordToolResponseInFold,
+} from "./foldPeerThreads.js";
+
+const createdAt = new Date().toISOString();
+
+function modelMessage(
+    event: Omit<ModelMessageEvent, "type" | "createdAt">,
+): ModelMessageEvent {
+    return { type: "model.message", createdAt, ...event };
+}
+
+function threadCreated(
+    event: Omit<ThreadCreatedEvent, "type" | "createdAt">,
+): ThreadCreatedEvent {
+    return { type: "thread.created", createdAt, ...event };
+}
+
+describe("foldPeerThreads", () => {
+    it("ignores sandbox.created (no threadId, not foldable) without crashing", () => {
+        const state = new PeerThreadFoldState();
+        const sandboxEvent = {
+            type: "sandbox.created" as const,
+            id: "sandbox-evt",
+            createdAt,
+            sandboxId: "sbx-123",
+        } as unknown as TurnEvent;
+
+        expect(() => ingestTurnEvent(state, sandboxEvent)).not.toThrow();
+        expect(ingestStreamEvent(state, sandboxEvent)).toBe(false);
+        expect(buildRootAssistantContent(state)).toEqual([]);
+    });
+
+    it("anchors root content on main without inference", () => {
+        const state = new PeerThreadFoldState();
+
+        const rootMessage: TurnEvent = modelMessage({
+            id: "m1",
+            threadId: ROOT_THREAD_ID,
+            content: "hello",
+        });
+
+        ingestTurnEvent(state, rootMessage);
+
+        expect(buildRootAssistantContent(state)).toEqual([
+            { type: "text", text: "hello" },
+        ]);
+    });
+
+    it("captures sub-agent title from thread.created and tags nested messages", () => {
+        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: "{}" },
+                        toolInfo: { type: "truefoundry-system", name: "create_sub_agent" },
+                    },
+                ],
+            }),
+        );
+
+        ingestTurnEvent(
+            state,
+            threadCreated({
+                id: "t-created",
+                threadId: "child-1",
+                title: "Research agent",
+                agentInfo: { type: "dynamic", name: "researcher", input: "do research" },
+                parent: { threadId: ROOT_THREAD_ID, toolCallId: "spawn-1" },
+            }),
+        );
+
+        ingestTurnEvent(
+            state,
+            modelMessage({
+                id: "child-msg",
+                threadId: "child-1",
+                content: "working",
+            }),
+        );
+
+        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.artifact).toEqual({
+            subAgents: [
+                {
+                    threadId: "child-1",
+                    title: "Research agent",
+                    agentInfo: {
+                        type: "dynamic",
+                        name: "researcher",
+                        input: "do research",
+                    },
+                },
+            ],
+        });
+
+        const nested = spawn.messages?.[0];
+        expect(nested?.metadata.custom.subAgent).toEqual({
+            threadId: "child-1",
+            title: "Research agent",
+            name: "researcher",
+            input: "do research",
+        });
+    });
+
+    it("classifies stream events by thread id", () => {
+        const state = new PeerThreadFoldState();
+        expect(
+            ingestStreamEvent(
+                state,
+                threadCreated({
+                    id: "e1",
+                    threadId: "child-1",
+                    title: "Child",
+                    agentInfo: { type: "dynamic", name: "child", input: "x" },
+                    parent: { threadId: ROOT_THREAD_ID, toolCallId: "tc" },
+                }),
+            ),
+        ).toBe(true);
+        expect(state.threads.get("child-1")?.title).toBe("Child");
+    });
+
+    it("ingests tool.response_required and marks tool calls as pending responses", () => {
+        const state = new PeerThreadFoldState();
+
+        ingestTurnEvent(
+            state,
+            modelMessage({
+                id: "model-1",
+                threadId: ROOT_THREAD_ID,
+                toolCalls: [
+                    {
+                        id: "question-1",
+                        type: "function",
+                        function: {
+                            name: "ask_user_question",
+                            arguments: JSON.stringify({
+                                question: "Pick one",
+                                options: ["A", "B"],
+                            }),
+                        },
+                        toolInfo: { type: "truefoundry-system", name: "ask_user_question" },
+                    },
+                ],
+            }),
+        );
+
+        ingestTurnEvent(state, {
+            type: "tool.response_required",
+            id: "resp-req-1",
+            createdAt,
+            threadId: ROOT_THREAD_ID,
+            toolCalls: [{ id: "question-1", sourceEventId: "model-1" }],
+        });
+
+        const bucket = state.threads.get(ROOT_THREAD_ID)!;
+        expect(bucket.pendingResponses.get("question-1")).toMatchObject({
+            id: "question-1",
+            sourceEventId: "model-1",
+            question: "Pick one",
+            options: ["A", "B"],
+        });
+
+        const parts = buildRootAssistantContent(state);
+        const toolCall = parts.find((part) => part.type === "tool-call");
+        expect(toolCall?.type).toBe("tool-call");
+        if (toolCall?.type !== "tool-call") {
+            return;
+        }
+        expect(toolCall.interrupt).toEqual({
+            type: "human",
+            payload: { question: "Pick one", options: ["A", "B"] },
+        });
+    });
+
+    it("recordToolResponseInFold clears pending and attaches result", () => {
+        const state = new PeerThreadFoldState();
+
+        ingestTurnEvent(
+            state,
+            modelMessage({
+                id: "model-1",
+                threadId: ROOT_THREAD_ID,
+                toolCalls: [
+                    {
+                        id: "question-1",
+                        type: "function",
+                        function: {
+                            name: "ask_user_question",
+                            arguments: JSON.stringify({
+                                question: "Pick one",
+                                options: ["A", "B"],
+                            }),
+                        },
+                        toolInfo: { type: "truefoundry-system", name: "ask_user_question" },
+                    },
+                ],
+            }),
+        );
+
+        ingestTurnEvent(state, {
+            type: "tool.response_required",
+            id: "resp-req-1",
+            createdAt,
+            threadId: ROOT_THREAD_ID,
+            toolCalls: [{ id: "question-1", sourceEventId: "model-1" }],
+        });
+
+        recordToolResponseInFold(state, {
+            toolCallId: "question-1",
+            content: "A",
+        });
+
+        const bucket = state.threads.get(ROOT_THREAD_ID)!;
+        expect(bucket.pendingResponses.has("question-1")).toBe(false);
+        expect(bucket.toolResults.get("question-1")).toBe("A");
+
+        const toolCall = buildRootAssistantContent(state).find(
+            (part) => part.type === "tool-call",
+        );
+        expect(toolCall?.type).toBe("tool-call");
+        if (toolCall?.type !== "tool-call") {
+            return;
+        }
+        expect(toolCall.result).toBe("A");
+        expect(toolCall.interrupt).toBeUndefined();
+    });
+
+    it("ingests tool.response and clears pending ask-user state", () => {
+        const state = new PeerThreadFoldState();
+
+        ingestTurnEvent(
+            state,
+            modelMessage({
+                id: "model-1",
+                threadId: ROOT_THREAD_ID,
+                toolCalls: [
+                    {
+                        id: "question-1",
+                        type: "function",
+                        function: {
+                            name: "ask_user_question",
+                            arguments: JSON.stringify({
+                                question: "Pick one",
+                                options: ["A", "B"],
+                            }),
+                        },
+                        toolInfo: { type: "truefoundry-system", name: "ask_user_question" },
+                    },
+                ],
+            }),
+        );
+
+        ingestTurnEvent(state, {
+            type: "tool.response_required",
+            id: "resp-req-1",
+            createdAt,
+            threadId: ROOT_THREAD_ID,
+            toolCalls: [{ id: "question-1", sourceEventId: "model-1" }],
+        });
+
+        ingestTurnEvent(state, {
+            type: "tool.response",
+            id: "resp-1",
+            createdAt,
+            threadId: ROOT_THREAD_ID,
+            toolCallId: "question-1",
+            content: "A",
+        });
+
+        const bucket = state.threads.get(ROOT_THREAD_ID)!;
+        expect(bucket.pendingResponses.has("question-1")).toBe(false);
+        expect(bucket.toolResults.get("question-1")).toBe("A");
+
+        const toolCall = buildRootAssistantContent(state).find(
+            (part) => part.type === "tool-call",
+        );
+        expect(toolCall?.type).toBe("tool-call");
+        if (toolCall?.type !== "tool-call") {
+            return;
+        }
+        expect(toolCall.result).toBe("A");
+        expect(toolCall.interrupt).toBeUndefined();
+    });
+
+    function seedPendingApproval(): PeerThreadFoldState {
+        const state = new PeerThreadFoldState();
+        ingestTurnEvent(
+            state,
+            modelMessage({
+                id: "model-1",
+                threadId: ROOT_THREAD_ID,
+                toolCalls: [
+                    {
+                        id: "tool-1",
+                        type: "function",
+                        function: { name: "run_shell", arguments: "{}" },
+                        toolInfo: {
+                            type: "mcp",
+                            name: "run_shell",
+                            serverId: "srv-1",
+                            serverName: "shell",
+                        },
+                    },
+                ],
+            }),
+        );
+        ingestTurnEvent(state, {
+            type: "tool.approval_required",
+            id: "appr-req-1",
+            createdAt,
+            threadId: ROOT_THREAD_ID,
+            toolCalls: [{ id: "tool-1", sourceEventId: "model-1" }],
+        });
+        return state;
+    }
+
+    it("recordToolApprovalInFold resolves a pending approval on allow", () => {
+        const state = seedPendingApproval();
+        const bucket = state.threads.get(ROOT_THREAD_ID)!;
+        expect(bucket.pendingApprovals.has("tool-1")).toBe(true);
+
+        recordToolApprovalInFold(state, { toolCallId: "tool-1", approved: true });
+
+        // Once decided, the approval must leave the pending set so the turn is
+        // not re-paused (and the user re-prompted) for it after resume.
+        expect(bucket.pendingApprovals.has("tool-1")).toBe(false);
+
+        const toolCall = buildRootAssistantContent(state).find(
+            (part) => part.type === "tool-call",
+        );
+        if (toolCall?.type !== "tool-call") {
+            throw new Error("expected a tool-call part");
+        }
+        expect(toolCall.approval?.approved).toBe(true);
+    });
+
+    it("recordToolApprovalInFold synthesizes an error result on deny", () => {
+        const state = seedPendingApproval();
+
+        recordToolApprovalInFold(state, {
+            toolCallId: "tool-1",
+            approved: false,
+            reason: "not allowed",
+        });
+
+        const bucket = state.threads.get(ROOT_THREAD_ID)!;
+        expect(bucket.pendingApprovals.has("tool-1")).toBe(false);
+
+        const toolCall = buildRootAssistantContent(state).find(
+            (part) => part.type === "tool-call",
+        );
+        if (toolCall?.type !== "tool-call") {
+            throw new Error("expected a tool-call part");
+        }
+        expect(toolCall.approval?.approved).toBe(false);
+        expect(toolCall.isError).toBe(true);
+        expect(toolCall.result).toEqual({ error: "not allowed" });
+    });
+});