@ably/ai-transport 0.1.0 → 0.3.0

package/dist/vercel/transport/index.d.ts

@@ -1,4 +1,5 @@
-import { ClientTransport, ClientTransportOptions, ServerTransport, ServerTransportOptions } from '../../core/transport/types.js';
+import { AgentSession, AgentSessionOptions, ClientSession, ClientSessionOptions } from '../../core/transport/types.js';
+import { VercelInput, VercelOutput, VercelProjection } from '../codec/index.js';
 /**
  * Vercel AI SDK transport wrappers that pre-bind the UIMessageCodec.
  *
@@ -6,34 +7,37 @@ import { ClientTransport, ClientTransportOptions, ServerTransport, ServerTranspo
  * explicitly when using the Vercel AI SDK integration.
  *
  * ```ts
- * import { createClientTransport } from '@ably/ai-transport/vercel';
+ * import { createClientSession } from '@ably/ai-transport/vercel';
  *
- * const transport = createClientTransport({ channel });
+ * const session = createClientSession({ client, channelName: 'ai:demo' });
+ * await session.connect();
  * ```
  */
 export type { ChatTransport, ChatTransportOptions, SendMessagesRequestContext } from './chat-transport.js';
 export { createChatTransport } from './chat-transport.js';
 import type * as AI from 'ai';
-/** Core client transport options with Vercel AI SDK types pre-applied. */
-type CoreClientOpts = ClientTransportOptions<AI.UIMessageChunk, AI.UIMessage>;
-/** Options for creating a Vercel client transport. Same as core options but without the codec field, and with `api` optional (defaults to `"/api/chat"`). */
-export type VercelClientTransportOptions = Omit<CoreClientOpts, 'codec' | 'api'> & Partial<Pick<CoreClientOpts, 'api'>>;
-/** Options for creating a Vercel server transport. Same as core options but without the codec field. */
-export type VercelServerTransportOptions = Omit<ServerTransportOptions<AI.UIMessageChunk, AI.UIMessage>, 'codec'>;
-export declare const DEFAULT_VERCEL_API = "/api/chat";
+/** Core client session options with Vercel AI SDK types pre-applied. */
+type CoreClientOpts = ClientSessionOptions<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>;
+/** Options for creating a Vercel client session. Same as core options but without the codec field. */
+export type VercelClientSessionOptions = Omit<CoreClientOpts, 'codec'>;
+/** Options for creating a Vercel agent session. Same as core options but without the codec field. */
+export type VercelAgentSessionOptions = Omit<AgentSessionOptions<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>, 'codec'>;
 /**
- * Create a client-side transport pre-configured with the Vercel AI SDK codec.
+ * Create a client-side session pre-configured with the Vercel AI SDK codec.
  *
- * Equivalent to calling the core `createClientTransport` with `codec: UIMessageCodec`.
- * @param options - Configuration for the client transport (codec is provided automatically).
- * @returns A new {@link ClientTransport} for Vercel AI SDK UIMessage/UIMessageChunk types.
+ * Equivalent to calling the core `createClientSession` with `codec: UIMessageCodec`.
+ * The core session is a pure Ably-channel transport — it never sends HTTP.
+ * To wake a serverless agent over HTTP, POST `run.toInvocation().toJSON()`
+ * yourself, or use `createChatTransport` (which does it for useChat parity).
+ * @param options - Configuration for the client session (codec is provided automatically).
+ * @returns A new {@link ClientSession} for Vercel AI SDK UIMessage/UIMessageChunk types.
  */
-export declare const createClientTransport: (options: VercelClientTransportOptions) => ClientTransport<AI.UIMessageChunk, AI.UIMessage>;
+export declare const createClientSession: (options: VercelClientSessionOptions) => ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>;
 /**
- * Create a server-side transport pre-configured with the Vercel AI SDK codec.
+ * Create an agent (server-side) session pre-configured with the Vercel AI SDK codec.
  *
- * Equivalent to calling the core `createServerTransport` with `codec: UIMessageCodec`.
- * @param options - Configuration for the server transport (codec is provided automatically).
- * @returns A new {@link ServerTransport} for Vercel AI SDK UIMessage/UIMessageChunk types.
+ * Equivalent to calling the core `createAgentSession` with `codec: UIMessageCodec`.
+ * @param options - Configuration for the agent session (codec is provided automatically).
+ * @returns A new {@link AgentSession} for Vercel AI SDK UIMessage/UIMessageChunk types.
  */
