agent-relay 1.2.0 → 1.3.0

package/TESTING.md

@@ -0,0 +1,278 @@
+# Manual Testing Guide
+
+Manual testing instructions for bridge, staffing, and multi-project orchestration features.
+
+## Prerequisites
+
+- Node.js installed
+- `agent-relay` built and available (`npm run build`)
+- tmux installed (`brew install tmux` on macOS)
+
+---
+
+## 1. Single Project - Lead + Spawning
+
+Test the Lead role and worker spawning within a single project.
+
+### Setup
+
+```bash
+# Terminal 1: Start daemon
+cd /path/to/your/project
+agent-relay up
+```
+
+```bash
+# Terminal 2: Start an agent
+agent-relay -n Alice claude
+```
+
+### Test Spawning
+
+Inside Alice's terminal, output these patterns:
+
+```
+->relay:spawn Dev1 claude "Write unit tests for the auth module"
+```
+
+Or using the fenced format for messages:
+
+```
+->relay:Dev1 <<<
+Write unit tests for the auth module>>>
+```
+
+**Expected:**
+- New tmux window created in `relay-workers` session
+- Dev1 agent starts with the task injected
+- Message: `[spawner] Spawned Dev1 (claude) for Alice`
+
+### Verify Spawn
+
+```bash
+# Check tmux windows
+tmux list-windows -t relay-workers
+```
+
+### Test Release
+
+```
+->relay:release Dev1
+```
+
+**Expected:**
+- Dev1 window closed
+- Message: `[spawner] Released Dev1`
+
+### Test Release All
+
+First spawn multiple workers:
+```
+->relay:spawn Dev1 claude "Task 1"
+->relay:spawn Dev2 claude "Task 2"
+->relay:spawn QA1 claude "Task 3"
+```
+
+Then release all:
+```
+->relay:release *
+```
+
+**Expected:** All workers released.
+
+---
+
+## 2. Multi-Project Bridge
+
+Test cross-project communication with the bridge command.
+
+### Setup (3 terminals minimum)
+
+```bash
+# Terminal 1: Project A daemon
+mkdir -p /tmp/project-a
+cd /tmp/project-a
+agent-relay up
+```
+
+```bash
+# Terminal 2: Project B daemon
+mkdir -p /tmp/project-b
+cd /tmp/project-b
+agent-relay up
+```
+
+```bash
+# Terminal 3: Bridge (Architect mode)
+agent-relay bridge /tmp/project-a /tmp/project-b
+```
+
+**Expected:**
+- Bridge connects to both project sockets
+- Dashboard shows both projects (if enabled)
+
+### Start Agents in Each Project
+
+```bash
+# Terminal 4: Agent in Project A
+cd /tmp/project-a
+agent-relay -n Alice claude
+```
+
+```bash
+# Terminal 5: Agent in Project B
+cd /tmp/project-b
+agent-relay -n Bob claude
+```
+
+### Test Cross-Project Messaging
+
+From Alice (Project A):
+```
+->relay:project-b:Bob <<<
+Hey Bob, can you review my changes?>>>
+```
+
+**Expected:** Bob receives the message in Project B.
+
+From Bob (Project B):
+```
+->relay:project-a:Alice <<<
+Sure, sending review now.>>>
+```
+
+**Expected:** Alice receives the message in Project A.
+
+### Test Broadcast to All Leads
+
+From the bridge/architect:
+```
+->relay:*:lead <<<
+Standup time - report your status>>>
+```
+
+**Expected:** Both Alice and Bob receive the message.
+
+---
+
+## 3. Dashboard Verification
+
+### Main Dashboard
+
+Open: http://localhost:4280
+
+Check:
+- [ ] Connected agents appear
+- [ ] Online/Offline status badges show correctly
+- [ ] Messages appear in activity log
+- [ ] Last seen timestamps update
+
+### Bridge Dashboard
+
+Open: http://localhost:4280/bridge
+
+Check:
+- [ ] Connected projects appear
+- [ ] Leads shown per project
+- [ ] Workers shown under their lead
+- [ ] Cross-project messages in message flow panel
+
+---
+
+## 4. Agent Role Auto-Detection
+
+Test that agent names match role definitions.
+
+### Setup
+
+Create a role agent:
+```bash
+mkdir -p .claude/agents
+cat > .claude/agents/lead.md << 'EOF'
+---
+name: lead
+description: Coordinator agent
+model: haiku
+---
+
+# Lead Agent
+
+You are a Lead agent - coordinate and delegate.
+EOF
+```
+
+### Test
+
+```bash
+agent-relay -n Lead claude
+```
+
+**Expected:** Agent assumes the Lead role from `lead.md` (case-insensitive match).
+
+---
+
+## 5. Cleanup
+
+```bash
+# Stop all daemons
+agent-relay down
+
+# Kill any orphaned tmux sessions
+tmux kill-session -t relay-workers 2>/dev/null
+tmux list-sessions | grep relay | cut -d: -f1 | xargs -I {} tmux kill-session -t {}
+
+# Remove test directories
+rm -rf /tmp/project-a /tmp/project-b
+```
+
+---
+
+## Quick Smoke Test Script
+
+Save as `test-bridge.sh` and run:
+
+```bash
+#!/bin/bash
+set -e
+
+echo "=== Bridge Smoke Test ==="
+
+# Setup
+mkdir -p /tmp/smoke-a /tmp/smoke-b
+cd /tmp/smoke-a && agent-relay up &
+PID_A=$!
+sleep 1
+
+cd /tmp/smoke-b && agent-relay up &
+PID_B=$!
+sleep 1
+
+# Check daemons
+echo "Checking daemons..."
+agent-relay status
+
+# Bridge
+echo "Starting bridge..."
+agent-relay bridge /tmp/smoke-a /tmp/smoke-b &
+PID_BRIDGE=$!
+sleep 2
+
+# Cleanup
+echo "Cleaning up..."
+kill $PID_A $PID_B $PID_BRIDGE 2>/dev/null || true
+rm -rf /tmp/smoke-a /tmp/smoke-b
+
+echo "=== Smoke Test Complete ==="
+```
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Socket not found" | Start daemon with `agent-relay up` |
+| Spawn not working | Check tmux is installed, check `relay-workers` session |
+| Cross-project messages not delivered | Verify bridge is running and connected to both daemons |
+| Dashboard not loading | Check daemon started with dashboard enabled (default) |
+| Agent role not applied | Check file exists at `.claude/agents/<name>.md` (case-insensitive) |

