@ably/ai-transport 0.2.0 → 0.3.0

package/dist/vercel/react/contexts/chat-transport-context.d.ts

@@ -19,7 +19,7 @@ export interface ChatTransportSlot {
  * The shape of the single {@link ChatTransportContext} value.
  * Combines the nearest slot with the full registry in one context object.
  */
-export interface ChatTransportContextValue {
+interface ChatTransportContextValue {
     /** The slot from the nearest {@link ChatTransportProvider} in the tree. */
     readonly nearest: ChatTransportSlot | undefined;
     /** All registered slots, keyed by channelName. */
@@ -31,3 +31,4 @@ export interface ChatTransportContextValue {
  * read by {@link useChatTransport}.
  */
 export declare const ChatTransportContext: import('react').Context<ChatTransportContextValue>;
+export {};

package/dist/vercel/run-end-reason.d.ts

@@ -1,14 +1,69 @@
 import { RunEndReason, StreamResult } from '../core/transport/types.js';
+import * as Ably from 'ably';
 import type * as AI from 'ai';
 /**
- * Derive the outcome for a Vercel `streamText` response that was piped through
- * `Run.pipe`: either a terminal {@link RunEndReason} the caller passes to
- * `Run.end`, or the sentinel `'suspend'` telling the caller to call
- * `Run.suspend` instead. Preserves transport-level outcomes (`'cancelled'`,
- * `'error'`) from the pipe result; when the pipe completed naturally, awaits
- * Vercel's `finishReason` and returns `'suspend'` for `'tool-calls'` (the LLM
- * requested tools the SDK did not auto-execute, so the run should suspend
- * rather than end), or `'complete'` otherwise.
+ * The outcome of a Vercel `streamText` response piped through `Run.pipe`.
+ * Discriminated on `reason`: `'suspend'` means the run should pause; the
+ * non-`'suspend'` arms describe how it terminated, and an `'error'` outcome
+ * always carries `error`.
+ *
+ * This is a *description of what the Vercel run resulted in*, not a command to
+ * the SDK. The common case maps cleanly onto one transport action — `'suspend'`
+ * → `Run.suspend()`, everything else → `Run.end()` — and to make that case a
+ * one-liner the non-`'suspend'` arms are deliberately assignable to
+ * {@link RunEndParams}, so after a `suspend` guard the whole object passes
+ * straight to `Run.end(outcome)`. That assignability is a convenience for this
+ * adapter, not a constraint on what an outcome can mean: responding to an
+ * outcome may also involve work outside this SDK (persisting a result,
+ * notifying a human, triggering a downstream workflow), and the developer is
+ * free to do that around the terminal call.
+ *
+ * The type is Vercel-specific by design. Outcomes are the layer where agent
+ * SDKs diverge most — both in what they report (the `'suspend'` arm exists only
+ * because Vercel surfaces unexecuted tool calls as a non-terminal finish) and
+ * in what a developer must do in response. A different SDK's outcome type would
+ * have different arms; hence each adapter names its own rather than sharing a
+ * single core `RunOutcome`. The vocabulary it bottoms out in
+ * ({@link RunEndParams}, `Run.suspend`/`Run.end`) is the shared, codec-agnostic
+ * part that does live in core.
+ */
+export type VercelRunOutcome = {
+    /**
+     * The LLM requested tools the SDK did not auto-execute, so the run
+     * pauses rather than ending — call `Run.suspend()`.
+     */
+    reason: 'suspend';
+    /** Never present for a suspend outcome. */
+    error?: never;
+} | {
+    /** A non-error terminal reason; pass the outcome to `Run.end()`. */
+    reason: Exclude<RunEndReason, 'error'>;
+    /** Never present for a non-error outcome. */
+    error?: never;
+} | {
+    /** The run ended in error; pass the outcome to `Run.end()`. */
+    reason: Extract<RunEndReason, 'error'>;
+    /**
+     * The terminal error: the underlying stream / `finishReason` failure
+     * wrapped as an `Ably.ErrorInfo` (code `StreamError`).
+     */
+    error: Ably.ErrorInfo;
+};
+/**
+ * Derive the {@link VercelRunOutcome} for a Vercel `streamText` response that
+ * was piped through `Run.pipe`. Preserves transport-level outcomes
+ * (`'cancelled'`, `'error'`) from the pipe result; when the pipe completed
+ * naturally, awaits Vercel's `finishReason` and returns `'suspend'` for
+ * `'tool-calls'` (the LLM requested tools the SDK did not auto-execute, so the
+ * run should suspend rather than end), or `'complete'` otherwise.
+ *
+ * Surfaces the failure for both error shapes so the caller can forward it to
+ * `Run.end(reason, error)`: a stream that threw (`pipeResult.error`) and a
+ * `finishReason` that rejected with a non-abort error (e.g.
+ * `NoOutputGeneratedError`, network blow-ups). The error is wrapped as an
+ * `Ably.ErrorInfo` (code `StreamError`). A stream that already produced a
+ * codec-level error chunk is unaffected — stamping run-end is the
+ * codec-agnostic baseline that any consumer can read.
  *
  * Tolerates `finishReason` rejection. Vercel AI SDK v6 rejects
  * `streamText().finishReason` with the abort signal's reason when the stream
@@ -23,7 +78,7 @@ import type * as AI from 'ai';
  * of every route handler.
  * @param pipeResult - The result returned by `Run.pipe`.
  * @param finishReason - The `finishReason` promise from a `streamText` result.
- * @returns `'suspend'` when the run should suspend awaiting tool input, or the
- *   {@link RunEndReason} to pass to `Run.end` otherwise.
+ * @returns The {@link VercelRunOutcome}: the terminal `reason` (or `'suspend'`)
+ *   and, when `reason` is `'error'`, the wrapped `error` to pass to `Run.end`.
  */
-export declare const vercelRunOutcome: (pipeResult: StreamResult, finishReason: PromiseLike<AI.FinishReason>) => Promise<RunEndReason | "suspend">;
+export declare const vercelRunOutcome: (pipeResult: StreamResult, finishReason: PromiseLike<AI.FinishReason>) => Promise<VercelRunOutcome>;

package/dist/vercel/tool-part.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Shared tool-part type guard for the Vercel layer.
+ *
+ * The codec normalises every tool part to the `dynamic-tool` shape, but the AI
+ * SDK emits `tool-${name}` parts for statically-declared tools. Both shapes
+ * carry `toolCallId` and `state`. The guard accepts either representation so
+ * the transport's unresolved-tool detection and the React overlay merge can
+ * match tool parts uniformly — and so the cross-representation rule lives in
+ * one place rather than being re-spelled per call site.
+ */
+import type * as AI from 'ai';
+/** A UIMessage tool part in either the `dynamic-tool` or `tool-${name}` representation. */
+export type ToolPart = AI.DynamicToolUIPart | AI.ToolUIPart;
+/**
+ * Whether a UIMessage part is a tool part of either representation. The
+ * `toolCallId`/`state` shape check is defensive against a future AI SDK release
+ * introducing a non-tool variant under the `tool-` prefix (none exists today).
+ * @param part - The UIMessage part to inspect.
+ * @returns True when the part is a tool part.
+ */
+export declare const isToolPart: (part: AI.UIMessage["parts"][number]) => part is ToolPart;

package/dist/vercel/transport/chat-transport.d.ts

@@ -55,8 +55,6 @@ export interface SendMessagesRequestContext {
     /** The codec-message-id of the predecessor in the conversation thread. */
     parent?: string;
 }
-/** Default agent endpoint the transport POSTs invocations to — mirrors Vercel's DefaultChatTransport. */
-export declare const DEFAULT_VERCEL_API = "/api/chat";
 /** Options for customizing the ChatTransport behavior. */
 export interface ChatTransportOptions {
     /**

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

@@ -14,7 +14,7 @@ import { VercelInput, VercelOutput, VercelProjection } from '../codec/index.js';
  * ```
  */
 export type { ChatTransport, ChatTransportOptions, SendMessagesRequestContext } from './chat-transport.js';
-export { createChatTransport, DEFAULT_VERCEL_API } from './chat-transport.js';
+export { createChatTransport } from './chat-transport.js';
 import type * as AI from 'ai';
 /** Core client session options with Vercel AI SDK types pre-applied. */
 type CoreClientOpts = ClientSessionOptions<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>;

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

@@ -23,23 +23,21 @@ import { VercelInput, VercelOutput, VercelProjection } from '../codec/index.js';
  * continuity loss, or an agent-reported mid-run error), so the consumer's
  * reader rejects rather than hanging.
  */
-import * as Ably from 'ably';
 import type * as AI from 'ai';
 type VercelSession = ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>;
-/** A consumer-facing run output stream plus the handles to settle it externally. */
-export interface RunOutputStream {
+/** 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;
-    /** Error the stream now (e.g. on a failed agent-invocation POST). Idempotent. */
-    error: (reason: Ably.ErrorInfo) => 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`/`error` let the caller settle the stream for conditions the Tree
- * doesn't surface (local cancel, POST failure).
+ * `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
@@ -50,7 +48,7 @@ export interface RunOutputStream {
  *   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 settle handles.
+ * @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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ably/ai-transport",
-  "version": "0.2.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",
@@ -70,7 +70,7 @@
     }
   },
   "peerDependencies": {
-    "ably": "^2.21.0",
+    "ably": "^2.23.0",
     "ai": "^6",
     "react": "^18.0.0 || ^19.0.0"
   },

package/src/constants.ts

@@ -164,14 +164,14 @@ export const EVENT_RUN_END = 'ai-run-end';
  * 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
- * codec-level `type` header so the decoder can dispatch.
+ * SDK-controlled codec-level `kind` header so the decoder can dispatch.
  */
 export const EVENT_AI_OUTPUT = 'ai-output';
 
 /**
  * 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 `type`
+ * 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

@@ -19,11 +19,6 @@ interface RealtimeWithOptions extends Ably.Realtime {
 
 const SDK_NAME = 'ai-transport-js';
 
-/** Internal shape a codec may carry to opt into Ably-Agent header registration. */
-interface AdapterTagHolder {
-  readonly adapterTag?: string;
-}
-
 /**
  * Merge `agents` into `client.options.agents` and return the space-separated
  * `params.agent` string for channel ATTACH.
@@ -40,29 +35,58 @@ const injectAgents = (
 ): { params: { agent: string } } => {
   const realtime = client as RealtimeWithOptions;
   realtime.options.agents = { ...realtime.options.agents, ...agents };
-  const agentString = Object.entries(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(' ');
-  return { params: { agent: agentString } };
-};
+
+/**
+ * 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 internal `adapterTag` field (via {@link AdapterTagHolder}), also sets
- * `options.agents[adapterTag] = VERSION`.
+ * 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; cast to {@link AdapterTagHolder} to detect an optional identifier.
+ * @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?: unknown): { params: { agent: string } } => {
-  // CAST: AdapterTagHolder is an internal opt-in shape — not part of the public Codec interface.
-  const adapterTag = (codec as AdapterTagHolder | undefined)?.adapterTag;
-  const agents: Record<string, string> = { [SDK_NAME]: VERSION };
-  if (adapterTag) agents[adapterTag] = VERSION;
-  return injectAgents(client, agents);
-};
+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];
+};

package/src/core/codec/codec-event.ts

@@ -0,0 +1,27 @@
+/**
+ * `toCodecEvents` — tag a decoded message's events with their wire direction.
+ *
+ * A decoded message is already split into inputs and outputs by the decoder
+ * (driven by the Ably message name — the authoritative direction signal). This
+ * helper folds that split into the ordered {@link CodecEvent} stream the reducer
+ * consumes, so the direction is carried explicitly rather than re-inferred from
+ * each event's shape. Inputs are tagged before outputs, preserving the wire
+ * order within a single message (a message is single-direction, so the relative
+ * order of the two groups is immaterial).
+ */
+
+import type { CodecEvent, CodecInputEvent, CodecOutputEvent, DecodedMessage } from './types.js';
+
+/**
+ * Tag a decoded message's events with their wire direction.
+ * @template TInput - The codec's input union.
+ * @template TOutput - The codec's output union.
+ * @param decoded - The decoder's input/output split for one inbound message.
+ * @returns The events as a direction-tagged {@link CodecEvent} list, inputs first.
+ */
+export const toCodecEvents = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent>(
+  decoded: DecodedMessage<TInput, TOutput>,
+): CodecEvent<TInput, TOutput>[] => [
+  ...decoded.inputs.map((event): CodecEvent<TInput, TOutput> => ({ direction: 'input', event })),
+  ...decoded.outputs.map((event): CodecEvent<TInput, TOutput> => ({ direction: 'output', event })),
+];