@ably/ai-transport 0.0.1 → 0.1.0

package/src/vercel/transport/chat-transport.ts

@@ -7,12 +7,18 @@
  * to the core transport's send/cancel methods.
  *
  * useChat manages message state before calling sendMessages:
- * - submit-message: appends the new user message, passes the full array
+ * - submit-message (new): appends the new user message, passes the full array
+ * - submit-message (edit): truncates after the edited message, replaces it,
+ *   passes the truncated array with messageId set
  * - regenerate-message: truncates after the target, passes the truncated array
  *
  * The adapter uses `trigger` to determine the history/messages split:
  * - submit-message: last message is new (publish to channel), rest is history
  * - regenerate-message: no new messages, entire array is history
+ *
+ * When messageId is set (edit or regeneration), the adapter computes fork
+ * metadata (forkOf/parent) from the conversation tree so the server can
+ * place the response on the correct branch.
  */
 
 import * as Ably from 'ably';
@@ -31,12 +37,14 @@ import { ErrorCode } from '../../errors.js';
  */
 export interface SendMessagesRequestContext {
   /** Chat session ID (from useChat's id). */
-  id?: string;
+  chatId?: string;
   /** What triggered the request: user sent a message, or requested regeneration. */
   trigger: 'submit-message' | 'regenerate-message';
   /**
-   * The message ID for regeneration requests. Identifies which assistant
-   * message to regenerate. Undefined for submit-message.
+   * The message ID for edit or regeneration requests. For regeneration,
+   * identifies the assistant message to regenerate. For edits (submit-message
+   * with messageId), identifies the user message being replaced. Undefined
+   * when submitting a new message.
    */
   messageId?: string;
   /** Previous messages in the conversation (context for the LLM). */
@@ -46,7 +54,7 @@ export interface SendMessagesRequestContext {
   /** The msg-id of the message being forked (regenerated or edited). */
   forkOf?: string;
   /** The msg-id of the predecessor in the conversation thread. */
-  parent?: string | null;
+  parent?: string;
 }
 
 /** Options for customizing the ChatTransport behavior. */
@@ -91,7 +99,8 @@ interface ChatRequestOptions {
  *
  * Structurally compatible with the AI SDK's internal `ChatTransport<UIMessage>`
  * interface. Extended with `close()` for releasing the underlying Ably transport
- * resources.
+ * resources and `streaming` / `onStreamingChange` for coordinating with
+ * useMessageSync.
  */
 export interface ChatTransport {
   /** Send messages and return a streaming response of UIMessageChunk events. */
@@ -123,8 +132,78 @@ export interface ChatTransport {
 
   /** Close the underlying transport, releasing all resources. */
   close(options?: CloseOptions): Promise<void>;
+
+  /** Whether an own-turn stream is currently being consumed by useChat. */
+  readonly streaming: boolean;
+
+  /**
+   * Subscribe to streaming state changes. The callback fires when the
+   * ChatTransport transitions between streaming and idle. Used by
+   * useMessageSync to gate setMessages calls during active streams.
+   * @param callback - Called with `true` when a stream starts, `false` when it ends.
+   * @returns Unsubscribe function.
+   */
+  onStreamingChange(callback: (streaming: boolean) => void): () => void;
 }
 
+// ---------------------------------------------------------------------------
+// Stream wrapper — passthrough that signals completion via a promise
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a ReadableStream in a passthrough TransformStream that resolves a
+ * promise when the stream completes or errors. The returned stream passes
+ * all chunks through unchanged.
+ * @param source - The original stream to wrap.
+ * @returns The wrapped stream and a `done` promise that resolves when the stream closes.
+ */
+const wrapStreamWithDone = <T>(source: ReadableStream<T>): { stream: ReadableStream<T>; done: Promise<void> } => {
+  let resolveDone: () => void;
+  const done = new Promise<void>((resolve) => {
+    resolveDone = resolve;
+  });
+
+  const passthrough = new TransformStream<T, T>({
+    flush: () => {
+      resolveDone();
+    },
+  });
+
+  // Pipe in the background. If the source errors or is cancelled, resolve
+  // done so the serialization queue advances.
+  // Fire-and-forget: the pipe runs independently; errors surface through
+  // the readable side that useChat consumes.
+  source.pipeTo(passthrough.writable).catch(() => {
+    resolveDone();
+  });
+
+  return { stream: passthrough.readable, done };
+};
+
+// ---------------------------------------------------------------------------
+// Unresolved tool call detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether an assistant message has a `dynamic-tool` part that can't resolve
+ * without further user action. Matches:
+ * - `input-streaming` / `input-available` — tool call emitted, not yet run.
+ * - `approval-requested` — waiting for the user.
+ *
+ * Excludes `approval-responded` (streamText will run the tool this turn)
+ * and all terminal `output-*` states.
+ * @param msg - The UIMessage to inspect.
+ * @returns True when a fork-on-send is warranted to avoid shipping a
+ *   dangling tool call to the LLM.
+ */
+const hasUnresolvedToolCall = (msg: AI.UIMessage): boolean =>
+  msg.role === 'assistant' &&
+  msg.parts.some(
+    (p) =>
+      p.type === 'dynamic-tool' &&
+      (p.state === 'input-streaming' || p.state === 'input-available' || p.state === 'approval-requested'),
+  );
+
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -132,11 +211,14 @@ export interface ChatTransport {
 /**
  * Create a Vercel ChatTransport from a core ClientTransport.
  *
- * Maps Vercel's useChat contract to the core transport's methods:
- * - trigger 'submit-message' → transport.send(lastMessage) with history in body
- * - trigger 'regenerate-message' → transport.send([]) with all messages as history
- * - abortSignal → transport.cancel({ all: true })
- * - reconnectToStream → null (observer mode handles in-progress streams)
+ * Exposes a `streaming` flag and `onStreamingChange` callback so that
+ * `useMessageSync` can gate `setMessages` calls during active own-turn
+ * streams, preventing the push/replace ID mismatch in useChat's `write()`.
+ *
+ * Note: concurrent `sendMessage` calls from the same user are a useChat
+ * limitation that cannot be fixed from the transport layer. The
+ * developer must respect useChat's `status` and only call `sendMessage`
+ * when status is `'ready'`.
  * @param transport - The core client transport to wrap.
  * @param chatOptions - Optional hooks for customizing request construction.
  * @returns A {@link ChatTransport} compatible with Vercel's useChat hook.
@@ -144,17 +226,73 @@ export interface ChatTransport {
 export const createChatTransport = (
   transport: ClientTransport<AI.UIMessageChunk, AI.UIMessage>,
   chatOptions?: ChatTransportOptions,
-): ChatTransport => ({
-  sendMessages: async (opts) => {
+): ChatTransport => {
+  // -- Streaming state -------------------------------------------------------
+  let _streaming = false;
+  const streamingCallbacks = new Set<(streaming: boolean) => void>();
+
+  const setStreaming = (value: boolean): void => {
+    _streaming = value;
+    for (const cb of streamingCallbacks) {
+      try {
+        cb(value);
+      } catch {
+        // Isolate subscriber errors so one bad handler doesn't prevent
+        // other subscribers from being notified or block the streaming
+        // state transition.
+      }
+    }
+  };
+
+  // -- sendMessages implementation -------------------------------------------
+
+  const sendMessages: ChatTransport['sendMessages'] = async (opts) => {
     const { messages, abortSignal, trigger, messageId } = opts;
+    const allNodes = transport.view.flattenNodes();
+
+    // useChat calls sendMessages in three distinct modes. We disambiguate
+    // by (trigger, last-message role) so each mode dispatches correctly:
+    //
+    //   - 'regenerate-message'                          → fork an assistant
+    //   - 'submit-message' + last message is assistant  → continuation
+    //                                                     (auto-submit after
+    //                                                     addToolResult, or
+    //                                                     multi-step tool use)
+    //   - 'submit-message' + last message is user       → new user message
+    //                                                     (or edit if
+    //                                                     messageId is set)
+    //
+    // Continuation mode must NOT publish the assistant as a new message or
+    // treat messageId as a fork target — useChat v6's sendAutomaticallyWhen
+    // path always sets messageId to the last message id regardless.
+    //
+    // Client-side tool outputs are expected to be staged on the transport
+    // via transport.stageEvents() before this runs; the core transport
+    // flushes staged events into the POST body automatically.
+    const lastMessage = messages.at(-1);
+    const lastMessageNode = lastMessage ? allNodes.find((n) => n.message.id === lastMessage.id) : undefined;
+    const isContinuation = trigger === 'submit-message' && lastMessage?.role === 'assistant' && !!lastMessageNode;
 
-    // Determine the history/messages split based on trigger.
-    // - submit-message: useChat appended the new user message → last is new
-    // - regenerate-message: useChat truncated the array → no new messages
+    // Fork-on-unresolved-tool: user sent a new message while the preceding
+    // assistant has an unresolved tool call (approval-requested, input-*).
+    // Fork the new message off the preceding assistant so the unresolved
+    // tool call stays dormant on a sibling branch. Inference this turn runs
+    // on the clean fork — the LLM never sees the dangling tool_use.
+    //
+    // Only applies to fresh user-message submits (not continuations, not
+    // regenerates, not edits-with-messageId).
+    const precedingMessage =
+      trigger === 'submit-message' && !messageId && lastMessage?.role === 'user' ? messages.at(-2) : undefined;
+    const forkSource =
+      precedingMessage && hasUnresolvedToolCall(precedingMessage)
+        ? allNodes.find((n) => n.message.id === precedingMessage.id)
+        : undefined;
+
+    // Determine the history/messages split based on mode.
     let newMessages: AI.UIMessage[];
     let history: AI.UIMessage[];
 
-    if (trigger === 'regenerate-message') {
+    if (trigger === 'regenerate-message' || isContinuation) {
       newMessages = [];
       history = messages;
     } else {
@@ -168,27 +306,38 @@ export const createChatTransport = (
       // CAST: length check above guarantees at least one element; .at(-1) cannot be undefined.
       // eslint-disable-next-line @typescript-eslint/non-nullable-type-assertion-style -- prefer `as` over `!` per TYPES.md
       newMessages = [messages.at(-1) as AI.UIMessage];
-      history = messages.slice(0, -1);
+      // When forking off an unresolved tool call, drop the unresolved
+      // assistant from history too — it belongs on the sibling branch, not
+      // the ancestor chain of the new message.
+      history = forkSource ? messages.slice(0, -2) : messages.slice(0, -1);
     }
 
-    // Compute fork metadata from the conversation tree.
-    // For regeneration: forkOf = messageId (the assistant message being regenerated),
-    //   parent = the parent of that message in the tree.
+    // Compute fork metadata. Only set in regenerate or edit modes — in
+    // continuation mode we do NOT fork, we continue the branch.
     let forkOf: string | undefined;
-    let parent: string | null | undefined;
+    let parent: string | undefined;
 
-    if (trigger === 'regenerate-message' && messageId) {
+    if (messageId && !isContinuation) {
+      // Regeneration: messageId = assistant to regenerate.
+      // Edit (submit-message with user message and messageId): messageId = user being replaced.
+      // In both cases forkOf = the x-ably-msg-id, parent = that message's parent.
       forkOf = messageId;
-      // Look up the parent of the message being regenerated.
-      // messageId comes from useChat (UIMessage.id), so use getNodeByKey
-      // which resolves via the codec key secondary index.
-      const node = transport.getTree().getNodeByKey(messageId);
+      const node = allNodes.find((n) => n.message.id === messageId);
       if (node) {
-        // Use the tree node's msgId (x-ably-msg-id) as forkOf — this is
-        // what the server stamps on the wire, not the UIMessage.id.
         forkOf = node.msgId;
         parent = node.parentId;
       }
+    } else if (isContinuation) {
+      // Continuation: the server's next assistant message is a child of the
+      // last assistant (no fork). Pass parent so the server places the new
+      // message correctly in the tree. isContinuation narrows lastMessageNode
+      // to defined.
+      parent = lastMessageNode.msgId;
+    } else if (forkSource) {
+      // Fork off the preceding assistant — the new user message becomes a
+      // sibling of the unresolved tool call assistant, rooted at its parent.
+      forkOf = forkSource.msgId;
+      parent = forkSource.parentId;
     }
 
     let sendBody: Record<string, unknown>;
@@ -196,7 +345,7 @@ export const createChatTransport = (
 
     if (chatOptions?.prepareSendMessagesRequest) {
       const prepared = chatOptions.prepareSendMessagesRequest({
-        id: opts.chatId,
+        chatId: opts.chatId,
         trigger,
         messageId,
         history,
@@ -207,13 +356,11 @@ export const createChatTransport = (
       sendBody = prepared.body ?? {};
       sendHeaders = prepared.headers;
     } else {
-      const historyWithHeaders = history.map((m) => ({
-        message: m,
-        headers: transport.getMessageHeaders(m),
-      }));
+      const historyIds = new Set(history.map((m) => m.id));
+      const historyNodes = allNodes.filter((n) => historyIds.has(n.message.id));
       sendBody = {
-        history: historyWithHeaders,
-        id: opts.chatId,
+        history: historyNodes,
+        chatId: opts.chatId,
         trigger,
         ...(messageId !== undefined && { messageId }),
         ...(forkOf !== undefined && { forkOf }),
@@ -226,53 +373,52 @@ export const createChatTransport = (
     if (forkOf !== undefined) sendOpts.forkOf = forkOf;
     if (parent !== undefined) sendOpts.parent = parent;
 
-    const turn = await transport.send(newMessages, sendOpts);
+    // A single dispatch path: view.send with the (possibly empty)
+    // newMessages array. Any events staged via transport.stageEvents()
+    // flow automatically through _internalSend into the POST body.
+    const turn = await transport.view.send(newMessages, sendOpts);
 
-    // Wire abort signal to cancel all turns on the channel.
-    // In multi-user scenarios, any client can stop any stream — cancelling
-    // by specific turnId would only work for the sender.
     if (abortSignal) {
       abortSignal.addEventListener('abort', () => void transport.cancel({ all: true }), {
         once: true,
       });
     }
 
-    // Return an empty stream that closes when the turn ends.
-    // useChat consumes the returned stream to accumulate the assistant message,
-    // but useMessageSync already pushes the transport's authoritative message
-    // state into useChat via setMessages. Returning the real event stream would
-    // cause useChat to accumulate a duplicate assistant message. Instead, we
-    // return a stream that produces no chunks and closes when the turn's stream
-    // finishes, so useChat knows when streaming is done without duplicating state.
-    const { readable, writable } = new TransformStream<AI.UIMessageChunk>();
-    const writer = writable.getWriter();
-    // Fire-and-forget: we only care about the close/abort signal, not the piped data.
-    // Errors on the turn stream are surfaced via transport.on('error'), not here.
-    /* eslint-disable @typescript-eslint/no-empty-function -- swallow: writer.close() rejection after stream teardown is unrecoverable */
-    turn.stream
-      .pipeTo(
-        new WritableStream({
-          close: () => {
-            writer.close().catch(() => {});
-          },
-          abort: () => {
-            writer.close().catch(() => {});
-          },
-        }),
-      )
-      .catch(() => {
-        writer.close().catch(() => {});
-      });
-    /* eslint-enable @typescript-eslint/no-empty-function */
-    return readable;
-  },
-
-  // Observer mode handles in-progress streams automatically.
-  // The transport subscribes before attach — on the next server append,
-  // observer accumulation emits lifecycle events that useMessageSync
-  // upserts into React state.
-  // eslint-disable-next-line unicorn/no-null, @typescript-eslint/promise-function-async -- null is required by the AI SDK ChatTransport contract; no await needed
-  reconnectToStream: () => Promise.resolve(null),
-
-  close: async (options?: CloseOptions) => transport.close(options),
-});
+    // Wrap the stream to detect completion. The streaming flag gates
+    // useMessageSync so that setMessages doesn't interfere with
+    // useChat's internal write() during active streams.
+    const { stream, done } = wrapStreamWithDone(turn.stream);
+    setStreaming(true);
+
+    // Fire-and-forget: clear the streaming flag when the stream ends.
+    void done.then(() => {
+      setStreaming(false);
+    });
+
+    return stream;
+  };
+
+  return {
+    sendMessages,
+
+    // Observer mode handles in-progress streams automatically.
+    // The transport subscribes before attach — on the next server append,
+    // observer accumulation emits lifecycle events that useMessageSync
+    // upserts into React state.
+    // eslint-disable-next-line unicorn/no-null, @typescript-eslint/promise-function-async -- null is required by the AI SDK ChatTransport contract; no await needed
+    reconnectToStream: () => Promise.resolve(null),
+
+    close: async (options?: CloseOptions) => transport.close(options),
+
+    get streaming(): boolean {
+      return _streaming;
+    },
+
+    onStreamingChange: (callback: (streaming: boolean) => void): (() => void) => {
+      streamingCallbacks.add(callback);
+      return () => {
+        streamingCallbacks.delete(callback);
+      };
+    },
+  };
+};

