Declan scale/readme

agentex-ui/README.md

@@ -1,64 +1,189 @@
 # Agentex UI
 
-A generic Agentex web client.
+A modern web interface for building, testing, and monitoring intelligent agents. The Agentex UI provides a comprehensive developer experience for interacting with agents, managing tasks, and visualizing execution traces.
+
+<img src="./docs/images/dashboard.png" alt="Agentex UI Dashboard" width="1280"/>
+
+## Features
+
+### Agent Management
+
+- **Agent Discovery** - Browse and explore all available agents in your system
+- **Agent Details** - View agent configurations, capabilities, and deployment status
+- **Multi-Agent Support** - Work with multiple agents simultaneously
+
+<img src="./docs/images/agents-list.gif" alt="Agents List" width="1280"/>
+
+### Task Execution
+
+- **Create Tasks** - Initialize agent tasks with custom parameters
+- **Task History** - View complete task execution history with filtering by agent
+- **Infinite Scroll** - Efficiently browse through long task lists
+
+<img src="./docs/images/tasks-list.gif" alt="Tasks List" width="1280"/>
+
+### Interactive Chat
+
+- **Conversational Interface** - Send messages and interact with agents in real-time
+- **Streaming Responses** - Live message streaming for sync agents
+- **Message History** - Full conversation history with timestamps
+- **Rich Content Support** - Display text, markdown, code, and structured data
+
+<img src="./docs/images/chat-interface.gif" alt="Chat Interface" width="1280"/>
+
+### Observability
+
+- **Execution Traces** - View OpenTelemetry-style spans for task execution
+- **Span Visualization** - Hierarchical view of execution flow
+- **Performance Metrics** - Timing and duration information for each execution step
+- **Error Tracking** - Detailed error information when tasks fail
+
+<img src="./docs/images/execution-traces.gif" alt="Execution Traces" width="1280"/>
+
+### Developer Experience
+
+- **Real-time Updates** - Live task and message updates via WebSocket subscriptions
+- **Optimistic UI** - Instant feedback with automatic cache updates
+- **Error Handling** - User-friendly error messages with toast notifications
+- **Dark Mode** - WCAG-compliant dark mode with proper contrast ratios
 
 ## Stack
 
-- Next.js 15 (App Router), React 19, TypeScript
-- Tailwind CSS v4, agentex-ui-kit, shadcn/ui
-- State: Zustand stores + controller hooks
-- Agentex SDK (`agentex`): API client + RPC helpers
+- **Framework**: Next.js 15 (App Router), React 19, TypeScript
+- **Styling**: Tailwind CSS v4, shadcn/ui components
+- **State Management**: React Query for server state
+- **Data Fetching**: Agentex SDK (`agentex`) for API client + RPC helpers
+- **Real-time**: WebSocket subscriptions for live updates
 
 ## Prerequisites
 
-- Node.js 20.x (match Docker base). Use npm (project ships `package-lock.json`).
+- npm
+- Running Agentex backend (see `../agentex/README.md`)
+
+## Getting Started from Scratch
 
-## Quickstart (Local)
+### 1. Start the Backend
 
-### 1. Env
+Before running the frontend, ensure the Agentex backend is running:
 
 ```bash
+cd ../agentex
+make dev
+```
+
+This starts all required services (PostgreSQL, Redis, MongoDB, Temporal) and the FastAPI backend on port 5003.
+
+### 2. Configure Environment Variables
+
+Create your local environment file:
+
+```bash
+cd agentex-ui
 cp example.env.development .env.development
-# edit values as needed
 ```
 
-Required public vars:
+Edit `.env.development` with your configuration:
+
+```bash
+# Backend API endpoint
+NEXT_PUBLIC_AGENTEX_API_BASE_URL=http://localhost:5003
+```
+
+### 3. Install Dependencies
+
+```bash
+npm install
+```
 
-- `NEXT_PUBLIC_AGENTEX_API_BASE_URL` (e.g. `http://localhost:5003`)
-- `NEXT_PUBLIC_SGP_APP_URL` (login redirect base; e.g. `https://egp.dashboard.scale.com`)
+This installs all required packages including Next.js, React, Tailwind CSS, and the Agentex SDK.
 
-### 2. Install & run
+### 4. Run the Development Server
 
 ```bash
+npm run dev
+# or using make
 make dev
-# http://localhost:3000
 ```
 
