@steerable/agent-ui 0.2.0

package/src/components/MessageList.tsx

@@ -0,0 +1,144 @@
+/**
+ * `MessageList` — render a list of `ChatMessage`s with auto-scroll-to-bottom
+ * behaviour. The component is intentionally **headless**: it knows the list
+ * shape but lets the caller render every individual bubble.
+ *
+ * Why a render prop instead of a fixed bubble component? Because every
+ * consumer wants to layer additional UI (markdown, search-source pills,
+ * mention chips, action renderers) onto the assistant message and we don't
+ * want to ship every pluggable variant from `deeppath/apps/web` here.
+ */
+
+import { useEffect, useMemo, useRef } from 'react';
+import type { ChatMessage } from '@steerable/agent-protocol';
+import { cn } from './cn.js';
+
+export interface MessageRendererProps {
+  message: ChatMessage;
+  index: number;
+  isLastAssistant: boolean;
+  isStreaming: boolean;
+}
+
+export interface MessageListProps {
+  messages: ChatMessage[];
+  isStreaming?: boolean;
+  className?: string;
+  /**
+   * Bubble renderer. If omitted, `MessageList` falls back to the built-in
+   * `DefaultMessageBubble` which just renders role + content.
+   */
+  renderMessage?: (props: MessageRendererProps) => React.ReactNode;
+  /**
+   * If true (default), scrolls the container to the bottom every time the
+   * message list grows or the last assistant message gets new content.
+   */
+  autoScroll?: boolean;
+  /**
+   * Slot rendered above the first message — typically a "start of conversation"
+   * marker or a system prompt summary.
+   */
+  header?: React.ReactNode;
+  /**
+   * Slot rendered when `messages` is empty. Production callers usually drop
+   * an `<EmptyChat />` here.
+   */
+  emptyState?: React.ReactNode;
+}
+
+function DefaultMessageBubble({ message, isLastAssistant, isStreaming }: MessageRendererProps) {
+  const isAssistant = message.role === 'assistant';
+  return (
+    <div
+      data-role={message.role}
+      className={cn(
+        'flex w-full',
+        isAssistant ? 'justify-start' : 'justify-end',
+      )}
+    >
+      <div
+        className={cn(
+          'max-w-[80%] 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 && isStreaming ? '…' : '')}</div>
+        {isLastAssistant && isStreaming ? (
+          <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>
+    </div>
+  );
+}
+
+export function MessageList(props: MessageListProps) {
+  const {
+    messages,
+    isStreaming = false,
+    className,
+    renderMessage,
+    autoScroll = true,
+    header,
+    emptyState,
+  } = props;
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const lastAssistantIndex = useMemo(() => {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (messages[i].role === 'assistant') return i;
+    }
+    return -1;
+  }, [messages]);
+
+  // Scroll to bottom on growth or when the streaming assistant gets longer.
+  const lastAssistantContent =
+    lastAssistantIndex >= 0 ? messages[lastAssistantIndex].content : '';
+
+  useEffect(() => {
+    if (!autoScroll) return;
+    const el = containerRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+  }, [autoScroll, messages.length, lastAssistantContent]);
+
+  const Renderer = renderMessage ?? DefaultMessageBubble;
+
+  return (
+    <div
+      ref={containerRef}
+      className={cn(
+        'flex h-full w-full flex-col gap-3 overflow-y-auto bg-agent-canvas px-4 py-3',
+        'focus:outline-none focus-visible:ring-2 focus-visible:ring-agent-accent',
+        className,
+      )}
+      role="log"
+      aria-live="polite"
+      aria-label="Conversation"
+      tabIndex={0}
+    >
+      {header}
+      {messages.length === 0 ? (
+        emptyState ?? (
+          <div className="m-auto text-sm text-agent-muted-foreground">
+            No messages yet.
+          </div>
+        )
+      ) : (
+        messages.map((message, index) => (
+          <Renderer
+            key={message.id ?? index}
+            message={message}
+            index={index}
+            isLastAssistant={index === lastAssistantIndex}
+            isStreaming={isStreaming}
+          />
+        ))
+      )}
+    </div>
+  );
+}

package/src/components/OrchestrationPlanCard.stories.tsx

@@ -0,0 +1,98 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { OrchestrationPlanCard, type OrchestrationStep } from './OrchestrationPlanCard.js';
+
+const meta: Meta<typeof OrchestrationPlanCard> = {
+  title: 'Components/OrchestrationPlanCard',
+  component: OrchestrationPlanCard,
+  parameters: {
+    layout: 'centered',
+    actions: { argTypesRegex: '^on[A-Z].*' },
+    docs: {
+      description: {
+        component:
+          'Read-only multi-step plan with per-step status icons and a header summary. Status values are `pending` / `running` / `done` / `error` / `skipped`. Pass `onStepClick` to make rows interactive (used in production to open a step\u2019s trace timeline in a side panel).',
+      },
+    },
+  },
+  args: {
+    title: 'Plan',
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[480px]">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof OrchestrationPlanCard>;
+
+const steps: OrchestrationStep[] = [
+  { id: 's1', title: 'Parse user request', status: 'done', kind: 'decision' },
+  {
+    id: 's2',
+    title: 'Look up matching projects',
+    status: 'done',
+    kind: 'tool',
+    description: 'web_search → project_index',
+  },
+  {
+    id: 's3',
+    title: 'Draft proposal outline',
+    status: 'running',
+    kind: 'agent:writer',
+  },
+  { id: 's4', title: 'Estimate budget', status: 'pending', kind: 'tool' },
+  { id: 's5', title: 'Send for review', status: 'pending', kind: 'wait' },
+];
+
+export const InProgress: Story = {
+  args: {
+    steps,
+  },
+};
+
+export const AllDone: Story = {
+  args: {
+    steps: steps.map((s) => ({ ...s, status: 'done' as const, finishedAt: '15:32' })),
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    steps: [
+      ...steps.slice(0, 2),
+      {
+        ...steps[2],
+        status: 'error',
+        description: 'writer_agent rejected: missing required tone parameter',
+      },
+      ...steps.slice(3),
+    ],
+  },
+};
+
+export const SkippedBranch: Story = {
+  args: {
+    steps: [
+      ...steps.slice(0, 3).map((s) => ({ ...s, status: 'done' as const })),
+      { ...steps[3], status: 'skipped' as const, description: 'no budget needed' },
+      { ...steps[4], status: 'done' as const, finishedAt: '15:55' },
+    ],
+  },
+};
+
+export const Empty: Story = {
+  args: {
+    steps: [],
+  },
+};
+
+export const Interactive: Story = {
+  args: {
+    steps,
+    onStepClick: () => {},
+  },
+};

package/src/components/OrchestrationPlanCard.test.tsx

@@ -0,0 +1,34 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  OrchestrationPlanCard,
+  type OrchestrationStep,
+} from './OrchestrationPlanCard';
+
+const steps: OrchestrationStep[] = [
+  { id: '1', title: 'Plan trip', status: 'done', kind: 'agent:planner' },
+  { id: '2', title: 'Book flights', status: 'running', kind: 'tool' },
+  { id: '3', title: 'Reserve hotel', status: 'pending' },
+  { id: '4', title: 'Email itinerary', status: 'error', description: 'SMTP timeout' },
+];
+
+describe('OrchestrationPlanCard', () => {
+  it('renders the right summary count + each step with status data attribute', () => {
+    render(<OrchestrationPlanCard steps={steps} />);
+    expect(screen.getByText('1/4')).toBeTruthy();
+    expect(screen.getByText('1 error')).toBeTruthy();
+    expect(screen.getByText('Plan trip')).toBeTruthy();
+    expect(screen.getByText('SMTP timeout')).toBeTruthy();
+    const errorRow = screen.getByText('Email itinerary').closest('[data-status]');
+    expect(errorRow?.getAttribute('data-status')).toBe('error');
+  });
+
+  it('makes rows clickable when onStepClick is provided and reports the right step', () => {
+    const onStepClick = vi.fn();
+    render(<OrchestrationPlanCard steps={steps} onStepClick={onStepClick} />);
+    fireEvent.click(screen.getByText('Book flights'));
+    expect(onStepClick).toHaveBeenCalledWith(
+      expect.objectContaining({ id: '2', status: 'running' }),
+    );
+  });
+});

package/src/components/OrchestrationPlanCard.tsx

@@ -0,0 +1,159 @@
+/**
+ * `OrchestrationPlanCard` — render a multi-step plan with per-step status.
+ *
+ * Maps to the `orchestration` SSE event family: the harness emits a structured
+ * plan up-front and updates step status as execution progresses. The card is
+ * intentionally read-only; consumers that want inline edit (`deeppath/apps/web`'s
+ * "PlanSteps") should compose their own editor using `useChatStream`'s
+ * `onUnknownEvent` hook to track plan events and feed updated steps in here.
+ */
+
+import { useMemo } from 'react';
+import { cn } from './cn.js';
+
+export type OrchestrationStepStatus =
+  | 'pending'
+  | 'running'
+  | 'done'
+  | 'error'
+  | 'skipped';
+
+export interface OrchestrationStep {
+  id: string;
+  title: string;
+  description?: string;
+  status: OrchestrationStepStatus;
+  /** Optional badge (`tool`, `wait`, `decision`, `agent:<name>`, …). */
+  kind?: string;
+  /** Optional ISO datetime when the step finished, used for the right column. */
+  finishedAt?: string;
+}
+
+export interface OrchestrationPlanCardProps {
+  title?: string;
+  steps: OrchestrationStep[];
+  className?: string;
+  /**
+   * Optional click handler — useful when you want to open a step's trace
+   * timeline in a side panel. Receives the step that was clicked.
+   */
+  onStepClick?: (step: OrchestrationStep) => void;
+}
+
+const statusToIcon: Record<OrchestrationStepStatus, string> = {
+  pending: '○',
+  running: '◐',
+  done: '●',
+  error: '✕',
+  skipped: '—',
+};
+
+const statusToColor: Record<OrchestrationStepStatus, string> = {
+  pending: 'text-agent-muted-foreground',
+  running: 'text-agent-accent',
+  done: 'text-agent-tool-read',
+  error: 'text-agent-destructive',
+  skipped: 'text-agent-muted-foreground line-through',
+};
+
+export function OrchestrationPlanCard(props: OrchestrationPlanCardProps) {
+  const { title = 'Plan', steps, className, onStepClick } = props;
+
+  const summary = useMemo(() => {
+    const total = steps.length;
+    const done = steps.filter((s) => s.status === 'done').length;
+    const errored = steps.filter((s) => s.status === 'error').length;
+    return { total, done, errored };
+  }, [steps]);
+
+  return (
+    <div
+      className={cn(
+        'rounded-agent-lg border border-agent-border bg-agent-canvas p-4',
+        className,
+      )}
+      data-testid="orchestration-plan-card"
+    >
+      <div className="mb-3 flex items-center justify-between">
+        <div className="flex items-center gap-2">
+          <span className="text-sm font-semibold text-agent-foreground">
+            {title}
+          </span>
+          <span className="rounded-full border border-agent-border px-2 py-0.5 text-[10px] uppercase tracking-wide text-agent-muted-foreground">
+            {summary.done}/{summary.total}
+          </span>
+        </div>
+        {summary.errored > 0 ? (
+          <span className="text-[11px] font-medium text-agent-destructive">
+            {summary.errored} error{summary.errored === 1 ? '' : 's'}
+          </span>
+        ) : null}
+      </div>
+      <ol className="space-y-1.5">
+        {steps.map((step, idx) => {
+          const interactive = Boolean(onStepClick);
+          const Tag: 'button' | 'div' = interactive ? 'button' : 'div';
+          return (
+            <li key={step.id}>
+              <Tag
+                {...(interactive
+                  ? {
+                      type: 'button' as const,
+                      onClick: () => onStepClick?.(step),
+                    }
+                  : {})}
+                className={cn(
+                  'flex w-full items-start gap-2 rounded-agent-sm px-2 py-1.5 text-left',
+                  interactive
+                    ? 'transition-colors hover:bg-agent-muted'
+                    : '',
+                )}
+                data-status={step.status}
+              >
+                <span
+                  className={cn(
+                    'mt-0.5 select-none font-mono text-base leading-none',
+                    statusToColor[step.status],
+                  )}
+                  aria-hidden
+                >
+                  {statusToIcon[step.status]}
+                </span>
+                <div className="min-w-0 flex-1">
+                  <div className="flex items-center gap-2">
+                    <span className="truncate text-xs font-mono text-agent-muted-foreground">
+                      {(idx + 1).toString().padStart(2, '0')}
+                    </span>
+                    <span
+                      className={cn(
+                        'truncate text-sm font-medium',
+                        statusToColor[step.status],
+                      )}
+                    >
+                      {step.title}
+                    </span>
+                    {step.kind ? (
+                      <span className="shrink-0 rounded-full border border-agent-border bg-agent-muted px-1.5 py-0.5 text-[10px] font-semibold uppercase tracking-wide text-agent-muted-foreground">
+                        {step.kind}
+                      </span>
+                    ) : null}
+                  </div>
+                  {step.description ? (
+                    <p className="mt-0.5 text-xs text-agent-muted-foreground">
+                      {step.description}
+                    </p>
+                  ) : null}
+                </div>
+                {step.finishedAt ? (
+                  <span className="shrink-0 text-[10px] text-agent-muted-foreground">
+                    {step.finishedAt}
+                  </span>
+                ) : null}
+              </Tag>
+            </li>
+          );
+        })}
+      </ol>
+    </div>
+  );
+}

package/src/components/SSEStreamView.stories.tsx

@@ -0,0 +1,99 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import type { SSEEvent } from '@steerable/agent-protocol';
+import { SSEStreamView } from './SSEStreamView.js';
+
+const meta: Meta<typeof SSEStreamView> = {
+  title: 'Components/SSEStreamView',
+  component: SSEStreamView,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Append-only debug view of the raw SSE event log. Used in production for the "Trace" tab in `deeppath/apps/web` and as a dev console inside `deeppath-agent`. Toggle `verbose` to inspect full JSON payloads, or pass `filterTypes` to narrow to a single event family.',
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="h-[400px] w-[640px]">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof SSEStreamView>;
+
+const events: SSEEvent[] = [
+  { type: 'agent', agentId: 'planner', model: 'gpt-4o-mini' },
+  {
+    type: 'orchestration',
+    orchestrationGroupId: 'plan-1',
+    payload: { phase: 'plan_started' },
+  },
+  { type: 'content', content: 'Looking up the latest project status…' },
+  {
+    type: 'tool_call',
+    payload: {
+      callId: 'call_1',
+      name: 'project_search',
+      arguments: { query: 'Q4 roadmap', limit: 5 },
+    },
+  },
+  {
+    type: 'tool_result',
+    payload: { callId: 'call_1', name: 'project_search', status: 'success', count: 3 },
+  },
+  { type: 'content', content: 'Found 3 active projects. Drafting summary…' },
+  { type: 'loader-hint', hint: 'Composing response…' },
+  { type: 'content', content: 'Here are the highlights:\n1. Project Alpha\n2. Project Beta' },
+  { type: 'done' },
+];
+
+export const Empty: Story = {
+  args: {
+    events: [],
+  },
+};
+
+export const Default: Story = {
+  args: {
+    events,
+  },
+};
+
+export const Verbose: Story = {
+  args: {
+    events,
+    verbose: true,
+  },
+};
+
+export const FilteredToolEvents: Story = {
+  args: {
+    events,
+    filterTypes: ['tool_call', 'tool_result'],
+  },
+};
+
+export const ErrorAndBudget: Story = {
+  args: {
+    events: [
+      ...events.slice(0, 5),
+      { type: 'budget_exhausted', message: 'token budget reached after 3.2k tokens' },
+      { type: 'error', message: 'tool_dispatch failed: timeout after 30s' },
+    ],
+  },
+};
+
+export const HighVolume: Story = {
+  args: {
+    events: Array.from({ length: 200 }, (_, i): SSEEvent => {
+      if (i % 13 === 0) return { type: 'tool_call', payload: { callId: `c${i}`, name: 'noop' } };
+      if (i % 13 === 6) return { type: 'tool_result', payload: { callId: `c${i - 6}`, status: 'success' } };
+      return { type: 'content', content: `chunk ${i}: ` + 'lorem ipsum dolor sit amet '.repeat(2) };
+    }),
+  },
+};

package/src/components/SSEStreamView.test.tsx

@@ -0,0 +1,42 @@
+import { render, screen } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import type { SSEEvent } from '@steerable/agent-protocol';
+import { SSEStreamView } from './SSEStreamView';
+
+const events: SSEEvent[] = [
+  { type: 'content', content: 'Hello world' },
+  {
+    type: 'tool_call',
+    payload: { id: 'c1', name: 'get_weather', arguments: { city: 'SF' } },
+  },
+  { type: 'tool_result', payload: { success: true } },
+  { type: 'done' },
+];
+
+describe('SSEStreamView', () => {
+  it('renders one row per event with the type label uppercase', () => {
+    render(<SSEStreamView events={events} />);
+    expect(screen.getByText('content')).toBeTruthy();
+    expect(screen.getByText('tool_call')).toBeTruthy();
+    expect(screen.getByText('tool_result')).toBeTruthy();
+    expect(screen.getByText('done')).toBeTruthy();
+  });
+
+  it('filters by type when filterTypes is provided', () => {
+    render(<SSEStreamView events={events} filterTypes={['tool_call', 'tool_result']} />);
+    expect(screen.queryByText('content')).toBeNull();
+    expect(screen.queryByText('done')).toBeNull();
+    expect(screen.getByText('tool_call')).toBeTruthy();
+    expect(screen.getByText('tool_result')).toBeTruthy();
+  });
+
+  it('renders the empty state when there are no events', () => {
+    render(<SSEStreamView events={[]} emptyState={<span>(idle)</span>} />);
+    expect(screen.getByText('(idle)')).toBeTruthy();
+  });
+
+  it('renders pretty-printed JSON in verbose mode', () => {
+    render(<SSEStreamView events={events.slice(1, 2)} verbose />);
+    expect(screen.getByText(/"name": "get_weather"/)).toBeTruthy();
+  });
+});