package/src/vercel/transport/index.ts

@@ -27,12 +27,17 @@ import type {
 } from '../../core/transport/types.js';
 import { UIMessageCodec } from '../codec/index.js';
 
-/** Options for creating a Vercel client transport. Same as core options but without the codec field. */
-export type VercelClientTransportOptions = Omit<ClientTransportOptions<AI.UIMessageChunk, AI.UIMessage>, 'codec'>;
+/** Core client transport options with Vercel AI SDK types pre-applied. */
+type CoreClientOpts = ClientTransportOptions<AI.UIMessageChunk, AI.UIMessage>;
+
+/** Options for creating a Vercel client transport. Same as core options but without the codec field, and with `api` optional (defaults to `"/api/chat"`). */
+export type VercelClientTransportOptions = Omit<CoreClientOpts, 'codec' | 'api'> & Partial<Pick<CoreClientOpts, 'api'>>;
 
 /** Options for creating a Vercel server transport. Same as core options but without the codec field. */
 export type VercelServerTransportOptions = Omit<ServerTransportOptions<AI.UIMessageChunk, AI.UIMessage>, 'codec'>;
 
+export const DEFAULT_VERCEL_API = '/api/chat';
+
 /**
  * Create a client-side transport pre-configured with the Vercel AI SDK codec.
  *
@@ -42,7 +47,13 @@ export type VercelServerTransportOptions = Omit<ServerTransportOptions<AI.UIMess
  */
 export const createClientTransport = (
   options: VercelClientTransportOptions,
-): ClientTransport<AI.UIMessageChunk, AI.UIMessage> => createCoreClientTransport({ ...options, codec: UIMessageCodec });
+): ClientTransport<AI.UIMessageChunk, AI.UIMessage> =>
+  createCoreClientTransport({
+    ...options,
+    codec: UIMessageCodec,
+    // Mirrors the Vercel AI SDK's DefaultChatTransport default.
+    api: options.api ?? DEFAULT_VERCEL_API,
+  });
 
 /**
  * Create a server-side transport pre-configured with the Vercel AI SDK codec.

package/dist/core/transport/conversation-tree.d.ts

@@ -1,9 +0,0 @@
-import { Logger } from '../../logger.js';
-import { ConversationTree } from './types.js';
-/**
- * Create a ConversationTree that materializes branching history from a flat oplog.
- * @param getKey - Codec function that returns a stable key for a domain message.
- * @param logger - Logger for diagnostic output.
- * @returns A new {@link ConversationTree} instance.
- */
-export declare const createConversationTree: <TMessage>(getKey: (message: TMessage) => string, logger: Logger) => ConversationTree<TMessage>;

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

