@steerable/agent-ui 0.2.3 → 0.2.5

package/src/state/parseSSE.ts

@@ -0,0 +1,123 @@
+/**
+ * `parseSSE` — wire-level Server-Sent-Events parser.
+ *
+ * Feed it raw text chunks from any source (fetch ReadableStream chunks,
+ * Electron IPC `webContents.send` payloads, mocked fixtures, …). It buffers,
+ * splits on the `\r?\n\r?\n` frame terminator, and emits one
+ * `{ event?, data?, id?, retry? }` per complete frame. JSON parsing of `data`
+ * is intentionally out of scope; downstream layers like {@link bridgeLegacySSE}
+ * handle that.
+ *
+ * Replaces deeppath's `SSEParser` and deeppath-agent's `LocalBackendSseParser`
+ * with a single dependency-free implementation that compiles to both Node and
+ * the browser. Heartbeat-timeout watchdogs (deeppath had a 30 s gate) live on
+ * the transport, not here — this class is a pure parser.
+ */
+
+export interface SSEFrame {
+  /** The `event: …` field; undefined for default `message` events. */
+  event?: string;
+  /** Concatenated `data: …` lines (newline-joined per the SSE spec). */
+  data?: string;
+  /** The `id: …` field. */
+  id?: string;
+  /** The `retry: …` field, as milliseconds. */
+  retry?: number;
+}
+
+export interface SSEParserOptions {
+  onFrame: (frame: SSEFrame) => void;
+  onError?: (err: Error) => void;
+  /** Called when the stream emits the canonical `data: [DONE]` terminator. */
+  onComplete?: () => void;
+}
+
+export class SSEParser {
+  private buffer = '';
+  private completed = false;
+
+  constructor(private readonly options: SSEParserOptions) {}
+
+  /** Feed one chunk. Safe to call with partial UTF-8 strings (we don't decode). */
+  feed(chunk: string): void {
+    if (this.completed) return;
+    this.buffer += chunk;
+    const parts = this.buffer.split(/\r?\n\r?\n/);
+    this.buffer = parts.pop() ?? '';
+    for (const frame of parts) {
+      if (frame.length > 0) this.processFrame(frame);
+    }
+  }
+
+  /** Call when the source signals end-of-stream. Flushes any trailing frame. */
+  end(): void {
+    if (this.completed) return;
+    if (this.buffer.trim().length > 0) this.processFrame(this.buffer);
+    this.buffer = '';
+  }
+
+  /** Drop all state and stop emitting. */
+  cleanup(): void {
+    this.buffer = '';
+    this.completed = true;
+  }
+
+  private processFrame(raw: string): void {
+    const frame: SSEFrame = {};
+    const dataLines: string[] = [];
+    for (const line of raw.split(/\r?\n/)) {
+      if (line.length === 0) continue;
+      // Comments per the SSE spec — leading `:` lines.
+      if (line.startsWith(':')) continue;
+      const colon = line.indexOf(':');
+      const field = colon === -1 ? line : line.substring(0, colon);
+      let value = colon === -1 ? '' : line.substring(colon + 1);
+      if (value.startsWith(' ')) value = value.substring(1);
+      switch (field) {
+        case 'event':
+          frame.event = value;
+          break;
+        case 'data':
+          dataLines.push(value);
+          break;
+        case 'id':
+          frame.id = value;
+          break;
+        case 'retry': {
+          const ms = Number.parseInt(value, 10);
+          if (Number.isFinite(ms)) frame.retry = ms;
+          break;
+        }
+        default:
+          break;
+      }
+    }
+    if (dataLines.length === 0 && frame.event === undefined && frame.id === undefined) {
+      return;
+    }
+    if (dataLines.length > 0) frame.data = dataLines.join('\n');
+
+    if (frame.data === '[DONE]' || frame.data === '"[DONE]"') {
+      this.completed = true;
+      this.options.onComplete?.();
+      return;
+    }
+    try {
+      this.options.onFrame(frame);
+    } catch (err) {
+      this.options.onError?.(err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+}
+
+/**
+ * Tolerant JSON parser for SSE `data:` payloads — returns the raw string when
+ * the body isn't JSON, which deeppath relies on for bare-text content deltas.
+ */
+export function parseSSEData(data: string): unknown {
+  try {
+    return JSON.parse(data);
+  } catch {
+    return data;
+  }
+}

package/src/state/useChatComposer.test.ts

@@ -0,0 +1,145 @@
+/**
+ * Tests for `useChatComposer`. The hook is intentionally tiny so the suite is
+ * focused — keyboard semantics, the streaming guard, and the trim/clear
+ * contract are what consumers actually pin behaviour against.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { act, renderHook } from '@testing-library/react';
+import { useChatComposer } from './useChatComposer';
+
+function makeKey(key: string, extras: Partial<KeyboardEvent> = {}) {
+  // Construct a minimal React keyboard event matching what the hook uses.
+  return {
+    key,
+    shiftKey: extras.shiftKey ?? false,
+    metaKey: extras.metaKey ?? false,
+    ctrlKey: extras.ctrlKey ?? false,
+    preventDefault: vi.fn(),
+  } as unknown as React.KeyboardEvent<HTMLElement>;
+}
+
+describe('useChatComposer', () => {
+  it('submits the trimmed value and clears the draft', async () => {
+    const onSend = vi.fn().mockResolvedValue(undefined);
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend, initialValue: '  hello  ' }),
+    );
+
+    await act(async () => {
+      await result.current.submit();
+    });
+
+    expect(onSend).toHaveBeenCalledWith('hello');
+    expect(result.current.value).toBe('');
+  });
+
+  it('does not submit empty / whitespace-only drafts', async () => {
+    const onSend = vi.fn();
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend, initialValue: '   ' }),
+    );
+
+    await act(async () => {
+      await result.current.submit();
+    });
+
+    expect(onSend).not.toHaveBeenCalled();
+  });
+
+  it('Enter submits, Shift+Enter inserts a newline (default)', async () => {
+    const onSend = vi.fn();
+    const { result } = renderHook(() => useChatComposer({ onSend, initialValue: 'hi' }));
+
+    const submit = makeKey('Enter');
+    await act(async () => {
+      result.current.handleKeyDown(submit);
+    });
+    expect(submit.preventDefault).toHaveBeenCalled();
+    expect(onSend).toHaveBeenCalledWith('hi');
+
+    const shift = makeKey('Enter', { shiftKey: true });
+    await act(async () => {
+      result.current.handleKeyDown(shift);
+    });
+    expect(shift.preventDefault).not.toHaveBeenCalled();
+  });
+
+  it('isStreaming flips Enter into a cancel', async () => {
+    const onSend = vi.fn();
+    const onCancel = vi.fn();
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend, onCancel, isStreaming: true, initialValue: 'x' }),
+    );
+
+    const ev = makeKey('Enter');
+    await act(async () => {
+      result.current.handleKeyDown(ev);
+    });
+    expect(onCancel).toHaveBeenCalledOnce();
+    expect(onSend).not.toHaveBeenCalled();
+  });
+
+  it('Escape cancels while streaming', async () => {
+    const onCancel = vi.fn();
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend: vi.fn(), onCancel, isStreaming: true }),
+    );
+    const ev = makeKey('Escape');
+    await act(async () => {
+      result.current.handleKeyDown(ev);
+    });
+    expect(onCancel).toHaveBeenCalledOnce();
+  });
+
+  it('enterToSubmit=false requires Cmd/Ctrl+Enter', async () => {
+    const onSend = vi.fn();
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend, enterToSubmit: false, initialValue: 'hi' }),
+    );
+
+    const plain = makeKey('Enter');
+    await act(async () => {
+      result.current.handleKeyDown(plain);
+    });
+    expect(plain.preventDefault).not.toHaveBeenCalled();
+    expect(onSend).not.toHaveBeenCalled();
+
+    const cmd = makeKey('Enter', { metaKey: true });
+    await act(async () => {
+      result.current.handleKeyDown(cmd);
+    });
+    expect(cmd.preventDefault).toHaveBeenCalled();
+    expect(onSend).toHaveBeenCalledWith('hi');
+  });
+
+  it('disabled state suppresses both submit and key handling', async () => {
+    const onSend = vi.fn();
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend, disabled: true, initialValue: 'hi' }),
+    );
+
+    await act(async () => {
+      await result.current.submit();
+    });
+    const ev = makeKey('Enter');
+    await act(async () => {
+      result.current.handleKeyDown(ev);
+    });
+    expect(onSend).not.toHaveBeenCalled();
+    expect(ev.preventDefault).not.toHaveBeenCalled();
+    expect(result.current.canSubmit).toBe(false);
+  });
+
+  it('clear() empties the draft without sending', async () => {
+    const onSend = vi.fn();
+    const { result } = renderHook(() =>
+      useChatComposer({ onSend, initialValue: 'hi' }),
+    );
+    await act(async () => {
+      result.current.clear();
+    });
+    expect(result.current.value).toBe('');
+    expect(onSend).not.toHaveBeenCalled();
+  });
+});

package/src/state/useChatComposer.ts

@@ -0,0 +1,117 @@
+/**
+ * `useChatComposer` — input draft + send/cancel + keyboard glue.
+ *
+ * Lifted from deeppath-agent's `LocalChatPanel.tsx` (inline `inputValue` /
+ * `handleSubmit`) and deeppath's `ChatInput` (cancel handling). The hook is
+ * intentionally UI-free: it owns the draft string and the keyboard
+ * dispatcher; the visible textarea and send button live in the consuming
+ * component.
+ *
+ * Typical wiring:
+ *
+ *   const composer = useChatComposer({ onSend: send, onCancel: cancel });
+ *
+ *   <textarea
+ *     value={composer.value}
+ *     onChange={(e) => composer.setValue(e.target.value)}
+ *     onKeyDown={composer.handleKeyDown}
+ *   />
+ *   <button onClick={composer.submit}>Send</button>
+ */
+
+import { useCallback, useRef, useState } from 'react';
+
+export interface UseChatComposerOptions {
+  initialValue?: string;
+  /** Called with the trimmed value when the user submits a non-empty draft. */
+  onSend: (value: string) => void | Promise<void>;
+  /** Called when the user wants to cancel the in-flight stream. Optional. */
+  onCancel?: () => void;
+  /**
+   * If true (default), Enter submits and Shift+Enter inserts a newline. Set
+   * to false for "Enter inserts newline, Cmd/Ctrl+Enter submits" semantics.
+   */
+  enterToSubmit?: boolean;
+  /** Whether the composer is currently disabled (no submit / no key handling). */
+  disabled?: boolean;
+  /**
+   * Whether the parent reports an in-flight stream. When true, `submit()` is
+   * a no-op and Enter triggers `onCancel` instead. Mirrors the cloud product.
+   */
+  isStreaming?: boolean;
+}
+
+export interface UseChatComposerReturn {
+  value: string;
+  setValue: (value: string) => void;
+  submit: () => Promise<void> | void;
+  cancel: () => void;
+  clear: () => void;
+  handleKeyDown: (e: React.KeyboardEvent<HTMLElement>) => void;
+  /** True if `value.trim()` is non-empty and we're not disabled. */
+  canSubmit: boolean;
+}
+
+export function useChatComposer(options: UseChatComposerOptions): UseChatComposerReturn {
+  const [value, setValue] = useState(options.initialValue ?? '');
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const submit = useCallback(async () => {
+    const opts = optionsRef.current;
+    if (opts.disabled || opts.isStreaming) return;
+    const trimmed = value.trim();
+    if (!trimmed) return;
+    // Clear synchronously so the user can keep typing while the request flies.
+    setValue('');
+    await opts.onSend(trimmed);
+  }, [value]);
+
+  const cancel = useCallback(() => {
+    optionsRef.current.onCancel?.();
+  }, []);
+
+  const clear = useCallback(() => setValue(''), []);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLElement>) => {
+      const opts = optionsRef.current;
+      if (opts.disabled) return;
+      const enterSubmits = opts.enterToSubmit ?? true;
+      if (e.key === 'Enter') {
+        if (enterSubmits && !e.shiftKey && !e.metaKey && !e.ctrlKey) {
+          e.preventDefault();
+          if (opts.isStreaming) {
+            cancel();
+          } else {
+            void submit();
+          }
+          return;
+        }
+        if (!enterSubmits && (e.metaKey || e.ctrlKey)) {
+          e.preventDefault();
+          if (opts.isStreaming) cancel();
+          else void submit();
+          return;
+        }
+      }
+      if (e.key === 'Escape' && opts.isStreaming) {
+        e.preventDefault();
+        cancel();
+      }
+    },
+    [submit, cancel],
+  );
+
+  const canSubmit = value.trim().length > 0 && !(options.disabled || options.isStreaming);
+
+  return {
+    value,
+    setValue,
+    submit,
+    cancel,
+    clear,
+    handleKeyDown,
+    canSubmit,
+  };
+}

package/src/state/useChatList.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Tests for `useChatList`. The generics are deliberately unconstrained, so
+ * here we instantiate with simple `{id,title}`-shaped chats and agents to
+ * keep the suite readable.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import {
+  useChatList,
+  type ChatListTransport,
+} from './useChatList';
+
+interface ChatDouble {
+  id: string;
+  title: string;
+}
+
+interface AgentDouble {
+  id: string;
+}
+
+function makeTransport(): {
+  transport: ChatListTransport<ChatDouble, AgentDouble>;
+  listChats: ReturnType<typeof vi.fn>;
+  listAgents: ReturnType<typeof vi.fn>;
+  createChat: ReturnType<typeof vi.fn>;
+  deleteChat: ReturnType<typeof vi.fn>;
+} {
+  const listChats = vi.fn(async ({ page }: { page: number }) => ({
+    chats:
+      page === 1
+        ? [
+            { id: 'c1', title: 'First' },
+            { id: 'c2', title: 'Second' },
+          ]
+        : [{ id: 'c3', title: 'Third' }],
+    hasMore: page === 1,
+  }));
+  const listAgents = vi.fn(async () => [{ id: 'a1' }, { id: 'a2' }]);
+  const createChat = vi.fn(async () => ({ id: 'c-new', title: 'New' }));
+  const deleteChat = vi.fn(async () => true);
+  return {
+    transport: {
+      listChats,
+      listAgents,
+      createChat,
+      deleteChat,
+      getChatId: (c) => c.id,
+      setChatTitle: (c, title) => ({ ...c, title }),
+      getAgentId: (a) => a.id,
+    },
+    listChats,
+    listAgents,
+    createChat,
+    deleteChat,
+  };
+}
+
+describe('useChatList', () => {
+  it('loads chats + agents on mount', async () => {
+    const { transport } = makeTransport();
+    const { result } = renderHook(() => useChatList({ transport, pageSize: 50 }));
+
+    await waitFor(() => {
+      expect(result.current.chats.length).toBe(2);
+      expect(result.current.agents.length).toBe(2);
+    });
+    expect(result.current.hasMoreChats).toBe(true);
+  });
+
+  it('loadMoreChats appends page 2 results', async () => {
+    const { transport } = makeTransport();
+    const { result } = renderHook(() => useChatList({ transport, pageSize: 50 }));
+
+    await waitFor(() => expect(result.current.chats.length).toBe(2));
+
+    await act(async () => {
+      await result.current.loadMoreChats();
+    });
+
+    expect(result.current.chats.map((c) => c.id)).toEqual(['c1', 'c2', 'c3']);
+    expect(result.current.hasMoreChats).toBe(false);
+  });
+
+  it('patchChatTitle updates without re-fetching', async () => {
+    const { transport, listChats } = makeTransport();
+    const { result } = renderHook(() => useChatList({ transport, pageSize: 50 }));
+    await waitFor(() => expect(result.current.chats.length).toBe(2));
+
+    act(() => {
+      result.current.patchChatTitle('c1', 'Renamed');
+    });
+
+    expect(result.current.chats[0].title).toBe('Renamed');
+    expect(listChats).toHaveBeenCalledTimes(1);
+  });
+
+  it('createChat triggers refresh + returns id', async () => {
+    const { transport } = makeTransport();
+    const { result } = renderHook(() => useChatList({ transport, pageSize: 50 }));
+    await waitFor(() => expect(result.current.chats.length).toBe(2));
+
+    let id: string | null = null;
+    await act(async () => {
+      id = await result.current.createChat();
+    });
+    expect(id).toBe('c-new');
+  });
+
+  it('deleteChat optimistically removes the chat', async () => {
+    const { transport } = makeTransport();
+    const { result } = renderHook(() => useChatList({ transport, pageSize: 50 }));
+    await waitFor(() => expect(result.current.chats.length).toBe(2));
+
+    await act(async () => {
+      await result.current.deleteChat('c1');
+    });
+
+    expect(result.current.chats.map((c) => c.id)).toEqual(['c2']);
+  });
+
+  it('selectedAgentId is settable and persists across renders', async () => {
+    const { transport } = makeTransport();
+    const { result, rerender } = renderHook(() =>
+      useChatList({ transport, pageSize: 50 }),
+    );
+    await waitFor(() => expect(result.current.agents.length).toBe(2));
+
+    act(() => result.current.setSelectedAgentId('a2'));
+    expect(result.current.selectedAgentId).toBe('a2');
+    rerender();
+    expect(result.current.selectedAgentId).toBe('a2');
+  });
+});