@matt82198/aesop 0.1.0-beta.4 → 0.1.0-beta.5

package/ui/web/src/lib/types.ts

@@ -0,0 +1,230 @@
+/**
+ * TypeScript types for Aesop UI API contracts.
+ * These types are imported by U4–U7 components and must remain stable across the wave.
+ */
+
+export interface HeartbeatStatus {
+  alive: 'ALIVE' | 'STALE' | 'UNKNOWN' | 'unknown' | 'not running';
+  age: number; // seconds, bucketed to 3-second intervals; -1 if unknown
+  threshold: number; // seconds until considered stale
+}
+
+/**
+ * One fleet agent — the JSON emitted by dash/dash-extra.mjs --json
+ * (served via GET /api/agents and the `agents` SSE section; also embedded
+ * as `agents` inside GET /data).
+ * `status`: 'running' | 'idle' age-derived, overridden by security-log
+ * severities 'SUSPICIOUS' | 'HIGH' | 'DRIFT' | 'MED'.
+ * ui/agents.py de-dupes colliding 13-char ids by suffixing "-2", "-3", ...
+ */
+export interface Agent {
+  id: string;
+  project: string;
+  status: 'running' | 'idle' | 'SUSPICIOUS' | 'HIGH' | 'DRIFT' | 'MED' | string;
+  age_s: number; // seconds since transcript mtime
+  hint: string; // label, capped at 60 chars
+  startedAt: string | null; // ISO 8601 transcript timestamp
+  lastActivity: string | null; // ISO 8601 transcript timestamp
+  runtimeSeconds?: number;
+  tokensUsed?: number;
+  taskLabel: string; // first prompt line, capped at 80 chars
+  promptFull?: string;
+}
+
+/**
+ * GET /agent?id=<id> — dispatch prompt + metadata
+ * (ui/agents.py extract_agent_dispatch_prompt).
+ * Error responses are {error: string} with 400 (invalid id) or 404 (no transcript).
+ */
+export interface AgentDetail {
+  id: string;
+  dispatch_prompt: string;
+  dispatcher: 'main thread' | 'parent agent';
+  model: string; // "unknown" when not found in transcript
+  message_count: number;
+  first_seen: number; // epoch seconds (file mtime)
+  last_activity: number; // epoch seconds (file mtime)
+}
+
+/** GET /api/session — CSRF token for same-origin JS (U2 adds this). */
+export interface SessionResponse {
+  token: string;
+}
+
+/** Uniform error payload shape for non-2xx JSON responses. */
+export interface ApiError {
+  error: string;
+}
+
+export interface Alert {
+  count: number;
+  lines: string[];
+}
+
+export interface TrackerItem {
+  id: string;
+  title: string;
+  priority: 'P0' | 'P1' | 'P2';
+  status: 'todo' | 'done' | 'in-progress' | 'archived';
+  lane: 'proposed' | 'ranked' | 'in-progress' | 'done';
+  source: string;
+  tags: string[];
+  notes: string | null;
+  pr_link: string | null;
+  created_at: string; // ISO 8601
+  completed_at: string | null;
+}
+
+/**
+ * The `tracker` SSE section and the tracker slice of GET /api/state.
+ * NOTE: GET /api/tracker returns a BARE TrackerItem[] array (no wrapper).
+ */
+export interface TrackerSnapshot {
+  items: TrackerItem[];
+}
+
+export interface AuditBacklogItem {
+  status: '✅' | '🔵' | '⬜' | '⏸';
+  tag: string; // e.g., "[sec]"
+  title: string;
+}
+
+export interface AuditBacklogTier {
+  tier: 'P0' | 'P1' | 'P2' | 'Needs decision';
+  items: AuditBacklogItem[];
+  done: number;
+  inflight: number;
+  todo: number;
+  total: number;
+}
+
+export interface AuditBacklog {
+  tiers: AuditBacklogTier[];
+}
+
+export interface Message {
+  role: 'user' | 'assistant';
+  text: string;
+  timestamp: string; // ISO 8601
+}
+
+export interface OrchestratorEntry {
+  id?: string;
+  role?: string;
+  activity?: string;
+  phase?: string;
+  age_seconds: number;
+  stale: boolean;
+  updated_at?: string;
+}
+
+export interface OrchestratorStatus {
+  orchestrators: OrchestratorEntry[];
+}
+
+/**
+ * Repo status entry from .watchdog-repos.json (list passthrough, or
+ * {repo, state} pairs when the file holds an object).
+ */
+export interface RepoStatus {
+  repo?: string;
+  state?: unknown;
+  [key: string]: unknown;
+}
+
+/**
+ * GET /data response AND the `data` SSE section.
+ * Note: `agents` is present on GET /data only; the SSE `data` section
+ * (collectors._snapshot_data) omits it — agents arrive on their own
+ * `agents` SSE section.
+ */
+export interface DashboardData {
+  watchdog: HeartbeatStatus;
+  monitor: HeartbeatStatus;
+  agents?: Agent[];
+  repos: RepoStatus[];
+  events: string[];
+  alerts: Alert;
+  messages: Message[];
+}
+
+/** POST /submit success response. */
+export interface SubmitResponse {
+  ok: boolean;
+}
+
+export interface FullState {
+  data: DashboardData;
+  backlog: AuditBacklog;
+  agents: Agent[];
+  tracker: TrackerSnapshot;
+  status: OrchestratorStatus;
+  cost?: CostSummary;
+}
+
+/**
+ * Cost summary from GET /api/cost.
+ * Mirrors ui/cost.py get_cost_summary() docstring on branch
+ * feat/wave14-u3-cost-collector — verbatim shape, NOT provisional.
+ */
+export interface CostModelStats {
+  runs: number;
+  tokens_in: number;
+  tokens_out: number;
+  verdicts: {
+    OK: number;
+    FAILED: number;
+    EMPTY: number;
+    HUNG: number;
+  };
+}
+
+export interface CostDailyTotal {
+  tokens_in: number;
+  tokens_out: number;
+}
+
+export interface CostOverallScorecard {
+  total_runs: number;
+  ok_count: number;
+  failed_count: number;
+  empty_count: number;
+  hung_count: number;
+  ok_rate: number; // 0.0-1.0
+  failed_rate: number;
+  empty_rate: number;
+  hung_rate: number;
+}
+
+export interface CostEstimate {
+  input_cost: number; // dollars
+  output_cost: number; // dollars
+  total_cost: number; // dollars
+}
+
+export interface CostSummary {
+  models: Record<string, CostModelStats>; // keyed by model id
+  daily_totals: Record<string, CostDailyTotal>; // keyed by "YYYY-MM-DD"
+  overall_scorecard: CostOverallScorecard;
+  skipped_lines: number;
+  has_pricing: boolean;
+  estimates_by_model: Record<string, CostEstimate>; // empty when has_pricing is false
+}
+
+/**
+ * SSE event sections emitted by GET /events.
+ * Initial sections: data, backlog, agents, tracker, status
+ * Added in U3: cost
+ */
+export type SSESection =
+  | 'data'
+  | 'backlog'
+  | 'agents'
+  | 'tracker'
+  | 'status'
+  | 'cost';
+
+export interface SSEConnectionStatus {
+  status: 'live' | 'reconnecting' | 'error';
+  lastError?: string;
+}

