agent-relay 1.0.21 → 1.1.0

package/docs/TESTING_PRESENCE_FEATURES.md

@@ -0,0 +1,327 @@
+# Manual Testing Guide: Presence & Cloud Features
+
+This document provides step-by-step testing procedures for the presence indicators, typing indicators, and user profile features in cloud mode.
+
+## Prerequisites
+
+1. **Cloud Mode Setup**: You need access to the cloud-hosted dashboard with GitHub OAuth authentication.
+2. **Multiple Test Accounts**: Ideally 2-3 different GitHub accounts to test multi-user features.
+3. **Multiple Browser Windows**: Use different browsers or incognito windows for simultaneous sessions.
+
+---
+
+## Test 1: GitHub Avatar & Username Display
+
+### Objective
+Verify that logged-in users see their GitHub avatar and username in messages.
+
+### Steps
+
+1. Log in to the cloud dashboard using GitHub OAuth
+2. Send a message to any agent (e.g., `@AgentName Hello`)
+3. Observe the message in the chat
+
+### Expected Results
+
+- [ ] Your GitHub avatar appears next to your sent message
+- [ ] Your GitHub username appears as the sender
+- [ ] Messages display "You" or your username consistently
+
+---
+
+## Test 2: Presence Indicator - Single User
+
+### Objective
+Verify presence tracking works for a single user.
+
+### Steps
+
+1. Log in to the cloud dashboard
+2. Look at the header area below the main header
+
+### Expected Results
+
+- [ ] A green dot indicator appears showing online status
+- [ ] Your avatar appears in the stacked avatar row
+- [ ] "1 online" text displays next to the avatars
+- [ ] Clicking the indicator shows a dropdown with your username
+
+---
+
+## Test 3: Presence Indicator - Multiple Users
+
+### Objective
+Verify multiple users can see each other's presence.
+
+### Steps
+
+1. **User A**: Log in with first GitHub account in Browser 1
+2. **User B**: Log in with second GitHub account in Browser 2 (different browser or incognito)
+3. Both users observe the presence indicator
+
+### Expected Results
+
+- [ ] Both users see "2 online" in the presence indicator
+- [ ] Both avatars appear in the stacked row
+- [ ] Clicking shows both usernames in the dropdown
+- [ ] Each user can see the other's GitHub avatar
+
+---
+
+## Test 4: Presence Join/Leave Detection
+
+### Objective
+Verify real-time updates when users join and leave.
+
+### Steps
+
+1. **User A**: Already logged in
+2. **User B**: Log in to dashboard
+3. Observe User A's screen when User B joins
+4. **User B**: Close the browser tab
+5. Observe User A's screen after User B leaves
+
+### Expected Results
+
+- [ ] User A immediately sees count increase when User B joins
+- [ ] User B's avatar appears in User A's presence list
+- [ ] User A immediately sees count decrease when User B leaves
+- [ ] User B's avatar disappears from User A's presence list
+
+---
+
+## Test 5: Multi-Tab Support
+
+### Objective
+Verify a user stays "online" when they have multiple tabs open.
+
+### Steps
+
+1. **User A**: Log in to dashboard in Tab 1
+2. **User A**: Open a second tab to the same dashboard (Tab 2)
+3. **User B**: Log in from a different browser
+4. Observe presence count (should show 2 users, not 3)
+5. **User A**: Close Tab 1
+6. Observe presence (User A should still show as online)
+7. **User A**: Close Tab 2
+8. Observe presence (User A should now show as offline)
+
+### Expected Results
+
+- [ ] Multiple tabs from same user don't inflate online count
+- [ ] Closing one tab doesn't disconnect the user
+- [ ] User only shows as offline when ALL tabs are closed
+
+---
+
+## Test 6: Typing Indicator - Single User
+
+### Objective
+Verify typing indicators appear when another user is typing.
+
+### Steps
+
+1. **User A**: Log in in Browser 1
+2. **User B**: Log in in Browser 2
+3. **User B**: Start typing a message (don't send)
+4. Observe User A's screen
+
+### Expected Results
+
+- [ ] User A sees "User B is typing..." indicator
+- [ ] The indicator appears below the message list, above the composer
+- [ ] User B's avatar appears in the typing indicator
+- [ ] Animated dots appear next to the message
+
+---
+
+## Test 7: Typing Indicator - Stop Typing
+
+### Objective
+Verify typing indicator disappears when user stops typing.
+
+### Steps
+
+1. Continue from Test 6
+2. **User B**: Delete all text from the input field
+3. Observe User A's screen
+
+### Expected Results
+
+- [ ] Typing indicator disappears within 1 second
+- [ ] No residual "typing" state shown
+
+---
+
+## Test 8: Typing Indicator - Auto-Clear
+
+### Objective
+Verify typing indicator auto-clears after 3 seconds of inactivity.
+
+### Steps
+
+1. **User A**: Log in in Browser 1
+2. **User B**: Log in in Browser 2
+3. **User B**: Type something and then stop (don't clear input)
+4. Wait 3-4 seconds
+
+### Expected Results
+
+- [ ] Typing indicator disappears after ~3 seconds of no typing activity
+- [ ] This prevents stale "typing" states
+
+---
+
+## Test 9: User Profile Panel - Open
+
+### Objective
+Verify the user profile panel opens when clicking on an online user.
+
+### Steps
+
+1. Have at least 2 users logged in
+2. Click on the online users indicator
+3. Click on another user's name/avatar in the dropdown
+
+### Expected Results
+
+- [ ] A slide-out panel appears from the right
+- [ ] Panel shows the user's large avatar
+- [ ] Panel shows the user's GitHub username
+- [ ] Panel shows "Online" status with green indicator
+- [ ] Panel shows "Online Since" timestamp
+- [ ] Panel shows "Last Active" timestamp
+- [ ] Panel shows GitHub link
+
+---
+
+## Test 10: User Profile Panel - Actions
+
+### Objective
+Verify profile panel action buttons work correctly.
+
+### Steps
+
+1. Open a user's profile panel (from Test 9)
+2. Click the "Mention @username" button
+3. Close the panel and open it again
+4. Click the "View on GitHub" button
+
+### Expected Results
+
+- [ ] "Mention" button closes panel (TODO: should insert @username in composer)
+- [ ] "View on GitHub" opens new tab to user's GitHub profile
+- [ ] GitHub profile URL is correctly formatted
+
+---
+
+## Test 11: User Profile Panel - Close Methods
+
+### Objective
+Verify all methods of closing the profile panel work.
+
+### Steps
+
+1. Open a user's profile panel
+2. Click the X button in the panel header
+3. Open the panel again
+4. Press the Escape key
+5. Open the panel again
+6. Click outside the panel (on the backdrop)
+
+### Expected Results
+
+- [ ] X button closes the panel
+- [ ] Escape key closes the panel
+- [ ] Clicking backdrop closes the panel
+
+---
+
+## Test 12: Human User Autocomplete
+
+### Objective
+Verify human users appear in @ mention autocomplete.
+
+### Steps
+
+1. Have User A and User B both logged in
+2. Have User A send at least one message
+3. **User B**: Start typing `@` in the message input
+4. Observe the autocomplete dropdown
+
+### Expected Results
+
+- [ ] User A appears in the autocomplete list
+- [ ] Human users show with purple color and person icon
+- [ ] Human users are labeled as "Human user"
+- [ ] Selecting a human user inserts @username in message
+
+---
+
+## Test 13: Input Validation - Invalid Username
+
+### Objective
+Verify the server rejects invalid usernames (security feature).
+
+### Steps
+
+This test requires developer tools or a custom client:
+
+1. Open browser developer tools
+2. Find the presence WebSocket connection
+3. Try to send a join message with an invalid username (e.g., containing special characters)
+
+### Expected Results
+
+- [ ] Server rejects the invalid username
+- [ ] No error is displayed to the user (silent rejection)
+- [ ] Console logs show "Invalid username rejected"
+
+---
+
+## Test 14: Security - Cannot Remove Other Users
+
+### Objective
+Verify users cannot forcibly remove others from online list.
+
+### Steps
+
+This test requires developer tools:
+
+1. User A and User B both logged in
+2. Using developer tools, try to send a leave message with User B's username from User A's connection
+
+### Expected Results
+
+- [ ] Server rejects the leave attempt
+- [ ] User B remains in the online list
+- [ ] Console logs show security warning
+
+---
+
+## Troubleshooting
+
+### Presence Not Updating
+
+1. Check browser console for WebSocket errors
+2. Verify `/ws/presence` WebSocket is connected
+3. Refresh the page to reconnect
+
+### Typing Indicator Stuck
+
+1. This may indicate a WebSocket issue
+2. Typing indicators auto-clear after 3 seconds
+3. Refresh to reset
+
+### Profile Panel Not Opening
+
+1. Ensure you're clicking on a user, not just the indicator
+2. Check for JavaScript errors in console
+
+---
+
+## Notes
+
+- All presence features require cloud mode (GitHub OAuth login)
+- Local mode does not support multi-user presence
+- WebSocket connections may take a moment to establish on page load

package/docs/agent-relay-snippet.md

@@ -16,7 +16,25 @@ Your message here.>>>
 Broadcast to all agents.>>>
 ```
 
-**CRITICAL:** Always end with `>>>` at the end of the last line of content!
+**CRITICAL:** Always close multi-line messages with `>>>` on its own line!
+
+## Communication Protocol
+
+**ACK immediately** - When you receive a task, acknowledge it before starting work:
+
+```
+->relay:Sender <<<
+ACK: Brief description of task received>>>
+```
+
+Then proceed with your work. This confirms message delivery and lets the sender know you're on it.
+
+**Report completion** - When done, send a completion message:
+
+```
+->relay:Sender <<<
+DONE: Brief summary of what was completed>>>
+```
 
 ## Receiving Messages
 
@@ -25,6 +43,27 @@ Messages appear as:
 Relay message from Alice [abc123]: Message content here
 ```
 
+### Channel Routing (Important!)
+
+Messages from #general (broadcast channel) include a `[#general]` indicator:
+```
+Relay message from Alice [abc123] [#general]: Hello everyone!
+```
+
+**When you see `[#general]`**: Reply to `*` (broadcast), NOT to the sender directly.
+
+```
+# Correct - responds to #general channel
+->relay:* <<<
+Response to the group message.>>>
+
+# Wrong - sends as DM to sender instead of to the channel
+->relay:Alice <<<
+Response to the group message.>>>
+```
+
+This ensures your response appears in the same channel as the original message.
+
 If truncated, read full message:
 ```bash
 agent-relay read abc123
@@ -39,25 +78,89 @@ Spawn workers to delegate tasks:
 ->relay:release WorkerName
 ```
 
+## Threads
+
+Use threads to group related messages together. Thread syntax:
+
+```
+->relay:AgentName [thread:topic-name] <<<
+Your message here.>>>
+```
+
+**When to use threads:**
+- Working on a specific issue (e.g., `[thread:agent-relay-299]`)
+- Back-and-forth discussions with another agent
+- Code review conversations
+- Any multi-message topic you want grouped
+
+**Examples:**
+
+```
+->relay:Protocol [thread:auth-feature] <<<
+How should we handle token refresh?>>>
+
+->relay:Frontend [thread:auth-feature] <<<
+Use a 401 interceptor that auto-refreshes.>>>
+
+->relay:Reviewer [thread:pr-123] <<<
+Please review src/auth/*.ts>>>
+
+->relay:Developer [thread:pr-123] <<<
+LGTM, approved!>>>
+```
+
+Thread messages appear grouped in the dashboard with reply counts.
+
 ## Common Patterns
 
 ```
-->relay:* <<<
-STATUS: Starting work on auth module>>>
+->relay:Lead <<<
+ACK: Starting /api/register implementation>>>
 
 ->relay:* <<<
+STATUS: Working on auth module>>>
+
+->relay:Lead <<<
 DONE: Auth module complete>>>
 
 ->relay:Developer <<<
 TASK: Implement /api/register>>>
 
-->relay:Reviewer <<<
+->relay:Reviewer [thread:code-review-auth] <<<
 REVIEW: Please check src/auth/*.ts>>>
 
 ->relay:Architect <<<
 QUESTION: JWT or sessions?>>>
 ```
 
+## Cross-Project Messaging
+
+When running in bridge mode (multiple projects connected), use `project:agent` format:
+
+```
+->relay:frontend:Designer <<<
+Please update the login UI for the new auth flow>>>
+
+->relay:backend:lead <<<
+API question - should we use REST or GraphQL?>>>
+
+->relay:shared-lib:* <<<
+New utility functions available, please pull latest>>>
+```
+
+**Format:** `->relay:project-id:agent-name`
+
+**Special targets:**
+- `->relay:project:lead` - Message the lead agent of that project
+- `->relay:project:*` - Broadcast to all agents in that project
+- `->relay:*:*` - Broadcast to ALL agents in ALL projects
+
+**Cross-project threads:**
+```
+->relay:frontend:Designer [thread:auth-feature] <<<
+UI mockups ready for review>>>
+```
+
 ## Rules
 
 - Pattern must be at line start (whitespace OK)

package/docs/guides/CLOUD.md

@@ -0,0 +1,236 @@
+# Agent Relay Cloud
+
+Get started with [agent-relay.com](https://agent-relay.com) - the fully managed way to orchestrate AI agents across your repositories.
+
+## Overview
+
+Agent Relay Cloud handles everything for you:
+- Automatic server provisioning
+- GitHub repository integration
+- Multi-provider agent authentication (Claude, Codex, Gemini)
+- Team management and collaboration
+- Centralized dashboard and logs
+
+**No servers to manage. No infrastructure to maintain.**
+
+## Getting Started
+
+### 1. Sign Up
+
+Visit [agent-relay.com](https://agent-relay.com) and click **Continue with GitHub**.
+
+This:
+- Creates your Agent Relay account
+- Automatically connects GitHub Copilot
+- Gives us access to list your repositories
+
+### 2. Connect Your Repositories
+
+Select which repositories Agent Relay should manage:
+
+1. Browse your GitHub repos
+2. Check the ones you want to connect
+3. Click **Continue**
+
+We'll:
+- Install the Agent Relay GitHub App on selected repos
+- Clone repos to your cloud workspace
+- Set up webhooks for PR/issue events
+
+### 3. Connect AI Providers
+
+Connect the AI providers you want to use. Click **Login with [Provider]** for each:
+
+| Provider | What You Get |
+|----------|--------------|
+| **Anthropic** | Claude Code - recommended for code tasks |
+| **OpenAI** | Codex and ChatGPT models |
+| **Google** | Gemini - multi-modal capabilities |
+| **GitHub Copilot** | Auto-connected via GitHub signup |
+
+You authenticate with your existing provider accounts. No API keys to manage.
+
+### 4. Start Using Agents
+
+Once connected, you can:
+
+**From the Dashboard:**
+- Spawn agents manually
+- View real-time agent activity
+- Monitor message flows between agents
+
+**From GitHub:**
+- Open a PR to trigger automatic code review
+- Use `@agent-relay` in PR comments to chat with agents
+- Agents respond directly in your PRs
+
+**From the CLI:**
+```bash
+# Connect your local environment to cloud
+agent-relay cloud login
+
+# Spawn a cloud agent from anywhere
+agent-relay cloud spawn Alice claude "Review the auth module"
+```
+
+## Dashboard
+
+Your dashboard is available at `https://app.agent-relay.com` after login.
+
+### Features
+
+- **Real-time Activity Feed** - See all agent messages as they happen
+- **Agent Management** - Spawn, monitor, and stop agents
+- **Repository Overview** - Connected repos and their status
+- **Team Settings** - Manage team members and permissions
+- **Usage & Billing** - Track compute hours and plan limits
+
+## Plans
+
+| Feature | Free | Pro | Team | Enterprise |
+|---------|------|-----|------|------------|
+| Workspaces | 1 | 5 | 20 | Unlimited |
+| Repositories | 3 | 20 | 100 | Unlimited |
+| Concurrent Agents | 2 | 10 | 50 | Unlimited |
+| Compute Hours/Month | 10 | 100 | 500 | Unlimited |
+| Coordinator Agents | - | ✓ | ✓ | ✓ |
+| Priority Support | - | ✓ | ✓ | ✓ |
+| SSO/SAML | - | - | - | ✓ |
+
+See [Pricing](/pricing) for current rates.
+
+## Teams
+
+### Creating a Team
+
+1. Go to **Settings → Teams**
+2. Click **Create Team**
+3. Name your team and invite members
+
+### Team Roles
+
+| Role | Permissions |
+|------|-------------|
+| **Owner** | Full access, billing, can delete team |
+| **Admin** | Manage members, repos, agents |
+| **Member** | Spawn agents, view activity |
+
+### Shared Credentials
+
+Team admins can share provider credentials with team members, so everyone can spawn agents without individual logins.
+
+## Project Groups
+
+Organize related repositories into project groups for coordinated multi-repo work.
+
+### Creating a Project Group
+
+1. Go to **Settings → Project Groups**
+2. Click **Create Group**
+3. Add repositories to the group
+4. Optionally enable a **Coordinator Agent** (Pro+)
+
+### Coordinator Agents
+
+Coordinator agents (Pro plans and above) oversee work across all repos in a project group:
+
+- Delegate tasks to repo-specific agents
+- Track progress across the group
+- Ensure consistency between repos
+
+## CLI Integration
+
+Connect your local terminal to Agent Relay Cloud:
+
+```bash
+# Login to cloud
+agent-relay cloud login
+
+# Check connection status
+agent-relay cloud status
+
+# List your cloud workspaces
+agent-relay cloud workspaces
+
+# Spawn a cloud agent
+agent-relay cloud spawn MyAgent claude "Fix the login bug"
+
+# View cloud agent logs
+agent-relay cloud logs MyAgent
+```
+
+## GitHub Integration
+
+### Webhooks
+
+Agent Relay listens for:
+- **Pull Requests** - Automatic code review
+- **Issues** - Task assignment to agents
+- **Comments** - `@agent-relay` mentions
+
+### PR Comments
+
+Interact with agents directly in PRs:
+
+```
+@agent-relay review this PR
+@agent-relay explain the changes in src/auth/
+@agent-relay suggest improvements
+```
+
+### Issue Assignment
+
+Assign issues to agents:
+
+```
+@agent-relay work on this issue
+@agent-relay implement this feature using Claude
+```
+
+## Security
+
+### Data Protection
+
+- All data encrypted at rest (AES-256)
+- TLS 1.3 for all connections
+- SOC 2 Type II compliant (Enterprise)
+
+### Credential Security
+
+- OAuth tokens encrypted with per-user keys
+- Automatic token refresh
+- No API keys stored in plaintext
+
+### Workspace Isolation
+
+- Each workspace runs in isolated containers
+- No shared filesystem between users
+- Network isolation between workspaces
+
+## Troubleshooting
+
+### Agent Won't Spawn
+
+1. Check provider connection in **Settings → Providers**
+2. Verify you haven't exceeded plan limits
+3. Check the activity log for errors
+
+### GitHub Webhooks Not Working
+
+1. Go to **Settings → Repositories**
+2. Click **Resync** on the affected repo
+3. Verify the GitHub App is still installed
+
+### Token Expired
+
+If you see "Token expired" errors:
+
+1. Go to **Settings → Providers**
+2. Click **Reconnect** on the affected provider
+3. Re-authenticate with the provider
+
+## Support
+
+- **Documentation**: [docs.agent-relay.com](https://docs.agent-relay.com)
+- **GitHub Issues**: [github.com/khaliqgant/agent-relay/issues](https://github.com/khaliqgant/agent-relay/issues)
+- **Email**: support@agent-relay.com (Pro+ plans)