@steerable/agent-ui 0.2.3 → 0.2.5

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/hooks/useChatStream.test.ts

@@ -231,3 +231,81 @@ describe('useChatStream', () => {
     expect(true).toBe(true);
   });
 });
+
+describe('steerUserMessage', () => {
+  it('appends the user message when the transport accepts the steer', async () => {
+    const steer = vi.fn().mockResolvedValue(true);
+    const transport: ChatStreamTransport = {
+      stream: vi.fn(async (_input, onEvent) => {
+        onEvent({ type: 'content', content: 'working…' });
+        // keep the stream open until the test steers
+        await new Promise<void>((resolve) => setTimeout(resolve, 30));
+        onEvent({ type: 'content', content: 'done' });
+        onEvent({ type: 'done' });
+      }),
+      steer,
+    };
+    const { result } = renderHook(() => useChatStream({ transport }));
+
+    let done: Promise<void>;
+    act(() => {
+      done = result.current.sendUserMessage({ content: 'start' });
+    });
+    await act(async () => {
+      await new Promise((r) => setTimeout(r, 5));
+    });
+
+    let ok = false;
+    await act(async () => {
+      ok = await result.current.steerUserMessage('补充一句');
+    });
+    expect(ok).toBe(true);
+    expect(steer).toHaveBeenCalledWith('补充一句');
+    expect(
+      result.current.messages.some((m) => m.role === 'user' && m.content === '补充一句'),
+    ).toBe(true);
+
+    await act(async () => {
+      await done;
+    });
+  });
+
+  it('returns false and appends nothing when not streaming', async () => {
+    const steer = vi.fn().mockResolvedValue(true);
+    const transport: ChatStreamTransport = {
+      stream: vi.fn(async () => {}),
+      steer,
+    };
+    const { result } = renderHook(() => useChatStream({ transport }));
+
+    let ok = true;
+    await act(async () => {
+      ok = await result.current.steerUserMessage('hello');
+    });
+    expect(ok).toBe(false);
+    expect(steer).not.toHaveBeenCalled();
+    expect(result.current.messages).toHaveLength(0);
+  });
+
+  it('returns false when the transport has no steer support', async () => {
+    const transport: ChatStreamTransport = {
+      stream: vi.fn(async () => {
+        await new Promise<void>((resolve) => setTimeout(resolve, 20));
+      }),
+    };
+    const { result } = renderHook(() => useChatStream({ transport }));
+
+    let done: Promise<void>;
+    act(() => {
+      done = result.current.sendUserMessage({ content: 'start' });
+    });
+    let ok = true;
+    await act(async () => {
+      ok = await result.current.steerUserMessage('mid');
+    });
+    expect(ok).toBe(false);
+    await act(async () => {
+      await done;
+    });
+  });
+});

package/src/hooks/useChatStream.ts

@@ -38,6 +38,14 @@ export interface ChatStreamTransport {
     input: ChatStreamSendInput,
     onEvent: (event: SSEEvent) => void,
   ) => Promise<void | (() => void)>;
+  /**
+   * Optional mid-turn steering: inject a user message into the currently
+   * running turn (CoreLoop `steer`). Resolve `true` when the running turn
+   * accepted the message; `false` when no steerable turn is active (the
+   * caller should keep the draft — a normal send can follow once the turn
+   * ends). When omitted, the UI keeps send-during-streaming disabled.
+   */
+  steer?: (content: string) => Promise<boolean>;
 }
 
 export interface UseChatStreamOptions {
@@ -63,6 +71,13 @@ export interface UseChatStreamReturn {
   messages: ChatMessage[];
   isStreaming: boolean;
   sendUserMessage: (input: ChatStreamSendInput) => Promise<void>;
+  /**
+   * Steer the running turn with an extra user message. No-op resolving
+   * `false` when not streaming or the transport has no `steer`. On success
+   * the message is appended to the visible transcript immediately (the loop
+   * consumes it at the next round boundary).
+   */
+  steerUserMessage: (content: string) => Promise<boolean>;
   cancel: () => void;
   /** Replace the message buffer (e.g. when switching chat). */
   setMessages: (messages: ChatMessage[]) => void;
@@ -310,6 +325,21 @@ export function useChatStream(
     setStreaming(false);
   }, [setStreaming]);
 
+  const steerUserMessage = useCallback(
+    async (content: string): Promise<boolean> => {
+      const steer = options.transport.steer;
+      if (!isStreamingRef.current || !steer || !content.trim()) {
+        return false;
+      }
+      const ok = await steer(content);
+      if (ok) {
+        dispatch({ type: 'append', message: newUserMessage(content) });
+      }
+      return ok;
+    },
+    [options.transport],
+  );
+
   const setMessages = useCallback((messages: ChatMessage[]) => {
     dispatch({ type: 'reset', messages });
   }, []);
@@ -332,10 +362,11 @@ export function useChatStream(
       messages: state.messages,
       isStreaming: isStreamingRef.current,
       sendUserMessage,
+      steerUserMessage,
       cancel,
       setMessages,
       appendMessage,
     }),
-    [state.messages, sendUserMessage, cancel, setMessages, appendMessage],
+    [state.messages, sendUserMessage, steerUserMessage, cancel, setMessages, appendMessage],
   );
 }

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