@truefoundry/assistant-ui-runtime 0.1.9 → 0.1.10

package/src/plugins/truefoundry-agent-server-adapter/cp.ts

@@ -335,9 +335,126 @@ export async function listMcpServers(
 // ---------------------------------------------------------------------------
 
 type RawAgent = {
+    id?: string;
     name?: string;
+    latestVersionDetails?: {
+        manifest?: unknown;
+    };
+    /** Defensive: some payloads nest manifest at the top level. */
+    manifest?: unknown;
 };
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function snakeToCamelKey(key: string): string {
+    return key.replace(/_([a-z])/g, (_, letter: string) => letter.toUpperCase());
+}
+
+/** Deep snake_case → camelCase (inverse of {@link toSnakeCaseDeep}). */
+export function toCamelCaseDeep(value: unknown): unknown {
+    if (Array.isArray(value)) {
+        return value.map(toCamelCaseDeep);
+    }
+    if (isRecord(value)) {
+        const out: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[snakeToCamelKey(k)] = toCamelCaseDeep(v);
+        }
+        return out;
+    }
+    return value;
+}
+
+/**
+ * Map a CP AgentManifest (snake_case wire) → FE AgentSpec for Edit seeding.
+ * Skills/MCP keep `{ id, name }` for draft pickers plus runtime fields
+ * (`enableTools`, `preload`, `config`) so Edit → Save does not widen tool
+ * access or wipe settings. Gateway registry shapes are restored on save via
+ * normalizeAgentSpecForGateway.
+ */
+export function agentSpecFromCpManifest(manifest: unknown): TfyAgentSpec | undefined {
+    if (!isRecord(manifest)) return undefined;
+    const modelRaw = manifest.model;
+    if (!isRecord(modelRaw) || typeof modelRaw.name !== "string" || modelRaw.name === "") {
+        return undefined;
+    }
+    const model = toCamelCaseDeep(modelRaw) as TfyAgentSpec["model"];
+
+    // Catalog-shaped mounts (`id`/`name` + runtime fields). Not yet gateway
+    // registry unions — normalizeAgentSpecForGateway restores those on save.
+    const skills: Array<Record<string, unknown>> = [];
+    if (Array.isArray(manifest.skills)) {
+        for (const row of manifest.skills) {
+            if (!isRecord(row)) continue;
+            const fqn =
+                typeof row.fqn === "string" && row.fqn !== ""
+                    ? row.fqn
+                    : typeof row.id === "string" && row.id !== ""
+                      ? row.id
+                      : null;
+            if (fqn == null) continue;
+            const camel = toCamelCaseDeep(row) as Record<string, unknown>;
+            const name =
+                typeof camel.name === "string" && camel.name !== ""
+                    ? camel.name
+                    : fqn;
+            skills.push({
+                id: fqn,
+                name,
+                ...(typeof camel.preload === "boolean"
+                    ? { preload: camel.preload }
+                    : {}),
+                ...(camel.config != null ? { config: camel.config } : {}),
+            });
+        }
+    }
+
+    const mcpServers: Array<Record<string, unknown>> = [];
+    const mcpRaw = Array.isArray(manifest.mcp_servers)
+        ? manifest.mcp_servers
+        : Array.isArray(manifest.mcpServers)
+          ? manifest.mcpServers
+          : [];
+    for (const row of mcpRaw) {
+        if (!isRecord(row)) continue;
+        const camel = toCamelCaseDeep(row) as Record<string, unknown>;
+        const name =
+            typeof camel.name === "string" && camel.name !== ""
+                ? camel.name
+                : typeof camel.id === "string" && camel.id !== ""
+                  ? camel.id
+                  : null;
+        if (name == null) continue;
+        mcpServers.push({
+            id: name,
+            name,
+            ...(Array.isArray(camel.enableTools)
+                ? { enableTools: camel.enableTools }
+                : {}),
+            ...(typeof camel.preload === "boolean"
+                ? { preload: camel.preload }
+                : {}),
+            ...(camel.config != null ? { config: camel.config } : {}),
+        });
+    }
+
+    const configRaw = manifest.config;
+    const config =
+        configRaw != null ? (toCamelCaseDeep(configRaw) as TfyAgentSpec["config"]) : undefined;
+
+    return {
+        model,
+        ...(typeof manifest.instructions === "string"
+            ? { instructions: manifest.instructions }
+            : {}),
+        ...(config != null ? { config } : {}),
+        ...(skills.length > 0 ? { skills } : {}),
+        ...(mcpServers.length > 0 ? { mcpServers } : {}),
+    } as TfyAgentSpec;
+}
+
 export function normalizeAgents(raw: unknown): TfyAgentSelectorEntry[] {
     const data =
         raw != null &&
@@ -348,7 +465,15 @@ export function normalizeAgents(raw: unknown): TfyAgentSelectorEntry[] {
     const out: TfyAgentSelectorEntry[] = [];
     for (const row of data) {
         if (row.name == null || row.name === "") continue;
-        out.push({ name: row.name });
+        const manifest = row.latestVersionDetails?.manifest ?? row.manifest;
+        const agentSpec = agentSpecFromCpManifest(manifest);
+        const agentId =
+            typeof row.id === "string" && row.id !== "" ? row.id : row.name;
+        out.push({
+            name: row.name,
+            agentId,
+            ...(agentSpec != null ? { agentSpec } : {}),
+        });
     }
     return out;
 }

package/src/plugins/truefoundry-agent-server-adapter/normalizeAgentSpec.test.ts

@@ -29,6 +29,24 @@ describe("normalizeMcpMount", () => {
             name: "deepwiki-mcp",
         });
     });