-export declare const createServerTransport: (options: VercelServerTransportOptions) => ServerTransport<AI.UIMessageChunk, AI.UIMessage>;
+export declare const createAgentSession: (options: VercelAgentSessionOptions) => AgentSession<VercelOutput, VercelProjection, AI.UIMessage>;

package/dist/vercel/transport/run-output-stream.d.ts

@@ -0,0 +1,54 @@
+import { ClientSession } from '../../core/transport/types.js';
+import { VercelInput, VercelOutput, VercelProjection } from '../codec/index.js';
+/**
+ * Vercel-owned per-run output stream.
+ *
+ * Builds the `ReadableStream<UIMessageChunk>` that `useChat` consumes by
+ * subscribing to the session Tree's `output` and `run` events for a single
+ * run. Streaming is a useChat-integration concern, so it lives in the Vercel
+ * layer rather than the generic core: the core Tree is the fan-out point, and
+ * this projects its events into the shape `useChat` expects.
+ *
+ * Close semantics — the stream the consumer reads ends when:
+ * - a **terminal chunk** (`finish` / `error` / `abort`) is folded for the run.
+ *   This is the signal `useChat`'s `sendAutomaticallyWhen` waits for, and it
+ *   fires even when the run merely *suspends* for a tool call (a tool-calls
+ *   `finish` ends the consumer stream while the core run stays alive in the
+ *   Tree for the continuation); or
+ * - the run reaches `run-end`, which is always terminal (safety net for a run
+ *   that ends without emitting a terminal chunk). A `run-suspend` keeps the
+ *   core run alive and does not close the consumer stream.
+ *
+ * It errors when the session emits a non-fatal `error` (e.g. channel
+ * continuity loss, or an agent-reported mid-run error), so the consumer's
+ * reader rejects rather than hanging.
+ */
+import type * as AI from 'ai';
+type VercelSession = ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>;
+/** A consumer-facing run output stream plus the handle to close it externally. */
+interface RunOutputStream {
+    /** The stream of decoded outputs for the run, as `useChat` consumes it. */
+    stream: ReadableStream<VercelOutput>;
+    /** Close the stream now (e.g. on local cancel). Idempotent. */
+    close: () => void;
+}
+/**
+ * Create a consumer-facing output stream for a send, sourced from the session
+ * Tree's events. See the module docs for close/error semantics. The returned
+ * `close` lets the caller settle the stream for conditions the Tree doesn't
+ * surface (local cancel). Session errors are wired internally to error the
+ * stream.
+ *
+ * Outputs route PURELY by the triggering input's codec-message-id — the key the
+ * client owns from send time, before the agent mints the runId. The agent's
+ * minted runId is supplied as a promise so the run-end safety-net can still
+ * close the stream once it resolves.
+ * @param session - The Vercel client session whose Tree to observe.
+ * @param runId - The agent-minted runId, resolved when run-start is observed.
+ *   Used only by the run-end safety-net; routing keys on `inputCodecMessageId`.
+ * @param inputCodecMessageId - The triggering input's codec-message-id. An
+ *   output routes to this stream when it carries this id.
+ * @returns The stream and its external close handle.
+ */
+export declare const createRunOutputStream: (session: VercelSession, runId: Promise<string>, inputCodecMessageId: string) => RunOutputStream;
+export {};

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** SDK version. Kept in sync with `package.json` by the `/release` workflow. */
+export declare const VERSION = "0.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ably/ai-transport",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Ably transport and codecs for building AI applications with Ably.",
   "type": "module",
   "main": "dist/ably-ai-transport.umd.cjs",
@@ -36,26 +36,6 @@
     },
     "./package.json": "./package.json"
   },
