agent-relay 1.1.0 → 1.2.0

package/docs/tasks/webhook-integrations.tasks.md

@@ -0,0 +1,184 @@
+# Webhook Integrations - Task Breakdown
+
+Tasks for future iterations of the webhook and integrations system.
+Convert to beads tasks with: `bd import docs/tasks/webhook-integrations.tasks.md`
+
+## Phase 1: Linear Full Integration [priority: high]
+
+### linear-outbound-comments
+- [ ] Create LinearIntegration service class
+- [ ] Implement createComment() with Linear GraphQL API
+- [ ] Add Linear API key management to workspace settings
+- [ ] Add encryption for stored API keys
+
+Dependencies: none
+Estimate: 2 story points
+
+### linear-outbound-state
+- [ ] Implement setIssueState() for state transitions
+- [ ] Implement getAvailableStates() to fetch team states
+- [ ] Add state ID caching with TTL
+
+Dependencies: linear-outbound-comments
+Estimate: 1 story point
+
+### linear-outbound-issues
+- [ ] Implement createIssue() with full CreateIssueInput
+- [ ] Implement updateIssue() for editing
+- [ ] Implement assignIssue() for assignment changes
+- [ ] Add label operations (add/remove)
+
+Dependencies: linear-outbound-state
+Estimate: 3 story points
+
+### linear-webhook-state-change
+- [ ] Parse issue state change webhooks
+- [ ] Add `issue_state_changed` event type
+- [ ] Create rule for auto-responding to state changes
+
+Dependencies: none
+Estimate: 1 story point
+
+### linear-webhook-due-dates
+- [ ] Parse due date approaching events
+- [ ] Add `issue_due_soon` event type with configurable threshold
+- [ ] Create reminder rule for approaching due dates
+
+Dependencies: linear-webhook-state-change
+Estimate: 1 story point
+
+## Phase 2: Slack Enhanced [priority: high]
+
+### slack-slash-commands
+- [ ] Create slash command handler endpoint
+- [ ] Parse slash command payloads
+- [ ] Add slash_command event type
+- [ ] Create agent spawning from slash commands
+
+Dependencies: none
+Estimate: 2 story points
+
+### slack-interactive-components
+- [ ] Handle button click callbacks
+- [ ] Handle modal submission callbacks
+- [ ] Add interactive_message event type
+- [ ] Implement openModal() and updateModal()
+
+Dependencies: slack-slash-commands
+Estimate: 3 story points
+
+### slack-rich-messages
+- [ ] Implement postBlocks() with Block Kit
+- [ ] Add common block templates (code, error, success)
+- [ ] Add file upload support
+- [ ] Add scheduled message support
+
+Dependencies: none
+Estimate: 2 story points
+
+## Phase 3: GitHub Enhanced [priority: high]
+
+### github-pr-management
+- [ ] Parse PR opened/updated webhooks
+- [ ] Add pr_opened, pr_updated event types
+- [ ] Implement PR review request parsing
+- [ ] Add createPR() outbound action
+
+Dependencies: none
+Estimate: 3 story points
+
+### github-check-runs
+- [ ] Implement createCheckRun() for CI status
+- [ ] Implement updateCheckRun() for progress
+- [ ] Add annotations support for inline errors
+- [ ] Parse deployment status webhooks
+
+Dependencies: github-pr-management
+Estimate: 2 story points
+
+### github-issue-management
+- [ ] Implement createIssue()
+- [ ] Implement addLabels() and removeLabels()
+- [ ] Implement assignUsers()
+- [ ] Add issue linking support
+
+Dependencies: none
+Estimate: 2 story points
+
+## Phase 4: Agent Tools [priority: medium]
+
+### agent-integration-tools
+- [ ] Create integration tools accessible to agents
+- [ ] Add LinearTool for agent actions
+- [ ] Add SlackTool for agent messages
+- [ ] Add GitHubTool for agent operations
+
+Dependencies: linear-outbound-issues, slack-rich-messages, github-issue-management
+Estimate: 4 story points
+
+### agent-permissions
+- [ ] Implement AgentIntegrationPermissions type
+- [ ] Add permission checking before actions
+- [ ] Create permission UI in spawn modal
+- [ ] Add audit logging for all external calls
+
+Dependencies: agent-integration-tools
+Estimate: 2 story points
+
+## Phase 5: Additional Integrations [priority: low]
+
+### jira-integration
+- [ ] Create Jira webhook parser
+- [ ] Implement JiraIntegration service
+- [ ] Add Jira responder
+- [ ] Add workspace settings for Jira
+
+Dependencies: agent-integration-tools
+Estimate: 4 story points
+
+### gitlab-integration
+- [ ] Create GitLab webhook parser
+- [ ] Implement GitLabIntegration service
+- [ ] Add GitLab responder
+- [ ] Map GitLab events to normalized format
+
+Dependencies: agent-integration-tools
+Estimate: 3 story points
+
+### discord-integration
+- [ ] Create Discord webhook parser
+- [ ] Implement DiscordIntegration service
+- [ ] Add Discord responder
+- [ ] Handle Discord-specific message formatting
+
+Dependencies: agent-integration-tools
+Estimate: 3 story points
+
+## Testing & Infrastructure
+
+### webhook-load-testing
+- [ ] Create load test suite for webhook endpoint
+- [ ] Measure p50/p95/p99 latencies
+- [ ] Test concurrent webhook handling
+- [ ] Add rate limiting if needed
+
+Dependencies: none
+Estimate: 2 story points
+
+### integration-mocks
+- [ ] Create mock Linear API server for tests
+- [ ] Create mock Slack API server for tests
+- [ ] Create mock GitHub API server for tests
+- [ ] Add E2E test suite with mocks
+
+Dependencies: none
+Estimate: 3 story points
+
+### sandbox-testing
+- [ ] Set up Linear sandbox workspace
+- [ ] Set up Slack test workspace
+- [ ] Set up GitHub test repository
+- [ ] Create E2E test suite with real APIs
+
+Dependencies: integration-mocks
+Estimate: 2 story points

