@steerable/agent-ui 0.2.0

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@steerable/agent-ui",
+  "version": "0.2.0",
+  "description": "Steerable framework Tier 4 — headless React hooks (useAgentSession, useChatStream, useToolCallStatus) and Tailwind-themed components (ChatPanel, MessageList, OrchestrationPlanCard, ToolCallRenderer, SSEStreamView) for embedding Steerable agents in any React app.",
+  "license": "Apache-2.0",
+  "homepage": "https://pathlyapp.github.io/steerable-framework/storybook/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pathlyapp/steerable-framework.git",
+    "directory": "packages/agent-ui/ts"
+  },
+  "bugs": {
+    "url": "https://github.com/pathlyapp/steerable-framework/issues"
+  },
+  "keywords": [
+    "steerable",
+    "agent",
+    "ui",
+    "react",
+    "hooks",
+    "chat",
+    "sse",
+    "tailwind"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tailwind-preset": {
+      "types": "./dist/tailwind-preset.d.ts",
+      "import": "./dist/tailwind-preset.js"
+    },
+    "./hooks": {
+      "types": "./dist/hooks/index.d.ts",
+      "import": "./dist/hooks/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "import": "./dist/components/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@steerable/agent-protocol": "0.2.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.60.0",
+    "@storybook/addon-a11y": "^8.6.18",
+    "@storybook/addon-essentials": "^8.6.14",
+    "@storybook/addon-interactions": "^8.6.14",
+    "@storybook/react": "^8.6.18",
+    "@storybook/react-vite": "^8.6.18",
+    "@storybook/test": "^8.6.15",
+    "@storybook/test-runner": "^0.21.3",
+    "@tailwindcss/vite": "^4.3.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.7.0",
+    "axe-playwright": "^2.2.2",
+    "happy-dom": "^15.11.7",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "storybook": "^8.6.18",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^5.8.3",
+    "vite": "^5.4.21",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "storybook": "storybook dev -p 6006 --no-open",
+    "storybook:build": "storybook build -o storybook-static",
+    "storybook:test": "test-storybook --url http://127.0.0.1:6006",
+    "storybook:vrt": "playwright test --config playwright.config.ts",
+    "storybook:vrt:update": "playwright test --config playwright.config.ts --update-snapshots",
+    "storybook:ci": "pnpm storybook:build && pnpm storybook:vrt"
+  }
+}

package/src/Introduction.mdx

@@ -0,0 +1,71 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Introduction" />
+
+# @steerable/agent-ui
+
+> Headless React building blocks for Steerable agent UIs — chat shells, tool-call cards, orchestration plans, raw SSE inspectors, plus the hooks that wire them to any transport.
+
+This package ships the visual surface area you need to drop a Steerable agent into a React app, plus the lifecycle hooks that own message state and tool-call status. Components are intentionally **headless**: they render through Tailwind utility classes built on a small set of `--agent-*` design tokens, so consuming apps can theme them, replace any subtree, or compose them into bespoke layouts without forking.
+
+## What's in this Storybook
+
+* **Components** — visual primitives:
+  * [`ChatPanel`](?path=/docs/components-chatpanel--docs) — the foundational chat shell (`MessageList` + composer + stop button).
+  * [`MessageList`](?path=/docs/components-messagelist--docs) — auto-scrolling list with a render-prop bubble.
+  * [`OrchestrationPlanCard`](?path=/docs/components-orchestrationplancard--docs) — multi-step plan with per-step status.
+  * [`ToolCallRenderer`](?path=/docs/components-toolcallrenderer--docs) — tool-call card with mode badges, approval, expandable args/result.
+  * [`SSEStreamView`](?path=/docs/components-ssestreamview--docs) — append-only SSE event log, useful in trace tabs and dev consoles.
+* **Hooks** — transport-agnostic state:
+  * [`useChatStream`](?path=/docs/hooks-usechatstream--docs) — owns message state and translates `SSEEvent` into `ChatMessage` mutations.
+  * [`useToolCallStatus`](?path=/docs/hooks-usetoolcallstatus--docs) — derives status + mode + approval requirements for a single tool call.
+  * [`useAgentSession`](?path=/docs/hooks-useagentsession--docs) — wraps create / resume / list against any session storage adapter.
+
+## Installation (consuming app)
+
+```bash
+pnpm add @steerable/agent-ui @steerable/agent-protocol react react-dom
+```
+
+If you use Tailwind v3, register the preset:
+
+```ts
+// tailwind.config.ts
+import preset from '@steerable/agent-ui/tailwind-preset';
+export default {
+  presets: [preset],
+  content: [
+    './src/**/*.{ts,tsx}',
+    './node_modules/@steerable/agent-ui/dist/**/*.{js,mjs}',
+  ],
+};
+```
+
+For Tailwind v4 callers, mirror the design tokens with `@theme` (see `apps/web/src/app/globals.css` in `deeppath` for an in-tree example, and `packages/agent-ui/ts/.storybook/preview.css` here for a minimal copy you can paste).
+
+## Design philosophy
+
+1. **Headless first.** Every component takes a render prop or accepts `children` for the parts a real app wants to customise (markdown rendering, mention chips, search-source pills, …). Defaults are dumb on purpose so you don't end up forking the whole component to swap one row.
+2. **One token vocabulary.** All colors, radii, and animations come from `--agent-*` variables. Themes ship as CSS overrides, never as React props.
+3. **Transport-agnostic hooks.** `useChatStream` and friends never speak HTTP or know which provider serves the events — they call into a transport you pass in. This is what lets `deeppath/apps/web` and `deeppath-agent` share the same chat surface while one talks to FastAPI/SSE and the other talks to the embedded sidecar over IPC.
+4. **Mirror the framework spec.** `ChatMessage`, `ToolCall`, `ToolResult`, `SSEEvent`, `AgentSession` are imported from `@steerable/agent-protocol`, which is generated from the JSON schemas in `spec/`. The TS and Py worlds stay lock-step.
+
+## Working with this Storybook locally
+
+```bash
+cd packages/agent-ui/ts
+pnpm storybook        # http://localhost:6006
+pnpm storybook:build  # static bundle in storybook-static/
+```
+
+To regenerate visual snapshots (Phase 6, Playwright VRT):
+
+```bash
+pnpm storybook:vrt --update-snapshots
+```
+
+To run the headless mount + a11y test suite:
+
+```bash
+pnpm storybook:test   # expects pnpm storybook to be running on :6006
+```