+
+    it("forwards enableTools / preload / config from catalog rows", () => {
+        expect(
+            normalizeMcpMount({
+                id: "gmail",
+                name: "gmail",
+                enableTools: ["@read-only"],
+                preload: true,
+                config: { locale: "en" },
+            }),
+        ).toEqual({
+            type: "truefoundry-mcp-registry",
+            name: "gmail",
+            enableTools: ["@read-only"],
+            preload: true,
+            config: { locale: "en" },
+        });
+    });
 });
 
 describe("normalizeSkillMount", () => {
@@ -57,6 +75,22 @@ describe("normalizeSkillMount", () => {
             fqn: "agent-skill:truefoundry/skills/web:1",
         });
     });
+
+    it("forwards preload / config from catalog rows, including preload false", () => {
+        expect(
+            normalizeSkillMount({
+                id: "agent-skill:truefoundry/skills/web:1",
+                name: "web",
+                preload: false,
+                config: { timeoutMs: 1000 },
+            }),
+        ).toEqual({
+            type: "truefoundry-skills-registry",
+            fqn: "agent-skill:truefoundry/skills/web:1",
+            preload: false,
+            config: { timeoutMs: 1000 },
+        });
+    });
 });
 
 describe("normalizeAgentSpecForGateway", () => {

package/src/plugins/truefoundry-agent-server-adapter/normalizeAgentSpec.ts

@@ -20,7 +20,7 @@ export function normalizeMcpMount(
         throw new Error("mcpServers entry must be an object");
     }
     if (raw.type === "truefoundry-mcp-registry" || raw.type === "inline") {
-        return raw as TruefoundryGatewayApi.McpServer;
+        return raw as unknown as TruefoundryGatewayApi.McpServer;
     }
     const name =
         (typeof raw.name === "string" && raw.name !== "" ? raw.name : null) ??
@@ -33,7 +33,13 @@ export function normalizeMcpMount(
             "mcpServers entry needs name, mcpName, or id to mount as registry MCP",
         );
     }
-    return { type: "truefoundry-mcp-registry", name };
+    return {
+        type: "truefoundry-mcp-registry",
+        name,
+        ...(Array.isArray(raw.enableTools) ? { enableTools: raw.enableTools } : {}),
+        ...(typeof raw.preload === "boolean" ? { preload: raw.preload } : {}),
+        ...(raw.config != null ? { config: raw.config } : {}),
+    } as unknown as TruefoundryGatewayApi.McpServer;
 }
 
 export function normalizeSkillMount(
@@ -43,7 +49,7 @@ export function normalizeSkillMount(
         throw new Error("skills entry must be an object");
     }
     if (raw.type === "truefoundry-skills-registry" || raw.type === "git") {
-        return raw as TruefoundryGatewayApi.SkillMount;
+        return raw as unknown as TruefoundryGatewayApi.SkillMount;
     }
     const fqn =
         (typeof raw.fqn === "string" && raw.fqn !== "" ? raw.fqn : null) ??
@@ -56,8 +62,9 @@ export function normalizeSkillMount(
     return {
         type: "truefoundry-skills-registry",
         fqn,
-        ...(raw.preload === true ? { preload: true } : {}),
-    };
+        ...(typeof raw.preload === "boolean" ? { preload: raw.preload } : {}),
+        ...(raw.config != null ? { config: raw.config } : {}),
+    } as unknown as TruefoundryGatewayApi.SkillMount;
 }
 
 /** Rewrite UI `{id,name}` mounts so create/update draft session can serialize. */

