@steerable/agent-ui 0.2.3 → 0.2.4

package/src/components/index.ts

@@ -2,7 +2,19 @@ export { MessageList } from './MessageList.js';
 export type { MessageListProps, MessageRendererProps } from './MessageList.js';
 
 export { ChatPanel } from './ChatPanel.js';
-export type { ChatPanelProps } from './ChatPanel.js';
+export type {
+  ChatPanelProps,
+  ChatPanelRootProps,
+  ChatPanelHeaderProps,
+  ChatPanelMessagesProps,
+  ChatPanelInputProps,
+  ChatPanelInputHandle,
+  ChatPanelEmptyProps,
+  ChatPanelStreamingStatusProps,
+} from './ChatPanel.js';
+
+export { AgentSelector } from './AgentSelector.js';
+export type { AgentSelectorProps } from './AgentSelector.js';
 
 export { OrchestrationPlanCard } from './OrchestrationPlanCard.js';
 export type {

package/src/index.ts

@@ -10,3 +10,46 @@
 
 export * from './hooks/index.js';
 export * from './components/index.js';
+
+// `state/` is the home for chat-session primitives (hooks + transports +
+// SSE parsing) lifted out of deeppath / deeppath-agent. The package root
+// re-exports the public surface for convenience; the `./state` subpath is the
+// canonical entrypoint for tree-shaking.
+export {
+  SSEParser,
+  parseSSEData,
+  bridgeLegacySSE,
+  MockChatStreamTransport,
+  useChatComposer,
+  useChatList,
+  useChatSession,
+  useToolCallStream,
+  useScrollLock,
+  ChatSessionProvider,
+  useChatSessionContext,
+  useOptionalChatSession,
+  useChatSessionSlice,
+} from './state/index.js';
+export type {
+  SSEFrame,
+  SSEParserOptions,
+  EnvelopeProfile,
+  BridgeLegacySSEOptions,
+  MockScript,
+  MockScriptStep,
+  MockChatStreamTransportOptions,
+  UseChatComposerOptions,
+  UseChatComposerReturn,
+  ChatListTransport,
+  UseChatListOptions,
+  UseChatListReturn,
+  UseChatSessionOptions,
+  UseChatSessionReturn,
+  ToolCallEntry,
+  UseToolCallStreamOptions,
+  UseToolCallStreamReturn,
+  UseScrollLockOptions,
+  UseScrollLockReturn,
+  ChatSessionContextValue,
+  ChatSessionProviderProps,
+} from './state/index.js';

package/src/state/ChatSessionProvider.test.tsx

@@ -0,0 +1,85 @@
+/**
+ * Smoke tests for `ChatSessionProvider`. Verifies that the provider exposes
+ * the active session, that `useChatSessionContext` throws outside it, and
+ * that the optional / slice variants degrade gracefully.
+ */
+import * as React from 'react';
+import { render, screen, act, fireEvent } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  ChatSessionProvider,
+  useChatSessionContext,
+  useOptionalChatSession,
+  useChatSessionSlice,
+  useChatSession,
+} from './index.js';
+import { MockChatStreamTransport } from './MockChatStreamTransport.js';
+
+function Probe({ onValue }: { onValue: (v: unknown) => void }) {
+  const ctx = useChatSessionContext();
+  React.useEffect(() => {
+    onValue({ messages: ctx.messages.length, isStreaming: ctx.isStreaming });
+  }, [ctx.messages.length, ctx.isStreaming, onValue]);
+  return <span data-testid="ok">ok</span>;
+}
+
+function OptionalProbe({ onResult }: { onResult: (v: unknown) => void }) {
+  const ctx = useOptionalChatSession();
+  React.useEffect(() => onResult(ctx), [ctx, onResult]);
+  return <span>maybe</span>;
+}
+
+function SliceProbe({ onValue }: { onValue: (v: unknown) => void }) {
+  const slice = useChatSessionSlice();
+  React.useEffect(() => onValue(slice), [slice, onValue]);
+  return <span>slice</span>;
+}
+
+function Host({ children }: { children: React.ReactNode }) {
+  const transport = React.useMemo(
+    () =>
+      new MockChatStreamTransport({
+        script: [
+          { event: { type: 'message.delta', role: 'assistant', delta: 'hi' } },
+          { event: { type: 'message.complete' } },
+        ],
+      }),
+    [],
+  );
+  const session = useChatSession({ transport });
+  return <ChatSessionProvider value={session}>{children}</ChatSessionProvider>;
+}
+
+describe('ChatSessionProvider', () => {
+  it('exposes the session via useChatSessionContext', () => {
+    const seen = vi.fn();
+    render(
+      <Host>
+        <Probe onValue={seen} />
+      </Host>,
+    );
+    expect(screen.getByTestId('ok')).toBeTruthy();
+    expect(seen).toHaveBeenCalled();
+  });
+
+  it('useChatSessionContext throws outside provider', () => {
+    const consoleError = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    expect(() => {
+      render(<Probe onValue={vi.fn()} />);
+    }).toThrow(/inside a <ChatSessionProvider/);
+    consoleError.mockRestore();
+  });
+
+  it('useOptionalChatSession returns null outside provider', () => {
+    const seen = vi.fn();
+    render(<OptionalProbe onResult={seen} />);
+    expect(seen).toHaveBeenCalledWith(null);
+  });
+
+  it('useChatSessionSlice returns null outside provider', () => {
+    const seen = vi.fn();
+    render(<SliceProbe onValue={seen} />);
+    expect(seen).toHaveBeenCalledWith(null);
+  });
+});

