@ably/ai-transport 0.1.0 → 0.2.0

package/dist/core/transport/client-session.d.ts

@@ -0,0 +1,13 @@
+import { CodecInputEvent, CodecOutputEvent } from '../codec/types.js';
+import { ClientSession, ClientSessionOptions } from './types.js';
+/**
+ * Create a client-side session that manages conversation state over an Ably channel.
+ *
+ * The caller owns the client's lifecycle; the session owns its channel.
+ * The session is created in a not-yet-connected state — callers must
+ * `await session.connect()` before `send`, `regenerate`, `edit`, `update`,
+ * or `cancel`.
+ * @param options - Configuration for the client session.
+ * @returns A new {@link ClientSession} instance.
+ */
+export declare const createClientSession: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>(options: ClientSessionOptions<TInput, TOutput, TProjection, TMessage>) => ClientSession<TInput, TOutput, TProjection, TMessage>;

package/dist/core/transport/decode-fold.d.ts

@@ -0,0 +1,47 @@
+import { Codec, CodecInputEvent, CodecOutputEvent, Decoder } from '../codec/types.js';
+import { TreeInternal } from './tree.js';
+import { RunLifecycleEvent } from './types.js';
+/**
+ * Shared wire decode-and-apply engine.
+ *
+ * The client's live decode loop and the View's history replay both reconstruct
+ * the conversation Tree from the same raw Ably wire log. This module is the one
+ * place that classifies a wire message (run-lifecycle vs codec-decoded), parses
+ * or decodes it, and applies it to the Tree — so the two paths can never drift.
+ */
+import type * as Ably from 'ably';
+/**
+ * Apply one inbound wire message to the tree.
+ *
+ * Run-lifecycle messages are turned into a {@link RunLifecycleEvent} via
+ * {@link parseRunLifecycle} and applied with `applyRunLifecycle`; everything
+ * else is decoded with `decoder` and applied with `applyMessage`, skipping
+ * wire-only carriers that decode to no events and carry no run-id (the eventual
+ * reply run is created later by its run-start).
+ *
+ * Does NOT emit the tree's `ably-message` event — the caller owns that, because
+ * the live loop emits per message while history replay emits in a batch once
+ * the whole page is applied. Returns the parsed lifecycle event so a live
+ * caller can run its own side-effects (resolving a pending run-start,
+ * surfacing an agent error); returns `undefined` for a codec-decoded message
+ * or a lifecycle message that carried no run-id.
+ * @param tree - The tree to apply the message to.
+ * @param decoder - The codec decoder used for non-lifecycle messages.
+ * @param rawMsg - The inbound Ably wire message.
+ * @returns The parsed run-lifecycle event, or `undefined`.
+ */
+export declare const applyWireMessage: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection>(tree: TreeInternal<TInput, TOutput, TProjection>, decoder: Decoder<TInput, TOutput>, rawMsg: Ably.InboundMessage) => RunLifecycleEvent | undefined;
+/**
+ * Decode one wire message with `decoder` and fold its events into `projection`,
+ * returning the updated projection. Unlike {@link applyWireMessage} this builds
+ * a standalone projection rather than applying to a tree — used by the agent's
+ * conversation reconstruction. The caller owns the decoder so its streaming
+ * state can span the messages of a run, and chooses the reducer routing key.
+ * @param codec - The codec whose inherited Reducer `fold` method folds each decoded event into the projection.
+ * @param decoder - The caller-owned codec decoder (reused across a run's wires).
+ * @param projection - The projection to fold the message's events into.
+ * @param rawMsg - The wire message to decode and fold.
+ * @param messageId - The reducer routing key (codec-message-id) for this message.
+ * @returns The projection after folding all of the message's decoded events.
+ */
+export declare const foldMessageInto: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>(codec: Codec<TInput, TOutput, TProjection, TMessage>, decoder: Decoder<TInput, TOutput>, projection: TProjection, rawMsg: Ably.InboundMessage, messageId: string) => TProjection;

package/dist/core/transport/headers.d.ts

