@ably/ai-transport 0.1.0 → 0.3.0

package/src/react/use-view.ts

@@ -1,32 +1,51 @@
 /**
  * useView — reactive paginated view of the conversation.
  *
- * Subscribes to view updates and exposes the visible nodes, branch navigation,
- * write operations, pagination state, and a `loadOlder` callback. Pass `transport`
- * to use a transport's default view, or `view` to subscribe to a specific
- * {@link View} directly. When both are omitted, defaults to the nearest
- * {@link TransportProvider}'s transport via context.
+ * Subscribes to view updates and exposes the visible messages, msg-anchored
+ * branch navigation, write operations, pagination state, and a `loadOlder`
+ * callback. Pass `session` to use a session's default view, or `view` to
+ * subscribe to a specific {@link View} directly. When both are omitted,
+ * defaults to the nearest {@link ClientSessionProvider}'s session via context.
  */
 
 import * as Ably from 'ably';
-import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 
-import type { ActiveTurn, ClientTransport, MessageNode, SendOptions, View } from '../core/transport/types.js';
+import type { CodecInputEvent, CodecMessage, CodecOutputEvent } from '../core/codec/types.js';
+import type { ActiveRun, BranchSelection, RunInfo, SendOptions, View } from '../core/transport/types.js';
 import { ErrorCode } from '../errors.js';
-import { NearestTransportContext } from './contexts/transport-context.js';
+import type { BaseSessionOption } from './internal/use-resolved-session.js';
+import { useResolvedSession } from './internal/use-resolved-session.js';
 
