@steerable/agent-ui 0.2.0

package/src/hooks/useChatStream.test.ts

@@ -0,0 +1,233 @@
+/**
+ * Tests for `useChatStream`.
+ *
+ * The hook is an SSE-event reducer that owns ChatMessage[]; we verify the
+ * canonical event family from `@steerable/agent-protocol` produces the right
+ * message buffer mutations, and that lifecycle (cancel, error, unmount) is
+ * handled without leaking pending streams.
+ */
+
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { SSEEvent } from '@steerable/agent-protocol';
+import {
+  useChatStream,
+  type ChatStreamTransport,
+} from './useChatStream';
+
+function makeTransport(
+  script: SSEEvent[][],
+): { transport: ChatStreamTransport; cancel: ReturnType<typeof vi.fn> } {
+  const cancel = vi.fn();
+  let invocation = 0;
+  const transport: ChatStreamTransport = {
+    stream: async (_input, onEvent) => {
+      const events = script[invocation++] ?? [];
+      // Deliver synchronously inside `await Promise.resolve()` to mimic real
+      // SSE chunks landing on the microtask queue.
+      for (const ev of events) {
+        await Promise.resolve();
+        onEvent(ev);
+      }
+      return cancel;
+    },
+  };
+  return { transport, cancel };
+}
+
+describe('useChatStream', () => {
+  it('appends user + assistant placeholder, then accumulates content deltas', async () => {
+    const { transport } = makeTransport([
+      [
+        { type: 'content', content: 'Hello, ' },
+        { type: 'content', content: 'world!' },
+        { type: 'done' },
+      ],
+    ]);
+
+    const { result } = renderHook(() => useChatStream({ transport }));
+
+    await act(async () => {
+      await result.current.sendUserMessage({ content: 'hi' });
+    });
+
+    await waitFor(() => {
+      const last = result.current.messages.at(-1);
+      expect(last?.role).toBe('assistant');
+      expect(last?.content).toBe('Hello, world!');
+    });
+    expect(result.current.messages[0].role).toBe('user');
+    expect(result.current.messages[0].content).toBe('hi');
+    expect(result.current.isStreaming).toBe(false);
+  });
+
+  it('captures tool_call events as toolCalls on the assistant message', async () => {
+    const { transport } = makeTransport([
+      [
+        { type: 'content', content: 'calling…' },
+        {
+          type: 'tool_call',
+          payload: { id: 'c1', name: 'get_weather', arguments: { city: 'SF' } },
+        },
+        {
+          type: 'tool_result',
+          payload: { success: true, data: { temp: 70 } },
+        },
+        { type: 'done' },
+      ],
+    ]);
+
+    const { result } = renderHook(() => useChatStream({ transport }));
+
+    await act(async () => {
+      await result.current.sendUserMessage({ content: 'weather?' });
+    });
+
+    await waitFor(() => {
+      const last = result.current.messages.at(-1);
+      expect(last?.toolCalls).toEqual([
+        { id: 'c1', name: 'get_weather', arguments: { city: 'SF' } },
+      ]);
+      expect(last?.toolResult).toEqual({ success: true, data: { temp: 70 } });
+    });
+  });
+
+  it('routes tool_result via toolResultToMessage when provided', async () => {
+    const { transport } = makeTransport([
+      [
+        {
+          type: 'tool_result',
+          payload: { success: true, data: { ok: true } },
+        },
+        { type: 'done' },
+      ],
+    ]);
+
+    const toolResultToMessage = vi.fn(() => ({
+      id: 't1',
+      role: 'tool' as const,
+      content: 'mapped',
+      createdAt: new Date().toISOString(),
+    }));
+
+    const { result } = renderHook(() =>
+      useChatStream({ transport, toolResultToMessage }),
+    );
+
+    await act(async () => {
+      await result.current.sendUserMessage({ content: 'go' });
+    });
+
+    await waitFor(() => {
+      expect(toolResultToMessage).toHaveBeenCalledTimes(1);
+      const tool = result.current.messages.find((m) => m.role === 'tool');
+      expect(tool?.content).toBe('mapped');
+    });
+  });
+
+  it('forwards unrecognised events to onUnknownEvent', async () => {
+    const { transport } = makeTransport([
+      [
+        { type: 'loader-hint', hint: 'thinking…' },
+        { type: 'agent', payload: { agentId: 'a1' } },
+        { type: 'done' },
+      ],
+    ]);
+    const onUnknownEvent = vi.fn();
+    const { result } = renderHook(() => useChatStream({ transport, onUnknownEvent }));
+
+    await act(async () => {
+      await result.current.sendUserMessage({ content: 'go' });
+    });
+
+    await waitFor(() => {
+      expect(onUnknownEvent).toHaveBeenCalledTimes(2);
+    });
+    expect(onUnknownEvent.mock.calls[0]?.[0].type).toBe('loader-hint');
+    expect(onUnknownEvent.mock.calls[1]?.[0].type).toBe('agent');
+  });
+
+  it('emits an error overlay onto the assistant message when the stream throws', async () => {
+    const transport: ChatStreamTransport = {
+      stream: async () => {
+        throw new Error('boom');
+      },
+    };
+    const { result } = renderHook(() => useChatStream({ transport }));
+
+    await act(async () => {
+      await result.current.sendUserMessage({ content: 'hi' });
+    });
+
+    await waitFor(() => {
+      const last = result.current.messages.at(-1);
+      expect(last?.content).toContain('[stream error] boom');
+    });
+    expect(result.current.isStreaming).toBe(false);
+  });
+
+  it('renders error events from the protocol as inline overlays', async () => {
+    const { transport } = makeTransport([
+      [
+        { type: 'content', content: 'partial' },
+        { type: 'error', message: 'upstream failed' },
+        { type: 'done' },
+      ],
+    ]);
+    const { result } = renderHook(() => useChatStream({ transport }));
+
+    await act(async () => {
+      await result.current.sendUserMessage({ content: 'hi' });
+    });
+
+    await waitFor(() => {
+      const last = result.current.messages.at(-1);
+      expect(last?.content).toContain('[stream error] upstream failed');
+    });
+  });
+
+  it('budget_exhausted overrides the assistant content with the error message', async () => {
+    const { transport } = makeTransport([
+      [
+        { type: 'budget_exhausted', message: 'token limit hit' },
+        { type: 'done' },
+      ],
+    ]);
+    const { result } = renderHook(() => useChatStream({ transport }));
+
+    await act(async () => {
+      await result.current.sendUserMessage({ content: 'hi' });
+    });
+
+    await waitFor(() => {
+      const last = result.current.messages.at(-1);
+      expect(last?.content).toBe('token limit hit');
+    });
+  });
+
+  it('cancel() invokes the transport-supplied cancel handle', async () => {
+    const cancel = vi.fn();
+    const transport: ChatStreamTransport = {
+      stream: async () =>
+        // Return cancel synchronously but never resolve the rest of the stream.
+        new Promise((_resolve) => {
+          setImmediate(() => {
+            // Returning the cancel via the resolved value pattern is the
+            // canonical use; here we use a separate channel.
+          });
+          // For test simplicity, return cancel after a microtask flush.
+        }).then(() => cancel),
+    };
+
+    const { result, unmount } = renderHook(() =>
+      useChatStream({ transport }),
+    );
+    void act(() => {
+      void result.current.sendUserMessage({ content: 'hi' });
+    });
+
+    // Unmounting should not throw even if the transport is still hanging.
+    unmount();
+    expect(true).toBe(true);
+  });
+});

