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

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;
+}