@ably/ai-transport 0.2.0 → 0.3.0

package/src/vercel/codec/tool-transitions.ts

@@ -10,7 +10,7 @@ import type * as AI from 'ai';
 import { stripUndefined } from '../../utils.js';
 
 // ---------------------------------------------------------------------------
-// Tool output chunk type guard
+// Tool output chunk type
 // ---------------------------------------------------------------------------
 
 /** The set of UIMessageChunk types that represent tool output transitions. */
@@ -19,17 +19,6 @@ export type ToolOutputChunk = Extract<
   { type: 'tool-output-available' | 'tool-output-error' | 'tool-output-denied' | 'tool-approval-request' }
 >;
 
-/**
- * Whether a UIMessageChunk is a tool output transition event.
- * @param chunk - The chunk to test.
- * @returns True if the chunk is a tool output transition type.
- */
-export const isToolOutputChunk = (chunk: AI.UIMessageChunk): chunk is ToolOutputChunk =>
-  chunk.type === 'tool-output-available' ||
-  chunk.type === 'tool-output-error' ||
-  chunk.type === 'tool-output-denied' ||
-  chunk.type === 'tool-approval-request';
-
 // ---------------------------------------------------------------------------
 // Tool base helper
 // ---------------------------------------------------------------------------

package/src/vercel/codec/wire-data.ts

@@ -0,0 +1,64 @@
+/**
+ * Wire-data shapes and runtime guards for the tool payloads whose `data`
+ * envelope is JSON-parsed from the network (a trust boundary). The guards
+ * validate the typed envelope fields; tool-defined `output`/`input` stay
+ * unconstrained. Shared by the output and input descriptor tables.
+ */
+
+/** Wire format for the agent-side `tool-input-error` chunk data payload. */
+export interface ToolInputErrorWireData {
+  errorText?: string;
+  input?: unknown;
+}
+
+/** Wire format for the `tool-output-available` (agent) / `tool-result` (client) data payload. */
+export interface ToolOutputAvailableWireData {
+  output?: unknown;
+}
+
+/** Wire format for the agent-side `tool-output-error` chunk data payload. */
+export interface AgentToolOutputErrorWireData {
+  errorText?: string;
+}
+
+/** Wire format for the client-side `tool-result-error` input data payload. */
+export interface ClientToolResultErrorWireData {
+  message?: string;
+}
+
+// Narrow JSON-parsed wire data to a record. The encoder is expected to publish
+// an object for these payloads, but a malformed publish could carry a primitive
+// or null — callers fall back to field defaults when these guards reject.
+const isRecord = (data: unknown): data is Record<string, unknown> => typeof data === 'object' && data !== null;
+
+// Validate that `data` is a record whose named field is absent or a string. The
+// optional-string check for the typed error fields below lives here once so the
+// guards can't drift. No `as` needed: `isRecord` narrows `data` to a record, so
+// string-key indexing is well-typed.
+const isRecordWithOptionalString = (data: unknown, key: string): boolean =>
+  isRecord(data) && (data[key] === undefined || typeof data[key] === 'string');
+
+// Validates the typed `errorText` field; `input` is tool-defined and
+// intentionally left unconstrained.
+/**
+ * Coerce wire `data` to a string, falling back to `''` for any non-string
+ * payload — the defensive read for descriptors whose data is plain text.
+ * @param data - The inbound wire data.
+ * @returns The string payload, or `''` when the data is not a string.
+ */
+export const asString = (data: unknown): string => (typeof data === 'string' ? data : '');
+
+export const isToolInputErrorWireData = (data: unknown): data is ToolInputErrorWireData =>
+  isRecordWithOptionalString(data, 'errorText');
+
+// The sole field `output` is tool-defined and intentionally unconstrained, so
+// this asserts only that the payload is an object envelope.
+export const isToolOutputAvailableWireData = (data: unknown): data is ToolOutputAvailableWireData => isRecord(data);
+
+// Validates the typed `errorText` field.
+export const isAgentToolOutputErrorWireData = (data: unknown): data is AgentToolOutputErrorWireData =>
+  isRecordWithOptionalString(data, 'errorText');
+
+// Validates the typed `message` field.
+export const isClientToolResultErrorWireData = (data: unknown): data is ClientToolResultErrorWireData =>
+  isRecordWithOptionalString(data, 'message');

