# @agent-smith/ui

## Summary
A Vue 3 web dashboard for managing AI agents, workflows, tasks, and model configurations, with an optional Node.js server binary (`lmui`) that serves the frontend and bridges to the Agent Smith backend.

## Dependencies
- `@agent-smith/server` — Backend server integration and base routes
- `@agent-smith/wscli` — WebSocket client features for server communication
- `@agent-smith/types` — Shared TypeScript types (AgentState, HistoryTurn, etc.)
- `@agent-smith/app-debate` — Example plugin app (file dependency) demonstrating route extension
- `vue-router` (5.2) — Application routing
- `@snowind/state` — Reactive state management (User class)
- `@vueuse/core` — Vue utilities (useStorage for persisted UI preferences)
- `restmix` — REST API client for server communication
- `markstream-vue` — Streaming markdown renderer for agent output
- `stream-markdown` — Streaming markdown utilities
- `stream-monaco` — Streaming code editor integration
- `mermaid` — Diagram/chart rendering in agent responses
- `highlight.js` — Syntax highlighting for code blocks
- `yaml` — YAML parsing for config files
- `modprompt` — Prompt processing utilities
- `vuecodit` — Code editor component
- `@snowind/header` — Header component
- `@snowind/plugin` — Plugin system integration
- `@snowind/switch` — Theme switch component
- `@fontsource/roboto` — Roboto font
- External: `tailwindcss` (4.3), `sass`, `vite` (8)

## Used By
- End users — Primary interface for Agent Smith AI framework
- `@agent-smith/server` — Serves built frontend assets via `lmui` binary
- App plugins (e.g., `@agent-smith/app-debate`) — Extend routes and components dynamically

## Entry Point
- `src/main.ts` — Vue app bootstrap: creates app, registers router, mounts App component
- `src/bin/index.ts` — Node.js server entry (`lmui`): launches HTTP server with base routes, serves static frontend assets

## Key Files
| File | Purpose |
|------|---------|
| `src/main.ts` | Vue app initialization, registers router, mounts App |
| `src/App.vue` | Root layout: header, sidebar dispatch, router-view, toast/confirmation dialogs |
| `src/state.ts` | Central reactive state: agent state, models, backends, workspaces, UI preferences (persisted via useStorage) |
| `src/router.ts` | 9 routes: home, config, init, workflow, app, task run/view, agent run/view |
| `src/bin/index.ts` | Server binary with static asset serving and dynamic route loading |
| `src/conf.ts` | Default inference params, available plugins list, theme definitions |
| `src/utils.ts` | Utility functions: createAwaiter, transformTasksData |
| `src/interfaces.ts` | Type definitions: SidebarType, UiTaskView, NotificationMsg |
| `src/views/*.vue` | Page components: HomeView, ConfigView, ConfigInitView, AppView, WorkflowView, TaskRunView, TaskViewView |
| `src/components/sidebars/*.vue` | Sidebar navigation: tasks, agents, workflows, inference params, dispatch (7 sidebars) |
| `src/components/navbars/*.vue` | Prompt input toolbars (PromptNavbarLeft, NavbarTask) |
| `src/components/*.vue` | Core UI: TheHeader, tool call rendering, thinking nodes, settings, backend management (15 components) |
| `src/components/EditSettings.vue` | Settings panel: theme switcher + "Save last prompt" toggle (`saveLastPrompt` state) |
| `src/widgets/icons/*.vue` | 34 icon components (PascalCase + Icon suffix) |
| `src/widgets/*.vue` | Reusable widgets: ToolCallDetails, AutoTextarea, LoadingSpinner, HistoryTurnStatsBar, TurnTitle |
| `src/services/api.ts` | REST API client via restmix library |
| `src/services/history.ts` | Conversation turn management, tool call tracking, and stats transfer between history items |
| `src/services/agent-history.ts` | Agent conversation history tree: hierarchical agent history nodes & navigation |
| `src/services/task_events.ts` | Real-time task event handling with streaming markdown parsing |
| `src/services/notify.ts` | Toast/confirmation notification service |
| `src/services/template.ts` | Prompt template application via server API |
| `src/services/str.ts` | String utilities: humanize, humanizeNumber, formatDuration |
| `src/services/perf.ts` | Inference performance timer (tokens/sec tracking) |
| `src/scss/*.scss` | 14 SCSS files (main.scss is the aggregator entry point; default.scss is an alias theme) with CSS custom properties for runtime switching |
| `src/conf.ts` | `themes` array registers 12 themes for the runtime switcher |
| `src/apps/debate.js` | Debate app plugin demonstrating route extension pattern |

## Architecture
- **Component-Based Layout**: App.vue orchestrates TheHeader, SidebarsDispatch (collapsible sidebar system), and router-view with responsive fixed positioning
- **Centralized Reactive State**: Single `state` object (AgentState) managed via Vue `reactive()` + `@snowind/state` `User` class; UI preferences persisted separately via `@vueuse/core` `useStorage()`
- **Service Layer**: Modular services (agent-history, api, history, notify, task_events, perf, str, template) provide isolated concerns; stats handling moved into history.ts; task_events handles real-time streaming with markdown parsing at ~20 parses/sec
- **Theme System**: 14 SCSS files in src/scss/ (main.scss aggregates 13 themes; conf.ts registers 12 for runtime switching) toggleable via CSS class on `<html>` element
- **Plugin System**: Apps in `src/apps/` dynamically extend routes via server-side import; debate app demonstrates the pattern

## Related
- See `@agent-smith/server` — Provides backend HTTP/WebSocket server with base routes
- See `@agent-smith/wscli` — Supplies client-side WebSocket features for real-time communication
- See `@agent-smith/app-debate` — Example plugin demonstrating route extension pattern
- See `@agent-smith/types` — Shared TypeScript type definitions used throughout the UI

## Documentation
- `.agents/documentation/decision-tree.md` — Quick guide: find the right doc for your task
- `.agents/documentation/project-overview.md` — Concise project overview (~1 page)
- `.agents/documentation/project-nav.md` — Detailed navigation map with dependency graph
- `.agents/documentation/code_style_guidelines.md` — UI code style guidelines
- `.agents/documentation/css-style-guide.md` — CSS/theming style guide