@truefoundry/assistant-ui-runtime 0.1.7 → 0.1.9

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

@@ -1,399 +1,28 @@
-import { AgentSessionClient } from "truefoundry-gateway-sdk/agents";
-import type { AgentSession } from "truefoundry-gateway-sdk/agents";
-import { PrivateAgentSessionClient } from "truefoundry-gateway-sdk/agents/private";
-import type { AgentDraftSession } from "truefoundry-gateway-sdk/agents/private";
-import type {
-    AgentChatServer,
-    ListResult,
-    TurnInputItem,
-    PreviousTurnIdInput,
-    UpdateSessionRequest,
-} from "../../server/types.js";
-import type {
-    SessionEventItem,
-    TurnEvent,
-    TurnStreamData,
-} from "../../server/events.js";
-import type {
-    TfyAgentSpec,
-    TfyCreateSessionRequest,
-    TfyListSessionsParams,
-    TfySession,
-    TfyTurn,
-    TfyTurnState,
-} from "./types.js";
+export {
+    createTrueFoundryChatServer,
+    type CreateTrueFoundryChatServerOptions,
+    type TrueFoundryChatServer
+} from "./chatServer.js";
+
+export {
+    createTrueFoundryAgentUIServer,
+    type CreateTrueFoundryAgentUIServerOptions,
+    type TrueFoundryAgentUIServer
+} from "./createTrueFoundryAgentUIServer.js";
+
+export {
+    type TfyAgentSelectorEntry, type TfyConnectorSelectorEntry, type TfyModelSelectorEntry,
+    type TfySkillSelectorEntry
+} from "./cp.js";
 
 export {
-    type TfyAgentSpec,
-    type TfySkillMount,
-    type TfyMcpServerMount,
-    type TfyModelParams,
-    type TfyRuntimeConfig,
-    type TfyResponseFormat,
-    type TfySubject,
-    type ToolsSelectorItem,
-    type ToolsSelectorTag,
     type RequireApprovalToolSelectorItem,
-    type RequireApprovalToolsSelectorTag,
-    type TfyTurn,
-    type TfyTurnState,
-    type TfyTurnCancelledReason,
-    type TfyTurnStateDoneOutput,
-    type TfySession,
-    type TfyCreateSessionRequest,
-    type TfyListSessionsParams,
-    type TfyToolInfo,
-    type TfySystemToolInfo,
-    type TfyMcpToolInfo,
-    type TfyModelMessageUsage,
-    type TfyFinishReason,
-    type TfyThreadState,
-    type TfyMcpServerInitInfo,
+    type RequireApprovalToolsSelectorTag, type TfyAgentSpec, type TfyCreateSessionRequest, type TfyFinishReason, type TfyListSessionsParams, type TfyMcpServerInitInfo, type TfyMcpServerMount, type TfyMcpToolInfo,
+    type TfyModelMessageUsage, type TfyModelParams, type TfyResponseFormat, type TfyRuntimeConfig, type TfySession, type TfySkillMount, type TfySubject, type TfySystemToolInfo, type TfyThreadState, type TfyToolInfo, type TfyTurn, type TfyTurnCancelledReason, type TfyTurnState, type TfyTurnStateDoneOutput, type ToolsSelectorItem,
+    type ToolsSelectorTag
 } from "./types.js";
 
 export {
-    isTfyToolInfo,
-    isTfySystemToolInfo,
-    isTfyMcpToolInfo,
-    getTfyUsage,
-    getTfyThreadState,
-    getTfyMcpInitServers,
+    getTfyMcpInitServers, getTfyThreadState, getTfyUsage, isTfyMcpToolInfo, isTfySystemToolInfo, isTfyToolInfo
 } from "./guards.js";
 