@@ -1,28 +1,106 @@
-/**
- * Transport header builder.
- *
- * Single source of truth for which `x-ably-*` headers every transport
- * message carries. Used by the server transport (addMessages, streamResponse)
- * and will be used by the client transport (optimistic message stamping).
- */
+import { EVENT_RUN_END, EVENT_RUN_RESUME, EVENT_RUN_START, EVENT_RUN_SUSPEND } from '../../constants.js';
+import { RunEndReason, RunLifecycleEvent } from './types.js';
 /**
  * Build the standard transport header set for a message.
  * @param opts - The header values to include.
  * @param opts.role - Message role (e.g. "user", "assistant").
- * @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).
- * @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.
+ * @param opts.runId - Run correlation ID, or `undefined` for a fresh client
+ *   input (the agent mints run-ids, so it is not known synchronously). Omitted
+ *   from the headers when undefined; a continuation still carries the known run-id.
+ * @param opts.codecMessageId - Message identity — the wire `codec-message-id` for this message.
+ * @param opts.runClientId - ClientId of the run initiator.
+ * @param opts.parent - Preceding message's codec-message-id (for branching).
+ * @param opts.forkOf - Forked user-prompt's codec-message-id (for edits — creates a Run-level fork sibling).
+ * @param opts.regenerates - Assistant codec-message-id this run regenerates. Stamps
+ *   `msg-regenerate`. Distinct from `forkOf`: regenerate is a
+ *   continuation of the prior run (no Run-level fork), with the message
+ *   replacement resolved at projection extraction time.
+ * @param opts.invocationId - Agent-minted invocation id. Stamped by the agent on every event it publishes for the invocation (run lifecycle + outputs) so the client can observe it; not set by the client on the input.
+ * @param opts.inputClientId - ClientId of the input event (the `ai-input`) that
+ *   drove the current invocation. The agent reads it from the publisher's
+ *   Ably-level `clientId` on the matched input event and re-stamps it on its
+ *   own publishes (run lifecycle + outputs). Differs from `runClientId` on
+ *   continuation invocations driven by an input from a non-owner.
+ * @param opts.inputEventId - Per-event identifier. Set on each client-published user-prompt message; the invocation body's `inputEventIds` lists the ids the agent should look up.
+ * @param opts.inputCodecMessageId - The codec-message-id of the input event that
+ *   triggered the current invocation (the one whose `event-id` matched the
+ *   invocation's `inputEventId`). The agent re-stamps it on every event it
+ *   publishes for the invocation (run lifecycle + outputs), mirroring
+ *   `inputClientId`, so the client can correlate any of those events back to
+ *   the originating input by the id it owned at send time.
+ * @returns A headers record with the transport headers set.
  */
 export declare const buildTransportHeaders: (opts: {
     role: string;
-    turnId: string;
-    msgId: string;
-    turnClientId?: string;
+    runId?: string;
+    codecMessageId: string;
+    runClientId?: string;
+    parent?: string;
+    forkOf?: string;
+    regenerates?: string;
+    invocationId?: string;
+    inputClientId?: string;
+    inputCodecMessageId?: string;
+    inputEventId?: string;
+}) => Record<string, string>;
+/**
+ * Build the transport header set for a run-lifecycle event (run-start,
+ * run-resume, run-suspend, run-end). Single source of truth for lifecycle
+ * header stamping, mirroring {@link buildTransportHeaders} for the
+ * message-carrier path. Every field except `runId`/`runClientId` is optional
+ * and omitted when not provided.
+ *
+ * A resume suppresses the structural `parent` / `forkOf` / `regenerates`
+ * headers — the caller passes them only for a fresh run-start. `reason` is
+ * stamped only on run-end.
+ * @param opts - The lifecycle header values to include.
+ * @param opts.runId - The run's id.
+ * @param opts.runClientId - ClientId of the run initiator (empty string when unknown).
+ * @param opts.parent - Structural parent codec-message-id (fresh run-start only).
+ * @param opts.forkOf - Forked user-prompt codec-message-id (fresh run-start only).
+ * @param opts.regenerates - Regenerated assistant codec-message-id (fresh run-start only).
+ * @param opts.invocationId - Agent-minted invocation id; carried on every lifecycle event.
+ * @param opts.inputClientId - ClientId of the triggering input event.
+ * @param opts.inputCodecMessageId - Codec-message-id of the triggering input event.
+ * @param opts.reason - Terminal reason; stamped on run-end only.
+ * @returns A headers record with the lifecycle headers set.
+ */
+export declare const buildLifecycleHeaders: (opts: {
+    runId: string;
+    runClientId: string;
     parent?: string;
     forkOf?: string;
-    amend?: string;
+    regenerates?: string;
+    invocationId?: string;
+    inputClientId?: string;
+    inputCodecMessageId?: string;
+    reason?: RunEndReason;
 }) => Record<string, string>;
