agent-relay 1.2.0 → 1.3.0

package/docs/archive/ROADMAP.md

@@ -1,329 +0,0 @@
-# Agent Relay Roadmap
-
-This roadmap tracks planned improvements, bug fixes, and new features for agent-relay. Issues are tracked in [Beads](https://github.com/steveyegge/beads).
-
-**Last Updated:** 2025-12-20
-
----
-
-## Overview
-
-| Category | Open | In Progress |
-|----------|------|-------------|
-| Bugs | 4 | 0 |
-| Features | 7 | 1 |
-| Tasks | 7 | 1 |
-| **Total** | **18** | **2** |
-
----
-
-## Bugs
-
-### `agent-relay-ahe` Session resume not implemented
-**Status:** Open | **Priority:** P2
-
-Session resume tokens are received but not persisted or validated. The server always responds with `RESUME_TOO_OLD`, breaking the resume capability advertised in the protocol.
-
-**Location:** `src/daemon/connection.ts:140-143`
-
-**Required Work:**
-- Implement token persistence
-- Add session state recovery
-- Validate resume tokens on reconnect
-
----
-
-### `agent-relay-5af` Hook doesn't integrate with daemon-based messaging
-**Status:** Open | **Priority:** P2
-
-The inbox-check hook reads from file-based inbox but the daemon uses SQLite. When using daemon mode, the hook won't see messages.
-
-**Location:** `src/hooks/inbox-check/hook.ts`
-
-**Required Work:**
-- Query daemon storage from hook, OR
-- Ensure inbox files are written in daemon mode too
-
----
-
-### `agent-relay-6rz` Message injection timing can cause race conditions
-**Status:** Open | **Priority:** P2
-
-Injection waits for 'idle' (1.5s since last output) but this is fragile. If agent produces output during injection, messages could interleave.
-
-**Location:** `src/wrapper/tmux-wrapper.ts:564-569`
-
-**Required Work:**
-- Input buffer detection
-- Bracketed paste mode support
-- Agent-specific injection strategies
-
----
-
-### `agent-relay-8nx` SIGINT/SIGTERM handlers don't await cleanup
-**Status:** Open | **Priority:** P2
-
-SIGINT handlers call `stop()` but `process.exit(0)` runs immediately. The `stop()` is async but not awaited, potentially leaving socket files or incomplete shutdown.
-
-**Location:** `src/cli/index.ts:74-77`
-
-**Required Work:**
-- Await async cleanup before exit
-- Ensure socket files are removed
-- Add timeout for cleanup operations
-
----
-
-## Features
-
-### `agent-relay-ghy` Team config: auto-spawn agents from teams.json
-**Status:** In Progress | **Priority:** P2
-
-When a project has a `teams.json` config file, `agent-relay up` should either auto-spawn terminal sessions for each agent or validate names against the config.
-
-**teams.json format:**
-```json
-{
-  "team": "my-project",
-  "agents": [
-    {"name": "Coordinator", "cli": "claude", "role": "coordinator"},
-    {"name": "LeadDev", "cli": "claude", "role": "developer"}
-  ],
-  "autoSpawn": false
-}
-```
-
-**Commands:**
-- `agent-relay up --spawn` - force spawn all agents
-- `agent-relay up --no-spawn` - just start daemon, manual agent starts
-
----
-
-### `agent-relay-2z1` ACK messages not used for reliability
-**Status:** Open | **Priority:** P2
-
-ACK messages are accepted but not processed. The protocol supports reliable delivery with ACK/NACK but it's not implemented.
-
-**Location:** `src/daemon/connection.ts:114-116`
-
-**Required Work:**
-- Track unACKed messages
-- Implement retry logic
-- Add configurable TTL for messages
-
----
-
-### `agent-relay-go9` PostgreSQL storage adapter
-**Status:** Open | **Priority:** P2
-
-PostgreSQL is listed as a storage option but throws "not yet implemented". For production multi-node deployments, SQLite won't scale.
-
-**Location:** `src/storage/adapter.ts:152-162`
-
-**Required Work:**
-- Implement PostgreSQL adapter
-- Add connection pooling
-- Support distributed storage for multi-node setups
-
----
-
-### `agent-relay-sio` Graceful degradation when daemon unavailable
-**Status:** Open | **Priority:** P2
-
-Daemon connection failures are silently caught with no recovery mechanism.
-
-**Location:** `src/wrapper/tmux-wrapper.ts:195-197`
-
-**Required Work:**
-- Periodic reconnection attempts
-- Queue messages for later delivery
-- Visual indicator in terminal showing connection status
-
----
-
-### `agent-relay-dyr` Authentication between agents
-**Status:** Open | **Priority:** P2
-
-Any process can connect to the daemon socket and impersonate any agent name. No authentication exists.
-
-**Required Work:**
-- Per-agent tokens/secrets
-- Socket permission checks
-- Optional TLS for non-localhost deployments
-
----
-
-### `agent-relay-0bn` Dashboard real-time connection status
-**Status:** Open | **Priority:** P2
-
-Dashboard shows agent status from messages but doesn't show live connection status (connected/disconnected).
-
-**Required Work:**
-- Show online/offline indicators
-- Display last-seen timestamps
-- Real-time connection state from daemon
-
----
-
-### `agent-relay-52d` Metrics/observability for daemon
-**Status:** Open | **Priority:** P2
-
-No way to monitor daemon health, message throughput, or agent activity.
-
-**Required Work:**
-- `/metrics` endpoint for Prometheus
-- Message count/rate stats
-- Connection lifecycle events
-- Error rate tracking
-
----
-
-### `agent-relay-8ff` Agent list command in CLI
-**Status:** Open | **Priority:** P2
-
-CLI has `up/down/status/read` but no way to list connected agents or see message history from command line.
-
-**Required Work:**
-- `agent-relay agents` - list connected agents
-- `agent-relay history` - show recent messages
-- `agent-relay send <agent> <msg>` - send from CLI
-
----
-
-## Tasks
-
-### `agent-relay-8z1` Add CLI tests for new command structure
-**Status:** In Progress | **Priority:** P2
-
-Add comprehensive tests for CLI commands after command consolidation.
-
-**Blocked by:** Command consolidation tasks (closed)
-
----
-
-### `agent-relay-hks` Increase test coverage
-**Status:** Open | **Priority:** P2
-
-Current coverage is only **39% overall**. Key files with 0% coverage:
-- `daemon/server.ts`
-- `dashboard/server.ts`
-- `cli/index.ts`
-- `wrapper/client.ts`
-- `wrapper/tmux-wrapper.ts`
-- `utils/project-namespace.ts`
-
-**Required Work:**
-- Integration tests for daemon startup/shutdown lifecycle
-- CLI command tests
-- End-to-end message flow tests
-
----
-
-### `agent-relay-v57` Message expiration/cleanup in SQLite
-**Status:** Open | **Priority:** P2
-
-SQLite adapter has no TTL or cleanup mechanism for old messages. Database will grow unbounded over time.
-
-**Location:** `src/storage/sqlite-adapter.ts`
-
-**Required Work:**
-- Configurable message retention period
-- Automatic cleanup job
-- Leverage existing `ts` column index
-
----
-
-### `agent-relay-kzw` Project namespace uses /tmp
-**Status:** Open | **Priority:** P2
-
-`BASE_DIR` is `/tmp/agent-relay`. On macOS/Linux, `/tmp` is cleared on reboot, losing all message history.
-
-**Location:** `src/utils/project-namespace.ts:13`
-
-**Required Work:**
-- XDG_DATA_HOME fallback
-- `~/.agent-relay` option
-- Per-project `.agent-relay` folder
-
----
-
-### `agent-relay-37i` Message deduplication memory limits
-**Status:** Open | **Priority:** P2
-
-`sentMessageHashes` is a Set that grows unbounded. For long-running sessions, this could cause memory issues.
-
-**Location:** `src/wrapper/tmux-wrapper.ts:65`
-
-**Required Work:**
-- Max size with LRU eviction
-- Time-based expiration
-- Bloom filter alternative for memory efficiency
-
----
-
-### `agent-relay-5g0` Heartbeat timeout configuration
-**Status:** Open | **Priority:** P2
-
-Heartbeat timeout is hardcoded as 2x `heartbeatMs`. Heartbeat failures immediately kill the connection.
-
-**Location:** `src/daemon/connection.ts:196`
-
-**Required Work:**
-- Independent timeout configuration
-- Exponential backoff for transient issues
-
----
-
-### `agent-relay-7bp` Memory storage adapter limits
-**Status:** Open | **Priority:** P2
-
-MemoryStorageAdapter hard-codes 1000 message limit.
-
-**Location:** `src/storage/adapter.ts:60-63`
-
-**Required Work:**
-- Configurable limit
-- LRU eviction instead of slice
-
----
-
-### `agent-relay-47z` Express 5 compatibility verification
-**Status:** Open | **Priority:** P2
-
-`package.json` uses `express@5.2.1` which has breaking changes from Express 4.
-
-**Required Work:**
-- Verify error handling middleware patterns
-- Check router behavior
-- Validate body parsing (express.json vs body-parser)
-
----
-
-## Recently Completed
-
-### `agent-relay-ucw` Dashboard: multi-project navigation or dynamic port allocation
-**Status:** Closed | **Completed:** 2025-12-20
-
-Fixed dashboard to warn when requested port is busy and return the actual port. CLI now awaits and logs the real URL.
-
----
-
-## Priority Legend
-
-| Priority | Meaning |
-|----------|---------|
-| P0 | Critical - blocking users |
-| P1 | High - significant impact |
-| P2 | Medium - normal priority |
-| P3 | Low - nice to have |
-
----
-
-## Contributing
-
-To work on an issue:
-1. Run `bd ready` to see available work
-2. Claim with `bd update <id> --status=in_progress`
-3. Complete work and close with `bd close <id>`
-
-See [CLAUDE.md](./CLAUDE.md) for development workflow details.

package/docs/archive/SCALING_ANALYSIS.md

@@ -1,280 +0,0 @@
-# Scaling Analysis: Is the TUI Dashboard Worth It?
-
-## The Question
-
-The proposed changes add significant complexity:
-- TUI dashboard with `blessed` library
-- Daemon event streaming
-- Activity state reporting from wrappers
-- New CLI commands
-
-**Is this the right approach, or is there a simpler path?**
-
----
-
-## Behavior Comparison
-
-### Current (2-3 Agents)
-
-```bash
-# Terminal 1
-agent-relay -n Alice claude
-# You're IN Alice's tmux, working
-
-# Terminal 2
-agent-relay -n Bob claude
-# You're IN Bob's tmux
-
-# To switch: Alt+Tab between terminal windows
-# To see status: mentally track what each is doing
-```
-
-**Works fine because:** You can hold 2-3 contexts in your head.
-
-### Proposed (5-10 Agents)
-
-```bash
-# Terminal 1
-agent-relay up        # Start daemon
-agent-relay watch     # TUI dashboard
-
-┌─ Agent Relay ───────────────────────────────┐
-│ ● Alice     active   12↑ 8↓                 │
-│ ● Bob       typing   5↑ 14↓                 │
-│ ○ Charlie   offline  queued: 3              │
-│ ...                                         │
-└─────────────────────────────────────────────┘
-
-# Press 'a' → attach to native tmux
-# Ctrl+B d → back to TUI
-```
-
-**Adds complexity:**
-- blessed dependency (~500KB)
-- Event stream protocol
-- Activity reporting
-- More state to track in daemon
-
----
-
-## Alternative: Just Use tmux Better
-
-tmux already has multi-pane and multi-window support. Why not leverage it?
-
-### Simpler Approach: Native tmux Layout
-
-```bash
-# Start all agents in one tmux session with multiple windows
-agent-relay team start
-
-# Creates tmux session "relay-team" with:
-# - Window 0: Alice (claude)
-# - Window 1: Bob (claude)
-# - Window 2: Charlie (claude)
-# - Window 3: Status pane (tail -f on logs)
-
-# Switch windows: Ctrl+B 0, Ctrl+B 1, Ctrl+B 2...
-# Or use: Ctrl+B w (window list)
-```
-
-**Implementation (50 lines, not 500):**
-
-```bash
-#!/bin/bash
-# agent-relay team start
-
-TEAM_SESSION="relay-team"
-AGENTS=$(cat teams.json | jq -r '.agents[].name')
-
-tmux new-session -d -s "$TEAM_SESSION"
-
-i=0
-for agent in $AGENTS; do
-  if [ $i -eq 0 ]; then
-    tmux send-keys -t "$TEAM_SESSION" "agent-relay -n $agent claude" Enter
-  else
-    tmux new-window -t "$TEAM_SESSION"
-    tmux send-keys -t "$TEAM_SESSION" "agent-relay -n $agent claude" Enter
-  fi
-  ((i++))
-done
-
-# Add status window
-tmux new-window -t "$TEAM_SESSION" -n "status"
-tmux send-keys -t "$TEAM_SESSION:status" "watch -n1 agent-relay agents" Enter
-
-tmux attach -t "$TEAM_SESSION"
-```
-
-**User experience:**
-```
-Ctrl+B w  →  Shows window list:
-  0: Alice (attached)
-  1: Bob
-  2: Charlie
-  3: status
-
-Ctrl+B 1  →  Jump to Bob
-Ctrl+B 3  →  See status (agent-relay agents output)
-```
-
----
-
-## Comparison: TUI vs Native tmux
-
-| Aspect | TUI Dashboard (blessed) | Native tmux Windows |
-|--------|------------------------|---------------------|
-| **Lines of code** | ~500 | ~50 |
-| **Dependencies** | blessed (~500KB) | None (tmux built-in) |
-| **Learning curve** | New UI to learn | tmux you already know |
-| **Real-time updates** | Yes (event stream) | Yes (watch command) |
-| **Quick switch** | Press 'a', select | Ctrl+B {number} |
-| **See all at once** | TUI list | Ctrl+B w (window list) |
-| **Native experience** | Detach TUI → attach tmux | Already in tmux |
-| **Maintenance** | blessed updates, bugs | tmux is stable |
-
----
-
-## What We Actually Need for Scaling
-
-Let's separate "nice to have" from "essential":
-
-### Essential (for 5-10 agents)
-
-1. **Quick overview of all agents** → `agent-relay agents` (already proposed)
-2. **Know who's busy vs idle** → Activity state in agents output
-3. **Message history** → `agent-relay history` (already proposed)
-4. **Quick attach** → `agent-relay attach Alice`
-5. **Group messaging** → `->relay:@backend` (already proposed)
-
-### Nice to Have (but complex)
-
-1. **Real-time TUI dashboard** → Use `watch` instead
-2. **Event streaming** → Poll daemon status instead
-3. **Typing indicators** → Not critical for coordination
-
----
-
-## Recommended Simpler Approach
-
-### Phase 5 Revised: Minimal Scaling
-
-```bash
-# 1. Better status command (essential)
-$ agent-relay agents
-NAME       STATUS   MESSAGES   LAST SEEN
-Alice      active   12↑ 8↓     now
-Bob        idle     5↑ 14↓     30s ago
-Charlie    offline  queued: 3  5m ago
-
-# 2. Quick attach (essential)
-$ agent-relay attach Alice
-# Attaches to relay-Alice-* session
-
-# 3. Team layout (essential)
-$ agent-relay team start
-# Creates multi-window tmux session
-# Use Ctrl+B w to see all, Ctrl+B {n} to switch
-
-# 4. Live status (nice to have, zero code)
-$ watch -n2 agent-relay agents
-# Updates every 2 seconds
-
-# 5. Message history (essential)
-$ agent-relay history --last 20
-14:23:01 Alice → Bob: Can you check the API?
-14:23:15 Bob → Alice: On it
-...
-```
-
-### Implementation Effort
-
-| Feature | Complex TUI Approach | Simpler Approach |
-|---------|---------------------|------------------|
-| TUI dashboard | 2 days + blessed dep | 0 (use `watch`) |
-| Event stream | 1 day + protocol change | 0 (poll status) |
-| Activity reporting | 1 day | 0.5 day (just in status) |
-| Team layout | Already proposed | Same (0.5 day) |
-| Better agents cmd | Same | Same (0.5 day) |
-| History command | Same | Same (0.5 day) |
-| **Total** | **5+ days** | **2 days** |
-
----
-
-## Verdict: Skip the TUI, Use tmux
-
-The TUI dashboard is over-engineered. tmux already provides:
-- Multi-window switching (Ctrl+B w)
-- Split panes (Ctrl+B %)
-- Session persistence
-- Window list
-
-**What we actually need:**
-
-1. **`agent-relay agents`** - Show status with activity state
-2. **`agent-relay attach <name>`** - Quick attach helper
-3. **`agent-relay team start`** - Multi-window tmux layout
-4. **`agent-relay history`** - Query past messages
-
-**What we DON'T need:**
-
-1. ❌ blessed TUI dependency
-2. ❌ Event streaming from daemon
-3. ❌ Complex activity reporting protocol
-4. ❌ Real-time typing indicators
-
----
-
-## Updated Design Recommendation
-
-### Keep from Phase 5:
-- Agent groups (`->relay:@backend`)
-- Message priority (`!`, `?`)
-- `agent-relay agents` command
-- `agent-relay history` command
-
-### Replace TUI with:
-```bash
-# Multi-window tmux session
-agent-relay team start    # Creates relay-team session
-agent-relay team attach   # Attach to existing
-agent-relay team add Bob  # Add agent to running team
-
-# Quick attach to single agent
-agent-relay attach Alice
-
-# Live status (zero code, just docs)
-watch -n2 agent-relay agents
-```
-
-### Effort Saved:
-- No blessed dependency
-- No event streaming protocol
-- No TUI code maintenance
-- 3+ days of implementation saved
-
----
-
-## Behavior Impact Summary
-
-| Scenario | TUI Approach | Simpler Approach |
-|----------|--------------|------------------|
-| See all agents | Open TUI, see list | `agent-relay agents` or `Ctrl+B w` |
-| Switch to Bob | Press 'a', select Bob | `Ctrl+B 1` or `agent-relay attach Bob` |
-| Check if Alice is busy | See "typing..." in TUI | Check status column in agents |
-| Send message to group | Same | Same (`->relay:@backend`) |
-| View history | Press 'h' in TUI | `agent-relay history` |
-
-**The simpler approach does everything the TUI does, with 80% less code.**
-
----
-
-## Final Recommendation
-
-1. **Don't build the TUI dashboard** - It's solving a problem tmux already solves
-2. **Do add `agent-relay team`** - Leverages tmux's native multi-window
-3. **Do improve `agent-relay agents`** - Add activity state, message counts
-4. **Do add `agent-relay history`** - Query past messages
-5. **Document `watch` trick** - Free live updates
-
-This keeps the simplicity advantage while scaling to 10+ agents.