@ably/ai-transport 0.1.0 → 0.2.0

package/src/errors.ts

@@ -14,18 +14,24 @@ export enum ErrorCode {
    */
   InvalidArgument = 40003,
 
+  /**
+   * Operation not permitted with the provided capability (Ably 40160).
+   * Used when the Ably channel rejects a publish for a capability reason.
+   */
+  InsufficientCapability = 40160,
+
   // 104000 - 104999 are reserved for AI Transport SDK errors
 
   /**
-   * Encoder recovery failed after flush — one or more updateMessage calls
+   * Encoder recovery failed during flush — one or more updateMessage calls
    * could not recover a failed append pipeline.
    */
   EncoderRecoveryFailed = 104000,
 
   /**
-   * A transport-level channel subscription callback threw unexpectedly.
+   * A session-level channel subscription callback threw unexpectedly.
    */
-  TransportSubscriptionError = 104001,
+  SessionSubscriptionError = 104001,
 
   /**
    * Cancel listener or onCancel hook threw while processing a cancel message.
@@ -33,19 +39,19 @@ export enum ErrorCode {
   CancelListenerError = 104002,
 
   /**
-   * A publish within a turn failed (lifecycle event, message, or event).
+   * A publish within a run failed (lifecycle event, message, or event).
    */
-  TurnLifecycleError = 104003,
+  RunLifecycleError = 104003,
 
   /**
-   * An operation was attempted on a transport that has already been closed.
+   * An operation was attempted on a session that has already been closed.
    */
-  TransportClosed = 104004,
+  SessionClosed = 104004,
 
   /**
-   * The HTTP POST to the server endpoint failed (network error or non-2xx response).
+   * The HTTP POST to the agent endpoint failed (network error or non-2xx response).
    */
-  TransportSendFailed = 104005,
+  SessionSendFailed = 104005,
 
   /**
    * The Ably channel lost message continuity — the channel entered FAILED,
@@ -66,6 +72,13 @@ export enum ErrorCode {
    * network failure) or an underlying publish failed mid-stream.
    */
   StreamError = 104008,
+
+  /**
+   * The agent attached to the channel and waited for the input event(s) the
+   * invocation points at (rewind + live wait) but `inputEventLookupTimeoutMs`
+   * lapsed without seeing them.
+   */
+  InputEventNotFound = 104010,
 }
 
 /**

package/src/event-emitter.ts

@@ -76,8 +76,9 @@ const toAblyLogger = (logger: Logger): unknown => ({
 });
 
 // CAST: Access Ably's internal EventEmitter constructor. Not publicly exported
-// but available to other Ably SDKs. The logger parameter ensures listener
-// exceptions are caught and logged rather than crashing.
+// but available to other Ably SDKs. Ably always catches listener exceptions
+// internally; the logger parameter ensures those caught exceptions are logged
+// rather than silently swallowed.
 const InternalEventEmitter: new <EventsMap>(logger: unknown) => InterfaceEventEmitter<EventsMap> = (
   Ably.Realtime as unknown as { EventEmitter: new <EventsMap>(logger: unknown) => InterfaceEventEmitter<EventsMap> }
 ).EventEmitter;

package/src/index.ts

@@ -1,87 +1,98 @@
 // Core transport
 export type {
-  ActiveTurn,
-  AddMessageOptions,
-  AddMessagesResult,
-  CancelFilter,
+  ActiveRun,
+  AgentSession,
+  AgentSessionOptions,
+  BranchSelection,
   CancelRequest,
-  ClientTransport,
-  ClientTransportOptions,
-  CloseOptions,
+  ClientSession,
+  ClientSessionOptions,
+  ConversationNode,
   EventsNode,
+  InputNode,
+  InvocationData,
+  LoadConversationOptions,
   MessageNode,
-  NewTurnOptions,
+  OutputEvent,
+  PipeOptions,
+  Run,
+  RunEndReason,
+  RunInfo,
+  RunLifecycleEvent,
+  RunNode,
+  RunRuntime,
+  RunView,
   SendOptions,
-  ServerTransport,
-  ServerTransportOptions,
-  StreamResponseOptions,
   StreamResult,
   Tree,
-  Turn,
-  TurnEndReason,
-  TurnLifecycleEvent,
   View,
 } from './core/transport/index.js';
-
-// Deprecated aliases — intentional re-export of deprecated types for backwards compatibility.
-// eslint-disable-next-line @typescript-eslint/no-deprecated
-export type { EventNode } from './core/transport/index.js';
-// eslint-disable-next-line @typescript-eslint/no-deprecated
-export type { TreeNode } from './core/transport/index.js';
-export { buildTransportHeaders, createClientTransport, createServerTransport } from './core/transport/index.js';
+export { buildTransportHeaders, createAgentSession, createClientSession, Invocation } from './core/transport/index.js';
 
 // Core codec
 export type {
   ChannelWriter,
   Codec,
+  CodecInputEvent,
+  CodecMessage,
+  CodecOutputEvent,
+  DecodedMessage,
+  Decoder,
   DecoderCore,
   DecoderCoreHooks,
   DecoderCoreOptions,
-  DecoderOutput,
-  DiscreteEncoder,
+  Encoder,
   EncoderCore,
   EncoderCoreOptions,
   EncoderOptions,
   Extras,
   LifecycleTracker,
-  MessageAccumulator,
   MessagePayload,
   PhaseConfig,
-  StreamDecoder,
-  StreamEncoder,
+  Reducer,
+  ReducerMeta,
+  Regenerate,
   StreamPayload,
   StreamTrackerState,
+  ToolApprovalResponse,
+  ToolResult,
+  ToolResultError,
+  UserMessage,
   WriteOptions,
 } from './core/codec/index.js';
-export { createDecoderCore, createEncoderCore, createLifecycleTracker, eventOutput } from './core/codec/index.js';
+export { createDecoderCore, createEncoderCore, createLifecycleTracker } from './core/codec/index.js';
 
 // Constants
 export {
-  DOMAIN_HEADER_PREFIX,
-  EVENT_ABORT,
   EVENT_CANCEL,
-  EVENT_ERROR,
-  EVENT_TURN_END,
-  EVENT_TURN_START,
-  HEADER_CANCEL_ALL,
-  HEADER_CANCEL_CLIENT_ID,
-  HEADER_CANCEL_OWN,
-  HEADER_CANCEL_TURN_ID,
+  EVENT_RUN_END,
+  EVENT_RUN_START,
+  HEADER_CODEC_MESSAGE_ID,
+  HEADER_ERROR_CODE,
+  HEADER_ERROR_MESSAGE,
   HEADER_FORK_OF,
-  HEADER_MSG_ID,
+  HEADER_INPUT_CLIENT_ID,
+  HEADER_MSG_REGENERATE,
   HEADER_PARENT,
   HEADER_ROLE,
+  HEADER_RUN_CLIENT_ID,
+  HEADER_RUN_ID,
+  HEADER_RUN_REASON,
   HEADER_STATUS,
   HEADER_STREAM,
   HEADER_STREAM_ID,
-  HEADER_TURN_CLIENT_ID,
-  HEADER_TURN_ID,
-  HEADER_TURN_REASON,
 } from './constants.js';
 
 // Utilities
 export type { DomainHeaderReader, DomainHeaderWriter, Stripped } from './utils.js';
-export { getHeaders, headerReader, headerWriter, mergeHeaders, stripUndefined } from './utils.js';
+export {
+  getCodecHeaders,
+  getTransportHeaders,
+  headerReader,
+  headerWriter,
+  mergeHeaders,
+  stripUndefined,
+} from './utils.js';
 
 // Event emitter
 export { EventEmitter } from './event-emitter.js';

package/src/logger.ts

@@ -143,10 +143,22 @@ export const consoleLogger = (message: string, level: LogLevel, context?: LogCon
  * Options for creating a logger.
  */
 export interface LoggerOptions {
+  /**
+   * The handler that receives formatted log messages. Defaults to {@link consoleLogger} when omitted.
+   */
   logHandler?: LogHandler;
+  /**
+   * The minimum level to emit; messages below this level are suppressed. Must be a valid {@link LogLevel}, otherwise logger creation throws.
+   */
   logLevel: LogLevel;
 }
 