+/** The four run-lifecycle Ably message names. */
+type RunLifecycleName = typeof EVENT_RUN_START | typeof EVENT_RUN_SUSPEND | typeof EVENT_RUN_RESUME | typeof EVENT_RUN_END;
+/**
+ * Whether an Ably message `name` is one of the run-lifecycle event names
+ * (run-start / run-suspend / run-resume / run-end). Single source of truth for
+ * the classification both decode loops and the agent's history scan use to
+ * route lifecycle wires away from the codec decoder. Narrows `name` to a
+ * lifecycle name so callers can pass it straight to {@link parseRunLifecycle}.
+ * @param name - The inbound Ably message `name`, or undefined.
+ * @returns True when `name` is a run-lifecycle event name.
+ */
+export declare const isRunLifecycleName: (name: string | undefined) => name is RunLifecycleName;
+/**
+ * Parse an inbound run-lifecycle Ably message into a {@link RunLifecycleEvent}.
+ *
+ * Single source of truth for turning the wire run-lifecycle message `name`,
+ * transport headers, and channel serial into the structured lifecycle event
+ * the Tree consumes. Used by the client decode loop (live) and the View's
+ * history replay so both build the event identically.
+ * @param name - The inbound Ably message `name`.
+ * @param headers - Transport headers from the inbound Ably message.
+ * @param serial - Ably channel serial of the message, or `undefined` for an
+ *   optimistic local event. Stamped onto the returned event.
+ * @returns The lifecycle event, or `undefined` when `name` is not a
+ *   run-lifecycle event name or the message carries no `run-id`.
+ */
+export declare const parseRunLifecycle: (name: string, headers: Record<string, string>, serial: string | undefined) => RunLifecycleEvent | undefined;
+export {};

package/dist/core/transport/index.d.ts

@@ -1,7 +1,6 @@
-export type { ActiveTurn, AddMessageOptions, AddMessagesResult, CancelFilter, CancelRequest, ClientTransport, ClientTransportOptions, CloseOptions, EventsNode, MessageNode, NewTurnOptions, SendOptions, ServerTransport, ServerTransportOptions, StreamResponseOptions, StreamResult, Tree, Turn, TurnEndReason, TurnLifecycleEvent, View, } from './types.js';
-export type { EventNode } from './types.js';
-export type { TreeNode } from './types.js';
-export type { TreeInternal } from './tree.js';
-export { createServerTransport } from './server-transport.js';
-export { createClientTransport } from './client-transport.js';
+export type { ActiveRun, AgentSession, AgentSessionOptions, BranchSelection, CancelRequest, ClientSession, ClientSessionOptions, ConversationNode, EventsNode, InputNode, LoadConversationOptions, MessageNode, OutputEvent, PipeOptions, Run, RunEndReason, RunInfo, RunLifecycleEvent, RunNode, RunRuntime, RunView, SendOptions, StreamResult, Tree, View, } from './types.js';
+export type { InvocationData } from './invocation.js';
+export { Invocation } from './invocation.js';
+export { createAgentSession } from './agent-session.js';
+export { createClientSession } from './client-session.js';
 export { buildTransportHeaders } from './headers.js';

