docs: chat.agent on Sessions-as-run-manager

Bring the AI Chat documentation in line with the Sessions-as-run-manager
release. Public surface (chat.agent({...}), useTriggerChatTransport,
AgentChat, chat.store / chat.defer / chat.history) is unchanged in
shape; the wiring docs around it changed enough that every transport
example, every server-action snippet, and the auth/session model needed
updating.

New:
- ai-chat/upgrade-guide.mdx — step-by-step migration for prerelease
  customers (replace getStartToken / getChatToken with startSession +
  accessToken, drop runId from ChatSession persistence, etc.).

Updated transport-shape group (these all share the same callback
shape and ship together):
- quick-start, frontend, backend, server-chat, types, reference

Updated peripherals:
- overview, changelog, client-protocol, features, error-handling,
  testing, patterns/version-upgrades, patterns/database-persistence

Outside ai-chat:
- realtime/backend/{streams,input-streams}: callout cross-references
  no longer point at the deleted Sessions docs.

Removed:
- docs/sessions/{overview,quick-start,channels,reference}.mdx — the
  standalone-Sessions surface predates the task-bound model and was
  giving stale guidance. We'll re-introduce Sessions docs once the
  primitive ships a non-chat.agent customer flow worth documenting.
- The "Sessions" group in docs.json's AI nav.

Author: ericallam

docs/ai-chat/backend.mdx

@@ -13,7 +13,7 @@ The highest-level approach. Handles message accumulation, stop signals, turn lif
 </Tip>
 
 <Info>
-  Every `chat.agent` conversation is backed by a [Session](/sessions/overview) — `externalId` is your `chatId`, `type` is `"chat.agent"`. The session outlives any single run, which is why chats can resume across days or deploys without losing identity. You rarely need to touch the session directly (`chat.stream`, `chat.messages`, `chat.stopSignal` wrap everything), but `payload.sessionId` is available if you want to reach in — e.g. `sessions.open(payload.sessionId)` to write from a sub-agent or from outside the turn loop.
+  Every `chat.agent` conversation is backed by a durable Session — `externalId` is your `chatId`, `type` is `"chat.agent"`, `taskIdentifier` is the agent's task ID. The session is the run manager: it owns the chat's runs, persists across run lifecycles, and orchestrates handoffs (idle continuation, `chat.requestUpgrade`). You rarely need to touch the session directly (`chat.stream`, `chat.messages`, `chat.stopSignal` wrap everything), but `payload.sessionId` is available if you want to reach in — e.g. `sessions.open(payload.sessionId)` to write from a sub-agent or from outside the turn loop.
 </Info>
 
 ### Simple: return a StreamTextResult