-/** Options for configuring the view's initial load behavior. */
-export interface UseViewOptions {
-  /** Maximum number of older messages to load per page. Defaults to 100. */
+/** Options for {@link useView}. */
+export interface UseViewOptions<
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+> extends BaseSessionOption<TInput, TOutput, TProjection, TMessage> {
+  /** A specific {@link View} to subscribe to directly. Takes priority over `session`. */
+  view?: View<TInput, TMessage> | null;
+  /** Number of older codecMessages to reveal per page (exactly `limit`, fewer only at the end of history). When provided, auto-loads the first page on mount. */
   limit?: number;
+  /** When `true`, skip all subscriptions and return an empty handle immediately. */
+  skip?: boolean;
 }
 
 /** Handle for the paginated, branch-aware conversation view. */
-export interface ViewHandle<TEvent, TMessage> {
-  /** The visible domain messages along the selected branch. */
-  messages: TMessage[];
-  /** Visible conversation nodes along the selected branch. */
-  nodes: MessageNode<TMessage>[];
+export interface ViewHandle<TInput extends CodecInputEvent, TMessage> {
+  /**
+   * The visible messages along the selected branch, concatenated across all
+   * visible Runs, each paired with its codec-message-id (see
+   * {@link CodecMessage}). Read the domain object from each entry's
+   * `message` field.
+   *
+   * Correlate a rendered message back to the View — `runOf`,
+   * `branchSelection`, `selectSibling`, `regenerate`, or `edit` — via its
+   * `codecMessageId`, which the SDK assigns and tracks independently of any
+   * identity the domain `message` may carry. See {@link View.getMessages}.
+   */
+  messages: CodecMessage<TMessage>[];
   /** Whether there are older messages that can be revealed via `loadOlder`. */
   hasOlder: boolean;
   /** Whether a page load is currently in progress. */
@@ -39,65 +58,90 @@ export interface ViewHandle<TEvent, TMessage> {
   loadError: Ably.ErrorInfo | undefined;
   /**
    * Load older messages into the view. No-op if already loading.
-   * On failure, `error` is set; on success, `error` is cleared.
+   * On failure, `loadError` is set; on success, `loadError` is cleared.
    */
   loadOlder: () => Promise<void>;
-  /** Select a sibling at a fork point by index. Triggers a view update with the new branch. */
-  select: (msgId: string, index: number) => void;
-  /** Index of the currently selected sibling at a fork point. */
-  getSelectedIndex: (msgId: string) => number;
-  /** Get all sibling messages at a fork point, ordered chronologically by serial. */
-  getSiblings: (msgId: string) => TMessage[];
-  /** Whether a message has sibling alternatives (i.e., show navigation arrows). */
-  hasSiblings: (msgId: string) => boolean;
-  /** Get a node by msgId, or undefined if not found. */
-  getNode: (msgId: string) => MessageNode<TMessage> | undefined;
-  /** Send one or more messages in the context of this view's selected branch. */
-  send: (messages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
-  /** Regenerate an assistant message, using this view's branch for history. */
-  regenerate: (messageId: string, options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
-  /** Edit a user message, forking from this view's branch. */
-  edit: (messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
-  /** Amend an existing message and start a continuation turn (e.g. tool results). */
-  update: (msgId: string, events: TEvent[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
+  /**
+   * Look up the {@link RunInfo} for the Run that owns `codecMessageId`.
+   * Returns `undefined` when the codec-message-id hasn't been observed.
+   * See {@link View.runOf}.
+   */
+  runOf: (codecMessageId: string) => RunInfo | undefined;
+  /**
+   * Direct lookup by runId. Returns `undefined` when the Run hasn't been
+   * observed. See {@link View.run}.
+   */
+  run: (runId: string) => RunInfo | undefined;
+  /**
+   * Snapshot of the visible Runs along the selected branch, in
+   * chronological order. Returns `[]` when the view isn't resolved.
+   * See {@link View.runs}.
+   */
+  runs: () => RunInfo[];
+  /**
+   * Resolve the {@link BranchSelection} bundle anchored at
+   * `codecMessageId`. Always returns a safe object — see
+   * {@link BranchSelection}. See {@link View.branchSelection}.
+   */
+  branchSelection: (codecMessageId: string) => BranchSelection<TMessage>;
+  /**
+   * Select a sibling at the branch point anchored at `codecMessageId`.
+   * `index` is clamped to `[0, siblings.length - 1]`. Silent no-op when
+   * `codecMessageId` isn't a branch anchor. See {@link View.selectSibling}.
+   */
+  selectSibling: (codecMessageId: string, index: number) => void;
+  /**
+   * Send one or more TInputs on the channel and fire a POST. See {@link View.send}.
+   * @throws Ably.ErrorInfo with code {@link ErrorCode.InvalidArgument} when no view is resolved (before the session is available, or when `skip` is `true`).
+   */
+  send: (events: TInput | TInput[], options?: SendOptions) => Promise<ActiveRun>;
+  /**
+   * Regenerate an assistant message, using this view's branch for history.
+   * @throws Ably.ErrorInfo with code {@link ErrorCode.InvalidArgument} when no view is resolved (before the session is available, or when `skip` is `true`).
+   */
+  regenerate: (messageId: string, options?: SendOptions) => Promise<ActiveRun>;
+  /**
+   * Edit a user message, forking from this view's branch.
+   * Rejects with an `Ably.ErrorInfo` (code {@link ErrorCode.InvalidArgument}) if no view is resolved — e.g. before the session is available, or when `skip` is `true`.
+   */
+  edit: (messageId: string, inputs: TInput | TInput[], options?: SendOptions) => Promise<ActiveRun>;
 }
 
 /**
- * Subscribe to a view and return the visible node list with pagination, navigation, and write operations.
+ * Fallback returned by `branchSelection` when the view isn't resolved.
+ * Same shape the view returns for an unknown codec-message-id, so callers
+ * can destructure uniformly.
+ */
+const EMPTY_BRANCH_SELECTION: BranchSelection<never> = {
+  hasSiblings: false,
+  siblings: [],
+  index: 0,
+  selected: undefined,
+};
+
+/**
+ * Subscribe to a view and return the visible messages with pagination, navigation, and write operations.
  *
- * `view` takes priority over `transport`. When neither is provided, the nearest
- * {@link TransportProvider}'s transport is used. When `limit` is provided, auto-loads
+ * `view` takes priority over `session`. When neither is provided, the nearest
+ * {@link ClientSessionProvider}'s session is used. When `limit` is provided, auto-loads
  * the first page on mount (SWR-style).
  * @param props - Options for selecting the view source and configuring auto-load.
- * @param props.transport - Client transport whose default view to subscribe to; defaults to the nearest provider.
- * @param props.view - A specific {@link View} to subscribe to directly. Takes priority over `transport`.
- * @param props.limit - Max older messages per page; when provided, auto-loads on mount.
+ * @param props.session - Client session whose default view to subscribe to; defaults to the nearest provider.
+ * @param props.view - A specific {@link View} to subscribe to directly. Takes priority over `session`.
+ * @param props.limit - Number of older codecMessages to reveal per page (exactly `limit`, fewer only at end of history); when provided, auto-loads the first page on mount.
  * @param props.skip - When `true`, skip all subscriptions and return an empty handle.
- * @returns A {@link ViewHandle} with nodes, pagination state, navigation, write operations, and loadOlder.
+ * @returns A {@link ViewHandle} with messages, pagination state, navigation, write operations, and loadOlder.
  */
-export const useView = <TEvent, TMessage>({
-  transport,
+export const useView = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({
+  session,
   view,
   limit,
   skip,
-}: {
-  /** Client transport whose default view to subscribe to; defaults to the nearest provider when omitted. */
-  transport?: ClientTransport<TEvent, TMessage> | null;
-  /** A specific {@link View} to subscribe to directly. Takes priority over `transport`. */
-  view?: View<TEvent, TMessage> | null;
-  /** When provided, auto-loads the first page on mount. Omit for manual loading. */
-  limit?: number;
-  /** When `true`, skip all subscriptions and return an empty handle immediately. */
-  skip?: boolean;
-} = {}): ViewHandle<TEvent, TMessage> => {
-  const nearestSlot = useContext(NearestTransportContext);
-  // CAST: NearestTransportContext stores transport with erased generics; types fixed at call site.
-  const resolvedTransport = skip
-    ? undefined
-    : (transport ?? (nearestSlot?.transport as unknown as ClientTransport<TEvent, TMessage> | undefined));
-  const resolvedView = skip ? undefined : (view ?? resolvedTransport?.view);
-
-  const [nodes, setNodes] = useState<MessageNode<TMessage>[]>(() => resolvedView?.flattenNodes() ?? []);
+}: UseViewOptions<TInput, TOutput, TProjection, TMessage> = {}): ViewHandle<TInput, TMessage> => {
+  const resolvedSession = useResolvedSession({ session, skip });
+  const resolvedView = skip ? undefined : (view ?? resolvedSession?.view);
+
+  const [messages, setMessages] = useState<CodecMessage<TMessage>[]>(() => resolvedView?.getMessages() ?? []);
   const [hasOlder, setHasOlder] = useState(() => resolvedView?.hasOlder() ?? false);
   const [loading, setLoading] = useState(false);
   const [loadError, setLoadError] = useState<Ably.ErrorInfo | undefined>();
@@ -112,7 +156,7 @@ export const useView = <TEvent, TMessage>({
   // Subscribe to view updates
   useEffect(() => {
     if (!resolvedView) {
-      setNodes([]);
+      setMessages([]);
       setHasOlder(false);
       setLoadError(undefined);
       return;
@@ -122,12 +166,12 @@ export const useView = <TEvent, TMessage>({
     autoLoadedRef.current = false;
 
     // Sync initial state
-    setNodes(resolvedView.flattenNodes());
+    setMessages(resolvedView.getMessages());
     setHasOlder(resolvedView.hasOlder());
     setLoadError(undefined);
 
     const unsub = resolvedView.on('update', () => {
-      setNodes(resolvedView.flattenNodes());
+      setMessages(resolvedView.getMessages());
       setHasOlder(resolvedView.hasOlder());
     });
     return unsub;
@@ -158,30 +202,39 @@ export const useView = <TEvent, TMessage>({
     void loadOlder();
   }, [autoLoad, resolvedView, loadOlder]);
 
-  const messages = useMemo(() => nodes.map((n) => n.message), [nodes]);
-
-  // Branch navigation callbacks
-  const select = useCallback(
-    (msgId: string, index: number) => {
-      resolvedView?.select(msgId, index);
-    },
+  // Run lookups
+  const runOf = useCallback(
+    (codecMessageId: string): RunInfo | undefined => resolvedView?.runOf(codecMessageId),
     [resolvedView],
   );
 
-  const getSelectedIndex = useCallback((msgId: string) => resolvedView?.getSelectedIndex(msgId) ?? 0, [resolvedView]);
+  const run = useCallback((runId: string): RunInfo | undefined => resolvedView?.run(runId), [resolvedView]);
 
-  const getSiblings = useCallback((msgId: string) => resolvedView?.getSiblings(msgId) ?? [], [resolvedView]);
+  const runs = useCallback((): RunInfo[] => resolvedView?.runs() ?? [], [resolvedView]);
 
-  const hasSiblings = useCallback((msgId: string) => resolvedView?.hasSiblings(msgId) ?? false, [resolvedView]);
+  // Branch navigation
+  const branchSelection = useCallback(
+    (codecMessageId: string): BranchSelection<TMessage> =>
+      // CAST: `EMPTY_BRANCH_SELECTION` is typed `BranchSelection<never>`; `never` is
+      // assignable to any `TMessage`, so the empty bundle is a valid fallback for
+      // the not-yet-resolved view case.
+      resolvedView?.branchSelection(codecMessageId) ?? (EMPTY_BRANCH_SELECTION as BranchSelection<TMessage>),
+    [resolvedView],
+  );
 
-  const getNode = useCallback((msgId: string) => resolvedView?.getNode(msgId), [resolvedView]);
+  const selectSibling = useCallback(
+    (codecMessageId: string, index: number) => {
+      resolvedView?.selectSibling(codecMessageId, index);
+    },
+    [resolvedView],
+  );
 
   // Write operation callbacks
   const send = useCallback(
-    async (msgs: TMessage | TMessage[], opts?: SendOptions) => {
+    async (events: TInput | TInput[], opts?: SendOptions) => {
       if (!resolvedView)
         throw new Ably.ErrorInfo('unable to send; view is not available', ErrorCode.InvalidArgument, 400);
-      return resolvedView.send(msgs, opts);
+      return resolvedView.send(events, opts);
     },
     [resolvedView],
   );
@@ -196,38 +249,27 @@ export const useView = <TEvent, TMessage>({
   );
 
   const edit = useCallback(
-    async (messageId: string, newMessages: TMessage | TMessage[], opts?: SendOptions) => {
+    async (messageId: string, inputs: TInput | TInput[], opts?: SendOptions) => {
       if (!resolvedView)
         throw new Ably.ErrorInfo('unable to edit; view is not available', ErrorCode.InvalidArgument, 400);
-      return resolvedView.edit(messageId, newMessages, opts);
-    },
-    [resolvedView],
-  );
-
-  const update = useCallback(
-    async (msgId: string, events: TEvent[], opts?: SendOptions) => {
-      if (!resolvedView)
-        throw new Ably.ErrorInfo('unable to update; view is not available', ErrorCode.InvalidArgument, 400);
-      return resolvedView.update(msgId, events, opts);
+      return resolvedView.edit(messageId, inputs, opts);
     },
     [resolvedView],
   );
 
   return {
     messages,
-    nodes,
     hasOlder,
     loading,
     loadError,
     loadOlder,
-    select,
-    getSelectedIndex,
-    getSiblings,
-    hasSiblings,
-    getNode,
+    runOf,
+    run,
+    runs,
+    branchSelection,
+    selectSibling,
     send,
     regenerate,
     edit,
-    update,
   };
 };

package/src/utils.ts

@@ -6,26 +6,68 @@
  * the other.
  */
 
-import type * as Ably from 'ably';
+import * as Ably from 'ably';
 
-import { DOMAIN_HEADER_PREFIX } from './constants.js';
+/**
+ * Extract a human-readable message from an unknown thrown value.
+ * @param error - The thrown value.
+ * @returns The error's `message` when it is an `Error`, otherwise its string form.
+ */
+export const errorMessage = (error: unknown): string => (error instanceof Error ? error.message : String(error));
 
 /**
- * Extract extras.headers from an Ably InboundMessage.
- * @param message - The Ably message to extract headers from.
- * @returns The headers record, or an empty object if absent.
+ * Narrow an unknown thrown value to an `Ably.ErrorInfo` for use as a wrapping
+ * `cause`, returning `undefined` when it is not one. Pass the result as the
+ * fourth argument to the `Ably.ErrorInfo` constructor to preserve the error
+ * chain without asserting a type the value may not have.
+ * @param error - The thrown value.
+ * @returns The value when it is an `Ably.ErrorInfo`, otherwise `undefined`.
+ */
+export const errorCause = (error: unknown): Ably.ErrorInfo | undefined =>
+  error instanceof Ably.ErrorInfo ? error : undefined;
+
+/**
+ * Read one tier of the SDK's `extras.ai` namespace from an Ably message.
+ * `extras.ai` is the SDK's reserved corner of the message envelope, split into
+ * a `transport` tier (generic transport headers) and a `codec` tier (codec
+ * headers). The application's own `extras.headers` is deliberately left
+ * untouched.
+ * @param message - The Ably message to read from.
+ * @param tier - Which `extras.ai` sub-namespace to read.
+ * @returns The tier's headers record, or an empty object if absent.
  */
-export const getHeaders = (message: Ably.InboundMessage): Record<string, string> => {
+const getAiTier = (message: Ably.InboundMessage, tier: 'transport' | 'codec'): Record<string, string> => {
   // CAST: Ably SDK types `extras` as `any`; runtime checks below guard access.
   const extras = message.extras as unknown;
   if (!extras || typeof extras !== 'object') return {};
-  const headers = (extras as { headers?: unknown }).headers;
-  if (!headers || typeof headers !== 'object') return {};
-  // CAST: Ably wire protocol guarantees headers is Record<string, string>
+  const ai = (extras as { ai?: unknown }).ai;
+  if (!ai || typeof ai !== 'object') return {};
+  const sub = (ai as Record<string, unknown>)[tier];
+  if (!sub || typeof sub !== 'object') return {};
+  // CAST: Ably wire protocol guarantees the tier is Record<string, string>
   // when present, verified by the runtime guards above.
-  return headers as Record<string, string>;
+  return sub as Record<string, string>;
 };
 
+/**
+ * Extract the transport-tier headers (`extras.ai.transport`) from an Ably
+ * InboundMessage. These are the generic transport headers (run/stream/identity/
+ * branching), set and read by the transport layer.
+ * @param message - The Ably message to extract headers from.
+ * @returns The transport headers record, or an empty object if absent.
+ */
+export const getTransportHeaders = (message: Ably.InboundMessage): Record<string, string> =>
+  getAiTier(message, 'transport');
+
+/**
+ * Extract the codec-tier headers (`extras.ai.codec`) from an Ably
+ * InboundMessage. These are the codec's own headers, with no prefix — the
+ * tier isolates them from transport headers.
+ * @param message - The Ably message to extract headers from.
+ * @returns The codec headers record, or an empty object if absent.
+ */
+export const getCodecHeaders = (message: Ably.InboundMessage): Record<string, string> => getAiTier(message, 'codec');
+
 /**
  * Parse a JSON string, returning undefined on failure.
  * @param value - The JSON string to parse.
@@ -41,32 +83,19 @@ export const parseJson = (value: string | undefined): unknown => {
 };
 
 /**
- * Set a header value if defined, skipping undefined and null. Strings are set directly,
- * booleans and numbers are stringified, objects are JSON-serialized.
- * @param headers - The headers object to mutate.
- * @param key - The header key.
- * @param value - The value to set.
+ * Parse a string as JSON, falling back to the raw string when it isn't valid
+ * JSON. An empty string yields `undefined`. Used for accumulated stream text
+ * whose payload may be JSON or a plain string.
+ * @param value - The string to parse.
+ * @returns The parsed value, the raw string on parse failure, or undefined if empty.
  */
-export const setIfPresent = (headers: Record<string, string>, key: string, value: unknown): void => {
-  if (value === undefined || value === null) return;
-  if (typeof value === 'string') {
-    headers[key] = value;
-  } else if (typeof value === 'boolean' || typeof value === 'number') {
-    headers[key] = String(value);
-  } else if (typeof value === 'object') {
-    headers[key] = JSON.stringify(value);
-  }
-};
-
-/**
- * Set multiple headers at once, skipping entries whose values are undefined or null.
- * Each value is converted using the same rules as {@link setIfPresent}.
- * @param headers - The headers object to mutate.
- * @param entries - Key-value pairs to set.
- */
-export const setHeadersIfPresent = (headers: Record<string, string>, entries: Record<string, unknown>): void => {
-  for (const [key, value] of Object.entries(entries)) {
-    setIfPresent(headers, key, value);
+export const parseJsonOrString = (value: string): unknown => {
+  if (!value) return undefined;
+  try {
+    // CAST: JSON.parse returns any; unknown is the safe trust-boundary type.
+    return JSON.parse(value) as unknown;
+  } catch {
+    return value;
   }
 };
 
@@ -95,30 +124,28 @@ export const parseBool = (value: string | undefined): boolean | undefined => {
   return value === 'true';
 };
 
-/**
- * Build a domain headers record from key-value pairs. Each key is automatically
- * prefixed with {@link DOMAIN_HEADER_PREFIX}. Values that are undefined or null
- * are skipped; strings are set directly; booleans, numbers, and objects are
- * converted using the same rules as {@link setIfPresent}.
- * @param entries - Unprefixed key-value pairs (e.g. `{ toolCallId: 'tc-1' }` becomes `{ 'x-domain-toolCallId': 'tc-1' }`).
- * @returns A new headers record with prefixed keys.
- */
-export const domainHeaders = (entries: Record<string, unknown>): Record<string, string> => {
-  const h: Record<string, string> = {};
-  for (const [key, value] of Object.entries(entries)) {
-    setIfPresent(h, DOMAIN_HEADER_PREFIX + key, value);
-  }
-  return h;
-};
+/** A record carrying an optional Ably `serial`, orderable by {@link compareBySerial}. */
+interface HasSerial {
+  /** Ably serial, or undefined if the server has not yet assigned one. */
+  readonly serial?: string;
+}
 
 /**
- * Read a domain header value from a headers record.
- * @param headers - The headers record to read from.
- * @param key - The unprefixed domain key (e.g. `'toolCallId'` reads `'x-domain-toolCallId'`).
- * @returns The header value, or undefined if absent.
+ * Comparator that orders records by their Ably `serial` ascending
+ * (chronological). Serials are lexicographically comparable; records whose
+ * serial is undefined sort last. Pass directly to `Array.prototype.sort`.
+ * @param a - First record to compare.
+ * @param b - Second record to compare.
+ * @returns Negative if `a` precedes `b`, positive if `a` follows `b`, 0 if equal.
  */
-export const getDomainHeader = (headers: Record<string, string>, key: string): string | undefined =>
-  headers[DOMAIN_HEADER_PREFIX + key];
+export const compareBySerial = (a: HasSerial, b: HasSerial): number => {
+  if (a.serial === undefined && b.serial === undefined) return 0;
+  if (a.serial === undefined) return 1;
+  if (b.serial === undefined) return -1;
+  if (a.serial < b.serial) return -1;
+  if (a.serial > b.serial) return 1;
+  return 0;
+};
 
 /**
  * Mapped type that converts properties whose type includes `undefined`
@@ -153,78 +180,3 @@ export const stripUndefined = <T extends Record<string, unknown>>(obj: T): Strip
   // required keys are always present, optional keys are absent when undefined.
   return result as Stripped<T>;
 };
-
-// ---------------------------------------------------------------------------
-// DomainHeaderReader — typed accessors for domain headers
-// ---------------------------------------------------------------------------
-
-/**
- * Typed accessor wrapper around a headers record for reading domain headers.
- * Reduces repetitive `getDomainHeader` + `parseBool` / `parseJson` chains.
- */
-export interface DomainHeaderReader {
-  /** Read a domain header as a string, or undefined if absent. */
-  str(key: string): string | undefined;
-  /** Read a domain header as a string, falling back to a default if absent. */
-  strOr(key: string, fallback: string): string;
-  /** Read a domain header as a boolean ("true"/"false"), or undefined if absent. */
-  bool(key: string): boolean | undefined;
-  /** Read a domain header as parsed JSON, or undefined if absent or invalid. */
-  json(key: string): unknown;
-}
-
-/**
- * Create a {@link DomainHeaderReader} over a headers record.
- * @param headers - The raw headers record to read domain headers from.
- * @returns A typed accessor for domain header values.
- */
-export const headerReader = (headers: Record<string, string>): DomainHeaderReader => ({
-  str: (key: string) => getDomainHeader(headers, key),
-  strOr: (key: string, fallback: string) => getDomainHeader(headers, key) ?? fallback,
-  bool: (key: string) => parseBool(getDomainHeader(headers, key)),
-  json: (key: string) => parseJson(getDomainHeader(headers, key)),
-});
-
-// ---------------------------------------------------------------------------
-// DomainHeaderWriter — typed builder for domain headers
-// ---------------------------------------------------------------------------
-
-/**
- * Fluent builder for constructing domain header records with typed setters.
- * Mirrors {@link DomainHeaderReader} with the same method names for symmetry.
- * Undefined values are silently skipped on all setters.
- */
-export interface DomainHeaderWriter {
-  /** Set a string domain header. Skips if value is undefined. */
-  str(key: string, value: string | undefined): DomainHeaderWriter;
-  /** Set a boolean domain header (serialized as "true"/"false"). Skips if value is undefined. */
-  bool(key: string, value: boolean | undefined): DomainHeaderWriter;
-  /** Set a JSON-serialized domain header. Skips if value is undefined or null. */
-  json(key: string, value: unknown): DomainHeaderWriter;
-  /** Return the accumulated headers record. */
-  build(): Record<string, string>;
-}
-
-/**
- * Create a {@link DomainHeaderWriter} for building a domain headers record.
- * @returns A fluent builder that prefixes each key with the domain header prefix.
- */
-export const headerWriter = (): DomainHeaderWriter => {
-  const h: Record<string, string> = {};
-  const writer: DomainHeaderWriter = {
-    str: (key: string, value: string | undefined) => {
-      if (value !== undefined) h[DOMAIN_HEADER_PREFIX + key] = value;
-      return writer;
-    },
-    bool: (key: string, value: boolean | undefined) => {
-      if (value !== undefined) h[DOMAIN_HEADER_PREFIX + key] = String(value);
-      return writer;
-    },
-    json: (key: string, value: unknown) => {
-      if (value !== undefined && value !== null) h[DOMAIN_HEADER_PREFIX + key] = JSON.stringify(value);
-      return writer;
-    },
-    build: () => h,
-  };
-  return writer;
-};

package/src/vercel/codec/decode-lifecycle.ts

@@ -0,0 +1,70 @@
+/**
+ * Vercel decode lifecycle policy — mid-stream-join repair.
+ *
+ * When a client joins a stream mid-flight (history compaction, rewind miss,
+ * partial page), the reducer must still see a clean `start` / `start-step`
+ * pre-roll. This policy keys that repair on the discrete codec `kind` and on
+ * stream start; each entry performs its tracker side effect and returns the
+ * lead-in chunks the generic decoder prepends before running the descriptor
+ * driver. A fresh policy (and tracker) is built per decoder instance.
+ */
+
+import type * as AI from 'ai';
+
+import { createLifecycleTracker, type LifecyclePolicy, type LifecycleTracker } from '../../core/codec/index.js';
+import { stripUndefined } from '../../utils.js';
+import type { VercelOutput } from './events.js';
+import { fMessageId } from './fields.js';
+
+const createVercelLifecycleTracker = (): LifecycleTracker<AI.UIMessageChunk> =>
+  createLifecycleTracker<AI.UIMessageChunk>([
+    {
+      key: 'start',
+      build: (ctx) => [stripUndefined({ type: 'start' as const, messageId: ctx.messageId })],
+    },
+    {
+      key: 'start-step',
+      build: () => [{ type: 'start-step' as const }],
+    },
+  ]);
+
+/**
+ * Build a fresh Vercel decode lifecycle policy (with its own tracker). Passed
+ * to `defineCodec` as the `decodeLifecycle` factory so each decoder instance
+ * gets independent per-run phase state.
+ * @returns A {@link LifecyclePolicy} for the Vercel output union.
+ */
+export const createVercelDecodeLifecycle = (): LifecyclePolicy<VercelOutput> => {
+  const tracker = createVercelLifecycleTracker();
+  return {
+    onDiscrete: {
+      start: (runId) => {
+        tracker.markEmitted(runId, 'start');
+        return [];
+      },
+      'start-step': (runId) => {
+        tracker.markEmitted(runId, 'start-step');
+        return [];
+      },
+      'finish-step': (runId) => {
+        tracker.resetPhase(runId, 'start-step');
+        return [];
+      },
+      finish: (runId) => {
+        tracker.clearScope(runId);
+        return [];
+      },
+      error: (runId) => {
+        tracker.clearScope(runId);
+        return [];
+      },
+      abort: (runId) => {
+        tracker.clearScope(runId);
+        return [];
+      },
+      'tool-input': (runId, ctx) => tracker.ensurePhases(runId, { messageId: fMessageId.read(ctx.codecHeaders) }),
+    },
+    onStreamStart: (runId, trackerState) =>
+      tracker.ensurePhases(runId, { messageId: fMessageId.read(trackerState.codecHeaders) }),
+  };
+};