-  "scripts": {
-    "build": "npm run build:clean && npm run build:core && npm run build:react && npm run build:vercel && npm run build:vercel-react",
-    "build:clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build:core": "vite build --config ./src/vite.config.ts",
-    "build:react": "vite build --config ./src/react/vite.config.ts --emptyOutDir",
-    "build:vercel": "vite build --config ./src/vercel/vite.config.ts --emptyOutDir",
-    "build:vercel-react": "vite build --config ./src/vercel/react/vite.config.ts --emptyOutDir",
-    "prepare": "npm run build",
-    "lint": "eslint .",
-    "lint:fix": "eslint --fix .; (npm run format > /dev/null)",
-    "format": "prettier --list-different --write .",
-    "format:check": "prettier --check .",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:integration": "vitest run --config vitest.config.integration.ts",
-    "check:error-codes": "tsx scripts/validate-error-codes.ts",
-    "precommit": "npm run format:check && npm run lint && npm run typecheck",
-    "docs": "typedoc",
-    "docs:lint": "typedoc --emit none"
-  },
   "files": [
     "dist/**",
     "src/**",
@@ -80,10 +60,17 @@
   },
   "homepage": "https://github.com/ably/ably-ai-transport-js#readme",
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
+  },
+  "devEngines": {
+    "packageManager": {
+      "name": "pnpm",
+      "version": "11.3.0",
+      "onFail": "download"
+    }
   },
   "peerDependencies": {
-    "ably": "^2.21.0",
+    "ably": "^2.23.0",
     "ai": "^6",
     "react": "^18.0.0 || ^19.0.0"
   },
@@ -101,6 +88,7 @@
     "@eslint/eslintrc": "^3.3.0",
     "@eslint/js": "^10.0.1",
     "@testing-library/react": "^16.3.2",
+    "@types/node": "^25.0.0",
     "@types/react": "^19.2.14",
     "@typescript-eslint/eslint-plugin": "^8.58.2",
     "@typescript-eslint/parser": "^8.58.2",
@@ -125,5 +113,24 @@
     "vite": "^8.0.0",
     "vite-plugin-dts": "^4.5.4",
     "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:core && pnpm run build:react && pnpm run build:vercel && pnpm run build:vercel-react",
+    "build:clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build:core": "vite build --config ./src/vite.config.ts",
+    "build:react": "vite build --config ./src/react/vite.config.ts --emptyOutDir",
+    "build:vercel": "vite build --config ./src/vercel/vite.config.ts --emptyOutDir",
+    "build:vercel-react": "vite build --config ./src/vercel/react/vite.config.ts --emptyOutDir",
+    "lint": "eslint .",
+    "lint:fix": "eslint --fix .; (pnpm run format > /dev/null)",
+    "format": "prettier --list-different --write .",
+    "format:check": "prettier --check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:integration": "vitest run --config vitest.config.integration.ts",
+    "check:error-codes": "tsx scripts/validate-error-codes.ts",
+    "precommit": "pnpm run format:check && pnpm run lint && pnpm run typecheck",
+    "docs": "typedoc",
+    "docs:lint": "typedoc --emit none"
   }
-}
+}

package/src/constants.ts

@@ -1,12 +1,12 @@
 /**
  * Shared constants used by both codec and transport layers.
  *
- * Header constants define the `x-ably-*` wire protocol. Message and event
- * name constants define the transport lifecycle signals on the channel.
+ * Header constants define the transport wire header names. Message and event
+ * name constants define the session lifecycle signals on the channel.
  *
  * These live at the top level (not in codec/ or transport/) because both
  * layers need them — the codec core reads/writes stream and status headers,
- * while the transport layer reads/writes turn, cancel, and role headers.
+ * while the transport layer reads/writes run, cancel, and role headers.
  */
 
 // ---------------------------------------------------------------------------
@@ -14,91 +14,164 @@
 // ---------------------------------------------------------------------------
 
 /** Header: whether this Ably message uses streaming (message appends) or is discrete. Always "true" or "false". */