package/dist/core/transport/internal/bounded-map.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Helpers for FIFO-bounded `Map`s — Maps used as capacity-limited buffers that
+ * must evict their oldest entry when full.
+ */
+/**
+ * Make room for a new key in a FIFO-bounded map: if `map` is at (or over)
+ * `limit` and does not already contain `key`, evict the oldest entry (insertion
+ * order) and return its key so the caller can log the eviction. Returns
+ * `undefined` when nothing was evicted (the key already exists, the map is
+ * below the limit, or it is empty).
+ *
+ * The caller performs the actual set/append afterwards — this only frees a
+ * slot — so it works for maps whose values are replaced and for maps whose
+ * values are appended-to lists.
+ * @param map - The bounded map to evict from.
+ * @param key - The key about to be added; an existing key never evicts.
+ * @param limit - The maximum number of entries the map may hold.
+ * @returns The evicted key, or `undefined` if nothing was evicted.
+ */
+export declare const evictOldestIfFull: <K, V>(map: Map<K, V>, key: K, limit: number) => K | undefined;

package/dist/core/transport/invocation.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Invocation — value object wrapping the JSON body that a client sends to
+ * an agent's HTTP endpoint to start a run.
+ *
+ * The data shape is the wire contract; the {@link Invocation} class is a
+ * runtime view of that data with the same fields. {@link Invocation.fromJSON}
+ * is the entry point used by agent handlers:
+ *
+ * ```ts
+ * const data = (await req.json()) as InvocationData;
+ * const invocation = Invocation.fromJSON(data);
+ * const run = session.createRun(invocation, { signal: req.signal });
+ * await run.start();
+ * await run.loadProjection(); // fetch run projection from the channel
+ * const messages = run.messages;
+ * ```
+ *
+ * The body carries only what the agent needs out-of-band before the channel
+ * is observable: the session/channel name and the `inputEventId` that triggered
+ * the invocation. The agent mints the `invocationId` itself (one per HTTP
+ * request) and returns it on the HTTP response, so it is not a body field. Run
+ * identity also lives on the channel: the agent mints the `runId` for a fresh
+ * run and reads the existing `runId` off the triggering input event for a
+ * continuation — so the body carries no run-id either. Per-message metadata —
+ * `clientId`, `parent`, `forkOf`, continuation status — likewise lives on the
+ * channel and is resolved by the agent from the triggering input event, not
+ * from the body. The `inputClientId` the agent re-stamps on its own publishes
+ * comes from the publisher's Ably `clientId` on the matched input event, not
+ * from a body field.
+ */
+/**
+ * Wire shape of a single invocation — the JSON body sent from the client
+ * transport's HTTP POST to the agent endpoint.
+ */
+export interface InvocationData {
+    /**
+     * Identifier for the specific input event on the channel that triggered
+     * this invocation. The agent locates the event via the `event-id`
+     * header. Its wire headers carry the run-id for a continuation (absent for
+     * a fresh run), so run identity is resolved from the channel, not the body.
+     */
+    inputEventId: string;
+    /** Logical name of the session (chat) — used as the Ably channel name. */
+    sessionName: string;
+}
+/**
+ * Runtime view of an {@link InvocationData}. Constructed via
+ * {@link Invocation.fromJSON}. Read-only; carries no behaviour beyond
+ * exposing its fields.
+ */
+export declare class Invocation {
+    /**
+     * Identifier for the specific input event on the channel that triggered
+     * this invocation. Run identity is resolved from that event's wire headers
+     * (or minted), not from the body.
+     */
+    readonly inputEventId: string;
+    /** Logical name of the session (chat). Used as the Ably channel name. */
+    readonly sessionName: string;
+    private constructor();
+    /**
+     * Build an Invocation from its JSON wire shape.
+     * @param data - Parsed JSON body matching {@link InvocationData}.
+     * @returns A new Invocation exposing the same fields.
+     */
+    static fromJSON(data: InvocationData): Invocation;
+    /**
+     * Serialise this invocation to its JSON wire shape — the body a client
+     * POSTs to the agent's endpoint to wake a run. Round-trips through
+     * {@link Invocation.fromJSON}.
+     * @returns The {@link InvocationData} carrying this invocation's identity.
+     */
+    toJSON(): InvocationData;
+}