package/src/state/ChatSessionProvider.tsx

@@ -0,0 +1,98 @@
+/**
+ * `ChatSessionProvider` + `useChatSessionContext`
+ *
+ * Lifts the chat-session primitives out of the host app's god-context (e.g.
+ * deeppath's `ChatUIContext`, deeppath-agent's hooks) into a framework-owned
+ * provider. Concretely it owns:
+ *
+ *   - the streaming transcript: `messages`, `isStreaming`, `streamingMessageId`
+ *   - send / cancel / clear actions
+ *   - the composer (draft, send, cancel, key handlers)
+ *
+ * App-specific concerns that don't belong here (file uploads, geolocation,
+ * suggestion banners, chat tool toggles, chat list / agent selector) stay in
+ * the host app's own context. The `extras` slot lets apps thread custom
+ * values through the same provider so chat cards can call host actions
+ * without prop-drilling.
+ *
+ * Usage in a host app:
+ *
+ *   <ChatSessionProvider
+ *     value={{ ...useChatSession({ transport }), extras: { ...appHooks } }}
+ *   >
+ *     <ChatPanel.Root>...</ChatPanel.Root>
+ *   </ChatSessionProvider>
+ *
+ * Cards / shell pieces consume via `useChatSessionContext()` so they don't
+ * import the host's context directly. This is the seam that lets the same
+ * compound `ChatPanel` work in deeppath, deeppath-agent, and the framework
+ * `examples/web-shell`.
+ */
+import * as React from 'react';
+import type { ChatMessage } from '@steerable/agent-protocol';
+import type { UseChatSessionReturn } from './useChatSession.js';
+
+export interface ChatSessionContextValue<TExtras = unknown> extends UseChatSessionReturn {
+  /** Host-specific values threaded through the same provider (geo, files, ...). */
+  extras?: TExtras;
+}
+
+const ChatSessionContext = React.createContext<ChatSessionContextValue | null>(null);
+
+export interface ChatSessionProviderProps<TExtras = unknown> {
+  value: ChatSessionContextValue<TExtras>;
+  children: React.ReactNode;
+}
+
+export function ChatSessionProvider<TExtras = unknown>({
+  value,
+  children,
+}: ChatSessionProviderProps<TExtras>) {
+  return (
+    <ChatSessionContext.Provider value={value as ChatSessionContextValue}>
+      {children}
+    </ChatSessionContext.Provider>
+  );
+}
+
+/**
+ * Read the active chat session. Throws if no `ChatSessionProvider` is
+ * mounted above -- this is intentional: cards / shell pieces should be
+ * usable both inside the provider (typical) and via direct props for
+ * apps that haven't migrated yet (use `useOptionalChatSession()` for that).
+ */
+export function useChatSessionContext<TExtras = unknown>(): ChatSessionContextValue<TExtras> {
+  const ctx = React.useContext(ChatSessionContext);
+  if (!ctx) {
+    throw new Error('useChatSessionContext must be used inside a <ChatSessionProvider />');
+  }
+  return ctx as ChatSessionContextValue<TExtras>;
+}
+
+/** Non-throwing variant for components that want to fall back to props. */
+export function useOptionalChatSession<TExtras = unknown>():
+  | ChatSessionContextValue<TExtras>
+  | null {
+  const ctx = React.useContext(ChatSessionContext);
+  return ctx as ChatSessionContextValue<TExtras> | null;
+}
+
+/**
+ * Convenience selector for the most-used slice in cards (`{ messages,
+ * isStreaming, sendUserMessage, cancel }`). Returns null when there's no
+ * provider so cards can opt into context-driven mode incrementally.
+ */
+export function useChatSessionSlice():
+  | Pick<ChatSessionContextValue, 'messages' | 'isStreaming' | 'sendUserMessage' | 'cancel'>
+  | null {
+  const ctx = useOptionalChatSession();
+  if (!ctx) return null;
+  return {
+    messages: ctx.messages,
+    isStreaming: ctx.isStreaming,
+    sendUserMessage: ctx.sendUserMessage,
+    cancel: ctx.cancel,
+  };
+}
+
+export type { ChatMessage };