-export const HEADER_STREAM = 'x-ably-stream';
+export const HEADER_STREAM = 'stream';
 
-/** Header: lifecycle status of a streamed message. Only set when x-ably-stream is "true". */
-export const HEADER_STATUS = 'x-ably-status';
+/** Header: lifecycle status of a streamed message. Only set when stream is "true". One of "streaming", "complete", or "cancelled". */
+export const HEADER_STATUS = 'status';
 
 /** Header: stream identity. Set by the encoder on every streamed message; read by the decoder to correlate streams. */
-export const HEADER_STREAM_ID = 'x-ably-stream-id';
+export const HEADER_STREAM_ID = 'stream-id';
 
 /** Header: marks a message as a discrete message part (from writeMessages). Set by publishDiscreteBatch; not set on lifecycle events from publishDiscrete. */
-export const HEADER_DISCRETE = 'x-ably-discrete';
+export const HEADER_DISCRETE = 'discrete';
 
 // ---------------------------------------------------------------------------
-// Identity headers (used by transport for turn correlation)
+// Identity headers (used by transport for run correlation)
 // ---------------------------------------------------------------------------
 
-/** Header: turn correlation ID. Set on every message in a turn. */
-export const HEADER_TURN_ID = 'x-ably-turn-id';
+/** Header: run correlation ID. Set on every agent-published message and on continuation client inputs, but omitted from the originating fresh client input (the agent mints the run-id at run-start). */
+export const HEADER_RUN_ID = 'run-id';
+
+/** Header: invocation correlation ID; identifies a specific invocation under a run. Agent-minted and stamped by the agent on every event it publishes for the invocation — run lifecycle (run-start/resume/suspend/end) and assistant outputs. Never set by the client on its input. */
+export const HEADER_INVOCATION_ID = 'invocation-id';
+
+/**
+ * Header: per-event identifier stamped by the client on every
+ * client-published event in a send — user-message events AND amend
+ * events (tool-approval responses, client tool outputs). Distinct from
+ * `codec-message-id` so it survives edits/retries that reuse the same
+ * codec-message-id, and so amend events that target an existing message can
+ * carry their own per-send identity. The invocation body lists every
+ * inputEventId the agent must observe on the channel before starting LLM
+ * work — see `Run.start()`'s input-event lookup.
+ */
+export const HEADER_EVENT_ID = 'event-id';
 
 /** Header: message identity. Assigned per message (user or assistant). Used for optimistic reconciliation on the client. */
-export const HEADER_MSG_ID = 'x-ably-msg-id';
+export const HEADER_CODEC_MESSAGE_ID = 'codec-message-id';
 
-/** Header: clientId of the user who initiated the turn. Set by the server on stream messages. */
-export const HEADER_TURN_CLIENT_ID = 'x-ably-turn-client-id';
+/** Header: clientId of the user who initiated the run. Stamped by the client on its user input and re-stamped by the agent on the run's lifecycle and stream messages. */
+export const HEADER_RUN_CLIENT_ID = 'run-client-id';
 
-/** Header: message role (e.g. "user", "assistant"). */
-export const HEADER_ROLE = 'x-ably-role';
+/**
+ * Header: clientId of the input event (the `ai-input`) that drove the
+ * current invocation. The agent reads the publisher's Ably-level `clientId`
+ * from the triggering input event on the channel and re-stamps it as
+ * `input-client-id` on every event it publishes for that invocation
+ * (run lifecycle and assistant outputs). May differ from
+ * `run-client-id` on continuation invocations driven by an input
+ * from a non-owner (e.g. a tool-result publish from a different client).
+ * Not stamped on `ai-input` events themselves — the wire publisher's
+ * Ably `clientId` already conveys that.
+ */
+export const HEADER_INPUT_CLIENT_ID = 'input-client-id';
 
-/** Header: the msg-id of the existing message this Ably message amends. Present on cross-turn amendment events. */
-export const HEADER_AMEND = 'x-ably-amend';
+/** Header: message role (e.g. "user", "assistant"). */
+export const HEADER_ROLE = 'role';
 
 // ---------------------------------------------------------------------------
