@steerable/agent-ui 0.2.3 → 0.2.4

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);
+  });
+});

package/src/state/useToolCallStream.ts

@@ -0,0 +1,110 @@
+/**
+ * `useToolCallStream` — turn the assistant message's `toolCalls` / `toolResult`
+ * (as maintained by `useChatStream`) into a derived `{ id -> {call, result,
+ * status, mode} }` map, so renderers can show per-call cards without
+ * threading status through the tree manually.
+ *
+ * Aggregates `useToolCallStatus` across all tool calls on a single message.
+ * Pure derivation, no I/O.
+ */
+
+import { useMemo } from 'react';
+import type { ChatMessage, ToolCall, ToolResult } from '@steerable/agent-protocol';
+import {
+  useToolCallStatus,
+  type ToolCallMode,
+  type ToolCallStatus,
+} from '../hooks/useToolCallStatus.js';
+
+export interface ToolCallEntry {
+  call: ToolCall;
+  result?: ToolResult;
+  status: ToolCallStatus;
+  mode: ToolCallMode;
+  isDestructive: boolean;
+  requiresApproval: boolean;
+}
+
+export interface UseToolCallStreamOptions {
+  message: ChatMessage | null | undefined;
+  /**
+   * Optional per-call result lookup — when the runtime emits `tool_result`
+   * with a `callId`, we can pair it to the originating call rather than
+   * relying on `message.toolResult` (which always holds the last result).
+   */
+  resultByCallId?: Record<string, ToolResult>;
+  /** Optional mode override per tool name. */
+  modeByName?: Record<string, ToolCallMode>;
+}
+
+export interface UseToolCallStreamReturn {
+  entries: ToolCallEntry[];
+  pendingCount: number;
+  errorCount: number;
+}
+
+export function useToolCallStream(
+  options: UseToolCallStreamOptions,
+): UseToolCallStreamReturn {
+  const message = options.message ?? null;
+  return useMemo(() => {
+    if (!message || !Array.isArray(message.toolCalls)) {
+      return { entries: [], pendingCount: 0, errorCount: 0 };
+    }
+    const entries: ToolCallEntry[] = message.toolCalls.map((call) => {
+      const lookup = options.resultByCallId?.[call.id];
+      const fallback =
+        message.toolResult && (message.toolResult as { callId?: string }).callId === call.id
+          ? message.toolResult
+          : undefined;
+      const result = lookup ?? fallback ?? message.toolResult;
+      const status = deriveStatus(result);
+      const mode = options.modeByName?.[call.name] ?? inferMode(call.name);
+      return {
+        call,
+        result,
+        status,
+        mode,
+        isDestructive: mode === 'destructive',
+        requiresApproval: mode === 'local',
+      };
+    });
+    return {
+      entries,
+      pendingCount: entries.filter((e) => e.status === 'pending').length,
+      errorCount: entries.filter((e) => e.status === 'error').length,
+    };
+  }, [message, options.resultByCallId, options.modeByName]);
+}
+
+// `useToolCallStatus` is per-call; this hook is the bulk variant. We keep the
+// inference rules in sync by re-using the same heuristics here.
+
+const READ_PATTERNS = [/^get[_-]/, /^list[_-]/, /^read[_-]/, /^search[_-]/];
+const DESTRUCTIVE_PATTERNS = [
+  /^delete[_-]/,
+  /^remove[_-]/,
+  /^archive[_-]/,
+  /^purge[_-]/,
+  /^drop[_-]/,
+];
+const SAFE_WRITE_PATTERNS = [/^create[_-]/, /^update[_-]/, /^add[_-]/, /^set[_-]/];
+const LOCAL_PATTERNS = [/^local[_-]/, /^shell[_-]/, /^exec[_-]/];
+
+function inferMode(name: string): ToolCallMode {
+  const lower = name.toLowerCase();
+  if (READ_PATTERNS.some((re) => re.test(lower))) return 'read';
+  if (LOCAL_PATTERNS.some((re) => re.test(lower))) return 'local';
+  if (DESTRUCTIVE_PATTERNS.some((re) => re.test(lower))) return 'destructive';
+  if (SAFE_WRITE_PATTERNS.some((re) => re.test(lower))) return 'safe_write';
+  return 'unknown';
+}
+
+function deriveStatus(result: ToolResult | undefined): ToolCallStatus {
+  if (!result) return 'pending';
+  if (result.success === false) return 'error';
+  return 'done';
+}
+
+// Re-export the per-call hook for convenience.
+export { useToolCallStatus } from '../hooks/useToolCallStatus.js';