package/deploy/init-db.sql

@@ -0,0 +1,5 @@
+-- Agent Relay Cloud - Database bootstrap
+-- Migrations are handled by Drizzle ORM at server startup.
+-- This file is kept for Docker entrypoint compatibility.
+
+-- No-op: Drizzle migrations run automatically

package/deploy/scripts/setup-fly-workspaces.sh

@@ -0,0 +1,69 @@
+#!/bin/bash
+# Setup Fly.io for Agent Relay Workspaces
+# Run this from the project root
+
+set -e
+
+echo "=== Agent Relay Cloud - Fly.io Workspace Setup ==="
+echo ""
+
+# Check for fly CLI
+if ! command -v fly &> /dev/null; then
+    echo "Error: Fly CLI not found. Install it with:"
+    echo "  curl -L https://fly.io/install.sh | sh"
+    exit 1
+fi
+
+# Check if logged in
+if ! fly auth whoami &> /dev/null; then
+    echo "Please log in to Fly.io first:"
+    fly auth login
+fi
+
+# Get org
+FLY_ORG=${FLY_ORG:-personal}
+echo "Using Fly.io org: $FLY_ORG"
+
+echo ""
+echo "=== Building Workspace Image ==="
+echo ""
+
+# Build and push the workspace image
+cd deploy/workspace
+
+echo "Building workspace Docker image..."
+docker build -t ghcr.io/khaliqgant/agent-relay-workspace:latest .
+
+echo ""
+echo "Pushing to GitHub Container Registry..."
+echo "(Make sure you're logged in: docker login ghcr.io)"
+docker push ghcr.io/khaliqgant/agent-relay-workspace:latest
+
+cd ../..
+
+echo ""
+echo "=== Get Your API Token ==="
+echo ""
+echo "Run this to get your Fly.io API token:"
+echo "  fly auth token"
+echo ""
+echo "Add it to your Railway environment:"
+echo "  FLY_API_TOKEN=<token>"
+echo "  FLY_ORG=$FLY_ORG"
+echo "  COMPUTE_PROVIDER=fly"
+echo ""
+
+echo "=== Custom Domain Setup ==="
+echo ""
+echo "To use custom workspace domains (e.g., abc123.ws.agent-relay.com):"
+echo ""
+echo "1. Add a wildcard CNAME record in your DNS:"
+echo "   *.ws.agent-relay.com  CNAME  fly.dev"
+echo ""
+echo "2. Set the domain in Railway:"
+echo "   FLY_WORKSPACE_DOMAIN=ws.agent-relay.com"
+echo ""
+echo "3. Each workspace will be accessible at:"
+echo "   https://{workspace-id}.ws.agent-relay.com"
+echo ""
+echo "Setup complete!"

