@ably/ai-transport 0.1.0 → 0.2.0

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

@@ -0,0 +1,56 @@
+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 * 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 {
+    /** 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).
+ *
+ * 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 settle handles.
+ */
+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.2.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ably/ai-transport",
-  "version": "0.1.0",
+  "version": "0.2.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,7 +60,14 @@
   },
   "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",
@@ -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
+ * codec-level `type` 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 `type`
+ * header so the decoder can dispatch.
+ */
+export const EVENT_AI_INPUT = 'ai-input';

package/src/core/agent.ts

@@ -0,0 +1,68 @@
+/**
+ * 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';
+
+/** 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.
+ * @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 };
+  const agentString = Object.entries(agents)
+    .map(([name, version]) => `${name}/${version}`)
+    .join(' ');
+  return { params: { agent: agentString } };
+};
+
+/**
+ * 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`.
+ * 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.
+ * @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);
+};