@steerable/agent-ui 0.2.0

package/src/hooks/useToolCallStatus.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Tests for `useToolCallStatus`.
+ *
+ * The status hook combines two axes — lifecycle (pending/running/done/error)
+ * and mode (read/safe_write/destructive/local/…) — and exposes the booleans
+ * (`isDestructive`, `requiresApproval`) the renderer cares about. We verify
+ * both the explicit `mode` override path and the name-pattern fallback that
+ * mirrors the framework's `decide_tool_mode`.
+ */
+
+import { renderHook } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { useToolCallStatus } from './useToolCallStatus';
+
+const baseCall = { id: 'c1', name: 'noop', arguments: {} };
+
+describe('useToolCallStatus', () => {
+  it('returns pending when no result has arrived', () => {
+    const { result } = renderHook(() =>
+      useToolCallStatus({ call: { ...baseCall } }),
+    );
+    expect(result.current.status).toBe('pending');
+    expect(result.current.mode).toBe('unknown');
+  });
+
+  it('returns running when runningHint=true and no result yet', () => {
+    const { result } = renderHook(() =>
+      useToolCallStatus({ call: { ...baseCall }, runningHint: true }),
+    );
+    expect(result.current.status).toBe('running');
+  });
+
+  it('returns done when result.success=true', () => {
+    const { result } = renderHook(() =>
+      useToolCallStatus({
+        call: { ...baseCall },
+        result: { success: true },
+      }),
+    );
+    expect(result.current.status).toBe('done');
+  });
+
+  it('returns error when result.success=false', () => {
+    const { result } = renderHook(() =>
+      useToolCallStatus({
+        call: { ...baseCall },
+        result: { success: false, error: 'nope' },
+      }),
+    );
+    expect(result.current.status).toBe('error');
+  });
+
+  it.each([
+    ['get_user', 'read'],
+    ['list_files', 'read'],
+    ['search_messages', 'read'],
+    ['create_event', 'safe_write'],
+    ['update_task', 'safe_write'],
+    ['delete_chat', 'destructive'],
+    ['archive_project', 'destructive'],
+    ['local_run_script', 'local'],
+    ['shell_exec', 'local'],
+    ['something_unrecognised', 'unknown'],
+  ])('infers mode for %s -> %s', (name, expected) => {
+    const { result } = renderHook(() =>
+      useToolCallStatus({ call: { id: 'x', name, arguments: {} } }),
+    );
+    expect(result.current.mode).toBe(expected);
+  });
+
+  it('honours an explicit mode override even if the name suggests something else', () => {
+    const { result } = renderHook(() =>
+      useToolCallStatus({
+        call: { id: 'x', name: 'delete_everything', arguments: {} },
+        mode: 'safe_write',
+      }),
+    );
+    expect(result.current.mode).toBe('safe_write');
+    expect(result.current.isDestructive).toBe(false);
+  });
+
+  it('marks local-mode calls as requiring approval and destructive calls as destructive', () => {
+    const local = renderHook(() =>
+      useToolCallStatus({
+        call: { id: 'x', name: 'local_write_file', arguments: {} },
+      }),
+    );
+    expect(local.result.current.requiresApproval).toBe(true);
+
+    const destr = renderHook(() =>
+      useToolCallStatus({
+        call: { id: 'x', name: 'delete_event', arguments: {} },
+      }),
+    );
+    expect(destr.result.current.isDestructive).toBe(true);
+    // Destructive does not auto-flip requiresApproval; that's a separate decision.
+    expect(destr.result.current.requiresApproval).toBe(false);
+  });
+});

package/src/hooks/useToolCallStatus.ts

