@ably/ai-transport 0.1.0 → 0.2.0

package/dist/constants.d.ts

@@ -1,54 +1,128 @@
 /**
  * Shared constants used by both codec and transport layers.
  *
- * Header constants define the `x-ably-*` wire protocol. Message and event
- * name constants define the transport lifecycle signals on the channel.
+ * Header constants define the transport wire header names. Message and event
+ * name constants define the session lifecycle signals on the channel.
  *
  * These live at the top level (not in codec/ or transport/) because both
  * layers need them — the codec core reads/writes stream and status headers,
- * while the transport layer reads/writes turn, cancel, and role headers.
+ * while the transport layer reads/writes run, cancel, and role headers.
  */
 /** Header: whether this Ably message uses streaming (message appends) or is discrete. Always "true" or "false". */
-export declare const HEADER_STREAM = "x-ably-stream";
-/** Header: lifecycle status of a streamed message. Only set when x-ably-stream is "true". */
-export declare const HEADER_STATUS = "x-ably-status";
+export declare const HEADER_STREAM = "stream";
+/** Header: lifecycle status of a streamed message. Only set when stream is "true". One of "streaming", "complete", or "cancelled". */
+export declare const HEADER_STATUS = "status";
 /** Header: stream identity. Set by the encoder on every streamed message; read by the decoder to correlate streams. */
-export declare const HEADER_STREAM_ID = "x-ably-stream-id";
+export declare const HEADER_STREAM_ID = "stream-id";
 /** Header: marks a message as a discrete message part (from writeMessages). Set by publishDiscreteBatch; not set on lifecycle events from publishDiscrete. */
-export declare const HEADER_DISCRETE = "x-ably-discrete";
-/** Header: turn correlation ID. Set on every message in a turn. */
-export declare const HEADER_TURN_ID = "x-ably-turn-id";
+export declare const HEADER_DISCRETE = "discrete";
+/** Header: run correlation ID. Set on every agent-published message and on continuation client inputs, but omitted from the originating fresh client input (the agent mints the run-id at run-start). */
+export declare const HEADER_RUN_ID = "run-id";
+/** Header: invocation correlation ID; identifies a specific invocation under a run. Agent-minted and stamped by the agent on every event it publishes for the invocation — run lifecycle (run-start/resume/suspend/end) and assistant outputs. Never set by the client on its input. */
+export declare const HEADER_INVOCATION_ID = "invocation-id";
+/**
+ * Header: per-event identifier stamped by the client on every
+ * client-published event in a send — user-message events AND amend
+ * events (tool-approval responses, client tool outputs). Distinct from
+ * `codec-message-id` so it survives edits/retries that reuse the same
+ * codec-message-id, and so amend events that target an existing message can
+ * carry their own per-send identity. The invocation body lists every
+ * inputEventId the agent must observe on the channel before starting LLM
+ * work — see `Run.start()`'s input-event lookup.
+ */
+export declare const HEADER_EVENT_ID = "event-id";
 /** Header: message identity. Assigned per message (user or assistant). Used for optimistic reconciliation on the client. */
-export declare const HEADER_MSG_ID = "x-ably-msg-id";
-/** Header: clientId of the user who initiated the turn. Set by the server on stream messages. */
-export declare const HEADER_TURN_CLIENT_ID = "x-ably-turn-client-id";
+export declare const HEADER_CODEC_MESSAGE_ID = "codec-message-id";
+/** Header: clientId of the user who initiated the run. Stamped by the client on its user input and re-stamped by the agent on the run's lifecycle and stream messages. */
+export declare const HEADER_RUN_CLIENT_ID = "run-client-id";
+/**
+ * Header: clientId of the input event (the `ai-input`) that drove the
+ * current invocation. The agent reads the publisher's Ably-level `clientId`
+ * from the triggering input event on the channel and re-stamps it as
+ * `input-client-id` on every event it publishes for that invocation
+ * (run lifecycle and assistant outputs). May differ from
+ * `run-client-id` on continuation invocations driven by an input
+ * from a non-owner (e.g. a tool-result publish from a different client).
+ * Not stamped on `ai-input` events themselves — the wire publisher's
+ * Ably `clientId` already conveys that.
+ */
+export declare const HEADER_INPUT_CLIENT_ID = "input-client-id";
 /** Header: message role (e.g. "user", "assistant"). */