package/dist/core/transport/load-conversation.d.ts

@@ -0,0 +1,128 @@
+import { Logger } from '../../logger.js';
+import { Codec, CodecInputEvent, CodecOutputEvent } from '../codec/types.js';
+/**
+ * Agent-side conversation reconstruction from the channel wire log.
+ *
+ * When an agent wakes (or resumes) it has no in-memory tree — it rebuilds the
+ * state it needs by paging channel history and folding the wires through the
+ * codec. Two entry points:
+ *
+ * - {@link loadRunProjection} — fold a single run's wires into one projection
+ *   (used to resume a suspended run with its client tool-output amends).
+ * - {@link loadConversation} — walk the structural parent chain from the
+ *   current run's input node to the root and fold each node, producing the full
+ *   multi-turn message history along the taken branch.
+ *
+ * Both reuse {@link foldMessageInto} (the shared per-message fold primitive) and
+ * {@link buildBranchChain} (the shared parent-chain walk), so the agent's
+ * reconstruction can't drift from the client/View decode paths.
+ */
+import * as Ably from 'ably';
+/**
+ * Merge messages observed live (e.g. by the input-event lookup) into a set of
+ * collected history messages, dedup by serial, and sort chronologically.
+ *
+ * History messages take priority in deduplication (history serial wins if the
+ * same message appears in both). Messages without a serial are dropped because
+ * they cannot be reliably ordered.
+ * @param collected - Raw messages from channel.history (any order).
+ * @param live - Messages observed live (e.g. by the input-event lookup); may be undefined.
+ * @returns Deduplicated, chronologically sorted messages.
+ */
+export declare const withLiveMessages: (collected: readonly Ably.InboundMessage[], live?: readonly Ably.InboundMessage[]) => Ably.InboundMessage[];
+/**
+ * Fold a pre-sorted array of wire messages for a single run into a projection.
+ *
+ * Skips lifecycle events (they carry no codec content) and stops before the
+ * message whose `codec-message-id` equals `truncateAt` (exclusive — that
+ * message is not folded). Used by both {@link loadRunProjection} (no
+ * truncation) and {@link loadConversation} (per-ancestor folding).
+ * @param codec - Codec used to decode and fold events.
+ * @param sortedMessages - Chronologically ordered wire messages (all runs).
+ * @param runId - Only messages stamped with this run-id are folded.
+ * @param truncateAt - Stop before this codec-message-id; omit to fold all messages.
+ * @returns The projection and the count of messages that were folded.
+ */
+export declare const foldRunMessages: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>(codec: Codec<TInput, TOutput, TProjection, TMessage>, sortedMessages: readonly Ably.InboundMessage[], runId: string, truncateAt?: string) => {
+    projection: TProjection;
+    folded: number;
+};
+/**
+ * Fold a single run-less INPUT node's events into a fresh projection: every
+ * wire stamped with `codecMessageId` and NO run-id (the user prompt the client
+ * published before the agent minted a run-id). The two-node analogue of
+ * {@link foldRunMessages} for the user-input side of the conversation chain.
+ * @param codec - Codec used to decode and fold events.
+ * @param sortedMessages - Chronologically ordered wire messages (all runs).
+ * @param codecMessageId - The input node's codec-message-id.
+ * @returns The folded projection for that input node.
+ */
+export declare const foldInputMessages: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>(codec: Codec<TInput, TOutput, TProjection, TMessage>, sortedMessages: readonly Ably.InboundMessage[], codecMessageId: string) => TProjection;
+/**
+ * Fetch all messages on the channel that belong to `runId`, decode them
+ * through the codec, and fold them into a single projection. Used by the agent
+ * to reconstruct a run's full state — including client-published tool-output
+ * amends — when resuming a suspended run in a fresh agent session.
+ *
+ * Doesn't require channel rewind: an explicit `channel.history()` call returns
+ * the same data even if the channel is already attached from a prior session.
+ * @param opts - Load parameters.
+ * @param opts.channel - The Ably channel to read history from.
+ * @param opts.codec - Codec used to decode and fold events.
+ * @param opts.runId - Run identifier whose events should be folded.
+ * @param opts.signal - AbortSignal checked once at entry: if already aborted the call throws immediately and no history is fetched. It does not interrupt an in-flight load.
+ * @param opts.logger - Optional logger for diagnostic output.
+ * @param opts.liveMessages - Raw Ably messages already observed live (e.g. by
+ *   the input-event lookup). Folded alongside the history fetch so just-published
+ *   client wires don't depend on Ably's history-indexing window.
+ * @returns The projection produced by folding all run events in serial order.
+ * @throws {Ably.ErrorInfo} with code ErrorCode.InvalidArgument if `signal` is already aborted at entry (the run was cancelled before loading began).
+ */
+export declare const loadRunProjection: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>(opts: {
+    channel: Ably.RealtimeChannel;
+    codec: Codec<TInput, TOutput, TProjection, TMessage>;
+    runId: string;
+    signal: AbortSignal;
+    logger: Logger | undefined;
+    liveMessages?: readonly Ably.InboundMessage[];
+}) => Promise<TProjection>;
+/**
+ * Reconstruct the full multi-turn conversation history along the branch the
+ * current run sits on.
+ *
+ * Pages channel history (merging live lookup messages), indexes each
+ * codec-message-id's structural parent and run-id with sticky identity (the
+ * first wire wins; later amends can't poison it), backfills a reply run's
+ * parent from its `ai-run-start` when the output wire wasn't indexed, then
+ * walks the structural parent chain from the current run's input node
+ * (`assistantParentFallback`) to the root and folds each node in chain order.
+ * The current run is folded once, wholesale, at the tail.
+ * @param opts - Reconstruction parameters.
+ * @param opts.channel - The Ably channel to read history from.
+ * @param opts.codec - Codec used to decode and fold events.
+ * @param opts.runId - The current run's id.
+ * @param opts.signal - AbortSignal checked once at entry; if already aborted the call throws before any history is fetched. It does not interrupt an in-flight load.
+ * @param opts.logger - Optional logger for diagnostic output.
+ * @param opts.liveMessages - Wires already observed live, merged into history.
+ * @param opts.assistantParentFallback - The current run's input node
+ *   (codec-message-id) — the anchor the parent-chain walk starts from. When
+ *   undefined, only the current run is folded.
+ * @param opts.pageLimit - Messages requested per history page.
+ * @param opts.maxMessages - Stop paging once this many messages are collected.
+ * @returns The branch's messages (root-first) and the current run's projection.
+ * @throws {Ably.ErrorInfo} with code ErrorCode.InvalidArgument when `signal` is already aborted at entry.
+ */
+export declare const loadConversation: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>(opts: {
+    channel: Ably.RealtimeChannel;
+    codec: Codec<TInput, TOutput, TProjection, TMessage>;
+    runId: string;
+    signal: AbortSignal;
+    logger: Logger | undefined;
+    liveMessages: readonly Ably.InboundMessage[] | undefined;
+    assistantParentFallback: string | undefined;
+    pageLimit: number;
+    maxMessages: number;
+}) => Promise<{
+    messages: TMessage[];
+    projection: TProjection;
+}>;

