@ably/ai-transport 0.2.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

@@ -1,23 +1,25 @@
 /**
  * loadHistory — load conversation history from an Ably channel and return
- * the raw wire messages as a paginated HistoryPage result.
+ * the raw Ably messages as a paginated HistoryPage result.
  *
- * This does NOT decode: it pages back through Ably history 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 decoder never runs here.
+ * 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 wire messages fetched. A message is complete when
+ * 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.
+ * `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';
@@ -25,6 +27,7 @@ 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';
 
 // ---------------------------------------------------------------------------
@@ -32,6 +35,8 @@ import type { HistoryPage, LoadHistoryOptions } from './types.js';
 // ---------------------------------------------------------------------------
 
 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[];
   /**
@@ -43,14 +48,12 @@ interface HistoryState {
   returnedCount: number;
   /** How many raw Ably messages have been served to the consumer so far. */
   returnedRawCount: number;
-  /** The last Ably page cursor for continued pagination. */
-  lastAblyPage: Ably.PaginatedResult<Ably.InboundMessage> | undefined;
   /**
    * `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 wire message).
+   * message, created and terminated in one Ably message).
    */
   startedCodecMessageIds: Set<string>;
   /**
@@ -80,7 +83,7 @@ interface HistoryState {
  *
  * 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 wire
+ *   (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).
@@ -104,7 +107,7 @@ interface HistoryState {
  * - Missing `codec-message-id`: lifecycle events not tied to a domain message.
  * - `message.delete`: clears the tracker, doesn't produce output.
  *
- * Amend-class wire messages (events targeting an existing message via
+ * 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.
  *
@@ -142,39 +145,30 @@ const countNewCompletions = (state: HistoryState, newMessages: readonly Ably.Inb
 };
 
 // ---------------------------------------------------------------------------
-// Fetch Ably pages until we have enough completed messages
+// Pull pages from the shared iterator until we have enough completions
 // ---------------------------------------------------------------------------
 
 /**
- * Fetch Ably history pages until we have enough completed messages.
+ * Pull chunks from the shared {@link loadHistoryPages} iterator until enough
+ * completed messages have been collected (target = already-returned +
+ * `limit`) or the iterator is exhausted.
  *
- * The loop uses {@link countNewCompletions} - a cheap O(new messages) header
- * scan - to decide when to stop, rather than running the decoder per page.
+ * 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 ablyPage - The current Ably paginated result to start from.
  * @param limit - Target number of completed messages beyond what has already been returned.
  */