package/src/hooks/useChatStream.ts

@@ -0,0 +1,341 @@
+/**
+ * `useChatStream` — own the in-flight chat lifecycle.
+ *
+ * Caller plugs in a transport (fetch+SSE, IPC bridge, sidecar, …) that yields
+ * `SSEEvent` instances; the hook turns those into the local `ChatMessage[]`
+ * that `<MessageList>` and `<ChatPanel>` render. The hook is intentionally
+ * unaware of HTTP, of which provider serves the events, and of any specific
+ * sequencing rules — those live in the framework spec and the caller's
+ * transport.
+ */
+
+import { useCallback, useEffect, useMemo, useReducer, useRef } from 'react';
+import type {
+  ChatMessage,
+  SSEEvent,
+  ToolCall,
+  ToolResult,
+} from '@steerable/agent-protocol';
+
+export interface ChatStreamSendInput {
+  /** The user's free-text message. */
+  content: string;
+  /** Optional structured metadata (mention list, tools requested, etc.). */
+  metadata?: Record<string, unknown>;
+}
+
+export interface ChatStreamTransport {
+  /**
+   * Called when the user submits a message. The transport is expected to:
+   *   1. POST/IPC the message to the backend,
+   *   2. consume the SSE stream and call `onEvent` for each parsed event,
+   *   3. resolve when the stream terminates (or reject on error).
+   *
+   * Returning a function from the promise is a `cancel` handle the hook will
+   * call on unmount or when the user clicks "stop".
+   */
+  stream: (
+    input: ChatStreamSendInput,
+    onEvent: (event: SSEEvent) => void,
+  ) => Promise<void | (() => void)>;
+}
+
+export interface UseChatStreamOptions {
+  /** Required transport handle; see `ChatStreamTransport`. */
+  transport: ChatStreamTransport;
+  /** Initial message history (persisted from previous turns). */
+  initialMessages?: ChatMessage[];
+  /**
+   * Map a tool-result event to a standalone `tool` ChatMessage. Default
+   * returns null, which keeps tool results inline on the assistant message
+   * that owns the corresponding call.
+   */
+  toolResultToMessage?: (result: ToolResult) => ChatMessage | null;
+  /**
+   * Called for every event that doesn't have a built-in handler — useful for
+   * `loader-hint`, `agent`, `orchestration`, automation, search-source, etc.
+   * Receivers can stash these into their own state.
+   */
+  onUnknownEvent?: (event: SSEEvent) => void;
+}
+
+export interface UseChatStreamReturn {
+  messages: ChatMessage[];
+  isStreaming: boolean;
+  sendUserMessage: (input: ChatStreamSendInput) => Promise<void>;
+  cancel: () => void;
+  /** Replace the message buffer (e.g. when switching chat). */
+  setMessages: (messages: ChatMessage[]) => void;
+  /** Append a single message without going through the transport. */
+  appendMessage: (message: ChatMessage) => void;
+}
+
+type Action =
+  | { type: 'reset'; messages: ChatMessage[] }
+  | { type: 'append'; message: ChatMessage }
+  | { type: 'patch-last-assistant'; patch: Partial<ChatMessage> }
+  | { type: 'append-content'; delta: string }
+  | { type: 'append-tool-call'; call: ToolCall }
+  | { type: 'attach-tool-result'; result: ToolResult }
+  | { type: 'finalize-assistant' };
+
+interface State {
+  messages: ChatMessage[];
+}
+
+function reducer(state: State, action: Action): State {
+  switch (action.type) {
+    case 'reset':
+      return { messages: action.messages };
+    case 'append':
+      return { messages: [...state.messages, action.message] };
+    case 'patch-last-assistant': {
+      const idx = findLastAssistantIndex(state.messages);
+      if (idx === -1) return state;
+      const patched: ChatMessage = {
+        ...state.messages[idx],
+        ...action.patch,
+      } as ChatMessage;
+      const next = state.messages.slice();
+      next[idx] = patched;
+      return { messages: next };
+    }
+    case 'append-content': {
+      const idx = findLastAssistantIndex(state.messages);
+      if (idx === -1) return state;
+      const target = state.messages[idx];
+      const patched: ChatMessage = {
+        ...target,
+        content: (target.content ?? '') + action.delta,
+      } as ChatMessage;
+      const next = state.messages.slice();
+      next[idx] = patched;
+      return { messages: next };
+    }
+    case 'append-tool-call': {
+      const idx = findLastAssistantIndex(state.messages);
+      if (idx === -1) return state;
+      const target = state.messages[idx];
+      const calls = Array.isArray(target.toolCalls) ? [...target.toolCalls] : [];
+      calls.push(action.call);
+      const patched: ChatMessage = { ...target, toolCalls: calls } as ChatMessage;
+      const next = state.messages.slice();
+      next[idx] = patched;
+      return { messages: next };
+    }
+    case 'attach-tool-result': {
+      // The protocol allows `ChatMessage.toolResult`, but most renderers want
+      // to see results inline on the assistant message that owns the call.
+      const idx = findLastAssistantIndex(state.messages);
+      if (idx === -1) return state;
+      const target = state.messages[idx];
+      const patched: ChatMessage = {
+        ...target,
+        toolResult: action.result,
+      } as ChatMessage;
+      const next = state.messages.slice();
+      next[idx] = patched;
+      return { messages: next };
+    }
+    case 'finalize-assistant':
+      return state;
+    default:
+      return state;
+  }
+}
+
+function findLastAssistantIndex(messages: ChatMessage[]): number {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (messages[i].role === 'assistant') return i;
+  }
+  return -1;
+}
+
+function newAssistantPlaceholder(): ChatMessage {
+  return {
+    id: `placeholder_${Date.now()}_${Math.floor(Math.random() * 1e6)}`,
+    role: 'assistant',
+    content: '',
+    createdAt: new Date().toISOString(),
+  };
+}
+
+function newUserMessage(content: string): ChatMessage {
+  return {
+    id: `user_${Date.now()}_${Math.floor(Math.random() * 1e6)}`,
+    role: 'user',
+    content,
+    createdAt: new Date().toISOString(),
+  };
+}
+
+function pickContentDelta(event: SSEEvent): string | null {
+  if (typeof event.content === 'string' && event.content.length > 0) {
+    return event.content;
+  }
+  // Some transports stash the delta in `payload.delta` or `payload.content`.
+  const payload = (event.payload ?? {}) as Record<string, unknown>;
+  if (typeof payload.delta === 'string') return payload.delta;
+  if (typeof payload.content === 'string') return payload.content;
+  return null;
+}
+
+function pickToolCall(event: SSEEvent): ToolCall | null {
+  const payload = event.payload as unknown;
+  if (
+    payload &&
+    typeof payload === 'object' &&
+    'id' in payload &&
+    'name' in payload &&
+    'arguments' in payload
+  ) {
+    return payload as ToolCall;
+  }
+  return null;
+}
+
+function pickToolResult(event: SSEEvent): ToolResult | null {
+  const payload = event.payload as unknown;
+  if (payload && typeof payload === 'object' && 'success' in payload) {
+    return payload as ToolResult;
+  }
+  return null;
+}
+
+export function useChatStream(
+  options: UseChatStreamOptions,
+): UseChatStreamReturn {
+  const [state, dispatch] = useReducer(reducer, {
+    messages: options.initialMessages ?? [],
+  });
+  const isStreamingRef = useRef(false);
+  const cancelRef = useRef<(() => void) | null>(null);
+  const [, forceRerender] = useReducer((x: number) => x + 1, 0);
+
+  const setStreaming = useCallback((next: boolean) => {
+    isStreamingRef.current = next;
+    forceRerender();
+  }, []);
+
+  const handleEvent = useCallback(
+    (event: SSEEvent) => {
+      switch (event.type) {
+        case 'content': {
+          const delta = pickContentDelta(event);
+          if (delta) dispatch({ type: 'append-content', delta });
+          return;
+        }
+        case 'tool_call': {
+          const call = pickToolCall(event);
+          if (call) dispatch({ type: 'append-tool-call', call });
+          return;
+        }
+        case 'tool_result': {
+          const result = pickToolResult(event);
+          if (!result) return;
+          const newMsg = options.toolResultToMessage?.(result);
+          if (newMsg) {
+            dispatch({ type: 'append', message: newMsg });
+          } else {
+            dispatch({ type: 'attach-tool-result', result });
+          }
+          return;
+        }
+        case 'done':
+          dispatch({ type: 'finalize-assistant' });
+          return;
+        case 'error': {
+          const msg = event.message ?? 'stream error';
+          dispatch({
+            type: 'patch-last-assistant',
+            patch: { content: `[stream error] ${msg}` },
+          });
+          return;
+        }
+        case 'budget_exhausted': {
+          dispatch({
+            type: 'patch-last-assistant',
+            patch: {
+              content:
+                event.message ??
+                '[budget exhausted] the harness stopped this run.',
+            },
+          });
+          return;
+        }
+        case 'agent':
+        case 'orchestration':
+        case 'loader-hint':
+        case 'keepalive':
+        default:
+          options.onUnknownEvent?.(event);
+      }
+    },
+    [options],
+  );
+
+  const sendUserMessage = useCallback(
+    async (input: ChatStreamSendInput) => {
+      if (isStreamingRef.current) {
+        return;
+      }
+      dispatch({ type: 'append', message: newUserMessage(input.content) });
+      dispatch({ type: 'append', message: newAssistantPlaceholder() });
+      setStreaming(true);
+      try {
+        const cancel = await options.transport.stream(input, handleEvent);
+        cancelRef.current = typeof cancel === 'function' ? cancel : null;
+      } catch (err) {
+        dispatch({
+          type: 'patch-last-assistant',
+          patch: {
+            content:
+              '[stream error] ' +
+              (err instanceof Error ? err.message : String(err)),
+          },
+        });
+      } finally {
+        cancelRef.current = null;
+        setStreaming(false);
+      }
+    },
+    [handleEvent, options.transport, setStreaming],
+  );
+
+  const cancel = useCallback(() => {
+    if (cancelRef.current) {
+      cancelRef.current();
+      cancelRef.current = null;
+    }
+    setStreaming(false);
+  }, [setStreaming]);
+
+  const setMessages = useCallback((messages: ChatMessage[]) => {
+    dispatch({ type: 'reset', messages });
+  }, []);
+
+  const appendMessage = useCallback((message: ChatMessage) => {
+    dispatch({ type: 'append', message });
+  }, []);
+
+  useEffect(() => {
+    return () => {
+      if (cancelRef.current) {
+        cancelRef.current();
+        cancelRef.current = null;
+      }
+    };
+  }, []);
+
+  return useMemo<UseChatStreamReturn>(
+    () => ({
+      messages: state.messages,
+      isStreaming: isStreamingRef.current,
+      sendUserMessage,
+      cancel,
+      setMessages,
+      appendMessage,
+    }),
+    [state.messages, sendUserMessage, cancel, setMessages, appendMessage],
+  );
+}

