@truefoundry/assistant-ui-runtime 0.1.5 → 0.1.6

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

@@ -0,0 +1,130 @@
+/**
+ * Point-of-use narrowing for the event half of the gateway protocol.
+ *
+ * `AgentChatServer` hardcodes the runtime's event types on listEvents,
+ * listTurnEvents, subscribeToTurn and prepareAndExecuteTurn — there is no
+ * generic to override them from here. So instead of typing those channels,
+ * hosts call these guards on the values they receive.
+ *
+ * They validate rather than cast: this data comes off the network, and the
+ * runtime types the relevant fields as `unknown` precisely because nothing
+ * has checked them yet.
+ */
+
+import type {
+    TfyMcpServerInitInfo,
+    TfyMcpToolInfo,
+    TfyModelMessageUsage,
+    TfySystemToolInfo,
+    TfyThreadState,
+    TfyToolInfo,
+} from "./types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null;
+}
+
+function hasNumbers<K extends string>(
+    value: unknown,
+    keys: readonly K[],
+): value is Record<string, unknown> & Record<K, number> {
+    return isRecord(value) && keys.every((key) => typeof value[key] === "number");
+}
+
+/**
+ * Identifies built-in tools such as `ask_user_question` and `create_sub_agent`.
+ * Note `toolInfo` is legitimately absent on streamed deltas, so callers must
+ * keep their `function.name` fallback rather than treating absence as an error.
+ */
+export function isTfySystemToolInfo(
+    toolInfo: unknown,
+): toolInfo is TfySystemToolInfo {
+    return (
+        isRecord(toolInfo) &&
+        toolInfo.type === "truefoundry-system" &&
+        typeof toolInfo.name === "string"
+    );
+}
+
+/** Carries `serverId` / `serverName`, so the UI can attribute a call to its MCP server. */
+export function isTfyMcpToolInfo(toolInfo: unknown): toolInfo is TfyMcpToolInfo {
+    return (
+        isRecord(toolInfo) &&
+        toolInfo.type === "mcp" &&
+        typeof toolInfo.name === "string" &&
+        typeof toolInfo.serverId === "string" &&
+        typeof toolInfo.serverName === "string"
+    );
+}
+
+export function isTfyToolInfo(toolInfo: unknown): toolInfo is TfyToolInfo {
+    return isTfySystemToolInfo(toolInfo) || isTfyMcpToolInfo(toolInfo);
+}
+
+const USAGE_BREAKDOWN_KEYS = [
+    "harness",
+    "skills",
+    "instructions",
+    "toolDefinitions",
+    "messages",
+] as const;
+
+/**
+ * Token usage including the TrueFoundry-specific `inputTokensBreakdown`, which
+ * attributes input tokens across harness, skills, instructions, tool
+ * definitions and messages.
+ */
+export function getTfyUsage(
+    source: { usage?: unknown } | null | undefined,
+): TfyModelMessageUsage | undefined {
+    const usage = source?.usage;
+    if (!hasNumbers(usage, ["inputTokens", "outputTokens"])) {
+        return undefined;
+    }
+    if (!hasNumbers(usage.inputTokensBreakdown, USAGE_BREAKDOWN_KEYS)) {
+        return undefined;
+    }
+    return usage as unknown as TfyModelMessageUsage;
+}
+
+/**
+ * Completion state of a sub-agent thread. The runtime types `thread.done`'s
+ * `state` as `unknown`, so a sub-agent that errored is otherwise
+ * indistinguishable from one that succeeded.
+ */
+export function getTfyThreadState(
+    event: { state?: unknown } | null | undefined,
+): TfyThreadState | undefined {
+    const state = event?.state;
+    if (!isRecord(state)) {
+        return undefined;
+    }
+    if (state.status === "done" && isRecord(state.output)) {
+        return state as unknown as TfyThreadState;
+    }
+    if (state.status === "error" && typeof state.error === "string") {
+        return state as unknown as TfyThreadState;
+    }
+    return undefined;
+}
+
+/**
+ * Servers from an `mcp.initialize` event, including each one's `transportType`.
+ * The runtime models this event with an index signature, so the array is
+ * `unknown` until checked.
+ */
+export function getTfyMcpInitServers(
+    event: { mcpServers?: unknown } | null | undefined,
+): TfyMcpServerInitInfo[] | undefined {
+    const servers = event?.mcpServers;
+    if (!Array.isArray(servers)) {
+        return undefined;
+    }
+    const valid = servers.every(
+        (server) =>
+            isRecord(server) &&
+            typeof server.id === "string" &&
+            typeof server.name === "string",
+    );
+    return valid ? (servers as TfyMcpServerInitInfo[]) : undefined;
+}

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

