@steerable/agent-ui 0.2.0

package/src/components/SSEStreamView.tsx

@@ -0,0 +1,155 @@
+/**
+ * `SSEStreamView` — debug / power-user view that prints the raw SSE event log.
+ *
+ * Used in two production contexts today:
+ *   1. The "Trace" tab in `deeppath/apps/web` admin tooling.
+ *   2. The mockCflog log window in `deeppath-agent`, where it doubles as a
+ *      dev console for the Electron app.
+ *
+ * The component is intentionally append-only; consumers feed it events via the
+ * `events` prop and it auto-scrolls to keep the latest in view.
+ */
+
+import { useEffect, useMemo, useRef } from 'react';
+import type { SSEEvent } from '@steerable/agent-protocol';
+import { cn } from './cn.js';
+
+export interface SSEStreamViewProps {
+  events: SSEEvent[];
+  className?: string;
+  /** Show full JSON payloads instead of a one-line summary. */
+  verbose?: boolean;
+  autoScroll?: boolean;
+  /**
+   * Optional filter; only events whose `type` is in the set are rendered.
+   * Useful for production debugging where you only care about, e.g.,
+   * `tool_call` + `tool_result` chains.
+   */
+  filterTypes?: SSEEvent['type'][];
+  emptyState?: React.ReactNode;
+  maxRows?: number;
+}
+
+const typeColor: Record<SSEEvent['type'], string> = {
+  content: 'text-agent-foreground',
+  error: 'text-agent-destructive',
+  agent: 'text-agent-accent',
+  orchestration: 'text-agent-tool-write',
+  'loader-hint': 'text-agent-muted-foreground',
+  keepalive: 'text-agent-muted-foreground/60',
+  done: 'text-agent-tool-read',
+  budget_exhausted: 'text-agent-destructive',
+  tool_call: 'text-agent-tool-write',
+  tool_result: 'text-agent-tool-read',
+};
+
+function summarize(event: SSEEvent): string {
+  if (event.type === 'content') {
+    const c = typeof event.content === 'string' ? event.content : '';
+    return c.length > 80 ? c.slice(0, 80) + '…' : c;
+  }
+  if (event.type === 'error' || event.type === 'budget_exhausted') {
+    return event.message ?? '';
+  }
+  if (event.type === 'tool_call' || event.type === 'tool_result') {
+    const payload = event.payload as Record<string, unknown> | undefined;
+    return payload ? JSON.stringify(payload).slice(0, 120) : '';
+  }
+  if (event.type === 'loader-hint') {
+    return event.hint ?? '';
+  }
+  if (event.type === 'orchestration') {
+    return event.orchestrationGroupId ?? '';
+  }
+  if (event.type === 'agent') {
+    return JSON.stringify(event).slice(0, 120);
+  }
+  return '';
+}
+
+export function SSEStreamView(props: SSEStreamViewProps) {
+  const {
+    events,
+    className,
+    verbose = false,
+    autoScroll = true,
+    filterTypes,
+    emptyState,
+    maxRows = 1000,
+  } = props;
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  const visible = useMemo(() => {
+    let list = filterTypes ? events.filter((e) => filterTypes.includes(e.type)) : events;
+    if (list.length > maxRows) {
+      list = list.slice(list.length - maxRows);
+    }
+    return list;
+  }, [events, filterTypes, maxRows]);
+
+  useEffect(() => {
+    if (!autoScroll) return;
+    const el = containerRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+  }, [autoScroll, visible.length]);
+
+  return (
+    <div
+      ref={containerRef}
+      className={cn(
+        'h-full overflow-y-auto rounded-agent-md border border-agent-border bg-agent-canvas font-mono text-[11px] leading-relaxed',
+        'focus:outline-none focus-visible:ring-2 focus-visible:ring-agent-accent',
+        className,
+      )}
+      role="log"
+      aria-live="polite"
+      aria-label="SSE event log"
+      tabIndex={0}
+    >
+      {visible.length === 0 ? (
+        <div className="flex h-full items-center justify-center text-agent-muted-foreground">
+          {emptyState ?? 'No events yet.'}
+        </div>
+      ) : (
+        <ul className="divide-y divide-agent-border">
+          {visible.map((event, idx) => (
+            <li
+              key={`${idx}_${event.type}`}
+              className="flex flex-col gap-0.5 px-3 py-1.5"
+            >
+              <div className="flex items-center gap-2">
+                <span
+                  className={cn(
+                    'shrink-0 font-semibold uppercase tracking-wide',
+                    typeColor[event.type],
+                  )}
+                >
+                  {event.type}
+                </span>
+                {!verbose ? (
+                  <span className="truncate text-agent-muted-foreground">
+                    {summarize(event)}
+                  </span>
+                ) : null}
+              </div>
+              {verbose ? (
+                <pre className="overflow-x-auto whitespace-pre-wrap break-words text-agent-muted-foreground">
+                  {safeStringify(event)}
+                </pre>
+              ) : null}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}

package/src/components/ToolCallRenderer.stories.tsx

@@ -0,0 +1,152 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import type { ToolCall, ToolResult } from '@steerable/agent-protocol';
+import { ToolCallRenderer } from './ToolCallRenderer.js';
+
+const meta: Meta<typeof ToolCallRenderer> = {
+  title: 'Components/ToolCallRenderer',
+  component: ToolCallRenderer,
+  parameters: {
+    layout: 'centered',
+    actions: { argTypesRegex: '^on[A-Z].*' },
+    docs: {
+      description: {
+        component:
+          'Single tool-call card. Computes its display state from `useToolCallStatus` (call + optional result + mode hint). Pass `mode="local"` and `onApprove` / `onReject` to render an approval prompt for local-execution tools.',
+      },
+    },
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-[520px]">
+        <Story />
+      </div>
+    ),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof ToolCallRenderer>;
+
+const readCall: ToolCall = {
+  id: 'call_read_1',
+  name: 'web_search',
+  arguments: { query: 'tokyo vegetarian restaurants 2026' },
+};
+
+const writeCall: ToolCall = {
+  id: 'call_write_1',
+  name: 'create_calendar_event',
+  arguments: {
+    title: 'Team retro',
+    startTime: '2026-05-20T14:00:00Z',
+    durationMinutes: 60,
+  },
+};
+
+const destructiveCall: ToolCall = {
+  id: 'call_destructive_1',
+  name: 'shell_exec',
+  arguments: { command: 'rm -rf /tmp/build-cache' },
+};
+
+const localCall: ToolCall = {
+  id: 'call_local_1',
+  name: 'cflog_open_workspace',
+  arguments: { path: '/Users/me/projects/cflog/case-2024-001' },
+};
+
+const successResult: ToolResult = {
+  success: true,
+  message: 'Found 12 results.',
+  data: {
+    hits: [
+      { title: 'T\u2019s Tantan', url: 'https://example.com/1' },
+      { title: 'AIN SOPH. Soar', url: 'https://example.com/2' },
+    ],
+  },
+};
+
+const errorResult: ToolResult = {
+  success: false,
+  error: 'TimeRangeConflict: another event already occupies 14:00–15:00 on 2026-05-20',
+};
+
+export const ReadModePending: Story = {
+  args: {
+    call: readCall,
+    mode: 'read',
+  },
+};
+
+export const ReadModeSuccess: Story = {
+  args: {
+    call: readCall,
+    result: successResult,
+    mode: 'read',
+    defaultExpanded: true,
+  },
+};
+
+export const SafeWriteRunning: Story = {
+  args: {
+    call: writeCall,
+    mode: 'safe_write',
+    runningHint: true,
+  },
+};
+
+export const SafeWriteError: Story = {
+  args: {
+    call: writeCall,
+    result: errorResult,
+    mode: 'safe_write',
+    defaultExpanded: true,
+  },
+};
+
+export const DestructivePending: Story = {
+  args: {
+    call: destructiveCall,
+    mode: 'destructive',
+    defaultExpanded: true,
+  },
+};
+
+export const LocalAwaitingApproval: Story = {
+  args: {
+    call: localCall,
+    mode: 'local',
+    onApprove: () => {},
+    onReject: () => {},
+  },
+};
+
+export const CustomRenderers: Story = {
+  args: {
+    call: readCall,
+    result: successResult,
+    mode: 'read',
+    defaultExpanded: true,
+    renderArgs: (call) => (
+      <div className="text-xs">
+        <span className="font-medium text-agent-foreground">Query:</span>{' '}
+        <span className="text-agent-muted-foreground">
+          {String((call.arguments as { query?: string }).query ?? '')}
+        </span>
+      </div>
+    ),
+    renderResult: (result) => (
+      <ul className="space-y-1 text-xs text-agent-muted-foreground">
+        {((result.data as { hits?: Array<{ title: string; url: string }> } | undefined)?.hits ?? []).map(
+          (hit) => (
+            <li key={hit.url}>
+              <a className="text-agent-accent underline" href={hit.url}>
+                {hit.title}
+              </a>
+            </li>
+          ),
+        )}
+      </ul>
+    ),
+  },
+};

package/src/components/ToolCallRenderer.test.tsx

@@ -0,0 +1,93 @@
+/**
+ * Render tests for `<ToolCallRenderer />`. We don't snapshot the whole DOM —
+ * Tailwind class strings shift any time we tweak tokens — but we assert the
+ * data-attributes (used by consumer styling overrides) and the visibility
+ * rules for the approval row + result subtree.
+ */
+
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { ToolCallRenderer } from './ToolCallRenderer';
+
+describe('ToolCallRenderer', () => {
+  it('renders pending state with collapsed args by default', () => {
+    render(
+      <ToolCallRenderer
+        call={{ id: 'c1', name: 'get_weather', arguments: { city: 'SF' } }}
+      />,
+    );
+    const card = screen.getByText('get_weather').closest('[data-status]');
+    expect(card?.getAttribute('data-status')).toBe('pending');
+    expect(card?.getAttribute('data-mode')).toBe('read');
+    // Args body is hidden until expanded.
+    expect(screen.queryByText(/"city"/)).toBeNull();
+  });
+
+  it('expands args + result on click', () => {
+    render(
+      <ToolCallRenderer
+        call={{ id: 'c1', name: 'create_event', arguments: { title: 'meeting' } }}
+        result={{ success: true, data: { id: 'e1' } }}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button'));
+    expect(screen.getByText(/"title": "meeting"/)).toBeTruthy();
+    expect(screen.getByText(/"id": "e1"/)).toBeTruthy();
+  });
+
+  it('renders done status when result.success=true', () => {
+    render(
+      <ToolCallRenderer
+        call={{ id: 'c1', name: 'create_event', arguments: {} }}
+        result={{ success: true }}
+      />,
+    );
+    const card = screen.getByText('create_event').closest('[data-status]');
+    expect(card?.getAttribute('data-status')).toBe('done');
+  });
+
+  it('renders error status and the error text in the result subtree when expanded', () => {
+    render(
+      <ToolCallRenderer
+        call={{ id: 'c1', name: 'create_event', arguments: {} }}
+        result={{ success: false, error: 'missing field' }}
+      />,
+    );
+    const card = screen.getByText('create_event').closest('[data-status]');
+    expect(card?.getAttribute('data-status')).toBe('error');
+    fireEvent.click(screen.getByRole('button'));
+    expect(screen.getByText('missing field')).toBeTruthy();
+  });
+
+  it('shows approve / reject buttons for local tools when handlers are provided', () => {
+    const onApprove = vi.fn();
+    const onReject = vi.fn();
+    render(
+      <ToolCallRenderer
+        call={{ id: 'c1', name: 'local_run_script', arguments: { cmd: 'ls' } }}
+        onApprove={onApprove}
+        onReject={onReject}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Approve' }));
+    fireEvent.click(screen.getByRole('button', { name: 'Reject' }));
+    expect(onApprove).toHaveBeenCalledWith({
+      id: 'c1',
+      name: 'local_run_script',
+      arguments: { cmd: 'ls' },
+    });
+    expect(onReject).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not show approval row once a result has arrived', () => {
+    const onApprove = vi.fn();
+    render(
+      <ToolCallRenderer
+        call={{ id: 'c1', name: 'local_run_script', arguments: { cmd: 'ls' } }}
+        result={{ success: true }}
+        onApprove={onApprove}
+      />,
+    );
+    expect(screen.queryByRole('button', { name: 'Approve' })).toBeNull();
+  });
+});

package/src/components/ToolCallRenderer.tsx

@@ -0,0 +1,213 @@
+/**
+ * `ToolCallRenderer` — display a single tool call + (optional) tool result.
+ *
+ * Renders three visual rows depending on lifecycle / mode:
+ *
+ *   ┌──────────────────────────────────────────────────┐
+ *   │ [icon] tool_name [mode-pill]              [time] │
+ *   │   args (collapsed by default)                    │
+ *   │   ── result ──                                   │
+ *   │   message + data (collapsed by default)          │
+ *   └──────────────────────────────────────────────────┘
+ *
+ * Headless body: callers can override the args / result subtree with
+ * `renderArgs` / `renderResult` if they need richer formatting (diffs, code
+ * blocks, structured cards). Default body uses pretty-printed JSON.
+ */
+
+import { useState } from 'react';
+import type { ToolCall, ToolResult } from '@steerable/agent-protocol';
+import { useToolCallStatus, type ToolCallMode } from '../hooks/useToolCallStatus.js';
+import { cn } from './cn.js';
+
+export interface ToolCallRendererProps {
+  call: ToolCall;
+  result?: ToolResult;
+  /**
+   * Optional explicit mode override. Use when the framework's `decide_tool_mode`
+   * has already classified the tool (the local `ToolRouter` ships this value
+   * alongside the call in production setups).
+   */
+  mode?: ToolCallMode;
+  runningHint?: boolean;
+  /**
+   * Approval handler. Must be supplied when rendering a `local`-mode call you
+   * want the user to confirm before execution. If omitted, the renderer falls
+   * back to the read-only "awaiting result" treatment.
+   */
+  onApprove?: (call: ToolCall) => void;
+  onReject?: (call: ToolCall) => void;
+  className?: string;
+  renderArgs?: (call: ToolCall) => React.ReactNode;
+  renderResult?: (result: ToolResult) => React.ReactNode;
+  defaultExpanded?: boolean;
+}
+
+const modeBadgeClass: Record<ToolCallMode, string> = {
+  read: 'bg-agent-tool-read/15 text-agent-tool-read border-agent-tool-read/40',
+  safe_write:
+    'bg-agent-tool-write/15 text-agent-tool-write border-agent-tool-write/40',
+  destructive:
+    'bg-agent-tool-destructive/15 text-agent-tool-destructive border-agent-tool-destructive/40',
+  local:
+    'bg-agent-accent/15 text-agent-accent border-agent-accent/40',
+  external:
+    'bg-agent-muted text-agent-muted-foreground border-agent-border',
+  ui: 'bg-agent-muted text-agent-muted-foreground border-agent-border',
+  synthetic:
+    'bg-agent-muted text-agent-muted-foreground border-agent-border',
+  unknown:
+    'bg-agent-muted text-agent-muted-foreground border-agent-border',
+};
+
+const statusDotClass: Record<string, string> = {
+  pending: 'bg-agent-muted-foreground animate-pulse',
+  running: 'bg-agent-accent animate-pulse',
+  done: 'bg-agent-tool-read',
+  error: 'bg-agent-destructive',
+};
+
+function defaultArgsRenderer(call: ToolCall) {
+  return (
+    <pre className="whitespace-pre-wrap break-words text-xs leading-relaxed text-agent-muted-foreground">
+      {safeStringify(call.arguments)}
+    </pre>
+  );
+}
+
+function defaultResultRenderer(result: ToolResult) {
+  const lines: React.ReactNode[] = [];
+  if (result.message) {
+    lines.push(
+      <div key="msg" className="text-xs text-agent-foreground">
+        {result.message}
+      </div>,
+    );
+  }
+  if (result.error) {
+    lines.push(
+      <div key="err" className="text-xs text-agent-destructive">
+        {result.error}
+      </div>,
+    );
+  }
+  if (result.data) {
+    lines.push(
+      <pre
+        key="data"
+        className="mt-1 whitespace-pre-wrap break-words text-xs leading-relaxed text-agent-muted-foreground"
+      >
+        {safeStringify(result.data)}
+      </pre>,
+    );
+  }
+  if (lines.length === 0) {
+    lines.push(
+      <div key="ok" className="text-xs text-agent-muted-foreground">
+        ok
+      </div>,
+    );
+  }
+  return <div className="space-y-1">{lines}</div>;
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return String(value);
+  }
+}
+
+export function ToolCallRenderer(props: ToolCallRendererProps) {
+  const {
+    call,
+    result,
+    mode,
+    runningHint,
+    onApprove,
+    onReject,
+    className,
+    renderArgs = defaultArgsRenderer,
+    renderResult = defaultResultRenderer,
+    defaultExpanded = false,
+  } = props;
+  const [expanded, setExpanded] = useState(defaultExpanded);
+
+  const status = useToolCallStatus({ call, result, mode, runningHint });
+
+  return (
+    <div
+      data-status={status.status}
+      data-mode={status.mode}
+      className={cn(
+        'rounded-agent-md border bg-agent-canvas px-3 py-2 text-agent-foreground',
+        status.isDestructive ? 'border-agent-destructive/40' : 'border-agent-border',
+        className,
+      )}
+    >
+      <button
+        type="button"
+        className="flex w-full items-center justify-between gap-2 text-left"
+        onClick={() => setExpanded((v) => !v)}
+        aria-expanded={expanded}
+      >
+        <span className="flex min-w-0 items-center gap-2">
+          <span
+            className={cn('h-2 w-2 rounded-full', statusDotClass[status.status])}
+            aria-hidden
+          />
+          <span className="truncate font-mono text-xs font-medium">
+            {call.name}
+          </span>
+          <span
+            className={cn(
+              'shrink-0 rounded-full border px-1.5 py-0.5 text-[10px] font-semibold uppercase tracking-wide',
+              modeBadgeClass[status.mode],
+            )}
+          >
+            {status.mode}
+          </span>
+        </span>
+        <span className="shrink-0 text-[10px] uppercase tracking-wide text-agent-muted-foreground">
+          {status.status}
+        </span>
+      </button>
+      {status.requiresApproval && !result ? (
+        <div className="mt-2 flex items-center gap-2">
+          <span className="text-xs text-agent-muted-foreground">
+            Local execution requires approval.
+          </span>
+          {onApprove ? (
+            <button
+              type="button"
+              className="rounded-agent-sm bg-agent-accent px-2 py-1 text-xs font-medium text-agent-accent-foreground"
+              onClick={() => onApprove(call)}
+            >
+              Approve
+            </button>
+          ) : null}
+          {onReject ? (
+            <button
+              type="button"
+              className="rounded-agent-sm border border-agent-border px-2 py-1 text-xs font-medium text-agent-foreground"
+              onClick={() => onReject(call)}
+            >
+              Reject
+            </button>
+          ) : null}
+        </div>
+      ) : null}
+      {expanded ? (
+        <div className="mt-2 space-y-2 border-t border-agent-border pt-2">
+          {renderArgs(call)}
+          {result ? (
+            <div className="border-t border-dashed border-agent-border pt-2">
+              {renderResult(result)}
+            </div>
+          ) : null}
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/src/components/cn.ts

@@ -0,0 +1,10 @@
+/**
+ * Tiny class-name combiner. We intentionally don't depend on `clsx` /
+ * `tailwind-merge` to keep the package's runtime footprint near zero — those
+ * niceties belong in the consumer app.
+ */
+export function cn(
+  ...values: Array<string | false | null | undefined>
+): string {
+  return values.filter(Boolean).join(' ');
+}

package/src/components/index.ts

@@ -0,0 +1,18 @@
+export { MessageList } from './MessageList.js';
+export type { MessageListProps, MessageRendererProps } from './MessageList.js';
+
+export { ChatPanel } from './ChatPanel.js';
+export type { ChatPanelProps } from './ChatPanel.js';
+
+export { OrchestrationPlanCard } from './OrchestrationPlanCard.js';
+export type {
+  OrchestrationPlanCardProps,
+  OrchestrationStep,
+  OrchestrationStepStatus,
+} from './OrchestrationPlanCard.js';
+
+export { ToolCallRenderer } from './ToolCallRenderer.js';
+export type { ToolCallRendererProps } from './ToolCallRenderer.js';
+
+export { SSEStreamView } from './SSEStreamView.js';
+export type { SSEStreamViewProps } from './SSEStreamView.js';

package/src/hooks/index.ts

@@ -0,0 +1,21 @@
+export { useChatStream } from './useChatStream.js';
+export type {
+  UseChatStreamOptions,
+  UseChatStreamReturn,
+  ChatStreamTransport,
+  ChatStreamSendInput,
+} from './useChatStream.js';
+
+export { useToolCallStatus } from './useToolCallStatus.js';
+export type {
+  ToolCallStatus,
+  UseToolCallStatusOptions,
+  UseToolCallStatusReturn,
+} from './useToolCallStatus.js';
+
+export { useAgentSession } from './useAgentSession.js';
+export type {
+  UseAgentSessionOptions,
+  UseAgentSessionReturn,
+  AgentSessionTransport,
+} from './useAgentSession.js';