package/ui/web/src/lib/useHashRoute.test.ts

@@ -0,0 +1,60 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useHashRoute, normalizeHash, ROUTES } from './useHashRoute';
+
+function setHash(hash: string) {
+  window.location.hash = hash;
+  window.dispatchEvent(new HashChangeEvent('hashchange'));
+}
+
+afterEach(() => {
+  window.location.hash = '';
+});
+
+describe('normalizeHash', () => {
+  it('passes through known routes', () => {
+    for (const r of ROUTES) {
+      expect(normalizeHash(r)).toBe(r);
+    }
+  });
+
+  it('normalizes empty hash to #/', () => {
+    expect(normalizeHash('')).toBe('#/');
+  });
+
+  it('normalizes unknown hashes to #/', () => {
+    expect(normalizeHash('#/bogus')).toBe('#/');
+    expect(normalizeHash('#work')).toBe('#/');
+  });
+});
+
+describe('useHashRoute', () => {
+  it('returns #/ initially with no hash', () => {
+    const { result } = renderHook(() => useHashRoute());
+    expect(result.current).toBe('#/');
+  });
+
+  it('follows hashchange events', () => {
+    const { result } = renderHook(() => useHashRoute());
+    act(() => setHash('#/work'));
+    expect(result.current).toBe('#/work');
+    act(() => setHash('#/cost'));
+    expect(result.current).toBe('#/cost');
+    act(() => setHash('#/activity'));
+    expect(result.current).toBe('#/activity');
+  });
+
+  it('normalizes unknown hash changes to #/', () => {
+    const { result } = renderHook(() => useHashRoute());
+    act(() => setHash('#/work'));
+    expect(result.current).toBe('#/work');
+    act(() => setHash('#/nonsense'));
+    expect(result.current).toBe('#/');
+  });
+
+  it('reads the initial hash on mount', () => {
+    window.location.hash = '#/cost';
+    const { result } = renderHook(() => useHashRoute());
+    expect(result.current).toBe('#/cost');
+  });
+});