-// Cancel headers
+// Fork / branching headers
 // ---------------------------------------------------------------------------
 
-/** Header: cancel a specific turn by ID. */
-export const HEADER_CANCEL_TURN_ID = 'x-ably-cancel-turn-id';
-
-/** Header: cancel all turns belonging to the sender's clientId. */
-export const HEADER_CANCEL_OWN = 'x-ably-cancel-own';
+/** Header: the codec-message-id of the immediately preceding message in this branch. */
+export const HEADER_PARENT = 'parent';
 
-/** Header: cancel all turns on the channel. */
-export const HEADER_CANCEL_ALL = 'x-ably-cancel-all';
+/** Header: the codec-message-id of the message this one replaces (creates a fork). */
+export const HEADER_FORK_OF = 'fork-of';
 
-/** Header: cancel all turns belonging to a specific clientId. */
-export const HEADER_CANCEL_CLIENT_ID = 'x-ably-cancel-client-id';
+/**
+ * Header: the codec-message-id of the assistant message this run regenerates.
+ *
+ * Stamped on the regenerate wire (and echoed on `run-start`) when the
+ * client requested a regeneration. A regenerate run parents at the SAME input
+ * node as the reply it regenerates, so it joins that input's reply runs as a
+ * same-parent sibling (no fork-of). The View consults this header to resolve
+ * the message-level sibling group and to drop the regenerated message from
+ * earlier Runs in the visible chain (Spec: AIT-CT13d).
+ */
+export const HEADER_MSG_REGENERATE = 'msg-regenerate';
 
 // ---------------------------------------------------------------------------
-// Fork / branching headers
+// Run lifecycle headers
 // ---------------------------------------------------------------------------
 
-/** Header: the msg-id of the immediately preceding message in this branch. */
-export const HEADER_PARENT = 'x-ably-parent';
+/** Header: reason a run ended (on ai-run-end messages). */
+export const HEADER_RUN_REASON = 'run-reason';
 
-/** Header: the msg-id of the message this one replaces (creates a fork). */
-export const HEADER_FORK_OF = 'x-ably-fork-of';
+/**
+ * Header: the `codec-message-id` of the input event that triggered the run.
+ * The triggering input is the one whose `event-id` matches the invocation's
+ * `inputEventId` (the last input of the originating send). The agent
+ * re-stamps it on every event it publishes for the invocation (run
+ * lifecycle + assistant outputs), mirroring `input-client-id`. This is the
+ * codec-message-id the client owns at send time, so it lets the client
+ * correlate any of those events back to the originating input without
+ * depending on a client-minted run-id or invocation-id.
+ */
+export const HEADER_INPUT_CODEC_MESSAGE_ID = 'input-codec-message-id';
 
 // ---------------------------------------------------------------------------
-// Turn lifecycle headers
+// Run-end error headers (set on `ai-run-end` when `run-reason: error`)
 // ---------------------------------------------------------------------------
 
-/** Header: reason a turn ended (on x-ably-turn-end messages). */
-export const HEADER_TURN_REASON = 'x-ably-turn-reason';
+/** Header: numeric error code accompanying an `ai-run-end` with reason `error`. */
+export const HEADER_ERROR_CODE = 'error-code';
+
+/** Header: human-readable error message accompanying an `ai-run-end` with reason `error`. */
+export const HEADER_ERROR_MESSAGE = 'error-message';
 
 // ---------------------------------------------------------------------------
 // Message / event names
 // ---------------------------------------------------------------------------
 
-/** Message name: client->server cancel signal. */
-export const EVENT_CANCEL = 'x-ably-cancel';
+/**
+ * Message name: client->agent cancel intent. Targets a run by `run-id` (a
+ * continuation, whose run-id the client already knows) and/or by
+ * `input-codec-message-id` (a fresh send, whose run-id the agent mints at
+ * run-start — so the client can only key the cancel by the triggering input's
+ * codec-message-id it owns at send time). The agent resolves whichever is
+ * present to the registered run; a cancel that arrives before the run is known
+ * (the input-event lookup hasn't resolved the input id to a run yet) is
+ * buffered by `input-codec-message-id` and honoured when the run resolves it.
+ * Also carries an `event-id` so channel rewind redelivers it to a per-request /
+ * serverless agent that attaches after the cancel was published.
+ */
+export const EVENT_CANCEL = 'ai-cancel';
 