package/dist/core/transport/load-history.d.ts

@@ -0,0 +1,39 @@
+import { Logger } from '../../logger.js';
+import { HistoryPage, LoadHistoryOptions } from './types.js';
+/**
+ * loadHistory — load conversation history from an Ably channel and return
+ * the raw wire 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.
+ *
+ * The `limit` option controls the number of complete **messages** per page,
+ * not the number of Ably wire 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.
+ */
+import type * as Ably from 'ably';
+/**
+ * Load conversation history from a channel and return the raw wire 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.
+ *
+ * The `limit` option controls the number of complete messages
+ * returned per page, not the number of Ably wire 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.
+ */
+export declare const loadHistory: (channel: Ably.RealtimeChannel, options: LoadHistoryOptions | undefined, logger: Logger) => Promise<HistoryPage>;

package/dist/core/transport/pipe-stream.d.ts

@@ -1,17 +1,17 @@
 import { Logger } from '../../logger.js';
-import { StreamEncoder, WriteOptions } from '../codec/types.js';
+import { CodecInputEvent, CodecOutputEvent, Encoder, WriteOptions } from '../codec/types.js';
 import { StreamResult } from './types.js';
 /**
- * Pipe an event stream through an encoder to the channel.
+ * 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 declare const pipeStream: <TEvent, TMessage>(stream: ReadableStream<TEvent>, 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>;
+export declare const pipeStream: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent>(stream: ReadableStream<TOutput>, encoder: Encoder<TInput, TOutput>, signal: AbortSignal | undefined, onCancelled?: (write: (output: TOutput) => Promise<void>) => void | Promise<void>, resolveWriteOptions?: (output: TOutput) => WriteOptions | undefined, logger?: Logger) => Promise<StreamResult>;

package/dist/core/transport/run-manager.d.ts

@@ -0,0 +1,78 @@
+import { Logger } from '../../logger.js';
+import { RunEndReason } from './types.js';
+/**
+ * Server-side run state management and lifecycle event publishing.
+ *
+ * Owns the authoritative run lifecycle. Tracks active runs with their
+ * AbortControllers and clientIds. Publishes run-start, run-resume, run-suspend, and
+ * run-end events on the Ably channel so all clients can react to run
+ * state changes.
+ */
+import type * as Ably from 'ably';
+/**
+ * Per-invocation metadata carried on a run's opening lifecycle event. A
+ * continuation (re-entering an existing run) sets `continuation` and omits the
+ * structural `parent` / `forkOf` / `regenerates` fields.
+ */
+export 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). */
+    forkOf?: string;
+    /** Regenerated assistant codec-message-id (fresh run-start only). */
+    regenerates?: string;
+    /** Agent-minted invocation id, carried on the lifecycle event. */
+    invocationId?: string;
+    /** ClientId of the triggering input event. */
+    inputClientId?: string;
+    /** Codec-message-id of the triggering input event. */
+    inputCodecMessageId?: string;
+    /** When true, publish `ai-run-resume` (re-entry) instead of `ai-run-start`. */
+    continuation?: boolean;
+}
+/** Manages active runs and publishes run lifecycle events on the channel. */
+export interface RunManager {
+    /**
+     * Register a run and publish its opening lifecycle event. Publishes
+     * `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.
+     */
+    startRun(runId: string, clientId?: string, controller?: AbortController, metadata?: StartRunMetadata): Promise<AbortSignal>;
+    /**
+     * 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
+     * live AbortController to retain. A cancel arriving during suspension is a
+     * no-op; the resuming invocation re-registers the run via {@link startRun}.
+     * Carries the same per-invocation attribution as {@link endRun}
+     * (`inputClientId`, `inputCodecMessageId`), since a suspend is the terminal
+     * event of the suspending invocation just as run-end is of an ending one.
+     */
+    suspendRun(runId: string, invocationId?: string, inputClientId?: string, inputCodecMessageId?: string): Promise<void>;
+    /**
+     * End a run. Publishes run-end on the channel (stamping `reason` as the
+     * 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.
+     */
+    endRun(runId: string, reason: RunEndReason, invocationId?: string, inputClientId?: string, inputCodecMessageId?: string): 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;
+}
+/**
+ * Create a run manager bound to the given channel.
+ * @param channel - The Ably channel to publish lifecycle events on.
+ * @param logger - Optional logger for diagnostic output.
+ * @returns A new {@link RunManager} instance.
+ */
+export declare const createRunManager: (channel: Ably.RealtimeChannel, logger?: Logger) => RunManager;