agent-relay 2.0.29 → 2.0.32

package/CHANGELOG.md

@@ -1,231 +0,0 @@
-# Changelog
-
-All notable changes to Agent Relay will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [2.0.20] - 2026-01-26
-
-### Overview
-- Major SDK expansion with swarm primitives, logs API, and protocol types.
-- New CLI auth testing package with Dockerized workflows and scripts.
-- Relay-pty and wrapper improvements focused on reliability and orchestration.
-- Expanded documentation for swarm primitives and testing guides.
-
-### Product Perspective
-#### User-Facing Features & Improvements
-- Swarm primitives added to SDK with full documentation and examples.
-- CLI auth testing tooling introduced with repeatable scripts and Docker workflows.
-- Provider connection UI copy refreshed (OpenCode/Droid messaging updates).
-- Improved onboarding reliability for OAuth flows in cloud workspaces.
-
-#### User-Impacting Fixes
-- Spawner registration timeouts in cloud workspaces resolved.
-- Idle detection behavior made more robust to avoid false positives.
-- OAuth URL parsing now handles line-wrapped output from CLI.
-
-#### Deprecations
-- None noted for this release.
-
-#### Breaking Changes & Migration Guidance
-- None noted for this release.
-
-### Technical Perspective
-#### Architecture & API Changes
-- New SDK client capabilities (`client`, `logs`, and protocol types) and expanded test coverage.
-- Spawner logic updated for more reliable agent registration and routing.
-- Relay-pty orchestration updated in Rust core with supporting wrapper changes.
-
-#### Performance & Reliability
-- Idle detection strengthened in wrapper layer (logic + tests).
-- Relay-pty orchestration hardened; additional tests for injection handling.
-
-#### Dependencies & Tooling
-- Workspace package updates and lockfile refresh.
-- New hooks scripts (`scripts/hooks/install.sh`, `scripts/hooks/pre-commit`) for developer workflows.
-- Dockerfiles updated for workspace and CLI testing images.
-
-#### Implementation Details (For Developers)
-- Added `packages/cli-tester` with auth credential checks and socket client utilities.
-- New CLI tester scripts for spawn/registration/auth flows.
-- `packages/config` gains CLI auth config updates for cloud onboarding.
-- `relay-pty` binary updated for macOS arm64.
-
-### Added
-- `@agent-relay/mcp` package with MCP tools/resources and one-command install.
-- Swarm primitives SDK API and examples (`SWARM_CAPABILITIES`, `SWARM_PATTERNS`).
-- CLI auth testing package with Docker and scripted flows.
-- New roadmap/spec documentation for primitives and multi-server architecture.
-
-### Fixed
-- Cloud spawner timeout in agent registration.
-- OAuth URL parsing for line-wrapped output in CLI auth flows.
-- Idle detection stability in wrapper layer.
-- Relay-pty postinstall and codesign handling for macOS builds.
-- Minor CI/test issues in relay-pty orchestrator tests.
-
-### Changed
-- Dynamic import for MCP commands in CLI.
-- Spawner and daemon routing adjustments for improved registration and diagnostics.
-- Wrapper base class behavior and tests for relay-pty orchestration.
-
-### Infrastructure & Refactors
-- Updates to workspace Dockerfiles and publish workflow tweaks.
-- Package metadata alignment across SDK, dashboard, wrapper, spawner, and api-types.
-- Additional instrumentation in relay-pty and orchestrator to support reliability.
-
-### Documentation
-- Swarm primitives guide and comprehensive roadmap specification.
-- CLI auth testing guide.
-
-### Recent Daily Breakdown
-#### 2026-01-27
-- Merged swarm primitives and channels work into mainline (#314).
-- Relay and orchestrator fixes: relay-pty updates, wrapper base changes, and new dev hooks.
-
-#### 2026-01-26
-- Added CLI auth testing package with Docker workflow and scripts.
-- Added swarm primitives SDK APIs, examples, and documentation.
-- Added primitives roadmap spec and beads/trajectory artifacts.
-- Fixed spawner registration timeout in cloud workspaces.
-- Improved onboarding behavior for OAuth URL wrapping and bypass permissions.
-- Hardened idle detection and relay-pty orchestration; added tests.
-- Updated package-lock and workspace package metadata; release tags v2.0.18–v2.0.20.
-
-### Commit Activity (Past 3 Weeks)
-- 23 commits across Jan 26–27, 2026 (21 on Jan 26; 2 on Jan 27).
-- Authors: Khaliq (18), GitHub Actions (3), Agent Relay (2).
-- Top scopes: `feat`, `fix`, `docs`, `chore`.
-
----
-
-## [Three-Week Retrospective: Jan 3–24, 2026]
-
-## [Week 1: January 3-10, 2026]
-
-### Product Perspective
-**Core Messaging & Communication**
-- First-class channels and direct messages as core features.
-- Direct message routing improvements and message store integration.
-
-**Cloud & Workspace Management**
-- Cloud link logic for workspace connectivity.
-- Workspace persistence across container restarts and dynamic repo management.
-- Workspace deployment fixes.
-
-**Developer Experience**
-- CLI patterns for agent visibility and log tailing.
-- Codex state management and XTerm display improvements.
-
-**Billing & Authentication**
-- Billing bridge fixes and GitHub CLI auth support.
-- Authentication tightening and token fetch improvements.
-
-### Technical Perspective
-**Architecture & Infrastructure**
-- Multi-server architecture documentation and scalability adjustments.
-- WebSocket ping/pong keepalive for main and bridge connections.
-
-**Cloud Infrastructure**
-- Cloud link migrations and update-workspaces workflow fixes.
-
-**State Management**
-- Message delivery fixes and Codex state persistence improvements.
-
-**Deployment & Operations**
-- Container entrypoint updates and deployment fixes.
-
-**Documentation**
-- Trail snippet bump and competitive analysis additions.
-
----
-
-## [Week 2: January 10-17, 2026]
-
-### Product Perspective
-**Mobile & UI Improvements**
-- Mobile scrolling fixes for XTermLogViewer and viewport stability.
-- Dashboard UI restrictions/restore and agent list labeling cleanup.
-
-**Channels & Messaging**
-- Channel creation logging improvements.
-- Message routing, duplication, and attribution fixes in cloud dashboard.
-
-**Workspace & User Management**
-- Workspace selector and user filtering fixes.
-- Workspace proxy query parameter preservation.
-
-**Agent Profiles & Coordination**
-- Added agent profiles for multi-project support and Mega coordinator command.
-- Trajectory viewer race condition fixes.
-
-**Authentication & Providers**
-- Gemini API key validation fixes and Claude login flow improvements.
-
-### Technical Perspective
-**Relay-PTY System Migration**
-- Node-pty to Rust relay-pty migration with hybrid orchestrator.
-- Relay-pty infrastructure tests and Rust 1.83 Cargo.lock v4 fixes.
-
-**Performance & Reliability**
-- Injection reliability improvements and duplicate terminal message fixes.
-- Workspace ID sync fixes to avoid routing race conditions.
-
-**State & Continuity**
-- Continuity parsing and workspace path handling.
-
-**Fallback Logic**
-- Proper fallback logic and protocol prompt updates.
-
----
-
-## [Week 3: January 17-24, 2026]
-
-### Product Perspective
-**Channels & Team Collaboration**
-- Channel invites, endpoints, and message delivery fixes.
-- Mobile channel scrolling and DM filtering in sidebar.
-- Unified threading between channels and DMs.
-
-**Performance & User Experience**
-- 5x faster relay message injection latency.
-- Mobile scrolling improvements and unified markdown rendering.
-- Agent pin-to-top for agents panel.
-
-**Developer Experience**
-- Model selection dropdown sync and mapping consolidation.
-- CLI tool bumps and SDK fixes.
-
-**Workspace & Credentials**
-- Workspace-scoped provider credentials.
-- Workspace switching fixes and force-update workflow.
-
-**Pricing & Documentation**
-- Pricing updates and TASKS/protocol documentation refresh.
-- Clarified agent roles (devops vs infrastructure).
-
-### Technical Perspective
-**Build System & CI/CD**
-- Turborepo integration and concurrent Docker builds.
-- Turbo/TypeScript build fixes and publish error remediation.
-
-**Sync Messaging Protocol**
-- Turn-based sync messaging with `[await]` syntax and ACK tracking.
-
-**Daemon & Spawning**
-- Daemon-based spawning with improved diagnostics and membership restore.
-- Spawn timing race condition fixes.
-
-**Cloud Infrastructure**
-- Static file serving fixes, new `/api/bridge` endpoint, and routing fixes.
-- Cloud sync heartbeat timeout handling and queue monitor fixes.
-
-**Authentication & Git Operations**
-- GitHub token fallback and GH_TOKEN injection fixes.
-- Custom GitHub credential helper with improved retry logic.
-
-**Workspace & Path Management**
-- Workspace inbox namespacing and continuity parsing improvements.

package/TESTING.md

@@ -1,278 +0,0 @@
-# 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/TRAIL_GIT_AUTH_FIX.md

@@ -1,113 +0,0 @@
-# Git Authentication Infrastructure Fix - Trail Documentation
-
-**Trajectory ID:** traj_pdreuiy4xr4i
-**Status:** ✅ Completed
-**Confidence:** 92%
-**Started:** January 8, 2026 at 07:01 PM
-**Completed:** January 8, 2026 at 07:03 PM
-
-## Problem
-
-Git push and GitHub CLI operations were failing due to authentication issues:
-- `/api/git/token` endpoint returned GitHub App **installation tokens** (ghs_*)
-- Installation tokens are API-only and don't work with git credential helpers
-- Agents had to use workaround: embed token directly in HTTPS URL
-- This wasted cycles and blocked automated workflows
-
-Error encountered:
-```
-git push origin branch
-# FAILS: "Password authentication is not supported for Git operations"
-```
-
-## Root Cause Analysis
-
-The `/api/git/token` endpoint (src/cloud/api/git.ts):
-1. Was fetching both `userToken` (GitHub user OAuth) and `installationToken` (GitHub App)
-2. But returned `installationToken` as the primary `token` field
-3. Installation tokens only work with GitHub API, not git operations
-4. User OAuth tokens work for both git operations AND GitHub App API calls
-
-## Solution: Dual Token Approach (Option A+)
-
-Modified `/api/git/token` response to return:
-- **`userToken`** (primary): GitHub user OAuth token → For git push, git clone, gh CLI
-- **`installationToken`** (fallback): GitHub App token → For GitHub App-specific API operations
-- **`tokenType`** (field): Indicates which type is being used ('user' or 'installation')
-
-### Why This Works
-
-1. **Git operations** get a compatible token (userToken)
-2. **GitHub App operations** have access to app-specific endpoints
-3. **Backward compatible** - falls back to installation token if user token unavailable
-4. **Extensible** - enables future GitHub App integrations
-
-## Implementation Details
-
-### Files Modified
-
-**src/cloud/api/git.ts** (lines 182-186)
-```typescript
-res.json({
-  token: userToken || installationToken,  // Primary: prefer user token
-  tokenType: userToken ? 'user' : 'installation',
-  installationToken,                       // Also return for app ops
-  expiresAt,
-  username: 'x-access-token',
-});
-```
-
-**deploy/workspace/git-credential-relay**
-- Updated to prefer `.userToken` field
-- Falls back to `.token` if userToken unavailable
-- Added debug logging for token type
-
-**deploy/workspace/gh-relay**
-- Updated to prefer `.userToken` field
-- Falls back to `.token` if userToken unavailable
-
-## Verification
-
-During implementation, GitAuthEngineer experienced the exact problem:
-- `git push origin branch` failed with "Password authentication not supported"
-- `gh pr create` failed with 401 Bad Credentials
-- Had to use token-in-URL workaround to push the fix
-
-This confirmed the fix is needed and validates the solution.
-
-## Impact
-
-✅ **Unblocks all agent workflows:**
-- Git push/pull/clone now works transparently
-- GitHub CLI (gh) operations work transparently
-- No manual token embedding workarounds needed
-- Credential helpers function as intended
-
-✅ **Enables GitHub App integration:**
-- Agents can call GitHub App-specific API endpoints if needed
-- Webhook management, installation management, etc.
-- Future extensibility for advanced integrations
-
-## Related Tasks
-
-- **PR:** #112 - Git auth infrastructure fix
-- **Beads:** bd-git-auth-fix (completed - investigation and implementation)
-- **Beads:** bd-git-auth-docs (pending - agent documentation on dual token usage)
-- **Trail:** traj_pdreuiy4xr4i (this trajectory)
-
-## Key Decisions
-
-1. **Implemented dual-token approach** instead of single endpoint separation
-   - Reasoning: Keeps endpoint simple, returns both tokens for flexibility
-   - Keeps PR #112 focused on fix
-   - Documentation tabled as separate task (bd-git-auth-docs) for later
-
-2. **Return both tokens in response** rather than separate endpoints
-   - Less API fragmentation
-   - Agents get what they need in one call
-   - Clear field names indicate purpose
-
-3. **Prefer userToken over installationToken**
-   - User tokens work for all operations (git + API)
-   - Installation tokens only work for specific GitHub App operations
-   - Makes transparent user experience the default

package/scripts/demos/README.md

@@ -1,79 +0,0 @@
-# Multi-Agent Negotiation Demos
-
-Two demos showcasing agents with competing priorities negotiating limited resources using the full agent-relay system.
-
-## Prerequisites
-
-```bash
-# Build agent-relay and link globally
-cd /path/to/relay
-npm run build
-npm link
-
-# Verify
-agent-relay --version
-
-# Ensure claude CLI is authenticated
-claude --version
-```
-
-## The Demos
-
-### 1. Server Capacity (Emergency)
-
-**Scenario**: Black Friday traffic spike. 3 services compete for 10 emergency server slots.
-
-```bash
-./scripts/demos/server-capacity.sh
-```
-
----
-
-### 2. Sprint Planning
-
-**Scenario**: 50 story points available, 85 requested. Product Lead facilitates.
-
-```bash
-./scripts/demos/sprint-planning.sh
-```
-
----
-
-## Running a Demo
-
-### Step 1: Start Relay Daemon
-
-```bash
-agent-relay up --dashboard
-```
-
-Open http://localhost:3888 to watch the conversation.
-
-### Step 2: Run Setup Script
-
-```bash
-./scripts/demos/server-capacity.sh
-```
-
-This creates a prompt file in `/tmp/agent-relay-demos/`.
-
-### Step 3: Start Agents
-
-```bash
-# Terminal 2
-agent-relay -n WebAPI claude
-# Say: Read /tmp/agent-relay-demos/server-capacity.md - you are WebAPI. Join #incident channel.
-
-# Terminal 3
-agent-relay -n BatchJobs claude
-# Say: Read /tmp/agent-relay-demos/server-capacity.md - you are BatchJobs. Join #incident channel.
-
-# Terminal 4
-agent-relay -n Analytics claude
-# Say: Read /tmp/agent-relay-demos/server-capacity.md - you are Analytics. Join #incident channel.
-```
-
-## What You'll See
-
-- **Dashboard**: Agents connect, messages flow in real-time
-- **Terminals**: Agents negotiate, propose allocations, vote on outcomes