agent-relay 1.0.22 → 1.2.0

package/docs/design/github-app-permissions.md

@@ -0,0 +1,264 @@
+# GitHub App Permissions
+
+This document describes the GitHub App permissions required for Agent Relay's features, particularly the CI failure webhook integration.
+
+## Overview
+
+Agent Relay uses a GitHub App to:
+1. Receive webhook events (installations, PRs, CI failures)
+2. Access repository code for cloning/syncing
+3. Create commits and push fixes
+4. Interact with PRs (comments, reviews)
+
+## Required Permissions
+
+### Repository Permissions
+
+| Permission | Access Level | Purpose |
+|------------|--------------|---------|
+| **Contents** | Read & Write | Clone repos, push commits, read files |
+| **Pull requests** | Read & Write | Read PR details, create/update PRs, comment |
+| **Checks** | Read | Receive check_run webhooks, read failure details |
+| **Actions** | Read | Receive workflow_run webhooks, read logs |
+| **Commit statuses** | Read | Read status checks, understand CI state |
+| **Metadata** | Read | Basic repo info (required for all apps) |
+
+### Organization Permissions
+
+| Permission | Access Level | Purpose |
+|------------|--------------|---------|
+| **Members** | Read | Identify organization members for access control |
+
+### Account Permissions
+
+| Permission | Access Level | Purpose |
+|------------|--------------|---------|
+| **Email addresses** | Read | User identification, notifications |
+
+## Webhook Events
+
+The following webhook events should be enabled:
+
+### Required Events
+
+| Event | Purpose |
+|-------|---------|
+| `installation` | Track app installations/uninstallations |
+| `installation_repositories` | Track repo access changes |
+| `check_run` | **CI failure detection** - triggers agent spawn |
+| `workflow_run` | Workflow-level failure tracking |
+| `push` | Detect new commits for sync |
+| `pull_request` | Track PR lifecycle |
+
+### Optional Events
+
+| Event | Purpose |
+|-------|---------|
+| `issues` | Future: issue-to-agent assignment |
+| `issue_comment` | Future: agent @mentions |
+| `pull_request_review` | Future: review request handling |
+| `check_suite` | Aggregate check status |
+
+## Configuration Steps
+
+### 1. Create GitHub App
+
+1. Go to GitHub Settings > Developer settings > GitHub Apps
+2. Click "New GitHub App"
+3. Fill in basic info:
+   - **Name**: Agent Relay (or your instance name)
+   - **Homepage URL**: Your dashboard URL
+   - **Webhook URL**: `https://your-domain.com/api/webhooks/github`
+
+### 2. Set Permissions
+
+Under "Permissions & events":
+
+**Repository permissions:**
+- Contents: Read and write
+- Pull requests: Read and write
+- Checks: Read-only
+- Actions: Read-only
+- Commit statuses: Read-only
+- Metadata: Read-only (default)
+
+**Organization permissions:**
+- Members: Read-only
+
+**Account permissions:**
+- Email addresses: Read-only
+
+### 3. Subscribe to Events
+
+Check the following events:
+- [x] Check run
+- [x] Workflow run
+- [x] Installation
+- [x] Installation and repositories
+- [x] Push
+- [x] Pull request
+
+### 4. Generate Keys
+
+1. Generate a private key (downloads .pem file)
+2. Note the App ID
+3. Generate a client secret for OAuth
+
+### 5. Configure Agent Relay
+
+Set environment variables:
+
+```bash
+# GitHub App credentials
+GITHUB_APP_ID=123456
+GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
+GITHUB_CLIENT_ID=Iv1.abc123
+GITHUB_CLIENT_SECRET=secret123
+
+# Webhook secret (generate a random string)
+GITHUB_WEBHOOK_SECRET=whsec_random_string_here
+```
+
+## Permission Rationale
+
+### Why Contents: Write?
+
+Agents need to push fixes to branches. This includes:
+- Creating new commits
+- Pushing to existing branches
+- Creating new branches for fixes
+
+### Why Checks: Read (not Write)?
+
+We only receive check failure events and read results. We don't:
+- Create our own checks
+- Update check status
+
+CI runs in GitHub Actions and creates its own checks.
+
+### Why Pull Requests: Write?
+
+Agents may need to:
+- Comment on PRs with fix summaries
+- Request reviews after fixes
+- Update PR descriptions
+
+### Why Actions: Read?
+
+For workflow_run events that provide:
+- Workflow-level failure context
+- Access to workflow logs (future)
+
+## Security Considerations
+
+### Webhook Secret
+
+Always configure a webhook secret:
+
+```typescript
+function verifyGitHubSignature(payload: string, signature: string, secret: string): boolean {
+  const expected = `sha256=${crypto
+    .createHmac('sha256', secret)
+    .update(payload)
+    .digest('hex')}`;
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expected)
+  );
+}
+```
+
+### Private Key Storage
+
+- Never commit the private key to version control
+- Use secure secret management (Vault, AWS Secrets Manager, etc.)
+- Rotate keys periodically
+
+### Installation Scope
+
+When users install the app:
+- Recommend "Only select repositories" over "All repositories"
+- Document which repos will be monitored
+- Allow easy un-installation
+
+### Token Expiry
+
+GitHub App installation tokens expire after 1 hour:
+- Cache tokens with expiry tracking
+- Refresh before expiration
+- Handle 401 errors with token refresh
+
+## Minimal Permissions Option
+
+For users who want minimal permissions:
+
+| Permission | Access | Notes |
+|------------|--------|-------|
+| Contents | Read | Can clone, cannot push |
+| Pull requests | Read | Can read PRs, cannot comment |
+| Checks | Read | Receive failures |
+
+With minimal permissions:
+- Agents can analyze failures but cannot push fixes
+- Manual intervention required for commits
+- Good for "notify only" mode
+
+## Events Flow
+
+```
+┌──────────────┐      webhook       ┌─────────────────┐
+│  GitHub CI   │ ──────────────────>│  Agent Relay    │
+│  (check_run  │                    │  /webhooks      │
+│   failed)    │                    └────────┬────────┘
+└──────────────┘                             │
+                                             │ verify signature
+                                             │ parse payload
+                                             ▼
+                                    ┌─────────────────┐
+                                    │  Record failure │
+                                    │  in database    │
+                                    └────────┬────────┘
+                                             │
+                                             │ spawn agent
+                                             ▼
+                                    ┌─────────────────┐
+                                    │  Agent fixes    │
+                                    │  and pushes     │
+                                    └────────┬────────┘
+                                             │
+                                             │ uses Contents:write
+                                             ▼
+                                    ┌─────────────────┐
+                                    │  GitHub CI      │
+                                    │  re-runs        │
+                                    └─────────────────┘
+```
+
+## Troubleshooting
+
+### Webhook Not Received
+
+1. Check webhook URL is correct and accessible
+2. Verify webhook secret matches configuration
+3. Check GitHub App webhook delivery logs
+4. Ensure firewall allows GitHub IPs
+
+### Permission Denied Errors
+
+1. Verify app is installed on the repository
+2. Check installation hasn't been suspended
+3. Confirm required permissions are granted
+4. Regenerate installation token
+
+### CI Events Not Triggering
+
+1. Verify `check_run` event is subscribed
+2. Check check is from a GitHub Action (not external CI)
+3. Ensure webhook URL is receiving events (check delivery logs)
+
+## References
+
+- [GitHub Apps documentation](https://docs.github.com/en/apps)
+- [Webhook events and payloads](https://docs.github.com/en/webhooks/webhook-events-and-payloads)
+- [GitHub App permissions](https://docs.github.com/en/rest/overview/permissions-required-for-github-apps)
+- [Check runs API](https://docs.github.com/en/rest/checks/runs)

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)