@ably/ai-transport 0.1.0 → 0.2.0

package/src/react/use-view.ts

@@ -1,33 +1,52 @@
 /**
  * useView — reactive paginated view of the conversation.
  *
- * Subscribes to view updates and exposes the visible nodes, branch navigation,
- * write operations, pagination state, and a `loadOlder` callback. Pass `transport`
- * to use a transport's default view, or `view` to subscribe to a specific
- * {@link View} directly. When both are omitted, defaults to the nearest
- * {@link TransportProvider}'s transport via context.
+ * Subscribes to view updates and exposes the visible messages, msg-anchored
+ * branch navigation, write operations, pagination state, and a `loadOlder`
+ * callback. Pass `session` to use a session's default view, or `view` to
+ * subscribe to a specific {@link View} directly. When both are omitted,
+ * defaults to the nearest {@link ClientSessionProvider}'s session via context.
  */
 
 import * as Ably from 'ably';
-import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 
-import type { ActiveTurn, ClientTransport, MessageNode, SendOptions, View } from '../core/transport/types.js';
+import type { CodecInputEvent, CodecMessage, CodecOutputEvent } from '../core/codec/types.js';
+import type { ActiveRun, BranchSelection, RunInfo, SendOptions, View } from '../core/transport/types.js';
 import { ErrorCode } from '../errors.js';
-import { NearestTransportContext } from './contexts/transport-context.js';
+import type { BaseSessionOption } from './internal/use-resolved-session.js';
+import { useResolvedSession } from './internal/use-resolved-session.js';
 