-const fetchUntilLimit = async (
-  state: HistoryState,
-  ablyPage: Ably.PaginatedResult<Ably.InboundMessage>,
-  limit: number,
-): Promise<void> => {
-  state.rawMessages.push(...ablyPage.items);
-  state.lastAblyPage = ablyPage;
-  countNewCompletions(state, ablyPage.items);
-
+const fetchUntilLimit = async (state: HistoryState, limit: number): Promise<void> => {
   const target = state.returnedCount + limit;
-  while (state.completedCodecMessageIds.size < target && ablyPage.hasNext()) {
-    state.logger.debug('loadHistory.fetchUntilLimit(); fetching next page', {
+  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 nextPage = await ablyPage.next();
-    if (!nextPage) break;
-    ablyPage = nextPage;
-    state.rawMessages.push(...nextPage.items);
-    state.lastAblyPage = nextPage;
-    countNewCompletions(state, nextPage.items);
+    const chunk = await state.cursor.next();
+    if (!chunk) break;
+    state.rawMessages.push(...chunk);
+    countNewCompletions(state, chunk);
   }
 };
 
@@ -183,7 +177,7 @@ const fetchUntilLimit = async (
 // ---------------------------------------------------------------------------
 
 /**
- * Build a HistoryPage of raw wire messages from the current fetch 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.
@@ -191,13 +185,13 @@ const fetchUntilLimit = async (
 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 wires fetched since the previous page (empty for buffered pages).
+  // 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 moreAblyPages = state.lastAblyPage?.hasNext() ?? false;
+  const moreFromCursor = state.cursor.hasNext();
 
   // Raw Ably messages for this page in chronological order (oldest first).
   const newRawCount = state.rawMessages.length - state.returnedRawCount;
@@ -206,15 +200,13 @@ const buildResult = (state: HistoryState, limit: number): HistoryPage => {
 
   return {
     rawMessages,
-    hasNext: () => moreCompleted || moreAblyPages,
+    hasNext: () => moreCompleted || moreFromCursor,
     next: async () => {
       if (moreCompleted) {
         return buildResult(state, limit);
       }
-      if (!moreAblyPages || !state.lastAblyPage) return;
-      const nextAbly = await state.lastAblyPage.next();
-      if (!nextAbly) return;
-      await fetchUntilLimit(state, nextAbly, limit);
+      if (!moreFromCursor) return;
+      await fetchUntilLimit(state, limit);
       return buildResult(state, limit);
     },
   };
@@ -225,14 +217,17 @@ const buildResult = (state: HistoryState, limit: number): HistoryPage => {
 // ---------------------------------------------------------------------------
 
 /**
- * Load conversation history from a channel and return the raw wire messages.
+ * Load conversation history from a channel and return the raw Ably messages.
  *
- * Attaches the channel if not already attached, then calls
- * `channel.history({ untilAttach: true })` to guarantee no gap between
- * historical and live messages. The attach is idempotent.
+ * 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 wire messages fetched.
+ * 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.
@@ -245,25 +240,32 @@ export const loadHistory = async (
   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,
-    lastAblyPage: undefined,
     startedCodecMessageIds: new Set<string>(),
     terminatedCodecMessageIds: new Set<string>(),
     completedCodecMessageIds: new Set<string>(),
     logger,
   };
 
-  logger.trace('loadHistory();', { limit });
-
-  // Request more Ably messages than the domain limit to account for
-  // the many-to-one ratio (multiple wire messages per message).
-  const wireLimit = limit * 10;
-
-  await channel.attach();
-  const ablyPage = await channel.history({ untilAttach: true, limit: wireLimit });
-  await fetchUntilLimit(state, ablyPage, limit);
+  await fetchUntilLimit(state, limit);
   return buildResult(state, limit);
 };

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

@@ -80,12 +80,21 @@ export const pipeStream = async <TInput extends CodecInputEvent, TOutput extends
         if (onCancelled) {
           await onCancelled(async (output: TOutput) => encoder.publishOutput(output));
         }
-        await encoder.cancel('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;

package/src/core/transport/run-manager.ts

@@ -19,7 +19,7 @@ import type { RunEndReason } from './types.js';
  * continuation (re-entering an existing run) sets `continuation` and omits the
  * structural `parent` / `forkOf` / `regenerates` fields.
  */
-export interface StartRunMetadata {
+interface StartRunMetadata {
   /** Structural parent codec-message-id (fresh run-start only). */
   parent?: string;
   /** Forked user-prompt codec-message-id for an edit (fresh run-start only). */
@@ -47,14 +47,9 @@ export interface RunManager {
    * `ai-run-start` for a fresh run, or `ai-run-resume` when `metadata.continuation`
    * is set (a subsequent invocation re-entering an existing run). A resume omits
    * the structural `parent` / `forkOf` / `regenerates` headers — the original
-   * run-start owns the run's structure. Returns the run's AbortSignal.
+   * run-start owns the run's structure.
    */
-  startRun(
-    runId: string,
-    clientId?: string,
-    controller?: AbortController,
-    metadata?: StartRunMetadata,
-  ): Promise<AbortSignal>;
+  startRun(runId: string, clientId?: string, controller?: AbortController, metadata?: StartRunMetadata): Promise<void>;
   /**
    * Suspend a run. Publishes run-suspend on the channel and drops the run's
    * active-run entry — the agent process terminates on suspend, so there is no
@@ -70,7 +65,10 @@ export interface RunManager {
    * run-reason header) and drops the run's active-run entry. Carries the same
    * per-invocation attribution as {@link suspendRun} (`invocationId`,
    * `inputClientId`, `inputCodecMessageId`), since run-end is the terminal event
-   * of the ending invocation.
+   * of the ending invocation. When `reason` is `'error'` and an `error` is
+   * supplied, its `code` and `message` are additionally stamped as the
+   * `error-code` / `error-message` headers — a codec-agnostic baseline failure
+   * detail for consumers; omitting `error` publishes a bare `reason: 'error'`.
    */
   endRun(
     runId: string,
@@ -78,15 +76,10 @@ export interface RunManager {
     invocationId?: string,
     inputClientId?: string,
     inputCodecMessageId?: string,
+    error?: Ably.ErrorInfo,
   ): Promise<void>;
-  /** Get the AbortSignal for a run. */
-  getSignal(runId: string): AbortSignal | undefined;
   /** Get the clientId that owns a run. */
   getClientId(runId: string): string | undefined;
-  /** Fire the AbortSignal for a run to cancel any in-flight work. */
-  cancel(runId: string): void;
-  /** Get all active run IDs. */
-  getActiveRunIds(): string[];
   /** Cancel all active runs and clear state. */
   close(): void;
 }
@@ -119,7 +112,7 @@ class DefaultRunManager implements RunManager {
     clientId?: string,
     externalController?: AbortController,
     metadata?: StartRunMetadata,
-  ): Promise<AbortSignal> {
+  ): Promise<void> {
     this._logger?.trace('DefaultRunManager.startRun();', { runId, clientId });
 
     const controller = externalController ?? new AbortController();
@@ -153,7 +146,6 @@ class DefaultRunManager implements RunManager {
     });
 
     this._logger?.debug('DefaultRunManager.startRun(); run started', { runId });
-    return controller.signal;
   }
 
   async suspendRun(
@@ -173,9 +165,20 @@ class DefaultRunManager implements RunManager {
     invocationId?: string,
     inputClientId?: string,
     inputCodecMessageId?: string,
+    error?: Ably.ErrorInfo,
   ): Promise<void> {
     this._logger?.trace('DefaultRunManager.endRun();', { runId, reason });
-    await this._publishTerminal(EVENT_RUN_END, runId, { reason, invocationId, inputClientId, inputCodecMessageId });
+    // Stamp error detail only for a terminal error the agent chose to surface
+    // (AIT-ST6b4: explicit, never automatic). error-code / error-message are
+    // generic transport headers, so any codec or consumer can read them.
+    const errorAttribution = reason === 'error' && error ? { errorCode: error.code, errorMessage: error.message } : {};
+    await this._publishTerminal(EVENT_RUN_END, runId, {
+      reason,
+      invocationId,
+      inputClientId,
+      inputCodecMessageId,
+      ...errorAttribution,
+    });
     this._logger?.debug('DefaultRunManager.endRun(); run ended', { runId, reason });
   }
 
@@ -192,6 +195,8 @@ class DefaultRunManager implements RunManager {
    * @param attribution.invocationId - The invocation's id.
    * @param attribution.inputClientId - ClientId of the triggering input event.
    * @param attribution.inputCodecMessageId - Codec-message-id of the triggering input event.
+   * @param attribution.errorCode - Numeric error code; set for run-end only when a terminal error is surfaced.
+   * @param attribution.errorMessage - Error message; paired with errorCode.
    */
   private async _publishTerminal(
     eventName: string,
@@ -201,6 +206,8 @@ class DefaultRunManager implements RunManager {
       invocationId?: string;
       inputClientId?: string;
       inputCodecMessageId?: string;
+      errorCode?: number;
+      errorMessage?: string;
     },
   ): Promise<void> {
     const resolvedClientId = this._activeRuns.get(runId)?.clientId ?? '';
@@ -209,23 +216,10 @@ class DefaultRunManager implements RunManager {
     this._activeRuns.delete(runId);
   }
 
-  getSignal(runId: string): AbortSignal | undefined {
-    return this._activeRuns.get(runId)?.controller.signal;
-  }
-
   getClientId(runId: string): string | undefined {
     return this._activeRuns.get(runId)?.clientId;
   }
 
-  cancel(runId: string): void {
-    this._logger?.debug('DefaultRunManager.cancel();', { runId });
-    this._activeRuns.get(runId)?.controller.abort();
-  }
-
-  getActiveRunIds(): string[] {
-    return [...this._activeRuns.keys()];
-  }
-
   close(): void {
     this._logger?.trace('DefaultRunManager.close();', { activeRuns: this._activeRuns.size });
     for (const state of this._activeRuns.values()) {