Merge pull request #11 from zenchantlive/docs/auto-update-20260216
docs: document Agent Sessions Hub, Timeline, and API endpoints
This commit is contained in:
zenchantlive
GitHub
commit
b201495f48
3 changed files with 428 additions and 0 deletions
15
README.md
15
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
|
||||
|
|
|
|||
283
docs/api-reference.md
Normal file
283
docs/api-reference.md
Normal file
|
|
@ -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.
|
||||
130
docs/features/agent-sessions.md
Normal file
130
docs/features/agent-sessions.md
Normal file
|
|
@ -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 <name> --role <role>` - Register agent identity
|
||||
- `bb agent send --from <sender> --to <recipient> --bead <id> --category <type>` - Send message
|
||||
- `bb agent inbox --agent <name>` - Check messages
|
||||
- `bb agent reserve --agent <name> --scope <glob> --bead <id>` - Reserve files
|
||||
- `bb agent status --bead <id>` - 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
|
||||
Loading…
Add table
Add a link
Reference in a new issue