@ably/ai-transport 0.1.0 → 0.3.0

package/dist/core/transport/types/agent.d.ts

@@ -0,0 +1,375 @@
+import { Logger } from '../../../logger.js';
+import { Codec, CodecInputEvent, CodecOutputEvent, WriteOptions } from '../../codec/types.js';
+import { Invocation } from '../invocation.js';
+import { CancelRequest, RunEndReason } from './shared.js';
+import { MessageNode, Tree } from './tree.js';
+/** Agent (server-side) session types: options, run runtime, and the Run / AgentSession contracts. */
+import type * as Ably from 'ably';
+import type * as AblyObjects from 'ably/liveobjects';
+/** Options for creating an agent session. */
+export interface AgentSessionOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /**
+     * The Ably Realtime client. The caller owns its lifecycle —
+     * `session.close()` does not close the client.
+     */
+    client: Ably.Realtime;
+    /**
+     * The name of the channel to publish to. The session owns this channel —
+     * do not also resolve it elsewhere with conflicting channel options.
+     */
+    channelName: string;
+    /** The codec to use for encoding events and messages. */
+    codec: Codec<TInput, TOutput, TProjection, TMessage>;
+    /** Logger instance for diagnostic output. */
+    logger?: Logger;
+    /**
+     * Called with non-fatal session-level errors not scoped to any run.
+     * Examples: cancel listener subscription failure, channel attach errors,
+     * channel continuity loss (FAILED/SUSPENDED/DETACHED or re-attach with
+     * `resumed: false`).
+     */
+    onError?: (error: Ably.ErrorInfo) => void;
+    /**
+     * How long `Run.start()` will wait for the input event(s) tagged with
+     * the run's `invocationId` to arrive on the channel — across both the
+     * post-attach live subscription and the bounded history scan — before
+     * rejecting with `InputEventNotFound`. The rejection bubbles up to the
+     * developer's HTTP handler, which should surface it as a non-2xx response
+     * so the client's pending send fails.
+     * Default: 30000 (30 seconds).
+     */
+    inputEventLookupTimeoutMs?: number;
+    /**
+     * How far back in time `Run.start()` scans channel history for the
+     * triggering input event. Implements the lookback bound for the
+     * input-event scan — anything older than `Date.now() - inputEventLookbackMs`
+     * is treated as outside the lookup window.
+     *
+     * History is fetched with `untilAttach: true` so the scan composes
+     * with the live subscription by serial boundary — together they cover
+     * every message within `inputEventLookbackMs` of attach.
+     *
+     * Increase this for long-suspended runs whose continuation may arrive
+     * many minutes after the original publish. Decrease it for stricter
+     * recency.
+     *
+     * Default: 120000 (2 minutes).
+     */
+    inputEventLookbackMs?: number;
+    /**
+     * Extra Ably channel modes to request on the session's channel, on top of the
+     * modes AI Transport always needs. Pass `OBJECT_MODES` (or
+     * `['OBJECT_SUBSCRIBE', 'OBJECT_PUBLISH']`) to use Ably LiveObjects via
+     * {@link AgentSession.object}. Omit to attach with the default mode set.
+     *
+     * The session requests the union of these modes with the modes it always
+     * needs, so passing extra modes never drops the SDK's required modes. The
+     * connection's token/key capability must permit the requested operations,
+     * otherwise the server grants only the permitted subset.
+     */
+    channelModes?: readonly Ably.ChannelMode[];
+}
+/**
+ * Options for `Run.pipe` — per-operation overrides for the assistant message.
+ * @template TOutput - The codec output type carried by the stream; used by the `resolveWriteOptions` hook.
+ */
+export interface PipeOptions<TOutput extends CodecOutputEvent> {
+    /** The codec-message-id of the immediately preceding message in this branch. */
+    parent?: string;
+    /** The codec-message-id of the message this response replaces (for regeneration). */
+    forkOf?: string;
+    /**
+     * Optional per-output hook invoked before each output is encoded. The
+     * returned {@link WriteOptions} (if any) override the stream's default
+     * headers and `codecMessageId` for that one encode call only; return `undefined`
+     * to use the stream defaults.
+     *
+     * Used to carry a subset of outputs within the stream to a different
+     * message (e.g. `tool-output-available` chunks that belong on a prior
+     * assistant message, stamped with `amend`). Must not be used
+     * for outputs that participate in the encoder's stream-append pipeline
+     * — streaming state (stream tracker, append ordering) is anchored to
+     * the stream's default identity and is not affected by per-output
+     * overrides.
+     * @param output - The output about to be encoded.
+     * @returns Per-write overrides for this output, or undefined.
+     */
+    resolveWriteOptions?: (output: TOutput) => WriteOptions | undefined;
+}
+/** The result of streaming a response through the encoder. */
+export interface StreamResult {
+    /** Why the stream ended. */
+    reason: RunEndReason;
+    /**
+     * The error that caused the stream to fail, present when `reason` is
+     * `'error'`. This is the original error (e.g. from the LLM provider)
+     * preserved so the caller can inspect provider-specific fields. The
+     * run's `onError` callback also fires with a wrapped `Ably.ErrorInfo`
+     * (code `StreamError`) for standardized observability.
+     */
+    error?: Error;
+}
+/** Per-run runtime hooks, signal, and overrides supplied at `createRun()` time. */
+export interface RunRuntime<TOutput extends CodecOutputEvent> {
+    /**
+     * Override the invocation id for this run. When omitted, the agent mints a
+     * fresh `crypto.randomUUID()` — the normal path (one per HTTP request).
+     * Supply a non-empty fixed value for deterministic ids in tests or
+     * in-process drivers; the empty string is not a valid override (it is the
+     * "unset" sentinel and does not fall through to minting).
+     */
+    invocationId?: string;
+    /**
+     * Override the run id for a FRESH run. When omitted, the agent mints a fresh
+     * `crypto.randomUUID()` — the normal path. A continuation IGNORES this: its
+     * run id is read from the triggering input event's wire headers, since a
+     * continuation re-enters a run that already exists. Supply a non-empty fixed
+     * value for deterministic ids in tests or in-process drivers; the empty
+     * string is not a valid override (it is the "unset" sentinel and does not
+     * fall through to minting).
+     */
+    runId?: string;
+    /**
+     * An external AbortSignal (typically the HTTP request's `req.signal`) that,
+     * when fired, cancels this run. This allows platform-level cancellation —
+     * request cancellation, serverless function timeout — to stop LLM generation
+     * and stream piping gracefully.
+     */
+    signal?: AbortSignal;
+    /**
+     * Called before each Ably message is published in this run.
+     * Mutate the Ably message in place to add custom headers under extras.ai.
+     */
+    onMessage?: (message: Ably.Message) => void;
+    /**
+     * Called when the run's stream is cancelled (by client cancel or server).
+     * Receives a write function to publish final outputs before the cancellation finalises.
+     */
+    onCancelled?: (write: (output: TOutput) => Promise<void>) => void | Promise<void>;
+    /**
+     * Called when a cancel message arrives matching this run.
+     * Return true to allow cancellation (fires `abortSignal`, stream cancels).
+     * Return false to reject (cancel ignored, stream continues).
+     * If not provided, all cancels are accepted.
+     */
+    onCancel?: (request: CancelRequest) => Promise<boolean>;
+    /**
+     * Called with non-fatal run-scoped errors that have no other delivery
+     * path. Fires in two scenarios:
+     * - Stream failures in `pipe` — the underlying error is also returned on
+     *   `StreamResult.error`, but this callback delivers it wrapped as an
+     *   `Ably.ErrorInfo` (code `StreamError`) for standardized observability.
+     * - Failures in the `onCancel` handler.
+     *
+     * Publish failures in `start` and `end`
+     * are not delivered here — those methods reject their returned promise
+     * with an `Ably.ErrorInfo`, and the caller should handle it at the await
+     * site. Run errors never render the session unusable, but the run may
+     * be in an inconsistent state; the caller should typically `end` it
+     * with reason `'error'`.
+     *
+     * Channel-wide events (e.g. continuity loss) are delivered via the
+     * session-level `onError` on {@link AgentSessionOptions}, not here.
+     */
+    onError?: (error: Ably.ErrorInfo) => void;
+}
+/**
+ * Read-only view exposed on a {@link Run} of the conversation messages
+ * this run was created with.
+ *
+ * TODO(AIT-771): when the agent rebuilds full conversation history from
+ * the channel, this should expose `RunNode[]`-shaped data to match the
+ * client side. Today it carries the flat input messages handed to the
+ * invocation.
+ */
+export interface RunView<TMessage> {
+    /** Invocation input messages handed to this run; no branch awareness today. */
+    readonly messages: MessageNode<TMessage>[];
+}
+/** Options for {@link Run.loadConversation}. */
+export interface LoadConversationOptions {
+    /**
+     * Maximum number of ANCESTOR reply RunNodes to walk back through the
+     * chain. Input nodes encountered alongside don't count toward the bound,
+     * and neither does the current run's own node (it is the conversation
+     * tail, not ancestor context). Default unbounded (walks to the
+     * conversation root).
+     *
+     * Set this to bound the LLM context window — `maxRuns: 5` returns the
+     * 5 most-recent prior reply runs and their associated input nodes
+     * (each bounded run's triggering input included, so the chain never
+     * starts assistant-first), in chronological order.
+     */
+    maxRuns?: number;
+}
+/**
+ * How a run terminates, passed to {@link Run.end}. Discriminated on `reason`:
+ * an `'error'` end may carry a terminal `error`; any other reason carries none.
+ */
+export type RunEndParams = {
+    /** Why the run ended — any terminal reason other than `'error'`. */
+    reason: Exclude<RunEndReason, 'error'>;
+} | {
+    /** The run ended in error. */
+    reason: 'error';
+    /**
+     * Optional terminal error to surface to clients. Omit to end in error
+     * without detail.
+     */
+    error?: Ably.ErrorInfo;
+};
+/**
+ * A server-side run with explicit lifecycle methods. Generic over the codec's
+ * output, projection, and message types. `TProjection` is retained for
+ * parameter symmetry with {@link AgentSession.createRun}; it does not
+ * appear in the Run's public surface today but keeps the type slot
+ * available for future per-Run projection accessors.
+ */
+export interface Run<TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /** The run's unique identifier. */
+    readonly runId: string;
+    /**
+     * The invocation's unique identifier, minted by the agent when the run is
+     * created (one per HTTP request that invokes the agent). Readable
+     * synchronously — the application returns it on the HTTP response so the
+     * caller can observe it. The agent stamps it on every event it publishes
+     * for this invocation (run lifecycle + outputs).
+     */
+    readonly invocationId: string;
+    /** AbortSignal scoped to this run. Fires when a cancel event arrives for this runId. */
+    readonly abortSignal: AbortSignal;
+    /** Read-only view of the conversation messages associated with this run. */
+    readonly view: RunView<TMessage>;
+    /**
+     * The conversation messages this run should feed to the model.
+     *
+     * - Before {@link start} resolves: empty (no view contribution yet).
+     * - After {@link start}: the user-prompt messages looked up on the
+     *   channel for this invocation.
+     * - After {@link loadConversation}: the full multi-turn conversation —
+     *   all ancestor run messages followed by the current run's messages,
+     *   oldest turn first. This is the value to pass to the LLM when the
+     *   agent handles a reply in an ongoing conversation.
+     *
+     * Each access returns a fresh array — safe to mutate without affecting
+     * internal Run state.
+     */
+    readonly messages: TMessage[];
+    /**
+     * Publish the run's opening lifecycle event to the channel (run-start, or
+     * run-resume for a continuation). Must be called before any other run method
+     * (pipe, suspend, end).
+     */
+    start(): Promise<void>;
+    /**
+     * Pipe a ReadableStream through the encoder to the channel.
+     * Returns when the stream completes, is cancelled, or errors.
+     * Does NOT call end() — the caller must call end() after pipe returns.
+     */
+    pipe(stream: ReadableStream<TOutput>, options?: PipeOptions<TOutput>): Promise<StreamResult>;
+    /**
+     * Reconstruct the full multi-turn conversation by walking the ancestor
+     * run chain over the session's Tree, concatenating each ancestor's
+     * projection (oldest turn first) plus the current run's projection.
+     *
+     * Hydrates the Tree as needed from channel history if the chain from
+     * the run's structural-parent anchor isn't already fully present;
+     * subsequent reads of {@link Run.messages} re-walk the same Tree and
+     * reflect any further folds (e.g. live arrivals from concurrent runs).
+     * No cache: every call computes a fresh snapshot from the live Tree.
+     *
+     * Walks to the conversation root by default; bound the walk via the
+     * optional {@link LoadConversationOptions.maxRuns} cap. If channel
+     * retention has expired older turns, the walk stops at what is available.
+     * @param options - Optional walk bounds.
+     * @returns The conversation messages in chronological order, ready to pass to an LLM.
+     * @throws {Ably.ErrorInfo} `HistoryFetchFailed` — or the underlying Ably
+     *   code when the failure carried one — when the history fetch fails after
+     *   retries (the conversation is never silently truncated on fetch
+     *   failure); `InvalidArgument` when the run's signal aborts.
+     */
+    loadConversation(options?: LoadConversationOptions): Promise<TMessage[]>;
+    /**
+     * Publish a run-suspend event to the channel and clean up, pausing the run
+     * without ending it. Call this instead of {@link Run.end} when the run is
+     * waiting on participant input (e.g. a client-side tool execution or a
+     * server-side tool approval): the run stays live and a later invocation can
+     * resume it under the same `runId`. Like {@link Run.end}, it is terminal for
+     * this Run instance — the resuming invocation builds a fresh Run. Must be
+     * called after {@link Run.start}; a no-op if the run has already ended or
+     * suspended.
+     */
+    suspend(): Promise<void>;
+    /**
+     * Publish run-end event to the channel and clean up. Terminal.
+     * @param params - How the run ended; see {@link RunEndParams}.
+     */
+    end(params: RunEndParams): Promise<void>;
+}
+/** Server-side session that manages run lifecycles over an Ably channel. */
+export interface AgentSession<TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /**
+     * The Ably presence object for this session's channel.
+     *
+     * Exposed as a convenience so the agent can track and publish presence
+     * (`enter`/`leave`/`update`/`get`/`subscribe`) — for example, to detect
+     * whether the requesting user is still connected — without obtaining the
+     * channel separately. This is the same `Ably.RealtimePresence` instance the
+     * underlying channel exposes; the session applies no additional semantics.
+     * Presence operations implicitly attach the channel and do not require
+     * {@link connect} to have been called first.
+     */
+    readonly presence: Ably.RealtimePresence;
+    /**
+     * The Ably LiveObjects entry point for this session's channel.
+     *
+     * Exposed as a convenience so the agent can read and mutate shared objects
+     * (LiveMap / LiveCounter) on the same channel the session uses, without
+     * obtaining the channel separately. This is the same `RealtimeObject`
+     * instance the underlying channel exposes; the session applies no additional
+     * semantics. Operating on it requires (a) the Realtime client to have been
+     * constructed with the `LiveObjects` plugin from `ably/liveobjects` and
+     * (b) the object channel modes to have been requested via
+     * {@link AgentSessionOptions.channelModes}. When either is absent the
+     * underlying SDK throws; the session does not suppress the error.
+     */
+    readonly object: AblyObjects.RealtimeObject;
+    /**
+     * The session's materialisation tree. Every Ably message received on the channel
+     * (live + history) folds into this tree; consumers can introspect hydrated
+     * conversation state via {@link Tree.getNodeByCodecMessageId} /
+     * {@link Tree.getRunNode} etc. Mirrors `ClientSession.tree` so both
+     * sessions share one materialisation engine.
+     */
+    readonly tree: Tree<TOutput, TProjection>;
+    /**
+     * Subscribe (unfiltered) to the shared channel and (implicitly) attach. The
+     * subscribe is deliberately unfiltered so channel-history-replayed input
+     * events reach the materialisation engine, which the input-event lookup
+     * queries via the Tree. Idempotent — subsequent calls return the same
+     * promise. All run methods (`start`, `pipe`, `loadConversation`,
+     * `suspend`, `end`) throw `InvalidArgument` until
+     * `connect()` has been *called*; once it has, they await the in-flight
+     * connect promise rather than throwing.
+     */
+    connect(): Promise<void>;
+    /**
+     * Create a new run from an invocation. Synchronous — no channel activity
+     * until start() is called. The run is registered for cancel routing
+     * immediately so that early cancels fire the AbortSignal.
+     * @param invocation - The {@link Invocation} carrying run identity and
+     *   conversation messages.
+     * @param runtime - Optional runtime hooks and external AbortSignal
+     *   (e.g. the HTTP request's `req.signal`).
+     */
+    createRun(invocation: Invocation, runtime?: RunRuntime<TOutput>): Run<TOutput, TProjection, TMessage>;
+    /**
+     * Unsubscribe from cancel messages, cancel all active runs, detach the
+     * channel this session attached, and clean up.
+     *
+     * Resolves once the detach completes. The detach is best-effort:
+     * a failure (e.g. the channel is already FAILED) is swallowed
+     * and does not reject. Idempotent.
+     */
+    close(): Promise<void>;
+}