package/docs/tasks/workspace-capabilities.tasks.md

@@ -0,0 +1,121 @@
+# Workspace Capabilities - Agent Discovery
+
+How should agents discover and use workspace capabilities (browser testing, container spawning, etc.)?
+
+## Problem Statement
+
+We have workspace capabilities:
+- Browser testing (Playwright, Xvfb, VNC)
+- Container spawning (Docker socket)
+- Potentially more in the future (E2B, Browserbase)
+
+**Challenge:** How do agents know these exist without bloating context for every agent?
+
+Current implementations exist but are not wired up:
+- `src/daemon/services/browser-testing.ts`
+- `src/daemon/services/container-spawner.ts`
+- `deploy/workspace/Dockerfile.browser`
+
+## Key Questions
+
+### 1. Static vs Dynamic Discovery
+- [ ] Should capabilities be in rules/skills (static, always injected)?
+- [ ] Should capabilities be discovered via MCP at runtime (dynamic)?
+- [ ] Hybrid: minimal hint in rules, full discovery via MCP?
+
+### 2. Cloud vs Local
+- [ ] Cloud workspaces: How are capabilities configured per workspace?
+- [ ] Local daemons: How does the daemon know what's available?
+- [ ] Should there be a "capability manifest" per workspace?
+
+### 3. Context Budget
+- [ ] How much context is acceptable for capability hints?
+- [ ] Should agents ask for capabilities only when needed?
+- [ ] Can we use tool descriptions instead of injected prompts?
+
+### 4. Opt-in vs Opt-out
+- [ ] Should capabilities be enabled by default?
+- [ ] Per-workspace configuration?
+- [ ] Per-agent configuration?
+
+## Design Options
+
+### Option A: MCP-Only Discovery
+Agents call `workspace_capabilities` tool to discover what's available.
+No static context injection.
+
+**Pros:** Zero context overhead, dynamic
+**Cons:** Agents might not know to call it
+
+### Option B: Minimal Hint + MCP
+One line in system prompt: "Call workspace_capabilities to check for browser/container tools"
+
+**Pros:** Tiny context, agents know to look
+**Cons:** Still some static injection
+
+### Option C: Workspace Manifest
+Each workspace has a capabilities.json that configures what's available.
+Cloud provisions this, agents read at startup.
+
+**Pros:** Explicit configuration
+**Cons:** More infrastructure
+
+### Option D: Auto-Detection
+MCP server auto-detects capabilities (checks DISPLAY, docker.sock) and only exposes available tools.
+
+**Pros:** Zero configuration, just works
+**Cons:** Magic behavior
+
+## Tasks
+
+### capability-discovery-design
+- [ ] Decide on discovery mechanism
+- [ ] Document decision rationale
+- [ ] Create ADR (Architecture Decision Record)
+
+Dependencies: none
+Priority: high
+
+### capability-manifest-schema
+- [ ] Define WorkspaceCapabilities schema
+- [ ] Define how cloud provisions capabilities
+- [ ] Define how daemon reads capabilities
+
+Dependencies: capability-discovery-design
+Priority: medium
+
+### mcp-capability-tools
+- [ ] Create MCP server for workspace tools
+- [ ] Only expose tools for available capabilities
+- [ ] Add workspace_capabilities discovery tool
+
+Dependencies: capability-manifest-schema
+Priority: medium
+
+### agent-prompting-strategy
+- [ ] Determine minimal context for capability awareness
+- [ ] Test with real agents
+- [ ] Measure context overhead
+
+Dependencies: capability-discovery-design
+Priority: medium
+
+### cloud-workspace-config
+- [ ] Add capabilities to workspace provisioning
+- [ ] UI for enabling/disabling capabilities
+- [ ] Per-workspace capability billing (if applicable)
+
+Dependencies: capability-manifest-schema
+Priority: low
+
+## Notes
+
+The core services are already implemented:
+- Browser testing: `src/daemon/services/browser-testing.ts`
+- Container spawning: `src/daemon/services/container-spawner.ts`
+- Browser Dockerfile: `deploy/workspace/Dockerfile.browser`
+
+What's missing is the discovery/awareness layer that doesn't bloat context.
+
+See also:
+- `docs/design/e2b-sandbox-integration.md` - E2B as alternative backend