package/src/server/types.ts

@@ -38,9 +38,13 @@ export interface ConnectorSelectorEntry {
     description?: string;
 }
 
-/** Agent selector row — UI shows name only. Host extends for metadata. */
+/** Agent selector row. Host extends for metadata; `agentSpec` enables Edit. */
 export interface AgentSelectorEntry {
     name: string;
+    /** Stable id when distinct from display `name`. Falls back to `name` when omitted. */
+    agentId?: string;
+    /** Published agent spec — required for Edit; optional for Try-only hosts. */
+    agentSpec?: AgentSpec;
 }
 
 export type SearchAgentSelectorParams = {
@@ -147,7 +151,8 @@ export type PageParams = {
 };
 
 export interface ListSessionsParams extends PageParams {
-    agentName?: string;
+    /** Host-owned agent identity filter. Hosts that key agents by name pass that name here. */
+    agentId?: string;
     /** Host-specific filter (e.g. TFY startTimestamp). */
     startTimestamp?: string;
 }
@@ -291,10 +296,17 @@ export interface AgentChatServer<
         abortSignal?: AbortSignal;
     }): AsyncIterable<TurnStreamData>;
 
-    downloadSandboxFile?(
-        sandboxId: string,
-        req: { path: string },
-    ): Promise<Blob>;
+    /**
+     * Reads a file the agent wrote inside its sandbox. Hosts whose download route is scoped to a
+     * turn resolve the sandbox from `turnId` and ignore `sandboxId`; hosts addressing sandboxes
+     * directly use `sandboxId`.
+     */
+    downloadSandboxFile?(req: {
+        sessionId: string;
+        turnId: string;
+        sandboxId: string;
+        path: string;
+    }): Promise<Blob>;
 }
 
 /**

package/src/sessionThreadMetadata.ts

@@ -0,0 +1,39 @@
+import type { RemoteThreadMetadata } from "@assistant-ui/core";
+
+import { draftSessionTitle } from "./draft/agentSpec.js";
+import type { AgentSpec, Session } from "./server/types.js";
+
+/**
+ * Title for a session row in a mixed (draft + named) thread list.
+ * Mutable sessions use draftSessionTitle (optionally falling back to
+ * `defaultAgentSpec`); named sessions use title → agentName → id.
+ */
+export function sessionDisplayTitle(
+    session: Session,
+    defaultAgentSpec?: AgentSpec,
+): string {
+    if (session.isMutable) {
+        const agentSpec = session.agentSpec ?? defaultAgentSpec;
+        if (agentSpec != null) {
+            return draftSessionTitle({
+                title: session.title,
+                agentSpec,
+            });
+        }
+    }
+    return session.title ?? session.agentName ?? session.id;
+}
+
+/** Map a Session DTO onto RemoteThreadMetadata, including display agentName in custom. */
+export function sessionToThreadMetadata(
+    session: Session,
+    title: string | undefined,
+): RemoteThreadMetadata {
+    return {
+        status: "regular",
+        remoteId: session.id,
+        title,
+        lastMessageAt: new Date(session.updatedAt),
+        ...(session.agentName != null ? { custom: { agentName: session.agentName } } : {}),
+    };
+}

package/src/truefoundryExtras.ts

