beadboard/docs/features/agent-sessions.md

# 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