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

package/README.md

@@ -1,55 +1,77 @@
-# truefoundry-agents-assistant-ui-runtime
+# @truefoundry/assistant-ui-runtime
 
-TrueFoundry Gateway agent runtime adapter for [assistant-ui](https://www.assistant-ui.com/).
+TrueFoundry agent runtime adapter for [assistant-ui](https://www.assistant-ui.com/).
 
 Connect assistant-ui components (`Thread`, `Composer`, tool UIs, `ThreadList`) to TrueFoundry agent sessions via `useTrueFoundryAgentRuntime`. The adapter maps gateway turns and streaming events onto assistant-ui's external-store runtime, including multi-agent nesting, tool approvals, ask-user tool responses, MCP auth, batched resume, resumable streams, and composer attachment forwarding on send.
 
 ## Requirements
 
 - **React** `^18 || ^19` (peer dependency)
-- **`truefoundry-gateway-sdk`** (peer dependency) — provides `AgentSessionClient` and agent types
 - **`@assistant-ui/react`** in the host app for the UI primitives
-- Bundled deps `@assistant-ui/core` and `@assistant-ui/store` are pulled in automatically
+- An **`AgentChatServer`** implementation — either use the built-in TrueFoundry gateway plugin (see below) or bring your own
+
+Bundled deps `@assistant-ui/core` and `@assistant-ui/store` are pulled in automatically.
 
 ## Installation
 
 ```bash
-npm install @assistant-ui/react truefoundry-agents-assistant-ui-runtime truefoundry-gateway-sdk@^0.1.0-rc.1
+npm install @truefoundry/assistant-ui-runtime @assistant-ui/react
+```
+
+If using the built-in TrueFoundry gateway adapter plugin, also install the gateway SDK:
+
+```bash
+npm install truefoundry-gateway-sdk
 ```
 
 ## Quickstart
 
-### 1. Create an `AgentSessionClient`
+### 1. Create an `AgentChatServer`
+
+The runtime accepts any object implementing the `AgentChatServer` interface — a flat, stateless port with methods like `createSession`, `listSessions`, `prepareAndExecuteTurn`, etc. It never reads credentials itself.
 
-Construct the client in your app (server module, proxy route, or demo). The runtime only accepts a pre-built client — it does **not** read API keys or gateway URLs itself.
+Using the built-in TrueFoundry gateway plugin (requires `truefoundry-gateway-sdk`):
 
 ```tsx
-import { AgentSessionClient } from "truefoundry-gateway-sdk/agents";
+import { createTrueFoundryChatServer } from "@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter";
 
-const client = new AgentSessionClient({
+const server = createTrueFoundryChatServer({
   apiKey: process.env.TFY_API_KEY!,
-  environment: process.env.TFY_GATEWAY_URL!, // https://gateway.truefoundry.ai/<tenant>
+  baseUrl: process.env.TFY_GATEWAY_URL!,
 });
 ```
 
-For production, point `fetch` or `auth` at your own backend proxy so secrets never reach the browser.
+Or bring your own implementation against any backend:
+
+```tsx
+import type { AgentChatServer } from "@truefoundry/assistant-ui-runtime";
+
+const server: AgentChatServer = {
+  createSession: async (req) => { /* ... */ },
+  listSessions: async (req) => { /* ... */ },
+  getSession: async (req) => { /* ... */ },
+  updateSession: async (req) => { /* ... */ },
+  prepareAndExecuteTurn: (req) => { /* return AsyncIterable<TurnStreamData> */ },
+  cancelSession: async (req) => { /* ... */ },
+  listTurns: async (req) => { /* ... */ },
+  getTurn: async (req) => { /* ... */ },
+  listEvents: async (req) => { /* ... */ },
+};
+```
 
-### 2. Set up the client runtime
+### 2. Set up the runtime
 
 ```tsx
 "use client";
 
 import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useTrueFoundryAgentRuntime } from "truefoundry-agents-assistant-ui-runtime";
+import { useTrueFoundryAgentRuntime } from "@truefoundry/assistant-ui-runtime";
 import { Thread } from "@/components/assistant-ui/thread";
 
-const AGENT_NAME = process.env.TFY_AGENT_NAME!;
-const client = new AgentSessionClient({ /* ... */ });
-
 export function MyAssistant() {
   const runtime = useTrueFoundryAgentRuntime({
-    client,
-    agentName: AGENT_NAME,
+    server,
+    agentName: "support-bot",
   });
 
   return (
@@ -84,46 +106,50 @@ See the assistant-ui [Thread UI guide](https://www.assistant-ui.com/docs/ui/thre
 
 | Option | Type | Required | Description |
 |--------|------|----------|-------------|
-| `client` | `AgentSessionClient` | Yes | Pre-built gateway client. The runtime never reads credentials itself. |
-| `agentName` | `string` | Yes | Saved agent to run (gateway agent name). |
+| `server` | `AgentChatServer` | Yes | Server implementation. The runtime never reads credentials itself. |
+| `agentName` | `string` | Yes* | Saved agent to run. *Or use `agent` for draft mode. |
+| `agent` | `NamedAgentConfig \| DraftAgentConfig` | No | Discriminated agent source. Overrides `agentName` when set. |
 | `initialSessionId` | `string` | No | Pin an existing session once on mount (uncontrolled). |
 | `threadId` | `string` | No | Controlled active session id; reactive and URL-syncable. |
 | `onThreadIdChange` | `(threadId: string \| undefined) => void` | No | Fires when the active session changes. |
 | `onError` | `(error: unknown) => void` | No | Invoked on stream/load/turn errors. |
-| `adapters` | `{ attachments?, speech?, dictation?, voice?, feedback? }` | No | Optional assistant-ui adapters forwarded to the runtime. See [Unsupported assistant-ui features](#unsupported-assistant-ui-features). |
+| `adapters` | `{ attachments?, speech?, dictation?, voice?, feedback? }` | No | Optional assistant-ui adapters forwarded to the runtime. |
 
 ### Specifying the agent
 
-Pass the saved agent name as `agentName`:
+Named agent (saved on the gateway):
 
 ```tsx
 const runtime = useTrueFoundryAgentRuntime({
-  client,
+  server,
   agentName: "support-bot",
 });
 ```
 
-### Adding adapters
-
-Pass optional assistant-ui adapters through `adapters`. Attachments are **opt-in**: wire the built-in adapter when you want composer file pick / previews and gateway forwarding on send.
+Draft agent (inline spec, mutable):
 
 ```tsx
-import { trueFoundryAttachmentAdapter, useTrueFoundryAgentRuntime } from "truefoundry-agents-assistant-ui-runtime";
-
 const runtime = useTrueFoundryAgentRuntime({
-  client,
-  agentName,
-  adapters: { attachments: trueFoundryAttachmentAdapter },
+  server,
+  agent: {
+    mode: "draft",
+    defaultAgentSpec: { model: { name: "gpt-4o" } },
+    onAgentSpecChange: (spec) => console.log("spec updated", spec),
+  },
 });
 ```
 
-Other adapters (speech, feedback, etc.) follow the same pattern:
+### Adding adapters
+
+Attachments are **opt-in**: wire the built-in adapter when you want composer file pick / previews and gateway forwarding on send.
 
 ```tsx
+import { trueFoundryAttachmentAdapter, useTrueFoundryAgentRuntime } from "@truefoundry/assistant-ui-runtime";
+
 const runtime = useTrueFoundryAgentRuntime({
-  client,
+  server,
   agentName,
-  adapters: { attachments: trueFoundryAttachmentAdapter, speech, feedback },
+  adapters: { attachments: trueFoundryAttachmentAdapter },
 });
 ```
 
@@ -131,7 +157,7 @@ const runtime = useTrueFoundryAgentRuntime({
 
 ```tsx
 const runtime = useTrueFoundryAgentRuntime({
-  client,
+  server,
   agentName,
   initialSessionId: "ses_abc123",
 });
@@ -139,11 +165,11 @@ const runtime = useTrueFoundryAgentRuntime({
 
 ### Bring your own session ID (no session list)
 
-You can drive a single, externally-owned session without rendering `<ThreadList>`. Pin the active session with `initialSessionId` (one-time) or controlled `threadId` (reactive, URL-syncable). Omit `<ThreadList>` — the session list adapter only powers that UI.
+Pin the active session with `initialSessionId` (one-time) or controlled `threadId` (reactive, URL-syncable). Omit `<ThreadList>` — the session list adapter only powers that UI.
 
 ```tsx
 const runtime = useTrueFoundryAgentRuntime({
-  client,
+  server,
   agentName,
   initialSessionId: "ses_abc123",
 });
@@ -157,16 +183,291 @@ return (
 
 Each gateway session corresponds to one assistant-ui thread.
 
+## `AgentChatServer` interface
+
+The runtime operates against a flat server port — no session-with-methods objects, no SDK dependency. Any backend can implement this interface:
+
+```tsx
+interface AgentChatServer {
+  createSession(req: CreateSessionRequest): Promise<Session>;
+  listSessions(req?: ListSessionsParams): Promise<ListResult<Session>>;
+  getSession(req: { sessionId: string }): Promise<Session>;
+  updateSession(req: UpdateSessionRequest): Promise<Session>;
+
+  prepareAndExecuteTurn(req: {
+    sessionId: string;
+    input?: TurnInputItem[];
+    previousTurnId?: PreviousTurnIdInput;
+    abortSignal?: AbortSignal;
+    headers?: Record<string, string>;
+  }): AsyncIterable<TurnStreamData>;
+
+  cancelSession(req: { sessionId: string }): Promise<void>;
+  deleteSession?(req: { sessionId: string }): Promise<void>;
+
+  listTurns(req: { sessionId: string; limit?: number; pageToken?: string; order?: "asc" | "desc" }): Promise<ListResult<Turn>>;
+  getTurn(req: { sessionId: string; turnId: string }): Promise<Turn>;
+  listEvents(req: { sessionId: string; pageToken?: string; lastTurnId?: string; limit?: number }): Promise<ListResult<SessionEventItem>>;
+
+  listTurnEvents?(req: { sessionId: string; turnId: string; limit?: number; pageToken?: string; order?: "asc" | "desc" }): Promise<ListResult<TurnEvent>>;
+  subscribeToTurn?(req: { sessionId: string; turnId: string; afterSequenceNumber?: number; abortSignal?: AbortSignal }): AsyncIterable<TurnStreamData>;
+  downloadSandboxFile?(sandboxId: string, req: { path: string }): Promise<Blob>;
+}
+```
+
+`ListResult<T>` is `{ data: T[]; nextPageToken?: string }` — flat token-based pagination.
+
+### Implementing your own backend
+
+Below is a fully-typed class implementing `AgentChatServer` against a custom REST API. Use this as a starting point when integrating your own agent backend:
+
+```typescript
+import type {
+  AgentChatServer,
+  CreateSessionRequest,
+  ListResult,
+  ListSessionsParams,
+  Session,
+  SessionEventItem,
+  Turn,
+  TurnEvent,
+  TurnInputItem,
+  TurnStreamData,
+  UpdateSessionRequest,
+} from "@truefoundry/assistant-ui-runtime";
+
+class MyAgentChatServer implements AgentChatServer {
+  constructor(private baseUrl: string, private authToken: string) {}
+
+  private async request<T>(path: string, init?: RequestInit): Promise<T> {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      ...init,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.authToken}`,
+        ...init?.headers,
+      },
+    });
+    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+    return res.json() as Promise<T>;
+  }
+
+  async createSession(req: CreateSessionRequest): Promise<Session> {
+    return this.request("/sessions", {
+      method: "POST",
+      body: JSON.stringify(req),
+    });
+  }
+
+  async listSessions(req?: ListSessionsParams): Promise<ListResult<Session>> {
+    const params = new URLSearchParams();
+    if (req?.limit) params.set("limit", String(req.limit));
+    if (req?.pageToken) params.set("pageToken", req.pageToken);
+    if (req?.agentName) params.set("agentName", req.agentName);
+    return this.request(`/sessions?${params}`);
+  }
+
+  async getSession(req: { sessionId: string }): Promise<Session> {
+    return this.request(`/sessions/${req.sessionId}`);
+  }
+
+  async updateSession(req: UpdateSessionRequest): Promise<Session> {
+    return this.request(`/sessions/${req.sessionId}`, {
+      method: "PATCH",
+      body: JSON.stringify({ agentSpec: req.agentSpec, title: req.title }),
+    });
+  }
+
+  prepareAndExecuteTurn(req: {
+    sessionId: string;
+    input?: TurnInputItem[];
+    previousTurnId?: string;
+    abortSignal?: AbortSignal;
+  }): AsyncIterable<TurnStreamData> {
+    const self = this;
+    return {
+      [Symbol.asyncIterator]() {
+        return self.streamTurn(req);
+      },
+    };
+  }
+
+  private async *streamTurn(req: {
+    sessionId: string;
+    input?: TurnInputItem[];
+    previousTurnId?: string;
+    abortSignal?: AbortSignal;
+  }): AsyncGenerator<TurnStreamData> {
+    const res = await fetch(`${this.baseUrl}/sessions/${req.sessionId}/turns`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.authToken}`,
+        Accept: "text/event-stream",
+      },
+      body: JSON.stringify({
+        input: req.input,
+        previousTurnId: req.previousTurnId,
+      }),
+      signal: req.abortSignal,
+    });
+
+    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+    const reader = res.body!.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (!line.startsWith("data: ")) continue;
+        const json = line.slice(6);
+        if (json === "[DONE]") return;
+        yield JSON.parse(json) as TurnStreamData;
+      }
+    }
+  }
+
+  async cancelSession(req: { sessionId: string }): Promise<void> {
+    await this.request(`/sessions/${req.sessionId}/cancel`, { method: "POST" });
+  }
+
+  async listTurns(req: {
+    sessionId: string;
+    limit?: number;
+    pageToken?: string;
+  }): Promise<ListResult<Turn>> {
+    const params = new URLSearchParams();
+    if (req.limit) params.set("limit", String(req.limit));
+    if (req.pageToken) params.set("pageToken", req.pageToken);
+    return this.request(`/sessions/${req.sessionId}/turns?${params}`);
+  }
+
+  async getTurn(req: { sessionId: string; turnId: string }): Promise<Turn> {
+    return this.request(`/sessions/${req.sessionId}/turns/${req.turnId}`);
+  }
+
+  async listEvents(req: {
+    sessionId: string;
+    pageToken?: string;
+    lastTurnId?: string;
+    limit?: number;
+  }): Promise<ListResult<SessionEventItem>> {
+    const params = new URLSearchParams();
+    if (req.limit) params.set("limit", String(req.limit));
+    if (req.pageToken) params.set("pageToken", req.pageToken);
+    if (req.lastTurnId) params.set("lastTurnId", req.lastTurnId);
+    return this.request(`/sessions/${req.sessionId}/events?${params}`);
+  }
+
+  async listTurnEvents(req: {
+    sessionId: string;
+    turnId: string;
+    limit?: number;
+    pageToken?: string;
+  }): Promise<ListResult<TurnEvent>> {
+    const params = new URLSearchParams();
+    if (req.limit) params.set("limit", String(req.limit));
+    if (req.pageToken) params.set("pageToken", req.pageToken);
+    return this.request(
+      `/sessions/${req.sessionId}/turns/${req.turnId}/events?${params}`,
+    );
+  }
+
+  subscribeToTurn(req: {
+    sessionId: string;
+    turnId: string;
+    afterSequenceNumber?: number;
+    abortSignal?: AbortSignal;
+  }): AsyncIterable<TurnStreamData> {
+    const self = this;
+    return {
+      [Symbol.asyncIterator]() {
+        return self.streamSubscribe(req);
+      },
+    };
+  }
+
+  private async *streamSubscribe(req: {
+    sessionId: string;
+    turnId: string;
+    afterSequenceNumber?: number;
+    abortSignal?: AbortSignal;
+  }): AsyncGenerator<TurnStreamData> {
+    const params = new URLSearchParams();
+    if (req.afterSequenceNumber != null) {
+      params.set("after", String(req.afterSequenceNumber));
+    }
+    const res = await fetch(
+      `${this.baseUrl}/sessions/${req.sessionId}/turns/${req.turnId}/stream?${params}`,
+      {
+        headers: {
+          Authorization: `Bearer ${this.authToken}`,
+          Accept: "text/event-stream",
+        },
+        signal: req.abortSignal,
+      },
+    );
+
+    if (!res.ok) throw new Error(`${res.status} ${res.statusText}`);
+    const reader = res.body!.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (!line.startsWith("data: ")) continue;
+        const json = line.slice(6);
+        if (json === "[DONE]") return;
+        yield JSON.parse(json) as TurnStreamData;
+      }
+    }
+  }
+}
+```
+
+Then use it with the runtime:
+
+```tsx
+const server = new MyAgentChatServer("https://api.example.com", authToken);
+
+function App() {
+  const runtime = useTrueFoundryAgentRuntime({
+    server,
+    agentName: "my-agent",
+  });
+
+  return (
+    <AssistantRuntimeProvider runtime={runtime}>
+      <Thread />
+    </AssistantRuntimeProvider>
+  );
+}
+```
+
 ## Multi-agent (nested sub-agents)
 
-TrueFoundry sub-agents are discovered at runtime via `thread.created` and nested under `ToolCallMessagePart.messages`. The gateway always sends `title` as a required `string` on `thread.created` / `thread.done` (never `null`). This runtime copies it onto `metadata.custom.subAgent.title` for the first nested message of each child thread; `name` comes from `agentInfo.name` on the same event.
+TrueFoundry sub-agents are discovered at runtime via `thread.created` and nested under `ToolCallMessagePart.messages`. The gateway sends `title` on `thread.created` / `thread.done`. This runtime copies it onto `metadata.custom.subAgent.title` for the first nested message of each child thread; `name` comes from `agentInfo.name` on the same event.
 
-Render nested threads with `MessagePartPrimitive.Messages` inside your tool fallback (recommended — no per-tool registration):
+Render nested threads with `MessagePartPrimitive.Messages` inside your tool fallback:
 
 ```tsx
 import { MessagePartPrimitive, MessagePrimitive } from "@assistant-ui/react";
 import { useAuiState } from "@assistant-ui/store";