-/** Message name: server publishes this to signal a turn has started. */
-export const EVENT_TURN_START = 'x-ably-turn-start';
+/** Message name: server publishes this to signal a run has started. */
+export const EVENT_RUN_START = 'ai-run-start';
 
-/** Message name: server publishes this to signal a turn has ended. */
-export const EVENT_TURN_END = 'x-ably-turn-end';
+/**
+ * Message name: server publishes this to signal a run has suspended — paused
+ * awaiting participant input (e.g. a client tool result or approval) without
+ * ending. The run stays live and may be resumed under the same `runId`.
+ * Distinct from `ai-run-end`, which is terminal.
+ */
+export const EVENT_RUN_SUSPEND = 'ai-run-suspend';
 
-/** Message name: transport-level abort signal (stream cancelled). */
-export const EVENT_ABORT = 'x-ably-abort';
+/**
+ * Message name: server publishes this when a subsequent invocation re-enters an
+ * already-started run (e.g. a tool-result follow-up under the same `runId`).
+ * A pure re-entry signal: unlike `ai-run-start` it carries no `parent` / `fork-of`
+ * (the original `ai-run-start` already established the run's structure).
+ */
+export const EVENT_RUN_RESUME = 'ai-run-resume';
 
-/** Message name: transport-level error signal. */
-export const EVENT_ERROR = 'x-ably-error';
+/** Message name: server publishes this to signal a run has ended. */
+export const EVENT_RUN_END = 'ai-run-end';
 
-// ---------------------------------------------------------------------------
-// Domain header prefix (used by codec implementations)
-// ---------------------------------------------------------------------------
+/**
+ * Message name: every agent-published codec event (text, reasoning, tool calls,
+ * tool outputs, lifecycle helpers, file / source parts, data-* chunks) rides
+ * this single wire name. The codec event's own `type` is carried in the
+ * SDK-controlled codec-level `kind` header so the decoder can dispatch.
+ */
+export const EVENT_AI_OUTPUT = 'ai-output';
 
-/** Prefix for domain-specific headers. Distinguishes codec-layer headers from transport `x-ably-*` headers. */
-export const DOMAIN_HEADER_PREFIX = 'x-domain-';
+/**
+ * Message name: every client-published codec event (user-message parts,
+ * tool-approval responses, regenerate signals) rides this single wire
+ * name. The codec event's own kind is carried in the codec-level `kind`
+ * header so the decoder can dispatch.
+ */
+export const EVENT_AI_INPUT = 'ai-input';

package/src/core/agent.ts