+/**
+ * Creates a {@link Logger} from the given options.
+ * @param options The handler and minimum level for the logger.
+ * @returns A logger that filters by level and delegates to the handler.
+ * @throws {@link Ably.ErrorInfo} with {@link ErrorCode.InvalidArgument} if `options.logLevel` is not a recognised {@link LogLevel}.
+ */
 export const makeLogger = (options: LoggerOptions): Logger => {
   const logHandler = options.logHandler ?? consoleLogger;
 
@@ -218,7 +230,8 @@ class DefaultLogger implements Logger {
   }
 
   withContext(context: LogContext): Logger {
-    // Get the original log level by finding the key in logLevelNumberMap that matches this._levelNumber
+    // Get the original log level by finding the key in logLevelNumberMap that matches this._levelNumber.
+    // The Error fallback is defensive and unreachable in practice: _levelNumber always originates from the map.
     const originalLevel =
       [...logLevelNumberMap.entries()].find(([, value]) => value === this._levelNumber)?.[0] ?? LogLevel.Error;
 

package/src/react/contexts/client-session-context.ts

@@ -0,0 +1,41 @@
+import type * as Ably from 'ably';
+import { createContext } from 'react';
+
+import type { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import type { ClientSession } from '../../core/transport/types.js';
+
+/**
+ * A single entry in the client-session registry, holding the session and any
+ * error that occurred during its construction.
+ *
+ * `session` is `undefined` when construction failed.
+ * `sessionError` is set when `createClientSession` threw during provider render.
+ */
+export interface ClientSessionSlot {
+  /** The constructed session, or `undefined` if construction failed. */
+  session: ClientSession<CodecInputEvent, CodecOutputEvent, unknown, unknown> | undefined;
+  /** Construction error from `createClientSession`, or `undefined` on success. */
+  sessionError?: Ably.ErrorInfo | undefined;
+}
+
+/**
+ * The shape of the {@link ClientSessionContext} value.
+ *
+ * `nearest` is the slot from the innermost enclosing {@link ClientSessionProvider}.
+ * `providers` is the full registry of all enclosing providers, keyed by channelName.
+ */
+export interface ClientSessionContextValue {
+  /** The innermost {@link ClientSessionProvider}'s slot. `undefined` when no provider is present. */
+  nearest: ClientSessionSlot | undefined;
+  /** All registered session slots from enclosing providers, keyed by channelName. */
+  providers: Readonly<Record<string, ClientSessionSlot>>;
+}
+
+/**
+ * Unified client-session context.
+ *
+ * Holds the nearest client-session slot and the full registry of all registered
+ * slots keyed by channelName. Populated by {@link ClientSessionProvider};
+ * read by {@link useClientSession} and internal hooks.
+ */
+export const ClientSessionContext = createContext<ClientSessionContextValue>({ nearest: undefined, providers: {} });

package/src/react/contexts/client-session-provider.tsx

@@ -0,0 +1,186 @@
+/**
+ * ClientSessionProvider: creates a ClientSession and makes it available to
+ * descendants via ClientSessionContext.
+ *
+ * Reads the Ably Realtime client from the surrounding `<AblyProvider>` and
+ * forwards it to `createClientSession` along with the supplied `channelName`.
+ *
+ * The session is created on first render (via useRef) and recreated when
+ * `channelName` changes; the previous session is queued for disposal.
+ * `connect()` is invoked from a `useEffect` so the session is
+ * subscribed/attached before the first descendant operation. If
+ * `createClientSession` throws,
+ * the error is stored in the ClientSessionSlot (alongside an undefined
+ * session) so that useClientSession can surface it as `sessionError`
+ * without crashing the component tree.
+ *
+ * The session is closed when the provider truly unmounts. The close is
+ * scheduled as a microtask so that React Strict Mode's synchronous
+ * remount cycle (mount → fake-unmount → remount) can cancel it before it
+ * fires, avoiding unnecessary session teardown in development.
+ *
+ * Multiple ClientSessionProviders can be nested using distinct channelNames.
+ * Each provider merges its slot into the parent record so descendants
+ * can access all registered sessions via useClientSession(channelName).
+ */
+
+import * as Ably from 'ably';
+import { useAbly } from 'ably/react';
+import { type PropsWithChildren, type ReactNode, useContext, useEffect, useMemo, useRef } from 'react';
+
+import type { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import { createClientSession } from '../../core/transport/client-session.js';
+import type { ClientSession, ClientSessionOptions } from '../../core/transport/types.js';
+import { ErrorCode } from '../../errors.js';
+import type { ClientSessionSlot } from './client-session-context.js';
+import { ClientSessionContext } from './client-session-context.js';
+
+/**
+ * Props for {@link ClientSessionProvider}.
+ *
+ * All {@link ClientSessionOptions} except `client` (read from the surrounding
+ * `<AblyProvider>`).
+ */
+export interface ClientSessionProviderProps<
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+>
+  extends Omit<ClientSessionOptions<TInput, TOutput, TProjection, TMessage>, 'client'>, PropsWithChildren {}
+
+/**
+ * Provide a {@link ClientSession} to descendant components.
+ *
+ * Reads the Ably Realtime client from the surrounding `<AblyProvider>`,
+ * creates a session bound to `channelName`, calls `connect()` on mount,
+ * and registers it in `ClientSessionContext` under `channelName`.
+ * Descendants call {@link useClientSession} with the same `channelName` to
+ * access the session.
+ *
+ * If `createClientSession` throws during construction, the error is surfaced
+ * through `useClientSession` as `sessionError` — the component tree does not
+ * crash and children are still rendered.
+ *
+ * ```tsx
+ * <AblyProvider client={ably}>
+ *   <ClientSessionProvider channelName="ai:demo" codec={UIMessageCodec}>
+ *     <Chat />
+ *   </ClientSessionProvider>
+ * </AblyProvider>
+ *
+ * // Inside Chat:
+ * const { session, sessionError } = useClientSession({ channelName: 'ai:demo' });
+ * ```
+ *
+ * For multiple sessions, nest providers with distinct channelNames:
+ *
+ * ```tsx
+ * <ClientSessionProvider channelName="ai:main" codec={UIMessageCodec}>
+ *   <ClientSessionProvider channelName="ai:aux" codec={UIMessageCodec}>
+ *     <App />
+ *   </ClientSessionProvider>
+ * </ClientSessionProvider>
+ *
+ * // Inside App:
+ * const { session: main } = useClientSession({ channelName: 'ai:main' });
+ * const { session: aux }  = useClientSession({ channelName: 'ai:aux' });
+ * ```
+ * @param props - Provider configuration including `channelName`, `codec`, and all other {@link ClientSessionOptions} except `client`.
+ * @param props.children - Descendant components that consume the session via {@link useClientSession}.
+ * @returns A React element wrapping children with ClientSessionContext.
+ */
+export const ClientSessionProvider = <
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+>({
+  children,
+  ...sessionOptions
+}: ClientSessionProviderProps<TInput, TOutput, TProjection, TMessage>): ReactNode => {
+  const client = useAbly();
+  const { channelName } = sessionOptions;
+  const sessionRef = useRef<ClientSession<TInput, TOutput, TProjection, TMessage> | undefined>(undefined);
+  const sessionChannelRef = useRef<string>(channelName);
+  const sessionsToDisposeRef = useRef<ClientSession<CodecInputEvent, CodecOutputEvent, unknown, unknown>[]>([]);
+  const pendingCloseRef = useRef(false);
+  const constructionErrorRef = useRef<Ably.ErrorInfo | undefined>(undefined);
+
+  const alreadyCreatedOrFailed = !!sessionRef.current || !!constructionErrorRef.current;
+
+  if (!alreadyCreatedOrFailed || sessionChannelRef.current !== channelName) {
+    sessionChannelRef.current = channelName;
+    if (sessionRef.current) sessionsToDisposeRef.current.push(sessionRef.current);
+    try {
+      sessionRef.current = createClientSession({ ...sessionOptions, client });
+      constructionErrorRef.current = undefined;
+    } catch (error) {
+      sessionRef.current = undefined;
+      constructionErrorRef.current =
+        error instanceof Ably.ErrorInfo
+          ? error
+          : new Ably.ErrorInfo('Unknown error while creating client session', ErrorCode.BadRequest, 400);
+    }
+  }
+
+  const parentContext = useContext(ClientSessionContext);
+
+  // Capture ref values as locals so useMemo deps track changes correctly.
+  // CAST: ClientSessionContext stores sessions with erased generics.
+  // The generic types are fixed at the ClientSessionProvider<TInput, TOutput, TProjection, TMessage> boundary.
+  const currentSession = sessionRef.current as
+    | ClientSession<CodecInputEvent, CodecOutputEvent, unknown, unknown>
+    | undefined;
+  const currentError = constructionErrorRef.current;
+
+  const slot = useMemo<ClientSessionSlot>(
+    () => ({ session: currentSession, sessionError: currentError }),
+    [currentSession, currentError],
+  );
+
+  const contextValue = useMemo(
+    () => ({ nearest: slot, providers: { ...parentContext.providers, [channelName]: slot } }),
+    [channelName, parentContext, slot],
+  );
+
+  // Dispose sessions superseded by a channelName change. When channelName
+  // changes, the render path above pushes the now-stale session into
+  // sessionsToDisposeRef and creates a replacement. This effect's cleanup —
+  // which runs on the next channelName change or on unmount — closes every
+  // queued session.
+  useEffect(
+    () => () => {
+      for (const session of sessionsToDisposeRef.current) void session.close();
+    },
+    [channelName],
+  );
+
+  // Trigger connect() once the session is created. Re-runs when channelName
+  // changes so the freshly-recreated session connects too. Any error is
+  // stored on the session's emitter and surfaced via on('error');
+  // useClientSession doesn't need to await this.
+  useEffect(() => {
+    void sessionRef.current?.connect();
+  }, [channelName]);
+
+  // Close the session when the component truly unmounts. The close is
+  // scheduled as a microtask: in React Strict Mode (dev) the component
+  // remounts synchronously before any microtask can drain, so the remount's
+  // effect setup resets pendingCloseRef.current = false and cancels the
+  // close. On a real unmount no remount follows, the microtask fires, and
+  // the session is closed.
+  useEffect(() => {
+    pendingCloseRef.current = false;
+    return () => {
+      pendingCloseRef.current = true;
+      void Promise.resolve().then(() => {
+        if (pendingCloseRef.current) {
+          void sessionRef.current?.close();
+        }
+      });
+    };
+  }, []);
+
+  return <ClientSessionContext.Provider value={contextValue}>{children}</ClientSessionContext.Provider>;
+};

package/src/react/create-session-hooks.ts

@@ -0,0 +1,141 @@
+/**
+ * createSessionHooks: factory that captures the codec's type parameters once and
+ * returns a bundle of type-safe hooks + ClientSessionProvider. Hook call sites need
+ * no type parameters at every use — just call the hooks directly.
+ * @example
+ * // Once per app (e.g. in a shared session.ts):
+ * export const {
+ *   ClientSessionProvider,
+ *   useClientSession,
+ *   useView,
+ * } = createSessionHooks<VercelInput, VercelOutput, VercelProjection, UIMessage>();
+ *
+ * // In page:
+ * <ClientSessionProvider channelName="ai:demo" codec={UIMessageCodec}>
+ *   <Chat />
+ * </ClientSessionProvider>
+ *
+ * // In Chat — no type params needed, session is implicit from nearest provider:
+ * const { nodes } = useView({ limit: 30 });
+ */
+
+import type * as Ably from 'ably';
+import type { ComponentType } from 'react';
+
+import type { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import type { ClientSession, View } from '../core/transport/types.js';
+import type { ClientSessionProviderProps } from './contexts/client-session-provider.js';
+import { ClientSessionProvider as _ClientSessionProvider } from './contexts/client-session-provider.js';
+import { useAblyMessages as _useAblyMessages } from './use-ably-messages.js';
+import type { ClientSessionHandle } from './use-client-session.js';
+import { useClientSession as _useClientSession } from './use-client-session.js';
+import { useCreateView as _useCreateView } from './use-create-view.js';
+import type { TreeHandle } from './use-tree.js';
+import { useTree as _useTree } from './use-tree.js';
+import type { ViewHandle } from './use-view.js';
+import { useView as _useView } from './use-view.js';
+
+/**
+ * Bundle of type-safe hooks and provider returned by {@link createSessionHooks}.
+ *
+ * The codec's `TInput`, `TOutput`, `TProjection`, and `TMessage` are baked in at
+ * factory creation time so no type params are needed at hook call sites.
+ */
+export interface SessionHooks<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+  /**
+   * `ClientSessionProvider` narrowed to the codec's `TInput`/`TOutput`/`TMessage`. No JSX type params needed.
+   */
+  ClientSessionProvider: ComponentType<ClientSessionProviderProps<TInput, TOutput, TProjection, TMessage>>;
+  /**
+   * Read the session from context. No type params needed.
+   *
+   * Returns `{ session, sessionError }`. When no provider is found (or session
+   * construction failed), `sessionError` is set and `session` is a stub that
+   * throws on access — the hook never throws during render.
+   *
+   * Pass `onError` to subscribe to post-construction session errors
+   * (e.g. send failures, channel continuity loss) without wiring
+   * `session.on('error', …)` manually.
+   */
+  useClientSession: (props?: {
+    /** Channel name to look up; omit to use the nearest {@link ClientSessionProvider}. */
+    channelName?: string;
+    /** When `true`, return a stub session that throws on any access. */
+    skip?: boolean;
+    /** Called whenever the resolved session emits an error event. */
+    onError?: (error: Ably.ErrorInfo) => void;
+  }) => ClientSessionHandle<TInput, TOutput, TProjection, TMessage>;
+  /**
+   * Subscribe to the nearest session's view and return the visible message list with pagination.
+   * Pass `session` to use a session's default view, `view` to subscribe to a specific view
+   * directly. Pass `limit` to auto-load on mount. Pass `skip: true` for an empty handle.
+   */
+  useView: (props?: {
+    /** Client session whose default view to subscribe to; defaults to the nearest {@link ClientSessionProvider}. */
+    session?: ClientSession<TInput, TOutput, TProjection, TMessage> | null;
+    /** A specific {@link View} to subscribe to directly. Takes priority over `session`. */
+    view?: View<TInput, TMessage> | null;
+    /** When provided, auto-loads the first page on mount. */
+    limit?: number;
+    /** When `true`, skip all subscriptions and return an empty handle. */
+    skip?: boolean;
+  }) => ViewHandle<TInput, TMessage>;
+  /**
+   * Navigate conversation branches in the session tree.
+   * Pass `session` to override; defaults to the nearest {@link ClientSessionProvider}.
+   */
+  useTree: (props?: {
+    /** Override session; defaults to the nearest {@link ClientSessionProvider}. */
+    session?: ClientSession<TInput, TOutput, TProjection, TMessage>;
+  }) => TreeHandle<TProjection>;
+  /**
+   * Subscribe to raw Ably messages on the session channel.
+   * Pass `session` to override; defaults to the nearest {@link ClientSessionProvider}.
+   * Pass `skip: true` to return an empty array without subscribing.
+   */
+  useAblyMessages: (props?: {
+    /** Override session; defaults to the nearest {@link ClientSessionProvider}. */
+    session?: ClientSession<TInput, TOutput, TProjection, TMessage>;
+    /** When `true`, skip all subscriptions and return an empty array. */
+    skip?: boolean;
+  }) => Ably.InboundMessage[];
+  /**
+   * Create an independent view over the same tree.
+   * Pass `session` to override; defaults to the nearest {@link ClientSessionProvider}.
+   * Pass `skip: true` to return an empty handle without creating a view.
+   */
+  useCreateView: (props?: {
+    /** Override session; defaults to the nearest {@link ClientSessionProvider}. */
+    session?: ClientSession<TInput, TOutput, TProjection, TMessage> | null;
+    /** When provided, auto-loads the first page on mount. */
+    limit?: number;
+    /** When `true`, skip view creation and return an empty handle. */
+    skip?: boolean;
+  }) => ViewHandle<TInput, TMessage>;
+}
+
+/**
+ * Create a bundle of type-safe hooks and provider for a given codec's
+ * `TInput`/`TOutput`/`TProjection`/`TMessage`.
+ *
+ * These type parameters are captured at factory creation time; hook call sites need
+ * no type parameters. The returned hooks are thin wrappers around the standalone hooks
+ * with the types resolved.
+ * @returns A {@link SessionHooks} bundle.
+ */
+export const createSessionHooks = <
+  TInput extends CodecInputEvent,
+  TOutput extends CodecOutputEvent,
+  TProjection,
+  TMessage,
+>(): SessionHooks<TInput, TOutput, TProjection, TMessage> => ({
+  // CAST: ClientSessionProvider is generic; factory narrows it to the codec's TInput/TOutput/TProjection/TMessage.
+  ClientSessionProvider: _ClientSessionProvider as ComponentType<
+    ClientSessionProviderProps<TInput, TOutput, TProjection, TMessage>
+  >,
+  useClientSession: (props) => _useClientSession<TInput, TOutput, TProjection, TMessage>(props ?? {}),
+  useView: (props) => _useView<TInput, TOutput, TProjection, TMessage>(props ?? {}),
+  useTree: (props) => _useTree<TInput, TOutput, TProjection, TMessage>(props ?? {}),
+  useAblyMessages: (props) => _useAblyMessages<TInput, TOutput, TProjection, TMessage>(props ?? {}),
+  useCreateView: (props) => _useCreateView<TInput, TOutput, TProjection, TMessage>(props ?? {}),
+});

package/src/react/index.ts

@@ -1,18 +1,28 @@
-export type { EventsNode, MessageNode } from '../core/transport/types.js';
-export type { TransportSlot } from './contexts/transport-context.js';
-export { NearestTransportContext } from './contexts/transport-context.js';
-export type { TransportProviderProps } from './contexts/transport-provider.js';
-export { TransportProvider } from './contexts/transport-provider.js';
-export type { TransportHooks } from './create-transport-hooks.js';
-export { createTransportHooks } from './create-transport-hooks.js';
-// eslint-disable-next-line @typescript-eslint/no-deprecated -- intentional re-export for backwards compatibility
-export type { EventNode, TreeNode } from '../core/transport/types.js';
+export type { CodecMessage } from '../core/codec/types.js';
+export type {
+  ActiveRun,
+  BranchSelection,
+  ClientSession,
+  ConversationNode,
+  EventsNode,
+  InputNode,
+  MessageNode,
+  RunInfo,
+  RunNode,
+  SendOptions,
+} from '../core/transport/types.js';
+export type { ClientSessionSlot } from './contexts/client-session-context.js';
+export type { ClientSessionProviderProps } from './contexts/client-session-provider.js';
+export { ClientSessionProvider } from './contexts/client-session-provider.js';
+export type { SessionHooks } from './create-session-hooks.js';
+export { createSessionHooks } from './create-session-hooks.js';
+export type { UseAblyMessagesOptions } from './use-ably-messages.js';
 export { useAblyMessages } from './use-ably-messages.js';
-export { useActiveTurns } from './use-active-turns.js';
-export type { ClientTransportHandle } from './use-client-transport.js';
-export { useClientTransport } from './use-client-transport.js';
+export type { ClientSessionHandle } from './use-client-session.js';
+export { useClientSession } from './use-client-session.js';
+export type { UseCreateViewOptions } from './use-create-view.js';
 export { useCreateView } from './use-create-view.js';
-export type { TreeHandle } from './use-tree.js';
+export type { TreeHandle, UseTreeOptions } from './use-tree.js';
 export { useTree } from './use-tree.js';
 export type { UseViewOptions, ViewHandle } from './use-view.js';
 export { useView } from './use-view.js';