@steerable/agent-ui 0.2.3 → 0.2.5

package/src/state/useChatList.ts

@@ -0,0 +1,220 @@
+/**
+ * `useChatList` — paginated chat-summary + agent-catalog state for the chat
+ * sidebar. Generic in the chat and agent shapes so cloud and local apps reuse
+ * the same hook (the cloud schema has extra fields on `Chat`, the local
+ * schema has fewer).
+ *
+ * Lifted from deeppath-agent's `useChatsAndAgents.ts` and deeppath's
+ * `useChatUI` chat-list subset. The hook owns:
+ *   - paginated chat list with "load more" and refresh
+ *   - the agent catalog (single page for now)
+ *   - the agent picked for the next new chat
+ *   - in-place title patching (used by `chat_title_updated` SSE events to
+ *     avoid clobbering pagination state with a full refresh)
+ *   - create / delete chat actions, with optimistic patching of the local
+ *     list.
+ *
+ * The transport is provided by the consumer so the same hook serves Electron
+ * IPC, the cloud REST client, or any other backend.
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type Dispatch,
+  type SetStateAction,
+} from 'react';
+
+export interface ChatListTransport<TChat, TAgent> {
+  listChats: (input: { page: number; pageSize: number }) => Promise<{
+    chats: TChat[];
+    hasMore: boolean;
+  }>;
+  listAgents: () => Promise<TAgent[]>;
+  createChat?: (input: { agentId?: string; projectId?: string }) => Promise<TChat | string>;
+  deleteChat?: (chatId: string) => Promise<boolean>;
+  /** Tell the hook how to read a chat's id and title. */
+  getChatId: (chat: TChat) => string;
+  setChatTitle?: (chat: TChat, title: string) => TChat;
+  /** Tell the hook how to read an agent's id (for `selectedAgentId`). */
+  getAgentId: (agent: TAgent) => string;
+}
+
+export interface UseChatListOptions<TChat, TAgent> {
+  transport: ChatListTransport<TChat, TAgent>;
+  /** Defaults to 50. */
+  pageSize?: number;
+  /** Skip the mount-time fetch (e.g. SSR contexts). */
+  skipInitialLoad?: boolean;
+}
+
+export interface UseChatListReturn<TChat, TAgent> {
+  chats: TChat[];
+  agents: TAgent[];
+  isLoading: boolean;
+  isLoadingMoreChats: boolean;
+  hasMoreChats: boolean;
+  error: Error | null;
+  selectedAgentId: string | null;
+  /**
+   * Accepts either a plain value or a React-style updater function so
+   * adapters can patch the selection without re-reading the current value.
+   */
+  setSelectedAgentId: Dispatch<SetStateAction<string | null>>;
+  refreshChats: () => Promise<void>;
+  refreshAgents: () => Promise<void>;
+  loadMoreChats: () => Promise<void>;
+  createChat: (input?: { agentId?: string; projectId?: string }) => Promise<string | null>;
+  deleteChat: (chatId: string) => Promise<boolean>;
+  /** In-place title patcher — does not hit the server. */
+  patchChatTitle: (chatId: string, title: string) => void;
+}
+
+export function useChatList<TChat, TAgent>(
+  options: UseChatListOptions<TChat, TAgent>,
+): UseChatListReturn<TChat, TAgent> {
+  const pageSize = options.pageSize ?? 50;
+  const transportRef = useRef(options.transport);
+  transportRef.current = options.transport;
+
+  const [chats, setChats] = useState<TChat[]>([]);
+  const [agents, setAgents] = useState<TAgent[]>([]);
+  const [isLoading, setLoading] = useState(!options.skipInitialLoad);
+  const [isLoadingMoreChats, setLoadingMore] = useState(false);
+  const [hasMoreChats, setHasMore] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [selectedAgentId, setSelectedAgentId] = useState<string | null>(null);
+  const pageRef = useRef(1);
+  const mountedRef = useRef(true);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const refreshChats = useCallback(async () => {
+    setLoading(true);
+    try {
+      const res = await transportRef.current.listChats({ page: 1, pageSize });
+      if (!mountedRef.current) return;
+      setChats(res.chats);
+      setHasMore(res.hasMore);
+      pageRef.current = 1;
+      setError(null);
+    } catch (err) {
+      if (mountedRef.current) setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      if (mountedRef.current) setLoading(false);
+    }
+  }, [pageSize]);
+
+  const refreshAgents = useCallback(async () => {
+    try {
+      const list = await transportRef.current.listAgents();
+      if (mountedRef.current) setAgents(list);
+    } catch (err) {
+      if (mountedRef.current) setError(err instanceof Error ? err : new Error(String(err)));
+    }
+  }, []);
+
+  const loadMoreChats = useCallback(async () => {
+    if (!hasMoreChats || isLoadingMoreChats) return;
+    setLoadingMore(true);
+    try {
+      const next = pageRef.current + 1;
+      const res = await transportRef.current.listChats({ page: next, pageSize });
+      if (!mountedRef.current) return;
+      setChats((prev) => prev.concat(res.chats));
+      setHasMore(res.hasMore);
+      pageRef.current = next;
+    } catch (err) {
+      if (mountedRef.current) setError(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      if (mountedRef.current) setLoadingMore(false);
+    }
+  }, [hasMoreChats, isLoadingMoreChats, pageSize]);
+
+  const createChat = useCallback(
+    async (input?: { agentId?: string; projectId?: string }) => {
+      const t = transportRef.current;
+      if (!t.createChat) return null;
+      const created = await t.createChat({
+        agentId: input?.agentId ?? selectedAgentId ?? undefined,
+        projectId: input?.projectId,
+      });
+      // Either a chat object or a bare id.
+      const id = typeof created === 'string' ? created : t.getChatId(created);
+      await refreshChats();
+      return id;
+    },
+    [refreshChats, selectedAgentId],
+  );
+
+  const deleteChat = useCallback(
+    async (chatId: string) => {
+      const t = transportRef.current;
+      if (!t.deleteChat) return false;
+      const ok = await t.deleteChat(chatId);
+      if (ok && mountedRef.current) {
+        setChats((prev) => prev.filter((c) => t.getChatId(c) !== chatId));
+      }
+      return ok;
+    },
+    [],
+  );
+
+  const patchChatTitle = useCallback((chatId: string, title: string) => {
+    const t = transportRef.current;
+    if (!t.setChatTitle) return;
+    setChats((prev) =>
+      prev.map((c) => (t.getChatId(c) === chatId ? t.setChatTitle!(c, title) : c)),
+    );
+  }, []);
+
+  useEffect(() => {
+    if (options.skipInitialLoad) return;
+    void refreshChats();
+    void refreshAgents();
+    // Run once on mount; downstream callers use refresh* explicitly.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  return useMemo<UseChatListReturn<TChat, TAgent>>(
+    () => ({
+      chats,
+      agents,
+      isLoading,
+      isLoadingMoreChats,
+      hasMoreChats,
+      error,
+      selectedAgentId,
+      setSelectedAgentId,
+      refreshChats,
+      refreshAgents,
+      loadMoreChats,
+      createChat,
+      deleteChat,
+      patchChatTitle,
+    }),
+    [
+      chats,
+      agents,
+      isLoading,
+      isLoadingMoreChats,
+      hasMoreChats,
+      error,
+      selectedAgentId,
+      refreshChats,
+      refreshAgents,
+      loadMoreChats,
+      createChat,
+      deleteChat,
+      patchChatTitle,
+    ],
+  );
+}

package/src/state/useChatSession.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Tests for `useChatSession` — the composer-meets-stream convenience hook.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { MockChatStreamTransport } from './MockChatStreamTransport';
+import { useChatSession } from './useChatSession';
+
+describe('useChatSession', () => {
+  it('routes composer.submit through the stream pipeline', async () => {
+    const transport = new MockChatStreamTransport({
+      scripts: [[
+        { type: 'content', content: 'pong' },
+        { type: 'done' },
+      ]],
+    });
+    const { result } = renderHook(() =>
+      useChatSession({ transport, initialValue: '' }),
+    );
+
+    await act(async () => {
+      result.current.composer.setValue('ping');
+    });
+    await act(async () => {
+      await result.current.composer.submit();
+    });
+
+    await waitFor(() => {
+      expect(result.current.messages.length).toBeGreaterThanOrEqual(2);
+    });
+    expect(result.current.messages[0].content).toBe('ping');
+    expect(result.current.composer.value).toBe('');
+  });
+
+  it('forwards build metadata onto the transport', async () => {
+    const stream = vi.fn().mockImplementation(async (_input, onEvent) => {
+      onEvent({ type: 'done' });
+      return () => {};
+    });
+    const { result } = renderHook(() =>
+      useChatSession({
+        transport: { stream },
+        buildMetadata: (v) => ({ length: v.length }),
+      }),
+    );
+
+    await act(async () => {
+      result.current.composer.setValue('hello');
+    });
+    await act(async () => {
+      await result.current.composer.submit();
+    });
+
+    expect(stream).toHaveBeenCalledTimes(1);
+    expect(stream.mock.calls[0][0]).toEqual({
+      content: 'hello',
+      metadata: { length: 5 },
+    });
+  });
+});

package/src/state/useChatSession.ts

@@ -0,0 +1,64 @@
+/**
+ * `useChatSession` — convenience wrapper that combines `useChatStream` (turn
+ * lifecycle) with `useChatComposer` (draft + keys + send). Most consumers want
+ * this single hook so the wiring is identical across web-shell, deeppath, and
+ * deeppath-agent. Power users still reach for the underlying primitives.
+ *
+ *   const { messages, isStreaming, composer, cancel } = useChatSession({
+ *     transport,
+ *     initialMessages,
+ *   });
+ *
+ *   <ChatPanel>
+ *     <MessageList messages={messages} isStreaming={isStreaming} />
+ *     <ChatInput composer={composer} onCancel={cancel} />
+ *   </ChatPanel>
+ */
+
+import { useMemo } from 'react';
+import {
+  useChatStream,
+  type UseChatStreamOptions,
+  type UseChatStreamReturn,
+} from '../hooks/useChatStream.js';
+import {
+  useChatComposer,
+  type UseChatComposerOptions,
+  type UseChatComposerReturn,
+} from './useChatComposer.js';
+
+export interface UseChatSessionOptions
+  extends UseChatStreamOptions,
+    Pick<UseChatComposerOptions, 'enterToSubmit' | 'initialValue'> {
+  /** Optional metadata callback when submitting a message (e.g. @mentions). */
+  buildMetadata?: (value: string) => Record<string, unknown> | undefined;
+  /** Force-disable the composer regardless of streaming state. */
+  composerDisabled?: boolean;
+}
+
+export interface UseChatSessionReturn extends UseChatStreamReturn {
+  composer: UseChatComposerReturn;
+}
+
+export function useChatSession(options: UseChatSessionOptions): UseChatSessionReturn {
+  const stream = useChatStream(options);
+
+  const composer = useChatComposer({
+    initialValue: options.initialValue,
+    enterToSubmit: options.enterToSubmit,
+    isStreaming: stream.isStreaming,
+    disabled: options.composerDisabled,
+    onSend: async (value) => {
+      await stream.sendUserMessage({
+        content: value,
+        metadata: options.buildMetadata?.(value),
+      });
+    },
+    onCancel: stream.cancel,
+  });
+
+  return useMemo(
+    () => ({ ...stream, composer }),
+    [stream, composer],
+  );
+}

package/src/state/useScrollLock.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Tests for `useScrollLock`. happy-dom doesn't compute scroll distance
+ * automatically, so we manually mutate `scrollTop` and dispatch scroll events.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useScrollLock } from './useScrollLock';
+
+function makeScrollContainer(
+  options: { startAtBottom?: boolean } = {},
+): HTMLDivElement {
+  const el = document.createElement('div');
+  Object.defineProperty(el, 'scrollHeight', { value: 1000, writable: true });
+  Object.defineProperty(el, 'clientHeight', { value: 400, writable: true });
+  // happy-dom doesn't implement scrollTo; emulate the clamping browsers do.
+  el.scrollTo = ((opts: ScrollToOptions) => {
+    if (typeof opts === 'object' && typeof opts.top === 'number') {
+      const max = el.scrollHeight - el.clientHeight;
+      el.scrollTop = Math.min(Math.max(0, opts.top), max);
+    }
+  }) as typeof el.scrollTo;
+  if (options.startAtBottom !== false) {
+    el.scrollTop = el.scrollHeight - el.clientHeight;
+  }
+  return el;
+}
+
+describe('useScrollLock', () => {
+  it('auto-scrolls to bottom when revalidate keys change and user is anchored', () => {
+    let keys: ReadonlyArray<unknown> = [0];
+    const { result, rerender } = renderHook(() =>
+      useScrollLock({ revalidateKeys: keys }),
+    );
+    const el = makeScrollContainer();
+    act(() => result.current.setRef(el));
+    expect(result.current.isAnchored).toBe(true);
+
+    keys = [1];
+    rerender();
+    expect(el.scrollTop).toBe(el.scrollHeight - el.clientHeight);
+  });
+
+  it('releases the lock when the user scrolls up past the threshold', () => {
+    const { result } = renderHook(() => useScrollLock({ threshold: 24 }));
+    const el = makeScrollContainer();
+    act(() => result.current.setRef(el));
+    expect(result.current.isAnchored).toBe(true);
+
+    el.scrollTop = 0;
+    act(() => {
+      el.dispatchEvent(new Event('scroll'));
+    });
+    expect(result.current.isAnchored).toBe(false);
+  });
+
+  it('re-anchors once the user scrolls back to the bottom', () => {
+    const { result } = renderHook(() => useScrollLock({ threshold: 24 }));
+    const el = makeScrollContainer();
+    act(() => result.current.setRef(el));
+
+    el.scrollTop = 0;
+    act(() => el.dispatchEvent(new Event('scroll')));
+    expect(result.current.isAnchored).toBe(false);
+
+    el.scrollTop = el.scrollHeight - el.clientHeight;
+    act(() => el.dispatchEvent(new Event('scroll')));
+    expect(result.current.isAnchored).toBe(true);
+  });
+
+  it('scrollToBottom is callable imperatively', () => {
+    const { result } = renderHook(() => useScrollLock());
+    const el = makeScrollContainer({ startAtBottom: false });
+    act(() => result.current.setRef(el));
+    expect(el.scrollTop).toBe(0);
+
+    act(() => result.current.scrollToBottom());
+
+    expect(el.scrollTop).toBe(el.scrollHeight - el.clientHeight);
+  });
+
+  it('does not auto-scroll when the user is unanchored', () => {
+    let keys: ReadonlyArray<unknown> = [0];
+    const { result, rerender } = renderHook(() =>
+      useScrollLock({ revalidateKeys: keys, threshold: 24 }),
+    );
+    const el = makeScrollContainer();
+    act(() => result.current.setRef(el));
+
+    el.scrollTop = 0;
+    act(() => el.dispatchEvent(new Event('scroll')));
+    expect(result.current.isAnchored).toBe(false);
+
+    keys = [1];
+    rerender();
+    // Lock released → no auto-scroll, scrollTop stays at user's position.
+    expect(el.scrollTop).toBe(0);
+  });
+});

package/src/state/useScrollLock.ts

@@ -0,0 +1,105 @@
+/**
+ * `useScrollLock` — sticky-bottom scrolling for streaming message lists.
+ *
+ * The hook returns a callback ref to attach to the scroll container and a
+ * `scrollToBottom` imperative API. Behaviour:
+ *   - When the container's scroll position is within `threshold` px of the
+ *     bottom, the hook treats the user as "anchored" and re-runs
+ *     `scrollToBottom` whenever the dependency array `revalidateKeys` changes.
+ *   - As soon as the user scrolls up past `threshold`, the lock releases —
+ *     the list will no longer auto-scroll until the user scrolls back to the
+ *     bottom (or `scrollToBottom` is called explicitly, e.g. on send).
+ *
+ * Uses a callback ref so the listener attaches the moment the element mounts,
+ * not after a second effect pass. Matches deeppath's MessageList scroll
+ * handling minus the inline MutationObserver+IntersectionObserver soup.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+export interface UseScrollLockOptions {
+  /** Px from the bottom that still counts as "anchored". Default 24. */
+  threshold?: number;
+  /**
+   * Dependencies that, when changed, will trigger an auto-scroll if the user
+   * is currently anchored. Pass e.g. `[messages.length, lastMessageContent]`.
+   */
+  revalidateKeys?: ReadonlyArray<unknown>;
+  /** Scroll smooth vs jump. Defaults to 'auto' (instant). */
+  behavior?: ScrollBehavior;
+}
+
+export interface UseScrollLockReturn<E extends HTMLElement = HTMLDivElement> {
+  /** Callback ref — pass directly to `ref={...}` on the scroll container. */
+  setRef: (el: E | null) => void;
+  isAnchored: boolean;
+  scrollToBottom: (behavior?: ScrollBehavior) => void;
+}
+
+function maxScrollTop(el: HTMLElement): number {
+  return Math.max(0, el.scrollHeight - el.clientHeight);
+}
+
+export function useScrollLock<E extends HTMLElement = HTMLDivElement>(
+  options: UseScrollLockOptions = {},
+): UseScrollLockReturn<E> {
+  const threshold = options.threshold ?? 24;
+  const elRef = useRef<E | null>(null);
+  const cleanupRef = useRef<(() => void) | null>(null);
+  const [isAnchored, setAnchored] = useState(true);
+  const anchoredRef = useRef(true);
+  anchoredRef.current = isAnchored;
+
+  const scrollToBottom = useCallback(
+    (behavior?: ScrollBehavior) => {
+      const el = elRef.current;
+      if (!el) return;
+      el.scrollTo({
+        top: maxScrollTop(el),
+        behavior: behavior ?? options.behavior ?? 'auto',
+      });
+    },
+    [options.behavior],
+  );
+
+  const setRef = useCallback(
+    (el: E | null) => {
+      if (cleanupRef.current) {
+        cleanupRef.current();
+        cleanupRef.current = null;
+      }
+      elRef.current = el;
+      if (!el) return;
+      const handler = () => {
+        const distance = maxScrollTop(el) - el.scrollTop;
+        const anchored = distance <= threshold;
+        if (anchored !== anchoredRef.current) {
+          anchoredRef.current = anchored;
+          setAnchored(anchored);
+        }
+      };
+      el.addEventListener('scroll', handler, { passive: true });
+      cleanupRef.current = () => el.removeEventListener('scroll', handler);
+      // Run once to seed `isAnchored` from the current position.
+      handler();
+    },
+    [threshold],
+  );
+
+  useEffect(() => {
+    return () => {
+      if (cleanupRef.current) {
+        cleanupRef.current();
+        cleanupRef.current = null;
+      }
+    };
+  }, []);
+
+  useEffect(() => {
+    if (anchoredRef.current) scrollToBottom();
+    // Consumer-provided dependency array + the scroll callback.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, options.revalidateKeys ?? []);
+
+  return { setRef, isAnchored, scrollToBottom };
+}

package/src/state/useToolCallStream.test.ts

@@ -0,0 +1,86 @@
+/**
+ * Tests for `useToolCallStream` — pure derivation of in-flight tool-call
+ * status from a `ChatMessage`.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import type { ChatMessage } from '@steerable/agent-protocol';
+import { useToolCallStream } from './useToolCallStream';
+
+const baseMsg: ChatMessage = {
+  id: 'm1',
+  role: 'assistant',
+  content: '',
+  createdAt: new Date().toISOString(),
+};
+
+describe('useToolCallStream', () => {
+  it('returns an empty entry list when the message has no tool calls', () => {
+    const { result } = renderHook(() => useToolCallStream({ message: baseMsg }));
+    expect(result.current.entries).toEqual([]);
+    expect(result.current.pendingCount).toBe(0);
+  });
+
+  it('classifies pending calls (no result yet) as pending', () => {
+    const msg: ChatMessage = {
+      ...baseMsg,
+      toolCalls: [{ id: 'c1', name: 'get_weather', arguments: {} }],
+    };
+    const { result } = renderHook(() => useToolCallStream({ message: msg }));
+    expect(result.current.entries[0].status).toBe('pending');
+    expect(result.current.pendingCount).toBe(1);
+  });
+
+  it('infers mode from the tool name', () => {
+    const msg: ChatMessage = {
+      ...baseMsg,
+      toolCalls: [
+        { id: 'r', name: 'get_user', arguments: {} },
+        { id: 'd', name: 'delete_user', arguments: {} },
+        { id: 'l', name: 'local_exec', arguments: {} },
+        { id: 'w', name: 'create_thing', arguments: {} },
+      ],
+    };
+    const { result } = renderHook(() => useToolCallStream({ message: msg }));
+    expect(result.current.entries.map((e) => e.mode)).toEqual([
+      'read',
+      'destructive',
+      'local',
+      'safe_write',
+    ]);
+    expect(result.current.entries[1].isDestructive).toBe(true);
+    expect(result.current.entries[2].requiresApproval).toBe(true);
+  });
+
+  it('overrides mode via modeByName', () => {
+    const msg: ChatMessage = {
+      ...baseMsg,
+      toolCalls: [{ id: 'c1', name: 'mystery', arguments: {} }],
+    };
+    const { result } = renderHook(() =>
+      useToolCallStream({ message: msg, modeByName: { mystery: 'destructive' } }),
+    );
+    expect(result.current.entries[0].mode).toBe('destructive');
+  });
+
+  it('pairs results via resultByCallId, falls back to message.toolResult', () => {
+    const msg: ChatMessage = {
+      ...baseMsg,
+      toolCalls: [
+        { id: 'a', name: 'get_a', arguments: {} },
+        { id: 'b', name: 'get_b', arguments: {} },
+      ],
+      toolResult: { success: true, data: { fallback: true } },
+    };
+    const { result } = renderHook(() =>
+      useToolCallStream({
+        message: msg,
+        resultByCallId: { a: { success: false, data: { err: 'x' } } },
+      }),
+    );
+    expect(result.current.entries[0].status).toBe('error');
+    expect(result.current.entries[1].status).toBe('done');
+    expect(result.current.errorCount).toBe(1);
+  });
+});