package/ui/web/src/lib/useHashRoute.ts

@@ -0,0 +1,23 @@
+/**
+ * useHashRoute — ~10-line hash-tab routing hook (deliberately NOT react-router; see plan D1).
+ * Routes: '#/' (overview), '#/work', '#/activity', '#/cost'.
+ * Unknown/empty hashes normalize to '#/'.
+ */
+import { useEffect, useState } from 'react';
+
+export const ROUTES = ['#/', '#/work', '#/activity', '#/cost'] as const;
+export type Route = (typeof ROUTES)[number];
+
+export function normalizeHash(hash: string): Route {
+  return (ROUTES as readonly string[]).includes(hash) ? (hash as Route) : '#/';
+}
+
+export function useHashRoute(): Route {
+  const [route, setRoute] = useState<Route>(() => normalizeHash(window.location.hash));
+  useEffect(() => {
+    const onHashChange = () => setRoute(normalizeHash(window.location.hash));
+    window.addEventListener('hashchange', onHashChange);
+    return () => window.removeEventListener('hashchange', onHashChange);
+  }, []);
+  return route;
+}

package/ui/web/src/lib/useSSE.ts

@@ -0,0 +1,175 @@
+/**
+ * useSSE hook — EventSource wrapper with reconnect backoff, per-section state, and connection status.
+ *
+ * Usage:
+ *   const { data, backlog, agents, tracker, status, cost, connectionStatus } = useSSE();
+ *
+ * Emits on sections: data, backlog, agents, tracker, status, cost
+ * Handles connection errors and automatic reconnect with exponential backoff (1s → 10s max).
+ */
+
+import { useEffect, useRef, useState, useCallback } from 'react';
+import type { DashboardData, AuditBacklog, Agent, TrackerSnapshot, OrchestratorStatus, CostSummary, SSEConnectionStatus } from './types';
+
+export interface SSEState {
+  data: DashboardData | null;
+  backlog: AuditBacklog | null;
+  agents: Agent[] | null;
+  tracker: TrackerSnapshot | null;
+  status: OrchestratorStatus | null;
+  cost: CostSummary | null;
+  connectionStatus: SSEConnectionStatus;
+}
+
+const initialState: SSEState = {
+  data: null,
+  backlog: null,
+  agents: null,
+  tracker: null,
+  status: null,
+  cost: null,
+  connectionStatus: { status: 'reconnecting' },
+};
+
+export function useSSE() {
+  const [state, setState] = useState<SSEState>(initialState);
+  const eventSourceRef = useRef<EventSource | null>(null);
+  const reconnectAttemptRef = useRef(0);
+  const reconnectTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const getReconnectDelay = useCallback(() => {
+    const baseDelay = 1000; // 1 second
+    const maxDelay = 10000; // 10 seconds
+    const delay = Math.min(baseDelay * Math.pow(2, reconnectAttemptRef.current), maxDelay);
+    return delay;
+  }, []);
+
+  const connect = useCallback(() => {
+    if (eventSourceRef.current) {
+      return; // Already connected or connecting
+    }
+
+    const eventSource = new EventSource('/events');
+
+    eventSource.addEventListener('data', (e) => {
+      try {
+        const payload = JSON.parse(e.data);
+        setState((prev) => ({
+          ...prev,
+          data: payload,
+          connectionStatus: { status: 'live' },
+        }));
+        reconnectAttemptRef.current = 0;
+      } catch (err) {
+        console.error('Failed to parse SSE data:', err);
+      }
+    });
+
+    eventSource.addEventListener('backlog', (e) => {
+      try {
+        const payload = JSON.parse(e.data);
+        setState((prev) => ({
+          ...prev,
+          backlog: payload,
+          connectionStatus: { status: 'live' },
+        }));
+        reconnectAttemptRef.current = 0;
+      } catch (err) {
+        console.error('Failed to parse SSE backlog:', err);
+      }
+    });
+
+    eventSource.addEventListener('agents', (e) => {
+      try {
+        const payload = JSON.parse(e.data);
+        setState((prev) => ({
+          ...prev,
+          agents: Array.isArray(payload) ? payload : [],
+          connectionStatus: { status: 'live' },
+        }));
+        reconnectAttemptRef.current = 0;
+      } catch (err) {
+        console.error('Failed to parse SSE agents:', err);
+      }
+    });
+
+    eventSource.addEventListener('tracker', (e) => {
+      try {
+        const payload = JSON.parse(e.data);
+        setState((prev) => ({
+          ...prev,
+          tracker: payload,
+          connectionStatus: { status: 'live' },
+        }));
+        reconnectAttemptRef.current = 0;
+      } catch (err) {
+        console.error('Failed to parse SSE tracker:', err);
+      }
+    });
+
+    eventSource.addEventListener('status', (e) => {
+      try {
+        const payload = JSON.parse(e.data);
+        setState((prev) => ({
+          ...prev,
+          status: payload,
+          connectionStatus: { status: 'live' },
+        }));
+        reconnectAttemptRef.current = 0;
+      } catch (err) {
+        console.error('Failed to parse SSE status:', err);
+      }
+    });
+
+    eventSource.addEventListener('cost', (e) => {
+      try {
+        const payload = JSON.parse(e.data);
+        setState((prev) => ({
+          ...prev,
+          cost: payload,
+          connectionStatus: { status: 'live' },
+        }));
+        reconnectAttemptRef.current = 0;
+      } catch (err) {
+        console.error('Failed to parse SSE cost:', err);
+      }
+    });
+
+    eventSource.addEventListener('error', (err) => {
+      console.error('EventSource error:', err);
+      eventSource.close();
+      eventSourceRef.current = null;
+      setState((prev) => ({
+        ...prev,
+        connectionStatus: {
+          status: 'reconnecting',
+          lastError: 'Connection lost',
+        },
+      }));
+      reconnectAttemptRef.current += 1;
+      const delay = getReconnectDelay();
+      reconnectTimeoutRef.current = setTimeout(connect, delay);
+    });
+
+    eventSourceRef.current = eventSource;
+    setState((prev) => ({
+      ...prev,
+      connectionStatus: { status: 'reconnecting' },
+    }));
+  }, [getReconnectDelay]);
+
+  useEffect(() => {
+    connect();
+
+    return () => {
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
+      if (eventSourceRef.current) {
+        eventSourceRef.current.close();
+      }
+    };
+  }, [connect]);
+
+  return state;
+}