@@ -0,0 +1,359 @@
+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 {
+    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,
+} from "./types.js";
+
+export {
+    isTfyToolInfo,
+    isTfySystemToolInfo,
+    isTfyMcpToolInfo,
+    getTfyUsage,
+    getTfyThreadState,
+    getTfyMcpInitServers,
+} 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;
+        };
+    };
+
+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. No try/catch fallback, no double network calls.
+ */
+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>();
+
+    function cacheSessionType(session: {
+        id: string;
+        isMutable: boolean;
+    }): void {
+        sessionTypeCache.set(session.id, session.isMutable);
+    }
+
+    function getSessionObj(sessionId: string): Promise<GwSession> {
+        const isMutable = sessionTypeCache.get(sessionId);
+        if (isMutable === true) {
+            return privateClient.getDraftSession({ draftSessionId: sessionId });
+        }
+        if (isMutable === false) {
+            return client.getSession({ sessionId });
+        }
+        throw new Error(
+            `Cannot resolve session "${sessionId}": session type not cached. ` +
+                `Ensure createSession or listSessions was called first.`,
+        );
+    }
+
+    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/types.ts

@@ -0,0 +1,135 @@
+/**
+ * TrueFoundry-specific type extensions over the runtime's generic bases.
+ *
+ * The runtime defines minimal bases (SkillMount = {id,name}, McpServerMount =
+ * {id,name}, AgentSpec.config = unknown, etc.) that hosts extend via generics.
+ *
+ * This file builds the concrete TrueFoundry types by:
+ *  - Importing the runtime's AgentSpec as the base to extend.
+ *  - Importing concrete sub-types from the gateway SDK namespace rather than
+ *    re-defining them — they're purely gateway concepts.
+ *  - Composing a TfyAgentSpec that satisfies both the runtime's
+ *    `TSpec extends AgentSpec` constraint and the gateway SDK's AgentSpec shape.
+ */
+
+import type {
+    AgentSpec,
+    CreateSessionRequest,
+    ListSessionsParams,
+    Session,
+    Turn,
+    TurnState,
+} from "../../server/types.js";
+import type { TruefoundryGatewayApi } from "truefoundry-gateway-sdk";
+
+// ---------------------------------------------------------------------------
+// Re-exports — gateway sub-types surfaced for host convenience
+// ---------------------------------------------------------------------------
+
+export type TfyRuntimeConfig = TruefoundryGatewayApi.RuntimeConfig;
+export type TfyResponseFormat = TruefoundryGatewayApi.ResponseFormat;
+export type TfyModelParams = TruefoundryGatewayApi.ModelParams;
+export type TfySubject = TruefoundryGatewayApi.Subject;
+
+// ---------------------------------------------------------------------------
+// Tool selector helpers (mirrors gateway SDK enum values)
+// ---------------------------------------------------------------------------
+
+export type ToolsSelectorTag = "@all" | "@read-only";
+export type RequireApprovalToolsSelectorTag = "@all" | "@write" | "@destructive";
+export type ToolsSelectorItem = ToolsSelectorTag | string;
+export type RequireApprovalToolSelectorItem = RequireApprovalToolsSelectorTag | string;
+
+// ---------------------------------------------------------------------------
+// Runtime mount bases — derived from AgentSpec, which the runtime does export
+// (SkillMount / McpServerMount themselves are not part of its public API).
+// ---------------------------------------------------------------------------
+
+type RuntimeSkillMount = NonNullable<NonNullable<AgentSpec["skills"]>[number]>;
+type RuntimeMcpServerMount = NonNullable<NonNullable<AgentSpec["mcpServers"]>[number]>;
+
+// ---------------------------------------------------------------------------
+// Mounts — runtime base + gateway fields (fqn, type, url, tool selectors)
+// ---------------------------------------------------------------------------
+
+// Both gateway types are unions (git vs registry source, inline vs registry
+// server), so these must be intersections — an interface cannot `extends` a
+// union, and doing so silently degrades to the runtime base under skipLibCheck.
+export type TfySkillMount = RuntimeSkillMount & TruefoundryGatewayApi.SkillMount;
+
+export type TfyMcpServerMount = RuntimeMcpServerMount & TruefoundryGatewayApi.McpServer;
+
+// ---------------------------------------------------------------------------
+// AgentSpec — the concrete TrueFoundry agent definition
+// ---------------------------------------------------------------------------
+
+export interface TfyAgentSpec extends AgentSpec {
+    model: TruefoundryGatewayApi.Model;
+    skills?: TfySkillMount[];
+    mcpServers?: TfyMcpServerMount[];
+    config?: TruefoundryGatewayApi.RuntimeConfig;
+    responseFormat?: TruefoundryGatewayApi.ResponseFormat;
+    messages?: TruefoundryGatewayApi.AgentSpecUserMessage[];
+}
+
+// ---------------------------------------------------------------------------
+// Turn — runtime base narrowed to the gateway's concrete state shapes
+// ---------------------------------------------------------------------------
+
+export type TfyTurnCancelledReason = TruefoundryGatewayApi.TurnStateCancelledReason;
+export type TfyTurnStateDoneOutput = TruefoundryGatewayApi.TurnStateDoneOutput;
+
+type RuntimeTurnStateDone = Extract<TurnState, { status: "done" }>;
+type RuntimeTurnStateCancelled = Extract<TurnState, { status: "cancelled" }>;
+
+/**
+ * The runtime types `output` as `unknown` and `reason` as bare `string`. The
+ * gateway sends a model message and one of four reasons — `cancelled-for-next-turn`
+ * in particular is routine and should not render like a failure.
+ */
+export type TfyTurnState =
+    | Exclude<TurnState, { status: "done" | "cancelled" }>
+    | (Omit<RuntimeTurnStateDone, "output"> & { output?: TfyTurnStateDoneOutput })
+    | (Omit<RuntimeTurnStateCancelled, "reason"> & { reason: TfyTurnCancelledReason });
+
+export interface TfyTurn extends Turn {
+    state: TfyTurnState;
+    createdBySubject: TfySubject;
+}
+
+// ---------------------------------------------------------------------------
+// Session and request params — runtime bases + gateway-only fields
+// ---------------------------------------------------------------------------
+
+export interface TfySession<TSpec extends TfyAgentSpec = TfyAgentSpec>
+    extends Session<TSpec> {
+    createdBySubject: TfySubject;
+}
+
+export interface TfyCreateSessionRequest<TSpec extends TfyAgentSpec = TfyAgentSpec>
+    extends CreateSessionRequest<TSpec> {
+    /** Sent as `x-tfy-metadata`, persisted server-side as `request_metadata`. */
+    tfyMetadata?: string;
+}
+
+export interface TfyListSessionsParams extends ListSessionsParams {
+    /** Inclusive upper bound on `createdAt` (ISO-8601). */
+    endTimestamp?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Event-side types.
+//
+// These do NOT flow through AgentChatServer — its listEvents / listTurnEvents /
+// subscribeToTurn / prepareAndExecuteTurn 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`.
+// ---------------------------------------------------------------------------
+
+export type TfyToolInfo = TruefoundryGatewayApi.ToolInfo;
+export type TfySystemToolInfo = TruefoundryGatewayApi.TrueFoundrySystemToolInfo;
+export type TfyMcpToolInfo = TruefoundryGatewayApi.McpToolInfo;
+export type TfyModelMessageUsage = TruefoundryGatewayApi.ModelMessageUsage;
+export type TfyFinishReason = TruefoundryGatewayApi.FinishReason;
+export type TfyThreadState = TruefoundryGatewayApi.ThreadState;
+export type TfyMcpServerInitInfo = TruefoundryGatewayApi.McpServerInitInfo;