@@ -0,0 +1,92 @@
+/**
+ * Wraps the two paths chat-js uses (see ChatClient._addAgent): the
+ * `options.agents` mutation (read by ably-js when opening the initial
+ * WebSocket) and the `params.agent` channel option (sent on ATTACH so
+ * an already-open connection still carries the identifier).
+ *
+ * `options.agents` is a private API on the Realtime client — no public
+ * typed accessor exists in the `ably` package — so this module casts to a
+ * `RealtimeWithOptions` shape to write it.
+ */
+
+import type * as Ably from 'ably';
+
+import { VERSION } from '../version.js';
+
+interface RealtimeWithOptions extends Ably.Realtime {
+  options: { agents?: Record<string, string | undefined> };
+}
+
+const SDK_NAME = 'ai-transport-js';
+
+/**
+ * Merge `agents` into `client.options.agents` and return the space-separated
+ * `params.agent` string for channel ATTACH.
+ * @param client - The Ably Realtime client to mutate.
+ * @param agents - Map of agent-name to version strings to register.
+ * @returns Channel options containing `params.agent` for `channels.get`.
+ */
+const injectAgents = (
+  client: Ably.Realtime,
+  // CAST: Ably.Realtime's public type omits `options.agents`, but the SDK
+  // does carry it at runtime. ably-chat-js relies on the same shape — see
+  // ChatClient._addAgent in https://github.com/ably/ably-chat-js.
+  agents: Record<string, string>,
+): { params: { agent: string } } => {
+  const realtime = client as RealtimeWithOptions;
+  realtime.options.agents = { ...realtime.options.agents, ...agents };
+  return { params: { agent: joinAgents(agents) } };
+};
+
+/**
+ * Build the agent-name → version map this SDK registers for the given codec.
+ * @param codec - The codec instance whose optional identifier opts into registration.
+ * @param codec.adapterTag - The optional Ably-Agent identifier; registered as an agent when present.
+ * @returns Map of agent name to version, always including this SDK.
+ */
+const buildAgents = (codec?: { readonly adapterTag?: string }): Record<string, string> => {
+  const adapterTag = codec?.adapterTag;
+  const agents: Record<string, string> = { [SDK_NAME]: VERSION };
+  if (adapterTag) agents[adapterTag] = VERSION;
+  return agents;
+};
+
+/**
+ * Render an agents map as the space-separated `name/version` string Ably expects.
+ * @param agents - Map of agent name to version.
+ * @returns The space-separated `name/version` agent string.
+ */
+const joinAgents = (agents: Record<string, string>): string =>
+  Object.entries(agents)
+    .map(([name, version]) => `${name}/${version}`)
+    .join(' ');
+
+/**
+ * The space-separated `params.agent` string this SDK stamps on channel ATTACH —
+ * `ai-transport-js/<version>` plus the codec's adapter tag when present. Pure:
+ * unlike {@link registerAgent} it does not mutate the client. Use it to seed a
+ * `<ChannelProvider options>` so ably-js's React hooks append their own agent
+ * additively (`channelOptionsForReactHooks`) rather than overwriting this SDK's.
+ * @param codec - The codec instance whose optional identifier opts into registration.
+ * @param codec.adapterTag - The optional Ably-Agent identifier; registered as an agent when present.
+ * @returns The channel `params.agent` string.
+ */
+export const channelAgent = (codec?: { readonly adapterTag?: string }): string => joinAgents(buildAgents(codec));
+
+/**
+ * Register this SDK (and optionally a codec) on the supplied Realtime client
+ * and return the channel options the caller should pass to
+ * `client.channels.get(...)` so the agent is also carried on channel ATTACH.
+ * Sets `options.agents['ai-transport-js'] = VERSION`. When the codec carries an
+ * `adapterTag`, also sets `options.agents[adapterTag] = VERSION`.
+ * Idempotent — repeated calls with the same client and codec produce the same keys/values.
+ * Spec: AIT-CT1a, AIT-CT1a2, AIT-CT1a3, AIT-ST1a, AIT-ST1a2, AIT-ST1a3.
+ * @param client - The Ably Realtime client to register on.
+ * @param codec - The codec instance whose optional identifier opts into registration.
+ * @param codec.adapterTag - The optional Ably-Agent identifier; registered as an agent when present.
+ * @returns Channel options containing `params.agent` for `channels.get`.
+ */
+export const registerAgent = (
+  client: Ably.Realtime,
+  codec?: { readonly adapterTag?: string },
+): { params: { agent: string } } => injectAgents(client, buildAgents(codec));

package/src/core/channel-options.ts

