@truefoundry/assistant-ui-runtime 0.1.6-rc.0 → 0.1.6

package/src/plugins/truefoundry-agent-server-adapter/README.md

@@ -0,0 +1,178 @@
+# truefoundry-agent-server-adapter
+
+A gateway plugin that wraps [`truefoundry-gateway-sdk`](https://www.npmjs.com/package/truefoundry-gateway-sdk) into an [`AgentChatServer`](../../README.md#server-port-agentchatserver) for `@truefoundry/assistant-ui-runtime`.
+
+Named vs draft session routing is internal — you pass `apiKey` / `baseUrl` (or pre-built clients) and get a flat server the runtime can call.
+
+### Used by the [runtime Quick start](../../README.md#quick-start)
+
+---
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [`createTrueFoundryChatServer` options](#createtruefoundrychatserver-options)
+- [Named vs draft sessions](#named-vs-draft-sessions)
+- [Types & guards](#types--guards)
+- [Extending `TfyAgentSpec`](#extending-tfyagentspec)
+- [Exports](#exports)
+- [License](#license)
+
+---
+
+## Installation
+
+Shipped as a subpath of the runtime package (also re-exported from the main entry):
+
+```bash
+npm install @truefoundry/assistant-ui-runtime truefoundry-gateway-sdk
+# or
+pnpm add @truefoundry/assistant-ui-runtime truefoundry-gateway-sdk
+# or
+yarn add @truefoundry/assistant-ui-runtime truefoundry-gateway-sdk
+```
+
+`truefoundry-gateway-sdk` is an optional peer of the runtime — required only when using this plugin.
+
+---
+
+## Quick start
+
+```tsx
+import { createTrueFoundryChatServer } from "@truefoundry/assistant-ui-runtime";
+// Isolated import (no React):
+// import { createTrueFoundryChatServer } from "@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter";
+
+const server = createTrueFoundryChatServer({
+  apiKey: process.env.TFY_API_KEY!,
+  baseUrl: process.env.TFY_GATEWAY_URL!,
+});
+
+// Pass `server` to useTrueFoundryAgentRuntime({ server, agentName })
+```
+
+That returns a `TrueFoundryChatServer` implementing `AgentChatServer` with concrete `TfySession` / `TfyTurn` types.
+
+---
+
+## `createTrueFoundryChatServer` options
+
+| Option | Type | Required | Description |
+| ------ | ---- | -------- | ----------- |
+| `apiKey` | `string` | ✅ | TrueFoundry API key |
+| `baseUrl` | `string` | ✅ | Gateway base URL |
+| `client` | `AgentSessionClient` | — | Override the named-session client (otherwise built from `apiKey` / `baseUrl`) |
+| `privateClient` | `PrivateAgentSessionClient` | — | Override the draft/private client |
+| `deleteSession` | `(req: { sessionId: string }) => Promise<void>` | — | Optional delete hook — not on the gateway SDK today; pass your own if needed |
+
+```tsx
+const server = createTrueFoundryChatServer({
+  apiKey,
+  baseUrl,
+  // client, privateClient, deleteSession — optional overrides
+});
+```
+
+Escape hatch for hosts that still need raw gateway clients:
+
+```tsx
+const { client, privateClient } = server.getGatewayClients();
+```
+
+---
+
+## Named vs draft sessions
+
+Routing is fully internal via an in-memory session-type cache populated by `createSession` / `listSessions`:
+
+| Create with | Session kind | Client used |
+| ----------- | ------------ | ----------- |
+| `agentName` | Named (immutable) | `AgentSessionClient` |
+| `agentSpec` | Draft (mutable) | `PrivateAgentSessionClient` |
+
+`updateSession` is only allowed when `session.isMutable === true` (draft). Calling it on a named session throws.
+
+> Ensure `createSession` or `listSessions` ran before `getSession` / turn methods for a given id — the adapter must have cached the session type.
+
+---
+
+## Types & guards
+
+The plugin surfaces concrete gateway types for hosts that need them:
+
+```tsx
+import type {
+  TfyAgentSpec,
+  TfySkillMount,
+  TfyMcpServerMount,
+  TfySession,
+  TfyTurn,
+  TfyTurnState,
+  TfyToolInfo,
+} from "@truefoundry/assistant-ui-runtime";
+
+import {
+  isTfyToolInfo,
+  isTfySystemToolInfo,
+  isTfyMcpToolInfo,
+  getTfyUsage,
+  getTfyThreadState,
+  getTfyMcpInitServers,
+} from "@truefoundry/assistant-ui-runtime";
+```
+
+Use the type guards to narrow event fields typed as `unknown` by the runtime.
+
+---
+
+## Extending `TfyAgentSpec`
+
+Only the **spec** is generic. Session / turn / list-params stay as concrete `Tfy*` types. Host-added spec fields survive the round trip because the gateway SDK serializes with `unrecognizedObjectKeys: "passthrough"`:
+
+```tsx
+import {
+  createTrueFoundryChatServer,
+  type TfyAgentSpec,
+  type TrueFoundryChatServer,
+} from "@truefoundry/assistant-ui-runtime";
+
+interface MySpec extends TfyAgentSpec {
+  workspaceId: string;
+  deploymentId: string;
+}
+
+const server: TrueFoundryChatServer<MySpec> = createTrueFoundryChatServer<MySpec>({
+  apiKey,
+  baseUrl,
+});
+
+const session = await server.getSession({ sessionId: "ses_abc" });
+console.log(session.agentSpec?.workspaceId); // string | undefined
+```
+
+---
+
+## Exports
+
+| Export | Kind | Purpose |
+| ------ | ---- | ------- |
+| `createTrueFoundryChatServer` | Function | Build a `TrueFoundryChatServer` from gateway credentials / clients |
+| `CreateTrueFoundryChatServerOptions` | Type | Options bag above |
+| `TrueFoundryChatServer<TSpec>` | Type | `AgentChatServer` + `getGatewayClients()` |
+| `TfyAgentSpec`, `TfySession`, `TfyTurn`, … | Types | Concrete gateway DTOs |
+| `isTfyToolInfo`, `getTfyUsage`, … | Guards / helpers | Narrow / extract gateway event fields |
+
+Import path:
+
+```ts
+"@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter"
+```
+
+(or the main `@truefoundry/assistant-ui-runtime` entry, which re-exports these symbols).
+
+---
+
+## License
+
+See [LICENSE](../../../../LICENSE).

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

@@ -0,0 +1,113 @@
+import { describe, expect, it } from "vitest";
+import {
+    getTfyMcpInitServers,
+    getTfyThreadState,
+    getTfyUsage,
+    isTfyMcpToolInfo,
+    isTfySystemToolInfo,
+    isTfyToolInfo,
+} from "./guards.js";
+
+const usage = {
+    inputTokens: 10,
+    outputTokens: 5,
+    inputTokensBreakdown: {
+        harness: 1,
+        skills: 2,
+        instructions: 3,
+        toolDefinitions: 4,
+        messages: 5,
+    },
+};
+
+describe("tool info", () => {
+    it("discriminates on type", () => {
+        const system = { type: "truefoundry-system", name: "ask_user_question" };
+        const mcp = {
+            type: "mcp",
+            name: "search",
+            serverId: "s1",
+            serverName: "github",
+        };
+
+        expect(isTfySystemToolInfo(system)).toBe(true);
+        expect(isTfyMcpToolInfo(system)).toBe(false);
+        expect(isTfyMcpToolInfo(mcp)).toBe(true);
+        expect(isTfySystemToolInfo(mcp)).toBe(false);
+        expect(isTfyToolInfo(system) && isTfyToolInfo(mcp)).toBe(true);
+    });
+
+    it("rejects an mcp shape missing its server attribution", () => {
+        expect(isTfyMcpToolInfo({ type: "mcp", name: "search" })).toBe(false);
+    });
+
+    it("rejects absent and non-object values", () => {
+        for (const value of [undefined, null, "mcp", 0, []]) {
+            expect(isTfyToolInfo(value)).toBe(false);
+        }
+    });
+});
+
+describe("getTfyUsage", () => {
+    it("returns usage with its breakdown intact", () => {
+        expect(getTfyUsage({ usage })).toEqual(usage);
+    });
+
+    it("rejects usage whose breakdown is absent or incomplete", () => {
+        expect(getTfyUsage({ usage: { inputTokens: 1, outputTokens: 2 } })).toBeUndefined();
+        expect(
+            getTfyUsage({
+                usage: { ...usage, inputTokensBreakdown: { harness: 1 } },
+            }),
+        ).toBeUndefined();
+    });
+
+    it("returns undefined when there is no usage at all", () => {
+        expect(getTfyUsage({})).toBeUndefined();
+        expect(getTfyUsage(undefined)).toBeUndefined();
+    });
+});
+
+describe("getTfyThreadState", () => {
+    it("accepts done with output and error with a message", () => {
+        const done = { status: "done", output: { type: "model.message" } };
+        const errored = { status: "error", error: "boom" };
+
+        expect(getTfyThreadState({ state: done })).toEqual(done);
+        expect(getTfyThreadState({ state: errored })).toEqual(errored);
+    });
+
+    it("rejects done without output, since the gateway always sends one", () => {
+        expect(getTfyThreadState({ state: { status: "done" } })).toBeUndefined();
+    });
+
+    it("rejects an unknown status", () => {
+        expect(getTfyThreadState({ state: { status: "running" } })).toBeUndefined();
+        expect(getTfyThreadState({})).toBeUndefined();
+    });
+});
+
+describe("getTfyMcpInitServers", () => {
+    it("returns the servers when every entry is identifiable", () => {
+        const servers = [
+            { id: "a", name: "github", transportType: "http" },
+            { id: "b", name: "slack" },
+        ];
+        expect(getTfyMcpInitServers({ mcpServers: servers })).toEqual(servers);
+    });
+
+    it("rejects the whole array if any entry is malformed", () => {
+        expect(
+            getTfyMcpInitServers({ mcpServers: [{ id: "a", name: "ok" }, { id: "b" }] }),
+        ).toBeUndefined();
+    });
+
+    it("rejects a non-array", () => {
+        expect(getTfyMcpInitServers({ mcpServers: {} })).toBeUndefined();
+        expect(getTfyMcpInitServers({})).toBeUndefined();
+    });
+
+    it("accepts an empty list", () => {
+        expect(getTfyMcpInitServers({ mcpServers: [] })).toEqual([]);
+    });
+});

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

@@ -4,18 +4,61 @@ import { PrivateAgentSessionClient } from "truefoundry-gateway-sdk/agents/privat
 import type { AgentDraftSession } from "truefoundry-gateway-sdk/agents/private";
 import type {
     AgentChatServer,
-    AgentSpec,
     ListResult,
-    Session,
-    Turn,
     TurnInputItem,
     PreviousTurnIdInput,
+    UpdateSessionRequest,
 } from "../../server/types.js";
 import type {
+    SessionEventItem,
     TurnEvent,
     TurnStreamData,
-    SessionEventItem,
 } 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;
 
@@ -28,26 +71,42 @@ export type CreateTrueFoundryChatServerOptions = {
     deleteSession?: (req: { sessionId: string }) => Promise<void>;
 };
 
-export type TrueFoundryChatServer = AgentChatServer & {
-    /** Escape hatch for hosts that still need raw gateway clients. */
-    getGatewayClients(): {
-        client: AgentSessionClient;
-        privateClient: PrivateAgentSessionClient;
+/**
+ * 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(raw: GwSession): Session {
+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 AgentSpec } : {}),
+        ...(mutable ? { agentSpec: raw.agentSpec as TSpec } : {}),
         isMutable: mutable,
+        createdBySubject: raw.createdBySubject,
         createdAt: raw.createdAt,
         updatedAt: raw.updatedAt,
     };
@@ -58,15 +117,17 @@ function toTurn(raw: {
     sessionId: string;
     previousTurnId?: string | null;
     input?: TurnInputItem[];
-    state: Turn["state"];
+    state: unknown;
+    createdBySubject: TfyTurn["createdBySubject"];
     createdAt: string;
-}): Turn {
+}): TfyTurn {
     return {
         id: raw.id,
         sessionId: raw.sessionId,
         previousTurnId: raw.previousTurnId,
-        input: raw.input as TurnInputItem[] | undefined,
-        state: raw.state as Turn["state"],
+        input: raw.input,
+        state: raw.state as TfyTurnState,
+        createdBySubject: raw.createdBySubject,
         createdAt: raw.createdAt,
     };
 }
@@ -94,9 +155,11 @@ async function toListResult<TIn, TOut>(
  * (populated by createSession/listSessions) determines which gateway client
  * to call. No try/catch fallback, no double network calls.
  */
-export function createTrueFoundryChatServer(
+export function createTrueFoundryChatServer<
+    TSpec extends TfyAgentSpec = TfyAgentSpec,
+>(
     opts: CreateTrueFoundryChatServerOptions,
-): TrueFoundryChatServer {
+): TrueFoundryChatServer<TSpec> {
     const gatewayOpts = { apiKey: opts.apiKey, baseUrl: opts.baseUrl };
     const client = opts.client ?? new AgentSessionClient(gatewayOpts);
     const privateClient =
@@ -104,7 +167,10 @@ export function createTrueFoundryChatServer(
 
     const sessionTypeCache = new Map<string, boolean>();
 
-    function cacheSessionType(session: Session): void {
+    function cacheSessionType(session: {
+        id: string;
+        isMutable: boolean;
+    }): void {
         sessionTypeCache.set(session.id, session.isMutable);
     }
 
@@ -122,22 +188,28 @@ export function createTrueFoundryChatServer(
         );
     }
 
-    const server: TrueFoundryChatServer = {
+    const server: TrueFoundryChatServer<TSpec> = {
         async createSession(req) {
             if (req.agentSpec != null) {
                 const draft = await privateClient.createDraftSession({
-                    agentSpec: req.agentSpec as never,
+                    agentSpec: req.agentSpec,
                     ...(req.agentName != null ? { agentName: req.agentName } : {}),
+                    ...(req.tfyMetadata != null
+                        ? { tfyMetadata: req.tfyMetadata }
+                        : {}),
                 });
-                const session = toSession(draft);
+                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(named);
+                const session = toSession<TSpec>(named);
                 cacheSessionType(session);
                 return session;
             }
@@ -150,9 +222,10 @@ export function createTrueFoundryChatServer(
                 order: req?.order,
                 pageToken: req?.pageToken,
                 startTimestamp: req?.startTimestamp,
+                endTimestamp: req?.endTimestamp,
                 ...(req?.agentName != null ? { agentName: req.agentName } : {}),
             });
-            const result = await toListResult(page, toSession);
+            const result = await toListResult(page, (s) => toSession<TSpec>(s));
             for (const session of result.data) {
                 cacheSessionType(session);
             }
@@ -161,7 +234,7 @@ export function createTrueFoundryChatServer(
 
         async getSession({ sessionId }) {
             const raw = await getSessionObj(sessionId);
-            const session = toSession(raw);
+            const session = toSession<TSpec>(raw);
             cacheSessionType(session);
             return session;
         },
@@ -174,9 +247,9 @@ export function createTrueFoundryChatServer(
                 );
             }
             if (req.agentSpec != null) {
-                await raw.update({ agentSpec: req.agentSpec as never });
+                await raw.update({ agentSpec: req.agentSpec });
             }
-            return toSession(raw);
+            return toSession<TSpec>(raw);
         },
 
         prepareAndExecuteTurn(req: {
@@ -217,12 +290,13 @@ export function createTrueFoundryChatServer(
             await opts.deleteSession({ sessionId });
         },
 
-        async listTurns({ sessionId, limit, pageToken, order }) {
+        // 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 } : {}),
-                ...(order != null ? { order } : {}),
             });
             return toListResult(page, (turn) => toTurn(turn));
         },