-export declare const HEADER_ROLE = "x-ably-role";
-/** Header: the msg-id of the existing message this Ably message amends. Present on cross-turn amendment events. */
-export declare const HEADER_AMEND = "x-ably-amend";
-/** Header: cancel a specific turn by ID. */
-export declare const HEADER_CANCEL_TURN_ID = "x-ably-cancel-turn-id";
-/** Header: cancel all turns belonging to the sender's clientId. */
-export declare const HEADER_CANCEL_OWN = "x-ably-cancel-own";
-/** Header: cancel all turns on the channel. */
-export declare const HEADER_CANCEL_ALL = "x-ably-cancel-all";
-/** Header: cancel all turns belonging to a specific clientId. */
-export declare const HEADER_CANCEL_CLIENT_ID = "x-ably-cancel-client-id";
-/** Header: the msg-id of the immediately preceding message in this branch. */
-export declare const HEADER_PARENT = "x-ably-parent";
-/** Header: the msg-id of the message this one replaces (creates a fork). */
-export declare const HEADER_FORK_OF = "x-ably-fork-of";
-/** Header: reason a turn ended (on x-ably-turn-end messages). */
-export declare const HEADER_TURN_REASON = "x-ably-turn-reason";
-/** Message name: client->server cancel signal. */
-export declare const EVENT_CANCEL = "x-ably-cancel";
-/** Message name: server publishes this to signal a turn has started. */
-export declare const EVENT_TURN_START = "x-ably-turn-start";
-/** Message name: server publishes this to signal a turn has ended. */
-export declare const EVENT_TURN_END = "x-ably-turn-end";
-/** Message name: transport-level abort signal (stream cancelled). */
-export declare const EVENT_ABORT = "x-ably-abort";
-/** Message name: transport-level error signal. */
-export declare const EVENT_ERROR = "x-ably-error";
-/** Prefix for domain-specific headers. Distinguishes codec-layer headers from transport `x-ably-*` headers. */
-export declare const DOMAIN_HEADER_PREFIX = "x-domain-";
+export declare const HEADER_ROLE = "role";
+/** Header: the codec-message-id of the immediately preceding message in this branch. */
+export declare const HEADER_PARENT = "parent";
+/** Header: the codec-message-id of the message this one replaces (creates a fork). */
+export declare const HEADER_FORK_OF = "fork-of";
+/**
+ * Header: the codec-message-id of the assistant message this run regenerates.
+ *
+ * Stamped on the regenerate wire (and echoed on `run-start`) when the
+ * client requested a regeneration. A regenerate run parents at the SAME input
+ * node as the reply it regenerates, so it joins that input's reply runs as a
+ * same-parent sibling (no fork-of). The View consults this header to resolve
+ * the message-level sibling group and to drop the regenerated message from
+ * earlier Runs in the visible chain (Spec: AIT-CT13d).
+ */
+export declare const HEADER_MSG_REGENERATE = "msg-regenerate";
+/** Header: reason a run ended (on ai-run-end messages). */
+export declare const HEADER_RUN_REASON = "run-reason";
+/**
+ * Header: the `codec-message-id` of the input event that triggered the run.
+ * The triggering input is the one whose `event-id` matches the invocation's
+ * `inputEventId` (the last input of the originating send). The agent
+ * re-stamps it on every event it publishes for the invocation (run
+ * lifecycle + assistant outputs), mirroring `input-client-id`. This is the
+ * codec-message-id the client owns at send time, so it lets the client
+ * correlate any of those events back to the originating input without
+ * depending on a client-minted run-id or invocation-id.
+ */
+export declare const HEADER_INPUT_CODEC_MESSAGE_ID = "input-codec-message-id";
+/** Header: numeric error code accompanying an `ai-run-end` with reason `error`. */
+export declare const HEADER_ERROR_CODE = "error-code";
+/** Header: human-readable error message accompanying an `ai-run-end` with reason `error`. */
+export declare const HEADER_ERROR_MESSAGE = "error-message";
+/**
+ * Message name: client->agent cancel intent. Targets a run by `run-id` (a
+ * continuation, whose run-id the client already knows) and/or by
+ * `input-codec-message-id` (a fresh send, whose run-id the agent mints at
+ * run-start — so the client can only key the cancel by the triggering input's
+ * codec-message-id it owns at send time). The agent resolves whichever is
+ * present to the registered run; a cancel that arrives before the run is known
+ * (the input-event lookup hasn't resolved the input id to a run yet) is
+ * buffered by `input-codec-message-id` and honoured when the run resolves it.
+ * Also carries an `event-id` so channel rewind redelivers it to a per-request /
+ * serverless agent that attaches after the cancel was published.
+ */
+export declare const EVENT_CANCEL = "ai-cancel";
+/** Message name: server publishes this to signal a run has started. */
+export declare const EVENT_RUN_START = "ai-run-start";
+/**
+ * Message name: server publishes this to signal a run has suspended — paused
+ * awaiting participant input (e.g. a client tool result or approval) without
+ * ending. The run stays live and may be resumed under the same `runId`.
+ * Distinct from `ai-run-end`, which is terminal.
+ */
+export declare const EVENT_RUN_SUSPEND = "ai-run-suspend";
+/**
+ * Message name: server publishes this when a subsequent invocation re-enters an
+ * already-started run (e.g. a tool-result follow-up under the same `runId`).
+ * A pure re-entry signal: unlike `ai-run-start` it carries no `parent` / `fork-of`
+ * (the original `ai-run-start` already established the run's structure).
+ */
+export declare const EVENT_RUN_RESUME = "ai-run-resume";
+/** Message name: server publishes this to signal a run has ended. */
+export declare const EVENT_RUN_END = "ai-run-end";
+/**
+ * Message name: every agent-published codec event (text, reasoning, tool calls,
+ * tool outputs, lifecycle helpers, file / source parts, data-* chunks) rides
+ * this single wire name. The codec event's own `type` is carried in the
+ * codec-level `type` header so the decoder can dispatch.
+ */
+export declare const EVENT_AI_OUTPUT = "ai-output";
+/**
+ * Message name: every client-published codec event (user-message parts,
+ * tool-approval responses, regenerate signals) rides this single wire
+ * name. The codec event's own kind is carried in the codec-level `type`
+ * header so the decoder can dispatch.
+ */
+export declare const EVENT_AI_INPUT = "ai-input";

