diff --git a/.gitignore b/.gitignore index 18e56fb..adde0bc 100644 --- a/.gitignore +++ b/.gitignore @@ -98,4 +98,8 @@ mission-control/public/ci-verify-input.json docs/proposals/ docs/roadmap/ +# ── Ad-hoc Scripts (personal utilities, not project-relevant) ───── +scripts/generate_icons.py +scripts/rebuild.sh + diff --git a/README.md b/README.md index f570afc..5985e95 100644 --- a/README.md +++ b/README.md @@ -5,14 +5,15 @@

Stigmergic

- Biomimetic Multi-Agent Swarm (bMAS) Orchestration System + Blackboard Multi-Agent Swarm (bMAS) Orchestration System

- Features • - Architecture • + How It Works • + See It In Action • Quick Start • - Documentation + Documentation • + Components

@@ -22,61 +23,59 @@ TypeScript 6.x Next.js 16 Docker - Redis - LiteLLM - vLLM

-**A distributed AI swarm built on the Blackboard Multi-Agent System (bMAS) architecture.** Stigmergic coordinates multiple LLM-powered agents through a shared blackboard with an LLM-driven Control Unit that dynamically selects agents per round — achieving structured, multi-round debate and consensus. +--- + +**A distributed AI swarm built on the Blackboard Multi-Agent System (bMAS) architecture.** Stigmergic coordinates multiple LLM-powered agents through a shared blackboard with an LLM-driven Control Unit that dynamically selects agents per round and achieves structured, multi-round debate and consensus. > *Named after [stigmergy](https://en.wikipedia.org/wiki/Stigmergy) — the mechanism by which individual agents coordinate through shared environmental signals (the blackboard) rather than direct communication.* -## Features +

+ Stigmergic — Landing Page +

-- **Cyclic blackboard orchestration** — Control Unit selects agents per round; agents read/write a shared board; rounds repeat until convergence (not a fixed pipeline) -- **Dynamic agent roles** — Planner, Critic, Conflict Resolver, Cleaner, Decider, and domain-specific Experts — all discovered and activated dynamically -- **Multi-provider model routing** — Route tasks to Gemini, Claude, OpenAI, or local models based on complexity tiers -- **Intelligent triage** — Local Qwen3-1.7B classifier automatically routes tasks to the cheapest capable model -- **Execution graph** — Swimlane visualization of agent turns grouped by round, with coordinator routing rationale -- **Structured distributed logging** — Per-agent log streams with full structured payloads, level/agent filtering, and detail drawers -- **Blackboard command center** — Timeline, thread, and graph views of board entries with salience heat, debate threading, and type/author grouping -- **Mission cockpit** — Live 4-panel command center: blackboard graph, agent mind cards, global firehose, convergence strip -- **Human-in-the-loop** — Pause/resume at round boundaries, inject directives, abort tasks, approve/reject agent actions -- **Real-time cost tracking** — Per-model token usage and USD cost with budget ceilings and live gauges -- **Single config file** — Define your entire deployment in `bmas.yaml` -- **Docker-first** — `docker compose up` and you're running +## How It Works -## Architecture +**Orchestration** — A Control Unit reads the shared blackboard each round, selects which agents to activate, and those agents execute concurrently by writing findings, plans, and critiques back to the board. Rounds repeat until the swarm reaches consensus, hits a budget ceiling, or exhausts max rounds. Domain-specific experts are generated dynamically per task, not pre-configured. -``` -┌─────────────────── Control Plane (Docker Compose) ───────────────────┐ -│ │ -│ ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌────────┐ ┌───────────┐ │ -│ │ Redis │ │ LiteLLM │ │ Triage │ │ Daemon │ │ Mission │ │ -│ │ Board │ │ Gateway │ │ (GPU) │ │ Orch. │ │ Control │ │ -│ │ :6379 │ │ :4000 │ │ :8001 │ │ :9000 │ │ :9321 │ │ -│ └─────────┘ └──────────┘ └─────────┘ └────────┘ └───────────┘ │ -└───────────────────────────────────────────────────────────────────────┘ - │ │ │ - │ ┌──────┴──────┐ ┌──────┴──────┐ - │ │ Cloud APIs │ │ Agent Nodes │ - │ │ Gemini/etc │ │ Hermes+SSE │ - │ └─────────────┘ └─────────────┘ - - ┌─────── Per Round ─────────┐ - │ │ - │ Control Unit selects │ - │ agents from board state │ - │ │ │ - │ ┌────┴────┐ │ - │ │ Agents │ read/write │ - │ │ execute │ the board │ - │ └────┬────┘ │ - │ │ │ - │ Board updated; │ - │ loop until convergence │ - └────────────────────────────┘ -``` +**Observability** — Real-time execution graphs, distributed log streams across all agents, a blackboard command center, and per-model cost tracking are all visible in a live dashboard built with Next.js and Server-Sent Events. + +**Operations** — Pause at round boundaries, inject directives, steer which agents run next, and set budget ceilings. A local Qwen3-1.7B classifier routes every task to the cheapest capable model before any paid API call. One YAML file configures the entire deployment. Just `docker compose up` and you're running. + +## See It In Action + +### Execution Graph + +Swimlane visualization showing agent turns grouped by round. Each node reveals what the agent did, why the Control Unit selected it, and what it cost. + +

+ Execution Graph — swimlane view of rounds and agent turns +

+ +### Distributed Log Stream + +Unified chronological log across all agents with per-role filtering. Click any entry to expand structured fields — actor, model, round, output, and duration. + +

+ Distributed Log Stream — per-agent filtering with structured detail drawer +

+ +### Blackboard Command Center + +The shared knowledge store. Timeline of board entries with salience heat, entry types, and debate threading. Agent Minds shows each agent's model and contribution count. + +

+ Blackboard Command Center — board entries and agent minds +

+ +### Cost & Performance + +Per-model token breakdown, cost tracking, and an agent timeline showing when each role was active across rounds. + +

+ Cost tracking — token usage, cost breakdown, and agent timeline +

## Quick Start @@ -96,171 +95,54 @@ docker compose --profile gpu up -d # with GPU (enables triage) open http://localhost:9321 ``` -See [docs/QUICKSTART.md](docs/QUICKSTART.md) for the full guide. - -## Configuration - -Everything is configured through a single `bmas.yaml` file: - -```yaml -project: - name: "My Swarm" - -control_plane: - host: "localhost" - ports: { redis: 6379, litellm: 4000, daemon: 9000, dashboard: 9321 } - -coordination: - variant: traditional # traditional | stigmergic - traditional: - max_rounds: 8 - budget_ceiling_usd: 1.00 - cu_mode: llm # llm | heuristic - coordinator_narration: true - -nodes: - - name: "node-1" - host: "192.168.1.101" - port: 8000 - role: planner - inference: { host: "192.168.1.102", port: 8080, model: "gemma-4-e4b" } - -models: - gemini-pro: { provider: gemini, model: "gemini-3.1-pro-preview", api_key_env: GEMINI_API_KEY } - -routing: - complex: gemini-pro - medium: gemini-pro - light: gemini-pro - simple: local -``` - -See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for the full reference and [examples/](examples/) for sample configs. - -## Repository Structure - -``` -bmas/ -├── bmas.example.yaml # Reference configuration -├── .env.example # Secrets template -├── docker-compose.yml # Unified control plane (5 services) -├── docker-compose.dev.yml # Dev overrides (hot-reload, volume mounts) -│ -├── agent/ # Edge node agent API (deployed to LXCs) -│ ├── api_server.py # Hermes ↔ Daemon bridge (Runs API + CLI fallback) -│ ├── profiles/ # Per-role Hermes profiles (planner, critic, expert, ...) -│ └── tests/ # SSE parser + event translation tests -│ -├── daemon/ # Python FastAPI orchestrator -│ └── src/ -│ ├── app.py # API entry point (:9000) -│ ├── config.py # Loads bmas.yaml at startup -│ ├── database.py # SQLite persistence (v2 schema, 12 tables) -│ ├── auth.py # Bearer token authentication for node ingest -│ ├── core/ -│ │ ├── orchestrator.py # Task lifecycle + multi-round dispatch -│ │ ├── blackboard.py # Redis state + durable board snapshots -│ │ ├── board_store.py # Event-sourced board (entries + events) -│ │ ├── gateway.py # Capability-gated agent dispatch -│ │ ├── entry.py # Board entry schema + validation -│ │ ├── protocol.py # Agent ↔ Daemon message protocol -│ │ ├── salience.py # Entry salience scoring -│ │ ├── event_emitter.py # SSE event abstraction -│ │ ├── log_levels.py # Level normalization (INF→info, etc.) -│ │ ├── triage.py # Complexity classification client -│ │ └── variants/ -│ │ └── traditional.py # Cyclic CU → agents → board loop -│ └── routes/ -│ ├── submit.py # POST /submit -│ ├── tasks.py # GET /tasks, /tasks/{id}/* -│ ├── events.py # SSE endpoints (task + system) -│ ├── ingest.py # POST /ingest/traces, /ingest/logs -│ ├── artifacts.py # GET /tasks/{id}/artifacts -│ ├── files.py # GET /tasks/{id}/files -│ ├── hitl.py # POST /tasks/{id}/pause|resume|directive -│ └── health.py # GET /health -│ -├── mission-control/ # Next.js 16 dashboard (:9321) -│ └── src/ -│ ├── app/ -│ │ ├── page.tsx # Landing page — task list + submit -│ │ ├── task/[taskId]/ # Task-scoped pages (7 tabs) -│ │ │ ├── page.tsx # Overview — process summary + result -│ │ │ ├── dag/ # Execution Graph — TurnGraph (swimlane) -│ │ │ ├── logs/ # Distributed Log Stream + Agent Trace -│ │ │ ├── blackboard/ # Blackboard Board command center -│ │ │ ├── mission/ # Mission Cockpit (4-panel live view) -│ │ │ └── artifacts/ # Artifact browser + downloads -│ │ └── api/ # 20+ API route handlers (server-side proxies) -│ ├── components/ -│ │ ├── features/ # 18 feature components -│ │ │ ├── TurnGraph.tsx # Swimlane execution graph (React Flow) -│ │ │ ├── DistributedLogStream.tsx # Unified chronological logs -│ │ │ ├── BlackboardBoard.tsx # Board command center -│ │ │ ├── AgentTrace.tsx # Structured turn trace viewer -│ │ │ └── ... # + 14 more feature components -│ │ ├── ui/ # Design system primitives (9 components) -│ │ └── layout/ # App shell (TopBar) -│ ├── hooks/ -│ │ ├── useTaskStream.ts # SSE hook — 18 event types, rAF batching -│ │ ├── useSystemStream.ts # System-level SSE (task lifecycle) -│ │ └── useTaskHistory.ts # REST task list fetching -│ └── lib/ -│ ├── config.ts # Server-side config loader -│ ├── mappers.ts # SSE → component data transforms -│ └── design-tokens.ts # Programmatic design token access -│ -├── litellm/ # LiteLLM model gateway (:4000) -├── redis/ # Redis blackboard (:6379) -├── triage/ # Complexity classifier (:8001) -│ -├── docs/ # Documentation -│ ├── QUICKSTART.md # Get started in 5 minutes -│ ├── CONFIGURATION.md # Full config reference -│ ├── NODE_SETUP.md # Edge node provisioning guide -│ ├── architecture/ # System architecture deep-dive -│ └── design/ # Mission Control UI specification -│ -├── scripts/ # Operational utilities -│ ├── check-ci.sh # Local CI mirror (ruff + mypy + pytest + eslint + tsc + build) -│ ├── deploy_profiles.sh # Deploy Hermes profiles to agent nodes -│ └── healthcheck.sh # Post-deploy service health check -│ -└── examples/ # Example configurations - ├── stigmergic/ # Reference deployment (3-node homelab) - ├── minimal-cloud.yaml # Cloud-only, no GPU required - └── multi-provider.yaml# Gemini + Claude + OpenAI routing -``` +See [Quick Start Guide](docs/QUICKSTART.md) for the full walkthrough. ## Documentation | Document | Description | |:---|:---| -| [Architecture](docs/architecture/README.md) | System architecture & component deep-dive | | [Quick Start](docs/QUICKSTART.md) | Get running in 5 minutes | | [Configuration](docs/CONFIGURATION.md) | Full `bmas.yaml` reference | -| [Node Setup](docs/NODE_SETUP.md) | Provisioning edge nodes | +| [Architecture](docs/architecture/README.md) | System architecture & component deep-dive | +| [Node Setup](docs/NODE_SETUP.md) | Provisioning edge nodes with inference + agents | | [Design System](docs/design/DESIGN.md) | Mission Control UI specification | +| [Hermes API](docs/HERMES_API.md) | Hermes Dashboard & Gateway API reference | -### Component READMEs +## Components -| Component | README | +The project is organized into six deployable components, each with its own README: + +| Component | Description | +|:---|:---| +| [`daemon/`](daemon/README.md) | **The brain.** Python FastAPI orchestrator — manages task lifecycle, cyclic blackboard execution, agent dispatch, and dual-write persistence (Redis + SQLite). | +| [`mission-control/`](mission-control/README.md) | **The eyes.** Next.js 16 real-time dashboard — execution graphs, distributed logs, blackboard command center, cost tracking, and HITL controls. | +| [`agent/`](agent/README.md) | **The hands.** FastAPI server deployed to each edge node — bridges the Daemon to Hermes agents via the Runs API with real-time trace and log shipping. | +| [`redis/`](redis/README.md) | **The shared memory.** Redis 8 serves as the blackboard — the central knowledge store through which all agents coordinate via Pub/Sub, Streams, and Redlock. | +| [`litellm/`](litellm/README.md) | **The router.** Unified OpenAI-compatible gateway that abstracts all model backends behind routing, cost tracking, and retry logic. | +| [`triage/`](triage/README.md) | **The gatekeeper.** Local Qwen3-1.7B complexity classifier (vLLM) that routes tasks to the cheapest capable model before any paid API call. | + +Additional directories: + +| Directory | Description | |:---|:---| -| Agent | [agent/README.md](agent/README.md) | -| Daemon | [daemon/README.md](daemon/README.md) | -| Mission Control | [mission-control/README.md](mission-control/README.md) | -| LiteLLM | [litellm/README.md](litellm/README.md) | -| Redis | [redis/README.md](redis/README.md) | -| Triage | [triage/README.md](triage/README.md) | +| [`examples/`](examples/) | Sample configurations — multi-node homelab, minimal cloud, multi-provider routing | +| [`scripts/`](scripts/) | Operational utilities — CI checks, profile deployment, health checks | +| [`eval/`](eval/) | Evaluation harness — A/B testing, accuracy scoring, failure injection | +| [`docs/`](docs/) | All documentation — architecture, design system, guides | -## Paper +## Papers -This project is an implementation of the Blackboard Multi-Agent System (bMAS) architecture proposed in: +This project implements and extends multi-agent coordination architectures from published research: > **Han, B. & Zhang, S. (2025).** *Exploring Advanced LLM Multi-Agent Systems Based on Blackboard Architecture.* > [arXiv:2507.01701](https://arxiv.org/abs/2507.01701) -The paper introduces a framework where LLM agents coordinate through a shared blackboard with an LLM-driven control unit that dynamically selects agents per round — achieving competitive performance with state-of-the-art multi-agent systems while consuming fewer tokens. Stigmergic implements this architecture with the **traditional** coordination variant. +The foundational architecture. LLM agents coordinate through a shared blackboard with an LLM-driven control unit that dynamically selects agents per round — achieving competitive performance with state-of-the-art multi-agent systems while consuming fewer tokens. Stigmergic implements this as the **traditional** coordination variant. + +> **Zhang, S., Shi, W. & Wang, H. (2026).** *PatchBoard: Schema-Grounded State Mutation for Reliable and Auditable LLM Multi-Agent Collaboration.* +> [arXiv:2605.29313](https://arxiv.org/abs/2605.29313) + +A complementary coordination paradigm where agents emit validated JSON-Patch mutations against a schema-grounded state tree through a deterministic kernel — achieving 84.6% task success (vs. 30.8% for LangGraph) with zero committed-state contamination under fault injection. Stigmergic implements this as the **PatchBoard** coordination variant. ## License diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 25c2615..83a043f 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -37,7 +37,7 @@ Defines the machine running the Docker Compose stack. | `ports.litellm` | int | ✅ | — | LiteLLM proxy port. | | `ports.triage` | int | ❌ | `8001` | Triage vLLM port. | | `ports.daemon` | int | ✅ | — | Daemon API port. | -| `ports.dashboard` | int | ✅ | — | Mission Control dashboard port. | +| `ports.dashboard` | int | ❌ | `9321` | Mission Control dashboard port. | ```yaml control_plane: @@ -177,7 +177,7 @@ Controls the coordination paradigm used for multi-agent tasks. | Field | Type | Required | Default | Description | |:---|:---|:---|:---|:---| | `variant` | string | ✅ | — | Active variant: `traditional`, `patchboard`, or `stigmergic`. | -| `blackboard_v2` | bool | ❌ | `true` | Enables the v2 board substrate (entries + events). | +| `blackboard_v2` | bool | ❌ | `false` | Enables the v2 board substrate (entries + events). | | `view_budget_tokens` | int | ❌ | `12000` | Full-board token budget; budgeted view mode above this. | | `round_execution` | string | ❌ | `concurrent` | `concurrent` (parallel agents) or `sequential` (paper-exact). | diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md index 5a79310..c079ca5 100644 --- a/docs/QUICKSTART.md +++ b/docs/QUICKSTART.md @@ -57,7 +57,7 @@ Fill in your secrets: REDIS_PASSWORD=your-secure-password LITELLM_MASTER_KEY=sk-your-litellm-key GEMINI_API_KEY=your-gemini-key -BMAS_NODE_KEY=your-node-auth-token # For agent ingest auth +BMAS_NODE_KEY= # Generate with: openssl rand -hex 32 ``` ## 3. Start the Swarm diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..052095a --- /dev/null +++ b/docs/README.md @@ -0,0 +1,19 @@ +# Documentation + +[← Back to Project](../README.md) + +## Guides + +| Document | Description | +|:---|:---| +| [Quick Start](QUICKSTART.md) | Get running in 5 minutes | +| [Configuration](CONFIGURATION.md) | Full `bmas.yaml` reference | +| [Node Setup](NODE_SETUP.md) | Provisioning edge nodes with inference + agents | +| [Hermes API](HERMES_API.md) | Hermes Dashboard & Gateway API reference | + +## Reference + +| Document | Description | +|:---|:---| +| [Architecture](architecture/README.md) | System architecture & component deep-dive | +| [Design System](design/DESIGN.md) | Mission Control UI specification | diff --git a/docs/architecture/README.md b/docs/architecture/README.md index dd214f5..d20a5bc 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -157,7 +157,7 @@ daemon/src/ | Aspect | Detail | |:---|:---| -| **Image** | `redis:7-alpine` | +| **Image** | `redis:8-alpine` | | **Port** | 6379 | | **Memory** | 1 GB `maxmemory` (2 GB container limit) | | **Persistence** | RDB snapshots every 60s if ≥100 keys changed | @@ -536,7 +536,7 @@ The Dashboard proxies hardware metrics from [Beszel Hub](https://github.com/henr |:---|:---|:---|:---| | **Orchestrator** | Python + FastAPI + Uvicorn | 3.13+ | Task lifecycle, API, dispatch | | **Persistence** | SQLite (aiosqlite) | v2 schema | Permanent task history (12 tables) | -| **Blackboard** | Redis | 7-alpine | Real-time state, Pub/Sub, Streams, locks | +| **Blackboard** | Redis | 8-alpine | Real-time state, Pub/Sub, Streams, locks | | **Model Gateway** | LiteLLM | latest | Unified model routing + cost tracking | | **Triage** | vLLM + Qwen3-1.7B | latest | Complexity classification | | **Agent Runtime** | Hermes CLI / Runs API | — | LLM agent execution on edge nodes | @@ -557,4 +557,5 @@ The Dashboard proxies hardware metrics from [Beszel Hub](https://github.com/henr ## References - **Han, B. & Zhang, S. (2025).** *Exploring Advanced LLM Multi-Agent Systems Based on Blackboard Architecture.* [arXiv:2507.01701](https://arxiv.org/abs/2507.01701) — The foundational paper for the bMAS architecture. +- **Zhang, S., Shi, W. & Wang, H. (2026).** *PatchBoard: Schema-Grounded State Mutation for Reliable and Auditable LLM Multi-Agent Collaboration.* [arXiv:2605.29313](https://arxiv.org/abs/2605.29313) — The PatchBoard coordination variant. - [Stigmergy (Wikipedia)](https://en.wikipedia.org/wiki/Stigmergy) — The coordination mechanism this system is named after. diff --git a/docs/design/DESIGN.md b/docs/design/DESIGN.md index b135f5d..a6b755d 100644 --- a/docs/design/DESIGN.md +++ b/docs/design/DESIGN.md @@ -1,8 +1,8 @@ -[🏠 Index](../README.md) | [📋 Context](../examples/stigmergic/CONTEXT.md) +[🏠 Index](../README.md) | [📋 Context](../../examples/stigmergic/CONTEXT.md) # Mission Control — Design System -> [!ABSTRACT] Purpose +> [!NOTE] Purpose > This document is the **single source of truth** for Mission Control's visual language. Every component, every screen, every interaction should reference this spec to maintain enterprise-grade consistency. This is not a component library — it is the design contract that any implementation (human or AI) must follow. > > **Inspiration benchmarks:** Notion (information density + clean hierarchy), Airbnb (typography + whitespace mastery), Linear (real-time ops dashboard), Vercel (dark-mode polish). @@ -192,7 +192,7 @@ Shadows are used **sparingly** — only for floating elements (modals, popovers, ## 5. Component Patterns -These are the **reusable primitives** that every feature component must be composed from. Building feature components directly from raw HTML/Tailwind (without using these primitives) violates the design contract. +These are the **reusable primitives** that every feature component must be composed from. Building feature components directly from raw HTML/CSS (without using these primitives) violates the design contract. ### 5.1 Panel @@ -240,9 +240,9 @@ Wrapper for the xterm.js terminal instances. Gives each terminal an identity. - **Body:** xterm.js fills remaining height. Border: 1px `--border-default`. Border radius bottom: `--radius-xl`. - **Border-top accent:** 2px solid line in the agent's identity color across the full width. -### 5.5 DebateList +### 5.5 DebateThread -Used by the Blackboard/Debate tab. Chronological list of debate entries from the agent deliberation process. Replaces the old SplitView (Public/Private Redis split). +Used by the Blackboard/Mission tab. Chronological list of debate entries from the agent deliberation process. - **Layout:** Vertical list of debate entries, newest at the bottom. Each entry shows: agent role identity (colored dot + name), content (text/markdown), timestamp. - **Agent identity:** 8px circle dot in the agent's `--agent-{role}` color + role name in `--text-sm`. @@ -307,10 +307,10 @@ Mission Control uses a **task-centric architecture** — the sidebar shows task │ ✓ task-b │ │ │ ✗ task-c │ B) Task Detail (route: /task/[id]) │ │──────────│ ┌─ Header: label, status, cost ─┐ │ -│ YESTERDAY│ │ [Overview][DAG][Logs][Board][$$]│ │ +│ YESTERDAY│ │ [Overview][Board][Graph][Logs] │ │ │ ✓ task-d │ ├─────────────────────────────────┤ │ │──────────│ │ Tab content fills this area │ │ -│ ─System─ │ │ (DAG, Logs, Blackboard, Cost) │ │ +│ ─System─ │ │ (Board, Graph, Logs, Artifacts)│ │ │ 📡 Infra │ └─────────────────────────────────┘ │ │ ✨ Skills│ │ │──────────│ │ @@ -342,16 +342,16 @@ Replaced from feature-navigation to **task-history sidebar**. The main area renders Next.js App Router pages based on the URL: -| Route | Content | -|:---|:---| -| `/` | Landing page — conversational task input with auto-resize textarea, inline send button, and recent task history cards | -| `/task/[taskId]` | Task overview — result display, sub-task progress, live phase indicator | -| `/task/[taskId]/dag` | DAG visualization — React Flow canvas showing task decomposition graph | -| `/task/[taskId]/logs` | Log terminals — 3-column (or tabbed on mobile) xterm.js terminals filtered by agent role | -| `/task/[taskId]/blackboard` | Debate history — chronological list of agent debate entries with typing indicators | -| `/task/[taskId]/cost` | Cost breakdown — per-phase and per-model cost tables with MetricCard heroes | -| `/infra` | Infrastructure telemetry — Beszel Hub metrics for all nodes | -| `/skills` | Skills explorer — per-agent skill lists with view/delete actions | +| Route | Tab Label | Content | +|:---|:---|:---| +| `/` | — | Landing page — conversational task input with auto-resize textarea, inline send button, and recent task history cards | +| `/task/[taskId]` | Overview | Task overview — result display (rendered markdown), sub-task progress, convergence strip, and live phase indicator | +| `/task/[taskId]/mission` | Blackboard | Mission cockpit — 4-panel live layout with blackboard board (timeline/threads/graph views), agent minds, budget gauge, convergence meter, and HITL controls | +| `/task/[taskId]/dag` | Graph | Execution graph — React Flow canvas with swimlane visualization of agent turns grouped by round | +| `/task/[taskId]/logs` | Logs | Distributed log stream — unified chronological log across all agents with per-role filtering and structured detail drawer | +| `/task/[taskId]/artifacts` | Artifacts | Artifact browser — file tree + downloads for agent-produced output files | +| `/infra` | — | Infrastructure telemetry — Beszel Hub metrics for all nodes | +| `/skills` | — | Skills explorer — per-agent skill lists with view/delete actions | All `/task/[taskId]/*` pages share a **task detail layout** (`task/[taskId]/layout.tsx`) that renders the task header + tab navigation and hosts the `TaskStreamContext.Provider` for SSE data distribution. Tab switches are instantaneous DOM swaps — the SSE connection persists in the layout. @@ -456,11 +456,12 @@ src/ │ ├── task/ │ │ └── [taskId]/ │ │ ├── layout.tsx # Task detail layout: header + tabs + TaskStreamContext.Provider +│ │ ├── TaskStreamContext.tsx # Distributes SSE data from useTaskStream to tab pages │ │ ├── page.tsx # Overview tab (default) -│ │ ├── dag/page.tsx # DAG visualization -│ │ ├── logs/page.tsx # Log terminals (3 columns) -│ │ ├── blackboard/page.tsx # Debate history -│ │ └── cost/page.tsx # Cost breakdown +│ │ ├── mission/page.tsx # Blackboard — 4-panel live cockpit +│ │ ├── dag/page.tsx # Graph — execution graph (React Flow) +│ │ ├── logs/page.tsx # Logs — distributed log stream +│ │ └── artifacts/page.tsx # Artifacts — file tree + downloads │ ├── infra/page.tsx # Infrastructure telemetry │ └── skills/page.tsx # Skills explorer ├── components/ @@ -469,17 +470,40 @@ src/ │ │ ├── StatusBadge.tsx │ │ ├── MetricCard.tsx │ │ ├── TerminalPane.tsx +│ │ ├── TaskSidebar.tsx # Task history sidebar + system nav │ │ ├── ActionButton.tsx │ │ ├── Skeleton.tsx │ │ ├── EmptyState.tsx +│ │ ├── InfoTooltip.tsx +│ │ ├── RichContent.tsx │ │ └── Toast.tsx -│ ├── TopBar.tsx # "use client" — daemon status, cost ticker -│ ├── TaskSidebar.tsx # "use client" — task history, system nav -│ ├── DAGVisualizer.tsx # Feature: React Flow canvas -│ ├── LogTerminal.tsx # Feature: xterm.js + TerminalPane -│ └── DebateList.tsx # Feature: debate entries + typing indicator +│ ├── layout/ +│ │ └── TopBar.tsx # "use client" — daemon status, cost ticker +│ └── features/ # Feature components composed from ui/ primitives +│ ├── TurnGraph.tsx # Execution graph — React Flow swimlane canvas +│ ├── DistributedLogStream.tsx # Log stream — TanStack Virtual with detail drawer +│ ├── BlackboardBoard.tsx # Board — timeline/threads/graph views +│ ├── BlackboardGraph.tsx # Board graph — visual entry relationships +│ ├── BudgetGauge.tsx # Cost tracking gauge +│ ├── ConsensusMeter.tsx # Convergence progress meter +│ ├── ConvergenceStrip.tsx # Round-by-round convergence indicator +│ ├── AgentTrace.tsx # Agent trace inspector +│ ├── AgentMindCard.tsx # Agent model/contribution card +│ ├── ArtifactBrowser.tsx # Artifact file tree + downloads +│ ├── AttachmentRail.tsx # File attachment display +│ ├── SkillsExplorer.tsx # Per-agent skill lists +│ ├── Telemetry.tsx # Hardware telemetry gauges +│ ├── VariantSelect.tsx # Coordination variant selector +│ ├── TurnInspector.tsx # Turn detail drawer +│ ├── WorkerLane.tsx # Per-worker execution lane +│ ├── GlobalFirehose.tsx # Cross-task log stream +│ ├── ReplayScrubber.tsx # Temporal replay controls +│ ├── ToolCallCard.tsx # Tool call detail card +│ └── board/ +│ ├── BoardEntryCard.tsx # Individual board entry card +│ ├── BoardEntryDetail.tsx # Expanded entry view +│ └── DebateThread.tsx # Threaded debate entries ├── contexts/ -│ ├── TaskStreamContext.tsx # Distributes SSE data from useTaskStream to tab pages │ └── PendingTaskContext.tsx # Optimistic UI: ephemeral submitted-text context ├── hooks/ │ ├── useTaskStream.ts # SSE hook for /api/stream/task/[taskId] (logs, phase, debate, etc.) @@ -493,7 +517,7 @@ src/ > Feature components (DAG, Logs, Debate, etc.) must **not** directly use raw CSS for layout, backgrounds, or spacing. They compose from the `ui/` primitives, which themselves use the token system. This creates one layer of indirection that makes future redesigns possible without touching feature logic. > [!IMPORTANT] SSE Data Flow -> The `useTaskStream` hook is called **once** in `task/[taskId]/layout.tsx` and distributed via `TaskStreamContext.Provider`. Individual tab pages consume data via `useTaskData()` — they never create their own `EventSource` connections. This prevents the "tab switch tear" where SSE reconnects cause 200-500ms flickers. +> The `useTaskStream` hook is called **once** in `task/[taskId]/layout.tsx` and distributed via `TaskStreamContext.Provider` (co-located at `task/[taskId]/TaskStreamContext.tsx`). Individual tab pages consume data via `useTaskData()` — they never create their own `EventSource` connections. This prevents the "tab switch tear" where SSE reconnects cause 200-500ms flickers. --- diff --git a/docs/screenshots/bmas-board.png b/docs/screenshots/bmas-board.png new file mode 100644 index 0000000..0a651b7 Binary files /dev/null and b/docs/screenshots/bmas-board.png differ diff --git a/docs/screenshots/bmas-graph.png b/docs/screenshots/bmas-graph.png new file mode 100644 index 0000000..cc2c6b2 Binary files /dev/null and b/docs/screenshots/bmas-graph.png differ diff --git a/docs/screenshots/bmas-hero.png b/docs/screenshots/bmas-hero.png new file mode 100644 index 0000000..9570550 Binary files /dev/null and b/docs/screenshots/bmas-hero.png differ diff --git a/docs/screenshots/bmas-logs.png b/docs/screenshots/bmas-logs.png new file mode 100644 index 0000000..387190d Binary files /dev/null and b/docs/screenshots/bmas-logs.png differ diff --git a/docs/screenshots/bmas-stats.png b/docs/screenshots/bmas-stats.png new file mode 100644 index 0000000..3a3e8e4 Binary files /dev/null and b/docs/screenshots/bmas-stats.png differ diff --git a/mission-control/src/app/layout.tsx b/mission-control/src/app/layout.tsx index b30d000..1df73a0 100644 --- a/mission-control/src/app/layout.tsx +++ b/mission-control/src/app/layout.tsx @@ -35,7 +35,7 @@ export async function generateMetadata(): Promise { keywords: [ "bMAS", "Multi-Agent Swarm", - "Biomimetic AI", + "Blackboard AI", "Stigmergy", "Decentralized AI Swarm", "Autonomous Agents", diff --git a/mission-control/src/app/manifest.ts b/mission-control/src/app/manifest.ts index f19979a..08a0f00 100644 --- a/mission-control/src/app/manifest.ts +++ b/mission-control/src/app/manifest.ts @@ -2,7 +2,7 @@ import type { MetadataRoute } from "next"; export default function manifest(): MetadataRoute.Manifest { return { - name: "Biomimetic Multi-Agent Swarm (bMAS)", + name: "Blackboard Multi-Agent Swarm (bMAS)", short_name: "bMAS", description: "A decentralized swarm of autonomous agents collaborating to execute tasks based on stigmergy and local interactions.", start_url: "/", diff --git a/scripts/generate_icons.py b/scripts/generate_icons.py deleted file mode 100644 index cb11b6a..0000000 --- a/scripts/generate_icons.py +++ /dev/null @@ -1,38 +0,0 @@ -import os -from PIL import Image - -src_path = "/opt/bmas/mission-control/public/ant-head.png" -public_dir = "/opt/bmas/mission-control/public" -app_dir = "/opt/bmas/mission-control/src/app" - -# Open the source image -img = Image.open(src_path) - -# 1. Save favicon.ico (multi-size ICO) -img.save( - os.path.join(public_dir, "favicon.ico"), - format="ICO", - sizes=[(16, 16), (32, 32), (48, 48)], -) -img.save( - os.path.join(app_dir, "favicon.ico"), - format="ICO", - sizes=[(16, 16), (32, 32), (48, 48)], -) -print("Generated favicon.ico (multi-size)") - -# 2. Resized PNGs -sizes_map = { - os.path.join(public_dir, "favicon-16x16.png"): (16, 16), - os.path.join(public_dir, "favicon-32x32.png"): (32, 32), - os.path.join(public_dir, "apple-touch-icon.png"): (180, 180), - os.path.join(public_dir, "android-chrome-192x192.png"): (192, 192), - os.path.join(public_dir, "android-chrome-512x512.png"): (512, 512), - os.path.join(app_dir, "icon.png"): (32, 32), - os.path.join(app_dir, "apple-icon.png"): (180, 180), -} - -for path, size in sizes_map.items(): - resized = img.resize(size, Image.Resampling.LANCZOS) - resized.save(path, format="PNG") - print(f"Generated: {path} ({size[0]}x{size[1]})") diff --git a/scripts/rebuild.sh b/scripts/rebuild.sh deleted file mode 100644 index 91936d3..0000000 --- a/scripts/rebuild.sh +++ /dev/null @@ -1,32 +0,0 @@ -#!/usr/bin/env bash -# Full clean rebuild and restart of all bMAS services -set -euo pipefail - -cd /opt/bmas - -echo "=== Stopping all containers ===" -docker compose down --remove-orphans 2>&1 || true - -echo "" -echo "=== Rebuilding all images (no cache) ===" -docker compose build --no-cache 2>&1 - -echo "" -echo "=== Starting all services ===" -docker compose up -d 2>&1 - -echo "" -echo "=== Waiting for health checks (30s) ===" -sleep 30 - -echo "" -echo "=== Container status ===" -docker ps -a --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}' 2>&1 - -echo "" -echo "=== Quick API check ===" -curl -s -o /dev/null -w "Dashboard: HTTP %{http_code}\n" http://localhost:9321/ 2>&1 || echo "Dashboard: not responding yet" -curl -s -o /dev/null -w "Daemon API: HTTP %{http_code}\n" http://localhost:9000/tasks?limit=1 2>&1 || echo "Daemon: not responding yet" - -echo "" -echo "=== REBUILD COMPLETE ==="