package/docs/testing/RESILIENCY-TEST-PLAN-2026-01-01.md

@@ -0,0 +1,366 @@
+# Resiliency Features Test Plan
+
+**Date:** 2026-01-01
+**Features:** P0-P5 Leader Coordination and Failover
+**Branch:** `claude/add-continuous-claude-logic-kba3r`
+
+---
+
+## Prerequisites
+
+1. Build the project: `npm run build`
+2. Have at least 2-3 terminal windows ready
+3. Ensure `.beads/` directory exists with `issues.jsonl`
+
+---
+
+## P0: Stateless Lead Pattern
+
+### Test 1: Lead reads tasks from Beads
+
+**Setup:**
+```bash
+# Add a test task to Beads
+echo '{"id":"test-001","title":"Test task for P0","status":"open","priority":1,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}' >> .beads/issues.jsonl
+```
+
+**Test:**
+```typescript
+import { createStatelessLead } from './src/resiliency';
+
+const lead = createStatelessLead('.beads', 'TestLead', 'lead-001', {
+  sendRelay: async (to, msg) => console.log(`[RELAY] To ${to}: ${msg}`),
+  getAvailableWorkers: async () => ['Worker1', 'Worker2'],
+});
+
+await lead.start();
+// Wait 5 seconds for poll
+// Expected: Console shows "Assigned test-001 to Worker1"
+```
+
+**Verify:**
+```bash
+# Check task was assigned in Beads
+grep "test-001" .beads/issues.jsonl
+# Should show: "status":"in_progress","assignee":"Worker1"
+```
+
+**Pass criteria:**
+- [ ] Task status changed to `in_progress`
+- [ ] Task has `assignee` field set
+- [ ] Task has `leaseExpires` timestamp
+
+---
+
+## P1: Task Lease Timeouts
+
+### Test 2: Lease expiration returns task to queue
+
+**Setup:**
+```typescript
+// Create lead with short lease (10 seconds for testing)
+const lead = new StatelessLeadCoordinator({
+  beadsDir: '.beads',
+  agentName: 'TestLead',
+  agentId: 'lead-001',
+  pollIntervalMs: 2000,
+  heartbeatIntervalMs: 5000,
+  leaseDurationMs: 10000, // 10 second lease
+  sendRelay: async (to, msg) => console.log(`[RELAY] To ${to}: ${msg}`),
+  getAvailableWorkers: async () => ['Worker1'],
+});
+```
+
+**Test:**
+1. Start lead - task gets assigned
+2. Wait 15 seconds (lease expires)
+3. Add new worker to available list
+4. Wait for next poll
+
+**Verify:**
+```bash
+# Task should be reassigned after lease expires
+grep "test-001" .beads/issues.jsonl
+```
+
+**Pass criteria:**
+- [ ] Task returned to queue after lease expired
+- [ ] Task reassigned to new worker on next poll
+
+### Test 3: Lease renewal
+
+**Test:**
+```typescript
+// Worker renews lease before expiration
+await lead.renewLease('test-001', 'Worker1');
+```
+
+**Pass criteria:**
+- [ ] `leaseExpires` timestamp updated
+- [ ] Console shows "Renewed lease for test-001"
+
+---
+
+## P2: Leader Heartbeat File
+
+### Test 4: Heartbeat file created and updated
+
+**Test:**
+```typescript
+const lead = createStatelessLead('.beads', 'TestLead', 'lead-001', {
+  sendRelay: async () => {},
+  getAvailableWorkers: async () => [],
+});
+
+await lead.start();
+// Wait 15 seconds
+```
+
+**Verify:**
+```bash
+cat .beads/leader-heartbeat.json
+```
+
+**Expected output:**
+```json
+{
+  "leadName": "TestLead",
+  "leadId": "lead-001",
+  "timestamp": 1735689600000,
+  "activeTaskCount": 0,
+  "assignedAgents": []
+}
+```
+
+**Pass criteria:**
+- [ ] File exists at `.beads/leader-heartbeat.json`
+- [ ] `timestamp` updates every 10 seconds
+- [ ] `activeTaskCount` reflects assigned tasks
+
+---
+
+## P3: Watchdog in AgentSupervisor
+
+### Test 5: Watchdog detects stale leader
+
+**Terminal 1 - Start leader:**
+```typescript
+import { createStatelessLead } from './src/resiliency';
+
+const lead = createStatelessLead('.beads', 'Leader1', 'lead-001', {
+  sendRelay: async () => {},
+  getAvailableWorkers: async () => [],
+});
+await lead.start();
+console.log('Leader1 started');
+```
+
+**Terminal 2 - Start watchdog:**
+```typescript
+import { createLeaderWatchdog } from './src/resiliency';
+
+const watchdog = createLeaderWatchdog('.beads', 'Watchdog1', 'watch-001', {
+  onBecomeLeader: async () => console.log('I AM NOW LEADER!'),
+  getHealthyAgents: async () => [
+    { name: 'Watchdog1', id: 'watch-001', spawnedAt: new Date() }
+  ],
+});
+
+watchdog.on('leaderDetected', (h) => console.log('Leader detected:', h.leadName));
+watchdog.on('leaderStale', (d) => console.log('Leader stale!', d));
+watchdog.on('becameLeader', () => console.log('Became leader'));
+
+watchdog.start();
+```
+
+**Test:**
+1. Both running - watchdog should detect Leader1
+2. Kill Terminal 1 (Ctrl+C)
+3. Wait 35 seconds (stale threshold + check interval)
+
+**Pass criteria:**
+- [ ] Watchdog logs "Leader detected: Leader1"
+- [ ] After leader killed, watchdog logs "Leader stale!"
+- [ ] Watchdog logs "I AM NOW LEADER!"
+- [ ] New heartbeat file shows Watchdog1 as leader
+
+---
+
+## P4: Gossip-Based Health Broadcast
+
+### Test 6: Peer discovery via heartbeats
+
+**Terminal 1 - Agent A:**
+```typescript
+import { createGossipHealth } from './src/resiliency';
+
+const messages: string[] = [];
+const gossipA = createGossipHealth('AgentA', 'a-001', async (msg) => {
+  messages.push(msg);
+  console.log('[A broadcast]', msg);
+});
+
+gossipA.on('peerDiscovered', (p) => console.log('Discovered peer:', p.name));
+gossipA.start();
+
+// Simulate receiving B's heartbeat
+setTimeout(() => {
+  const heartbeat = {
+    type: 'HEARTBEAT',
+    agent: 'AgentB',
+    agentId: 'b-001',
+    timestamp: Date.now(),
+    load: 0.5,
+    healthy: true,
+    isLeader: false,
+    taskCount: 2,
+  };
+  gossipA.processHeartbeat(heartbeat);
+}, 5000);
+```
+
+**Pass criteria:**
+- [ ] AgentA broadcasts HEARTBEAT messages
+- [ ] "Discovered peer: AgentB" logged
+- [ ] `gossipA.getPeers()` returns AgentB
+
+### Test 7: Stale peer detection
+
+**Test:**
+```typescript
+// Process old heartbeat
+const staleHeartbeat = {
+  type: 'HEARTBEAT',
+  agent: 'AgentC',
+  agentId: 'c-001',
+  timestamp: Date.now() - 60000, // 1 minute old
+  load: 0,
+  healthy: true,
+  isLeader: false,
+  taskCount: 0,
+};
+
+gossipA.on('peerStale', (d) => console.log('Peer stale:', d.peer.name));
+gossipA.processHeartbeat(staleHeartbeat);
+
+// Wait for check interval (5 seconds)
+```
+
+**Pass criteria:**
+- [ ] "Peer stale: AgentC" logged within 10 seconds
+- [ ] `gossipA.getPeer('AgentC').healthy` is `false`
+
+---
+
+## P5: Full Leader Election
+
+### Test 8: Oldest agent wins election
+
+**Setup:** Start 3 agents at different times
+
+**Terminal 1 (start first):**
+```typescript
+import { getSupervisor } from './src/resiliency';
+
+const supervisor = getSupervisor();
+supervisor.start();
+
+supervisor.on('electionStarted', (d) => console.log('Election started:', d));
+supervisor.on('electionComplete', (d) => console.log('Election result:', d));
+supervisor.on('becameLeader', () => console.log('*** I AM LEADER ***'));
+
+supervisor.enableLeaderCoordination('.beads', async (to, msg) => {
+  console.log(`Send to ${to}: ${msg}`);
+});
+
+console.log('Supervisor started at', new Date().toISOString());
+```
+
+**Verify:**
+```bash
+cat .beads/leader-heartbeat.json
+# Should show first supervisor as leader
+```
+
+**Pass criteria:**
+- [ ] First started supervisor becomes leader
+- [ ] `leader-heartbeat.json` shows correct leader
+- [ ] Election uses "oldest" method
+
+### Test 9: Failover on leader death
+
+**Test:**
+1. Start Supervisor A (becomes leader)
+2. Start Supervisor B (detects A as leader)
+3. Kill Supervisor A
+4. Wait 35 seconds
+
+**Pass criteria:**
+- [ ] Supervisor B logs "Leader stale"
+- [ ] Supervisor B logs "*** I AM LEADER ***"
+- [ ] Heartbeat file updates to show B as leader
+
+---
+
+## Integration Test: Full Workflow
+
+### Test 10: End-to-end task assignment and failover
+
+**Setup:**
+```bash
+# Clear test data
+rm -f .beads/leader-heartbeat.json
+# Add test tasks
+cat >> .beads/issues.jsonl << 'EOF'
+{"id":"e2e-001","title":"E2E Test Task 1","status":"open","priority":1,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}
+{"id":"e2e-002","title":"E2E Test Task 2","status":"open","priority":2,"created_at":"2026-01-01T00:00:00Z","updated_at":"2026-01-01T00:00:00Z"}
+EOF
+```
+
+**Workflow:**
+1. Start Lead agent
+2. Start 2 Worker agents
+3. Verify tasks assigned
+4. Kill Lead agent
+5. Verify new leader elected
+6. Verify tasks continue processing
+
+**Pass criteria:**
+- [ ] Tasks assigned to workers
+- [ ] Leader failover completes in <35 seconds
+- [ ] No task duplication
+- [ ] Orphaned tasks return to queue
+
+---
+
+## Cleanup
+
+```bash
+# Remove test data
+grep -v "test-001\|e2e-00" .beads/issues.jsonl > .beads/issues.jsonl.tmp
+mv .beads/issues.jsonl.tmp .beads/issues.jsonl
+rm -f .beads/leader-heartbeat.json
+```
+
+---
+
+## Summary Checklist
+
+| Feature | Test | Status |
+|---------|------|--------|
+| P0: Stateless Lead | Test 1: Lead reads from Beads | ☐ |
+| P1: Lease Timeouts | Test 2: Lease expiration | ☐ |
+| P1: Lease Timeouts | Test 3: Lease renewal | ☐ |
+| P2: Heartbeat File | Test 4: File created/updated | ☐ |
+| P3: Watchdog | Test 5: Stale leader detection | ☐ |
+| P4: Gossip Health | Test 6: Peer discovery | ☐ |
+| P4: Gossip Health | Test 7: Stale peer detection | ☐ |
+| P5: Leader Election | Test 8: Oldest wins | ☐ |
+| P5: Leader Election | Test 9: Failover | ☐ |
+| Integration | Test 10: Full workflow | ☐ |
+
+---
+
+**Tester:** ____________________
+**Date Completed:** ____________________
+**Notes:**