@truefoundry/assistant-ui-runtime 0.1.5 → 0.1.6

package/README.md

@@ -1,55 +1,72 @@
-# truefoundry-agents-assistant-ui-runtime
+# @truefoundry/assistant-ui-runtime
 
-TrueFoundry Gateway agent runtime adapter for [assistant-ui](https://www.assistant-ui.com/).
+A headless React runtime that connects [assistant-ui](https://www.assistant-ui.com/) to TrueFoundry agent sessions. Bring your own UI and server — the adapter maps sessions, turns, and streaming events onto assistant-ui's external-store runtime.
 
-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.
+Built on top of [`@assistant-ui/react`](https://www.assistant-ui.com/), so Thread, Composer, ThreadList, and tool UIs work against a familiar contract out of the box.
 
-## Requirements
+### Checkout the Demo [here](../../examples/assistant-ui-vite)
 
-- **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
+---
+
+## Table of contents
+
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [`useTrueFoundryAgentRuntime` options](#usetruefoundryagentruntime-options)
+- [Agent modes](#agent-modes)
+- [Attachments](#attachments)
+- [Runtime extras](#runtime-extras)
+- [Server port (`AgentChatServer`)](#server-port-agentchatserver)
+- [TrueFoundry gateway plugin](#truefoundry-gateway-plugin)
+- [Exports](#exports)
+- [Architecture](#architecture-source-map)
+- [License](#license)
+
+---
 
 ## 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
+# or
+pnpm add @truefoundry/assistant-ui-runtime @assistant-ui/react
+# or
+yarn add @truefoundry/assistant-ui-runtime @assistant-ui/react
 ```
 
-## Quickstart
+Using the built-in TrueFoundry gateway plugin? Also install the gateway SDK:
 
-### 1. Create an `AgentSessionClient`
+```bash
+npm install truefoundry-gateway-sdk
+```
 
-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.
+**Peers:** React `^18 || ^19`, `@assistant-ui/react` in the host app, and an `AgentChatServer` implementation (plugin or your own). Bundled deps `@assistant-ui/core` and `@assistant-ui/store` are pulled in automatically.
 
-```tsx
-import { AgentSessionClient } from "truefoundry-gateway-sdk/agents";
+---
 
-const client = new AgentSessionClient({
-  apiKey: process.env.TFY_API_KEY!,
-  environment: process.env.TFY_GATEWAY_URL!, // https://gateway.truefoundry.ai/<tenant>
-});
-```
-
-For production, point `fetch` or `auth` at your own backend proxy so secrets never reach the browser.
+## Quick start
 
-### 2. Set up the client runtime
+The fastest path is a TrueFoundry gateway server + the runtime hook + your Thread UI.
 
 ```tsx
 "use client";
 
 import { AssistantRuntimeProvider } from "@assistant-ui/react";
-import { useTrueFoundryAgentRuntime } from "truefoundry-agents-assistant-ui-runtime";
+import {
+  createTrueFoundryChatServer,
+  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({ /* ... */ });
+const server = createTrueFoundryChatServer({
+  apiKey: process.env.TFY_API_KEY!,
+  baseUrl: process.env.TFY_GATEWAY_URL!,
+});
 
 export function MyAssistant() {
   const runtime = useTrueFoundryAgentRuntime({
-    client,
-    agentName: AGENT_NAME,
+    server,
+    agentName: "support-bot",
   });
 
   return (
@@ -60,445 +77,237 @@ export function MyAssistant() {
 }
 ```
 
-### 3. Use the component
+That wires streaming turns, tool approvals, ask-user prompts, MCP auth, and sub-agent nesting through the runtime.
 
-```tsx
-import { MyAssistant } from "@/components/MyAssistant";
+> Prefer a drop-in chat UI? Pair with [`@truefoundry/agent-ui-sdk`](https://www.npmjs.com/package/@truefoundry/agent-ui-sdk) (`AgentChat`) instead of a custom Thread.
 
-export default function Home() {
-  return (
-    <main className="h-dvh">
-      <MyAssistant />
-    </main>
-  );
-}
-```
-
-### 4. Set up UI components
-
-See the assistant-ui [Thread UI guide](https://www.assistant-ui.com/docs/ui/thread) for wiring Thread, composer, and primitives.
+---
 
 ## `useTrueFoundryAgentRuntime` options
 
-`UseTrueFoundryAgentRuntimeOptions` extends assistant-ui's `ExternalStoreSharedOptions`. The adapter-specific fields are:
+`UseTrueFoundryAgentRuntimeOptions` extends assistant-ui's `ExternalStoreSharedOptions`. Adapter-specific fields:
 
 | 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). |
-| `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). |
-
-### Specifying the agent
-
-Pass the saved agent name as `agentName`:
+| ------ | ---- | -------- | ----------- |
+| `server` | `AgentChatServer` | ✅ | Server implementation. The runtime never reads credentials itself. |
+| `agentName` | `string` | ✅\* | Saved agent to run. \*Or use `agent` for draft / explicit named mode. |
+| `agent` | `NamedAgentConfig \| DraftAgentConfig` | — | Discriminated agent source. Overrides `agentName` when set. |
+| `initialSessionId` | `string` | — | Pin an existing session once on mount (uncontrolled). |
+| `threadId` | `string` | — | Controlled active session id; reactive and URL-syncable. |
+| `onThreadIdChange` | `(threadId: string \| undefined) => void` | — | Fires when the active session changes. |
+| `onError` | `(error: unknown) => void` | — | Invoked on stream / load / turn errors. |
+| `adapters` | `{ attachments?, speech?, dictation?, voice?, feedback? }` | — | Optional assistant-ui adapters forwarded to the runtime. |
+
+### Resume / pin a session
 
 ```tsx
 const runtime = useTrueFoundryAgentRuntime({
-  client,
+  server,
   agentName: "support-bot",
+  initialSessionId: "ses_abc123",
 });
 ```
 
-### Adding adapters
+Omit `<ThreadList>` if you manage session ids yourself — the session-list adapter only powers that UI. Each gateway session corresponds to one assistant-ui thread.
 
-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.
+---
 
-```tsx
-import { trueFoundryAttachmentAdapter, useTrueFoundryAgentRuntime } from "truefoundry-agents-assistant-ui-runtime";
+## Agent modes
 
-const runtime = useTrueFoundryAgentRuntime({
-  client,
-  agentName,
-  adapters: { attachments: trueFoundryAttachmentAdapter },
-});
-```
+`agent` / `agentName` control how the runtime sources the agent.
 
-Other adapters (speech, feedback, etc.) follow the same pattern:
+| Mode | Config | Behavior |
+| ---- | ------ | -------- |
+| `named` _(default)_ | `agentName` or `agent: { mode: "named", agentName }` | Runs a saved gateway agent |
+| `draft` | `agent: { mode: "draft", defaultAgentSpec }` | Inline mutable `AgentSpec`, synced via draft sessions |
 
 ```tsx
+// Named
 const runtime = useTrueFoundryAgentRuntime({
-  client,
-  agentName,
-  adapters: { attachments: trueFoundryAttachmentAdapter, speech, feedback },
+  server,
+  agentName: "support-bot",
 });
-```
-
-### Resuming a session
 
-```tsx
+// Draft
 const runtime = useTrueFoundryAgentRuntime({
-  client,
-  agentName,
-  initialSessionId: "ses_abc123",
+  server,
+  agent: {
+    mode: "draft",
+    defaultAgentSpec: { model: { name: "gpt-4o" } },
+    onAgentSpecChange: (spec) => console.log("spec updated", spec),
+  },
 });
 ```
 
-### 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.
+## Attachments
+
+Attachments are **opt-in**. Wire the built-in adapter for composer file pick / previews and gateway forwarding on send.
 
 ```tsx
+import {
+  trueFoundryAttachmentAdapter,
+  useTrueFoundryAgentRuntime,
+} from "@truefoundry/assistant-ui-runtime";
+
 const runtime = useTrueFoundryAgentRuntime({
-  client,
+  server,
   agentName,
-  initialSessionId: "ses_abc123",
+  adapters: { attachments: trueFoundryAttachmentAdapter },
 });
-
-return (
-  <AssistantRuntimeProvider runtime={runtime}>
-    <Thread />
-  </AssistantRuntimeProvider>
-);
-```
-
-Each gateway session corresponds to one assistant-ui thread.
-
-## 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.
-
-Render nested threads with `MessagePartPrimitive.Messages` inside your tool fallback (recommended — no per-tool registration):
-
-```tsx
-import { MessagePartPrimitive, MessagePrimitive } from "@assistant-ui/react";
-import { useAuiState } from "@assistant-ui/store";
-import type { TrueFoundryMessageCustomMetadata } from "truefoundry-agents-assistant-ui-runtime";
-
-function NestedSubAgentAssistantMessage() {
-  const custom = useAuiState(
-    (s) => s.message.metadata.custom as TrueFoundryMessageCustomMetadata,
-  );
-  const heading = custom.subAgent?.title ?? custom.subAgent?.name;
-
-  return (
-    <>
-      {heading != null && (
-        <div className="text-sm text-muted-foreground">{heading}</div>
-      )}
-      <MessagePrimitive.Root data-role="assistant">
-        <MessagePrimitive.Parts />
-      </MessagePrimitive.Root>
-    </>
-  );
-}
-
-<MessagePartPrimitive.Messages
-  components={{
-    AssistantMessage: NestedSubAgentAssistantMessage,
-    UserMessage: () => null,
-  }}
-/>
 ```
 
-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
-
-When the agent requests approval, the assistant message carries a `requires-action` status and the tool-call part exposes an `approval`. Respond through assistant-ui's tool-approval UI; the adapter converts the decision back into a gateway `user.tool_approval` input and resumes the turn. Approvals on nested sub-agent threads are scoped to the correct `threadId` automatically.
-
-For custom approval chrome (a thread-level bar instead of per-part buttons), use the extras hooks — see [Runtime extras](#runtime-extras) below.
-
-## Ask-user tool responses (`tool.response_required`)
-
-When the agent calls the client-side `ask_user_question` system tool, the turn ends with `tool.response_required`. The adapter marks the tool call with a human `interrupt` payload (`question`, `options`) resolved from the originating `model.message` via `ToolCallRef.sourceEventId`.
-
-Collect the user's answer and call `respondToToolResponse({ toolCallId, content })`. The `content` string is free-form (chosen option text, typed answer, etc.).
-
-## Batched resume (approvals + responses)
-
-The gateway requires **every** pending `user.tool_approval` and `user.tool_response` across all threads (root + sub-agents) in a **single** `prepareTurn({ input })` call. The adapter stages decisions locally and only sends when nothing is pending anywhere:
-
-1. User resolves all tool approvals (`respondToToolApproval`).
-2. User answers all ask-user prompts (`respondToToolResponse`).
-3. Runtime collects `collectRequiredActionInputs(message)` → one mixed `TurnInputItem[]` → `sendTurn({ inputs })`.
-
-Do not send partial resumes; the backend rejects incomplete input sets.
-
-## MCP auth
-
-When MCP OAuth is required, the paused assistant message has `metadata.custom.pendingMcpAuth === true` and structured `metadata.custom.mcpServers` (`{ id, name, authUrl }[]`) — both fields are on `TrueFoundryMessageCustomMetadata`. After the user completes OAuth in the browser, call `resumeMcpAuth()` from extras (or `startRun` with `runConfig.custom.resumeMcpAuth: true`).
+---
 
 ## Runtime extras
 
-Typed escape hatch for adapter-specific state and actions — same pattern as `@assistant-ui/react-google-adk`. Read pending state with selector hooks; call actions via `trueFoundryExtras.get(aui)` when rendering inside nested sub-agent threads (readonly context).
+Typed escape hatch for adapter-specific state and actions (same pattern as `@assistant-ui/react-google-adk`). Use selector hooks for thread-level UI; use action hooks / `trueFoundryExtras.get(aui)` inside nested sub-agent renderers.
 
-### Read hooks (thread-level UI)
+### Approvals, ask-user, MCP auth
 
 ```tsx
 import {
   useTrueFoundryApprovals,
   useTrueFoundryToolResponses,
   useTrueFoundryMcpAuth,
-} from "truefoundry-agents-assistant-ui-runtime";
-
-function ApprovalBar() {
-  const { pending, respond } = useTrueFoundryApprovals();
-  if (pending.length === 0) return null;
-
-  const item = pending[0]!;
-  return (
-    <div>
-      <p>Allow {item.toolName}?</p>
-      <button onClick={() => respond({ approvalId: item.approvalId, approved: true })}>
-        Allow
-      </button>
-      <button onClick={() => respond({ approvalId: item.approvalId, approved: false })}>
-        Deny
-      </button>
-    </div>
-  );
-}
-
-function AskUserBar() {
-  const { pending, respond } = useTrueFoundryToolResponses();
-  if (pending.length === 0) return null;
-
-  const item = pending[0]!;
-  return (
-    <div>
-      <p>{item.question ?? "Answer required"}</p>
-      {(item.options ?? []).map((option) => (
-        <button key={option} onClick={() => respond({ toolCallId: item.toolCallId, content: option })}>
-          {option}
-        </button>
-      ))}
-    </div>
-  );
-}
-
-function McpAuthContinue() {
-  const { pending, resume } = useTrueFoundryMcpAuth();
-  if (pending == null) return null;
-
-  return (
-    <div>
-      {pending.mcpServers.map((server) => (
-        <a key={server.id} href={server.authUrl} target="_blank" rel="noreferrer">
-          Authorize {server.name}
-        </a>
-      ))}
-      <button onClick={() => void resume()}>Continue</button>
-    </div>
-  );
-}
-```
-
-### Action hooks (any render context, including nested sub-agents)
-
-```tsx
-import { useTrueFoundryRespondToToolApproval } from "truefoundry-agents-assistant-ui-runtime";
+} from "@truefoundry/assistant-ui-runtime";
 
-function NestedToolApprovalButton({ approvalId }: { approvalId: string }) {
-  const respond = useTrueFoundryRespondToToolApproval();
-  return (
-    <button onClick={() => respond({ approvalId, approved: true })}>
-      Allow
-    </button>
-  );
-}
+const { pending, respond } = useTrueFoundryApprovals();
+const { pending: asks, respond: answer } = useTrueFoundryToolResponses();
+const { pending: mcp, resume } = useTrueFoundryMcpAuth();
 ```
 
-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";
-
-const respondToApproval = useTrueFoundryRespondToToolApproval();
-const respondToResponse = useTrueFoundryRespondToToolResponse();
-const resumeMcpAuth = useTrueFoundryResumeMcpAuth();
-const cancel = useTrueFoundryCancel();
-
-respondToApproval({ approvalId, approved: true });
-respondToResponse({ toolCallId, content: "Option A" });
-void resumeMcpAuth();
-void cancel();
-```
+**Batched resume:** the gateway requires **every** pending `user.tool_approval` and `user.tool_response` across all threads (root + sub-agents) in a **single** resume call. The adapter stages decisions locally and only sends when nothing is pending anywhere — partial resumes are rejected.
 
 ### Hooks reference
 
 | 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 + respond |
+| `useTrueFoundryToolResponses()` | `{ pending, respond }` | Pending ask-user prompts + respond |
+| `useTrueFoundryMcpAuth()` | `{ pending, resume }` | Pending MCP OAuth + resume |
+| `useTrueFoundryRespondToToolApproval()` | `(r) => void` | Respond from any render context |
+| `useTrueFoundryRespondToToolResponse()` | `(r) => void` | Answer ask-user from any render context |
+| `useTrueFoundryResumeMcpAuth()` | `() => Promise<void>` | Resume after MCP OAuth |
+| `useTrueFoundryCancel()` | `() => Promise<void>` | Cancel the active turn |
+| `useTrueFoundryHistoryPagination()` | `{ hasOlderHistory, isLoadingOlderHistory, loadOlderHistory }` | Scroll-up older history |
 
 ### Low-level namespace
 
 ```tsx
-import { trueFoundryExtras, type TrueFoundryRuntimeExtras } from "truefoundry-agents-assistant-ui-runtime";
+import { trueFoundryExtras } 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"`.
+## Server port (`AgentChatServer`)
 
-(Hard aborts still happen when *switching away* — starting a new run or changing sessions abandons the previous turn.)
+The runtime never holds credentials. It accepts any object implementing `AgentChatServer` — a flat, stateless port with methods like `createSession`, `listSessions`, `prepareAndExecuteTurn`, etc.
 
-## Resumable streams
+**First-party:** use [`createTrueFoundryChatServer`](#truefoundry-gateway-plugin) (requires `truefoundry-gateway-sdk`).
 
-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.
+**Your own backend:**
 
-> **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.
+```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) => {
+    /* … */
+  },
+};
+```
 
-## History pagination
+`ListResult<T>` is `{ data: T[]; nextPageToken?: string }` — flat token-based pagination. Optional methods: `deleteSession`, `listTurnEvents`, `subscribeToTurn`, `downloadSandboxFile`.
 
-Thread open no longer drains every turn. Initial load:
+---
 
-1. `listTurns({ limit: 1 })` once — detect a running turn (does **not** walk `page_token`).
-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.
+## TrueFoundry gateway plugin
 
-Older history is opt-in via extras / `useTrueFoundryHistoryPagination()`:
+`createTrueFoundryChatServer` wraps `truefoundry-gateway-sdk` into an `AgentChatServer`. Import from the main entry or the isolated subpath (no React):
 
 ```tsx
-const { hasOlderHistory, isLoadingOlderHistory, loadOlderHistory } =
-  useTrueFoundryHistoryPagination();
+import { createTrueFoundryChatServer } from "@truefoundry/assistant-ui-runtime";
+// or
+import { createTrueFoundryChatServer } from "@truefoundry/assistant-ui-runtime/plugins/truefoundry-agent-server-adapter";
 
-// e.g. IntersectionObserver at the top of the message list
-if (hasOlderHistory && !isLoadingOlderHistory) {
-  void loadOlderHistory();
-}
+const server = createTrueFoundryChatServer({
+  apiKey: process.env.TFY_API_KEY!,
+  baseUrl: process.env.TFY_GATEWAY_URL!,
+});
 ```
 
-`loadOlderHistory` prepends older turns without aborting an active stream.
+See the [plugin README](./src/plugins/truefoundry-agent-server-adapter/README.md) for options, named vs draft routing, `Tfy*` types, type guards, and host-spec extension.
 
-## Public API
+---
 
-Everything below is exported from the package root (`truefoundry-agents-assistant-ui-runtime`).
+## Exports
 
 | 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. |
+| ------ | ---- | ------- |
+| `useTrueFoundryAgentRuntime` | Hook | Root runtime — wires external-store + thread list |
+| `createTrueFoundryChatServer` | Function | TrueFoundry gateway → `AgentChatServer` (also via plugin subpath) |
+| `trueFoundryAttachmentAdapter` | Adapter | Opt-in composer attachments |
+| `trueFoundryExtras` | Namespace | Low-level extras access |
+| `useTrueFoundryApprovals` / `ToolResponses` / `McpAuth` / … | Hooks | Pending state + actions |
+| `AgentChatServer`, `Session`, `Turn`, … | Types | Server port + DTOs |
+| `TfyAgentSpec`, `TfySession`, `isTfyToolInfo`, … | Types / guards | Gateway-concrete types from the plugin |
+| `NamedAgentConfig`, `DraftAgentConfig` | Types | Agent source discriminants |
+
+---
 
 ## 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 |
-|------|----------------|
-| `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. |
-| `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. |
-| `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`. |
-| `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. |
+| ---- | -------------- |
+| `server/types.ts` | `AgentChatServer` + `AgentBuilderServer`, session/turn/pagination types |
+| `server/events.ts` | Concrete turn/stream event types |
+| `useTrueFoundryAgentRuntime.ts` | Public hook — external-store + thread-list + extras |
+| `useTrueFoundryAgentMessages.ts` | Reactive session snapshot: load, stream, cancel, resume |
+| `truefoundryExtras.ts` / `hooks.ts` | Extras namespace + consumer hooks |
+| `convertTurnMessages.ts` | Pure projection from snapshot → thread messages |
+| `foldPeerThreads.ts` | Nest peer/sub-agent threads under spawning tool calls |
+| `plugins/truefoundry-agent-server-adapter/` | Gateway SDK → `AgentChatServer` |
 
 ### 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.
-- 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.
-
-## Local development
+- Root thread id is always `"main"` (`ROOT_THREAD_ID`); sub-agents nest under their `create_sub_agent` tool call.
+- The runtime never holds credentials — only a pre-built `AgentChatServer`.
+- A paused turn's resume `input` must include **all** pending approvals + tool responses across every thread in one batch.
+- Two agent modes: **named** (`agentName`) and **draft** (`agent: { mode: "draft", … }`).
 
-From this package directory:
+### Local development
 
 ```bash
 pnpm build      # tsup → dist/
@@ -506,30 +315,18 @@ 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.
+### Unsupported assistant-ui features
 
-## Unsupported assistant-ui features
+| Feature | Notes |
+| ------- | ----- |
+| Attachment rendering | Forwarded on send; user bubbles show text only today |
+| Speech / Dictation / Voice | Pass-through only |
+| Feedback | Pass-through only; not persisted to the gateway |
+| Thread rename / archive / delete | Thread-list adapter no-ops |
+| Thread title generation | Returns an empty stream |
 
-Features below are not implemented in this adapter today. Other assistant-ui capabilities (streaming, cancel, tool approval, ask-user responses, MCP auth, sub-agent nesting, resumable streams, reasoning parts) are supported.
+---
 
-| Feature | Notes |
-|---------|-------|
-| Attachment rendering | Attachments are forwarded to the gateway on send when you provide an `AttachmentAdapter`, 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. |
-| 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. |
+## License
+
+See [LICENSE](../../LICENSE).