package/src/hooks/useToolCallStatus.mdx

@@ -0,0 +1,102 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Hooks/useToolCallStatus" />
+
+# `useToolCallStatus`
+
+> Derives the rendering state for a single tool call — `status` (pending/running/done/error), `mode` (read/safe_write/destructive/local/…), and whether the UI must prompt for approval.
+
+`<ToolCallRenderer>` uses this hook internally. You only need to call it directly if you're building a **custom** tool-call surface (a sidebar timeline, an audit log, a compact pill inside a markdown body, etc.) and want to share the framework's classification logic.
+
+## Signature
+
+```ts
+import { useToolCallStatus, type ToolCallMode } from '@steerable/agent-ui';
+
+const { status, mode, requiresApproval, isDestructive } = useToolCallStatus({
+  call,            // ToolCall (required)
+  result,          // ToolResult (optional; absence ⇒ pending/running)
+  mode,            // ToolCallMode (optional; auto-inferred from name)
+  runningHint,     // boolean (optional; flips pending → running)
+});
+```
+
+## Mode inference
+
+When `mode` is omitted, the hook classifies the tool by **name pattern**, mirroring the framework's harness `decide_tool_mode`:
+
+| Pattern | Inferred mode |
+|---|---|
+| `get_*` `list_*` `read_*` `search_*` | `read` |
+| `local_*` `shell_*` `exec_*` | `local` |
+| `delete_*` `remove_*` `archive_*` `purge_*` `drop_*` | `destructive` |
+| `create_*` `update_*` `add_*` `set_*` | `safe_write` |
+| anything else | `unknown` |
+
+In production the runtime ships a pre-classified mode alongside the call, so most consumers should pass `mode` explicitly to avoid drift between client and server. The hook's inference exists as a sane default for prototypes and hand-written demos.
+
+## Status state machine
+
+```
+            ┌──────────────────┐
+            │     pending      │
+            │ (no result yet)  │
+            └────────┬─────────┘
+                     │  runningHint
+                     ▼
+            ┌──────────────────┐
+            │     running      │
+            │ (sidecar emits   │
+            │  tool.running)   │
+            └────────┬─────────┘
+                     │  result attached
+        ┌────────────┴────────────┐
+        ▼                         ▼
+┌──────────────┐          ┌──────────────┐
+│     done     │          │    error     │
+│ success=true │          │ success=false│
+└──────────────┘          └──────────────┘
+```
+
+`runningHint` exists because not every transport emits a separate "running" notification. If you only have `pending` → `done`/`error`, leave it `false` and let the UI flip directly.
+
+## Example — compact tool pill
+
+```tsx
+import { useToolCallStatus } from '@steerable/agent-ui';
+import type { ToolCall, ToolResult } from '@steerable/agent-protocol';
+
+function ToolPill({ call, result }: { call: ToolCall; result?: ToolResult }) {
+  const { status, mode, isDestructive } = useToolCallStatus({ call, result });
+  return (
+    <span
+      data-status={status}
+      data-mode={mode}
+      className={
+        'inline-flex items-center gap-1.5 rounded-full border px-2 py-0.5 text-xs ' +
+        (isDestructive ? 'border-agent-destructive/40 text-agent-destructive' : 'border-agent-border')
+      }
+    >
+      <span
+        className={
+          'h-1.5 w-1.5 rounded-full ' +
+          (status === 'done' ? 'bg-agent-tool-read'
+           : status === 'error' ? 'bg-agent-destructive'
+           : 'bg-agent-muted-foreground animate-pulse')
+        }
+      />
+      <span className="font-mono">{call.name}</span>
+      <span className="uppercase tracking-wide text-agent-muted-foreground">{mode}</span>
+    </span>
+  );
+}
+```
+
+## Approval contract
+
+When `mode === 'local'`, `requiresApproval` is `true`. The convention is:
+
+* If the parent component supplies `onApprove` / `onReject`, render approval buttons.
+* If neither is supplied, the call should remain in `pending` and **not** be auto-executed — the user must approve via some other mechanism (a system-level prompt, a settings toggle, …).
+
+`<ToolCallRenderer>` already implements this; the hook just exposes the `requiresApproval` boolean for callers who want to enforce it themselves.