package/deploy/scripts/setup-railway.sh

@@ -0,0 +1,75 @@
+#!/bin/bash
+# Setup Agent Relay Cloud on Railway
+# Run this from the project root
+
+set -e
+
+echo "=== Agent Relay Cloud - Railway Setup ==="
+echo ""
+
+# Check for railway CLI
+if ! command -v railway &> /dev/null; then
+    echo "Error: Railway CLI not found. Install it with:"
+    echo "  npm install -g @railway/cli"
+    exit 1
+fi
+
+# Check if logged in
+if ! railway whoami &> /dev/null; then
+    echo "Please log in to Railway first:"
+    railway login
+fi
+
+echo "Creating Railway project..."
+railway init --name agent-relay-cloud
+
+echo ""
+echo "Adding PostgreSQL database..."
+railway add --plugin postgresql
+
+echo ""
+echo "Adding Redis..."
+railway add --plugin redis
+
+echo ""
+echo "=== Required Environment Variables ==="
+echo "Please set these in Railway dashboard or via CLI:"
+echo ""
+echo "Required:"
+echo "  SESSION_SECRET          - openssl rand -hex 32"
+echo "  GITHUB_CLIENT_ID        - From GitHub OAuth App"
+echo "  GITHUB_CLIENT_SECRET    - From GitHub OAuth App"
+echo "  VAULT_ENCRYPTION_KEY    - openssl rand -hex 32"
+echo ""
+echo "For Fly.io workspaces:"
+echo "  COMPUTE_PROVIDER=fly"
+echo "  FLY_API_TOKEN           - fly auth token"
+echo "  FLY_ORG=personal"
+echo "  FLY_WORKSPACE_DOMAIN    - e.g., ws.agent-relay.com"
+echo ""
+echo "For Stripe billing:"
+echo "  STRIPE_SECRET_KEY"
+echo "  STRIPE_PUBLISHABLE_KEY"
+echo "  STRIPE_WEBHOOK_SECRET"
+echo ""
+
+echo "Set variables with:"
+echo "  railway variables set KEY=value"
+echo ""
+
+echo "When ready, deploy with:"
+echo "  railway up"
+echo ""
+
+echo "=== DNS Configuration ==="
+echo "After deployment, configure your DNS:"
+echo ""
+echo "1. Get your Railway domain:"
+echo "   railway domain"
+echo ""
+echo "2. Configure DNS records:"
+echo "   api.agent-relay.com    CNAME  <railway-domain>"
+echo "   app.agent-relay.com    CNAME  <your-dashboard-host>"
+echo "   agent-relay.com        A      <your-landing-host>"
+echo "   *.ws.agent-relay.com   CNAME  fly.dev (for workspaces)"
+echo ""

package/deploy/workspace/codex.config.toml

@@ -0,0 +1,15 @@
+# Codex CLI Configuration for Agent Relay Containers
+# This file is copied to ~/.codex/config.toml in container environments
+# Reference: https://developers.openai.com/codex/config-reference/
+
+# Disable auto-updates in containers to prevent permission errors
+# Updates are managed via Dockerfile (pinned versions)
+check_for_updates = false
+
+# Additional configuration options can be added here as needed
+# Examples (uncomment and adjust as needed):
+# [model]
+# default_model = "o1"
+#
+# [editor]
+# default_editor = "vim"

package/deploy/workspace/entrypoint-browser.sh

