@ably/ai-transport 0.1.0 → 0.3.0

package/src/core/transport/decode-fold.ts

@@ -0,0 +1,101 @@
+/**
+ * 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.
+ *
+ * The engine is exposed as a {@link WireApplier} binding one Tree to one
+ * decoder. A Tree has exactly one applier (the session constructs it and hands
+ * it to every View), so every route a wire message can arrive by — the live
+ * subscription, View history pagination, the agent's hydration walks — feeds
+ * the same decoder. The decoder's version-guarded stream trackers then make
+ * re-delivery across routes (an attach-boundary in-flight stream, a replayed
+ * history page) decode to nothing instead of double-folding. The delivery's
+ * `version.serial` is also threaded into the Tree, whose per-entry
+ * `decodedThrough` high-water-mark drops whole-wire replays that no decoder
+ * state can see (stateless discrete re-decodes).
+ */
+
+import type * as Ably from 'ably';
+
+import { HEADER_RUN_ID } from '../../constants.js';
+import { getTransportHeaders } from '../../utils.js';
+import type { CodecInputEvent, CodecOutputEvent, Decoder } from '../codec/types.js';
+import { isRunLifecycleName, parseRunLifecycle } from './headers.js';
+import type { TreeInternal } from './tree.js';
+import type { RunLifecycleEvent } from './types.js';
+
+/**
+ * The decode-and-apply engine for one Tree: a single codec decoder bound to a
+ * single Tree, shared by every route that feeds the Tree wire messages.
+ */
+export interface WireApplier {
+  /**
+   * Apply one inbound wire message to the bound tree.
+   *
+   * Run-lifecycle messages are turned into a {@link RunLifecycleEvent} via
+   * {@link parseRunLifecycle} and applied with `applyRunLifecycle`; everything
+   * else is decoded with the bound 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 rawMsg - The inbound Ably wire message.
+   * @returns The parsed run-lifecycle event, or `undefined`.
+   */
+  apply(rawMsg: Ably.InboundMessage): RunLifecycleEvent | undefined;
+}
+
+/**
+ * Classify, decode, and apply one inbound wire message to the tree. See
+ * {@link WireApplier.apply} for the contract.
+ * @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`.
+ */
+const applyWireMessage = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection>(
+  tree: TreeInternal<TInput, TOutput, TProjection>,
+  decoder: Decoder<TInput, TOutput>,
+  rawMsg: Ably.InboundMessage,
+): RunLifecycleEvent | undefined => {
+  const headers = getTransportHeaders(rawMsg);
+  const serial = rawMsg.serial;
+  // Top-level timestamp — the message's create time on every delivery (an
+  // append's own receive time lives in `version.timestamp`). The retention
+  // clock is sound on this timeline because run-end, a fresh create published
+  // after every wire of its run, bounds the node's last activity.
+  const timestamp = rawMsg.timestamp;
+
+  if (isRunLifecycleName(rawMsg.name)) {
+    const event = parseRunLifecycle(rawMsg.name, headers, serial, timestamp);
+    if (event) tree.applyRunLifecycle(event);
+    return event;
+  }
+
+  const { inputs, outputs } = decoder.decode(rawMsg);
+  if (inputs.length > 0 || outputs.length > 0 || headers[HEADER_RUN_ID]) {
+    tree.applyMessage({ inputs, outputs }, headers, serial, timestamp, rawMsg.version.serial);
+  }
+  return undefined;
+};
+
+/**
+ * Bind a Tree and a decoder into the Tree's single {@link WireApplier}.
+ * @param tree - The tree the applier feeds.
+ * @param decoder - The codec decoder shared by every route into the tree.
+ * @returns The applier.
+ */
+export const createWireApplier = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection>(
+  tree: TreeInternal<TInput, TOutput, TProjection>,
+  decoder: Decoder<TInput, TOutput>,
+): WireApplier => ({
+  apply: (rawMsg: Ably.InboundMessage): RunLifecycleEvent | undefined => applyWireMessage(tree, decoder, rawMsg),
+});

package/src/core/transport/headers.ts

@@ -1,50 +1,262 @@
 /**
  * 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).
+ * Single source of truth for which transport headers every transport
+ * message carries. Used by the agent session (pipe) and by
+ * the client session (optimistic message stamping).
  */
 
