@ably/ai-transport 0.1.0 → 0.3.0

package/src/core/transport/load-history-pages.ts

@@ -0,0 +1,220 @@
+/**
+ * loadHistoryPages — shared low-level history pagination primitive.
+ *
+ * Consumed by both client (via `load-history.ts`, which layers a complete-
+ * domain-message counter on top) and agent (directly, for input-event lookup
+ * and conversation hydration). Returns raw Ably messages; does NOT decode.
+ *
+ * Behaviour:
+ *  - Attaches the channel (idempotent) then pages via `channel.history()`,
+ *    using `untilAttach: true` for gapless continuity with any live subscription.
+ *  - Exposes the underlying pagination as a cursor with `hasNext()` (cheap,
+ *    no network) and `next()` (one Ably page per call, newest-first within
+ *    the page).
+ *  - Per-page failures are retried with bounded exponential backoff; on
+ *    exhaustion throws `Ably.ErrorInfo` with code `HistoryFetchFailed`.
+ *  - `signal.aborted` is checked between pages; rejects with
+ *    `Ably.ErrorInfo` (InvalidArgument) when aborted.
+ *
+ * Spec: AIT-CT11 / AIT-ST hydration.
+ */
+
+import * as Ably from 'ably';
+
+import { ErrorCode } from '../../errors.js';
+import type { Logger } from '../../logger.js';
+import { errorCause, errorMessage } from '../../utils.js';
+
+/** Options for {@link loadHistoryPages}. */
+export interface LoadHistoryPagesOptions {
+  /** Wire-message limit per Ably page. */
+  pageLimit: number;
+  /** Set `untilAttach: true` on the underlying history query for gapless continuity with live subscriptions. Default: true. */
+  untilAttach?: boolean;
+  /** AbortSignal checked between pages. Rejects with InvalidArgument when aborted. */
+  signal?: AbortSignal;
+  /** Max retries per `page.next()` / initial `history()` failure. Default: 3. */
+  maxRetries?: number;
+  /** Initial retry backoff in ms (doubled per attempt). Default: 100. */
+  retryBackoffMs?: number;
+  /** Logger for diagnostic output. */
+  logger?: Logger;
+}
+
+/**
+ * Cursor over the channel's history pages.
+ *
+ * `hasNext()` is cheap (cursor-only, no network); `next()` issues one Ably
+ * page fetch (with retry/backoff) and returns its messages. Once `next()`
+ * returns `undefined` the cursor is exhausted.
+ */
+export interface HistoryPagesCursor {
+  /** True when another Ably page is available (cheap to check; no network). */
+  hasNext(): boolean;
+  /**
+   * Fetch the next Ably page's messages (newest-first within the page).
+   * Returns `undefined` when no more pages are available or the abort
+   * signal has fired.
+   */
+  next(): Promise<readonly Ably.InboundMessage[] | undefined>;
+}
+
+/**
+ * Sleep for `ms` milliseconds, honouring an AbortSignal.
+ * @param ms - Milliseconds to wait.
+ * @param signal - Optional abort signal; rejects when fired.
+ */
+// eslint-disable-next-line @typescript-eslint/promise-function-async -- the function body is the Promise constructor; async would wrap it in an extra Promise
+const sleep = (ms: number, signal?: AbortSignal): Promise<void> =>
+  new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Ably.ErrorInfo('unable to wait; signal aborted', ErrorCode.InvalidArgument, 400));
+      return;
+    }
+    const timer: ReturnType<typeof setTimeout> | number = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    // Node returns an unref-able Timeout; browsers return a number. Unref so
+    // a retry backoff cannot keep a Node process alive by itself.
+    if (typeof timer === 'object') timer.unref();
+    const onAbort = (): void => {
+      clearTimeout(timer);
+      reject(new Ably.ErrorInfo('unable to wait; signal aborted', ErrorCode.InvalidArgument, 400));
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+
+/**
+ * Invoke `fetchPage`, retrying on failure with exponential backoff. Throws
+ * the last failure wrapped as `HistoryFetchFailed` once retries are
+ * exhausted.
+ * @param fetchPage - The page fetch to retry (initial `channel.history()` call or a `page.next()`).
+ * @param maxRetries - Maximum number of attempts after the initial call.
+ * @param initialBackoffMs - Starting backoff delay (doubled per attempt).
+ * @param signal - Optional abort signal; cancels remaining retries.
+ * @param logger - Optional logger.
+ * @returns The fetched page, or `undefined` when pagination is exhausted.
+ */
+const fetchPageWithRetry = async (
+  fetchPage: () => Promise<Ably.PaginatedResult<Ably.InboundMessage> | undefined>,
+  maxRetries: number,
+  initialBackoffMs: number,
+  signal: AbortSignal | undefined,
+  logger: Logger | undefined,
+): Promise<Ably.PaginatedResult<Ably.InboundMessage> | undefined> => {
+  let lastError: unknown;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    if (signal?.aborted) {
+      throw new Ably.ErrorInfo(
+        'unable to fetch history page; signal aborted',
+        ErrorCode.InvalidArgument,
+        400,
+        errorCause(lastError),
+      );
+    }
+    try {
+      return await fetchPage();
+    } catch (error) {
+      lastError = error;
+      if (attempt === maxRetries) break;
+      const backoff = initialBackoffMs * 2 ** attempt;
+      logger?.debug('loadHistoryPages.fetchPageWithRetry(); page fetch failed, retrying', {
+        attempt: attempt + 1,
+        maxRetries,
+        backoff,
+      });
+      await sleep(backoff, signal);
+    }
+  }
+  throw new Ably.ErrorInfo(
+    `unable to fetch history page; ${errorMessage(lastError)}`,
+    ErrorCode.HistoryFetchFailed,
+    500,
+    errorCause(lastError),
+  );
+};
+
+/**
+ * Page through channel history, returning a cursor over Ably pages.
+ *
+ * Newest-first within each yielded page (matching Ably's native ordering).
+ * Caller drives the cursor — calling `next()` until it returns `undefined`
+ * or stopping early when a domain-specific stop condition is met
+ * (e.g. complete-message counter satisfied, target codec-message-id found,
+ * parent chain walk reaches root).
+ *
+ * The initial Ably history call is awaited eagerly so the returned cursor
+ * already knows whether there are pages available (via `hasNext()`).
+ * @param channel - The Ably channel to read history from.
+ * @param options - Pagination options.
+ * @returns A cursor with `hasNext()` (cheap, cursor-only) and `next()` (fetches one page with retry).
+ * @throws {Ably.ErrorInfo} `HistoryFetchFailed` on exhausted retry of the initial fetch, or `InvalidArgument` on signal abort.
+ */
+export const loadHistoryPages = async (
+  channel: Ably.RealtimeChannel,
+  options: LoadHistoryPagesOptions,
+): Promise<HistoryPagesCursor> => {
+  const { pageLimit, untilAttach = true, signal, maxRetries = 3, retryBackoffMs = 100, logger } = options;
+
+  if (signal?.aborted) {
+    throw new Ably.ErrorInfo('unable to load history; signal aborted', ErrorCode.InvalidArgument, 400);
+  }
+
+  await channel.attach();
+
+  const historyParams: Ably.RealtimeHistoryParams = { limit: pageLimit, untilAttach };
+
+  let currentPage: Ably.PaginatedResult<Ably.InboundMessage> | undefined = await fetchPageWithRetry(
+    // eslint-disable-next-line @typescript-eslint/promise-function-async -- channel.history returns a real Promise
+    () => channel.history(historyParams),
+    maxRetries,
+    retryBackoffMs,
+    signal,
+    logger,
+  );
+  let firstYielded = false;
+
+  // Compute whether the cursor has another page available. Cheap — no
+  // network. Reflects the latest fetched page's `hasNext()` plus the signal
+  // check.
+  const hasNext = (): boolean => {
+    if (currentPage === undefined) return false;
+    if (signal?.aborted) return false;
+    if (!firstYielded) return true;
+    return currentPage.hasNext();
+  };
+
+  const next = async (): Promise<readonly Ably.InboundMessage[] | undefined> => {
+    if (currentPage === undefined) return undefined;
+    if (signal?.aborted) {
+      throw new Ably.ErrorInfo('unable to load history; signal aborted', ErrorCode.InvalidArgument, 400);
+    }
+
+    if (!firstYielded) {
+      firstYielded = true;
+      return currentPage.items;
+    }
+
+    if (!currentPage.hasNext()) {
+      currentPage = undefined;
+      return undefined;
+    }
+
+    const nextPage: Ably.PaginatedResult<Ably.InboundMessage> | undefined = await fetchPageWithRetry(
+      async () => (await currentPage?.next()) ?? undefined,
+      maxRetries,
+      retryBackoffMs,
+      signal,
+      logger,
+    );
+    if (!nextPage) {
+      currentPage = undefined;
+      return undefined;
+    }
+    currentPage = nextPage;
+    return nextPage.items;
+  };
+
+  return { hasNext, next };
+};

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

