@truefoundry/assistant-ui-runtime 0.1.5 → 0.1.6

package/src/index.ts

@@ -12,15 +12,18 @@ export {
 } from "./convertTurnMessages.js";
 export type { ConvertTurnsResult, UserMessageContent } from "./convertTurnMessages.js";
 export { ROOT_THREAD_ID } from "./constants.js";
-export type { UseTrueFoundryAgentRuntimeOptions, NamedAgentConfig, DraftAgentConfig, TrueFoundryAgentConfig } from "./types.js";
+export type {
+    UseTrueFoundryAgentRuntimeOptions,
+    NamedAgentConfig,
+    DraftAgentConfig,
+    TrueFoundryAgentConfig,
+} from "./types.js";
 export type { AgentSpec, AgentSpecUpdate, DraftSession } from "./private/agentSpec.js";
 export { mergeAgentSpec, draftSessionTitle } from "./private/agentSpec.js";
 export { createTrueFoundryDraftThreadListAdapter } from "./private/truefoundryDraftThreadListAdapter.js";
 export { createTrueFoundryOwnedSessionsThreadListAdapter } from "./truefoundryOwnedSessionsThreadListAdapter.js";
 export { createDraftSessionBridge } from "./private/draftSessionBridge.js";
 export type { DraftSessionBridge } from "./private/draftSessionBridge.js";