+import * as Ably from 'ably';
+
 import {
-  HEADER_AMEND,
+  EVENT_RUN_END,
+  EVENT_RUN_RESUME,
+  EVENT_RUN_START,
+  EVENT_RUN_SUSPEND,
+  HEADER_CODEC_MESSAGE_ID,
+  HEADER_ERROR_CODE,
+  HEADER_ERROR_MESSAGE,
+  HEADER_EVENT_ID,
   HEADER_FORK_OF,
-  HEADER_MSG_ID,
+  HEADER_INPUT_CLIENT_ID,
+  HEADER_INPUT_CODEC_MESSAGE_ID,
+  HEADER_INVOCATION_ID,
+  HEADER_MSG_REGENERATE,
   HEADER_PARENT,
   HEADER_ROLE,
-  HEADER_TURN_CLIENT_ID,
-  HEADER_TURN_ID,
+  HEADER_RUN_CLIENT_ID,
+  HEADER_RUN_ID,
+  HEADER_RUN_REASON,
 } from '../../constants.js';
+import { ErrorCode } from '../../errors.js';
+import type { 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 const buildTransportHeaders = (opts: {
   role: string;
-  turnId: string;
-  msgId: string;
-  turnClientId?: string;
+  runId?: string;
+  codecMessageId: string;
+  runClientId?: string;
   parent?: string;
   forkOf?: string;
-  amend?: string;
+  regenerates?: string;
+  invocationId?: string;
+  inputClientId?: string;
+  inputCodecMessageId?: string;
+  inputEventId?: string;
 }): Record<string, string> => {
   const h: Record<string, string> = {
     [HEADER_ROLE]: opts.role,
-    [HEADER_TURN_ID]: opts.turnId,
-    [HEADER_MSG_ID]: opts.msgId,
+    [HEADER_CODEC_MESSAGE_ID]: opts.codecMessageId,
   };
-  if (opts.turnClientId !== undefined) h[HEADER_TURN_CLIENT_ID] = opts.turnClientId;
+  if (opts.runId !== undefined) h[HEADER_RUN_ID] = opts.runId;
+  if (opts.runClientId !== undefined) h[HEADER_RUN_CLIENT_ID] = opts.runClientId;
   if (opts.parent) h[HEADER_PARENT] = opts.parent;
   if (opts.forkOf) h[HEADER_FORK_OF] = opts.forkOf;
-  if (opts.amend) h[HEADER_AMEND] = opts.amend;
+  if (opts.regenerates) h[HEADER_MSG_REGENERATE] = opts.regenerates;
+  if (opts.invocationId) h[HEADER_INVOCATION_ID] = opts.invocationId;
+  if (opts.inputClientId !== undefined) h[HEADER_INPUT_CLIENT_ID] = opts.inputClientId;
+  if (opts.inputCodecMessageId !== undefined) h[HEADER_INPUT_CODEC_MESSAGE_ID] = opts.inputCodecMessageId;
+  if (opts.inputEventId) h[HEADER_EVENT_ID] = opts.inputEventId;
+  return h;
+};
+
+/**
+ * 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.
+ * @param opts.errorCode - Numeric error code stamped as `error-code` on
+ *   run-end. Set only when the run ended in error and the agent supplied an
+ *   error to surface; gives codec-agnostic consumers a baseline failure detail.
+ * @param opts.errorMessage - Error message stamped as `error-message` on
+ *   run-end. Paired with `errorCode`; set under the same condition.
+ * @returns A headers record with the lifecycle headers set.
+ */
+export const buildLifecycleHeaders = (opts: {
+  runId: string;
+  runClientId: string;
+  parent?: string;
+  forkOf?: string;
+  regenerates?: string;
+  invocationId?: string;
+  inputClientId?: string;
+  inputCodecMessageId?: string;
+  reason?: RunEndReason;
+  errorCode?: number;
+  errorMessage?: string;
+}): Record<string, string> => {
+  const h: Record<string, string> = {
+    [HEADER_RUN_ID]: opts.runId,
+    [HEADER_RUN_CLIENT_ID]: opts.runClientId,
+  };
+  if (opts.reason !== undefined) h[HEADER_RUN_REASON] = opts.reason;
+  if (opts.parent !== undefined) h[HEADER_PARENT] = opts.parent;
+  if (opts.forkOf !== undefined) h[HEADER_FORK_OF] = opts.forkOf;
+  if (opts.regenerates !== undefined) h[HEADER_MSG_REGENERATE] = opts.regenerates;
+  if (opts.invocationId !== undefined) h[HEADER_INVOCATION_ID] = opts.invocationId;
+  if (opts.inputClientId !== undefined) h[HEADER_INPUT_CLIENT_ID] = opts.inputClientId;
+  if (opts.inputCodecMessageId !== undefined) h[HEADER_INPUT_CODEC_MESSAGE_ID] = opts.inputCodecMessageId;
+  if (opts.errorCode !== undefined) h[HEADER_ERROR_CODE] = String(opts.errorCode);
+  if (opts.errorMessage !== undefined) h[HEADER_ERROR_MESSAGE] = opts.errorMessage;
   return h;
 };
+
+/** 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 const isRunLifecycleName = (name: string | undefined): name is RunLifecycleName =>
+  name === EVENT_RUN_START || name === EVENT_RUN_SUSPEND || name === EVENT_RUN_RESUME || name === EVENT_RUN_END;
+
+/**
+ * Reconstruct the terminal `Ably.ErrorInfo` for a run that ended in error, from
+ * its run-end transport headers. Reads the `error-code` / `error-message`
+ * headers the agent stamps (see {@link buildLifecycleHeaders}); falls back to a
+ * generic code/message when a run ended in error without detail. Single source
+ * of truth for the header→ErrorInfo derivation, shared by the client session's
+ * `on('error')` emit and the Tree's `RunInfo.error`.
+ * @param headers - Transport headers from the inbound run-end message.
+ * @returns The reconstructed terminal error.
+ */
+export const buildRunEndError = (headers: Record<string, string>): Ably.ErrorInfo => {
+  const codeRaw = headers[HEADER_ERROR_CODE];
+  const parsedCode = codeRaw === undefined ? Number.NaN : Number(codeRaw);
+  const code = Number.isFinite(parsedCode) ? parsedCode : ErrorCode.SessionSubscriptionError;
+  const message = headers[HEADER_ERROR_MESSAGE] ?? 'agent reported an error';
+  // 5-digit codes encode their HTTP status in the leading 3 digits; otherwise 500.
+  const statusCode = code >= 10000 && code < 60000 ? Math.floor(code / 100) : 500;
+  return new Ably.ErrorInfo(message, code, statusCode);
+};
+
+/**
+ * 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.
+ * @param timestamp - Ably server timestamp (epoch ms) of the message, or
+ *   `undefined` for an optimistic local event. Stamped onto the returned
+ *   event; drives the Tree's event-log retention clock.
+ * @returns The lifecycle event, or `undefined` when `name` is not a
+ *   run-lifecycle event name or the message carries no `run-id`.
+ */
+export const parseRunLifecycle = (
+  name: string,
+  headers: Record<string, string>,
+  serial: string | undefined,
+  timestamp: number | undefined,
+): RunLifecycleEvent | undefined => {
+  const runId = headers[HEADER_RUN_ID];
+  if (!runId) return undefined;
+
+  const clientId = headers[HEADER_RUN_CLIENT_ID] ?? '';
+  const stamped = timestamp === undefined ? {} : { timestamp };
+
+  if (name === EVENT_RUN_START) {
+    const parent = headers[HEADER_PARENT];
+    const forkOf = headers[HEADER_FORK_OF];
+    const regenerates = headers[HEADER_MSG_REGENERATE];
+    return {
+      type: 'start',
+      runId,
+      clientId,
+      serial,
+      invocationId: headers[HEADER_INVOCATION_ID] ?? '',
+      ...stamped,
+      ...(parent !== undefined && { parent }),
+      ...(forkOf !== undefined && { forkOf }),
+      ...(regenerates !== undefined && { regenerates }),
+    };
+  }
+
+  if (name === EVENT_RUN_SUSPEND) {
+    return { type: 'suspend', runId, clientId, serial, invocationId: headers[HEADER_INVOCATION_ID] ?? '', ...stamped };
+  }
+
+  if (name === EVENT_RUN_RESUME) {
+    return { type: 'resume', runId, clientId, serial, invocationId: headers[HEADER_INVOCATION_ID] ?? '', ...stamped };
+  }
+
+  if (name === EVENT_RUN_END) {
+    // CAST: agent always writes a valid RunEndReason; default to 'complete' for robustness.
+    const reason = (headers[HEADER_RUN_REASON] ?? 'complete') as RunEndReason;
+    const invocationId = headers[HEADER_INVOCATION_ID] ?? '';
+    if (reason === 'error') {
+      return {
+        type: 'end',
+        runId,
+        clientId,
+        serial,
+        invocationId,
+        reason,
+        ...stamped,
+        error: buildRunEndError(headers),
+      };
+    }
+    return { type: 'end', runId, clientId, serial, invocationId, reason, ...stamped };
+  }
+
+  return undefined;
+};

package/src/core/transport/index.ts

@@ -1,42 +1,42 @@
 // Shared types
 export type {
-  ActiveTurn,
-  AddMessageOptions,
-  AddMessagesResult,
-  CancelFilter,
+  ActiveRun,
+  AgentSession,
+  AgentSessionOptions,
+  BranchSelection,
   CancelRequest,
-  ClientTransport,
-  ClientTransportOptions,
-  CloseOptions,
-  EventsNode,
+  ClientSession,
+  ClientSessionOptions,
+  ConversationNode,
+  InputNode,
+  LoadConversationOptions,
   MessageNode,
-  NewTurnOptions,
+  OutputEvent,
+  PipeOptions,
+  Run,
+  RunEndParams,
+  RunEndReason,
+  RunInfo,
+  RunLifecycleEvent,
+  RunNode,
+  RunNodeState,
+  RunRuntime,
+  RunView,
   SendOptions,
-  ServerTransport,
-  ServerTransportOptions,
-  StreamResponseOptions,
   StreamResult,
   Tree,
-  Turn,
-  TurnEndReason,
-  TurnLifecycleEvent,
   View,
 } from './types.js';
 
-// Deprecated aliases — intentional re-export of deprecated types for backwards compatibility.
-// eslint-disable-next-line @typescript-eslint/no-deprecated
-export type { EventNode } from './types.js';
-// eslint-disable-next-line @typescript-eslint/no-deprecated
-export type { TreeNode } from './types.js';
+// Invocation
+export type { InvocationData } from './invocation.js';
+export { Invocation } from './invocation.js';
 
-// Internal tree interface (consumed by View implementations)
-export type { TreeInternal } from './tree.js';
+// Agent session
+export { createAgentSession } from './agent-session.js';
 
-// Server transport
-export { createServerTransport } from './server-transport.js';
-
-// Client transport
-export { createClientTransport } from './client-transport.js';
+// Client session
+export { createClientSession } from './client-session.js';
 
 // Header builder
 export { buildTransportHeaders } from './headers.js';

package/src/core/transport/internal/bounded-map.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 const evictOldestIfFull = <K, V>(map: Map<K, V>, key: K, limit: number): K | undefined => {
+  if (map.has(key) || map.size < limit) return undefined;
+  const oldest = map.keys().next().value;
+  if (oldest === undefined) return undefined;
+  map.delete(oldest);
+  return oldest;
+};

package/src/core/transport/invocation.ts

@@ -0,0 +1,98 @@
+/**
+ * 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.loadConversation(); // walk channel history into the session tree
+ * 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
+// ---------------------------------------------------------------------------
+
+/**
+ * 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
+// ---------------------------------------------------------------------------
+
+/**
+ * Runtime view of an {@link InvocationData}. Constructed via
+ * {@link Invocation.fromJSON}. Read-only; carries no behaviour beyond
+ * exposing its fields.
+ */
+// Spec: AIT-ST13
+export 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(data: InvocationData) {
+    this.inputEventId = data.inputEventId;
+    this.sessionName = data.sessionName;
+  }
+
+  /**
+   * 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 {
+    return new Invocation(data);
+  }
+
+  /**
+   * 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 {
+    return {
+      inputEventId: this.inputEventId,
+      sessionName: this.sessionName,
+    };
+  }
+}