package/src/state/MockChatStreamTransport.stories.tsx

@@ -0,0 +1,95 @@
+/**
+ * Storybook story for `MockChatStreamTransport` paired with `useChatSession`.
+ * This is the canonical "framework runs end-to-end with zero backend" demo —
+ * the same pattern is used by `examples/web-shell` in wave 5.
+ */
+
+import type { Meta, StoryObj } from '@storybook/react';
+import { useMemo } from 'react';
+import type { SSEEvent } from '@steerable/agent-protocol';
+import { ChatPanel } from '../components/ChatPanel.js';
+import { MockChatStreamTransport } from './MockChatStreamTransport.js';
+import { useChatSession } from './useChatSession.js';
+
+const meta: Meta = {
+  title: 'State/MockChatStreamTransport',
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Scripted SSE transport used in tests, stories, and the framework web-shell example. Pair with `useChatSession` for a fully offline chat demo.',
+      },
+    },
+  },
+};
+export default meta;
+type Story = StoryObj;
+
+const baselineScript: SSEEvent[] = [
+  { type: 'content', content: 'Sure — ' },
+  { type: 'content', content: "here's a plan:\n\n" },
+  { type: 'content', content: '1. Outline goals\n' },
+  { type: 'content', content: '2. Gather inputs\n' },
+  { type: 'content', content: '3. Iterate\n\n' },
+  { type: 'content', content: 'Want me to dive deeper into any step?' },
+  { type: 'done' },
+];
+
+const toolCallScript: SSEEvent[] = [
+  { type: 'content', content: 'Checking the weather…\n' },
+  {
+    type: 'tool_call',
+    payload: { id: 'c1', name: 'get_weather', arguments: { city: 'Tokyo' } },
+  },
+  {
+    type: 'tool_result',
+    payload: { success: true, data: { temp: 22, conditions: 'clear' } },
+  },
+  { type: 'content', content: '\nIt is 22°C and clear in Tokyo right now.' },
+  { type: 'done' },
+];
+
+function DemoChat({ scripts, delayMs }: { scripts: SSEEvent[][]; delayMs: number }) {
+  const transport = useMemo(
+    () =>
+      new MockChatStreamTransport({
+        scripts,
+        defaultDelayMs: delayMs,
+        exhaustionPolicy: 'cycle',
+      }),
+    [scripts, delayMs],
+  );
+  const session = useChatSession({ transport });
+
+  return (
+    <div className="h-[640px] w-full max-w-3xl border border-agent-border bg-agent-canvas">
+      <ChatPanel
+        messages={session.messages}
+        isStreaming={session.isStreaming}
+        onSubmit={async ({ content }) => {
+          await session.sendUserMessage({ content });
+        }}
+        onCancel={session.cancel}
+        emptyState={
+          <div className="m-auto max-w-sm text-center text-sm text-agent-muted-foreground">
+            <p className="font-medium text-agent-foreground">Try the mock transport</p>
+            <p className="mt-1">Anything you type triggers the next scripted reply.</p>
+          </div>
+        }
+      />
+    </div>
+  );
+}
+
+export const ContentOnly: Story = {
+  render: () => <DemoChat scripts={[baselineScript]} delayMs={30} />,
+};
+
+export const WithToolCall: Story = {
+  render: () => <DemoChat scripts={[toolCallScript]} delayMs={30} />,
+};
+
+export const Cycling: Story = {
+  render: () => <DemoChat scripts={[baselineScript, toolCallScript]} delayMs={30} />,
+};