@@ -1,20 +0,0 @@
-import { ClientTransport } from '../core/transport/types.js';
-/** Handle for navigating the branching conversation tree. */
-export interface ConversationTreeHandle<TMessage> {
-    /** Linear message list for the currently selected branch. */
-    messages: TMessage[];
-    /** Get all sibling messages at a fork point. */
-    getSiblings: (msgId: string) => TMessage[];
-    /** Whether a message has siblings (should show navigation arrows). */
-    hasSiblings: (msgId: string) => boolean;
-    /** Index of the currently selected sibling. */
-    getSelectedIndex: (msgId: string) => number;
-    /** Navigate to a sibling. Triggers re-render with updated messages. */
-    selectSibling: (msgId: string, index: number) => void;
-}
-/**
- * Subscribe to transport message updates and provide branch navigation primitives.
- * @param transport - The client transport whose conversation tree to navigate.
- * @returns A {@link ConversationTreeHandle} with the current messages and navigation methods.
- */
-export declare const useConversationTree: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>) => ConversationTreeHandle<TMessage>;

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

@@ -1,7 +0,0 @@
-import { ActiveTurn, ClientTransport, SendOptions } from '../core/transport/types.js';
-/**
- * Return a stable `edit` callback bound to the given transport.
- * @param transport - The client transport to edit through.
- * @returns A function that edits a user message and returns an {@link ActiveTurn} handle.
- */
-export declare const useEdit: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>) => ((messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>);

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

@@ -1,19 +0,0 @@
-import { ClientTransport, LoadHistoryOptions } from '../core/transport/types.js';
-/** Handle for paginated history loading. */
-export interface HistoryHandle {
-    /** Are there older pages available? False until `load()` has been called. */
-    hasNext: boolean;
-    /** Is a page being fetched? */
-    loading: boolean;
-    /** Load the first page (or re-load with different options). Inserts into the conversation tree. */
-    load: (options?: LoadHistoryOptions) => Promise<void>;
-    /** Fetch the next (older) page. No-op if loading or no more pages. Inserts into the conversation tree. */
-    next: () => Promise<void>;
-}
-/**
- * Paginated history handle for a client transport.
- * @param transport - The client transport to load history from, or null/undefined if not yet available.
- * @param options - When provided, auto-loads the first page on mount. Omit or pass null for manual loading.
- * @returns A {@link HistoryHandle} for loading and paginating through history.
- */
-export declare const useHistory: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage> | null | undefined, options?: LoadHistoryOptions | null) => HistoryHandle;

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