-/** Options for configuring the view's initial load behavior. */
-export interface UseViewOptions {
-  /** Maximum number of older messages to load per page. Defaults to 100. */
+/** Options for {@link useView}. */
+export interface UseViewOptions<
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+> extends BaseSessionOption<TInput, TOutput, TProjection, TMessage> {
+  /** A specific {@link View} to subscribe to directly. Takes priority over `session`. */
+  view?: View<TInput, TMessage> | null;
+  /** Maximum number of older Runs to reveal per page (the pagination unit is the Run, not the message). When provided, auto-loads the first page on mount. */
   limit?: number;
+  /** When `true`, skip all subscriptions and return an empty handle immediately. */
+  skip?: boolean;
 }
 
 /** Handle for the paginated, branch-aware conversation view. */
-export interface ViewHandle<TEvent, TMessage> {
-  /** The visible domain messages along the selected branch. */
-  messages: TMessage[];
-  /** Visible conversation nodes along the selected branch. */
-  nodes: MessageNode<TMessage>[];
-  /** Whether there are older messages that can be revealed via `loadOlder`. */
+export interface ViewHandle<TInput extends CodecInputEvent, TMessage> {
+  /**
+   * The visible messages along the selected branch, concatenated across all
+   * visible Runs, each paired with its codec-message-id (see
+   * {@link CodecMessage}). Read the domain object from each entry's
+   * `message` field.
+   *
+   * Correlate a rendered message back to the View — `runOf`,
+   * `branchSelection`, `selectSibling`, `regenerate`, or `edit` — via its
+   * `codecMessageId`, which the SDK assigns and tracks independently of any
+   * identity the domain `message` may carry. See {@link View.getMessages}.
+   */
+  messages: CodecMessage<TMessage>[];
+  /** Whether there are older Runs that can be revealed via `loadOlder`. */
   hasOlder: boolean;
   /** Whether a page load is currently in progress. */
   loading: boolean;
@@ -39,65 +58,90 @@ export interface ViewHandle<TEvent, TMessage> {
   loadError: Ably.ErrorInfo | undefined;
   /**
    * Load older messages into the view. No-op if already loading.
-   * On failure, `error` is set; on success, `error` is cleared.
+   * On failure, `loadError` is set; on success, `loadError` is cleared.
    */
   loadOlder: () => Promise<void>;
-  /** Select a sibling at a fork point by index. Triggers a view update with the new branch. */
-  select: (msgId: string, index: number) => void;
-  /** Index of the currently selected sibling at a fork point. */
-  getSelectedIndex: (msgId: string) => number;
-  /** Get all sibling messages at a fork point, ordered chronologically by serial. */
-  getSiblings: (msgId: string) => TMessage[];
-  /** Whether a message has sibling alternatives (i.e., show navigation arrows). */
-  hasSiblings: (msgId: string) => boolean;
-  /** Get a node by msgId, or undefined if not found. */
-  getNode: (msgId: string) => MessageNode<TMessage> | undefined;
-  /** Send one or more messages in the context of this view's selected branch. */
-  send: (messages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
-  /** Regenerate an assistant message, using this view's branch for history. */
-  regenerate: (messageId: string, options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
-  /** Edit a user message, forking from this view's branch. */
-  edit: (messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
-  /** Amend an existing message and start a continuation turn (e.g. tool results). */
-  update: (msgId: string, events: TEvent[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>;
+  /**
+   * Look up the {@link RunInfo} for the Run that owns `codecMessageId`.
+   * Returns `undefined` when the codec-message-id hasn't been observed.
+   * See {@link View.runOf}.
+   */
+  runOf: (codecMessageId: string) => RunInfo | undefined;
+  /**
+   * Direct lookup by runId. Returns `undefined` when the Run hasn't been
+   * observed. See {@link View.run}.
+   */
+  run: (runId: string) => RunInfo | undefined;
+  /**
+   * Snapshot of the visible Runs along the selected branch, in
+   * chronological order. Returns `[]` when the view isn't resolved.
+   * See {@link View.runs}.
+   */
+  runs: () => RunInfo[];
+  /**
+   * Resolve the {@link BranchSelection} bundle anchored at
+   * `codecMessageId`. Always returns a safe object — see
+   * {@link BranchSelection}. See {@link View.branchSelection}.
+   */
+  branchSelection: (codecMessageId: string) => BranchSelection<TMessage>;
+  /**
+   * Select a sibling at the branch point anchored at `codecMessageId`.
+   * `index` is clamped to `[0, siblings.length - 1]`. Silent no-op when
+   * `codecMessageId` isn't a branch anchor. See {@link View.selectSibling}.
+   */
+  selectSibling: (codecMessageId: string, index: number) => void;
+  /**
+   * Send one or more TInputs on the channel and fire a POST. See {@link View.send}.
+   * @throws Ably.ErrorInfo with code {@link ErrorCode.InvalidArgument} when no view is resolved (before the session is available, or when `skip` is `true`).
+   */
+  send: (events: TInput | TInput[], options?: SendOptions) => Promise<ActiveRun>;
+  /**
+   * Regenerate an assistant message, using this view's branch for history.
+   * @throws Ably.ErrorInfo with code {@link ErrorCode.InvalidArgument} when no view is resolved (before the session is available, or when `skip` is `true`).
+   */
+  regenerate: (messageId: string, options?: SendOptions) => Promise<ActiveRun>;
+  /**
+   * Edit a user message, forking from this view's branch.
+   * Rejects with an `Ably.ErrorInfo` (code {@link ErrorCode.InvalidArgument}) if no view is resolved — e.g. before the session is available, or when `skip` is `true`.
+   */
+  edit: (messageId: string, inputs: TInput | TInput[], options?: SendOptions) => Promise<ActiveRun>;
 }
 
 /**
- * Subscribe to a view and return the visible node list with pagination, navigation, and write operations.
+ * Fallback returned by `branchSelection` when the view isn't resolved.
+ * Same shape the view returns for an unknown codec-message-id, so callers
+ * can destructure uniformly.
+ */
+const EMPTY_BRANCH_SELECTION: BranchSelection<never> = {
+  hasSiblings: false,
+  siblings: [],
+  index: 0,
+  selected: undefined,
+};
+
+/**
+ * Subscribe to a view and return the visible messages with pagination, navigation, and write operations.
  *
- * `view` takes priority over `transport`. When neither is provided, the nearest
- * {@link TransportProvider}'s transport is used. When `limit` is provided, auto-loads
+ * `view` takes priority over `session`. When neither is provided, the nearest
+ * {@link ClientSessionProvider}'s session is used. When `limit` is provided, auto-loads
  * the first page on mount (SWR-style).
  * @param props - Options for selecting the view source and configuring auto-load.
- * @param props.transport - Client transport whose default view to subscribe to; defaults to the nearest provider.
- * @param props.view - A specific {@link View} to subscribe to directly. Takes priority over `transport`.
- * @param props.limit - Max older messages per page; when provided, auto-loads on mount.
+ * @param props.session - Client session whose default view to subscribe to; defaults to the nearest provider.
+ * @param props.view - A specific {@link View} to subscribe to directly. Takes priority over `session`.
+ * @param props.limit - Max older Runs to reveal per page; when provided, auto-loads the first page on mount.
  * @param props.skip - When `true`, skip all subscriptions and return an empty handle.
- * @returns A {@link ViewHandle} with nodes, pagination state, navigation, write operations, and loadOlder.
+ * @returns A {@link ViewHandle} with messages, pagination state, navigation, write operations, and loadOlder.
  */
-export const useView = <TEvent, TMessage>({
-  transport,
+export const useView = <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({
+  session,
   view,
   limit,
   skip,
-}: {
-  /** Client transport whose default view to subscribe to; defaults to the nearest provider when omitted. */
-  transport?: ClientTransport<TEvent, TMessage> | null;
-  /** A specific {@link View} to subscribe to directly. Takes priority over `transport`. */
-  view?: View<TEvent, TMessage> | null;
-  /** When provided, auto-loads the first page on mount. Omit for manual loading. */
-  limit?: number;
-  /** When `true`, skip all subscriptions and return an empty handle immediately. */
-  skip?: boolean;
-} = {}): ViewHandle<TEvent, TMessage> => {
-  const nearestSlot = useContext(NearestTransportContext);
-  // CAST: NearestTransportContext stores transport with erased generics; types fixed at call site.
-  const resolvedTransport = skip
-    ? undefined
-    : (transport ?? (nearestSlot?.transport as unknown as ClientTransport<TEvent, TMessage> | undefined));
-  const resolvedView = skip ? undefined : (view ?? resolvedTransport?.view);
-
-  const [nodes, setNodes] = useState<MessageNode<TMessage>[]>(() => resolvedView?.flattenNodes() ?? []);
+}: UseViewOptions<TInput, TOutput, TProjection, TMessage> = {}): ViewHandle<TInput, TMessage> => {
+  const resolvedSession = useResolvedSession({ session, skip });
+  const resolvedView = skip ? undefined : (view ?? resolvedSession?.view);
+
+  const [messages, setMessages] = useState<CodecMessage<TMessage>[]>(() => resolvedView?.getMessages() ?? []);
   const [hasOlder, setHasOlder] = useState(() => resolvedView?.hasOlder() ?? false);
   const [loading, setLoading] = useState(false);
   const [loadError, setLoadError] = useState<Ably.ErrorInfo | undefined>();
@@ -112,7 +156,7 @@ export const useView = <TEvent, TMessage>({
   // Subscribe to view updates
   useEffect(() => {
     if (!resolvedView) {
-      setNodes([]);
+      setMessages([]);
       setHasOlder(false);
       setLoadError(undefined);
       return;
@@ -122,12 +166,12 @@ export const useView = <TEvent, TMessage>({
     autoLoadedRef.current = false;
 
     // Sync initial state
-    setNodes(resolvedView.flattenNodes());
+    setMessages(resolvedView.getMessages());
     setHasOlder(resolvedView.hasOlder());
     setLoadError(undefined);
 
     const unsub = resolvedView.on('update', () => {
-      setNodes(resolvedView.flattenNodes());
+      setMessages(resolvedView.getMessages());
       setHasOlder(resolvedView.hasOlder());
     });
     return unsub;
@@ -158,30 +202,39 @@ export const useView = <TEvent, TMessage>({
     void loadOlder();
   }, [autoLoad, resolvedView, loadOlder]);
 
-  const messages = useMemo(() => nodes.map((n) => n.message), [nodes]);
-
-  // Branch navigation callbacks
-  const select = useCallback(
-    (msgId: string, index: number) => {
-      resolvedView?.select(msgId, index);
-    },
+  // Run lookups
+  const runOf = useCallback(
+    (codecMessageId: string): RunInfo | undefined => resolvedView?.runOf(codecMessageId),
     [resolvedView],
   );
 
-  const getSelectedIndex = useCallback((msgId: string) => resolvedView?.getSelectedIndex(msgId) ?? 0, [resolvedView]);
+  const run = useCallback((runId: string): RunInfo | undefined => resolvedView?.run(runId), [resolvedView]);
 
-  const getSiblings = useCallback((msgId: string) => resolvedView?.getSiblings(msgId) ?? [], [resolvedView]);
+  const runs = useCallback((): RunInfo[] => resolvedView?.runs() ?? [], [resolvedView]);
 
-  const hasSiblings = useCallback((msgId: string) => resolvedView?.hasSiblings(msgId) ?? false, [resolvedView]);
+  // Branch navigation
+  const branchSelection = useCallback(
+    (codecMessageId: string): BranchSelection<TMessage> =>
+      // CAST: `EMPTY_BRANCH_SELECTION` is typed `BranchSelection<never>`; `never` is
+      // assignable to any `TMessage`, so the empty bundle is a valid fallback for
+      // the not-yet-resolved view case.
+      resolvedView?.branchSelection(codecMessageId) ?? (EMPTY_BRANCH_SELECTION as BranchSelection<TMessage>),
+    [resolvedView],
+  );
 
-  const getNode = useCallback((msgId: string) => resolvedView?.getNode(msgId), [resolvedView]);
+  const selectSibling = useCallback(
+    (codecMessageId: string, index: number) => {
+      resolvedView?.selectSibling(codecMessageId, index);
+    },
+    [resolvedView],
+  );
 
   // Write operation callbacks
   const send = useCallback(
-    async (msgs: TMessage | TMessage[], opts?: SendOptions) => {
+    async (events: TInput | TInput[], opts?: SendOptions) => {
       if (!resolvedView)
         throw new Ably.ErrorInfo('unable to send; view is not available', ErrorCode.InvalidArgument, 400);
-      return resolvedView.send(msgs, opts);
+      return resolvedView.send(events, opts);
     },
     [resolvedView],
   );
@@ -196,38 +249,27 @@ export const useView = <TEvent, TMessage>({
   );
 
   const edit = useCallback(
-    async (messageId: string, newMessages: TMessage | TMessage[], opts?: SendOptions) => {
+    async (messageId: string, inputs: TInput | TInput[], opts?: SendOptions) => {
       if (!resolvedView)
         throw new Ably.ErrorInfo('unable to edit; view is not available', ErrorCode.InvalidArgument, 400);
-      return resolvedView.edit(messageId, newMessages, opts);
-    },
-    [resolvedView],
-  );
-
-  const update = useCallback(
-    async (msgId: string, events: TEvent[], opts?: SendOptions) => {
-      if (!resolvedView)
-        throw new Ably.ErrorInfo('unable to update; view is not available', ErrorCode.InvalidArgument, 400);
-      return resolvedView.update(msgId, events, opts);
+      return resolvedView.edit(messageId, inputs, opts);
     },
     [resolvedView],
   );
 
   return {
     messages,
-    nodes,
     hasOlder,
     loading,
     loadError,
     loadOlder,
-    select,
-    getSelectedIndex,
-    getSiblings,
-    hasSiblings,
-    getNode,
+    runOf,
+    run,
+    runs,
+    branchSelection,
+    selectSibling,
     send,
     regenerate,
     edit,
-    update,
   };
 };

package/src/utils.ts

@@ -8,24 +8,48 @@
 
 import type * as Ably from 'ably';
 
-import { DOMAIN_HEADER_PREFIX } from './constants.js';
-
 /**
- * Extract extras.headers from an Ably InboundMessage.
- * @param message - The Ably message to extract headers from.
- * @returns The headers record, or an empty object if absent.
+ * Read one tier of the SDK's `extras.ai` namespace from an Ably message.
+ * `extras.ai` is the SDK's reserved corner of the message envelope, split into
+ * a `transport` tier (generic transport headers) and a `codec` tier (codec
+ * headers). The application's own `extras.headers` is deliberately left
+ * untouched.
+ * @param message - The Ably message to read from.
+ * @param tier - Which `extras.ai` sub-namespace to read.
+ * @returns The tier's headers record, or an empty object if absent.
  */
-export const getHeaders = (message: Ably.InboundMessage): Record<string, string> => {
+const getAiTier = (message: Ably.InboundMessage, tier: 'transport' | 'codec'): Record<string, string> => {
   // CAST: Ably SDK types `extras` as `any`; runtime checks below guard access.
   const extras = message.extras as unknown;
   if (!extras || typeof extras !== 'object') return {};
-  const headers = (extras as { headers?: unknown }).headers;
-  if (!headers || typeof headers !== 'object') return {};
-  // CAST: Ably wire protocol guarantees headers is Record<string, string>
+  const ai = (extras as { ai?: unknown }).ai;
+  if (!ai || typeof ai !== 'object') return {};
+  const sub = (ai as Record<string, unknown>)[tier];
+  if (!sub || typeof sub !== 'object') return {};
+  // CAST: Ably wire protocol guarantees the tier is Record<string, string>
   // when present, verified by the runtime guards above.
-  return headers as Record<string, string>;
+  return sub as Record<string, string>;
 };
 
+/**
+ * Extract the transport-tier headers (`extras.ai.transport`) from an Ably
+ * InboundMessage. These are the generic transport headers (run/stream/identity/
+ * branching), set and read by the transport layer.
+ * @param message - The Ably message to extract headers from.
+ * @returns The transport headers record, or an empty object if absent.
+ */
+export const getTransportHeaders = (message: Ably.InboundMessage): Record<string, string> =>
+  getAiTier(message, 'transport');
+
+/**
+ * Extract the codec-tier headers (`extras.ai.codec`) from an Ably
+ * InboundMessage. These are the codec's own headers, with no prefix — the
+ * tier isolates them from transport headers.
+ * @param message - The Ably message to extract headers from.
+ * @returns The codec headers record, or an empty object if absent.
+ */
+export const getCodecHeaders = (message: Ably.InboundMessage): Record<string, string> => getAiTier(message, 'codec');
+
 /**
  * Parse a JSON string, returning undefined on failure.
  * @param value - The JSON string to parse.
@@ -58,18 +82,6 @@ export const setIfPresent = (headers: Record<string, string>, key: string, value
   }
 };
 
-/**
- * Set multiple headers at once, skipping entries whose values are undefined or null.
- * Each value is converted using the same rules as {@link setIfPresent}.
- * @param headers - The headers object to mutate.
- * @param entries - Key-value pairs to set.
- */
-export const setHeadersIfPresent = (headers: Record<string, string>, entries: Record<string, unknown>): void => {
-  for (const [key, value] of Object.entries(entries)) {
-    setIfPresent(headers, key, value);
-  }
-};
-
 /**
  * Merge two header records into a new object. Later values override earlier ones.
  * Undefined inputs are treated as empty.
@@ -95,30 +107,36 @@ export const parseBool = (value: string | undefined): boolean | undefined => {
   return value === 'true';
 };
 
+/** A record carrying an optional Ably `serial`, orderable by {@link compareBySerial}. */
+interface HasSerial {
+  /** Ably serial, or undefined if the server has not yet assigned one. */
+  readonly serial?: string;
+}
+
 /**
- * Build a domain headers record from key-value pairs. Each key is automatically
- * prefixed with {@link DOMAIN_HEADER_PREFIX}. Values that are undefined or null
- * are skipped; strings are set directly; booleans, numbers, and objects are
- * converted using the same rules as {@link setIfPresent}.
- * @param entries - Unprefixed key-value pairs (e.g. `{ toolCallId: 'tc-1' }` becomes `{ 'x-domain-toolCallId': 'tc-1' }`).
- * @returns A new headers record with prefixed keys.
+ * Comparator that orders records by their Ably `serial` ascending
+ * (chronological). Serials are lexicographically comparable; records whose
+ * serial is undefined sort last. Pass directly to `Array.prototype.sort`.
+ * @param a - First record to compare.
+ * @param b - Second record to compare.
+ * @returns Negative if `a` precedes `b`, positive if `a` follows `b`, 0 if equal.
  */
-export const domainHeaders = (entries: Record<string, unknown>): Record<string, string> => {
-  const h: Record<string, string> = {};
-  for (const [key, value] of Object.entries(entries)) {
-    setIfPresent(h, DOMAIN_HEADER_PREFIX + key, value);
-  }
-  return h;
+export const compareBySerial = (a: HasSerial, b: HasSerial): number => {
+  if (a.serial === undefined && b.serial === undefined) return 0;
+  if (a.serial === undefined) return 1;
+  if (b.serial === undefined) return -1;
+  if (a.serial < b.serial) return -1;
+  if (a.serial > b.serial) return 1;
+  return 0;
 };
 
 /**
- * Read a domain header value from a headers record.
- * @param headers - The headers record to read from.
- * @param key - The unprefixed domain key (e.g. `'toolCallId'` reads `'x-domain-toolCallId'`).
+ * Read a domain header value from a codec-tier headers record.
+ * @param headers - The codec headers record to read from.
+ * @param key - The domain key (e.g. `'toolCallId'`).
  * @returns The header value, or undefined if absent.
  */
-export const getDomainHeader = (headers: Record<string, string>, key: string): string | undefined =>
-  headers[DOMAIN_HEADER_PREFIX + key];
+export const getDomainHeader = (headers: Record<string, string>, key: string): string | undefined => headers[key];
 
 /**
  * Mapped type that converts properties whose type includes `undefined`
@@ -167,7 +185,7 @@ export interface DomainHeaderReader {
   str(key: string): string | undefined;
   /** Read a domain header as a string, falling back to a default if absent. */
   strOr(key: string, fallback: string): string;
-  /** Read a domain header as a boolean ("true"/"false"), or undefined if absent. */
+  /** Read a domain header as a boolean: `true` only for the exact string "true", `false` for any other present value, or undefined if absent. */
   bool(key: string): boolean | undefined;
   /** Read a domain header as parsed JSON, or undefined if absent or invalid. */
   json(key: string): unknown;
@@ -206,22 +224,22 @@ export interface DomainHeaderWriter {
 }
 
 /**
- * Create a {@link DomainHeaderWriter} for building a domain headers record.
- * @returns A fluent builder that prefixes each key with the domain header prefix.
+ * Create a {@link DomainHeaderWriter} for building a codec-tier headers record.
+ * @returns A fluent builder that accumulates codec headers under their bare keys.
  */
 export const headerWriter = (): DomainHeaderWriter => {
   const h: Record<string, string> = {};
   const writer: DomainHeaderWriter = {
     str: (key: string, value: string | undefined) => {
-      if (value !== undefined) h[DOMAIN_HEADER_PREFIX + key] = value;
+      if (value !== undefined) h[key] = value;
       return writer;
     },
     bool: (key: string, value: boolean | undefined) => {
-      if (value !== undefined) h[DOMAIN_HEADER_PREFIX + key] = String(value);
+      if (value !== undefined) h[key] = String(value);
       return writer;
     },
     json: (key: string, value: unknown) => {
-      if (value !== undefined && value !== null) h[DOMAIN_HEADER_PREFIX + key] = JSON.stringify(value);
+      if (value !== undefined && value !== null) h[key] = JSON.stringify(value);
       return writer;
     },
     build: () => h,