diff --git a/README.md b/README.md index 57cd744..afe7406 100644 --- a/README.md +++ b/README.md @@ -36,6 +36,21 @@ Understand the "Why" and "What's Next". - **Focus Mode**: Minimizable dependency strip and deep-linking support for sharing exact views. - **Smart Metadata**: See bead counts, priorities, and status health at a glance. +### 4. Agent Sessions Hub (`/sessions`) +Coordinate multi-agent workflows with social-dense visibility. +- **Epic-Grouped Task Feed**: Tasks organized by parent Epic with session state indicators (active, reviewing, needs_input, stale). +- **Cross-Agent Communication**: Built-in messaging with HANDOFF, BLOCKED, and INFO categories. +- **Agent Productivity Metrics**: Real-time stats showing active tasks, completions, and recent wins. +- **Derived Activity Engine**: O(N) snapshot diffing computes project history on-demand without separate event storage. +- **`bb agent` CLI Integration**: Visualizes data from agent registry, reservations, and mailboxes. + +### 5. Chronological Timeline (`/timeline`) +Real-time activity feed for all project events. +- **Live Updates**: Server-Sent Events stream changes instantly. +- **Date Grouping**: Events organized by day (Today, Yesterday, etc.). +- **Polymorphic Cards**: Distinct visual styles for Status, Lifecycle, and Diff events. +- **History Buffer**: Recent events preserved across server restarts. + ## 🛠️ Stack - **Framework**: Next.js 15 (App Router) - **UI Engine**: React 19 + Framer Motion diff --git a/docs/api-reference.md b/docs/api-reference.md new file mode 100644 index 0000000..b6c5420 --- /dev/null +++ b/docs/api-reference.md @@ -0,0 +1,283 @@ +# BeadBoard API Reference + +## Overview +BeadBoard exposes REST endpoints for reading bead data, managing agent coordination, and streaming real-time activity. All endpoints return JSON (unless noted otherwise). + +## Bead Management + +### `GET /api/beads/read` +Read beads from the current or specified project. + +**Query Parameters:** +- `project` (optional): Project key for scope resolution +- `mode` (optional): `single` or `aggregate` + +**Response:** +```json +{ + "issues": [...], + "projectRoot": "/path/to/project" +} +``` + +### `POST /api/beads/create` +Create a new bead. + +**Body:** +```json +{ + "title": "Task title", + "description": "Optional description", + "status": "open", + "priority": "p2", + "issue_type": "task" +} +``` + +### `POST /api/beads/update` +Update an existing bead. + +**Body:** +```json +{ + "id": "bb-abc", + "updates": { + "status": "in_progress", + "assignee": "agent-1" + } +} +``` + +### `POST /api/beads/close` +Close a bead. + +**Body:** +```json +{ + "id": "bb-abc", + "reason": "Completion reason" +} +``` + +### `POST /api/beads/reopen` +Reopen a closed bead. + +**Body:** +```json +{ + "id": "bb-abc" +} +``` + +### `POST /api/beads/comment` +Add a comment to a bead. + +**Body:** +```json +{ + "id": "bb-abc", + "comment": "Comment text", + "author": "agent-1" +} +``` + +## Agent Coordination + +### `GET /api/agents/[agentId]/stats` +Fetch productivity metrics for a specific agent. + +**Path Parameters:** +- `agentId`: Agent identifier + +**Response:** +```json +{ + "activeTasks": 3, + "completedTasks": 12, + "handoffsSent": 8, + "recentWins": [ + { "id": "bb-xyz", "title": "Task title" } + ] +} +``` + +### `GET /api/sessions` +Fetch the agent sessions task feed. + +**Query Parameters:** +- `project` (optional): Project scope +- `mode` (optional): `single` or `aggregate` + +**Response:** +```json +{ + "buckets": [ + { + "epic": { + "id": "bb-epic", + "title": "Epic Title", + "status": "open" + }, + "tasks": [ + { + "id": "bb-task", + "title": "Task Title", + "epicId": "bb-epic", + "status": "in_progress", + "sessionState": "active", + "owner": "agent-1", + "lastActor": "agent-1", + "lastActivityAt": "2026-02-16T05:00:00Z", + "communication": { + "unreadCount": 2, + "pendingRequired": true, + "latestSnippet": "Blocked on API" + } + } + ] + } + ] +} +``` + +### `GET /api/sessions/[beadId]/conversation` +Get the full conversation thread for a bead, including comments and agent messages. + +**Path Parameters:** +- `beadId`: Bead identifier + +**Response:** +```json +{ + "comments": [...], + "messages": [...] +} +``` + +### `POST /api/sessions/[beadId]/comment` +Add a comment to a bead session. + +**Path Parameters:** +- `beadId`: Bead identifier + +**Body:** +```json +{ + "comment": "Comment text", + "author": "agent-1" +} +``` + +### `POST /api/sessions/[beadId]/messages/[messageId]/read` +Mark an agent message as read. + +**Path Parameters:** +- `beadId`: Bead identifier +- `messageId`: Message identifier + +### `POST /api/sessions/[beadId]/messages/[messageId]/ack` +Acknowledge an agent message (required for HANDOFF/BLOCKED categories). + +**Path Parameters:** +- `beadId`: Bead identifier +- `messageId`: Message identifier + +## Activity & Events + +### `GET /api/activity` +Fetch recent activity events (history buffer). + +**Response:** +```json +{ + "events": [ + { + "id": "evt-123", + "beadId": "bb-abc", + "kind": "status_changed", + "actor": "agent-1", + "timestamp": "2026-02-16T05:00:00Z", + "changes": { + "from": "todo", + "to": "in_progress" + } + } + ] +} +``` + +### `GET /api/events` +Server-Sent Events stream for real-time activity. + +**Response:** SSE stream with `event` and `data` fields. + +**Event Types:** +- `activity`: New activity event +- `bead_updated`: Bead state changed +- `agent_registered`: New agent registered + +## Project Management + +### `GET /api/projects` +List all registered projects. + +**Response:** +```json +{ + "projects": [ + { + "key": "proj-1", + "root": "/path/to/project", + "name": "Project Name" + } + ] +} +``` + +### `POST /api/scan` +Scan filesystem for bead-enabled projects. + +**Body:** +```json +{ + "paths": ["/path/to/scan"] +} +``` + +**Response:** +```json +{ + "discovered": [ + { + "root": "/path/to/project", + "beadCount": 42 + } + ] +} +``` + +## Error Handling + +All endpoints follow a consistent error format: + +```json +{ + "error": "Error message", + "code": "ERROR_CODE", + "details": {} +} +``` + +**Common Error Codes:** +- `INVALID_REQUEST`: Malformed request body or parameters +- `NOT_FOUND`: Resource does not exist +- `PERMISSION_DENIED`: Operation not allowed +- `INTERNAL_ERROR`: Server-side error + +## Rate Limiting + +No rate limiting is currently enforced for local BeadBoard instances. If deploying publicly, implement rate limiting externally. + +## Authentication + +BeadBoard runs as a local dashboard with no authentication. If exposing over a network, secure access using reverse proxy authentication or network isolation. diff --git a/docs/features/agent-sessions.md b/docs/features/agent-sessions.md new file mode 100644 index 0000000..66d8e69 --- /dev/null +++ b/docs/features/agent-sessions.md @@ -0,0 +1,130 @@ +# Agent Sessions Hub + +## Overview +The Agent Sessions Hub (`/sessions`) provides a unified command workspace for tracking multi-agent coordination across your BeadBoard projects. It combines task status, agent communication, and derived activity into a social-dense interface optimized for understanding "who's doing what" at a glance. + +## Features + +### 1. Epic-Grouped Task Feed +Tasks are automatically organized by their parent Epic, providing logical context for understanding work scope. + +- **Session State Indicators**: Each task displays its real-time state (active, reviewing, needs_input, completed, stale) +- **Owner & Actor Tracking**: See who owns the task and who last acted on it +- **Communication Badges**: Unread message counts and pending acknowledgment flags + +### 2. Agent Communication Integration +Built-in cross-agent messaging system for coordination without leaving the dashboard. + +**Message Types:** +- `HANDOFF` - Pass context to another agent +- `BLOCKED` - Request help or flag blockers +- `INFO` - Share updates or documentation + +**Communication Features:** +- Inbox view with unread/read/acked states +- Required acknowledgments for critical handoffs +- Per-bead conversation threads + +### 3. Agent Statistics & Productivity Metrics +Real-time performance tracking for each registered agent. + +**Metrics Tracked:** +- Active tasks (currently in progress) +- Completed tasks (closed beads) +- Handoffs sent (coordination events) +- Recent wins (last 3 completed tasks) + +### 4. Derived Activity Engine +Instead of storing history separately, BeadBoard computes activity on-demand by diffing snapshots of `issues.jsonl`. + +**Event Types Generated:** +- Bead lifecycle: created, closed, reopened +- Status changes: todo → in_progress → done +- Assignee changes +- Priority, title, description updates +- Label and dependency changes + +**Persistence:** +- File-backed ring buffer survives server restarts +- O(N) snapshot diffing algorithm +- No separate event database required + +## Architecture + +### Backend Components +- **Agent Registry** (`src/lib/agent-registry.ts`): Maintains agent identity and roles +- **Agent Mail** (`src/lib/agent-mail.ts`): Cross-agent messaging with inbox/ack protocol +- **Agent Reservations** (`src/lib/agent-reservations.ts`): File/scope locking to prevent collisions +- **Agent Sessions** (`src/lib/agent-sessions.ts`): Session state derivation and task feed builder +- **Snapshot Differ** (`src/lib/snapshot-differ.ts`): O(N) diffing engine for activity events +- **Activity Persistence** (`src/lib/activity-persistence.ts`): File-backed event buffer + +### API Endpoints +- `GET /api/sessions` - Fetch session task feed +- `GET /api/sessions/[beadId]/conversation` - Get full conversation thread for a bead +- `POST /api/sessions/[beadId]/comment` - Add a comment to a bead session +- `POST /api/sessions/[beadId]/messages/[messageId]/read` - Mark message as read +- `POST /api/sessions/[beadId]/messages/[messageId]/ack` - Acknowledge message +- `GET /api/agents/[agentId]/stats` - Fetch agent productivity metrics + +### Frontend Components +- **SessionsPage** (`src/components/sessions/sessions-page.tsx`): Main layout and orchestration +- **TaskCard** components: Visual representation of session state +- **AgentStatsPanel**: Metrics dashboard per agent + +## Session States + +Tasks automatically transition between states based on activity and communication: + +| State | Description | Visual Indicator | +|-------|-------------|------------------| +| `active` | Status is `in_progress`, recent activity | Green pulse | +| `reviewing` | Under review or verification | Blue | +| `deciding` | Status is `todo` or `ready`, waiting for claim | Gray | +| `needs_input` | Status is `blocked` or has pending required acknowledgments | Yellow/Orange | +| `completed` | Status is `closed` | Green checkmark | +| `stale` | No activity in 24+ hours | Faded/Red | + +## Integration with `bb agent` CLI + +The Sessions Hub visualizes data managed by the `bb agent` command-line interface. See `docs/agent-session-flow.md` for the operator workflow. + +**Key Commands:** +- `bb agent register --name --role ` - Register agent identity +- `bb agent send --from --to --bead --category ` - Send message +- `bb agent inbox --agent ` - Check messages +- `bb agent reserve --agent --scope --bead ` - Reserve files +- `bb agent status --bead ` - Check reservation status + +## Data Flow + +1. **Source of Truth**: `.beads/issues.jsonl` via `bd` CLI +2. **Activity Generation**: Watcher detects changes → snapshot differ → event bus +3. **Agent Coordination**: `bb` CLI writes to `.beads/agents/` directory +4. **UI Refresh**: SSE stream (`/api/events`) pushes updates to frontend in real-time + +## Configuration + +No configuration required. The Sessions Hub automatically: +- Discovers registered agents from `.beads/agents/` +- Builds communication graph from mailboxes +- Derives session states from current bead status + activity + +## Performance + +- **O(N) Diffing**: Snapshot differ scales linearly with number of beads +- **Ring Buffer**: Activity persistence uses fixed-size memory buffer (configurable) +- **Real-time Updates**: SSE keeps UI synchronized without polling + +## Limitations + +- Comment interactions are not yet streamed to the timeline +- Cross-project agent coordination requires agents to be registered in each project +- Stale threshold is fixed at 24 hours (not user-configurable) + +## Related Documentation + +- `docs/agent-session-flow.md` - CLI workflow guide for operators +- `docs/features/timeline.md` - Chronological activity feed +- `docs/RFC-001-Agent-Coordination.md` - Agent coordination design +- `docs/adr/2026-02-14-beadboard-driver-skill-and-bb-resolution.md` - beadboard-driver skill