@@ -0,0 +1,99 @@
+/**
+ * `useToolCallStatus` — derive the rendering state for a single tool call.
+ *
+ * Tool calls in the framework go through four UI states:
+ *   `pending`    The model has emitted the call but no result has arrived.
+ *   `running`    Optional intermediate state when the runtime emits a
+ *                `tool.running` notification (sidecar / harness can do this).
+ *   `done`       A successful result has been attached.
+ *   `error`      The result reports `success: false` or an error envelope.
+ *
+ * Plus an additional axis — the `mode` (read / safe_write / destructive / local)
+ * — which decides whether the UI should render an approval prompt or an
+ * informational badge.
+ */
+
+import { useMemo } from 'react';
+import type { ToolCall, ToolResult } from '@steerable/agent-protocol';
+
+export type ToolCallStatus = 'pending' | 'running' | 'done' | 'error';
+
+export type ToolCallMode =
+  | 'read'
+  | 'safe_write'
+  | 'destructive'
+  | 'local'
+  | 'external'
+  | 'ui'
+  | 'synthetic'
+  | 'unknown';
+
+export interface UseToolCallStatusOptions {
+  call: ToolCall;
+  result?: ToolResult;
+  /**
+   * Optional override; when omitted the hook infers the mode from the tool
+   * name pattern (`get_*` / `list_*` → read, `delete_*` / `archive_*` →
+   * destructive, `local_*` → local, etc.). Mirrors the framework's harness
+   * `decide_tool_mode`.
+   */
+  mode?: ToolCallMode;
+  /**
+   * If the runtime can emit `tool.running` notifications, set this true to
+   * keep `status` in `running` until a result arrives. Defaults to false
+   * (status flips straight from `pending` → `done`/`error`).
+   */
+  runningHint?: boolean;
+}
+
+export interface UseToolCallStatusReturn {
+  status: ToolCallStatus;
+  mode: ToolCallMode;
+  /** True when the UI should ask for explicit user approval before running. */
+  requiresApproval: boolean;
+  /**
+   * True when the runtime should mark the call as destructive in the UI
+   * (red tone, undo affordance).
+   */
+  isDestructive: boolean;
+}
+
+const READ_PATTERNS = [/^get[_-]/, /^list[_-]/, /^read[_-]/, /^search[_-]/];
+const DESTRUCTIVE_PATTERNS = [
+  /^delete[_-]/,
+  /^remove[_-]/,
+  /^archive[_-]/,
+  /^purge[_-]/,
+  /^drop[_-]/,
+];
+const SAFE_WRITE_PATTERNS = [/^create[_-]/, /^update[_-]/, /^add[_-]/, /^set[_-]/];
+const LOCAL_PATTERNS = [/^local[_-]/, /^shell[_-]/, /^exec[_-]/];
+
+function inferMode(name: string): ToolCallMode {
+  const lower = name.toLowerCase();
+  if (READ_PATTERNS.some((re) => re.test(lower))) return 'read';
+  if (LOCAL_PATTERNS.some((re) => re.test(lower))) return 'local';
+  if (DESTRUCTIVE_PATTERNS.some((re) => re.test(lower))) return 'destructive';
+  if (SAFE_WRITE_PATTERNS.some((re) => re.test(lower))) return 'safe_write';
+  return 'unknown';
+}
+
+export function useToolCallStatus(
+  options: UseToolCallStatusOptions,
+): UseToolCallStatusReturn {
+  return useMemo<UseToolCallStatusReturn>(() => {
+    const mode = options.mode ?? inferMode(options.call.name);
+    const isDestructive = mode === 'destructive';
+    // `local` tools touch the user's machine and need explicit consent.
+    const requiresApproval = mode === 'local';
+    let status: ToolCallStatus;
+    if (!options.result) {
+      status = options.runningHint ? 'running' : 'pending';
+    } else if (options.result.success === false) {
+      status = 'error';
+    } else {
+      status = 'done';
+    }
+    return { status, mode, requiresApproval, isDestructive };
+  }, [options.call.name, options.mode, options.result, options.runningHint]);
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @steerable/agent-ui
+ *
+ * Entry point. Re-exports the public hooks + components surface.
+ *
+ * The Tailwind preset is exposed via the `./tailwind-preset` subpath, not from
+ * the root, so consumers don't pull a build-time dependency into their app
+ * runtime bundle. See `tsconfig.json` `exports` map.
+ */
+
+export * from './hooks/index.js';
+export * from './components/index.js';

package/src/tailwind-preset.ts

@@ -0,0 +1,109 @@
+/**
+ * Steerable Tailwind preset.
+ *
+ * Exposes design tokens (CSS variables) and a small theme extension covering
+ * the colors, spacing, and animations used by `@steerable/agent-ui` components.
+ *
+ * Usage:
+ *
+ *   // tailwind.config.ts
+ *   import preset from '@steerable/agent-ui/tailwind-preset';
+ *   export default { presets: [preset], content: ['./src/**\/*.{ts,tsx}'] };
+ *
+ * Override any token in your project's `globals.css`:
+ *
+ *   :root {
+ *     --agent-canvas: 0 0% 100%;
+ *     --agent-foreground: 240 10% 3.9%;
+ *     --agent-accent: 217 91% 60%;
+ *   }
+ *   .dark {
+ *     --agent-canvas: 240 10% 3.9%;
+ *     --agent-foreground: 0 0% 98%;
+ *   }
+ */
+
+const preset = {
+  // Tell Tailwind we use the `class` darkmode toggle so consumers can opt-in.
+  darkMode: 'class' as const,
+  theme: {
+    extend: {
+      colors: {
+        'agent-canvas': 'hsl(var(--agent-canvas) / <alpha-value>)',
+        'agent-foreground': 'hsl(var(--agent-foreground) / <alpha-value>)',
+        'agent-muted': 'hsl(var(--agent-muted) / <alpha-value>)',
+        'agent-muted-foreground':
+          'hsl(var(--agent-muted-foreground) / <alpha-value>)',
+        'agent-border': 'hsl(var(--agent-border) / <alpha-value>)',
+        'agent-accent': 'hsl(var(--agent-accent) / <alpha-value>)',
+        'agent-accent-foreground':
+          'hsl(var(--agent-accent-foreground) / <alpha-value>)',
+        'agent-destructive':
+          'hsl(var(--agent-destructive) / <alpha-value>)',
+        'agent-tool-read': 'hsl(var(--agent-tool-read) / <alpha-value>)',
+        'agent-tool-write': 'hsl(var(--agent-tool-write) / <alpha-value>)',
+        'agent-tool-destructive':
+          'hsl(var(--agent-tool-destructive) / <alpha-value>)',
+      },
+      borderRadius: {
+        'agent-sm': 'calc(var(--agent-radius) - 4px)',
+        'agent-md': 'calc(var(--agent-radius) - 2px)',
+        'agent-lg': 'var(--agent-radius)',
+      },
+      animation: {
+        'agent-cursor-blink': 'agent-cursor-blink 1s steps(1) infinite',
+        'agent-shimmer': 'agent-shimmer 2s linear infinite',
+      },
+      keyframes: {
+        'agent-cursor-blink': {
+          '0%, 100%': { opacity: '1' },
+          '50%': { opacity: '0' },
+        },
+        'agent-shimmer': {
+          '0%': { backgroundPosition: '-1000px 0' },
+          '100%': { backgroundPosition: '1000px 0' },
+        },
+      },
+    },
+  },
+  // Default token values; consumers can override in their own CSS.
+  // The defaults below satisfy WCAG 2 AA color-contrast (≥ 4.5:1 for normal
+  // text) against `--agent-canvas` (light) and `--agent-muted`. Override at
+  // your own risk — the framework's Storybook a11y suite will start failing
+  // if a regression is introduced.
+  plugins: [
+    function injectDefaultTokens(api: { addBase: (rules: Record<string, unknown>) => void }) {
+      api.addBase({
+        ':root': {
+          '--agent-canvas': '0 0% 100%',
+          '--agent-foreground': '240 10% 3.9%',
+          '--agent-muted': '240 4.8% 95.9%',
+          '--agent-muted-foreground': '240 5% 32%',
+          '--agent-border': '240 5.9% 90%',
+          '--agent-accent': '217 91% 42%',
+          '--agent-accent-foreground': '0 0% 100%',
+          '--agent-destructive': '0 75% 42%',
+          '--agent-tool-read': '142 71% 22%',
+          '--agent-tool-write': '28 90% 28%',
+          '--agent-tool-destructive': '0 75% 42%',
+          '--agent-radius': '0.75rem',
+        },
+        '.dark': {
+          '--agent-canvas': '240 10% 3.9%',
+          '--agent-foreground': '0 0% 98%',
+          '--agent-muted': '240 3.7% 15.9%',
+          '--agent-muted-foreground': '240 5% 75%',
+          '--agent-border': '240 3.7% 15.9%',
+          '--agent-accent': '217 91% 65%',
+          '--agent-accent-foreground': '240 10% 3.9%',
+          '--agent-destructive': '0 75% 60%',
+          '--agent-tool-read': '142 71% 60%',
+          '--agent-tool-write': '38 92% 60%',
+          '--agent-tool-destructive': '0 75% 60%',
+        },
+      });
+    },
+  ],
+};
+
+export default preset;