@ably/ai-transport 0.0.1 → 0.2.0

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

@@ -0,0 +1,91 @@
+/**
+ * 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';
+
+import { HEADER_RUN_ID } from '../../constants.js';
+import { getTransportHeaders } from '../../utils.js';
+import type { Codec, 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';
+
+/**
+ * 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 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;
+
+  if (isRunLifecycleName(rawMsg.name)) {
+    const event = parseRunLifecycle(rawMsg.name, headers, serial);
+    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);
+  }
+  return 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 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 => {
+  const { inputs, outputs } = decoder.decode(rawMsg);
+  let next = projection;
+  for (const event of [...inputs, ...outputs]) {
+    next = codec.fold(next, event, { serial: rawMsg.serial ?? '', messageId });
+  }
+  return next;
+};

package/src/core/transport/headers.ts

@@ -1,46 +1,209 @@
 /**
  * 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, addEvents) and by
+ * the client session (optimistic message stamping).
  */
 
 import {
+  EVENT_RUN_END,
+  EVENT_RUN_RESUME,
+  EVENT_RUN_START,
+  EVENT_RUN_SUSPEND,
+  HEADER_CODEC_MESSAGE_ID,
+  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 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). Null means root.
- * @param opts.forkOf - Forked message's msg-id (for edit/regen).
- * @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;
-  parent?: string | null;
+  runId?: string;
+  codecMessageId: string;
+  runClientId?: string;
+  parent?: string;
   forkOf?: 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.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.
+ * @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;
+}): 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;
+  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;
+
+/**
+ * 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 const parseRunLifecycle = (
+  name: string,
+  headers: Record<string, string>,
+  serial: string | undefined,
+): RunLifecycleEvent | undefined => {
+  const runId = headers[HEADER_RUN_ID];
+  if (!runId) return undefined;
+
+  const clientId = headers[HEADER_RUN_CLIENT_ID] ?? '';
+
+  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] ?? '',
+      ...(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] ?? '' };
+  }
+
+  if (name === EVENT_RUN_RESUME) {
+    return { type: 'resume', runId, clientId, serial, invocationId: headers[HEADER_INVOCATION_ID] ?? '' };
+  }
+
+  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;
+    return { type: 'end', runId, clientId, serial, invocationId: headers[HEADER_INVOCATION_ID] ?? '', reason };
+  }
+
+  return undefined;
+};

package/src/core/transport/index.ts

@@ -1,34 +1,41 @@
 // Shared types
 export type {
-  ActiveTurn,
-  AddMessageOptions,
-  AddMessagesResult,
-  CancelFilter,
+  ActiveRun,
+  AgentSession,
+  AgentSessionOptions,
+  BranchSelection,
   CancelRequest,
-  ClientTransport,
-  ClientTransportOptions,
-  CloseOptions,
+  ClientSession,
+  ClientSessionOptions,
   ConversationNode,
-  ConversationTree,
-  LoadHistoryOptions,
-  MessageWithHeaders,
-  NewTurnOptions,
-  PaginatedMessages,
+  EventsNode,
+  InputNode,
+  LoadConversationOptions,
+  MessageNode,
+  OutputEvent,
+  PipeOptions,
+  Run,
+  RunEndReason,
+  RunInfo,
+  RunLifecycleEvent,
+  RunNode,
+  RunRuntime,
+  RunView,
   SendOptions,
-  ServerTransport,
-  ServerTransportOptions,
-  StreamResponseOptions,
   StreamResult,
-  Turn,
-  TurnEndReason,
-  TurnLifecycleEvent,
+  Tree,
+  View,
 } from './types.js';
 
-// Server transport
-export { createServerTransport } from './server-transport.js';
+// Invocation
+export type { InvocationData } from './invocation.js';
+export { Invocation } from './invocation.js';
 
-// Client transport
-export { createClientTransport } from './client-transport.js';
+// Agent session
+export { createAgentSession } from './agent-session.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.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
+// ---------------------------------------------------------------------------
+
+/**
+ * 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,
+    };
+  }
+}