@@ -0,0 +1,271 @@
+/**
+ * loadHistory — load conversation history from an Ably channel and return
+ * the raw Ably messages as a paginated HistoryPage result.
+ *
+ * This does NOT decode: it pages back through Ably history via the shared
+ * {@link loadHistoryPages} primitive until `limit` complete messages are
+ * present, then hands the raw Ably messages (oldest-first) to the caller.
+ * The View re-decodes them into the Tree itself, so load-history only needs
+ * a cheap, header-based completion counter to decide when to stop paging.
+ *
+ * The `limit` option controls the number of complete **messages** per page,
+ * not the number of Ably messages fetched. A message is complete when
+ * its terminal wire signal — `status: "complete"` / `"cancelled"`, or a
+ * `discrete` create — has been seen. Runs that span a page boundary are
+ * handled by the counter requiring both a start and a terminal signal
+ * before counting a message complete.
+ *
+ * Because Ably history returns newest-first, each page's `rawMessages` are
+ * reversed to chronological (oldest-first) so the caller can fold them in
+ * order.
+ *
+ * Spec: AIT-CT11, AIT-CT11b.
+ */
+
+import type * as Ably from 'ably';
+
+import { HEADER_CODEC_MESSAGE_ID, HEADER_DISCRETE, HEADER_STATUS, HEADER_STREAM } from '../../constants.js';
+import type { Logger } from '../../logger.js';
+import { getTransportHeaders } from '../../utils.js';
+import { type HistoryPagesCursor, loadHistoryPages } from './load-history-pages.js';
+import type { HistoryPage, LoadHistoryOptions } from './types.js';
+
+// ---------------------------------------------------------------------------
+// Shared state across pages within one history traversal
+// ---------------------------------------------------------------------------
+
+interface HistoryState {
+  /** Cursor over the shared `loadHistoryPages` primitive; each `next()` returns one Ably page's messages (newest-first within the page). */
+  cursor: HistoryPagesCursor;
+  /** All raw Ably messages collected so far, in newest-first order (as received from Ably). */
+  rawMessages: Ably.InboundMessage[];
+  /**
+   * How many complete messages have been served to the consumer so far.
+   * Drives the buffered-page logic: when a single fetch gathers more than
+   * `limit` completions, later pages are served from the buffer without
+   * fetching, advancing this counter `limit` at a time.
+   */
+  returnedCount: number;
+  /** How many raw Ably messages have been served to the consumer so far. */
+  returnedRawCount: number;
+  /**
+   * `codec-message-id`s for which a start signal has been seen: any
+   * `message.create` / `message.update` / `message.append` with
+   * `stream: "true"` (the decoder establishes a tracker via create or
+   * first-contact), or a `message.create` carrying `discrete` (a discrete
+   * message, created and terminated in one Ably message).
+   */
+  startedCodecMessageIds: Set<string>;
+  /**
+   * `codec-message-id`s with a terminal wire signal: either `discrete`
+   * on a `message.create` (discrete message) or `status: "complete"`
+   * / `"cancelled"` on any action (closed stream).
+   */
+  terminatedCodecMessageIds: Set<string>;
+  /**
+   * `codec-message-id`s that are both started AND terminated — counted as
+   * complete. The fetch loop reads this set's size to decide when to stop
+   * paging. Maintained incrementally by {@link countNewCompletions}. Grows
+   * monotonically.
+   */
+  completedCodecMessageIds: Set<string>;
+  logger: Logger;
+}
+
+// ---------------------------------------------------------------------------
+// Incremental completion counting (header scan, no decode)
+// ---------------------------------------------------------------------------
+
+/**
+ * Scan newly-added raw messages and track which `codec-message-id`s have
+ * become complete. Used by {@link fetchUntilLimit} to decide when enough
+ * completed messages have been collected, without running the decoder.
+ *
+ * A codec-message-id is considered complete only when BOTH of these have been seen:
+ * - a "start" signal: either `discrete` on a `message.create`
+ *   (discrete messages are created and terminated by the same Ably message
+ *   message), OR any `message.create` / `message.update` / `message.append`
+ *   with `stream: "true"` (the decoder establishes a tracker via
+ *   create or first-contact).
+ * - a "terminal" signal: `discrete` on the create, or
+ *   `status: "complete"` / `"cancelled"` on any later action.
+ *
+ * Why update and append count as starts: Ably history can compact a live
+ * `create + append + ... + append{status:complete}` sequence into a single
+ * `message.update` with `STREAM=true` and `STATUS=complete`. The decoder
+ * handles that via first-contact. Counting only `message.create` as a start
+ * would cause the fetch loop to page past a compacted run without ever
+ * marking it complete.
+ *
+ * Requiring both halves matters when a streaming run 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 `codec-message-id`: lifecycle events not tied to a domain message.
+ * - `message.delete`: clears the tracker, doesn't produce output.
+ *
+ * Amend-class Ably messages (events targeting an existing message via
+ * `HEADER_CODEC_MESSAGE_ID`) flow through the same counter — the Sets naturally
+ * dedup so a tool-output amend on an already-seen codec-message-id is idempotent.
+ *
+ * Known edge case: if Ably history is truncated and a terminal survives
+ * while every start signal for its codec-message-id has rolled off, the counter will
+ * never mark that `codec-message-id` complete. The loop keeps fetching until it runs
+ * out of pages, then returns whatever raw messages it collected.
+ * @param state - The shared history traversal state.
+ * @param newMessages - The Ably messages just pushed onto `state.rawMessages`.
+ */
+const countNewCompletions = (state: HistoryState, newMessages: readonly Ably.InboundMessage[]): void => {
+  for (const msg of newMessages) {
+    const headers = getTransportHeaders(msg);
+    const codecMessageId = headers[HEADER_CODEC_MESSAGE_ID];
+    if (!codecMessageId) 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 === 'complete' || status === 'cancelled';
+
+    if (isDiscreteCreate || hasStreamContent) state.startedCodecMessageIds.add(codecMessageId);
+    if (isDiscreteCreate || isTerminal) state.terminatedCodecMessageIds.add(codecMessageId);
+    if (state.startedCodecMessageIds.has(codecMessageId) && state.terminatedCodecMessageIds.has(codecMessageId)) {
+      state.completedCodecMessageIds.add(codecMessageId);
+    }
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Pull pages from the shared iterator until we have enough completions
+// ---------------------------------------------------------------------------
+
+/**
+ * Pull chunks from the shared {@link loadHistoryPages} iterator until enough
+ * completed messages have been collected (target = already-returned +
+ * `limit`) or the iterator is exhausted.
+ *
+ * Uses {@link countNewCompletions} — a cheap O(new messages) header scan —
+ * to decide when to stop, rather than running the decoder per page.
+ * @param state - The shared history traversal state.
+ * @param limit - Target number of completed messages beyond what has already been returned.
+ */
+const fetchUntilLimit = async (state: HistoryState, limit: number): Promise<void> => {
+  const target = state.returnedCount + limit;
+  while (state.completedCodecMessageIds.size < target && state.cursor.hasNext()) {
+    state.logger.debug('loadHistory.fetchUntilLimit(); pulling next page', {
+      collected: state.rawMessages.length,
+      completed: state.completedCodecMessageIds.size,
+    });
+    const chunk = await state.cursor.next();
+    if (!chunk) break;
+    state.rawMessages.push(...chunk);
+    countNewCompletions(state, chunk);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Build HistoryPage result from current state
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a HistoryPage of raw Ably messages from the current fetch state.
+ * @param state - The shared history traversal state.
+ * @param limit - Max complete messages per page.
+ * @returns A page of raw history messages with a `next()` cursor.
+ */
+const buildResult = (state: HistoryState, limit: number): HistoryPage => {
+  // Advance the served-completion counter by up to `limit`, mirroring the
+  // page granularity the consumer asked for. `rawMessages` for this page are
+  // all messages fetched since the previous page (empty for buffered pages).
+  const totalCompleted = state.completedCodecMessageIds.size;
+  const served = Math.min(limit, Math.max(0, totalCompleted - state.returnedCount));
+  state.returnedCount += served;
+
+  const moreCompleted = totalCompleted > state.returnedCount;
+  const moreFromCursor = state.cursor.hasNext();
+
+  // Raw Ably messages for this page in chronological order (oldest first).
+  const newRawCount = state.rawMessages.length - state.returnedRawCount;
+  const rawMessages = newRawCount > 0 ? state.rawMessages.slice(state.returnedRawCount).toReversed() : [];
+  state.returnedRawCount = state.rawMessages.length;
+
+  return {
+    rawMessages,
+    hasNext: () => moreCompleted || moreFromCursor,
+    next: async () => {
+      if (moreCompleted) {
+        return buildResult(state, limit);
+      }
+      if (!moreFromCursor) return;
+      await fetchUntilLimit(state, limit);
+      return buildResult(state, limit);
+    },
+  };
+};
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Load conversation history from a channel and return the raw Ably messages.
+ *
+ * Drives the shared {@link loadHistoryPages} primitive with
+ * `untilAttach: true` (gapless continuity with the live subscription) and a
+ * Ably message page limit that overprovisions for the many-Ably-messages-per-domain-message
+ * ratio. Each `HistoryPage` returned covers up to `limit` complete domain
+ * messages; subsequent pages drain over-collected messages from the buffer
+ * before pulling more from the iterator.
+ *
+ * The `limit` option controls the number of complete messages returned per
+ * page, not the number of Ably messages fetched.
+ * @param channel - The Ably channel to load history from.
+ * @param options - Pagination options.
+ * @param logger - Logger for diagnostic output.
+ * @returns The first page of raw history messages.
+ */
+// Spec: AIT-CT11, AIT-CT11b
+export const loadHistory = async (
+  channel: Ably.RealtimeChannel,
+  options: LoadHistoryOptions | undefined,
+  logger: Logger,
+): Promise<HistoryPage> => {
+  const limit = options?.limit ?? 100;
+
+  logger.trace('loadHistory();', { limit });
+
+  // Request more Ably messages per page than the domain-message limit to
+  // account for the many-to-one ratio (multiple Ably messages per domain message).
+  // The wire pagination is internal to the iterator; the consumer-visible
+  // pagination is by complete domain messages.
+  const wireLimit = limit * 10;
+
+  const cursor = await loadHistoryPages(channel, {
+    pageLimit: wireLimit,
+    untilAttach: true,
+    logger,
+  });
+
+  const state: HistoryState = {
+    cursor,
+    rawMessages: [],
+    returnedCount: 0,
+    returnedRawCount: 0,
+    startedCodecMessageIds: new Set<string>(),
+    terminatedCodecMessageIds: new Set<string>(),
+    completedCodecMessageIds: new Set<string>(),
+    logger,
+  };
+
+  await fetchUntilLimit(state, limit);
+  return buildResult(state, limit);
+};

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

@@ -1,53 +1,68 @@
 /**
  * Pure stream piping function.
  *
- * Reads events from a ReadableStream, writes them to a streaming encoder,
- * and handles abort/error. No dependencies on turn state or transport internals.
+ * Reads outputs from a ReadableStream, writes them to an encoder via
+ * `publishOutput`, and handles cancel/error. No dependencies on run
+ * state or session internals.
  */
 
 import type { Logger } from '../../logger.js';
-import type { StreamEncoder, WriteOptions } from '../codec/types.js';
+import type { CodecInputEvent, CodecOutputEvent, Encoder, WriteOptions } from '../codec/types.js';
 import type { StreamResult } from './types.js';
 
 /**
- * Pipe an event stream through an encoder to the channel.
+ * Adapt an AbortSignal into a promise that resolves once the signal aborts,
+ * paired with a cleanup that detaches the listener. With no signal the promise
+ * never resolves (there is no cancellation path); an already-aborted signal
+ * resolves immediately. `cleanup` is a no-op unless a listener was attached.
+ * @param signal - The AbortSignal to watch, or undefined for no cancellation.
+ * @returns The abort promise and a cleanup to call when racing is done.
+ */
+const abortSignalToPromise = (signal: AbortSignal | undefined): { promise: Promise<void>; cleanup: () => void } => {
+  let listener: (() => void) | undefined;
+  const promise =
+    signal === undefined
+      ? // eslint-disable-next-line @typescript-eslint/no-empty-function -- never-resolving promise: no signal means no cancellation path
+        new Promise<void>(() => {})
+      : signal.aborted
+        ? Promise.resolve()
+        : new Promise<void>((resolve) => {
+            listener = () => {
+              resolve();
+            };
+            signal.addEventListener('abort', listener, { once: true });
+          });
+  const cleanup = (): void => {
+    if (listener && signal) signal.removeEventListener('abort', listener);
+  };
+  return { promise, cleanup };
+};
+
+/**
+ * Pipe an output stream through an encoder to the channel.
  *
  * Returns when the stream completes, is cancelled (via signal), or errors.
  * The `reason` field of the result indicates which case occurred.
- * @param stream - The event stream to read from.
- * @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 stream - The output stream to read from.
+ * @param encoder - The encoder to publish outputs through.
+ * @param signal - AbortSignal to monitor for cancellation.
+ * @param onCancelled - Optional callback invoked when the stream is cancelled, before the stream ends.
+ * @param resolveWriteOptions - Optional per-output hook returning {@link WriteOptions} overrides to pass to `encoder.publishOutput`.
  * @param logger - Optional logger for diagnostic output.
- * @returns The reason the pipe ended.
+ * @returns A {@link StreamResult}: `reason` is why the pipe ended, and `error` holds the caught error when `reason` is `'error'`.
  */
-export const pipeStream = async <TEvent, TMessage>(
-  stream: ReadableStream<TEvent>,
-  encoder: StreamEncoder<TEvent, TMessage>,
+export const pipeStream = async <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent>(
+  stream: ReadableStream<TOutput>,
+  encoder: Encoder<TInput, TOutput>,
   signal: AbortSignal | undefined,
-  onAbort?: (write: (event: TEvent) => Promise<void>) => void | Promise<void>,
-  resolveWriteOptions?: (event: TEvent) => WriteOptions | undefined,
+  onCancelled?: (write: (output: TOutput) => Promise<void>) => void | Promise<void>,
+  resolveWriteOptions?: (output: TOutput) => WriteOptions | undefined,
   logger?: Logger,
 ): Promise<StreamResult> => {
   logger?.trace('pipeStream();');
 
   const reader = stream.getReader();
-
-  let abortListener: (() => void) | undefined;
-  const abortPromise = signal
-    ? new Promise<void>((resolve) => {
-        if (signal.aborted) {
-          resolve();
-          return;
-        }
-        abortListener = () => {
-          resolve();
-        };
-        signal.addEventListener('abort', abortListener, { once: true });
-      })
-    : // eslint-disable-next-line @typescript-eslint/no-empty-function -- never-resolving promise: no signal means no cancellation path
-      new Promise<void>(() => {});
+  const abort = abortSignalToPromise(signal);
 
   let reason: StreamResult['reason'] = 'complete';
   let caughtError: Error | undefined;
@@ -55,28 +70,37 @@ export const pipeStream = async <TEvent, TMessage>(
   try {
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- intentional infinite loop broken by return/break
     while (true) {
-      // .then() is intentional: transforms the abort signal into a discriminant
+      // .then() is intentional: transforms the AbortSignal into a discriminant
       // for Promise.race — no async/await equivalent for this pattern.
-      const result = await Promise.race([reader.read(), abortPromise.then(() => 'aborted' as const)]);
+      const result = await Promise.race([reader.read(), abort.promise.then(() => 'cancelled' as const)]);
 
-      if (result === 'aborted') {
+      if (result === 'cancelled') {
         reason = 'cancelled';
-        logger?.debug('pipeStream(); stream cancelled by abort signal');
-        if (onAbort) {
-          await onAbort(async (event: TEvent) => encoder.appendEvent(event));
+        logger?.debug('pipeStream(); stream cancelled by AbortSignal');
+        if (onCancelled) {
+          await onCancelled(async (output: TOutput) => encoder.publishOutput(output));
         }
-        await encoder.abort('cancelled');
+        // Transport mechanics only — close in-flight streamed messages as
+        // cancelled. Run termination is the transport ai-run-end event,
+        // guaranteed by Run.pipe on a cancelled result.
+        await encoder.cancelStreams();
         break;
       }
 
       const { done, value } = result;
       if (done) {
+        // An agent-side self-abort (e.g. the AI SDK's abort signal firing)
+        // completes the stream without end chunks for in-flight streamed
+        // messages. Terminate any still-open wire streams with a cancelled
+        // status so decoders and history see a terminal; streams that closed
+        // normally are skipped (no-op on a clean completion).
+        await encoder.cancelStreams();
         await encoder.close();
         logger?.debug('pipeStream(); stream completed');
         break;
       }
 
-      await encoder.appendEvent(value, resolveWriteOptions?.(value));
+      await encoder.publishOutput(value, resolveWriteOptions?.(value));
     }
   } catch (error) {
     reason = 'error';
@@ -90,7 +114,7 @@ export const pipeStream = async <TEvent, TMessage>(
       // the StreamResult reason ("error").
     }
   } finally {
-    if (abortListener) signal?.removeEventListener('abort', abortListener);
+    abort.cleanup();
     reader.releaseLock();
   }