+The application will start on [http://localhost:3000](http://localhost:3000).
+
 ## Scripts
 
-- `make dev` — dev server (Turbopack)
-- `make lint` — ESLint (Next config)
-- `make typecheck` — TypeScript no-emit
-- `make build` — production build
-- `npm start` — start built app
-
-## Architecture Map (what to read first)
-
-- Entry points:
-  - `app/page.tsx` → no-agent mode → `entrypoints/no-agent/*`
-  - `app/agent/[agentName]/page.tsx` → single-agent mode → `entrypoints/single-agent/*`
-- Bootstrap per mode:
-  - `entrypoints/*/*-root.tsx` creates an `AgentexSDK`, fetches agents/tasks, and mounts a `Zustand` store via `AgentexRootStoreContext`.
-- State:
-  - `hooks/use-agentex-root-store.ts` — shared state that crosses task boundaries.
-  - `hooks/use-agentex-root-controller.ts` — async functions that rely on shared state (e.g., `createTask`, pending-message orchestration).
-  - `hooks/use-agentex-task-store.ts` — task-scoped store and selectors.
-  - `hooks/use-agentex-task-controller.ts` — task-scoped functions (e.g., `sendMessage`).
-- UI:
-  - Reusable components under `components/agentex/*` and `components/ui/*`. Keep UI dump components stateless; put IO and branching in controllers.
-
-## Conventions
-
-- Prefer controller hooks for side effects and branching; components should be mostly presentational.
-- Keep new public envs prefixed with `NEXT_PUBLIC_` and documented here.
-- Co-locate mode-specific UI under `entrypoints/` rather than `app/` when possible.
+**Development:**
+
+- `make dev` or `npm run dev` — Start dev server with Turbopack
+- `npm run build` — Create production build
+- `npm start` — Start production server
+
+**Code Quality:**
+
+- `make lint` or `npm run lint` — Run ESLint with zero warnings policy
+- `npm run lint:fix` — Auto-fix linting issues
+- `make typecheck` or `npm run typecheck` — TypeScript type checking
+- `npm run format` — Format code with Prettier
+- `npm run format:check` — Check formatting without writing
+
+**Testing:**
+
+- `npm test` — Run tests in watch mode
+- `npm run test:run` — Run tests once (CI mode)
+- `npm run test:ui` — Open Vitest UI for interactive testing
+- `npm run test:coverage` — Generate coverage report
+
+## Architecture
+
+### Code Structure
+
+**Entry Point:**
+
+- `app/page.tsx` → Main application entry → `app/home-view.tsx`
+
+**State Management:**
+
+- `hooks/use-agents.ts` - Fetches all agents via React Query
+- `hooks/use-tasks.ts` - Task list with infinite scroll pagination
+- `hooks/use-task-messages.ts` - Message fetching and sending with message streaming for sync agents
+- `hooks/use-task-subscription.ts` - Real-time task updates via WebSocket for async agents
+- `hooks/use-spans.ts` - Execution trace data
+
+**Components:**
+
+- `components/agentex/*` - Agentex-specific UI components (chat, task list, etc.)
+- `components/ui/*` - Reusable UI primitives from shadcn/ui
+
+## Testing
+
+The project uses [Vitest](https://vitest.dev/) as the test runner with React Testing Library for component testing.
+
+### Running Tests
+
+```bash
+# Watch mode (runs tests on file changes)
+npm test
+
+# Run once (useful for CI)
+npm run test:run
+
+# Interactive UI
+npm run test:ui
+
+# Generate coverage report
+npm run test:coverage
+```
+
+### Test Configuration
+
+The test suite is configured with:
+
+- **Environment**: happy-dom (lightweight DOM simulation)
+- **Globals**: Enabled for describe/it/expect without imports
+- **Coverage**: v8 provider with text, JSON, and HTML reporters
+- **Setup**: Path aliases configured to match Next.js (@/ → root, @/app, @/components, @/lib)
+
+Coverage reports are generated in the `coverage/` directory and exclude config files, type definitions, and node_modules.
+
+### Writing Tests
+
+- Use Testing Library best practices for component tests
+- Test files should be co-located with the code they test (e.g., `lib/utils.ts` → `lib/utils.test.ts`)
+- Aim for high coverage on business logic and utility functions

agentex-ui/components.json

@@ -17,8 +17,5 @@
     "ui": "@/components/ui",
     "lib": "@/lib",
     "hooks": "@/hooks"
-  },
-  "registries": {
-    "@ai-elements": "https://registry.ai-sdk.dev/{name}.json"
   }
 }

agentex-ui/components/agentex/task-sidebar.tsx

@@ -141,14 +141,14 @@ export function TaskSidebar() {
             </>
           )}
         </div>
-        <div className="mt-auto px-2 pt-2">
+        <div className="mt-auto pt-2">
           <Separator className="mb-2" />
           <Button
             onClick={handleFeedback}
             variant="ghost"
             className="text-sidebar-foreground hover:bg-sidebar-accent hover:text-sidebar-primary-foreground flex w-full items-center justify-start gap-2"
           >
-            <MessageSquare className="size-4" />
+            <MessageSquare className="size-5" />
             Give Feedback
           </Button>
         </div>

agentex-ui/example.env.development

@@ -1,2 +1 @@
 NEXT_PUBLIC_AGENTEX_API_BASE_URL=http://localhost:5003
-NEXT_PUBLIC_SGP_APP_URL=https://egp.dashboard.scale.com