package/src/components/ChatPanel.stories.tsx

@@ -0,0 +1,173 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useState } from 'react';
+import type { ChatMessage } from '@steerable/agent-protocol';
+import { ChatPanel } from './ChatPanel.js';
+
+const meta: Meta<typeof ChatPanel> = {
+  title: 'Components/ChatPanel',
+  component: ChatPanel,
+  parameters: {
+    layout: 'fullscreen',
+    actions: { argTypesRegex: '^on[A-Z].*' },
+    docs: {
+      description: {
+        component:
+          'Foundational orchestration shell. Renders a `MessageList` plus a minimal input row and a stop button. Production callers typically wrap it with their own header/composer and only feed in `messages` + `onSubmit`.',
+      },
+    },
+  },
+  args: {
+    onSubmit: () => {},
+    inputPlaceholder: 'Send a message…',
+  },
+  decorators: [
+    (Story) => (
+      <div className="h-[640px] w-full max-w-3xl border border-agent-border bg-agent-canvas">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof ChatPanel>;
+
+const NOW = '2026-05-15T00:00:00Z';
+
+const sampleMessages: ChatMessage[] = [
+  {
+    id: 'm-1',
+    role: 'user',
+    content: 'Plan a 3-day trip to Tokyo for a first-time visitor.',
+    createdAt: NOW,
+  },
+  {
+    id: 'm-2',
+    role: 'assistant',
+    content:
+      "Sure — here's a balanced 3-day plan covering culture, food and a half-day trip outside the city. I'll list each day with morning/afternoon/evening blocks.",
+    createdAt: NOW,
+  },
+  {
+    id: 'm-3',
+    role: 'user',
+    content: 'Great. Also include a vegetarian dinner each night.',
+    createdAt: NOW,
+  },
+];
+
+export const Empty: Story = {
+  args: {
+    messages: [],
+    emptyState: (
+      <div className="m-auto max-w-sm text-center text-sm text-agent-muted-foreground">
+        <p className="font-medium text-agent-foreground">Start a new conversation</p>
+        <p className="mt-1">Ask anything — I'll plan, search and call tools as needed.</p>
+      </div>
+    ),
+  },
+};
+
+export const WithMessages: Story = {
+  args: {
+    messages: sampleMessages,
+  },
+};
+
+export const Streaming: Story = {
+  args: {
+    messages: [
+      ...sampleMessages,
+      {
+        id: 'm-4',
+        role: 'assistant',
+        content: "Day 1 — Asakusa & Akihabara. Morning: visit Sensō-ji",
+        createdAt: NOW,
+      },
+    ],
+    isStreaming: true,
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    messages: sampleMessages,
+    disabled: true,
+    inputPlaceholder: 'Loading conversation…',
+  },
+};
+
+export const WithToolCalls: Story = {
+  args: {
+    messages: [
+      sampleMessages[0],
+      {
+        id: 'm-tc',
+        role: 'assistant',
+        content: 'Looking up current restaurant options in Tokyo for you.',
+        createdAt: NOW,
+        toolCalls: [
+          {
+            id: 'call-1',
+            name: 'web_search',
+            arguments: { query: 'best vegetarian restaurants Shibuya 2026' },
+          },
+        ],
+        toolResult: {
+          success: true,
+          message: 'Found 2 results.',
+          data: {
+            hits: [
+              { title: 'T\u2019s Tantan (Shibuya)', url: 'https://example.com' },
+              { title: 'AIN SOPH. Soar', url: 'https://example.com' },
+            ],
+          },
+        },
+      },
+    ],
+  },
+};
+
+/**
+ * Demonstrates the full controlled pattern: parent owns the message list,
+ * appends a new turn on submit, and toggles `isStreaming` while the assistant
+ * is "responding". Useful for sandbox-testing custom renderers.
+ */
+export const Interactive: Story = {
+  args: {
+    messages: sampleMessages,
+  },
+  render: (args) => {
+    const InteractiveChat = () => {
+      const [messages, setMessages] = useState<ChatMessage[]>(args.messages);
+      const [streaming, setStreaming] = useState(false);
+
+      return (
+        <ChatPanel
+          {...args}
+          messages={messages}
+          isStreaming={streaming}
+          onSubmit={async ({ content }) => {
+            setMessages((prev) => [
+              ...prev,
+              { id: `u-${prev.length}`, role: 'user', content, createdAt: new Date().toISOString() },
+            ]);
+            setStreaming(true);
+            await new Promise((r) => setTimeout(r, 600));
+            setMessages((prev) => [
+              ...prev,
+              {
+                id: `a-${prev.length}`,
+                role: 'assistant',
+                content: `Echo: ${content}`,
+                createdAt: new Date().toISOString(),
+              },
+            ]);
+            setStreaming(false);
+          }}
+        />
+      );
+    };
+    return <InteractiveChat />;
+  },
+};

package/src/components/ChatPanel.tsx

@@ -0,0 +1,188 @@
+/**
+ * `ChatPanel` — the foundational orchestration shell.
+ *
+ * Composes `MessageList` + a minimal input row + a stop button. The component
+ * is intentionally minimal so consumers can layer on the production-grade
+ * extras (model selector, tool toggles, mention picker, slash commands, file
+ * upload, automation alerts, share-image button, multi-tab agent switcher,
+ * orchestration sidebar) without having to fork the chat itself.
+ *
+ * Production callers in `deeppath/apps/web` will build their fancier
+ * `<ChatHeader />` and `<ChatInput />` separately and feed `ChatPanel` only
+ * the `messages` + `onSubmit` props — the rest is rendered around it.
+ */
+
+import { useCallback, useState } from 'react';
+import type { ChatMessage, ToolCall, ToolResult } from '@steerable/agent-protocol';
+import { MessageList, type MessageRendererProps } from './MessageList.js';
+import { ToolCallRenderer } from './ToolCallRenderer.js';
+import { cn } from './cn.js';
+
+export interface ChatPanelProps {
+  messages: ChatMessage[];
+  isStreaming?: boolean;
+  /**
+   * Called when the user submits the input. Receives the trimmed string.
+   * The parent is responsible for calling `useChatStream().sendUserMessage`.
+   */
+  onSubmit: (input: { content: string }) => void | Promise<void>;
+  onCancel?: () => void;
+  className?: string;
+  inputPlaceholder?: string;
+  /** Slot rendered above the message list (header, agent picker, …). */
+  header?: React.ReactNode;
+  /**
+   * Tool-call renderer. Default uses the framework's `ToolCallRenderer`;
+   * pass `() => null` to suppress, or your own component to inject a
+   * domain-specific renderer (CIFLog cards, SQL query previews, …).
+   */
+  renderToolCall?: (call: ToolCall, result?: ToolResult) => React.ReactNode;
+  /** Empty-state slot for the message list. */
+  emptyState?: React.ReactNode;
+  /** Disable the input (e.g. during initial chat load). */
+  disabled?: boolean;
+}
+
+function defaultRenderToolCall(call: ToolCall, result?: ToolResult) {
+  return <ToolCallRenderer key={call.id} call={call} result={result} />;
+}
+
+export function ChatPanel(props: ChatPanelProps) {
+  const {
+    messages,
+    isStreaming = false,
+    onSubmit,
+    onCancel,
+    className,
+    inputPlaceholder = 'Send a message…',
+    header,
+    renderToolCall = defaultRenderToolCall,
+    emptyState,
+    disabled = false,
+  } = props;
+  const [draft, setDraft] = useState('');
+
+  const handleSubmit = useCallback(
+    async (e?: React.FormEvent) => {
+      e?.preventDefault();
+      const trimmed = draft.trim();
+      if (!trimmed || disabled) return;
+      setDraft('');
+      await onSubmit({ content: trimmed });
+    },
+    [draft, disabled, onSubmit],
+  );
+
+  const renderMessage = useCallback(
+    (rendererProps: MessageRendererProps) => {
+      const { message, isLastAssistant, isStreaming: streaming } = rendererProps;
+      const isAssistant = message.role === 'assistant';
+      return (
+        <div
+          key={message.id ?? rendererProps.index}
+          data-role={message.role}
+          className={cn(
+            'flex w-full',
+            isAssistant ? 'justify-start' : 'justify-end',
+          )}
+        >
+          <div
+            className={cn(
+              'flex max-w-[80%] flex-col gap-2',
+              isAssistant ? 'items-start' : 'items-end',
+            )}
+          >
+            <div
+              className={cn(
+                'rounded-agent-md border px-3 py-2 text-sm leading-relaxed',
+                isAssistant
+                  ? 'border-agent-border bg-agent-muted text-agent-foreground'
+                  : 'border-transparent bg-agent-accent text-agent-accent-foreground',
+              )}
+            >
+              <div className="whitespace-pre-wrap">
+                {message.content || (isLastAssistant && streaming ? '…' : '')}
+              </div>
+              {isLastAssistant && streaming ? (
+                <span
+                  aria-hidden
+                  className="ml-0.5 inline-block h-3 w-1.5 align-baseline bg-agent-foreground animate-agent-cursor-blink"
+                />
+              ) : null}
+            </div>
+            {Array.isArray(message.toolCalls) && message.toolCalls.length > 0 ? (
+              <div className="flex w-full flex-col gap-1.5">
+                {message.toolCalls.map((call) =>
+                  renderToolCall(
+                    call,
+                    // The hook attaches a single `toolResult` to the message;
+                    // production callers that want per-call results should
+                    // override `renderToolCall` and look them up themselves.
+                    message.toolResult,
+                  ),
+                )}
+              </div>
+            ) : null}
+          </div>
+        </div>
+      );
+    },
+    [renderToolCall],
+  );
+
+  return (
+    <div
+      className={cn(
+        'flex h-full w-full flex-col bg-agent-canvas text-agent-foreground',
+        className,
+      )}
+    >
+      {header}
+      <div className="flex-1 overflow-hidden">
+        <MessageList
+          messages={messages}
+          isStreaming={isStreaming}
+          renderMessage={renderMessage}
+          emptyState={emptyState}
+        />
+      </div>
+      <form
+        className="flex items-center gap-2 border-t border-agent-border bg-agent-canvas px-3 py-2"
+        onSubmit={handleSubmit}
+      >
+        <input
+          type="text"
+          value={draft}
+          onChange={(e) => setDraft(e.target.value)}
+          placeholder={inputPlaceholder}
+          disabled={disabled}
+          className={cn(
+            'flex-1 rounded-agent-md border border-agent-border bg-agent-canvas px-3 py-2 text-sm text-agent-foreground placeholder:text-agent-muted-foreground',
+            'focus:border-agent-accent focus:outline-none focus:ring-1 focus:ring-agent-accent',
+            disabled && 'opacity-50',
+          )}
+        />
+        {isStreaming && onCancel ? (
+          <button
+            type="button"
+            onClick={onCancel}
+            className="rounded-agent-md border border-agent-border px-3 py-2 text-sm text-agent-foreground hover:bg-agent-muted"
+          >
+            Stop
+          </button>
+        ) : (
+          <button
+            type="submit"
+            disabled={disabled || !draft.trim()}
+            className={cn(
+              'rounded-agent-md bg-agent-accent px-3 py-2 text-sm font-medium text-agent-accent-foreground',
+              (disabled || !draft.trim()) && 'opacity-50',
+            )}
+          >
+            Send
+          </button>
+        )}
+      </form>
+    </div>
+  );
+}

package/src/components/MessageList.stories.tsx

@@ -0,0 +1,112 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import type { ChatMessage } from '@steerable/agent-protocol';
+import { MessageList } from './MessageList.js';
+
+const meta: Meta<typeof MessageList> = {
+  title: 'Components/MessageList',
+  component: MessageList,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Headless message list with auto-scroll-to-bottom. Pass a `renderMessage` prop to swap in your own bubble. The default renderer just shows role + content and is meant for sandbox / debugging only.',
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="h-[480px] w-[640px] border border-agent-border bg-agent-canvas">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof MessageList>;
+
+const NOW = '2026-05-15T00:00:00Z';
+
+const baseMessages: ChatMessage[] = [
+  { id: '1', role: 'user', content: 'Hi! What can you help me with?', createdAt: NOW },
+  {
+    id: '2',
+    role: 'assistant',
+    content:
+      'I can plan trips, draft emails, query your knowledge base and run safe shell commands. What would you like to start with?',
+    createdAt: NOW,
+  },
+  { id: '3', role: 'user', content: 'Plan a 2-day weekend in Kyoto.', createdAt: NOW },
+  {
+    id: '4',
+    role: 'assistant',
+    content:
+      "Sure — Day 1: Fushimi Inari at sunrise, then Gion in the afternoon. Day 2: Arashiyama bamboo grove and a kaiseki dinner. I'll add restaurant picks next.",
+    createdAt: NOW,
+  },
+];
+
+export const Default: Story = {
+  args: {
+    messages: baseMessages,
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    messages: [],
+  },
+};
+
+export const EmptyWithCustomState: Story = {
+  args: {
+    messages: [],
+    emptyState: (
+      <div className="m-auto max-w-xs text-center text-sm text-agent-muted-foreground">
+        <p className="font-medium text-agent-foreground">Nothing to show yet</p>
+        <p className="mt-1">Send your first message to start a conversation.</p>
+      </div>
+    ),
+  },
+};
+
+export const Streaming: Story = {
+  args: {
+    messages: [
+      ...baseMessages,
+      {
+        id: '5',
+        role: 'assistant',
+        content: "Day 2 — Morning: rent a bike near Arashiyama station and",
+        createdAt: NOW,
+      },
+    ],
+    isStreaming: true,
+  },
+};
+
+export const StreamingEmptyAssistant: Story = {
+  args: {
+    messages: [
+      ...baseMessages,
+      { id: '6', role: 'assistant', content: '', createdAt: NOW },
+    ],
+    isStreaming: true,
+  },
+};
+
+export const LongConversation: Story = {
+  args: {
+    messages: Array.from({ length: 30 }, (_, i): ChatMessage => ({
+      id: `m-${i}`,
+      role: i % 2 === 0 ? 'user' : 'assistant',
+      content:
+        i % 2 === 0
+          ? `User question #${i / 2 + 1}: tell me about topic ${i}.`
+          : `Assistant answer to question #${(i - 1) / 2 + 1}. ` +
+            'This response wraps across multiple lines so we exercise the auto-scroll behaviour and verify the bubble shape under longer content.',
+      createdAt: NOW,
+    })),
+  },
+};

package/src/components/MessageList.test.tsx

@@ -0,0 +1,57 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import type { ChatMessage } from '@steerable/agent-protocol';
+import { MessageList } from './MessageList';
+
+const baseMessages: ChatMessage[] = [
+  {
+    id: 'u1',
+    role: 'user',
+    content: 'Hi there!',
+    createdAt: new Date('2025-01-01T00:00:00Z').toISOString(),
+  },
+  {
+    id: 'a1',
+    role: 'assistant',
+    content: 'Hello! How can I help?',
+    createdAt: new Date('2025-01-01T00:00:01Z').toISOString(),
+  },
+];
+
+describe('MessageList', () => {
+  it('renders each message with the role data-attribute', () => {
+    render(<MessageList messages={baseMessages} />);
+    expect(screen.getByText('Hi there!')).toBeTruthy();
+    expect(screen.getByText('Hello! How can I help?')).toBeTruthy();
+    const roles = Array.from(
+      document.querySelectorAll('[data-role]'),
+    ).map((el) => el.getAttribute('data-role'));
+    expect(roles).toEqual(['user', 'assistant']);
+  });
+
+  it('renders the empty state slot when no messages and one is provided', () => {
+    render(
+      <MessageList
+        messages={[]}
+        emptyState={<div>start a conversation</div>}
+      />,
+    );
+    expect(screen.getByText('start a conversation')).toBeTruthy();
+  });
+
+  it('uses the supplied renderMessage when provided', () => {
+    render(
+      <MessageList
+        messages={baseMessages}
+        renderMessage={({ message }) => (
+          <span data-testid="custom">CUSTOM:{message.content}</span>
+        )}
+      />,
+    );
+    const items = screen.getAllByTestId('custom');
+    expect(items.map((el) => el.textContent)).toEqual([
+      'CUSTOM:Hi there!',
+      'CUSTOM:Hello! How can I help?',
+    ]);
+  });
+});