-type GwSession = AgentSession | AgentDraftSession;
-
-export type CreateTrueFoundryChatServerOptions = {
-    apiKey: string;
-    baseUrl: string;
-    /** Optional override — otherwise constructed from apiKey/baseUrl. */
-    client?: AgentSessionClient;
-    privateClient?: PrivateAgentSessionClient;
-    deleteSession?: (req: { sessionId: string }) => Promise<void>;
-};
-
-/**
- * Only the spec is generic. Session/Turn/list-params are the concrete Tfy*
- * types because the adapter builds them as fixed object literals — a generic
- * there would type fields that nothing ever populates. The spec is safe: the
- * gateway SDK serializes with `unrecognizedObjectKeys: "passthrough"`, so
- * host-added spec fields survive the round trip.
- */
-export type TrueFoundryChatServer<TSpec extends TfyAgentSpec = TfyAgentSpec> =
-    AgentChatServer<
-        TSpec,
-        TfySession<TSpec>,
-        TfyCreateSessionRequest<TSpec>,
-        TfyListSessionsParams,
-        UpdateSessionRequest<TSpec>,
-        TfyTurn
-    > & {
-        /** Escape hatch for hosts that still need raw gateway clients. */
-        getGatewayClients(): {
-            client: AgentSessionClient;
-            privateClient: PrivateAgentSessionClient;
-        };
-    };
-
-/** Gateway SDK errors carry the HTTP status as `statusCode`. */
-function isNotFound(error: unknown): boolean {
-    return (
-        typeof error === "object" &&
-        error !== null &&
-        (error as { statusCode?: unknown }).statusCode === 404
-    );
-}
-
-function isDraft(session: GwSession): session is AgentDraftSession {
-    return (session as AgentDraftSession).type === "session/draft";
-}
-
-function toSession<TSpec extends TfyAgentSpec>(raw: GwSession): TfySession<TSpec> {
-    const mutable = isDraft(raw);
-    return {
-        id: raw.id,
-        title: raw.title,
-        agentName: raw.agentName,
-        ...(mutable ? { agentSpec: raw.agentSpec as TSpec } : {}),
-        isMutable: mutable,
-        createdBySubject: raw.createdBySubject,
-        createdAt: raw.createdAt,
-        updatedAt: raw.updatedAt,
-    };
-}
-
-function toTurn(raw: {
-    id: string;
-    sessionId: string;
-    previousTurnId?: string | null;
-    input?: TurnInputItem[];
-    state: unknown;
-    createdBySubject: TfyTurn["createdBySubject"];
-    createdAt: string;
-}): TfyTurn {
-    return {
-        id: raw.id,
-        sessionId: raw.sessionId,
-        previousTurnId: raw.previousTurnId,
-        input: raw.input,
-        state: raw.state as TfyTurnState,
-        createdBySubject: raw.createdBySubject,
-        createdAt: raw.createdAt,
-    };
-}
-
-async function toListResult<TIn, TOut>(
-    page: {
-        data: TIn[];
-        response?: { pagination?: { nextPageToken?: string } };
-        hasNextPage?: () => boolean;
-    },
-    map: (item: TIn) => TOut,
-): Promise<ListResult<TOut>> {
-    const nextPageToken = page.response?.pagination?.nextPageToken;
-    return {
-        data: page.data.map(map),
-        ...(nextPageToken != null && nextPageToken !== ""
-            ? { nextPageToken }
-            : {}),
-    };
-}
-
-/**
- * Wraps TrueFoundry gateway clients into a flat `AgentChatServer`.
- * Named vs draft routing is fully internal — an in-memory session-type cache
- * (populated by createSession/listSessions) determines which gateway client
- * to call, falling back to a one-time probe for ids seen only in a URL.
- */
-export function createTrueFoundryChatServer<
-    TSpec extends TfyAgentSpec = TfyAgentSpec,
->(
-    opts: CreateTrueFoundryChatServerOptions,
-): TrueFoundryChatServer<TSpec> {
-    const gatewayOpts = { apiKey: opts.apiKey, baseUrl: opts.baseUrl };
-    const client = opts.client ?? new AgentSessionClient(gatewayOpts);
-    const privateClient =
-        opts.privateClient ?? new PrivateAgentSessionClient(gatewayOpts);
-
-    const sessionTypeCache = new Map<string, boolean>();
-    const sessionTypeProbes = new Map<string, Promise<boolean>>();
-
-    function cacheSessionType(session: {
-        id: string;
-        isMutable: boolean;
-    }): void {
-        sessionTypeCache.set(session.id, session.isMutable);
-    }
-
-    /**
-     * Resolving a session id straight from a URL (page reload / shared link)
-     * reaches the gateway before createSession or listSessions has cached the
-     * type, so discover it by probing the draft endpoint and falling back to
-     * the conversation endpoint. Concurrent callers share one probe.
-     */
-    async function probeSessionType(sessionId: string): Promise<boolean> {
-        const inflight = sessionTypeProbes.get(sessionId);
-        if (inflight != null) {
-            return inflight;
-        }
-        const probe = (async () => {
-            try {
-                await privateClient.getDraftSession({ draftSessionId: sessionId });
-                return true;
-            } catch (error) {
-                // Only a miss proves the id isn't a draft. Auth or transient
-                // failures would otherwise be retried as a conversation session
-                // and mislabel a real draft as named.
-                if (!isNotFound(error)) {
-                    throw error;
-                }
-                await client.getSession({ sessionId });
-                return false;
-            }
-        })();
-        sessionTypeProbes.set(sessionId, probe);
-        try {
-            const isMutable = await probe;
-            sessionTypeCache.set(sessionId, isMutable);
-            return isMutable;
-        } finally {
-            sessionTypeProbes.delete(sessionId);
-        }
-    }
-
-    async function getSessionObj(sessionId: string): Promise<GwSession> {
-        const isMutable =
-            sessionTypeCache.get(sessionId) ?? (await probeSessionType(sessionId));
-        return isMutable
-            ? privateClient.getDraftSession({ draftSessionId: sessionId })
-            : client.getSession({ sessionId });
-    }
-
-    const server: TrueFoundryChatServer<TSpec> = {
-        async createSession(req) {
-            if (req.agentSpec != null) {
-                const draft = await privateClient.createDraftSession({
-                    agentSpec: req.agentSpec,
-                    ...(req.agentName != null ? { agentName: req.agentName } : {}),
-                    ...(req.tfyMetadata != null
-                        ? { tfyMetadata: req.tfyMetadata }
-                        : {}),
-                });
-                const session = toSession<TSpec>(draft);
-                cacheSessionType(session);
-                return session;
-            }
-            if (req.agentName != null) {
-                const named = await client.createSession({
-                    agentName: req.agentName,
-                    ...(req.tfyMetadata != null
-                        ? { tfyMetadata: req.tfyMetadata }
-                        : {}),
-                });
-                const session = toSession<TSpec>(named);
-                cacheSessionType(session);
-                return session;
-            }
-            throw new Error("createSession requires agentName and/or agentSpec");
-        },
-
-        async listSessions(req) {
-            const page = await privateClient.listOwnedSessions({
-                limit: req?.limit,
-                order: req?.order,
-                pageToken: req?.pageToken,
-                startTimestamp: req?.startTimestamp,
-                endTimestamp: req?.endTimestamp,
-                ...(req?.agentName != null ? { agentName: req.agentName } : {}),
-            });
-            const result = await toListResult(page, (s) => toSession<TSpec>(s));
-            for (const session of result.data) {
-                cacheSessionType(session);
-            }
-            return result;
-        },
-
-        async getSession({ sessionId }) {
-            const raw = await getSessionObj(sessionId);
-            const session = toSession<TSpec>(raw);
-            cacheSessionType(session);
-            return session;
-        },
-
-        async updateSession(req) {
-            const raw = await getSessionObj(req.sessionId);
-            if (!isDraft(raw)) {
-                throw new Error(
-                    "updateSession: session is not mutable (isMutable=false)",
-                );
-            }
-            if (req.agentSpec != null) {
-                await raw.update({ agentSpec: req.agentSpec });
-            }
-            return toSession<TSpec>(raw);
-        },
-
-        prepareAndExecuteTurn(req: {
-            sessionId: string;
-            input?: TurnInputItem[];
-            previousTurnId?: PreviousTurnIdInput;
-            abortSignal?: AbortSignal;
-            headers?: Record<string, string>;
-        }): AsyncIterable<TurnStreamData> {
-            return (async function* () {
-                const session = await getSessionObj(req.sessionId);
-                const prepared = session.prepareTurn({
-                    input: req.input,
-                    previousTurnId: req.previousTurnId ?? "auto",
-                });
-                yield* prepared.execute(
-                    { stream: true },
-                    {
-                        ...(req.abortSignal != null
-                            ? { abortSignal: req.abortSignal }
-                            : {}),
-                        ...(req.headers != null ? { headers: req.headers } : {}),
-                    },
-                ) as AsyncIterable<TurnStreamData>;
-            })();
-        },
-
-        async cancelSession({ sessionId }) {
-            await (await getSessionObj(sessionId)).cancel();
-        },
-
-        async deleteSession({ sessionId }) {
-            if (opts.deleteSession == null) {
-                throw new Error(
-                    "deleteSession is not on the gateway SDK. Pass deleteSession to createTrueFoundryChatServer.",
-                );
-            }
-            await opts.deleteSession({ sessionId });
-        },
-
-        // The runtime's signature offers `order`, but the gateway's listTurns
-        // takes no such param — forwarding it silently did nothing.
-        async listTurns({ sessionId, limit, pageToken }) {
-            const raw = await getSessionObj(sessionId);
-            const page = await raw.listTurns({
-                ...(limit != null ? { limit } : {}),
-                ...(pageToken != null ? { pageToken } : {}),
-            });
-            return toListResult(page, (turn) => toTurn(turn));
-        },
-
-        async getTurn({ sessionId, turnId }) {
-            const raw = await getSessionObj(sessionId);
-            return toTurn(await raw.getTurn({ turnId }));
-        },
-
-        async listEvents({ sessionId, pageToken, lastTurnId, limit }) {
-            const raw = await getSessionObj(sessionId);
-            const page = await raw.listEvents({
-                ...(limit != null ? { limit } : {}),
-                ...(pageToken != null ? { pageToken } : {}),
-                ...(lastTurnId != null ? { lastTurnId } : {}),
-            });
-            return toListResult(
-                page,
-                (item) => item as SessionEventItem,
-            );
-        },
-
-        async listTurnEvents({ sessionId, turnId, limit, pageToken, order }) {
-            const raw = await getSessionObj(sessionId);
-            const turn = await raw.getTurn({ turnId });
-            const page = await turn.listEvents({
-                ...(limit != null ? { limit } : {}),
-                ...(pageToken != null ? { pageToken } : {}),
-                ...(order != null ? { order } : {}),
-            });
-            return toListResult(page, (event) => event as TurnEvent);
-        },
-
-        async *subscribeToTurn({
-            sessionId,
-            turnId,
-            afterSequenceNumber,
-            abortSignal,
-        }) {
-            const raw = await getSessionObj(sessionId);
-            const turn = await raw.getTurn({ turnId });
-            yield* turn.stream(
-                afterSequenceNumber != null ? { afterSequenceNumber } : {},
-                abortSignal != null ? { abortSignal } : {},
-            ) as AsyncIterable<TurnStreamData>;
-        },
-
-        async downloadSandboxFile(sandboxId, req) {
-            const response = await privateClient.downloadSandboxFile(
-                sandboxId,
-                req,
-            );
-            return await response.blob();
-        },
-
-        getGatewayClients: () => ({ client, privateClient }),
-    };
-
-    return server;
-}

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

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+
+import {
+    normalizeAgentSpecForGateway,
+    normalizeMcpMount,
+    normalizeSkillMount,
+} from "./normalizeAgentSpec.js";
+
+describe("normalizeMcpMount", () => {
+    it("passes through registry mounts", () => {
+        expect(
+            normalizeMcpMount({
+                type: "truefoundry-mcp-registry",
+                name: "g-calendar",
+                enableTools: ["@all"],
+            }),
+        ).toEqual({
+            type: "truefoundry-mcp-registry",
+            name: "g-calendar",
+            enableTools: ["@all"],
+        });
+    });
+
+    it("maps UI {id,name} catalog rows to registry mounts", () => {
+        expect(
+            normalizeMcpMount({ id: "deepwiki-mcp", name: "deepwiki-mcp" }),
+        ).toEqual({
+            type: "truefoundry-mcp-registry",
+            name: "deepwiki-mcp",
+        });
+    });
+});
+
+describe("normalizeSkillMount", () => {
+    it("passes through registry mounts", () => {
+        expect(
+            normalizeSkillMount({
+                type: "truefoundry-skills-registry",
+                fqn: "agent-skill:truefoundry/skills/web:1",
+                preload: false,
+            }),
+        ).toEqual({
+            type: "truefoundry-skills-registry",
+            fqn: "agent-skill:truefoundry/skills/web:1",
+            preload: false,
+        });
+    });
+
+    it("maps UI {id,name} rows (id = fqn from CP catalog) to registry mounts", () => {
+        expect(
+            normalizeSkillMount({
+                id: "agent-skill:truefoundry/skills/web:1",
+                name: "web",
+            }),
+        ).toEqual({
+            type: "truefoundry-skills-registry",
+            fqn: "agent-skill:truefoundry/skills/web:1",
+        });
+    });
+});
+
+describe("normalizeAgentSpecForGateway", () => {
+    it("rewrites UI mount rows so gateway serialization can succeed", () => {
+        const next = normalizeAgentSpecForGateway({
+            model: { name: "openai-main/gpt-4.1" },
+            mcpServers: [{ id: "gmail", name: "gmail" }] as never[],
+            skills: [
+                {
+                    id: "agent-skill:truefoundry/skills/web:1",
+                    name: "web",
+                },
+            ] as never[],
+        });
+
+        expect(next.mcpServers).toEqual([
+            { type: "truefoundry-mcp-registry", name: "gmail" },
+        ]);
+        expect(next.skills).toEqual([
+            {
+                type: "truefoundry-skills-registry",
+                fqn: "agent-skill:truefoundry/skills/web:1",
+            },
+        ]);
+    });
+});

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