package/dist/core/agent.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Wraps the two paths chat-js uses (see ChatClient._addAgent): the
+ * `options.agents` mutation (read by ably-js when opening the initial
+ * WebSocket) and the `params.agent` channel option (sent on ATTACH so
+ * an already-open connection still carries the identifier).
+ *
+ * `options.agents` is a private API on the Realtime client — no public
+ * typed accessor exists in the `ably` package — so this module casts to a
+ * `RealtimeWithOptions` shape to write it.
+ */
+import type * as Ably from 'ably';
+/**
+ * Register this SDK (and optionally a codec) on the supplied Realtime client
+ * and return the channel options the caller should pass to
+ * `client.channels.get(...)` so the agent is also carried on channel ATTACH.
+ * Sets `options.agents['ai-transport-js'] = VERSION`. When the codec carries
+ * an internal `adapterTag` field (via {@link AdapterTagHolder}), also sets
+ * `options.agents[adapterTag] = VERSION`.
+ * Idempotent — repeated calls with the same client and codec produce the same keys/values.
+ * Spec: AIT-CT1a, AIT-CT1a2, AIT-CT1a3, AIT-ST1a, AIT-ST1a2, AIT-ST1a3.
+ * @param client - The Ably Realtime client to register on.
+ * @param codec - The codec instance; cast to {@link AdapterTagHolder} to detect an optional identifier.
+ * @returns Channel options containing `params.agent` for `channels.get`.
+ */
+export declare const registerAgent: (client: Ably.Realtime, codec?: unknown) => {
+    params: {
+        agent: string;
+    };
+};