package/dist/core/transport/types/client.d.ts

@@ -0,0 +1,201 @@
+import { Logger } from '../../../logger.js';
+import { Codec, CodecInputEvent, CodecOutputEvent } from '../../codec/types.js';
+import { Invocation } from '../invocation.js';
+import { Tree } from './tree.js';
+import { View } from './view.js';
+/** Client session types: options, send options, the ActiveRun handle, and the ClientSession contract. */
+import type * as Ably from 'ably';
+import type * as AblyObjects from 'ably/liveobjects';
+/** Options for creating a client session. */
+export interface ClientSessionOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /**
+     * The Ably Realtime client. The caller owns its lifecycle —
+     * `session.close()` does not close the client.
+     *
+     * The session's identity is taken from this client's `auth.clientId` (set
+     * via the Ably token or `ClientOptions.clientId`) — it is read at publish
+     * time and stamped on the wire as the run/input client id so other clients
+     * can attribute messages. A connection without a concrete clientId
+     * (anonymous, or a wildcard `*` token) publishes without one.
+     */
+    client: Ably.Realtime;
+    /**
+     * The name of the channel to subscribe to and publish cancel signals on.
+     * The session owns this channel — do not also resolve it elsewhere with
+     * conflicting channel options.
+     */
+    channelName: string;
+    /** The codec to use for encoding/decoding. */
+    codec: Codec<TInput, TOutput, TProjection, TMessage>;
+    /** Initial messages to seed the conversation tree with. Forms a linear chain. */
+    messages?: TMessage[];
+    /**
+     * Extra Ably channel modes to request on the session's channel, on top of the
+     * modes AI Transport always needs. Pass `OBJECT_MODES` (or
+     * `['OBJECT_SUBSCRIBE', 'OBJECT_PUBLISH']`) to use Ably LiveObjects via
+     * {@link ClientSession.object}. Omit to attach with the default mode set.
+     *
+     * The session requests the union of these modes with the modes it always
+     * needs, so passing extra modes never drops the SDK's required modes. The
+     * connection's token/key capability must permit the requested operations,
+     * otherwise the server grants only the permitted subset.
+     */
+    channelModes?: readonly Ably.ChannelMode[];
+    /** Logger instance for diagnostic output. */
+    logger?: Logger;
+}
+/** Per-send options for branching metadata and run identity. */
+export interface SendOptions {
+    /**
+     * The codec-message-id of the message this send replaces (fork).
+     * Set for regeneration (forkOf an assistant message) or
+     * edit (forkOf a user message).
+     */
+    forkOf?: string;
+    /**
+     * The codec-message-id of the message that precedes this one in the
+     * conversation thread. If omitted, auto-computed from the last
+     * message in the view.
+     */
+    parent?: string;
+    /**
+     * Reuse an existing `runId` (e.g. resume a suspended run). When set,
+     * the send is treated as a continuation: the run's existing observer
+     * state (router stream, tree run-tracking) is reused; no fresh
+     * `crypto.randomUUID()` is minted. Each continuation POST is woken by the
+     * agent, which mints a distinct `invocationId` per HTTP request.
+     */
+    runId?: string;
+}
+/**
+ * A handle to an active client-side run, returned by `send()`,
+ * `regenerate()`, and `edit()`.
+ *
+ * The core does not expose a per-run output stream — streaming is a
+ * consumer-layer concern (e.g. the Vercel ChatTransport builds a stream from
+ * the Tree's `output` events). The handle carries only run identity and
+ * control, so it is not parameterized by the codec output type.
+ */
+export interface ActiveRun {
+    /**
+     * The synchronous routing handle for this send: the triggering input's
+     * codec-message-id, which the client owns the moment it publishes and the
+     * agent echoes back as `input-codec-message-id`. Stream routing and cancel
+     * key on this — it is known immediately, unlike {@link runId}, which the
+     * agent mints.
+     */
+    inputCodecMessageId: string;
+    /**
+     * The run's unique identifier, resolved when the agent's `ai-run-start` for
+     * this send is observed on the channel. The agent mints the run-id, so it is
+     * not known synchronously: `await run.runId`
+     * to learn it (this also tells you the agent has picked up the run). There is
+     * no built-in deadline — race it against your own timeout if you need one.
+     * Rejects only if the session is closed before run-start arrives. A
+     * continuation does not resolve any sooner: its run-id promise resolves when
+     * the agent's run-resume (`event.type === 'resume'`) for this send is observed
+     * on the channel, not synchronously from the run-id the caller passed in.
+     */
+    runId: Promise<string>;
+    /**
+     * The input event's unique identifier. Stamped on the primary input event
+     * published to the channel and forwarded in the HTTP POST body so the
+     * agent can locate the exact triggering event.
+     */
+    inputEventId: string;
+    /**
+     * Cancel this specific run. Publishes a cancel signal synchronously — keyed
+     * by the triggering input's codec-message-id ({@link inputCodecMessageId}),
+     * which the client owns the moment it publishes, so a cancel issued before
+     * the agent mints the run-id is still honoured (the agent buffers it and
+     * fires it once its input-event lookup resolves the input to the run). A
+     * continuation also carries its known run-id. Resolves once the cancel is
+     * published; it does not wait for {@link runId}.
+     */
+    cancel(): Promise<void>;
+    /**
+     * The codec-message-id of every input in this send, in input order. Includes
+     * wire-only inputs (regenerate, tool resolutions), which are NOT folded into
+     * the local projection — so an entry here does not by itself mean an
+     * optimistic insert occurred.
+     */
+    optimisticCodecMessageIds: string[];
+    /**
+     * Build the {@link Invocation} pointer for this run — only `inputEventId` and
+     * the session's channel name as `sessionName`. The body carries no run-id: a
+     * fresh run's run-id is minted by the agent, and a continuation's run-id is
+     * read off the triggering input event's wire headers, so run identity always
+     * lives on the channel rather than the invocation body. The
+     * application POSTs `run.toInvocation().toJSON()` to its agent endpoint to
+     * wake the agent; the agent rebuilds it via {@link Invocation.fromJSON} and
+     * mints the `invocationId` (and a fresh `runId`) itself. The conversation
+     * itself is read from the channel, so the pointer carries only identifiers.
+     */
+    toInvocation(): Invocation;
+}
+/** Client-side session that manages conversation state over an Ably channel. */
+export interface ClientSession<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /** The complete conversation tree — all known Run nodes, events for any change. */
+    readonly tree: Tree<TOutput, TProjection>;
+    /** The default paginated, branch-aware view for rendering — events scoped to visible messages. */
+    readonly view: View<TInput, TMessage>;
+    /**
+     * The Ably presence object for this session's channel.
+     *
+     * Exposed as a convenience so callers can track and publish presence
+     * (`enter`/`leave`/`update`/`get`/`subscribe`) — for example, to detect
+     * whether an agent is online — without obtaining the channel separately.
+     * This is the same `Ably.RealtimePresence` instance the underlying channel
+     * exposes; the session applies no additional semantics. Presence operations
+     * implicitly attach the channel and do not require {@link connect} to have
+     * been called first.
+     */
+    readonly presence: Ably.RealtimePresence;
+    /**
+     * The Ably LiveObjects entry point for this session's channel.
+     *
+     * Exposed as a convenience so callers can read and mutate shared objects
+     * (LiveMap / LiveCounter) on the same channel the session uses, without
+     * obtaining the channel separately. This is the same `RealtimeObject`
+     * instance the underlying channel exposes; the session applies no additional
+     * semantics. Operating on it requires (a) the Realtime client to have been
+     * constructed with the `LiveObjects` plugin from `ably/liveobjects` and
+     * (b) the object channel modes to have been requested via
+     * {@link ClientSessionOptions.channelModes}. When either is absent the
+     * underlying SDK throws; the session does not suppress the error.
+     */
+    readonly object: AblyObjects.RealtimeObject;
+    /**
+     * Subscribe to the channel and (implicitly) attach. Idempotent —
+     * subsequent calls return the same promise. The View's write operations
+     * (`send()`, `regenerate()`, `edit()`) and this session's `cancel()` throw
+     * `InvalidArgument` until `connect()` resolves.
+     */
+    connect(): Promise<void>;
+    /**
+     * Create an additional view over the same conversation tree.
+     * Each view has independent branch selections and pagination state.
+     * The caller is responsible for calling `close()` on the returned view
+     * when it is no longer needed, or it will be closed when the session closes.
+     */
+    createView(): View<TInput, TMessage>;
+    /** Cancel the specified run by publishing an `ai-cancel` signal on the channel. The core does not own a per-run stream; closing any consumer-built stream is the responsibility of the layer that built it (e.g. the Vercel ChatTransport). */
+    cancel(runId: string): Promise<void>;
+    /**
+     * Subscribe to non-fatal session errors. These indicate something went
+     * wrong but the session is still operational. Returns an unsubscribe function.
+     * Once the session is CLOSED this is a no-op: the handler is not registered and
+     * the returned function does nothing.
+     */
+    on(event: 'error', handler: (error: Ably.ErrorInfo) => void): () => void;
+    /**
+     * Tear down the session: unsubscribe from the channel, close active views,
+     * clear all handlers, and detach the channel this session attached.
+     *
+     * Detaching stops the session from receiving further channel messages;
+     * the server keeps streaming until its runs end on their own. To stop
+     * in-progress runs, call {@link cancel} for each before `close()`. The
+     * detach is best-effort: a failure is swallowed and does not reject.
+     */
+    close(): Promise<void>;
+}

package/dist/core/transport/types/shared.d.ts

@@ -0,0 +1,24 @@
+/** Types shared across the client, agent, tree, and view layers. */
+import type * as Ably from 'ably';
+/**
+ * Why a run ended.
+ *
+ * A run-end is terminal — a run that merely pauses awaiting input publishes
+ * `ai-run-suspend` instead (see {@link Run.suspend}).
+ *
+ * - `complete` — the run finished naturally.
+ * - `cancelled` — the run was cancelled by a client.
+ * - `error` — the run errored.
+ */
+export type RunEndReason = 'complete' | 'cancelled' | 'error';
+/**
+ * Passed to a run's `onCancel` hook for authorization decisions.
+ * The hook inspects the incoming cancel message and decides whether to
+ * allow the targeted run to be cancelled.
+ */
+export interface CancelRequest {
+    /** The raw Ably message that carried the cancel signal. */
+    message: Ably.InboundMessage;
+    /** The runId being cancelled. */
+    runId: string;
+}