@ably/ai-transport 0.0.1 → 0.2.0

package/src/core/transport/turn-manager.ts

@@ -1,147 +0,0 @@
-/**
- * Server-side turn state management and lifecycle event publishing.
- *
- * Owns the authoritative turn lifecycle. Tracks active turns with their
- * AbortControllers and clientIds. Publishes turn-start and turn-end events
- * on the Ably channel so all clients can react to turn state changes.
- */
-
-import type * as Ably from 'ably';
-
-import {
-  EVENT_TURN_END,
-  EVENT_TURN_START,
-  HEADER_TURN_CLIENT_ID,
-  HEADER_TURN_ID,
-  HEADER_TURN_REASON,
-} from '../../constants.js';
-import type { Logger } from '../../logger.js';
-import type { TurnEndReason } from './types.js';
-
-// ---------------------------------------------------------------------------
-// Interface
-// ---------------------------------------------------------------------------
-
-/** Manages active turns and publishes turn lifecycle events on the channel. */
-export interface TurnManager {
-  /** Register a new turn. Publishes turn-start on the channel. Returns AbortSignal. */
-  startTurn(turnId: string, clientId?: string, controller?: AbortController): Promise<AbortSignal>;
-  /** End a turn. Publishes turn-end on the channel. Cleans up internal state. */
-  endTurn(turnId: string, reason: TurnEndReason): Promise<void>;
-  /** Get the AbortSignal for a turn. */
-  getSignal(turnId: string): AbortSignal | undefined;
-  /** Get the clientId that owns a turn. */
-  getClientId(turnId: string): string | undefined;
-  /** Abort the signal for a turn. */
-  abort(turnId: string): void;
-  /** Get all active turn IDs. */
-  getActiveTurnIds(): string[];
-  /** Abort all active turns and clear state. */
-  close(): void;
-}
-
-// ---------------------------------------------------------------------------
-// Internal state
-// ---------------------------------------------------------------------------
-
-interface TurnState {
-  controller: AbortController;
-  clientId: string;
-}
-
-// ---------------------------------------------------------------------------
-// Implementation
-// ---------------------------------------------------------------------------
-
-class DefaultTurnManager implements TurnManager {
-  private readonly _channel: Ably.RealtimeChannel;
-  private readonly _logger: Logger | undefined;
-  private readonly _activeTurns = new Map<string, TurnState>();
-
-  constructor(channel: Ably.RealtimeChannel, logger?: Logger) {
-    this._channel = channel;
-    this._logger = logger?.withContext({ component: 'TurnManager' });
-  }
-
-  async startTurn(turnId: string, clientId?: string, externalController?: AbortController): Promise<AbortSignal> {
-    this._logger?.trace('DefaultTurnManager.startTurn();', { turnId, clientId });
-
-    const controller = externalController ?? new AbortController();
-    const resolvedClientId = clientId ?? '';
-    this._activeTurns.set(turnId, { controller, clientId: resolvedClientId });
-
-    await this._channel.publish({
-      name: EVENT_TURN_START,
-      extras: {
-        headers: {
-          [HEADER_TURN_ID]: turnId,
-          [HEADER_TURN_CLIENT_ID]: resolvedClientId,
-        },
-      },
-    });
-
-    this._logger?.debug('DefaultTurnManager.startTurn(); turn started', { turnId });
-    return controller.signal;
-  }
-
-  async endTurn(turnId: string, reason: TurnEndReason): Promise<void> {
-    this._logger?.trace('DefaultTurnManager.endTurn();', { turnId, reason });
-
-    const state = this._activeTurns.get(turnId);
-    const resolvedClientId = state?.clientId ?? '';
-
-    // Publish before deleting local state so that if publish fails,
-    // the turn remains in the active set and can be retried or cleaned up.
-    await this._channel.publish({
-      name: EVENT_TURN_END,
-      extras: {
-        headers: {
-          [HEADER_TURN_ID]: turnId,
-          [HEADER_TURN_CLIENT_ID]: resolvedClientId,
-          [HEADER_TURN_REASON]: reason,
-        },
-      },
-    });
-
-    this._activeTurns.delete(turnId);
-    this._logger?.debug('DefaultTurnManager.endTurn(); turn ended', { turnId, reason });
-  }
-
-  getSignal(turnId: string): AbortSignal | undefined {
-    return this._activeTurns.get(turnId)?.controller.signal;
-  }
-
-  getClientId(turnId: string): string | undefined {
-    return this._activeTurns.get(turnId)?.clientId;
-  }
-
-  abort(turnId: string): void {
-    this._logger?.debug('DefaultTurnManager.abort();', { turnId });
-    this._activeTurns.get(turnId)?.controller.abort();
-  }
-
-  getActiveTurnIds(): string[] {
-    return [...this._activeTurns.keys()];
-  }
-
-  close(): void {
-    this._logger?.trace('DefaultTurnManager.close();', { activeTurns: this._activeTurns.size });
-    for (const state of this._activeTurns.values()) {
-      state.controller.abort();
-    }
-    this._activeTurns.clear();
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Factory
-// ---------------------------------------------------------------------------
-
-/**
- * Create a turn manager bound to the given channel.
- * @param channel - The Ably channel to publish lifecycle events on.
- * @param logger - Optional logger for diagnostic output.
- * @returns A new {@link TurnManager} instance.
- */
-export const createTurnManager = (channel: Ably.RealtimeChannel, logger?: Logger): TurnManager =>
-  new DefaultTurnManager(channel, logger);

package/src/react/use-active-turns.ts

@@ -1,61 +0,0 @@
-/**
- * useActiveTurns: reactive view of active turns on the channel,
- * keyed by clientId.
- *
- * Subscribes to transport turn lifecycle events and maintains a
- * Map<clientId, Set<turnId>> that updates on every turn start/end.
- *
- * Generic — works with any codec, not tied to Vercel types.
- */
-
-import { useEffect, useState } from 'react';
-
-import { EVENT_TURN_START } from '../constants.js';
-import type { ClientTransport, TurnLifecycleEvent } from '../core/transport/types.js';
-
-/**
- * Returns a reactive Map of all active turns on the channel, keyed by clientId.
- * Updates when turns start or end.
- * @param transport - The client transport to observe, or null/undefined if not yet available.
- * @returns A Map where keys are clientIds and values are Sets of active turnIds.
- */
-export const useActiveTurns = <TEvent, TMessage>(
-  transport: ClientTransport<TEvent, TMessage> | null | undefined,
-): Map<string, Set<string>> => {
-  const [turns, setTurns] = useState<Map<string, Set<string>>>(() => new Map());
-
-  useEffect(() => {
-    if (!transport) return;
-
-    // Initialize from current state
-    setTurns(transport.getActiveTurnIds());
-
-    const unsubscribe = transport.on('turn', (event: TurnLifecycleEvent) => {
-      setTurns((prev) => {
-        const next = new Map(prev);
-
-        if (event.type === EVENT_TURN_START) {
-          const set = new Set(next.get(event.clientId) ?? []);
-          set.add(event.turnId);
-          next.set(event.clientId, set);
-        } else {
-          const set = next.get(event.clientId);
-          if (set) {
-            set.delete(event.turnId);
-            if (set.size === 0) {
-              next.delete(event.clientId);
-            } else {
-              next.set(event.clientId, new Set(set));
-            }
-          }
-        }
-
-        return next;
-      });
-    });
-
-    return unsubscribe;
-  }, [transport]);
-
-  return turns;
-};

package/src/react/use-client-transport.ts

@@ -1,37 +0,0 @@
-/**
- * useClientTransport: creates and memoizes a core ClientTransport instance
- * across renders.
- *
- * Stores the instance in a ref so the same transport is returned on every render.
- * The transport manages its own Ably channel subscription in the constructor —
- * this hook adds no subscription logic.
- *
- * The hook does NOT auto-close the transport on unmount. Channel lifecycle is
- * managed by the Ably provider (useChannel), which detaches the channel and
- * clears all subscriptions. Auto-closing would break React Strict Mode
- * (double-mount calls close() on the first cleanup, leaving a dead transport
- * on the second mount). Call transport.close() explicitly if you need to tear
- * down the transport independently of the channel lifecycle.
- */
-
-import { useRef } from 'react';
-
-import { createClientTransport } from '../core/transport/client-transport.js';
-import type { ClientTransport, ClientTransportOptions } from '../core/transport/types.js';
-
-/**
- * Create and memoize a {@link ClientTransport} across renders.
- * @param options - Configuration for the client transport.
- * @returns The memoized transport instance.
- */
-export const useClientTransport = <TEvent, TMessage>(
-  options: ClientTransportOptions<TEvent, TMessage>,
-): ClientTransport<TEvent, TMessage> => {
-  const transportRef = useRef<ClientTransport<TEvent, TMessage> | null>(null);
-
-  if (transportRef.current === null) {
-    transportRef.current = createClientTransport(options);
-  }
-
-  return transportRef.current;
-};

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],
-  );