package/src/state/MockChatStreamTransport.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Tests for `MockChatStreamTransport`.
+ *
+ * The mock is the source of all canned demos / stories / fixtures, so a
+ * regression here cascades. We cover: per-turn script rotation, exhaustion
+ * policies, the cancel handle, and per-step delays.
+ */
+
+import { describe, expect, it, vi } from 'vitest';
+import { MockChatStreamTransport } from './MockChatStreamTransport';
+
+describe('MockChatStreamTransport', () => {
+  it('replays the script for the current turn', async () => {
+    const onEvent = vi.fn();
+    const transport = new MockChatStreamTransport({
+      scripts: [[
+        { type: 'content', content: 'a' },
+        { type: 'content', content: 'b' },
+        { type: 'done' },
+      ]],
+    });
+    await transport.stream({ content: 'hi' }, onEvent);
+    // The mock dispatches synchronously when defaultDelayMs is 0 — but it
+    // still goes through a microtask queue inside `run()`. Flush.
+    await new Promise((r) => setTimeout(r, 0));
+    expect(onEvent).toHaveBeenCalledTimes(3);
+    expect(onEvent.mock.calls.map((c) => c[0].type)).toEqual([
+      'content',
+      'content',
+      'done',
+    ]);
+  });
+
+  it('cycles scripts when more turns than scripts exist (default)', async () => {
+    const transport = new MockChatStreamTransport({
+      scripts: [
+        [{ type: 'content', content: 'a' }, { type: 'done' }],
+        [{ type: 'content', content: 'b' }, { type: 'done' }],
+      ],
+    });
+    const sink: string[] = [];
+    const onEvent = (e: any) => {
+      if (e.type === 'content') sink.push(e.content);
+    };
+    await transport.stream({ content: '' }, onEvent);
+    await transport.stream({ content: '' }, onEvent);
+    await transport.stream({ content: '' }, onEvent);
+    await new Promise((r) => setTimeout(r, 0));
+    expect(sink).toEqual(['a', 'b', 'a']);
+  });
+
+  it('exhaustionPolicy=last keeps emitting the last script', async () => {
+    const transport = new MockChatStreamTransport({
+      scripts: [
+        [{ type: 'content', content: 'first' }, { type: 'done' }],
+        [{ type: 'content', content: 'last' }, { type: 'done' }],
+      ],
+      exhaustionPolicy: 'last',
+    });
+    const sink: string[] = [];
+    const onEvent = (e: any) => {
+      if (e.type === 'content') sink.push(e.content);
+    };
+    await transport.stream({ content: '' }, onEvent);
+    await transport.stream({ content: '' }, onEvent);
+    await transport.stream({ content: '' }, onEvent);
+    await new Promise((r) => setTimeout(r, 0));
+    expect(sink).toEqual(['first', 'last', 'last']);
+  });
+
+  it('exhaustionPolicy=empty emits a bare done event', async () => {
+    const transport = new MockChatStreamTransport({
+      scripts: [[{ type: 'content', content: 'one' }, { type: 'done' }]],
+      exhaustionPolicy: 'empty',
+    });
+    const events: string[] = [];
+    await transport.stream({ content: '' }, (e) => events.push(e.type));
+    await transport.stream({ content: '' }, (e) => events.push(e.type));
+    await new Promise((r) => setTimeout(r, 0));
+    expect(events).toEqual(['content', 'done', 'done']);
+  });
+
+  it('accepts a callback in place of a script array', async () => {
+    const transport = new MockChatStreamTransport({
+      scripts: (turn, input) => [
+        { type: 'content', content: `${input.content}:${turn}` },
+        { type: 'done' },
+      ],
+    });
+    const sink: string[] = [];
+    await transport.stream({ content: 'hi' }, (e) => {
+      if (e.type === 'content') sink.push(e.content!);
+    });
+    await transport.stream({ content: 'yo' }, (e) => {
+      if (e.type === 'content') sink.push(e.content!);
+    });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(sink).toEqual(['hi:0', 'yo:1']);
+  });
+
+  it('honours per-step delayMs', async () => {
+    vi.useFakeTimers();
+    try {
+      const transport = new MockChatStreamTransport({
+        scripts: [[
+          { event: { type: 'content', content: 'fast' } },
+          { event: { type: 'content', content: 'slow' }, delayMs: 100 },
+          { type: 'done' },
+        ]],
+      });
+      const events: any[] = [];
+      const p = transport.stream({ content: '' }, (e) => events.push(e));
+      await p;
+      // After the immediate microtask: first event delivered.
+      await Promise.resolve();
+      expect(events.length).toBeLessThanOrEqual(2);
+      await vi.advanceTimersByTimeAsync(100);
+      // After the delay: all events delivered.
+      expect(events.length).toBe(3);
+      expect(events[1].content).toBe('slow');
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('cancel handle stops further events', async () => {
+    const transport = new MockChatStreamTransport({
+      scripts: [[
+        { event: { type: 'content', content: 'a' }, delayMs: 10 },
+        { event: { type: 'content', content: 'b' }, delayMs: 10 },
+        { type: 'done' },
+      ]],
+    });
+    const events: any[] = [];
+    const cancel = await transport.stream({ content: '' }, (e) => events.push(e));
+    cancel();
+    await new Promise((r) => setTimeout(r, 50));
+    // Cancel should have prevented at least one of the delayed events from
+    // arriving. We don't pin the exact count (timing-dependent), just the
+    // strict upper bound.
+    expect(events.length).toBeLessThan(3);
+  });
+
+  it('reset() rewinds the turn counter', async () => {
+    const transport = new MockChatStreamTransport({
+      scripts: [
+        [{ type: 'content', content: 'a' }, { type: 'done' }],
+        [{ type: 'content', content: 'b' }, { type: 'done' }],
+      ],
+      exhaustionPolicy: 'empty',
+    });
+    const sink: string[] = [];
+    await transport.stream({ content: '' }, (e) => {
+      if (e.type === 'content') sink.push(e.content!);
+    });
+    transport.reset();
+    await transport.stream({ content: '' }, (e) => {
+      if (e.type === 'content') sink.push(e.content!);
+    });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(sink).toEqual(['a', 'a']);
+  });
+});

package/src/state/MockChatStreamTransport.ts

@@ -0,0 +1,123 @@
+/**
+ * `MockChatStreamTransport` — canned-script transport for stories, tests, and
+ * the framework's runnable web-shell example.
+ *
+ * Replays a deterministic list of `SSEEvent` per call to `stream()`. Optional
+ * per-event delays make streaming feel real in demos. Loop the same script
+ * forever, or vary by index — the constructor accepts either an array (one
+ * script per turn) or a function `(turn: number) => SSEEvent[]`.
+ *
+ *   const transport = new MockChatStreamTransport({
+ *     scripts: [
+ *       [{ type: 'content', content: 'Hello, ' }, { type: 'content', content: 'world!' }, { type: 'done' }],
+ *     ],
+ *     defaultDelayMs: 25,
+ *   });
+ *
+ *   const { messages, sendUserMessage } = useChatStream({ transport });
+ */
+
+import type { SSEEvent } from '@steerable/agent-protocol';
+import type {
+  ChatStreamSendInput,
+  ChatStreamTransport,
+} from '../hooks/useChatStream.js';
+
+export type MockScriptStep =
+  | SSEEvent
+  | { event: SSEEvent; delayMs?: number };
+
+export type MockScript = MockScriptStep[];
+
+export interface MockChatStreamTransportOptions {
+  /**
+   * A list of scripts (one per turn), or a callback that returns a script for
+   * the current turn. Required.
+   */
+  scripts: MockScript[] | ((turn: number, input: ChatStreamSendInput) => MockScript);
+  /** Delay between events when the step doesn't specify one. Defaults to 0. */
+  defaultDelayMs?: number;
+  /**
+   * What to do when there are fewer scripts than turns:
+   *   - 'cycle' (default): wrap modulo `scripts.length`.
+   *   - 'last': stay on the last script.
+   *   - 'empty': emit only a `done` event.
+   */
+  exhaustionPolicy?: 'cycle' | 'last' | 'empty';
+}
+
+export class MockChatStreamTransport implements ChatStreamTransport {
+  private turn = 0;
+  /** Set of in-flight cancel signals, exposed for tests. */
+  readonly cancelled = new Set<number>();
+
+  constructor(private readonly options: MockChatStreamTransportOptions) {}
+
+  /** Reset the turn counter — useful between fixture-driven test cases. */
+  reset(): void {
+    this.turn = 0;
+    this.cancelled.clear();
+  }
+
+  async stream(
+    input: ChatStreamSendInput,
+    onEvent: (event: SSEEvent) => void,
+  ): Promise<() => void> {
+    const turn = this.turn++;
+    const script = this.resolveScript(turn, input);
+    let cancelled = false;
+    const cancel = () => {
+      cancelled = true;
+      this.cancelled.add(turn);
+    };
+    void this.run(script, onEvent, () => cancelled);
+    // Return synchronously so the framework hook can capture the cancel handle
+    // without waiting for the full script.
+    return cancel;
+  }
+
+  private resolveScript(turn: number, input: ChatStreamSendInput): MockScript {
+    const { scripts, exhaustionPolicy = 'cycle' } = this.options;
+    if (typeof scripts === 'function') return scripts(turn, input);
+    if (scripts.length === 0) return [{ type: 'done' }];
+    if (turn < scripts.length) return scripts[turn];
+    switch (exhaustionPolicy) {
+      case 'last':
+        return scripts[scripts.length - 1];
+      case 'empty':
+        return [{ type: 'done' }];
+      case 'cycle':
+      default:
+        return scripts[turn % scripts.length];
+    }
+  }
+
+  private async run(
+    script: MockScript,
+    onEvent: (event: SSEEvent) => void,
+    isCancelled: () => boolean,
+  ): Promise<void> {
+    const defaultDelay = this.options.defaultDelayMs ?? 0;
+    for (const step of script) {
+      if (isCancelled()) return;
+      const { event, delayMs } = normaliseStep(step, defaultDelay);
+      if (delayMs > 0) await sleep(delayMs);
+      if (isCancelled()) return;
+      onEvent(event);
+    }
+  }
+}
+
+function normaliseStep(
+  step: MockScriptStep,
+  defaultDelayMs: number,
+): { event: SSEEvent; delayMs: number } {
+  if ('event' in step && step.event && typeof step.event === 'object') {
+    return { event: step.event, delayMs: step.delayMs ?? defaultDelayMs };
+  }
+  return { event: step as SSEEvent, delayMs: defaultDelayMs };
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}