@@ -0,0 +1,89 @@
+/**
+ * Channel-mode resolution shared by the sessions and the React provider.
+ *
+ * Presence, pub/sub, and annotation publishing are all part of the server's
+ * default channel-mode set, so a channel attached with no mode flags is granted
+ * them automatically. LiveObjects is different: object operations require the
+ * `object_subscribe` / `object_publish` modes, which are NOT in the default
+ * set, so the channel must be attached with explicit modes to use them.
+ *
+ * Setting `modes` on the wire is a full replacement, not additive: the moment
+ * an ATTACH carries any mode flag the server takes that bitfield verbatim and
+ * never falls back to its default set. So requesting object modes means also
+ * requesting everything the default set would grant, plus the object modes.
+ * {@link AIT_BASE_MODES} is exactly the server default, so opting into extra
+ * modes adds the extras and changes nothing else.
+ *
+ * Every place that resolves the session's channel options — both session
+ * constructors and the React `<ChannelProvider>` — must funnel through
+ * {@link resolveChannelModes} so they all request the SAME modes in the SAME
+ * order. ably-js compares modes order- and duplicate-sensitively when deciding
+ * whether a `setOptions` call needs a reattach; identical arrays compare equal,
+ * so consistent resolution avoids both spurious reattaches and silent mode
+ * reversion when one writer omits modes another set.
+ */
+
+import type * as Ably from 'ably';
+
+/**
+ * The modes AI Transport always needs — byte-for-byte the server's default
+ * channel-mode set (`PUBLISH | SUBSCRIBE | PRESENCE | PRESENCE_SUBSCRIBE |
+ * ANNOTATION_PUBLISH`). Because this equals the default, requesting it plus
+ * extra modes (e.g. {@link OBJECT_MODES}) grants the same access as the default
+ * set plus those extras.
+ */
+export const AIT_BASE_MODES: readonly Ably.ChannelMode[] = [
+  'PUBLISH',
+  'SUBSCRIBE',
+  'PRESENCE',
+  'PRESENCE_SUBSCRIBE',
+  'ANNOTATION_PUBLISH',
+];
+
+/**
+ * The channel modes required to read and write Ably LiveObjects. Pass as the
+ * session's `channelModes` option (`channelModes: OBJECT_MODES`) to enable the
+ * `object` accessor on a session and the LiveObjects channel hooks under a
+ * `<ClientSessionProvider>`.
+ */
+export const OBJECT_MODES: readonly Ably.ChannelMode[] = ['OBJECT_SUBSCRIBE', 'OBJECT_PUBLISH'];
+
+/**
+ * Canonical ordering for every known channel mode. {@link resolveChannelModes}
+ * emits modes in this order so two resolutions of the same mode set produce
+ * identical arrays, which ably-js treats as equal (no reattach churn).
+ */
+const MODE_ORDER: readonly Ably.ChannelMode[] = [
+  'PUBLISH',
+  'SUBSCRIBE',
+  'PRESENCE',
+  'PRESENCE_SUBSCRIBE',
+  'OBJECT_PUBLISH',
+  'OBJECT_SUBSCRIBE',
+  'ANNOTATION_PUBLISH',
+  'ANNOTATION_SUBSCRIBE',
+];
+
+/**
+ * Resolve the channel modes AI Transport should request on its channel.
+ *
+ * Returns `undefined` when the caller asks for no extra modes, so the channel
+ * attaches with no mode flags and the server applies its default set. When
+ * extra modes are supplied (e.g. {@link OBJECT_MODES}),
+ * returns {@link AIT_BASE_MODES} unioned with them, de-duplicated and in a
+ * fixed canonical order so repeated resolutions compare equal.
+ *
+ * Modes outside {@link MODE_ORDER} (which should not occur for a valid
+ * {@link Ably.ChannelMode}, but is possible with the type's lowercase aliases)
+ * are appended after the canonical modes, sorted alphabetically, so the result
+ * is still deterministic.
+ * @param extraModes - Additional modes to request on top of {@link AIT_BASE_MODES}. Omit or pass an empty array to request no modes at all.
+ * @returns The canonically-ordered, de-duplicated mode set, or `undefined` when no extra modes were requested.
+ */
+export const resolveChannelModes = (extraModes?: readonly Ably.ChannelMode[]): Ably.ChannelMode[] | undefined => {
+  if (extraModes === undefined || extraModes.length === 0) return undefined;
+  const requested = new Set<Ably.ChannelMode>([...AIT_BASE_MODES, ...extraModes]);
+  const ordered = MODE_ORDER.filter((mode) => requested.has(mode));
+  const unknown = [...requested].filter((mode) => !MODE_ORDER.includes(mode)).toSorted();
+  return [...ordered, ...unknown];
+};