package/src/react/use-history.ts

@@ -1,111 +0,0 @@
-/**
- * useHistory — history pagination handle for a ClientTransport.
- *
- * Returns a `HistoryHandle` with `load()`, `next()`, `hasNext`, and
- * `loading` — mirroring the transport's `history()` and
- * `PaginatedMessages` API.
- *
- * The transport's `history()` is branch-aware: `limit` means "keep loading
- * until N new messages appear on the selected branch." Messages on
- * unselected branches are loaded into the tree but not counted toward the
- * limit. The returned `items` contain only the newly visible messages.
- *
- * When `options` are provided, auto-loads the first page on mount
- * (SWR-style: options present = enabled). When omitted or null,
- * no auto-load — call `load()` manually.
- *
- * Usage:
- * ```tsx
- * // Auto-load on mount
- * const history = useHistory(transport, { limit: 30 });
- *
- * // Manual load (e.g. on button press)
- * const history = useHistory(transport);
- * // ...later: await history.load({ limit: 30 });
- *
- * // Scroll-back
- * if (history.hasNext) await history.next();
- * ```
- */
-
-import { useCallback, useEffect, useRef, useState } from 'react';
-
-import type { ClientTransport, LoadHistoryOptions, PaginatedMessages } 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 const useHistory = <TEvent, TMessage>(
-  transport: ClientTransport<TEvent, TMessage> | null | undefined,
-  options?: LoadHistoryOptions | null,
-): HistoryHandle => {
-  const [hasNext, setHasNext] = useState(false);
-  const [loading, setLoading] = useState(false);
-  const loadingRef = useRef(false);
-  const pageRef = useRef<PaginatedMessages<TMessage> | null>(null);
-  const transportRef = useRef(transport);
-  transportRef.current = transport;
-
-  const load = useCallback(async (loadOptions?: LoadHistoryOptions) => {
-    if (!transportRef.current || loadingRef.current) return;
-    loadingRef.current = true;
-    setLoading(true);
-    try {
-      const page = await transportRef.current.history(loadOptions);
-      pageRef.current = page;
-      setHasNext(page.hasNext());
-    } finally {
-      loadingRef.current = false;
-      setLoading(false);
-    }
-  }, []);
-
-  const next = useCallback(async () => {
-    const page = pageRef.current;
-    if (!page || !page.hasNext() || loadingRef.current || !transportRef.current) return;
-
-    loadingRef.current = true;
-    setLoading(true);
-    try {
-      const older = await page.next();
-      if (older) {
-        pageRef.current = older;
-        setHasNext(older.hasNext());
-      } else {
-        setHasNext(false);
-      }
-    } finally {
-      loadingRef.current = false;
-      setLoading(false);
-    }
-  }, []);
-
-  // Auto-load first page on mount when options are provided (SWR-style).
-  const autoLoad = options !== undefined && options !== null;
-  const autoLoadedRef = useRef(false);
-  const optionsRef = useRef(options);
-  optionsRef.current = options;
-
-  useEffect(() => {
-    if (!autoLoad || autoLoadedRef.current || !transportRef.current) return;
-    autoLoadedRef.current = true;
-    void load(optionsRef.current ?? undefined);
-  }, [autoLoad, load]);
-
-  return { hasNext, loading, load, next };
-};