package/src/vercel/index.ts

@@ -13,4 +13,5 @@ export type {
 export { createAgentSession, createChatTransport, createClientSession } from './transport/index.js';
 
 // Vercel-shaped helpers
+export type { VercelRunOutcome } from './run-end-reason.js';
 export { vercelRunOutcome } from './run-end-reason.js';

package/src/vercel/react/contexts/chat-transport-context.ts

@@ -23,7 +23,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. */

package/src/vercel/react/use-chat-transport.ts

@@ -16,36 +16,13 @@ import * as Ably from 'ably';
 import type * as AI from 'ai';
 import { useContext } from 'react';
 
-import type { ClientSession, Tree, View } from '../../core/transport/types.js';
+import type { ClientSession } from '../../core/transport/types.js';
 import { ErrorCode } from '../../errors.js';
+import { makeSkippedClientSession } from '../../react/internal/skipped-session.js';
 import type { VercelInput, VercelOutput, VercelProjection } from '../codec/index.js';
 import type { ChatTransport } from '../transport/index.js';
 import { ChatTransportContext } from './contexts/chat-transport-context.js';
 
-const SKIPPED_CLIENT_SESSION: ClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage> = {
-  get tree(): Tree<VercelOutput, VercelProjection> {
-    throw new Ably.ErrorInfo('unable to access tree; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  get view(): View<VercelInput, AI.UIMessage> {
-    throw new Ably.ErrorInfo('unable to access view; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  connect: () => {
-    throw new Ably.ErrorInfo('unable to connect; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  createView: (): View<VercelInput, AI.UIMessage> => {
-    throw new Ably.ErrorInfo('unable to create view; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  cancel: () => {
-    throw new Ably.ErrorInfo('unable to cancel; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  on: () => {
-    throw new Ably.ErrorInfo('unable to subscribe; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-  close: () => {
-    throw new Ably.ErrorInfo('unable to close; hook is skipped', ErrorCode.InvalidArgument, 400);
-  },
-};
-
 const SKIPPED_CHAT_TRANSPORT: ChatTransport = {
   sendMessages: (): never => {
     throw new Ably.ErrorInfo('unable to send messages; hook is skipped', ErrorCode.InvalidArgument, 400);
@@ -131,7 +108,10 @@ export const useChatTransport = ({ channelName, skip }: UseChatTransportOptions
   const { nearest, providers } = useContext(ChatTransportContext);
 
   if (skip) {
-    return { session: SKIPPED_CLIENT_SESSION, chatTransport: SKIPPED_CHAT_TRANSPORT };
+    return {
+      session: makeSkippedClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>(),
+      chatTransport: SKIPPED_CHAT_TRANSPORT,
+    };
   }
 
   if (channelName !== undefined) {
@@ -140,7 +120,7 @@ export const useChatTransport = ({ channelName, skip }: UseChatTransportOptions
       return { session: slot.session, chatTransport: slot.chatTransport, sessionError: slot.sessionError };
     }
     return {
-      session: SKIPPED_CLIENT_SESSION,
+      session: makeSkippedClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>(),
       chatTransport: SKIPPED_CHAT_TRANSPORT,
       sessionError: new Ably.ErrorInfo(
         `unable to use client session; no ClientSessionProvider found for channelName "${channelName}"`,
@@ -164,7 +144,7 @@ export const useChatTransport = ({ channelName, skip }: UseChatTransportOptions
   }
 
   return {
-    session: SKIPPED_CLIENT_SESSION,
+    session: makeSkippedClientSession<VercelInput, VercelOutput, VercelProjection, AI.UIMessage>(),
     chatTransport: SKIPPED_CHAT_TRANSPORT,
     sessionError: new Ably.ErrorInfo(
       'unable to use session; no ClientSessionProvider found in the tree',

package/src/vercel/react/use-message-sync.ts

@@ -16,6 +16,7 @@
 import type * as AI from 'ai';
 import { useEffect, useState } from 'react';
 
+import { isToolPart, type ToolPart } from '../tool-part.js';
 import { useChatTransport } from './use-chat-transport.js';
 
 /** Options for {@link useMessageSync}. */
@@ -38,19 +39,13 @@ export interface UseMessageSyncOptions {
 // Tool-resolution merge
 // ---------------------------------------------------------------------------
 //
-// The Vercel codec normalises every tool part to `dynamic-tool`, but the
-// AI SDK emits `tool-${name}` for statically-declared tools. Both shapes
-// share `toolCallId` + `state`; the merge matches by toolCallId and keeps
-// the tree's `type` on the result so downstream consumers narrowing on
-// `dynamic-tool` keep working.
-
-type ToolPart = AI.DynamicToolUIPart | AI.ToolUIPart;
+// The merge matches tool parts by toolCallId (via the shared {@link isToolPart}
+// guard, which accepts both the codec's `dynamic-tool` shape and the AI SDK's
+// `tool-${name}` shape) and keeps the tree's `type` on the result so downstream
+// consumers narrowing on `dynamic-tool` keep working.
 
 const RESOLVED_TOOL_STATES = new Set(['output-available', 'output-error', 'approval-responded', 'output-denied']);
 
-const isToolPart = (part: AI.UIMessage['parts'][number]): part is ToolPart =>
-  (part.type === 'dynamic-tool' || part.type.startsWith('tool-')) && 'toolCallId' in part && 'state' in part;
-
 const mergeAssistant = (tree: AI.UIMessage, overlay: AI.UIMessage): AI.UIMessage => {
   const overlayByCallId = new Map<string, ToolPart>();
   for (const part of overlay.parts) {

package/src/vercel/run-end-reason.ts

@@ -1,16 +1,76 @@
+import * as Ably from 'ably';
 import type * as AI from 'ai';
 
 import type { RunEndReason, StreamResult } from '../core/transport/types.js';
+import { ErrorCode } from '../errors.js';
 
 /**
- * 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
@@ -25,13 +85,13 @@ import type { RunEndReason, StreamResult } from '../core/transport/types.js';
  * 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 const vercelRunOutcome = async (
   pipeResult: StreamResult,
   finishReason: PromiseLike<AI.FinishReason>,
-): Promise<RunEndReason | 'suspend'> => {
+): Promise<VercelRunOutcome> => {
   if (pipeResult.reason !== 'complete') {
     // Vercel's `result.finishReason` getter creates the underlying Promise
     // eagerly, before the caller hands it to us. When `streamText` is
@@ -46,22 +106,41 @@ export const vercelRunOutcome = async (
     Promise.resolve(finishReason).catch(() => {
       /* intentionally discarded; reason already known from pipeResult */
     });
-    return pipeResult.reason;
+    if (pipeResult.reason === 'error') {
+      return { reason: 'error', error: _toErrorInfo(pipeResult.error) };
+    }
+    return { reason: pipeResult.reason };
   }
   try {
     const finish = await finishReason;
-    return finish === 'tool-calls' ? 'suspend' : 'complete';
+    if (finish === 'tool-calls') return { reason: 'suspend' };
+    return { reason: 'complete' };
   } catch (error) {
     // Abort-shaped rejections are surfaced from streamText when the run was
     // cancelled before any step finished — treat the run as cancelled so the
     // observable lifecycle matches the cancel that triggered it. Everything
     // else is a real error (e.g. NoOutputGeneratedError, network blow-ups);
-    // surface it as such so the developer sees the failure rather than a
-    // silent cancel.
-    return _isAbortLikeError(error) ? 'cancelled' : 'error';
+    // surface it as such — wrapped so the caller can stamp it on run-end — so
+    // the developer sees the failure rather than a silent cancel.
+    if (_isAbortLikeError(error)) return { reason: 'cancelled' };
+    return { reason: 'error', error: _toErrorInfo(error) };
   }
 };
 
+/**
+ * Wrap a caught stream / `finishReason` failure as an `Ably.ErrorInfo` so it
+ * can be passed to `Run.end(reason, error)`. An error that is already an
+ * `Ably.ErrorInfo` is returned unchanged; anything else is wrapped with code
+ * `StreamError`, mirroring how `Run.pipe` wraps stream errors for `onError`.
+ * @param error - The caught error (or `undefined` when the stream reported none).
+ * @returns The error as an `Ably.ErrorInfo`.
+ */
+const _toErrorInfo = (error: unknown): Ably.ErrorInfo => {
+  if (error instanceof Ably.ErrorInfo) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  return new Ably.ErrorInfo(`unable to complete run; ${message}`, ErrorCode.StreamError, 500);
+};
+
 /**
  * Heuristic for "this error came from an AbortSignal aborting".
  * Covers `DOMException` aborts (browser / Node 20+ `streamText`),

package/src/vercel/tool-part.ts

@@ -0,0 +1,25 @@
+/**
+ * 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 const isToolPart = (part: AI.UIMessage['parts'][number]): part is ToolPart =>
+  (part.type === 'dynamic-tool' || part.type.startsWith('tool-')) && 'toolCallId' in part && 'state' in part;

package/src/vercel/transport/chat-transport.ts

@@ -31,13 +31,15 @@
 import * as Ably from 'ably';
 import type * as AI from 'ai';
 
-import type { CodecMessage } from '../../core/codec/types.js';
+import type { CodecMessage } from '../../core/codec/index.js';
 import type { ActiveRun, ClientSession, SendOptions } from '../../core/transport/types.js';
 import { ErrorCode } from '../../errors.js';
 import { EventEmitter } from '../../event-emitter.js';
 import { LogLevel, makeLogger } from '../../logger.js';
+import { errorCause, errorMessage } from '../../utils.js';
 import type { VercelInput, VercelOutput, VercelProjection } from '../codec/index.js';
 import { UIMessageCodec } from '../codec/index.js';
+import { isToolPart, type ToolPart } from '../tool-part.js';
 import { createRunOutputStream } from './run-output-stream.js';
 
 // ---------------------------------------------------------------------------
@@ -71,7 +73,7 @@ export interface SendMessagesRequestContext {
 }
 
 /** Default agent endpoint the transport POSTs invocations to — mirrors Vercel's DefaultChatTransport. */
-export const DEFAULT_VERCEL_API = '/api/chat';
+const DEFAULT_VERCEL_API = '/api/chat';
 
 /** Options for customizing the ChatTransport behavior. */
 export interface ChatTransportOptions {
@@ -226,18 +228,6 @@ const wrapStreamWithDone = <T>(
 // Unresolved tool call detection
 // ---------------------------------------------------------------------------
 
-/**
- * Whether a UIMessage part is a tool part — either the codec-normalised
- * `dynamic-tool` shape or the AI SDK's statically-declared `tool-${name}`
- * shape. Both carry `toolCallId` and `state`; the shape check at the end
- * 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 of either representation.
- */
-const _isToolPart = (part: AI.UIMessage['parts'][number]): part is AI.DynamicToolUIPart | AI.ToolUIPart =>
-  (part.type === 'dynamic-tool' || part.type.startsWith('tool-')) && 'toolCallId' in part && 'state' in part;
-
 /**
  * Whether an assistant message has a `dynamic-tool` part that can't resolve
  * without further user action. Matches:
@@ -254,7 +244,7 @@ const hasUnresolvedToolCall = (msg: AI.UIMessage): boolean =>
   msg.role === 'assistant' &&
   msg.parts.some(
     (p) =>
-      _isToolPart(p) &&
+      isToolPart(p) &&
       (p.state === 'input-streaming' || p.state === 'input-available' || p.state === 'approval-requested'),
   );
 
@@ -280,7 +270,7 @@ const UNRESOLVED_TOOL_STATES = new Set(['input-streaming', 'input-available', 'a
  *
  * The resulting inputs are passed alongside the continuation `view.send`
  * so the channel publish and the continuation POST land as ONE atomic
- * operation — the agent's `loadProjection()` history fetch is guaranteed
+ * operation — the agent's `loadConversation()` history walk is guaranteed
  * to see them because the channel publish happens before the POST inside
  * `_internalSend`.
  *
@@ -314,15 +304,14 @@ const deriveContinuationInputs = (
     const { codecMessageId, message: treeMessage } = treeEntry;
 
     for (const overlayPart of overlay.parts) {
-      if (!_isToolPart(overlayPart)) continue;
+      if (!isToolPart(overlayPart)) continue;
       // The codec normalises every tool part to `dynamic-tool`, but the
       // AI SDK's useChat overlay emits `tool-${name}` parts for statically
       // declared tools. Match by toolCallId rather than the type prefix
       // so the cross-representation comparison works regardless of which
       // side the tool was declared on.
       const treePart = treeMessage.parts.find(
-        (p: AI.UIMessage['parts'][number]): p is AI.DynamicToolUIPart | AI.ToolUIPart =>
-          _isToolPart(p) && p.toolCallId === overlayPart.toolCallId,
+        (p: AI.UIMessage['parts'][number]): p is ToolPart => isToolPart(p) && p.toolCallId === overlayPart.toolCallId,
       );
 
       // Approval response: useChat's `addToolApprovalResponse` flipped the
@@ -678,13 +667,12 @@ export const createChatTransport = (
         }
       })
       .catch((error: unknown) => {
-        const cause = error instanceof Ably.ErrorInfo ? error : undefined;
         fail(
           new Ably.ErrorInfo(
-            `unable to send; HTTP POST to ${api} failed: ${error instanceof Error ? error.message : String(error)}`,
+            `unable to send; HTTP POST to ${api} failed: ${errorMessage(error)}`,
             ErrorCode.SessionSendFailed,
             500,
-            cause,
+            errorCause(error),
           ),
         );
       });

package/src/vercel/transport/index.ts

@@ -14,7 +14,7 @@
 
 // Chat transport adapter
 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';
 

package/src/vercel/transport/run-output-stream.ts

@@ -41,21 +41,20 @@ type VercelSession = ClientSession<VercelInput, VercelOutput, VercelProjection,
 const isTerminalChunk = (output: VercelOutput): boolean =>
   output.type === 'finish' || output.type === 'error' || output.type === 'abort';
 
-/** 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
@@ -66,7 +65,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 const createRunOutputStream = (
   session: VercelSession,
@@ -166,5 +165,5 @@ export const createRunOutputStream = (
     }),
   );
 
-  return { stream, close, error };
+  return { stream, close };
 };

package/src/version.ts

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

package/dist/core/transport/branch-chain.d.ts

@@ -1,43 +0,0 @@
-/**
- * buildBranchChain — order a single conversation branch by walking
- * codec-message-id parent links upward from an anchor node to the root.
- *
- * This is the shared ordering spine of the agent's conversation
- * reconstruction and of history decode: both need the same root→anchor
- * sequence of nodes before folding each node's projection. Keeping the walk
- * here — pure, with no codec, no I/O, no logger — lets it be proven in
- * isolation and reused by both engines without drift.
- *
- * Branch selection is implicit: a node reaches only its own ancestors via
- * `parentCodecMessageId`, so sibling branches (edits / regenerates that the
- * anchor did not descend from) are never visited. There is no separate
- * fork/regenerate filtering step — the un-taken sibling is simply unreachable.
- */
-/**
- * The single field {@link buildBranchChain} reads from a node. Richer node-meta
- * shapes (carrying run-id, fork-of, regenerates, …) satisfy this structurally,
- * so callers can pass their full index map directly.
- */
-export interface BranchChainNode {
-    /**
-     * Codec-message-id of this node's structural parent — the node it hangs off
-     * — or `undefined` for a root node. This is the only edge the walk follows.
-     */
-    parentCodecMessageId: string | undefined;
-}
-/**
- * Walk `parentCodecMessageId` links upward from `anchorCodecMessageId` and
- * return the branch it sits on, ordered root-first (oldest) to anchor (newest,
- * last). The anchor is always the final element.
- *
- * The walk stops at the root (a node with no parent), at a dangling parent
- * (a parent id absent from `nodeMeta` is still included as the chain head,
- * then the walk ends), or on revisiting a node (a cycle in malformed data is
- * broken best-effort rather than looping forever).
- * @param nodeMeta - Lookup from codec-message-id to its node meta. Need not
- *   contain the anchor or every ancestor; missing entries simply end the walk.
- * @param anchorCodecMessageId - The codec-message-id to start the walk from
- *   (the newest node on the branch; included in the result).
- * @returns The branch's codec-message-ids ordered root-first to anchor-last.
- */
-export declare const buildBranchChain: (nodeMeta: ReadonlyMap<string, BranchChainNode>, anchorCodecMessageId: string) => string[];