@@ -674,11 +674,18 @@ export const myChat = chat.agent({
 ```ts app/actions.ts
 "use server";
 
+import { auth } from "@trigger.dev/sdk";
 import { chat } from "@trigger.dev/sdk/ai";
-import type { myChat } from "@/trigger/chat";
 import { db } from "@/lib/db";
 
-export const getChatToken = () => chat.createAccessToken<typeof myChat>("my-chat");
+export const startChatSession = chat.createStartSessionAction("my-chat");
+
+export async function mintChatAccessToken(chatId: string) {
+  return auth.createPublicToken({
+    scopes: { read: { sessions: chatId }, write: { sessions: chatId } },
+    expirationTime: "1h",
+  });
+}
 
 export async function getChatMessages(chatId: string) {
   const found = await db.chat.findUnique({ where: { id: chatId } });
@@ -690,14 +697,12 @@ export async function getAllSessions() {
   const result: Record<
     string,
     {
-      runId: string;
       publicAccessToken: string;
       lastEventId?: string;
     }
   > = {};
   for (const s of sessions) {
     result[s.id] = {
-      runId: s.runId,
       publicAccessToken: s.publicAccessToken,
       lastEventId: s.lastEventId ?? undefined,
     };
@@ -716,12 +721,14 @@ export async function deleteSession(chatId: string) {
 import { useChat } from "@ai-sdk/react";
 import { useTriggerChatTransport } from "@trigger.dev/sdk/chat/react";
 import type { myChat } from "@/trigger/chat";
-import { getChatToken, deleteSession } from "@/app/actions";
+import { mintChatAccessToken, startChatSession, deleteSession } from "@/app/actions";
 
 export function Chat({ chatId, initialMessages, initialSessions }) {
   const transport = useTriggerChatTransport<typeof myChat>({
     task: "my-chat",
-    accessToken: getChatToken,
+    accessToken: ({ chatId }) => mintChatAccessToken(chatId),
+    startSession: ({ chatId, taskId, clientData }) =>
+      startChatSession({ chatId, taskId, clientData }),
     clientData: { userId: currentUser.id }, // Type-checked against clientDataSchema
     sessions: initialSessions,
     onSessionChange: (id, session) => {

docs/ai-chat/changelog.mdx

@@ -8,7 +8,7 @@ description: "Pre-release updates for AI chat agents."
 
 ## `chat.agent` now runs on Sessions
 
-Every chat is backed by a [Session](/sessions/overview) — a new public, durable, bidirectional I/O primitive that outlives any single run. `externalId` = your chat ID, `type` = `"chat.agent"`. Under the hood:
+Every chat is backed by a durable Session row that outlives any single run. `externalId` = your chat ID, `type` = `"chat.agent"`. Under the hood:
 
 - Output chunks stream on `session.out` (was a run-scoped `streams.writer("chat")`).
 - Client messages and stops land on `session.in` as a [`ChatInputChunk`](/ai-chat/reference#chatinputchunk) tagged union (was two run-scoped `streams.input` definitions).
@@ -21,7 +21,7 @@ Public surface (`chat.agent()`, `TriggerChatTransport`, `AgentChat`, `chat.strea
 - **`TriggerChatTaskResult.sessionId`** + **`ChatTaskRunPayload.sessionId`** — you can reach into the raw session via `sessions.open(payload.sessionId)` for advanced cases (writing from a sub-agent, custom transport).
 - **Dashboard Agent tab** resolves via `sessionId` and stays in sync with the live stream across runs.
 
-See the new [Sessions docs](/sessions/overview) for the underlying primitive.
+The full wire-level protocol (session create, channel routes, JWT scopes) is documented in [Client Protocol](/ai-chat/client-protocol).
 
 ## `X-Session-Settled` — fast reconnect on idle chats
 

docs/ai-chat/client-protocol.mdx

@@ -12,7 +12,7 @@ This page documents the protocol that chat clients use to communicate with `chat
 
 ## Overview
 
-`chat.agent` is built on [Sessions](/sessions/overview) — a durable, bidirectional I/O primitive that outlives a single run. A conversation is one session; a session can host many runs over its lifetime.
+`chat.agent` is built on a durable Session row — the unit of state that owns the chat's runs across their full lifecycle. A conversation is one session; a session can host many runs over its lifetime.
 
 The protocol has four parts:
 
@@ -75,7 +75,7 @@ Response:
 
 `id` is the `session_*` friendly ID — persist it alongside your chat state. `isCached: true` means the server returned an existing session for this `externalId` (safe to ignore).
 
-See [`POST /api/v1/sessions`](/sessions/reference#create) for the full request / response schema.
+`POST /api/v1/sessions` is documented inline in the wire-protocol section below.
 
 ## Step 2: Trigger a run
 
@@ -485,17 +485,13 @@ A client needs to track per-conversation:
 | Create session (`POST /api/v1/sessions`) | Secret API key or JWT with `write:sessions` |
 | Close session (`POST /api/v1/sessions/{id}/close`) | Secret API key or JWT with `admin:sessions:{id}` |
 | Trigger task | Secret API key or JWT with `write:tasks` |
-| `.in` append | JWT with `write:sessions:{id}` (or `write:sessions:{id}:in`) |
+| `.in` append | JWT with `write:sessions:{id}` |
 | `.out` subscribe | JWT with `read:sessions:{id}` |
 
-The transport-facing `publicAccessToken` returned from the trigger response carries both `read:sessions:{id}` and `write:sessions:{id}` for the session, plus `read:runs:{runId}` + `write:inputStreams:{runId}` for the run. Use it for all session operations.
-
-See [Session reference — Token scopes](/sessions/reference#token-scopes) for the full scope list.
+The transport-facing `publicAccessToken` returned from `POST /api/v1/sessions` carries both `read:sessions:{id}` and `write:sessions:{id}` for the session — use it for all session operations. A token minted for either the externalId form or the friendlyId form authorizes both URL forms on every read and write route.
 
 ## See also
 
-- [Sessions Overview](/sessions/overview) — The durable primitive chat.agent is built on
-- [Sessions Reference](/sessions/reference) — Full `sessions.*` API and wire endpoints
 - [`TriggerChatTransport`](/ai-chat/frontend) — Built-in browser transport (implements this protocol)
 - [`AgentChat`](/ai-chat/server-chat) — Built-in server-side client
 - [Backend lifecycle](/ai-chat/backend#lifecycle-hooks) — What the agent does on each event

docs/ai-chat/error-handling.mdx

@@ -300,7 +300,12 @@ const { messages, error, status } = useChat({
 
 ```tsx
 function Chat() {
-  const transport = useTriggerChatTransport({ task: "my-chat", accessToken });
+  const transport = useTriggerChatTransport({
+    task: "my-chat",
+    accessToken: ({ chatId }) => mintChatAccessToken(chatId),
+    startSession: ({ chatId, taskId, clientData }) =>
+      startChatSession({ chatId, taskId, clientData }),
+  });
   const { messages, error, sendMessage } = useChat({ transport });
 
   return (
@@ -344,6 +349,30 @@ uiMessageStreamOptions: {
   For richer error structures, use [`chat.response.write()`](/ai-chat/features#custom-data-parts) with a custom `data-error` part type. This lets you ship structured error metadata (codes, retry hints, etc.) instead of stringly-typed messages.
 </Tip>
 
+### Errors from `accessToken` / `startSession`
+
+If your `accessToken` or `startSession` callback throws (auth failure, DB write failure, network error), the rejection surfaces through `useChat`'s `error` state — same as a stream error. The transport doesn't retry the callback automatically; the customer is responsible for handling it.
+
+```tsx
+const transport = useTriggerChatTransport({
+  task: "my-chat",
+  accessToken: async ({ chatId }) => {
+    try {
+      return await mintChatAccessToken(chatId);
+    } catch (err) {
+      // Customer's server action failed (e.g. user lost auth).
+      // Re-throw to surface as a useChat error, or return a sentinel
+      // your UI can detect and prompt re-auth.
+      throw new Error(`AUTH_REFRESH: ${err.message}`);
+    }
+  },
+  startSession: ({ chatId, taskId, clientData }) =>
+    startChatSession({ chatId, taskId, clientData }),
+});
+```
+
+`startSession` failures most commonly mean the customer's authorization layer rejected the request (no plan, quota exceeded, user not allowed to chat with this agent). The customer's server should produce a meaningful error message; the transport propagates it verbatim to `useChat`'s `error` state.
+
 ## Run-level retries
 
 `chat.agent` uses `retry: { maxAttempts: 1 }` — the run **never retries** on unhandled failure. This is intentional: each turn is conversation-preserving, so a true run failure is severe and shouldn't silently retry (which could send duplicate API calls or mutate state twice).

docs/ai-chat/features.mdx

@@ -428,13 +428,17 @@ import { useChat } from "@ai-sdk/react";
 export function Chat({ chatId }) {
   const transport = useTriggerChatTransport({
     task: "my-chat",
-    accessToken: getChatToken,
+    accessToken: ({ chatId }) => mintChatAccessToken(chatId),
+    startSession: ({ chatId, taskId, clientData }) =>
+      startChatSession({ chatId, taskId, clientData }),
     clientData: { userId: currentUser.id },
   });
 
-  // Preload on mount — run starts before the user types anything
+  // Preload on mount — run starts before the user types anything.
+  // Trigger config (idleTimeoutInSeconds, machine, tags) lives in the
+  // server action that wraps `chat.createStartSessionAction`.
   useEffect(() => {
-    transport.preload(chatId, { idleTimeoutInSeconds: 60 });
+    transport.preload(chatId);
   }, [chatId]);
 
   const { messages, sendMessage } = useChat({ id: chatId, transport });