package/src/react/use-messages.ts

@@ -1,32 +0,0 @@
-/**
- * useMessages — reactive message list from a ClientTransport.
- *
- * Subscribes to the transport's "message" notification and returns
- * the current message list as React state. Replaces the manual
- * useState + useEffect + on("message") + getMessages() pattern.
- */
-
-import { useEffect, useState } from 'react';
-
-import type { 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 const useMessages = <TEvent, TMessage>(transport: ClientTransport<TEvent, TMessage>): TMessage[] => {
-  const [messages, setMessages] = useState<TMessage[]>(() => transport.getMessages());
-
-  useEffect(() => {
-    // Sync initial state in case the transport already has messages
-    setMessages(transport.getMessages());
-
-    const unsub = transport.on('message', () => {
-      setMessages(transport.getMessages());
-    });
-    return unsub;
-  }, [transport]);
-
-  return messages;
-};

package/src/react/use-regenerate.ts

@@ -1,24 +0,0 @@
-/**
- * useRegenerate — stable callback for regenerating an assistant message.
- *
- * Delegates to `transport.regenerate()`, which automatically computes
- * `forkOf`, `parent`, and truncated history from the conversation tree.
- */
-
-import { useCallback } from 'react';
-
-import type { 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 const useRegenerate = <TEvent, TMessage>(
-  transport: ClientTransport<TEvent, TMessage>,
-): ((messageId: string, options?: SendOptions) => Promise<ActiveTurn<TEvent>>) =>
-  useCallback(
-    async (messageId: string, options?: SendOptions): Promise<ActiveTurn<TEvent>> =>
-      transport.regenerate(messageId, options),
-    [transport],
-  );

package/src/react/use-send.ts

@@ -1,25 +0,0 @@
-/**
- * useSend — stable callback for sending messages through a ClientTransport.
- *
- * Returns a `send` function that sends one or more messages in a single
- * turn via `transport.send()`. Callers construct the domain messages
- * themselves; the hook provides a stable reference suitable for React deps.
- */
-
-import { useCallback } from 'react';
-
-import type { 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 const useSend = <TEvent, TMessage>(
-  transport: ClientTransport<TEvent, TMessage>,
-): ((messages: TMessage[], options?: SendOptions) => Promise<ActiveTurn<TEvent>>) =>
-  useCallback(
-    async (messages: TMessage[], options?: SendOptions): Promise<ActiveTurn<TEvent>> =>
-      transport.send(messages, options),
-    [transport],
-  );