package/dist/core/codec/decoder.d.ts

@@ -1,5 +1,5 @@
 import { Logger } from '../../logger.js';
-import { DecoderOutput, MessagePayload, StreamTrackerState } from './types.js';
+import { MessagePayload, StreamTrackerState } from './types.js';
 /**
  * Decoder core — action dispatch and serial tracking machinery.
  *
@@ -8,15 +8,12 @@ import { DecoderOutput, MessagePayload, StreamTrackerState } from './types.js';
  * event decoding.
  *
  * Domain decoders call `createDecoderCore(hooks, options)` and provide hooks
- * for stream classification, event building, and discrete decoding.
+ * for stream classification, event building, and discrete decoding. Hooks
+ * return a flat `TEvent[]` — no event-vs-message union. Per-message routing
+ * concerns (`codec-message-id`) are handled by the SDK via `ReducerMeta`, not
+ * here.
  */
 import type * as Ably from 'ably';
-/**
- * Wrap a domain event as a single-element decoder output array.
- * @param event - The domain event to wrap.
- * @returns A single-element array containing the event as a decoder output.
- */
-export declare const eventOutput: <TEvent, TMessage>(event: TEvent) => DecoderOutput<TEvent, TMessage>[];
 /** Options for creating a decoder core. */
 export interface DecoderCoreOptions {
     /** Called when a tracked stream is replaced (non-prefix update). Receives the tracker with updated state. */
@@ -27,31 +24,31 @@ export interface DecoderCoreOptions {
     logger?: Logger;
 }
 /** Hooks that a domain codec provides to the decoder core for stream classification and event building. */
-export interface DecoderCoreHooks<TEvent, TMessage> {
+export interface DecoderCoreHooks<TEvent> {
     /**
      * Build domain events emitted when a new stream starts. May return multiple
      * events (e.g. a start event and a start-step event).
      */
-    buildStartEvents(tracker: StreamTrackerState): DecoderOutput<TEvent, TMessage>[];
+    buildStartEvents(tracker: StreamTrackerState): TEvent[];
     /** Build domain events for a text delta received on a stream. */
-    buildDeltaEvents(tracker: StreamTrackerState, delta: string): DecoderOutput<TEvent, TMessage>[];
+    buildDeltaEvents(tracker: StreamTrackerState, delta: string): TEvent[];
     /**
-     * Build domain events emitted when a stream finishes (x-ably-status:finished).
-     * Not called for aborted streams. The closing headers may differ from
-     * tracker.headers if the closing append carried updated headers.
+     * Build domain events emitted when a stream completes (status:complete).
+     * Not called for cancelled streams. The closing codec headers may differ
+     * from tracker.codecHeaders if the closing append carried updated headers.
      */
-    buildEndEvents(tracker: StreamTrackerState, closingHeaders: Record<string, string>): DecoderOutput<TEvent, TMessage>[];
+    buildEndEvents(tracker: StreamTrackerState, closingCodecHeaders: Record<string, string>): TEvent[];
     /**
-     * Decode a discrete message (message.create where x-ably-stream is "false",
-     * or a non-streamable first-contact update). Handles user messages, lifecycle
-     * events, tool lifecycle, data-*, etc.
+     * Decode a discrete message (a `message.create` whose stream header is not
+     * "true", or a non-streamable first-contact update). Handles user messages,
+     * tool lifecycle, data-*, etc.
      */
-    decodeDiscrete(input: MessagePayload): DecoderOutput<TEvent, TMessage>[];
+    decodeDiscrete(input: MessagePayload): TEvent[];
 }
 /** The decoder core returned by {@link createDecoderCore}. */
-export interface DecoderCore<TEvent, TMessage> {
-    /** Decode a single Ably message into zero or more domain outputs. */
-    decode(message: Ably.InboundMessage): DecoderOutput<TEvent, TMessage>[];
+export interface DecoderCore<TEvent> {
+    /** Decode a single Ably message into zero or more domain TEvents. */
+    decode(message: Ably.InboundMessage): TEvent[];
 }
 /**
  * Create a decoder core with the given domain hooks.
@@ -59,4 +56,4 @@ export interface DecoderCore<TEvent, TMessage> {
  * @param options - Decoder configuration (callbacks, logger).
  * @returns A new {@link DecoderCore} instance.
  */
-export declare const createDecoderCore: <TEvent, TMessage>(hooks: DecoderCoreHooks<TEvent, TMessage>, options?: DecoderCoreOptions) => DecoderCore<TEvent, TMessage>;
+export declare const createDecoderCore: <TEvent>(hooks: DecoderCoreHooks<TEvent>, options?: DecoderCoreOptions) => DecoderCore<TEvent>;

package/dist/core/codec/encoder.d.ts

@@ -3,7 +3,7 @@ import { ChannelWriter, EncoderOptions, MessagePayload, StreamPayload, WriteOpti
 /**
  * Encoder core — message append lifecycle machinery.
  *
- * Provides Ably primitives (publish, append, close, abort, flush) that
+ * Provides Ably primitives (publish, append, close, cancel, flush) that
  * domain-specific encoders wire their event types to.
  *
  * Domain encoders call `createEncoderCore(writer, options)` and use the
@@ -22,28 +22,31 @@ export interface EncoderCore {
     publishDiscrete(payload: MessagePayload, opts?: WriteOptions): Promise<Ably.PublishResult>;
     /** Publish multiple discrete messages atomically in a single channel publish. */
     publishDiscreteBatch(payloads: MessagePayload[], opts?: WriteOptions): Promise<Ably.PublishResult>;
-    /** Start a streamed message with x-ably-status:streaming. */
+    /** Start a streamed message with status:streaming. */
     startStream(streamId: string, payload: StreamPayload, opts?: WriteOptions): Promise<void>;
     /**
      * Append data to an in-flight streamed message. Fire-and-forget: errors are
-     * collected internally and surfaced by {@link closeStream} or {@link close}.
+     * collected internally and surfaced by {@link closeStream}, {@link cancelStream},
+     * {@link cancelAllStreams} or {@link close}.
+     * @throws {Ably.ErrorInfo} InvalidArgument if there is no active stream for `streamId` or the core is closed.
      */
     appendStream(streamId: string, data: string): void;
     /**
-     * Close a streamed message with x-ably-status:finished. Flushes all pending
+     * Close a streamed message with status:complete. Flushes all pending
      * appends for recovery before returning. Repeats persistent and payload headers.
+     * @throws {Ably.ErrorInfo} InvalidArgument if there is no active stream for `streamId`, or the encoder has been closed; EncoderRecoveryFailed if a failed append cannot be recovered during the flush.
      */
     closeStream(streamId: string, payload: StreamPayload): Promise<void>;
     /**
-     * Abort a single in-progress stream (x-ably-status:aborted) and flush all
+     * Cancel a single in-progress stream (status:cancelled) and flush all
      * pending appends for recovery before returning.
      */
-    abortStream(streamId: string, opts?: WriteOptions): Promise<void>;
+    cancelStream(streamId: string, opts?: WriteOptions): Promise<void>;
     /**
-     * Abort all in-progress streams (x-ably-status:aborted) and flush all
+     * Cancel all in-progress streams (status:cancelled) and flush all
      * pending appends for recovery before returning.
      */
-    abortAllStreams(opts?: WriteOptions): Promise<void>;
+    cancelAllStreams(opts?: WriteOptions): Promise<void>;
     /** Flush + clear trackers. Idempotent. */
     close(): Promise<void>;
 }

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

@@ -1,5 +1,4 @@
-export { eventOutput } from './decoder.js';
-export type { ChannelWriter, Codec, DecoderOutput, DiscreteEncoder, EncoderOptions, Extras, MessageAccumulator, MessagePayload, StreamDecoder, StreamEncoder, StreamPayload, StreamTrackerState, WriteOptions, } from './types.js';
+export type { ChannelWriter, Codec, CodecInputEvent, CodecMessage, CodecOutputEvent, DecodedMessage, Decoder, Encoder, EncoderOptions, Extras, MessagePayload, Reducer, ReducerMeta, Regenerate, StreamPayload, StreamTrackerState, ToolApprovalResponse, ToolResult, ToolResultError, UserMessage, WriteOptions, } from './types.js';
 export type { EncoderCore, EncoderCoreOptions } from './encoder.js';
 export { createEncoderCore } from './encoder.js';
 export type { DecoderCore, DecoderCoreHooks, DecoderCoreOptions } from './decoder.js';

package/dist/core/codec/lifecycle-tracker.d.ts

@@ -1,7 +1,7 @@
 /**
  * Generic lifecycle tracker for codec decoders.
  *
- * Manages per-scope (typically per-turn) tracking of lifecycle phases that
+ * Manages per-scope (typically per-run) tracking of lifecycle phases that
  * must be emitted before content events. When a phase has not been emitted
  * (e.g. mid-stream join), the tracker synthesizes the missing events using
  * codec-provided build functions.
@@ -30,15 +30,16 @@ export interface PhaseConfig<TEvent> {
  * Per-scope lifecycle tracker that ensures required phases are emitted
  * before content events, synthesizing missing ones for mid-stream joins.
  *
- * Scoped by an arbitrary string key (typically a turn ID). Each scope
+ * Scoped by an arbitrary string key (typically a run ID). Each scope
  * tracks independently which phases have been emitted.
  */
 export interface LifecycleTracker<TEvent> {
     /**
      * Ensure all configured phases have been emitted for the given scope.
-     * Returns synthetic events for any phases not yet marked as emitted,
-     * then marks them. Returns an empty array if all phases are current.
-     * @param scopeId - The scope to check (e.g. turn ID).
+     * Synthesizes and returns the events for any phases not yet marked as
+     * emitted, marking each as emitted so it is not synthesized again.
+     * Returns an empty array if all phases are already emitted.
+     * @param scopeId - The scope to check (e.g. run ID).
      * @param context - Key-value pairs passed through to phase build functions.
      * @returns Synthetic events for missing phases, in configuration order.
      */
@@ -46,7 +47,7 @@ export interface LifecycleTracker<TEvent> {
     /**
      * Mark a phase as emitted from the wire (not synthetic). Call this
      * when the real event arrives so the tracker does not re-synthesize it.
-     * @param scopeId - The scope (e.g. turn ID).
+     * @param scopeId - The scope (e.g. run ID).
      * @param phaseKey - The phase key to mark.
      */
     markEmitted(scopeId: string, phaseKey: string): void;
@@ -54,13 +55,13 @@ export interface LifecycleTracker<TEvent> {
      * Reset a phase so it will be re-synthesized on the next
      * {@link ensurePhases} call. Used for repeating phases (e.g. "start-step"
      * resets after "finish-step").
-     * @param scopeId - The scope (e.g. turn ID).
+     * @param scopeId - The scope (e.g. run ID).
      * @param phaseKey - The phase key to reset.
      */
     resetPhase(scopeId: string, phaseKey: string): void;
     /**
-     * Remove all tracking state for a scope. Call on turn completion
-     * (finish, abort) to free memory.
+     * Remove all tracking state for a scope. Call on run completion
+     * (finish, cancel) to free memory.
      * @param scopeId - The scope to clear.
      */
     clearScope(scopeId: string): void;