@ably/ai-transport 0.0.1 → 0.1.0

package/src/core/transport/decode-history.ts

@@ -1,6 +1,6 @@
 /**
  * decodeHistory — load conversation history from an Ably channel and
- * return decoded messages as a PaginatedMessages result.
+ * return decoded messages as a paginated HistoryPage result.
  *
  * Uses a fresh decoder (not shared with the live subscription) to avoid
  * state conflicts. Per-turn accumulators handle interleaved turns correctly.
@@ -16,17 +16,26 @@
  *
  * Because Ably history returns newest-first while the decoder requires
  * chronological order, all collected Ably messages are re-decoded from
- * oldest to newest after each page fetch. This handles turns that span
- * page boundaries correctly.
+ * oldest to newest at the point a result is built. This handles turns
+ * that span page boundaries correctly. The fetch loop uses a cheap
+ * header-based completion counter to decide when to stop paging, so the
+ * full decode runs exactly once per traversal regardless of page count.
  */
 
 import type * as Ably from 'ably';
 
-import { HEADER_MSG_ID, HEADER_TURN_ID } from '../../constants.js';
+import {
+  HEADER_AMEND,
+  HEADER_DISCRETE,
+  HEADER_MSG_ID,
+  HEADER_STATUS,
+  HEADER_STREAM,
+  HEADER_TURN_ID,
+} from '../../constants.js';
 import type { Logger } from '../../logger.js';
 import { getHeaders } from '../../utils.js';
 import type { Codec, DecoderOutput, MessageAccumulator } from '../codec/types.js';
-import type { LoadHistoryOptions, PaginatedMessages } from './types.js';
+import type { HistoryPage, LoadHistoryOptions } from './types.js';
 
 // ---------------------------------------------------------------------------
 // Shared state across pages within one history traversal
@@ -42,8 +51,36 @@ interface HistoryState<TEvent, TMessage> {
   returnedRawCount: number;
   /** The last Ably page cursor for continued pagination. */
   lastAblyPage: Ably.PaginatedResult<Ably.InboundMessage> | undefined;
-  /** Key function for domain messages (codec.getMessageKey). */
-  getMessageKey: (message: TMessage) => string;
+  /**
+   * Cached result of the last {@link decodeAll} call, reused while
+   * `rawMessages` is unchanged. Invalidated implicitly by comparing
+   * {@link cachedAtRawLength} against `rawMessages.length`; `rawMessages`
+   * is append-only within a traversal so length is a sufficient key.
+   */
+  cachedDecode: DecodedItem<TMessage>[] | undefined;
+  /** `rawMessages.length` at the time {@link cachedDecode} was produced. */
+  cachedAtRawLength: number;
+  /**
+   * `x-ably-msg-id`s for which the decoder has something to produce output
+   * from: any `message.create` / `message.update` / `message.append` with
+   * `x-ably-stream: "true"` (establishes a tracker via create or
+   * first-contact), or a `message.create` carrying `x-ably-discrete` (a
+   * discrete message, created and terminated in one wire message).
+   */
+  startedMsgIds: Set<string>;
+  /**
+   * `x-ably-msg-id`s with a terminal wire signal: either `x-ably-discrete`
+   * on a `message.create` (discrete message) or `x-ably-status: "finished"`
+   * / `"aborted"` on any action (closed stream).
+   */
+  terminatedMsgIds: Set<string>;
+  /**
+   * `x-ably-msg-id`s that are both started AND terminated - ready to appear
+   * in the decoded output. The fetch loop reads this set's size to decide
+   * when to stop paging, avoiding a full decode per page. Maintained
+   * incrementally by {@link countNewCompletions}. Grows monotonically.
+   */
+  completedMsgIds: Set<string>;
   logger: Logger;
 }
 
@@ -84,10 +121,16 @@ const decodeAll = <TEvent, TMessage>(state: HistoryState<TEvent, TMessage>): Dec
   const defaultAccumulator = state.codec.createAccumulator();
   let orderCounter = 0;
 
-  // Headers for discrete messages (writeMessages output), keyed by codec message key.
+  // Headers and serials for non-turn discrete messages, keyed by x-ably-msg-id.
   const discreteHeaders = new Map<string, Record<string, string>>();
-  // Serials for discrete messages, keyed by codec message key.
   const discreteSerials = new Map<string, string>();
