@steerable/agent-ui 0.2.0

package/src/hooks/useAgentSession.mdx

@@ -0,0 +1,115 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Hooks/useAgentSession" />
+
+# `useAgentSession`
+
+> Light-weight wrapper around the agent-session lifecycle. Wraps `create` / `resume` / `list` against any storage adapter and gives you a stable `current` + `sessions` view.
+
+In most production setups, sessions are created lazily on the first user message — but the desktop and web shells still need a deterministic handle to fetch a session, resume an existing one, or render a "your active sessions" picker. `useAgentSession` exposes that surface in a transport-agnostic shape that maps 1:1 onto the framework's storage adapters (`InMemoryStorage`, `SqlAlchemyStorage`).
+
+## Signature
+
+```ts
+import { useAgentSession } from '@steerable/agent-ui';
+
+const {
+  sessions,    // AgentSession[]  — active sessions for the current filter
+  current,     // AgentSession | null
+  isLoading,
+  error,
+  create,      // (input) => Promise<AgentSession>
+  resume,      // (sessionId) => Promise<AgentSession>
+  refresh,     // () => Promise<void>
+  setCurrent,  // (session) => void
+} = useAgentSession({
+  transport,   // AgentSessionTransport (required)
+  autoLoad,    // { userId?, chatId?, activeOnly? } (optional)
+});
+```
+
+## The transport
+
+```ts
+interface AgentSessionTransport {
+  create: (input: {
+    chatId: string;
+    userId: string;
+    projectId?: string | null;
+    scenario?: string;
+    stageData?: Record<string, unknown> | null;
+  }) => Promise<AgentSession>;
+  resume: (sessionId: string) => Promise<AgentSession>;
+  list: (filter: {
+    userId?: string;
+    chatId?: string;
+    activeOnly?: boolean;
+  }) => Promise<AgentSession[]>;
+}
+```
+
+You can plug in:
+
+* a thin REST client (`fetch('/api/sessions/...')`),
+* an IPC bridge (`window.electron.session.list(...)`),
+* a sidecar JSON-RPC client (`sidecar.call('session.list', filter)`),
+* an in-memory mock for Storybook / tests.
+
+## Stability contract
+
+Two subtle but important behaviours:
+
+1. **`autoLoad` may be a fresh object every render.** The hook keys the `list` effect on the **values** in `autoLoad` (`userId` / `chatId` / `activeOnly`), not the object identity. Inline literals like `{ userId, activeOnly: true }` are safe.
+2. **`transport` is held by ref.** Swapping the transport implementation mid-session does **not** trigger a refetch. If you want one, call `refresh()` explicitly. This avoids surprise refetches when the parent re-renders and creates a new transport closure.
+
+## Example — REST-backed session picker
+
+```tsx
+import { useAgentSession } from '@steerable/agent-ui';
+
+function SessionPicker({ userId }: { userId: string }) {
+  const { sessions, current, isLoading, resume, setCurrent } = useAgentSession({
+    transport: {
+      create: (input) =>
+        fetch('/api/sessions', { method: 'POST', body: JSON.stringify(input) })
+          .then((r) => r.json()),
+      resume: (sessionId) =>
+        fetch(`/api/sessions/${sessionId}`).then((r) => r.json()),
+      list: (filter) => {
+        const qs = new URLSearchParams();
+        if (filter.userId) qs.set('userId', filter.userId);
+        if (filter.chatId) qs.set('chatId', filter.chatId);
+        if (filter.activeOnly) qs.set('activeOnly', 'true');
+        return fetch(`/api/sessions?${qs}`).then((r) => r.json());
+      },
+    },
+    autoLoad: { userId, activeOnly: true },
+  });
+
+  if (isLoading && sessions.length === 0) return <p>Loading sessions…</p>;
+
+  return (
+    <ul>
+      {sessions.map((s) => (
+        <li key={s.sessionId} aria-current={current?.sessionId === s.sessionId}>
+          <button
+            type="button"
+            onClick={async () => {
+              const fresh = await resume(s.sessionId);
+              setCurrent(fresh);
+            }}
+          >
+            {s.sessionId} — {s.scenario}
+          </button>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## Caveats
+
+* `current` is **the session created or resumed via this hook**, not whatever your global app state thinks is current. Mirror it into your store with `setCurrent` if you need cross-component access.
+* Errors from `create` are re-thrown after being captured into `error` state, so you can `await create(...)` in a try/catch **and** still render a banner from `error`.
+* `refresh` is a no-op when `autoLoad` is undefined. Pass an explicit filter to enable polling-style refetches.

package/src/hooks/useAgentSession.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Tests for `useAgentSession` — the hook is a thin transport adapter, but we
+ * still want to nail down the autoLoad behaviour and current-session pointer
+ * because callers route routing decisions off `current?.sessionId`.
+ */
+
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import type { AgentSession } from '@steerable/agent-protocol';
+import { useAgentSession, type AgentSessionTransport } from './useAgentSession';
+
+function makeSession(overrides: Partial<AgentSession>): AgentSession {
+  return {
+    id: 'row1',
+    sessionId: 's1',
+    userId: 'u1',
+    chatId: 'c1',
+    currentStage: 'INIT',
+    isActive: true,
+    createdAt: new Date('2025-01-01').toISOString(),
+    updatedAt: new Date('2025-01-01').toISOString(),
+    ...overrides,
+  };
+}
+
+function makeTransport(
+  list: AgentSession[] = [],
+): { transport: AgentSessionTransport; spies: Record<string, ReturnType<typeof vi.fn>> } {
+  const spies = {
+    create: vi.fn(async (input: Parameters<AgentSessionTransport['create']>[0]) =>
+      makeSession({
+        sessionId: 'created_' + input.chatId,
+        userId: input.userId,
+        chatId: input.chatId,
+      }),
+    ),
+    resume: vi.fn(async (sessionId: string) =>
+      makeSession({ sessionId, currentStage: 'RESUMED' }),
+    ),
+    list: vi.fn(async () => list),
+  };
+  return { transport: spies as unknown as AgentSessionTransport, spies };
+}
+
+describe('useAgentSession', () => {
+  it('does not call list when autoLoad is omitted', async () => {
+    const { transport, spies } = makeTransport();
+    renderHook(() => useAgentSession({ transport }));
+    await waitFor(() => {
+      expect(spies.list).not.toHaveBeenCalled();
+    });
+  });
+
+  it('calls list on mount when autoLoad is provided and exposes the result', async () => {
+    const sessions = [makeSession({ sessionId: 's1' }), makeSession({ sessionId: 's2' })];
+    const { transport, spies } = makeTransport(sessions);
+    const { result } = renderHook(() =>
+      useAgentSession({
+        transport,
+        autoLoad: { userId: 'u1', activeOnly: true },
+      }),
+    );
+
+    await waitFor(() => {
+      expect(spies.list).toHaveBeenCalledTimes(1);
+      expect(result.current.sessions).toHaveLength(2);
+    });
+  });
+
+  it('create() pushes the new session in front and updates current', async () => {
+    const { transport, spies } = makeTransport([]);
+    const { result } = renderHook(() =>
+      useAgentSession({ transport, autoLoad: { userId: 'u1' } }),
+    );
+
+    await waitFor(() => expect(spies.list).toHaveBeenCalled());
+
+    let created: AgentSession | undefined;
+    await act(async () => {
+      created = await result.current.create({
+        chatId: 'chat-x',
+        userId: 'u1',
+      });
+    });
+
+    expect(created?.sessionId).toBe('created_chat-x');
+    await waitFor(() => {
+      expect(result.current.current?.sessionId).toBe('created_chat-x');
+      expect(result.current.sessions[0]?.sessionId).toBe('created_chat-x');
+    });
+  });
+
+  it('resume() updates current without mutating sessions', async () => {
+    const list = [makeSession({ sessionId: 's-old' })];
+    const { transport, spies } = makeTransport(list);
+    const { result } = renderHook(() =>
+      useAgentSession({ transport, autoLoad: { userId: 'u1' } }),
+    );
+
+    await waitFor(() => expect(spies.list).toHaveBeenCalled());
+
+    await act(async () => {
+      await result.current.resume('s-old');
+    });
+
+    expect(result.current.current?.sessionId).toBe('s-old');
+    expect(result.current.current?.currentStage).toBe('RESUMED');
+    expect(result.current.sessions).toHaveLength(1);
+  });
+
+  it('captures errors from list() into the error field without throwing', async () => {
+    const transport: AgentSessionTransport = {
+      create: vi.fn(),
+      resume: vi.fn(),
+      list: vi.fn(async () => {
+        throw new Error('db down');
+      }),
+    };
+    const { result } = renderHook(() =>
+      useAgentSession({ transport, autoLoad: { userId: 'u1' } }),
+    );
+
+    await waitFor(() => {
+      expect(result.current.error?.message).toBe('db down');
+    });
+  });
+});

package/src/hooks/useAgentSession.ts

@@ -0,0 +1,181 @@
+/**
+ * `useAgentSession` — light-weight wrapper around the session lifecycle.
+ *
+ * Sessions are created lazily on first message in most production setups, but
+ * the desktop / web clients still need a deterministic handle to fetch /
+ * resume / list. The hook exposes a transport-agnostic API matching the
+ * methods on the framework's storage adapter (`InMemoryStorage`,
+ * `SqlAlchemyStorage`) so consumers can wire any backend.
+ *
+ * Stability contract:
+ *   The hook tolerates inline-object literals for `autoLoad`. We re-run the
+ *   `list` effect only when the **values** in `autoLoad` change, not when the
+ *   object identity changes (otherwise an unmemoised consumer would loop).
+ *   `transport` is held by ref so swapping the implementation mid-session
+ *   doesn't trigger a refetch — call `refresh()` explicitly if you need that.
+ */
+
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import type { AgentSession } from '@steerable/agent-protocol';
+
+export interface AgentSessionTransport {
+  create: (input: {
+    chatId: string;
+    userId: string;
+    projectId?: string | null;
+    scenario?: string;
+    stageData?: Record<string, unknown> | null;
+  }) => Promise<AgentSession>;
+  resume: (sessionId: string) => Promise<AgentSession>;
+  list: (filter: {
+    userId?: string;
+    chatId?: string;
+    activeOnly?: boolean;
+  }) => Promise<AgentSession[]>;
+}
+
+export interface UseAgentSessionOptions {
+  transport: AgentSessionTransport;
+  /** Optional auto-load filter; when set the hook calls `list` on mount. */
+  autoLoad?: { userId?: string; chatId?: string; activeOnly?: boolean };
+}
+
+export interface UseAgentSessionReturn {
+  /** Active sessions for the current filter. */
+  sessions: AgentSession[];
+  /** The session created/resumed most recently via this hook. */
+  current: AgentSession | null;
+  isLoading: boolean;
+  error: Error | null;
+  create: AgentSessionTransport['create'];
+  resume: AgentSessionTransport['resume'];
+  refresh: () => Promise<void>;
+  /** Set the current session pointer without re-fetching. */
+  setCurrent: (session: AgentSession | null) => void;
+}
+
+function autoLoadKey(
+  autoLoad: UseAgentSessionOptions['autoLoad'],
+): string | null {
+  if (!autoLoad) return null;
+  // Stable, deterministic key — values are primitives so JSON.stringify is fine.
+  return JSON.stringify({
+    userId: autoLoad.userId ?? null,
+    chatId: autoLoad.chatId ?? null,
+    activeOnly: autoLoad.activeOnly ?? null,
+  });
+}
+
+export function useAgentSession(
+  options: UseAgentSessionOptions,
+): UseAgentSessionReturn {
+  const [sessions, setSessions] = useState<AgentSession[]>([]);
+  const [current, setCurrent] = useState<AgentSession | null>(null);
+  const [isLoading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const mountedRef = useRef(true);
+  const transportRef = useRef(options.transport);
+  transportRef.current = options.transport;
+
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+
+  const autoLoadKeyVal = autoLoadKey(options.autoLoad);
+
+  const refresh = useCallback(async () => {
+    if (!options.autoLoad) return;
+    setLoading(true);
+    try {
+      const list = await transportRef.current.list(options.autoLoad);
+      if (mountedRef.current) {
+        setSessions(list);
+        setError(null);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    } finally {
+      if (mountedRef.current) setLoading(false);
+    }
+    // We intentionally key on the serialised filter, not the object identity.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [autoLoadKeyVal]);
+
+  useEffect(() => {
+    if (autoLoadKeyVal === null) return;
+    void refresh();
+  }, [autoLoadKeyVal, refresh]);
+
+  const create = useCallback<AgentSessionTransport['create']>(
+    async (input) => {
+      setLoading(true);
+      try {
+        const session = await transportRef.current.create(input);
+        if (mountedRef.current) {
+          setCurrent(session);
+          setSessions((prev) => [
+            session,
+            ...prev.filter((s) => s.sessionId !== session.sessionId),
+          ]);
+          setError(null);
+        }
+        return session;
+      } catch (err) {
+        if (mountedRef.current) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        throw err;
+      } finally {
+        if (mountedRef.current) setLoading(false);
+      }
+    },
+    [],
+  );
+
+  const resume = useCallback<AgentSessionTransport['resume']>(
+    async (sessionId) => {
+      setLoading(true);
+      try {
+        const session = await transportRef.current.resume(sessionId);
+        if (mountedRef.current) {
+          setCurrent(session);
+          setError(null);
+        }
+        return session;
+      } catch (err) {
+        if (mountedRef.current) {
+          setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        throw err;
+      } finally {
+        if (mountedRef.current) setLoading(false);
+      }
+    },
+    [],
+  );
+
+  return useMemo<UseAgentSessionReturn>(
+    () => ({
+      sessions,
+      current,
+      isLoading,
+      error,
+      create,
+      resume,
+      refresh,
+      setCurrent,
+    }),
+    [sessions, current, isLoading, error, create, resume, refresh],
+  );
+}

package/src/hooks/useChatStream.mdx

@@ -0,0 +1,129 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Hooks/useChatStream" />
+
+# `useChatStream`
+
+> Owns the in-flight chat lifecycle. Translates an `SSEEvent` stream into `ChatMessage[]` mutations, exposes a `sendUserMessage` / `cancel` API, and stays unaware of HTTP / IPC / sidecar.
+
+## When to use
+
+Reach for `useChatStream` when you need to hold the message list **and** drive a streaming reply. If you just need to render messages owned somewhere else, drop `<MessageList>` directly and skip the hook.
+
+The hook does:
+
+* Append the user message + a placeholder assistant message on `sendUserMessage`.
+* Append `content` deltas onto the latest assistant turn.
+* Attach `tool_call` / `tool_result` events inline on the assistant message.
+* Surface `error` and `budget_exhausted` as the assistant content (so the UI shows the failure inline rather than crashing).
+* Forward every other event type (`agent`, `orchestration`, `loader-hint`, `keepalive`, …) to `onUnknownEvent` so callers can stash them into their own state.
+
+It does **not**:
+
+* Speak HTTP. You give it a `transport.stream()` function and it consumes whatever events you yield.
+* Persist messages. `initialMessages` seeds the buffer; `setMessages` replaces it. Persistence is the caller's job.
+* Know which provider you use. The framework spec defines the `SSEEvent` envelope — pick whichever LLM/agent backend you want as long as it speaks that envelope.
+
+## Signature
+
+```ts
+import { useChatStream } from '@steerable/agent-ui';
+
+const {
+  messages,            // ChatMessage[]
+  isStreaming,         // boolean
+  sendUserMessage,     // ({ content }) => Promise<void>
+  cancel,              // () => void
+  setMessages,         // (messages) => void
+  appendMessage,       // (message) => void
+} = useChatStream({
+  transport,           // ChatStreamTransport (required)
+  initialMessages,     // ChatMessage[] (optional)
+  toolResultToMessage, // (result) => ChatMessage | null (optional)
+  onUnknownEvent,      // (event) => void (optional)
+});
+```
+
+## Minimal example — fetch-based SSE transport
+
+```tsx
+import { ChatPanel, useChatStream } from '@steerable/agent-ui';
+import type { SSEEvent } from '@steerable/agent-protocol';
+
+function Chat({ chatId }: { chatId: string }) {
+  const { messages, isStreaming, sendUserMessage, cancel } = useChatStream({
+    transport: {
+      stream: async ({ content }, onEvent) => {
+        const ctrl = new AbortController();
+        const res = await fetch(`/api/chats/${chatId}/send`, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ content }),
+          signal: ctrl.signal,
+        });
+        if (!res.body) throw new Error('no SSE body');
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          for (const chunk of buffer.split('\n\n')) {
+            if (!chunk.startsWith('data: ')) continue;
+            try {
+              const event = JSON.parse(chunk.slice('data: '.length)) as SSEEvent;
+              onEvent(event);
+            } catch {
+              // ignore partial / heartbeat lines
+            }
+          }
+          buffer = '';
+        }
+        return () => ctrl.abort();
+      },
+    },
+  });
+
+  return (
+    <ChatPanel
+      messages={messages}
+      isStreaming={isStreaming}
+      onSubmit={sendUserMessage}
+      onCancel={cancel}
+    />
+  );
+}
+```
+
+## Custom event handling
+
+The default routing covers `content` / `tool_call` / `tool_result` / `done` / `error` / `budget_exhausted`. Everything else is forwarded to `onUnknownEvent`. Stash those in your own state for things like loader hints, agent-switch banners, or orchestration plan updates:
+
+```tsx
+const [hint, setHint] = useState<string | null>(null);
+const [plan, setPlan] = useState<OrchestrationStep[]>([]);
+
+const { ... } = useChatStream({
+  transport,
+  onUnknownEvent: (event) => {
+    if (event.type === 'loader-hint') setHint(event.hint ?? null);
+    if (event.type === 'orchestration') setPlan(parsePlan(event));
+  },
+});
+```
+
+## Cancellation
+
+`transport.stream` may return a `() => void` cancel handle. The hook stores it and calls it when:
+
+* the consumer calls `cancel()` (e.g. user taps "Stop"),
+* the component unmounts mid-stream.
+
+If your transport can't cancel, return `void` — the hook will simply mark `isStreaming` as `false` when the promise settles.
+
+## Caveats
+
+* `sendUserMessage` is a no-op while `isStreaming` is true. Wire your composer's send button to `disabled={isStreaming}` to mirror this in the UI.
+* Tool results are attached to the **latest assistant message**. If you need per-call lookup, override `renderToolCall` on `ChatPanel` and pull the result from your own map.
+* Setting `toolResultToMessage` to a non-null returner switches to a "tool result lives in its own message" model — useful if you want to render tool results as standalone bubbles. Otherwise the result rides inline on the assistant turn.