@ably/ai-transport 0.1.0 → 0.2.0

package/dist/react/contexts/client-session-context.d.ts

@@ -0,0 +1,36 @@
+import { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import { ClientSession } from '../../core/transport/types.js';
+import type * as Ably from 'ably';
+/**
+ * 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 declare const ClientSessionContext: import('react').Context<ClientSessionContextValue>;

package/dist/react/contexts/client-session-provider.d.ts

@@ -0,0 +1,53 @@
+import { PropsWithChildren, ReactNode } from 'react';
+import { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import { ClientSessionOptions } from '../../core/transport/types.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 declare const ClientSessionProvider: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({ children, ...sessionOptions }: ClientSessionProviderProps<TInput, TOutput, TProjection, TMessage>) => ReactNode;

package/dist/react/create-session-hooks.d.ts

@@ -0,0 +1,116 @@
+import { ComponentType } from 'react';
+import { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import { ClientSession, View } from '../core/transport/types.js';
+import { ClientSessionProviderProps } from './contexts/client-session-provider.js';
+import { ClientSessionHandle } from './use-client-session.js';
+import { TreeHandle } from './use-tree.js';
+import { ViewHandle } from './use-view.js';
+/**
+ * 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';
+/**
+ * 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 declare const createSessionHooks: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>() => SessionHooks<TInput, TOutput, TProjection, TMessage>;

package/dist/react/index.d.ts

@@ -1,17 +1,17 @@
-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';
-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';

package/dist/react/internal/use-resolved-session.d.ts

@@ -0,0 +1,36 @@
+import { CodecInputEvent, CodecOutputEvent } from '../../core/codec/types.js';
+import { ClientSession } from '../../core/transport/types.js';
+/**
+ * Shared base for hook options that accept an explicit session override.
+ * Extend this interface for any hook whose `session` option defaults to the
+ * nearest {@link ClientSessionProvider} when omitted. Pass `null` to defer
+ * resolution (e.g. when a split pane is collapsed) — the helper returns
+ * `undefined` rather than falling back to the nearest provider.
+ */
+export interface BaseSessionOption<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /**
+     * Session to operate on; defaults to the nearest {@link ClientSessionProvider}.
+     * Pass `null` to defer (returns undefined; nearest provider is not used).
+     */
+    session?: ClientSession<TInput, TOutput, TProjection, TMessage> | null;
+}
+/**
+ * Resolve the active `ClientSession` for a hook.
+ *
+ * Reads `ClientSessionContext` and applies the standard three-way
+ * priority: explicit `session` argument → nearest provider → `undefined`.
+ * When `skip` is `true`, returns `undefined` regardless of context.
+ * When `session` is `null`, returns `undefined` (caller is deferring).
+ *
+ * Internal — not part of the public API.
+ * @param root0 - Options.
+ * @param root0.session - Explicit session; takes priority over the nearest provider. `null` to defer.
+ * @param root0.skip - When `true`, returns `undefined` immediately; context is still read but its value is ignored.
+ * @returns The resolved session, or `undefined` if none is available or `skip` is `true`.
+ */
+export declare const useResolvedSession: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({ session, skip, }?: {
+    /** Explicit session; takes priority over the nearest provider. `null` to defer. */
+    session?: ClientSession<TInput, TOutput, TProjection, TMessage> | null;
+    /** When `true`, return `undefined` immediately (context is still read, but ignored). */
+    skip?: boolean;
+}) => ClientSession<TInput, TOutput, TProjection, TMessage> | undefined;

package/dist/react/use-ably-messages.d.ts