@@ -26,7 +26,7 @@ export type TrueFoundryRuntimeExtras = {
     respondToToolApproval: (response: RespondToToolApprovalOptions) => void;
     respondToToolResponse: (response: RespondToToolResponseOptions) => void;
     resumeMcpAuth: () => Promise<void>;
-    downloadSandboxFile: (path: string) => Promise<Blob>;
+    downloadSandboxFile: (req: { turnId: string; path: string }) => Promise<Blob>;
     cancel: () => Promise<void>;
     resetFromTurn: (turnId: string) => Promise<void>;
     reload: () => void;

package/src/truefoundryOwnedSessionsThreadListAdapter.test.ts

@@ -61,6 +61,7 @@ describe("createTrueFoundryOwnedSessionsThreadListAdapter", () => {
                 remoteId: "s1",
                 title: "Named chat",
                 lastMessageAt: new Date("2026-06-30T12:00:00.000Z"),
+                custom: { agentName: "my-agent" },
             },
             {
                 status: "regular",
@@ -72,6 +73,21 @@ describe("createTrueFoundryOwnedSessionsThreadListAdapter", () => {
         expect(result.nextCursor).toBe("page-2");
     });
 
+    it("forwards listSessionsAgentId as agentId", async () => {
+        const listSessions = vi.fn().mockResolvedValue({ data: [] });
+        const server = mockServer({ listSessions, getSession: vi.fn() });
+
+        const adapter = createTrueFoundryOwnedSessionsThreadListAdapter({
+            server,
+            listSessionsAgentId: "agent-x",
+        });
+        await adapter.list();
+
+        expect(listSessions).toHaveBeenCalledWith(
+            expect.objectContaining({ agentId: "agent-x" }),
+        );
+    });
+
     it("falls back to model name for untitled drafts", async () => {
         const listSessions = vi.fn().mockResolvedValue({
             data: [mockDraftSession("d1", undefined, "2026-06-30T11:00:00.000Z")],

package/src/truefoundryOwnedSessionsThreadListAdapter.ts

@@ -1,43 +1,36 @@
 import type { RemoteThreadListAdapter } from "@assistant-ui/core";
 
-import type { AgentChatServer, Session } from "./server/types.js";
-import { draftSessionTitle } from "./draft/agentSpec.js";
+import type { AgentChatServer } from "./server/types.js";
 import { sessionListStartTimestamp } from "./sessionListStartTimestamp.js";
+import {
+    sessionDisplayTitle,
+    sessionToThreadMetadata,
+} from "./sessionThreadMetadata.js";
 
 const THREAD_LIST_PAGE_SIZE = 20;
 
-function ownedSessionTitle(session: Session): string {
-    if (session.isMutable && session.agentSpec != null) {
-        return draftSessionTitle({
-            title: session.title,
-            agentSpec: session.agentSpec,
-        });
-    }
-    return session.title ?? session.agentName ?? session.id;
-}
-
 /**
  * Read-only thread-list adapter backed by `AgentChatServer.listSessions`.
  * Hosts that previously used listOwnedSessions should filter in their server impl.
  */
 export function createTrueFoundryOwnedSessionsThreadListAdapter(options: {
     server: AgentChatServer;
+    /** When set, filters `listSessions` by this agent id. Omit for all chats. */
+    listSessionsAgentId?: string;
 }): RemoteThreadListAdapter {
-    const { server } = options;
+    const { server, listSessionsAgentId } = options;
 
     return {
         async list({ after } = {}) {
             const page = await server.listSessions({
+                ...(listSessionsAgentId != null ? { agentId: listSessionsAgentId } : {}),
                 limit: THREAD_LIST_PAGE_SIZE,
                 pageToken: after,
                 startTimestamp: sessionListStartTimestamp(),
             });
-            const threads = page.data.map((session) => ({
-                status: "regular" as const,
-                remoteId: session.id,
-                title: ownedSessionTitle(session),
-                lastMessageAt: new Date(session.updatedAt),
-            }));
+            const threads = page.data.map((session) =>
+                sessionToThreadMetadata(session, sessionDisplayTitle(session)),
+            );
             return {
                 threads,
                 nextCursor: page.nextPageToken ?? undefined,
@@ -52,12 +45,7 @@ export function createTrueFoundryOwnedSessionsThreadListAdapter(options: {
 
         async fetch(remoteId) {
             const session = await server.getSession({ sessionId: remoteId });
-            return {
-                status: "regular" as const,
-                remoteId: session.id,
-                title: ownedSessionTitle(session),
-                lastMessageAt: new Date(session.updatedAt),
-            };
+            return sessionToThreadMetadata(session, sessionDisplayTitle(session));
         },
 
         async rename() {},

package/src/truefoundryThreadListAdapter.test.ts

@@ -4,13 +4,19 @@ import type { AgentChatServer, Session } from "./server/index.js";
 
 import { createTrueFoundryThreadListAdapter } from "./truefoundryThreadListAdapter.js";
 
-function mockSession(id: string, title: string, updatedAt: string): Session {
+function mockSession(
+    id: string,
+    title: string,
+    updatedAt: string,
+    agentName?: string,
+): Session {
     return {
         id,
         title,
         updatedAt,
         createdAt: updatedAt,
         isMutable: false,
+        ...(agentName != null ? { agentName } : {}),
     };
 }
 
@@ -26,10 +32,10 @@ function mockServer(partial: Partial<AgentChatServer>): AgentChatServer {
 }
 
 describe("createTrueFoundryThreadListAdapter", () => {
-    it("lists the first page with limit and returns nextCursor", async () => {
+    it("lists the first page without agentId when filter is omitted", async () => {
         const listSessions = vi.fn().mockResolvedValue(
             mockListSessionsPage(
-                [mockSession("s1", "First", "2026-06-30T10:00:00.000Z")],
+                [mockSession("s1", "First", "2026-06-30T10:00:00.000Z", "my-agent")],
                 "page-2",
             ),
         );
@@ -43,40 +49,42 @@ describe("createTrueFoundryThreadListAdapter", () => {
 
         expect(listSessions).toHaveBeenCalledWith(
             expect.objectContaining({
-                agentName: "my-agent",
                 limit: 20,
                 pageToken: undefined,
                 startTimestamp: expect.any(String),
             }),
         );
+        expect(listSessions).toHaveBeenCalledWith(
+            expect.not.objectContaining({ agentId: expect.anything() }),
+        );
         expect(result.threads).toEqual([
             {
                 status: "regular",
                 remoteId: "s1",
                 title: "First",
                 lastMessageAt: new Date("2026-06-30T10:00:00.000Z"),
+                custom: { agentName: "my-agent" },
             },
         ]);
         expect(result.nextCursor).toBe("page-2");
     });
 
-    it("forwards after as pageToken for subsequent pages", async () => {
+    it("forwards listSessionsAgentId as agentId", async () => {
         const listSessions = vi.fn().mockResolvedValue(
-            mockListSessionsPage(
-                [mockSession("s2", "Second", "2026-06-29T10:00:00.000Z")],
-            ),
+            mockListSessionsPage([mockSession("s2", "Second", "2026-06-29T10:00:00.000Z")]),
         );
         const server = mockServer({ listSessions });
         const adapter = createTrueFoundryThreadListAdapter({
             server,
             agentName: "my-agent",
+            listSessionsAgentId: "filter-agent",
         });
 
         const result = await adapter.list({ after: "page-2" });
 
         expect(listSessions).toHaveBeenCalledWith(
             expect.objectContaining({
-                agentName: "my-agent",
+                agentId: "filter-agent",
                 limit: 20,
                 pageToken: "page-2",
             }),

package/src/truefoundryThreadListAdapter.ts

@@ -3,29 +3,29 @@ import type { RemoteThreadListAdapter } from "@assistant-ui/core";
 import type { AgentChatServer } from "./server/types.js";
 import { getSession } from "./sessions.js";
 import { sessionListStartTimestamp } from "./sessionListStartTimestamp.js";
+import { sessionToThreadMetadata } from "./sessionThreadMetadata.js";
 
 const THREAD_LIST_PAGE_SIZE = 20;
 
 export function createTrueFoundryThreadListAdapter(options: {
     server: AgentChatServer;
     agentName: string;
+    /** When set, filters `listSessions` by this agent id. Omit for all chats. */
+    listSessionsAgentId?: string;
 }): RemoteThreadListAdapter {
-    const { server, agentName } = options;
+    const { server, agentName, listSessionsAgentId } = options;
 
     return {
         async list({ after } = {}) {
             const page = await server.listSessions({
-                agentName,
+                ...(listSessionsAgentId != null ? { agentId: listSessionsAgentId } : {}),
                 limit: THREAD_LIST_PAGE_SIZE,
                 pageToken: after,
                 startTimestamp: sessionListStartTimestamp(),
             });
-            const threads = page.data.map((session) => ({
-                status: "regular" as const,
-                remoteId: session.id,
-                title: session.title ?? undefined,
-                lastMessageAt: new Date(session.updatedAt),
-            }));
+            const threads = page.data.map((session) =>
+                sessionToThreadMetadata(session, session.title ?? undefined),
+            );
             return {
                 threads,
                 nextCursor: page.nextPageToken ?? undefined,
@@ -39,12 +39,7 @@ export function createTrueFoundryThreadListAdapter(options: {
 
         async fetch(remoteId) {
             const session = await getSession(server, remoteId);
-            return {
-                status: "regular" as const,
-                remoteId: session.id,
-                title: session.title ?? undefined,
-                lastMessageAt: new Date(session.updatedAt),
-            };
+            return sessionToThreadMetadata(session, session.title ?? undefined);
         },
 
         async rename() {},

package/src/types.ts

@@ -29,6 +29,11 @@ type TrueFoundryAgentRuntimeBaseOptions = ExternalStoreSharedOptions & {
     onThreadIdChange?: ((threadId: string | undefined) => void) | undefined;
     onError?: ((error: unknown) => void) | undefined;
     listEventsConcurrency?: number | undefined;
+    /**
+     * Optional filter forwarded to `listSessions({ agentId })`.
+     * Omit for all chats; hosts that key agents by name pass that name as the id.
+     */
+    listSessionsAgentId?: string | undefined;
     adapters?:
         | {
               attachments?: AttachmentAdapter | undefined;

package/src/useTrueFoundryAgentRuntime.ts

@@ -152,18 +152,28 @@ function useTrueFoundryAgentRuntimeImpl(
     );
 
     const downloadSandboxFile = useCallback(
-        async (path: string) => {
+        async ({ turnId, path }: { turnId: string; path: string }) => {
             if (server.downloadSandboxFile == null) {
                 throw new Error(
                     "Downloading a sandbox file requires AgentChatServer.downloadSandboxFile.",
                 );
             }
+            if (sessionId == null) {
+                throw new Error(
+                    "This session has not been saved yet, so its files cannot be downloaded.",
+                );
+            }
             if (sandboxId == null) {
                 throw new Error("No sandbox is available yet for this session.");
             }
-            return await server.downloadSandboxFile(sandboxId, { path });
+            return await server.downloadSandboxFile({
+                sessionId,
+                turnId,
+                sandboxId,
+                path,
+            });
         },
-        [server, sandboxId],
+        [server, sessionId, sandboxId],
     );
 
     const draftExtras = useMemo(() => {
@@ -272,6 +282,7 @@ export function useTrueFoundryAgentRuntime(options: UseTrueFoundryAgentRuntimeOp
 
     const agentMode = agent.mode;
     const namedAgentName = agent.mode === "named" ? agent.agentName : undefined;
+    const listSessionsAgentId = resolved.listSessionsAgentId;
     const threadListAdapter = useMemo(() => {
         if (agentMode === "draft") {
             const draftAgent = agent as Extract<typeof agent, { mode: "draft" }>;
@@ -279,14 +290,16 @@ export function useTrueFoundryAgentRuntime(options: UseTrueFoundryAgentRuntimeOp
                 server,
                 defaultAgentSpec: draftAgent.defaultAgentSpec,
                 getAgentSpec: () => pendingAgentSpecRef.current ?? draftAgent.defaultAgentSpec,
+                listSessionsAgentId,
             });
         }
         return createTrueFoundryThreadListAdapter({
             server,
             agentName: namedAgentName!,
+            listSessionsAgentId,
         });
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [agentMode, namedAgentName, server]);
+    }, [agentMode, namedAgentName, listSessionsAgentId, server]);
 
     return useRemoteThreadListRuntime({
         allowNesting: true,