@@ -1,7 +0,0 @@
-import { ClientTransport } from '../core/transport/types.js';
-/**
- * Subscribe to transport message updates and return the current message list.
- * @param transport - The client transport to observe.
- * @returns The current list of decoded messages.
- */
-export declare const useMessages: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>) => TMessage[];

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

@@ -1,7 +0,0 @@
-import { ActiveTurn, ClientTransport, SendOptions } from '../core/transport/types.js';
-/**
- * Return a stable `regenerate` callback bound to the given transport.
- * @param transport - The client transport to regenerate through.
- * @returns A function that regenerates an assistant message and returns an {@link ActiveTurn} handle.
- */
-export declare const useRegenerate: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>) => ((messageId: string, options?: SendOptions) => Promise<ActiveTurn<TEvent>>);

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

@@ -1,7 +0,0 @@
-import { ActiveTurn, ClientTransport, SendOptions } from '../core/transport/types.js';
-/**
- * Return a stable `send` callback bound to the given transport.
- * @param transport - The client transport to send through.
- * @returns A function that sends messages and returns an {@link ActiveTurn} handle.
- */
-export declare const useSend: <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>) => ((messages: TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>);

package/src/react/use-conversation-tree.ts

@@ -1,71 +0,0 @@
-/**
- * useConversationTree — reactive branch navigation for a ClientTransport.
- *
- * Subscribes to the transport's "message" notification and provides
- * branch navigation primitives (getSiblings, selectSibling, hasSiblings)
- * backed by the transport's ConversationTree.
- *
- * Branch selection state is local to the hook instance — each component
- * (or tab) can navigate branches independently.
- */
-
-import { useCallback, useEffect, useState } from 'react';
-
-import type { ClientTransport } from '../core/transport/types.js';
-
-/** Handle for navigating the branching conversation tree. */
-export interface ConversationTreeHandle<TMessage> {
-  /** Linear message list for the currently selected branch. */
-  messages: TMessage[];
-  /** Get all sibling messages at a fork point. */
-  getSiblings: (msgId: string) => TMessage[];
-  /** Whether a message has siblings (should show navigation arrows). */
-  hasSiblings: (msgId: string) => boolean;
-  /** Index of the currently selected sibling. */
-  getSelectedIndex: (msgId: string) => number;
-  /** Navigate to a sibling. Triggers re-render with updated messages. */
-  selectSibling: (msgId: string, index: number) => void;
-}
-
-/**
- * Subscribe to transport message updates and provide branch navigation primitives.
- * @param transport - The client transport whose conversation tree to navigate.
- * @returns A {@link ConversationTreeHandle} with the current messages and navigation methods.
- */
-export const useConversationTree = <TEvent, TMessage>(
-  transport: ClientTransport<TEvent, TMessage>,
-): ConversationTreeHandle<TMessage> => {
-  const [messages, setMessages] = useState<TMessage[]>(() => transport.getMessages());
-
-  useEffect(() => {
-    setMessages(transport.getMessages());
-
-    const unsub = transport.on('message', () => {
-      setMessages(transport.getMessages());
-    });
-    return unsub;
-  }, [transport]);
-
-  const getSiblings = useCallback((msgId: string) => transport.getTree().getSiblings(msgId), [transport]);
-
-  const hasSiblings = useCallback((msgId: string) => transport.getTree().hasSiblings(msgId), [transport]);
-
-  const getSelectedIndex = useCallback((msgId: string) => transport.getTree().getSelectedIndex(msgId), [transport]);
-
-  const selectSibling = useCallback(
-    (msgId: string, index: number) => {
-      transport.getTree().select(msgId, index);
-      // flatten() returns a new array after select(), triggering re-render.
-      setMessages(transport.getMessages());
-    },
-    [transport],
-  );
-
-  return {
-    messages,
-    getSiblings,
-    hasSiblings,
-    getSelectedIndex,
-    selectSibling,
-  };
-};

package/src/react/use-edit.ts

@@ -1,24 +0,0 @@
-/**
- * useEdit — stable callback for editing a user message.
- *
- * Delegates to `transport.edit()`, which automatically computes
- * `forkOf`, `parent`, and history from the conversation tree.
- */
-
-import { useCallback } from 'react';
-
-import type { ActiveTurn, ClientTransport, SendOptions } from '../core/transport/types.js';
-
-/**
- * Return a stable `edit` callback bound to the given transport.
- * @param transport - The client transport to edit through.
- * @returns A function that edits a user message and returns an {@link ActiveTurn} handle.
- */
-export const useEdit = <TEvent, TMessage>(
-  transport: ClientTransport<TEvent, TMessage>,
-): ((messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>) =>
-  useCallback(
-    async (messageId: string, newMessages: TMessage | TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>> =>
-      transport.edit(messageId, newMessages, options),
-    [transport],
-  );