@@ -1,24 +1,27 @@
-import { ClientTransport } from '../core/transport/types.js';
+import { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import { BaseSessionOption } from './internal/use-resolved-session.js';
 /**
- * useAblyMessages — reactive raw Ably message log from a ClientTransport.
+ * useAblyMessages — reactive raw Ably message log from a ClientSession.
  *
- * Accumulates raw Ably InboundMessages from the transport's tree
+ * Accumulates raw Ably InboundMessages from the session's tree
  * 'ably-message' event. Messages are appended in arrival order.
  *
- * When `transport` is omitted, defaults to the nearest
- * {@link TransportProvider}'s transport via context.
+ * When `session` is omitted, defaults to the nearest
+ * {@link ClientSessionProvider}'s session via context.
  * Pass `skip: true` to bypass all subscriptions and return an empty array.
  */
 import type * as Ably from 'ably';
+/** Options for {@link useAblyMessages}. */
+export interface UseAblyMessagesOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> extends BaseSessionOption<TInput, TOutput, TProjection, TMessage> {
+    /** When `true`, skip all subscriptions and return an empty array. */
+    skip?: boolean;
+}
 /**
- * Subscribe to raw Ably message updates from a client transport's tree.
- * When `transport` is omitted, uses the nearest {@link TransportProvider}'s transport via context.
- * @param props - Options including optional `transport` and `skip`.
- * @param props.transport - Transport to subscribe to; defaults to the nearest provider.
+ * Subscribe to raw Ably message updates from a client session's tree.
+ * When `session` is omitted, uses the nearest {@link ClientSessionProvider}'s session via context.
+ * @param props - Options including optional `session` and `skip`.
+ * @param props.session - Session to subscribe to; defaults to the nearest provider.
  * @param props.skip - When `true`, skip all subscriptions and return an empty array.
- * @returns The accumulated raw Ably messages in chronological order.
+ * @returns The accumulated raw Ably messages in event-arrival order — older history messages loaded later are appended after the live messages already present, so this is not strictly chronological.
  */
-export declare const useAblyMessages: <TEvent, TMessage>({ transport, skip, }?: {
-    transport?: ClientTransport<TEvent, TMessage>;
-    skip?: boolean;
-}) => Ably.InboundMessage[];
+export declare const useAblyMessages: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({ session, skip }?: UseAblyMessagesOptions<TInput, TOutput, TProjection, TMessage>) => Ably.InboundMessage[];

package/dist/react/use-client-session.d.ts

@@ -0,0 +1,81 @@
+import { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import { ClientSession } from '../core/transport/types.js';
+/**
+ * useClientSession — read a ClientSession from the nearest ClientSessionProvider.
+ *
+ * The session is created by {@link ClientSessionProvider}, which reads the Ably
+ * Realtime client from the surrounding `<AblyProvider>`. This hook is a thin
+ * context reader — it does not create or manage session state.
+ *
+ * **Provider lookup**
+ * - Omit `channelName` to use the innermost `ClientSessionProvider` in the tree.
+ * - Pass `channelName` to look up a specific provider by name.
+ * - Pass `skip: true` to receive a stub session that throws on any access —
+ *   safe to hold in state before auth or other conditions are ready.
+ *
+ * **Error handling**
+ * - When no matching provider is found, or when the provider's `createClientSession`
+ *   call threw, `sessionError` is set on the returned object instead of throwing.
+ *   The component can render an error state without an error boundary.
+ * - Pass `onError` to receive post-construction session errors (e.g. send failures,
+ *   channel continuity loss) without wiring `session.on('error', ...)` manually.
+ */
+import * as Ably from 'ably';
+/**
+ * Return value of {@link useClientSession}.
+ *
+ * `session` is always a valid object. When `skip` is `true`, when no provider was
+ * found, or when the provider's session construction failed, `session` is a stub
+ * that throws {@link Ably.ErrorInfo} on every access.
+ * Check `sessionError` before using `session` to avoid those throws.
+ */
+export interface ClientSessionHandle<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> {
+    /**
+     * The resolved session.
+     *
+     * A throwing stub when `skip` is `true`, when no matching {@link ClientSessionProvider}
+     * was found in the tree, or when session construction failed.
+     */
+    session: ClientSession<TInput, TOutput, TProjection, TMessage>;
+    /**
+     * Set when no matching {@link ClientSessionProvider} was found, when session
+     * construction failed, and `skip` is `false`.
+     * `undefined` when the session resolved successfully or when `skip` is `true`.
+     */
+    sessionError?: Ably.ErrorInfo | undefined;
+}
+/**
+ * Read a {@link ClientSession} from the nearest {@link ClientSessionProvider}.
+ *
+ * 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. {@link ErrorCode.SessionSendFailed}, {@link ErrorCode.ChannelContinuityLost})
+ * without calling `session.on('error', …)` manually. The subscription is
+ * created when the session resolves and removed on unmount.
+ * @param props - Hook options.
+ * @param props.channelName - Look up a specific provider by channel name; omit for the nearest.
+ * @param props.skip - When `true`, return the stub session immediately without resolving a provider slot.
+ * @param props.onError - Called whenever the resolved session emits an error event.
+ * @returns `{ session, sessionError }`.
+ */
+export declare const useClientSession: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({ channelName, skip, onError, }?: {
+    /**
+     * Channel name passed to the enclosing {@link ClientSessionProvider}.
+     * Omit to use the nearest provider in the tree.
+     */
+    channelName?: string;
+    /**
+     * When `true`, skip context lookup and return a stub session that throws on
+     * any access. Use when a condition (auth, feature flag) is not yet resolved.
+     */
+    skip?: boolean;
+    /**
+     * Called whenever the resolved session emits an error event.
+     * The subscription is established once the session resolves and
+     * automatically removed on unmount or when the session changes.
+     */
+    onError?: (error: Ably.ErrorInfo) => void;
+}) => ClientSessionHandle<TInput, TOutput, TProjection, TMessage>;

package/dist/react/use-create-view.d.ts

@@ -1,22 +1,23 @@
-import { ClientTransport } from '../core/transport/types.js';
+import { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import { BaseSessionOption } from './internal/use-resolved-session.js';
 import { ViewHandle } from './use-view.js';
+/** Options for {@link useCreateView}. */
+export interface UseCreateViewOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> extends BaseSessionOption<TInput, TOutput, TProjection, TMessage> {
+    /** When provided, auto-loads the first page on mount. Omit for manual load. */
+    limit?: number;
+    /** When `true`, skip view creation and return an empty handle immediately. */
+    skip?: boolean;
+}
 /**
  * Create an independent {@link View} and subscribe to it.
  * Returns the same {@link ViewHandle} as {@link useView}, but backed by a
  * newly created view with its own branch selections and pagination state.
- * The view is closed on unmount or when the transport changes.
- * When `transport` is omitted, uses the nearest {@link TransportProvider}'s transport via context.
- * @param props - Options including optional `transport`, `limit` for auto-load, and `skip`.
- * @param props.transport - Transport to create a view from; defaults to the nearest provider.
+ * The view is closed on unmount or when the session changes.
+ * When `session` is omitted, uses the nearest {@link ClientSessionProvider}'s session via context.
+ * @param props - Options including optional `session`, `limit` for auto-load, and `skip`.
+ * @param props.session - Session to create a view from; defaults to the nearest provider.
  * @param props.limit - Max older messages per page; when provided, auto-loads on mount.
  * @param props.skip - When `true`, skip view creation and return an empty handle.
  * @returns A {@link ViewHandle} with nodes, pagination, navigation, and write operations.
  */
-export declare const useCreateView: <TEvent, TMessage>({ transport, limit, skip, }?: {
-    /** The transport to create a view from, or null/undefined to use the nearest provider. */
-    transport?: ClientTransport<TEvent, TMessage> | null;
-    /** When provided, auto-loads the first page on mount. Omit for manual load. */
-    limit?: number;
-    /** When `true`, skip view creation and return an empty handle immediately. */
-    skip?: boolean;
-}) => ViewHandle<TEvent, TMessage>;
+export declare const useCreateView: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({ session, limit, skip, }?: UseCreateViewOptions<TInput, TOutput, TProjection, TMessage>) => ViewHandle<TInput, TMessage>;

package/dist/react/use-tree.d.ts

@@ -1,20 +1,35 @@
-import { ClientTransport, MessageNode } from '../core/transport/types.js';
+import { CodecInputEvent, CodecOutputEvent } from '../core/codec/types.js';
+import { ConversationNode, RunNode } from '../core/transport/types.js';
+import { BaseSessionOption } from './internal/use-resolved-session.js';
 /** Handle for querying the conversation tree structure. */
-export interface TreeHandle<TMessage> {
-    /** 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;
+export interface TreeHandle<TProjection> {
+    /**
+     * Get the RunNode for `runId`, or undefined if no node is keyed by `runId`
+     * (or the keyed node is an input node, not a reply run).
+     */
+    getRunNode: (runId: string) => RunNode<TProjection> | undefined;
+    /**
+     * Get the node that owns a given codec-message-id, or undefined if not
+     * observed. Returns a {@link ConversationNode} union — narrow on `kind`
+     * (`'input'` vs `'run'`) before reading kind-specific fields.
+     */
+    getNodeByCodecMessageId: (codecMessageId: string) => ConversationNode<TProjection> | undefined;
+    /**
+     * Get the sibling group (both kinds) the node keyed by `key` belongs to —
+     * edit versions for an input node, regenerate runs for a reply run — ordered
+     * oldest-first. A single-element array when the node has no siblings; empty
+     * when `key` is unknown. `key` is a {@link RunNode.runId} or an
+     * {@link InputNode.codecMessageId}.
+     */
+    getSiblingNodes: (key: string) => ConversationNode<TProjection>[];
 }
+/** Options for {@link useTree}. */
+export type UseTreeOptions<TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage> = BaseSessionOption<TInput, TOutput, TProjection, TMessage>;
 /**
- * Provide stable structural query callbacks backed by the transport's tree.
- * When `transport` is omitted, uses the nearest {@link TransportProvider}'s transport via context.
- * @param props - Options including optional `transport`.
- * @param props.transport - Transport to read tree structure from; defaults to the nearest provider.
+ * Provide stable structural query callbacks backed by the session's tree.
+ * When `session` is omitted, uses the nearest {@link ClientSessionProvider}'s session via context.
+ * @param props - Options including optional `session`.
+ * @param props.session - Session to read tree structure from; defaults to the nearest provider.
  * @returns A {@link TreeHandle} with structural query methods.
  */
-export declare const useTree: <TEvent, TMessage>({ transport, }?: {
-    transport?: ClientTransport<TEvent, TMessage>;
-}) => TreeHandle<TMessage>;
+export declare const useTree: <TInput extends CodecInputEvent, TOutput extends CodecOutputEvent, TProjection, TMessage>({ session, }?: UseTreeOptions<TInput, TOutput, TProjection, TMessage>) => TreeHandle<TProjection>;