+  // Track which msgId produced each non-turn discrete message output (in order).
+  const discreteMsgIds: string[] = [];
+
+  // Cross-turn event targets to complete after all events are processed.
+  // Deferred so that finish/abort events that follow the update in serial
+  // order can still process on the active message (e.g. applying messageMetadata).
+  const deferredCompletions: { accumulator: MessageAccumulator<TEvent, TMessage>; messageId: string }[] = [];
 
   for (const msg of chronological) {
     const outputs: DecoderOutput<TEvent, TMessage>[] = decoder.decode(msg);
@@ -95,6 +138,26 @@ const decodeAll = <TEvent, TMessage>(state: HistoryState<TEvent, TMessage>): Dec
     const turnId = headers[HEADER_TURN_ID];
     const msgId = headers[HEADER_MSG_ID];
     const serial = msg.serial;
+    const amendTarget = headers[HEADER_AMEND];
+
+    // Cross-turn events target an existing message from a different turn.
+    // Route to the owning turn's accumulator via initMessage lifecycle.
+    if (amendTarget) {
+      for (const turn of turns.values()) {
+        if (turn.msgHeaders.has(amendTarget)) {
+          const headerKeys = [...turn.msgHeaders.keys()];
+          const msgIndex = headerKeys.indexOf(amendTarget);
+          const currentMsg = msgIndex === -1 ? undefined : turn.accumulator.messages[msgIndex];
+          if (currentMsg) {
+            turn.accumulator.initMessage(amendTarget, currentMsg);
+          }
+          turn.accumulator.processOutputs(outputs);
+          deferredCompletions.push({ accumulator: turn.accumulator, messageId: amendTarget });
+          break;
+        }
+      }
+      continue;
+    }
 
     if (turnId) {
       let turn = turns.get(turnId);
@@ -123,81 +186,65 @@ const decodeAll = <TEvent, TMessage>(state: HistoryState<TEvent, TMessage>): Dec
       turn.accumulator.processOutputs(outputs);
     } else {
       defaultAccumulator.processOutputs(outputs);
-    }
 
-    // Capture headers and serial for discrete messages by codec key.
-    for (const output of outputs) {
-      if (output.kind === 'message') {
-        const key = state.getMessageKey(output.message);
-        const existingDiscrete = discreteHeaders.get(key);
-        if (!existingDiscrete) {
-          discreteHeaders.set(key, { ...headers });
-          if (serial) discreteSerials.set(key, serial);
-        } else if (Object.keys(headers).length > 0) {
-          Object.assign(existingDiscrete, headers);
+      // Capture headers and serial for non-turn discrete messages by x-ably-msg-id.
+      for (const output of outputs) {
+        if (output.kind === 'message' && msgId) {
+          discreteMsgIds.push(msgId);
+          const existingDiscrete = discreteHeaders.get(msgId);
+          if (!existingDiscrete) {
+            discreteHeaders.set(msgId, { ...headers });
+            if (serial) discreteSerials.set(msgId, serial);
+          } else if (Object.keys(headers).length > 0) {
+            Object.assign(existingDiscrete, headers);
+          }
         }
       }
     }
   }
 
+  // Complete any messages that were re-activated for cross-turn updates.
+  // Idempotent — if finish already removed the message from active tracking,
+  // completeMessage is a no-op.
+  for (const { accumulator, messageId } of deferredCompletions) {
+    accumulator.completeMessage(messageId);
+  }
+
   // Collect completed messages in chronological order (oldest first) by turn.
   const completed: DecodedItem<TMessage>[] = [];
 
-  for (const msg of defaultAccumulator.completedMessages) {
-    const key = state.getMessageKey(msg);
+  // Default accumulator messages: pair with their discrete headers by position.
+  for (const [i, msg] of defaultAccumulator.completedMessages.entries()) {
+    const mid = discreteMsgIds[i];
     completed.push({
       message: msg,
-      headers: discreteHeaders.get(key) ?? {},
-      serial: discreteSerials.get(key) ?? '',
+      headers: mid ? (discreteHeaders.get(mid) ?? {}) : {},
+      serial: mid ? (discreteSerials.get(mid) ?? '') : '',
     });
   }
 
   const sorted = [...turns.values()].toSorted((a, b) => a.firstSeen - b.firstSeen);
   for (const turn of sorted) {
     // Assign headers and serials to each completed message in this turn.
-    // Discrete messages were already captured by codec key. Accumulated
-    // messages need to be matched to the turn's per-msg-id headers.
-    const claimedMsgIds = new Set<string>();
-
-    // First pass: resolve discrete messages and mark their msg-ids as claimed
-    const turnKeyHeaders = new Map<string, Record<string, string>>();
-    const turnKeySerials = new Map<string, string>();
-    for (const msg of turn.accumulator.completedMessages) {
-      const key = state.getMessageKey(msg);
-      const discrete = discreteHeaders.get(key);
-      if (discrete) {
-        turnKeyHeaders.set(key, discrete);
-        const dSerial = discreteSerials.get(key);
-        if (dSerial) turnKeySerials.set(key, dSerial);
-        const mid = discrete[HEADER_MSG_ID];
-        if (mid) claimedMsgIds.add(mid);
-      }
-    }
-
-    // Second pass: assign unclaimed msg-id entries to remaining messages
-    const unclaimedEntries = [...turn.msgHeaders.entries()].filter(([mid]) => !claimedMsgIds.has(mid));
-    let unclaimedIdx = 0;
+    // The turn's msgHeaders map is keyed by x-ably-msg-id and ordered by
+    // first-seen. Completed messages are matched positionally.
+    const headerEntries = [...turn.msgHeaders.entries()];
+    let headerIdx = 0;
 
     for (const msg of turn.accumulator.completedMessages) {
-      const key = state.getMessageKey(msg);
-      const unclaimed = unclaimedEntries[unclaimedIdx];
-      if (!turnKeyHeaders.has(key) && unclaimed) {
-        const [mid, hdrs] = unclaimed;
-        turnKeyHeaders.set(key, hdrs);
-        const mSerial = turn.msgSerials.get(mid);
-        if (mSerial) turnKeySerials.set(key, mSerial);
-        unclaimedIdx++;
+      const entry = headerEntries[headerIdx];
+      if (entry) {
+        const [mid, hdrs] = entry;
+        completed.push({
+          message: msg,
+          headers: hdrs,
+          serial: turn.msgSerials.get(mid) ?? '',
+        });
+        headerIdx++;
+      } else {
+        completed.push({ message: msg, headers: {}, serial: '' });
       }
     }
-
-    for (const msg of turn.accumulator.completedMessages) {
-      const key = state.getMessageKey(msg);
-      completed.push({
-        message: msg,
-        headers: turnKeyHeaders.get(key) ?? {},
-        serial: turnKeySerials.get(key) ?? '',
-      });
-    }
   }
 
   // Reverse to newest-first. The consumer slices from the front for the
@@ -205,12 +252,113 @@ const decodeAll = <TEvent, TMessage>(state: HistoryState<TEvent, TMessage>): Dec
   return completed.toReversed();
 };
 
+/**
+ * Cached wrapper around {@link decodeAll}. Returns the previous result when
+ * `rawMessages` hasn't changed since the last decode; otherwise re-decodes
+ * and updates the cache. The cache key is `rawMessages.length` because
+ * `rawMessages` is append-only within a traversal.
+ * @param state - The shared history traversal state.
+ * @returns Completed messages in newest-first order.
+ */
+const decodeAllCached = <TEvent, TMessage>(state: HistoryState<TEvent, TMessage>): DecodedItem<TMessage>[] => {
+  if (state.cachedDecode && state.cachedAtRawLength === state.rawMessages.length) {
+    return state.cachedDecode;
+  }
+  const result = decodeAll(state);
+  state.cachedDecode = result;
+  state.cachedAtRawLength = state.rawMessages.length;
+  return result;
+};
+
+// ---------------------------------------------------------------------------
+// Incremental completion counting (avoids full decode inside the fetch loop)
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan newly-added raw messages and track which `x-ably-msg-id`s have
+ * become complete. Used by {@link fetchUntilLimit} to decide when enough
+ * completed messages have been collected, without running the decoder.
+ *
+ * A msg-id is considered complete only when BOTH of these have been seen:
+ * - a "start" signal: either `x-ably-discrete` on a `message.create`
+ *   (discrete messages are created and terminated by the same wire
+ *   message), OR any `message.create` / `message.update` / `message.append`
+ *   with `x-ably-stream: "true"` (the decoder establishes a tracker via
+ *   create or first-contact).
+ * - a "terminal" signal: `x-ably-discrete` on the create, or
+ *   `x-ably-status: "finished"` / `"aborted"` on any later action.
+ *
+ * Why update and append count as starts: Ably history can compact a live
+ * `create + append + ... + append{status:finished}` sequence into a single
+ * `message.update` with `STREAM=true` and `STATUS=finished`. The decoder
+ * handles that in {@link _decodeUpdate} via first-contact. Counting only
+ * `message.create` as a start would cause the fetch loop to page past a
+ * compacted turn without ever marking it complete.
+ *
+ * Requiring both halves matters when a streaming turn spans a page
+ * boundary: the terminal arrives in the newer page (fetched first) while
+ * the start sits in an older page. Counting the terminal alone would stop
+ * the fetch loop prematurely - the decoder would have no stream state to
+ * resolve, and the message wouldn't make it into the result.
+ *
+ * Messages skipped for counting:
+ * - Missing `x-ably-msg-id`: lifecycle events not tied to a domain message.
+ * - `x-ably-amend` set: amendments target an existing message, not a new
+ *   completion.
+ * - `message.delete`: clears the tracker, doesn't produce output.
+ *
+ * Known edge case: if Ably history is truncated and a terminal survives
+ * while every start signal for its msg-id has rolled off, the counter will
+ * never mark that `msg-id` complete. The loop keeps fetching until it runs
+ * out of pages, then returns whatever the decoder actually produced.
+ * Matches the existing behaviour for the same truncation scenario.
+ * @param state - The shared history traversal state.
+ * @param newMessages - The Ably messages just pushed onto `state.rawMessages`.
+ */
+const countNewCompletions = <TEvent, TMessage>(
+  state: HistoryState<TEvent, TMessage>,
+  newMessages: readonly Ably.InboundMessage[],
+): void => {
+  for (const msg of newMessages) {
+    const headers = getHeaders(msg);
+    const msgId = headers[HEADER_MSG_ID];
+    if (!msgId) continue;
+    // Amendments target an existing message, not a new completion.
+    // Defensive: no current encoder path produces an amendment carrying
+    // HEADER_STREAM=true, HEADER_STATUS, or HEADER_DISCRETE.
+    if (headers[HEADER_AMEND]) continue;
+
+    const action = msg.action;
+    const isDiscreteCreate = action === 'message.create' && HEADER_DISCRETE in headers;
+    // Any content-producing action on a streamed serial counts as a start:
+    // the decoder uses create or first-contact (update/append) to establish
+    // its tracker. Delete clears tracker state and emits nothing, so it
+    // never counts as a start.
+    const hasStreamContent =
+      headers[HEADER_STREAM] === 'true' &&
+      (action === 'message.create' || action === 'message.update' || action === 'message.append');
+    const status = headers[HEADER_STATUS];
+    const isTerminal = status === 'finished' || status === 'aborted';
+
+    if (isDiscreteCreate || hasStreamContent) state.startedMsgIds.add(msgId);
+    if (isDiscreteCreate || isTerminal) state.terminatedMsgIds.add(msgId);
+    if (state.startedMsgIds.has(msgId) && state.terminatedMsgIds.has(msgId)) {
+      state.completedMsgIds.add(msgId);
+    }
+  }
+};
+
 // ---------------------------------------------------------------------------
 // Fetch Ably pages until we have enough completed messages
 // ---------------------------------------------------------------------------
 
 /**
  * Fetch Ably history pages until we have enough completed messages.
+ *
+ * The loop uses {@link countNewCompletions} to decide when to stop -
+ * a cheap O(new messages) header scan - rather than running the full
+ * decoder per page. The decoder runs exactly once later, in
+ * {@link buildResult}, against the fully-collected `rawMessages`.
  * @param state - The shared history traversal state.
  * @param ablyPage - The current Ably paginated result to start from.
  * @param limit - Target number of completed messages beyond what has already been returned.
@@ -222,39 +370,37 @@ const fetchUntilLimit = async <TEvent, TMessage>(
 ): Promise<void> => {
   state.rawMessages.push(...ablyPage.items);
   state.lastAblyPage = ablyPage;
+  countNewCompletions(state, ablyPage.items);
 
-  let decodedCount = decodeAll(state).length;
-  while (decodedCount < state.returnedCount + limit && ablyPage.hasNext()) {
+  const target = state.returnedCount + limit;
+  while (state.completedMsgIds.size < target && ablyPage.hasNext()) {
     state.logger.debug('decodeHistory.fetchUntilLimit(); fetching next page', {
       collected: state.rawMessages.length,
-      decoded: decodedCount,
+      completed: state.completedMsgIds.size,
     });
     const nextPage = await ablyPage.next();
     if (!nextPage) break;
     ablyPage = nextPage;
     state.rawMessages.push(...nextPage.items);
     state.lastAblyPage = nextPage;
-    decodedCount = decodeAll(state).length;
+    countNewCompletions(state, nextPage.items);
   }
 };
 
 // ---------------------------------------------------------------------------
-// Build PaginatedMessages result from current state
+// Build HistoryPage result from current state
 // ---------------------------------------------------------------------------
 
 /**
- * Build a PaginatedMessages page from the current decode state.
+ * Build a HistoryPage from the current decode state.
  * @param state - The shared history traversal state.
  * @param limit - Max messages per page.
- * @returns A page of decoded messages with a `next()` cursor.
+ * @returns A page of decoded history with a `next()` cursor.
  */
-const buildResult = <TEvent, TMessage>(
-  state: HistoryState<TEvent, TMessage>,
-  limit: number,
-): PaginatedMessages<TMessage> => {
+const buildResult = <TEvent, TMessage>(state: HistoryState<TEvent, TMessage>, limit: number): HistoryPage<TMessage> => {
   // allCompleted is newest-first. Slice from returnedCount for this page,
   // then reverse to chronological for display.
-  const allCompleted = decodeAll(state);
+  const allCompleted = decodeAllCached(state);
 
   const pageSlice = allCompleted.slice(state.returnedCount, state.returnedCount + limit);
   const chronSlice = [...pageSlice].toReversed();
@@ -269,9 +415,7 @@ const buildResult = <TEvent, TMessage>(
   state.returnedRawCount = state.rawMessages.length;
 
   return {
-    items: chronSlice.map((d) => d.message),
-    itemHeaders: chronSlice.map((d) => d.headers),
-    itemSerials: chronSlice.map((d) => d.serial),
+    items: chronSlice.map((d) => ({ message: d.message, headers: d.headers, serial: d.serial })),
     rawMessages: rawSlice,
     hasNext: () => moreCompleted || moreAblyPages,
     next: async () => {
@@ -304,7 +448,7 @@ const buildResult = <TEvent, TMessage>(
  * @param codec - The codec for decoding wire messages into domain messages.
  * @param options - Pagination options.
  * @param logger - Logger for diagnostic output.
- * @returns The first page of decoded history messages.
+ * @returns The first page of decoded history.
  */
 // Spec: AIT-CT11, AIT-CT11b
 export const decodeHistory = async <TEvent, TMessage>(
@@ -312,7 +456,7 @@ export const decodeHistory = async <TEvent, TMessage>(
   codec: Codec<TEvent, TMessage>,
   options: LoadHistoryOptions | undefined,
   logger: Logger,
-): Promise<PaginatedMessages<TMessage>> => {
+): Promise<HistoryPage<TMessage>> => {
   const limit = options?.limit ?? 100;
   const state: HistoryState<TEvent, TMessage> = {
     codec,
@@ -320,7 +464,11 @@ export const decodeHistory = async <TEvent, TMessage>(
     returnedCount: 0,
     returnedRawCount: 0,
     lastAblyPage: undefined,
-    getMessageKey: codec.getMessageKey.bind(codec),
+    cachedDecode: undefined,
+    cachedAtRawLength: 0,
+    startedMsgIds: new Set<string>(),
+    terminatedMsgIds: new Set<string>(),
+    completedMsgIds: new Set<string>(),
     logger,
   };
 

package/src/core/transport/headers.ts

@@ -7,6 +7,7 @@
  */
 
 import {
+  HEADER_AMEND,
   HEADER_FORK_OF,
   HEADER_MSG_ID,
   HEADER_PARENT,
@@ -22,8 +23,9 @@ import {
  * @param opts.turnId - Turn correlation ID.
  * @param opts.msgId - Message identity.
  * @param opts.turnClientId - ClientId of the turn initiator.
- * @param opts.parent - Preceding message's msg-id (for branching). Null means root.
+ * @param opts.parent - Preceding message's msg-id (for branching).
  * @param opts.forkOf - Forked message's msg-id (for edit/regen).
+ * @param opts.amend - The msg-id of the existing message this message targets (cross-turn events).
  * @returns A headers record with the `x-ably-*` transport headers set.
  */
 export const buildTransportHeaders = (opts: {
@@ -31,8 +33,9 @@ export const buildTransportHeaders = (opts: {
   turnId: string;
   msgId: string;
   turnClientId?: string;
-  parent?: string | null;
+  parent?: string;
   forkOf?: string;
+  amend?: string;
 }): Record<string, string> => {
   const h: Record<string, string> = {
     [HEADER_ROLE]: opts.role,
@@ -42,5 +45,6 @@ export const buildTransportHeaders = (opts: {
   if (opts.turnClientId !== undefined) h[HEADER_TURN_CLIENT_ID] = opts.turnClientId;
   if (opts.parent) h[HEADER_PARENT] = opts.parent;
   if (opts.forkOf) h[HEADER_FORK_OF] = opts.forkOf;
+  if (opts.amend) h[HEADER_AMEND] = opts.amend;
   return h;
 };

package/src/core/transport/index.ts

@@ -8,22 +8,30 @@ export type {
   ClientTransport,
   ClientTransportOptions,
   CloseOptions,
-  ConversationNode,
-  ConversationTree,
-  LoadHistoryOptions,
-  MessageWithHeaders,
+  EventsNode,
+  MessageNode,
   NewTurnOptions,
-  PaginatedMessages,
   SendOptions,
   ServerTransport,
   ServerTransportOptions,
   StreamResponseOptions,
   StreamResult,
+  Tree,
   Turn,
   TurnEndReason,
   TurnLifecycleEvent,
+  View,
 } from './types.js';
 
+// Deprecated aliases — intentional re-export of deprecated types for backwards compatibility.
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+export type { EventNode } from './types.js';
+// eslint-disable-next-line @typescript-eslint/no-deprecated
+export type { TreeNode } from './types.js';
+
+// Internal tree interface (consumed by View implementations)
+export type { TreeInternal } from './tree.js';
+
 // Server transport
 export { createServerTransport } from './server-transport.js';
 

package/src/core/transport/pipe-stream.ts

@@ -6,7 +6,7 @@
  */
 
 import type { Logger } from '../../logger.js';
-import type { StreamEncoder } from '../codec/types.js';
+import type { StreamEncoder, WriteOptions } from '../codec/types.js';
 import type { StreamResult } from './types.js';
 
 /**
@@ -18,6 +18,7 @@ import type { StreamResult } from './types.js';
  * @param encoder - The streaming encoder to write events through.
  * @param signal - Abort signal to monitor for cancellation.
  * @param onAbort - Optional callback invoked when the stream is cancelled, before the stream ends.
+ * @param resolveWriteOptions - Optional per-event hook returning {@link WriteOptions} overrides to pass to `encoder.appendEvent`.
  * @param logger - Optional logger for diagnostic output.
  * @returns The reason the pipe ended.
  */
@@ -26,6 +27,7 @@ export const pipeStream = async <TEvent, TMessage>(
   encoder: StreamEncoder<TEvent, TMessage>,
   signal: AbortSignal | undefined,
   onAbort?: (write: (event: TEvent) => Promise<void>) => void | Promise<void>,
+  resolveWriteOptions?: (event: TEvent) => WriteOptions | undefined,
   logger?: Logger,
 ): Promise<StreamResult> => {
   logger?.trace('pipeStream();');
@@ -48,6 +50,7 @@ export const pipeStream = async <TEvent, TMessage>(
       new Promise<void>(() => {});
 
   let reason: StreamResult['reason'] = 'complete';
+  let caughtError: Error | undefined;
 
   try {
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- intentional infinite loop broken by return/break
@@ -73,12 +76,12 @@ export const pipeStream = async <TEvent, TMessage>(
         break;
       }
 
-      await encoder.appendEvent(value);
+      await encoder.appendEvent(value, resolveWriteOptions?.(value));
     }
   } catch (error) {
     reason = 'error';
-    const errorText = error instanceof Error ? error.message : String(error);
-    logger?.error('pipeStream(); stream error', { error: errorText });
+    caughtError = error instanceof Error ? error : new Error(String(error));
+    logger?.error('pipeStream(); stream error', { error: caughtError.message });
     try {
       await encoder.close();
     } catch {
@@ -91,5 +94,5 @@ export const pipeStream = async <TEvent, TMessage>(
     reader.releaseLock();
   }
 
-  return { reason };
+  return { reason, error: caughtError };
 };