package/ui/web/src/main.tsx

@@ -0,0 +1,10 @@
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import './styles/global.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>,
+);

package/ui/web/src/styles/global.css

@@ -0,0 +1,179 @@
+/**
+ * Aesop global styles — reset, focus-visible rings, sr-only, reduced motion,
+ * app-shell layout. Component-specific styles belong with components (U4–U7);
+ * only shared shell + utility styles live here.
+ */
+
+@import './theme.css';
+
+/* ---- Reset ---- */
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html {
+  -webkit-text-size-adjust: 100%;
+}
+
+body {
+  font-family: var(--font-sans);
+  font-size: var(--font-size-md);
+  line-height: var(--line-height-normal);
+  color: var(--color-text);
+  background: var(--color-bg);
+}
+
+img,
+svg {
+  max-width: 100%;
+  display: block;
+}
+
+button,
+input,
+select,
+textarea {
+  font: inherit;
+  color: inherit;
+}
+
+a {
+  color: var(--color-accent);
+}
+
+/* ---- Focus-visible rings (D5: visible focus, never removed) ---- */
+:focus {
+  outline: none;
+}
+
+:focus-visible {
+  outline: 2px solid var(--color-focus-ring);
+  outline-offset: 2px;
+  border-radius: var(--radius-sm);
+}
+
+/* ---- Screen-reader-only utility ---- */
+.sr-only {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* ---- Reduced motion (D5) ---- */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+/* ---- App shell ---- */
+.app-header {
+  position: sticky;
+  top: 0;
+  z-index: 100;
+  display: flex;
+  align-items: center;
+  gap: var(--space-3);
+  min-height: var(--header-height);
+  padding: 0 var(--space-4);
+  background: var(--color-bg-subtle);
+  border-bottom: 1px solid var(--color-border);
+}
+
+.app-title {
+  font-size: var(--font-size-md);
+  font-weight: var(--font-weight-bold);
+  white-space: nowrap;
+}
+
+.app-nav {
+  display: flex;
+  gap: var(--space-1);
+}
+
+.app-nav a {
+  display: inline-block;
+  padding: var(--space-2) var(--space-3);
+  color: var(--color-text-muted);
+  text-decoration: none;
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-medium);
+  border-bottom: 2px solid transparent;
+}
+
+.app-nav a[aria-current='page'] {
+  color: var(--color-text);
+  border-bottom-color: var(--color-accent);
+}
+
+.app-nav a:hover {
+  color: var(--color-text);
+}
+
+.app-main {
+  max-width: var(--content-max-width);
+  margin: 0 auto;
+  padding: var(--space-4);
+}
+
+.view-placeholder {
+  padding: var(--space-6);
+  border: 1px dashed var(--color-border);
+  border-radius: var(--radius-md);
+  color: var(--color-text-muted);
+  text-align: center;
+}
+
+.theme-toggle {
+  margin-left: auto;
+  padding: var(--space-1) var(--space-2);
+  background: transparent;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  font-size: var(--font-size-sm);
+  color: var(--color-text-muted);
+}
+
+.theme-toggle:hover {
+  color: var(--color-text);
+  background: var(--color-bg-inset);
+}
+
+.sse-status {
+  font-size: var(--font-size-xs);
+  font-weight: var(--font-weight-medium);
+  padding: var(--space-1) var(--space-2);
+  border-radius: var(--radius-sm);
+  white-space: nowrap;
+}
+
+.sse-status[data-status='live'] {
+  color: var(--color-status-ok);
+  background: var(--color-status-ok-bg);
+}
+
+.sse-status[data-status='reconnecting'] {
+  color: var(--color-status-warn);
+  background: var(--color-status-warn-bg);
+}
+
+.sse-status[data-status='error'] {
+  color: var(--color-status-error);
+  background: var(--color-status-error-bg);
+}