@@ -0,0 +1,84 @@
+import type { TruefoundryGatewayApi } from "truefoundry-gateway-sdk";
+
+import type { TfyAgentSpec } from "./types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+/**
+ * agent-ui-sdk DraftCompositeSelector writes catalog rows as `{ id, name }`.
+ * Gateway AgentSpec mounts need discriminated registry shapes — without
+ * `type` (and skill `fqn`), Fern serialization throws JsonError before PATCH.
+ *
+ * Our CP catalog sets skill `id` = version fqn and MCP `id` = server name.
+ */
+export function normalizeMcpMount(
+    raw: unknown,
+): TruefoundryGatewayApi.McpServer {
+    if (!isRecord(raw)) {
+        throw new Error("mcpServers entry must be an object");
+    }
+    if (raw.type === "truefoundry-mcp-registry" || raw.type === "inline") {
+        return raw as TruefoundryGatewayApi.McpServer;
+    }
+    const name =
+        (typeof raw.name === "string" && raw.name !== "" ? raw.name : null) ??
+        (typeof raw.mcpName === "string" && raw.mcpName !== ""
+            ? raw.mcpName
+            : null) ??
+        (typeof raw.id === "string" && raw.id !== "" ? raw.id : null);
+    if (name == null) {
+        throw new Error(
+            "mcpServers entry needs name, mcpName, or id to mount as registry MCP",
+        );
+    }
+    return { type: "truefoundry-mcp-registry", name };
+}
+
+export function normalizeSkillMount(
+    raw: unknown,
+): TruefoundryGatewayApi.SkillMount {
+    if (!isRecord(raw)) {
+        throw new Error("skills entry must be an object");
+    }
+    if (raw.type === "truefoundry-skills-registry" || raw.type === "git") {
+        return raw as TruefoundryGatewayApi.SkillMount;
+    }
+    const fqn =
+        (typeof raw.fqn === "string" && raw.fqn !== "" ? raw.fqn : null) ??
+        (typeof raw.id === "string" && raw.id !== "" ? raw.id : null);
+    if (fqn == null) {
+        throw new Error(
+            "skills entry needs fqn or id to mount as registry skill",
+        );
+    }
+    return {
+        type: "truefoundry-skills-registry",
+        fqn,
+        ...(raw.preload === true ? { preload: true } : {}),
+    };
+}
+
+/** Rewrite UI `{id,name}` mounts so create/update draft session can serialize. */
+export function normalizeAgentSpecForGateway<TSpec extends TfyAgentSpec>(
+    spec: TSpec,
+): TSpec {
+    return {
+        ...spec,
+        ...(spec.mcpServers != null
+            ? {
+                  mcpServers: spec.mcpServers.map(
+                      normalizeMcpMount,
+                  ) as TSpec["mcpServers"],
+              }
+            : {}),
+        ...(spec.skills != null
+            ? {
+                  skills: spec.skills.map(
+                      normalizeSkillMount,
+                  ) as TSpec["skills"],
+              }
+            : {}),
+    };
+}

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