@@ -0,0 +1,118 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+log() {
+  echo "[workspace-browser] $*"
+}
+
+# ============================================================================
+# Start Virtual Display (Xvfb)
+# ============================================================================
+log "Starting Xvfb virtual display..."
+Xvfb :99 -screen 0 "${SCREEN_WIDTH:-1920}x${SCREEN_HEIGHT:-1080}x${SCREEN_DEPTH:-24}" &
+XVFB_PID=$!
+sleep 1
+
+# Verify Xvfb started
+if ! kill -0 $XVFB_PID 2>/dev/null; then
+  log "ERROR: Xvfb failed to start"
+  exit 1
+fi
+log "Xvfb started on display :99"
+
+# ============================================================================
+# Start Window Manager (Fluxbox)
+# ============================================================================
+log "Starting Fluxbox window manager..."
+fluxbox &
+sleep 1
+log "Fluxbox started"
+
+# ============================================================================
+# Start VNC Server (optional, for debugging/viewing)
+# ============================================================================
+if [[ "${VNC_ENABLED:-true}" == "true" ]]; then
+  log "Starting x11vnc server..."
+  x11vnc -display :99 -forever -shared -rfbport "${VNC_PORT:-5900}" -bg -nopw -xkb
+  log "VNC server started on port ${VNC_PORT:-5900}"
+
+  # Start noVNC for browser-based access
+  if [[ "${NOVNC_ENABLED:-true}" == "true" ]]; then
+    log "Starting noVNC web interface..."
+    websockify --web=/usr/share/novnc/ "${NOVNC_PORT:-6080}" localhost:"${VNC_PORT:-5900}" &
+    log "noVNC available at http://localhost:${NOVNC_PORT:-6080}/vnc.html"
+  fi
+fi
+
+# ============================================================================
+# Export browser testing utilities
+# ============================================================================
+
+# Create screenshot helper
+cat > /usr/local/bin/take-screenshot <<'EOF'
+#!/usr/bin/env bash
+# Take a screenshot and save to specified path
+# Usage: take-screenshot [output.png]
+OUTPUT="${1:-/tmp/screenshot-$(date +%Y%m%d-%H%M%S).png}"
+DISPLAY=:99 scrot "$OUTPUT"
+echo "$OUTPUT"
+EOF
+chmod +x /usr/local/bin/take-screenshot
+
+# Create browser launcher helper
+cat > /usr/local/bin/launch-browser <<'EOF'
+#!/usr/bin/env bash
+# Launch browser with optional URL
+# Usage: launch-browser [url]
+URL="${1:-about:blank}"
+DISPLAY=:99 chromium --no-sandbox --disable-gpu --start-maximized "$URL" &
+echo "Browser launched with PID $!"
+EOF
+chmod +x /usr/local/bin/launch-browser
+
+# Create Playwright test runner helper
+cat > /usr/local/bin/run-playwright <<'EOF'
+#!/usr/bin/env bash
+# Run Playwright tests with proper display settings
+# Usage: run-playwright [test-file.spec.ts] [additional args...]
+export DISPLAY=:99
+npx playwright test "$@"
+EOF
+chmod +x /usr/local/bin/run-playwright
+
+# ============================================================================
+# Docker-in-Docker helper (if socket mounted)
+# ============================================================================
+if [[ -S /var/run/docker.sock ]]; then
+  log "Docker socket detected - agents can spawn containers"
+
+  # Create helper for agents to spawn isolated containers
+  cat > /usr/local/bin/spawn-container <<'EOF'
+#!/usr/bin/env bash
+# Spawn an isolated container for agent tasks
+# Usage: spawn-container <image> [command...]
+IMAGE="${1:-ubuntu:22.04}"
+shift
+docker run --rm -it \
+  --network=host \
+  -v "$(pwd):/workspace" \
+  -w /workspace \
+  "$IMAGE" "$@"
+EOF
+  chmod +x /usr/local/bin/spawn-container
+else
+  log "WARN: Docker socket not mounted - container spawning disabled"
+fi
+
+# ============================================================================
+# Continue with main entrypoint
+# ============================================================================
+log "Browser testing environment ready"
+log "  - Display: $DISPLAY (${SCREEN_WIDTH}x${SCREEN_HEIGHT})"
+log "  - VNC: ${VNC_ENABLED:-true} (port ${VNC_PORT:-5900})"
+log "  - noVNC: ${NOVNC_ENABLED:-true} (http://localhost:${NOVNC_PORT:-6080})"
+log "  - Playwright: $(npx playwright --version 2>/dev/null || echo 'installed')"
+
+# Hand off to main entrypoint
+exec /entrypoint.sh "$@"