-export { PrivateAgentSessionClient } from "truefoundry-gateway-sdk/agents/private";
-export type { AgentDraftSession } from "truefoundry-gateway-sdk/agents/private";
 export {
     useTrueFoundryAgentSpec,
     useTrueFoundryUpdateAgentSpec,
@@ -35,7 +38,6 @@ export type {
     ToolApprovalMessageCustomMetadata,
     ToolResponseMessageCustomMetadata,
 } from "./messageCustomMetadata.js";
-export type { SandboxCreatedEvent } from "truefoundry-gateway-sdk/agents";
 export type { PendingApproval, PendingToolResponse } from "./collectPending.js";
 export type { TrueFoundryRuntimeExtras } from "./truefoundryExtras.js";
 export { trueFoundryExtras } from "./truefoundryExtras.js";
@@ -71,3 +73,77 @@ export {
 export { createTrueFoundryThreadListAdapter } from "./truefoundryThreadListAdapter.js";
 export { getSession } from "./sessions.js";
 export { trueFoundryAttachmentAdapter } from "./attachmentAdapter.js";
+
+export type {
+    AgentChatServer,
+    AgentBuilderServer,
+    Session,
+    Turn,
+    TurnState,
+    TurnStateDone,
+    TurnInputItem,
+    AgentSpec as ServerAgentSpec,
+    ListResult,
+    CreateSessionRequest,
+    UpdateSessionRequest,
+    ListSessionsParams,
+    UserMessage,
+    UserToolApprovalEvent,
+    UserToolResponseEvent,
+    PreviousTurnIdInput,
+} from "./server/index.js";
+export type {
+    SandboxCreatedEvent,
+    McpAuthRequiredEvent,
+    ModelMessageEvent,
+    TurnEvent,
+    TurnStreamingEvent,
+    TurnStreamData,
+    SessionEventItem,
+    ToolCall,
+    ThreadCreatedEvent,
+    ToolApprovalRequiredEvent,
+    ToolResponseRequiredEvent,
+} from "./server/index.js";
+export { isEventDelta, mergeEventDelta } from "./server/index.js";
+
+// ---------------------------------------------------------------------------
+// Plugin: truefoundry-agent-server-adapter
+// ---------------------------------------------------------------------------
+
+export {
+    createTrueFoundryChatServer,
+    type CreateTrueFoundryChatServerOptions,
+    type TrueFoundryChatServer,
+    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,
+    isTfyToolInfo,
+    isTfySystemToolInfo,
+    isTfyMcpToolInfo,
+    getTfyUsage,
+    getTfyThreadState,
+    getTfyMcpInitServers,
+} from "./plugins/truefoundry-agent-server-adapter/index.js";

package/src/listPages.ts

@@ -0,0 +1,21 @@
+import type { ListResult } from "./server/types.js";
+
+/**
+ * Drains all pages of a token-paginated list into a single array.
+ * Newest-first APIs should reverse after calling this.
+ */
+export async function drainListPages<T>(
+    fetchPage: (pageToken?: string) => Promise<ListResult<T>>,
+): Promise<T[]> {
+    const items: T[] = [];
+    let pageToken: string | undefined;
+    for (;;) {
+        const page = await fetchPage(pageToken);
+        items.push(...page.data);
+        if (page.nextPageToken == null || page.nextPageToken === "") {
+            break;
+        }
+        pageToken = page.nextPageToken;
+    }
+    return items;
+}

package/src/loadSessionSnapshot.test.ts

@@ -1,4 +1,4 @@
-import type { AgentSessionClient } from "truefoundry-gateway-sdk/agents";
+import type { AgentChatServer } from "./server/index.js";
 import { beforeEach, describe, expect, it, vi } from "vitest";
 
 import { createEmptySessionSnapshot } from "./sessionSnapshot.js";
@@ -19,7 +19,7 @@ import { buildSnapshotFromSessionEvents } from "./convertTurnMessages.js";
 import { loadSessionSnapshot } from "./loadSessionSnapshot.js";
 import { getSession } from "./sessions.js";
 
-const mockClient = {} as AgentSessionClient;
+const mockServer = {} as AgentChatServer;
 
 describe("loadSessionSnapshot", () => {
     beforeEach(() => {
@@ -33,8 +33,8 @@ describe("loadSessionSnapshot", () => {
         );
 
         const [first, second] = await Promise.all([
-            loadSessionSnapshot(mockClient, "session-1"),
-            loadSessionSnapshot(mockClient, "session-1"),
+            loadSessionSnapshot(mockServer, "session-1"),
+            loadSessionSnapshot(mockServer, "session-1"),
         ]);
 
         expect(first).toBe(second);
@@ -48,8 +48,8 @@ describe("loadSessionSnapshot", () => {
             createEmptySessionSnapshot(),
         );
 
-        await loadSessionSnapshot(mockClient, "session-1");
-        await loadSessionSnapshot(mockClient, "session-1");
+        await loadSessionSnapshot(mockServer, "session-1");
+        await loadSessionSnapshot(mockServer, "session-1");
 
         expect(getSession).toHaveBeenCalledTimes(2);
         expect(buildSnapshotFromSessionEvents).toHaveBeenCalledTimes(2);
@@ -62,10 +62,11 @@ describe("loadSessionSnapshot", () => {
         );
 
         const onProgress = vi.fn();
-        await loadSessionSnapshot(mockClient, "session-1", undefined, onProgress);
+        await loadSessionSnapshot(mockServer, "session-1", onProgress);
 
         expect(buildSnapshotFromSessionEvents).toHaveBeenCalledWith(
-            {},
+            mockServer,
+            "session-1",
             onProgress,
         );
     });

package/src/loadSessionSnapshot.ts

@@ -1,7 +1,7 @@
-import type { AgentSessionClient } from "truefoundry-gateway-sdk/agents";
+import type { AgentChatServer } from "./server/types.js";
 
 import { buildSnapshotFromSessionEvents } from "./convertTurnMessages.js";
-import { getSession, type GetSessionOptions } from "./sessions.js";
+import { getSession } from "./sessions.js";
 import type { SessionSnapshot } from "./sessionSnapshot.js";
 
 const inflightBySessionId = new Map<string, Promise<SessionSnapshot>>();
@@ -15,25 +15,20 @@ const inflightBySessionId = new Map<string, Promise<SessionSnapshot>>();
  * can update the UI progressively while history is being processed.
  */
 export function loadSessionSnapshot(
-    client: AgentSessionClient,
+    server: AgentChatServer,
     sessionId: string,
-    sessionOptions?: GetSessionOptions,
     onProgress?: (snap: SessionSnapshot) => void,
 ): Promise<SessionSnapshot> {
-    const cacheKey =
-        sessionOptions?.privateClient != null ? `draft:${sessionId}` : sessionId;
-    let inflight = inflightBySessionId.get(cacheKey);
+    let inflight = inflightBySessionId.get(sessionId);
     if (inflight == null) {
-        inflight = getSession(client, sessionId, sessionOptions)
-            .then((session) =>
-                buildSnapshotFromSessionEvents(session, onProgress),
-            )
+        inflight = getSession(server, sessionId)
+            .then(() => buildSnapshotFromSessionEvents(server, sessionId, onProgress))
             .finally(() => {
-                if (inflightBySessionId.get(cacheKey) === inflight) {
-                    inflightBySessionId.delete(cacheKey);
+                if (inflightBySessionId.get(sessionId) === inflight) {
+                    inflightBySessionId.delete(sessionId);
                 }
             });
-        inflightBySessionId.set(cacheKey, inflight);
+        inflightBySessionId.set(sessionId, inflight);
     }
     return inflight;
 }

package/src/mcpAuth.ts

@@ -1,5 +1,5 @@
 import type { MessageStatus } from "@assistant-ui/core";
-import type { McpAuthRequiredEvent, TurnStateDone } from "truefoundry-gateway-sdk/agents";
+import type { McpAuthRequiredEvent, TurnStateDone } from "./server/index.js";
 
 import type { AssistantContentPart } from "./modelMessageContent.js";
 import type { McpAuthMessageCustomMetadata } from "./messageCustomMetadata.js";
@@ -28,9 +28,12 @@ export function buildMcpAuthTextParts(
 export function findMcpAuthRequired(
     requiredActions: TurnStateDone["requiredActions"] | undefined,
 ): McpAuthRequiredEvent | undefined {
-    return requiredActions?.find(
-        (action): action is McpAuthRequiredEvent => action.type === "mcp.auth_required",
+    const found = requiredActions?.find(
+        (action) => action.type === "mcp.auth_required",
     );
+    return found?.type === "mcp.auth_required"
+        ? (found as McpAuthRequiredEvent)
+        : undefined;
 }
 
 export function mcpAuthAssistantStatus(): MessageStatus {

package/src/messageCustomMetadata.ts

@@ -1,4 +1,4 @@
-import type { McpAuthRequiredEvent } from "truefoundry-gateway-sdk/agents";
+import type { McpAuthRequiredEvent } from "./server/index.js";
 
 import type { SubAgentCustomMetadata } from "./foldPeerThreads.js";
 import { TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY } from "./toolApproval.js";

package/src/modelMessageContent.ts

@@ -1,5 +1,5 @@
 import type { ThreadAssistantMessagePart } from "@assistant-ui/core";
-import type { ModelMessageEvent } from "truefoundry-gateway-sdk/agents";
+import type { ModelMessageEvent } from "./server/index.js";
 import type { PendingResponseRef } from "./foldPeerThreads.js";
 import { extractImagePartsFromModelMessage } from "./modelMessageImageContent.js";
 

package/src/modelMessageImageContent.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import type { ModelMessageEvent } from "truefoundry-gateway-sdk/agents";
+import type { ModelMessageEvent } from "./server/index.js";
 
 import { buildAssistantContent } from "./modelMessageContent.js";
 import { mergeStreamEventDelta } from "./modelMessageImageContent.js";

package/src/modelMessageImageContent.ts

@@ -1,10 +1,11 @@
 import type { CompleteAttachment } from "@assistant-ui/core";
-import type {
-    ModelMessageEvent,
-    TurnEvent,
-    TurnStreamingEvent,
-} from "truefoundry-gateway-sdk/agents";
-import { isEventDelta, mergeEventDelta } from "truefoundry-gateway-sdk/agents";
+import {
+    isEventDelta,
+    mergeEventDelta,
+    type ModelMessageEvent,
+    type TurnEvent,
+    type TurnStreamingEvent,
+} from "./server/index.js";
 
 import type { AssistantContentPart } from "./modelMessageContent.js";
 

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([]);
+    });
+});