@@ -123,7 +123,7 @@ export interface TfyListSessionsParams extends ListSessionsParams {
 // Event-side types.
 //
 // These do NOT flow through AgentChatServer — its listEvents / listTurnEvents /
-// subscribeToTurn / prepareAndExecuteTurn signatures hardcode the runtime's
+// subscribeToTurn / createTurn signatures hardcode the runtime's
 // event types with no generic to override. Hosts narrow at the point of use
 // with the guards in `guards.ts`.
 // ---------------------------------------------------------------------------

package/src/server/index.ts

@@ -41,7 +41,13 @@ export type {
     ModelCatalogServer,
     ToolBase,
     ConnectorAuthType,
+    ConnectorAuthOAuth,
+    ConnectorAuthApiKey,
+    ConnectorAuthNone,
     ConnectorAuth,
+    ConnectorAuthPublicOAuth,
+    ConnectorAuthPublicApiKey,
+    ConnectorAuthPublicNone,
     ConnectorAuthPublic,
     ConnectorConfigBase,
     ConnectorBase,
@@ -50,8 +56,22 @@ export type {
     UpdateConnectorRequest,
     ConnectorCatalogServer,
     SkillBase,
+    RegistrySkill,
+    GithubSkill,
+    DefinedSkill,
+    SkillConfigBase,
+    SkillCatalogEntry,
+    CreateSkillRequestBase,
+    SelectRegistrySkillRequest,
+    ImportGithubSkillRequest,
     CreateSkillRequest,
     SkillCatalogServer,
+    SandboxConfig,
+    SandboxCatalogEntry,
+    SandboxBase,
+    CreateSandboxRequest,
+    UpdateSandboxRequest,
+    SandboxCatalogServer,
     CatalogServer,
     AgentUIServerPort,
 } from "./types.js";