-import type { TrueFoundryMessageCustomMetadata } from "truefoundry-agents-assistant-ui-runtime";
+import type { TrueFoundryMessageCustomMetadata } from "@truefoundry/assistant-ui-runtime";
 
 function NestedSubAgentAssistantMessage() {
   const custom = useAuiState(
@@ -194,10 +495,6 @@ function NestedSubAgentAssistantMessage() {
 />
 ```
 
-For a collapsed tool-row header, cast the spawning `create_sub_agent` tool part’s `artifact` to `SubAgentArtifact` and read `subAgents[].title` (or `agentInfo.name`):
-
-Alternative: register `defineToolkit({ create_sub_agent: ... })` — all sub-agents share that one system tool name.
-
 See the [Multi-Agent Chat UI guide](https://www.assistant-ui.com/docs/tools/multi-agent).
 
 ## Tool approvals
@@ -237,7 +534,7 @@ import {
   useTrueFoundryApprovals,
   useTrueFoundryToolResponses,
   useTrueFoundryMcpAuth,
-} from "truefoundry-agents-assistant-ui-runtime";
+} from "@truefoundry/assistant-ui-runtime";
 
 function ApprovalBar() {
   const { pending, respond } = useTrueFoundryApprovals();
@@ -293,28 +590,13 @@ function McpAuthContinue() {
 
 ### Action hooks (any render context, including nested sub-agents)
 
-```tsx
-import { useTrueFoundryRespondToToolApproval } from "truefoundry-agents-assistant-ui-runtime";
-
-function NestedToolApprovalButton({ approvalId }: { approvalId: string }) {
-  const respond = useTrueFoundryRespondToToolApproval();
-  return (
-    <button onClick={() => respond({ approvalId, approved: true })}>
-      Allow
-    </button>
-  );
-}
-```
-
-The action-only hooks return a single callback you can call from any render context (root or nested sub-agent thread). All four follow the same pattern:
-
 ```tsx
 import {
   useTrueFoundryRespondToToolApproval,
   useTrueFoundryRespondToToolResponse,
   useTrueFoundryResumeMcpAuth,
   useTrueFoundryCancel,
-} from "truefoundry-agents-assistant-ui-runtime";
+} from "@truefoundry/assistant-ui-runtime";
 
 const respondToApproval = useTrueFoundryRespondToToolApproval();
 const respondToResponse = useTrueFoundryRespondToToolResponse();
@@ -331,170 +613,85 @@ void cancel();
 
 | Hook | Returns | Description |
 |------|---------|-------------|
-| `useTrueFoundryApprovals()` | `{ pending: PendingApproval[]; respond: (r: RespondToToolApprovalOptions) => void }` | Pending tool approvals (across all threads) plus a respond action. Use for thread-level approval chrome. |
-| `useTrueFoundryToolResponses()` | `{ pending: PendingToolResponse[]; respond: (r: RespondToToolResponseOptions) => void }` | Pending ask-user / `tool.response_required` prompts plus a respond action. |
-| `useTrueFoundryMcpAuth()` | `{ pending: { mcpServers } \| null; resume: () => Promise<void> }` | Pending MCP OAuth pause state plus a resume action. |
-| `useTrueFoundryRespondToToolApproval()` | `(r: RespondToToolApprovalOptions) => void` | Respond to a tool approval from any render context, including nested sub-agent (readonly) renderers. |
-| `useTrueFoundryRespondToToolResponse()` | `(r: RespondToToolResponseOptions) => void` | Respond to an ask-user / `tool.response_required` prompt from any render context. |
-| `useTrueFoundryResumeMcpAuth()` | `() => Promise<void>` | Resume the paused turn after the user completes MCP OAuth in the browser. |
-| `useTrueFoundryCancel()` | `() => Promise<void>` | Cancel the active turn. Calls `session.cancel()` and drains the stream to its terminal `turn.done`. |
-| `useTrueFoundryHistoryPagination()` | `{ hasOlderHistory, isLoadingOlderHistory, loadOlderHistory }` | Scroll-up older history: call `loadOlderHistory()` when the user nears the top of the thread. |
-
-Where:
-
-- `PendingApproval` = `{ approvalId, threadId, toolName, args, argsText }`
-- `PendingToolResponse` = `{ toolCallId, threadId, toolName, args, argsText, question?, options? }`
-- `RespondToToolApprovalOptions` = `{ approvalId, approved, optionId?, reason? }`
-- `RespondToToolResponseOptions` = `{ toolCallId, content }`
-
-> **Read vs. action hooks.** The three `use*Approvals` / `use*ToolResponses` / `use*McpAuth` read hooks subscribe to extras state and re-render when pending items change — use them in thread-level UI (e.g. an approval bar). The four action-only hooks (`useTrueFoundryRespondTo*`, `useTrueFoundryResumeMcpAuth`, `useTrueFoundryCancel`) read the action via `trueFoundryExtras.get(aui)` and do **not** subscribe to state, so they are safe to call from nested sub-agent renderers where only a readonly context is available.
+| `useTrueFoundryApprovals()` | `{ pending, respond }` | Pending tool approvals plus a respond action. |
+| `useTrueFoundryToolResponses()` | `{ pending, respond }` | Pending ask-user prompts plus a respond action. |
+| `useTrueFoundryMcpAuth()` | `{ pending, resume }` | Pending MCP OAuth pause state plus a resume action. |
+| `useTrueFoundryRespondToToolApproval()` | `(r) => void` | Respond to a tool approval from any render context. |
+| `useTrueFoundryRespondToToolResponse()` | `(r) => void` | Respond to an ask-user prompt from any render context. |
+| `useTrueFoundryResumeMcpAuth()` | `() => Promise<void>` | Resume after MCP OAuth. |
+| `useTrueFoundryCancel()` | `() => Promise<void>` | Cancel the active turn. |
+| `useTrueFoundryResetFromTurn()` | n/a | Re-submit a user turn (branch/reset). |
+| `useTrueFoundryReload()` | n/a | Retry the current session load. |
+| `useTrueFoundryHistoryPagination()` | `{ hasOlderHistory, isLoadingOlderHistory, loadOlderHistory }` | Scroll-up older history. |
 
 ### Low-level namespace
 
 ```tsx
-import { trueFoundryExtras, type TrueFoundryRuntimeExtras } from "truefoundry-agents-assistant-ui-runtime";
+import { trueFoundryExtras, type TrueFoundryRuntimeExtras } from "@truefoundry/assistant-ui-runtime";
 
-// Throws outside useTrueFoundryAgentRuntime:
 const extras = trueFoundryExtras.use();
-
-// Safe with fallback (returns default outside runtime):
 const pending = trueFoundryExtras.use((e) => e.pendingApprovals, []);
 ```
 
-`TrueFoundryRuntimeExtras` fields:
-
-| Field | Type | Purpose |
-|-------|------|---------|
-| `pendingApprovals` | `PendingApproval[]` | Undecided tool approvals across all threads |
-| `pendingToolResponses` | `PendingToolResponse[]` | Unanswered ask-user / client-side tool prompts |
-| `pendingMcpAuth` | `{ mcpServers } \| null` | MCP OAuth pause state |
-| `respondToToolApproval` | `(r: { approvalId, approved, reason? }) => void` | Stage approval; batch-send when complete |
-| `respondToToolResponse` | `(r: { toolCallId, content }) => void` | Stage answer; batch-send when complete |
-| `resumeMcpAuth` | `() => Promise<void>` | Resume after OAuth |
-| `cancel` | `() => Promise<void>` | Cancel the active turn: calls `session.cancel()` and lets the stream drain to its terminal `turn.done` (reconciles on next session load) |
-| `resetFromTurn` | `(turnId: string) => Promise<void>` | Re-submit a user turn (branch/reset) |
-| `reload` | `() => void` | Retry the current session load |
-| `downloadSandboxFile` | `(path: string) => Promise<Blob>` | Download a file from the session sandbox |
-| `hasOlderHistory` | `boolean` | True when another older `listEvents` page is available |
-| `isLoadingOlderHistory` | `boolean` | True while `loadOlderHistory` is in flight |
-| `loadOlderHistory` | `() => Promise<void>` | Prepend the next older history window (scroll-up) |
-| `draft` | `TrueFoundryDraftRuntimeExtras \| null` | Draft-mode agent spec sync extras |
-
-Per-part `respondToApproval` from assistant-ui still works for root-thread tool UIs; extras complements that for global chrome and nested renderers.
-
 ## Cancellation
 
-`cancel()` does **not** tear down the stream mid-flight. It calls `session.cancel()` and then keeps consuming the active stream: the backend closes the SSE gracefully by emitting a terminal `turn.done` event before ending the stream, so the in-flight run drains to completion on its own. No explicit reconcile is performed — the cancelled turn is terminal, and local state reconciles against the authoritative event log on the next session load (e.g. page reload). A subsequent `sendTurn` chains on the cancelled turn's history via `previousTurnId: "auto"`.
-
-(Hard aborts still happen when *switching away* — starting a new run or changing sessions abandons the previous turn.)
+`cancel()` calls `server.cancelSession()` and then keeps consuming the active stream: the backend closes the SSE gracefully by emitting a terminal `turn.done` event before ending the stream. No explicit reconcile is performed — the cancelled turn is terminal, and local state reconciles against the authoritative event log on the next session load.
 
 ## Resumable streams
 
-Works out of the box — no server route or Redis store. TrueFoundry persists every turn server-side; on reload or reconnect the runtime calls `turn.stream({})` and replays events into the fold (idempotent). Running turns are detected on session load and resumed automatically.
-
-> **TODO:** Track the last ingested `sequenceNumber` and pass `afterSequenceNumber` on reconnect to avoid replaying already-seen events.
-
-Contrast with the [AI SDK resumable streams guide](https://www.assistant-ui.com/docs/guides/resumable-streams), which requires a separate encoded-byte store.
+Works out of the box — no server route or Redis store. TrueFoundry persists every turn server-side; on reload or reconnect the runtime calls `subscribeToTurn` and replays events into the fold (idempotent). Running turns are detected on session load and resumed automatically.
 
 ## History pagination
 
 Thread open no longer drains every turn. Initial load:
 
-1. `listTurns({ limit: 1 })` once — detect a running turn (does **not** walk `page_token`).
+1. `listTurns({ limit: 1 })` once — detect a running turn.
 2. One (or a few) `listEvents` page(s) for the newest complete user-message group.
 3. Clears `isLoading`, then resumes a running turn via subscribe if needed.
 
-Older history is opt-in via extras / `useTrueFoundryHistoryPagination()`:
+Older history is opt-in via `useTrueFoundryHistoryPagination()`:
 
 ```tsx
 const { hasOlderHistory, isLoadingOlderHistory, loadOlderHistory } =
   useTrueFoundryHistoryPagination();
 
-// e.g. IntersectionObserver at the top of the message list
 if (hasOlderHistory && !isLoadingOlderHistory) {
   void loadOlderHistory();
 }
 ```
 
-`loadOlderHistory` prepends older turns without aborting an active stream.
-
-## Public API
-
-Everything below is exported from the package root (`truefoundry-agents-assistant-ui-runtime`).
-
-| Export | Kind | Purpose |
-|--------|------|---------|
-| `useTrueFoundryAgentRuntime` | hook | Main entry point. Returns an assistant-ui runtime bound to gateway sessions. |
-| `UseTrueFoundryAgentRuntimeOptions` | type | Options for the hook (see table above). |
-| `useTrueFoundryApprovals` | hook | `{ pending, respond }` for tool approvals via extras. |
-| `useTrueFoundryToolResponses` | hook | `{ pending, respond }` for ask-user / `tool.response_required` prompts. |
-| `useTrueFoundryMcpAuth` | hook | `{ pending, resume }` for MCP OAuth pause/resume. |
-| `useTrueFoundryRespondToToolApproval` | hook | Action callback via `trueFoundryExtras.get(aui)` — works in nested renderers. |
-| `useTrueFoundryRespondToToolResponse` | hook | Same pattern for tool responses. |
-| `useTrueFoundryResumeMcpAuth` | hook | Same pattern for MCP resume. |
-| `useTrueFoundryCancel` | hook | Same pattern for cancel. |
-| `useTrueFoundryHistoryPagination` | hook | `{ hasOlderHistory, isLoadingOlderHistory, loadOlderHistory }` for scroll-up history. |
-| `trueFoundryExtras` | namespace | `createRuntimeExtras` channel — `.use()`, `.get(aui)`, `.provide()`. |
-| `TrueFoundryRuntimeExtras` | type | Shape provided into the runtime extras slot. |
-| `PendingApproval`, `PendingToolResponse` | types | Derived pending items for UI rendering. |
-| `createTrueFoundryThreadListAdapter` | fn | Builds the cursor-paginated `RemoteThreadListAdapter` powering `<ThreadList>` (`list({ after })` → `nextCursor`). Used internally; exported for custom wiring. |
-| `getSession` | fn | `(client, sessionId) => Promise<AgentSession>` convenience wrapper. |
-| `convertTurnsToThreadMessages` | fn | Loads a session's turns and folds them into assistant-ui `ThreadMessage[]` (`ConvertTurnsResult`). |
-| `buildTurnAssistantContent` | fn | Folds a single turn's events into assistant content parts. |
-| `repositoryItemsFromMessages` | fn | Converts messages into `ExportedMessageRepositoryItem[]` for history export. |
-| `getTurnMessageContent` | fn | Extracts the text payload from an `AppendMessage`. |
-| `ConvertTurnsResult` | type | Result of `convertTurnsToThreadMessages` (`messages`, `foldState`, `runningTurn?`, `unstable_resume?`). |
-| `collectApprovalInputs` | fn | Collects decided approvals from a message into `user.tool_approval` inputs. |
-| `collectResponseInputs` | fn | Collects staged answers into `user.tool_response` inputs. |
-| `collectRequiredActionInputs` | fn | Collects both approval + response inputs once nothing is pending. |
-| `messageHasPendingApprovals` | fn | True if a message still has undecided tool approvals. |
-| `messageHasPendingResponses` | fn | True if a message still has unanswered tool responses. |
-| `messageHasPendingRequiredActions` | fn | True if either approvals or responses are still pending. |
-| `findPausedAssistantMessage` | fn | Last assistant message in `requires-action` state. |
-| `toTrueFoundryApprovalInputs` | fn | Applies an approval decision and returns gateway inputs. |
-| `SubAgentArtifact`, `SubAgentCustomMetadata` | types | Shapes attached to sub-agent tool calls / nested messages. |
-| `TrueFoundryMessageCustomMetadata` | type | Typed keys on `ThreadMessage.metadata.custom` written by this adapter. |
-| `ROOT_THREAD_ID` | const | The literal `"main"` — the gateway's root thread id. |
-
 ## Architecture (source map)
 
-For contributors and agents working inside this package. Source lives in `src/`; the published entry point is `dist/index.js` (built by `tsup`).
+For contributors working inside this package. Source lives in `src/`; the published entry point is `dist/index.js` (built by `tsup`).
 
 | File | Responsibility |
 |------|----------------|
+| `server/types.ts` | `AgentChatServer` + `AgentBuilderServer` interfaces, `Session`, `Turn`, `AgentSpec`, pagination types. |
+| `server/events.ts` | Concrete turn/stream event types (`ModelMessageEvent`, `TurnCreatedEvent`, etc.). |
+| `server/eventUtils.ts` | `isEventDelta()` + `mergeEventDelta()` — streaming delta merge logic. |
 | `useTrueFoundryAgentRuntime.ts` | Public hook. Wires the external-store runtime, thread-list runtime, adapters, and extras. |
-| `useTrueFoundryAgentMessages.ts` | Reactive `SessionSnapshot` store: load, stream ingestion, cancel, resume; derives `messages` via pure projection; records approval/response decisions in overlay. |
+| `useTrueFoundryAgentMessages.ts` | Reactive `SessionSnapshot` store: load, stream ingestion, cancel, resume; derives `messages` via pure projection. |
 | `sessionSnapshot.ts` | `SessionSnapshot` shape, required-actions overlay, and immutable wrapper helpers. |
 | `truefoundryExtras.ts` | `createRuntimeExtras` namespace and `TrueFoundryRuntimeExtras` type. |
 | `hooks.ts` | Consumer hooks — read selectors + action callbacks via `.get(aui)`. |
 | `collectPending.ts` | Derives `pendingApprovals`, `pendingToolResponses`, `pendingMcpAuth` from messages. |
 | `requiredActionInputs.ts` | Combined gate + `collectRequiredActionInputs` for batched resume. |
-| `truefoundryThreadListAdapter.ts` | `RemoteThreadListAdapter` — cursor-paginated session list (`list({ after })` → `nextCursor`), create/fetch sessions. |
-| `convertTurnMessages.ts` | `projectSessionMessages` pure projector; `buildSnapshotFromSession` history ingest; `convertTurnsToThreadMessages` wrapper; stream-event aggregation. |
+| `truefoundryThreadListAdapter.ts` | `RemoteThreadListAdapter` — cursor-paginated session list. |
+| `convertTurnMessages.ts` | `projectSessionMessages` pure projector; `buildSnapshotFromSessionEvents` history ingest; stream-event aggregation. |
 | `foldPeerThreads.ts` | `PeerThreadFoldState` — folds peer/sub-agent threads under their spawning tool call. |
-| `messageCustomMetadata.ts` | `TrueFoundryMessageCustomMetadata` — typed `metadata.custom` keys for this adapter. |
-| `modelMessageContent.ts` | `model.message` events → assistant content parts (text, reasoning, tool calls). |
-| `streamTurn.ts` | `streamTurnContent` / `resumeTurnStream` generators over `prepareTurn`/`stream`. |
+| `streamTurn.ts` | `streamTurnContent` / `resumeTurnStream` generators over `AgentChatServer`. |
 | `toolApproval.ts` | Approval state, decision mapping, and `user.tool_approval` input collection. |
 | `toolResponse.ts` | Ask-user response state, staging, and `user.tool_response` input collection. |
-| `askUserQuestion.ts` | `ask_user_question` detection and argument parsing. |
-| `mcpAuth.ts` | MCP auth-required detection and structured authorize UI metadata. |
-| `turnEventHelpers.ts` | Appends approval / response / MCP-auth status onto turn updates. |
-| `createSubAgent.ts` | Detects the `create_sub_agent` system tool call. |
-| `extractTurnUserText.ts` / `lastUserMessageText.ts` | Text extraction helpers. |
-| `sessions.ts` | `getSession` wrapper. |
-| `sessionListStartTimestamp.ts` | Default `listSessions` window (1 year). |
-| `constants.ts` | `ROOT_THREAD_ID = "main"`. |
-| `types.ts` / `turnStreamUpdate.ts` | Shared option and update types. |
+| `listPages.ts` | `drainListPages` utility for exhausting token-paginated `ListResult` APIs. |
 
 ### Invariants
 
 - One gateway **session** ⇄ one assistant-ui **thread** (`session.id` = thread `remoteId`).
 - The root thread id is always `"main"` (`ROOT_THREAD_ID`); sub-agent threads nest beneath their `create_sub_agent` tool call.
-- The runtime never holds credentials — always pass a constructed `AgentSessionClient`.
-- Gateway types come from `truefoundry-gateway-sdk/agents`; do not redefine event/turn shapes locally.
+- The runtime never holds credentials — it only accepts a pre-built `AgentChatServer`.
+- Event/turn types are defined in `src/server/events.ts` (first-party, no external SDK dependency).
 - A paused turn's resume `input` must include **all** pending `user.tool_approval` and `user.tool_response` events across every thread in one batch.
-- Approval decisions are allow/deny only (`ApprovalDecision`); there is no `optionId` on the gateway wire.
+- Two agent modes: **named** (`agentName`) and **draft** (`agent: { mode: "draft", defaultAgentSpec }`).
 
 ## Local development
 
@@ -506,7 +703,7 @@ pnpm test       # vitest run
 pnpm typecheck  # tsc --noEmit
 ```
 
-`dist/` is generated output and is gitignored. From the repo root, `pnpm build` builds this package before the Next.js app.
+`dist/` is generated output and is gitignored. From the repo root, `pnpm build` builds this package.
 
 ## Unsupported assistant-ui features
 
@@ -514,22 +711,9 @@ Features below are not implemented in this adapter today. Other assistant-ui cap
 
 | Feature | Notes |
 |---------|-------|
-| Attachment rendering | Attachments are forwarded to the gateway on send when you provide an `AttachmentAdapter`, but user message bubbles show text only. |
+| Attachment rendering | Attachments are forwarded to the gateway on send, but user message bubbles show text only. |
 | Built-in `AttachmentAdapter` | Ships as `trueFoundryAttachmentAdapter` (opt-in via `adapters.attachments`). Not applied by default. |
-| Speech synthesis (`adapters.speech`) | Pass-through only. Not shipped. |
-| Dictation (`adapters.dictation`) | Pass-through only. Not shipped. |
-| Voice (`adapters.voice`) | Pass-through only. Not shipped. |
-| Feedback (`adapters.feedback`) | Pass-through only. Ratings are not persisted to the gateway. |
-| Message edit (`onEdit`) | Not wired. |
-| Regenerate (`onReload`) | Not wired. |
-| Message delete (`onDelete`) | Not wired. |
-| Client-side tool results (`onAddToolResult`) | Not wired. |
-| Tool call resume (`onResumeToolCall`) | Not wired. |
-| Message queue (`queue`) | Not wired. |
-| Branch switching | Not wired. |
+| Speech / Dictation / Voice | Pass-through only. Not shipped. |
+| Feedback | Pass-through only. Ratings are not persisted to the gateway. |
 | Thread rename / archive / delete | Thread-list adapter no-ops. |
 | Thread title generation | Returns an empty stream. |
-| Generative UI message parts | Not mapped from gateway events. |
-| Source citation parts | Not mapped from gateway events. |
-| Message import / external state | `onImport`, `onExportExternalState`, `onLoadExternalState` not wired. |
-| Composer suggestions | `suggestions` not populated. |