agent-relay 1.0.22 → 1.2.0

package/docs/tasks/global-skills-system.tasks.md

@@ -0,0 +1,230 @@
+# Agent Relay Skills via PRPM
+
+Leverage PRPM (Prompt Package Manager) to distribute agent-relay skills that users can opt into.
+
+## Overview
+
+PRPM already provides:
+- Registry at `registry.prpm.dev`
+- `prpm install @org/package` CLI
+- Lockfile tracking (`prpm.lock`)
+- Format conversion (claude, cursor, agents.md)
+- Subtypes: skill, agent, rule, snippet
+- Lazy loading (`eager: false`)
+
+**We should publish `@agent-relay/*` packages to PRPM instead of building custom infrastructure.**
+
+## Current State
+
+Already using prpm in this repo (see `prpm.lock`):
+- `@agent-relay/agent-relay-snippet` - Relay messaging syntax
+- `@agent-relay/agent-relay-protocol` - Full protocol docs
+- Various skills from `@prpm/*`, `@anthropic/*`, `@my-senior-dev/*`
+
+## Problem: Global vs Project Skills
+
+PRPM installs to project directories (`.claude/skills/`). We need:
+- Skills NOT in project source control
+- Skills available across all projects
+- Per-user opt-in, not per-project
+
+### Potential Solutions
+
+**A. PRPM Global Flag (feature request)**
+```bash
+prpm install --global @agent-relay/browser-testing
+# Installs to ~/.prpm/skills/ or ~/.config/prpm/skills/
+```
+
+**B. User-level prpm.lock**
+```
+~/.agent-relay/
+├── prpm.lock          # User's global skills
+└── .claude/skills/    # Installed skill content
+```
+Agent reads both project and user prpm.lock.
+
+**C. Workspace Bundle**
+Cloud workspaces come with @agent-relay skills pre-installed.
+Users don't manage - just available in cloud.
+
+## Proposed Skills to Publish
+
+### @agent-relay/workspace-capabilities
+Documentation for browser testing + container spawning.
+
+```json
+{
+  "name": "@agent-relay/workspace-capabilities",
+  "version": "1.0.0",
+  "description": "Browser testing (Playwright, VNC) and container spawning (Docker) for agent-relay workspaces",
+  "format": "claude",
+  "subtype": "skill",
+  "eager": false,
+  "tags": ["agent-relay", "browser-testing", "docker", "workspace"],
+  "files": [".claude/skills/workspace-capabilities/SKILL.md"]
+}
+```
+
+### @agent-relay/browser-testing
+Focused Playwright/screenshot skill.
+
+### @agent-relay/container-spawning
+Focused Docker/container skill.
+
+### @agent-relay/linear-integration
+Linear webhook/API patterns.
+
+### @agent-relay/slack-integration
+Slack bot patterns.
+
+### @agent-relay/workspace-pack (collection)
+Bundle of all workspace skills.
+
+```json
+{
+  "collections": [{
+    "id": "workspace-pack",
+    "name": "Agent Relay Workspace Pack",
+    "description": "All workspace capability skills",
+    "packages": [
+      { "packageId": "@agent-relay/workspace-capabilities" },
+      { "packageId": "@agent-relay/browser-testing" },
+      { "packageId": "@agent-relay/container-spawning" }
+    ]
+  }]
+}
+```
+
+## Tasks
+
+### prpm-global-research
+- [ ] Check if prpm supports `--global` flag
+- [ ] If not, evaluate: feature request vs workaround
+- [ ] Document findings
+
+Dependencies: none
+Priority: high
+
+### user-skills-directory
+- [ ] Define `~/.agent-relay/skills/` structure
+- [ ] Implement reading from user directory in daemon
+- [ ] Merge user + project skills in agent manifest
+
+Dependencies: prpm-global-research
+Priority: high
+
+### publish-workspace-capabilities
+- [ ] Create skill content (SKILL.md)
+- [ ] Create prpm.json manifest
+- [ ] Test locally with `prpm install .`
+- [ ] Publish to registry.prpm.dev
+
+Dependencies: none (can do in parallel)
+Priority: high
+
+### publish-browser-testing
+- [ ] Extract browser-specific content from workspace-capabilities
+- [ ] Create focused SKILL.md
+- [ ] Publish to registry
+
+Dependencies: publish-workspace-capabilities
+Priority: medium
+
+### publish-container-spawning
+- [ ] Extract container-specific content
+- [ ] Create focused SKILL.md
+- [ ] Publish to registry
+
+Dependencies: publish-workspace-capabilities
+Priority: medium
+
+### workspace-pack-collection
+- [ ] Create collection prpm.json
+- [ ] Bundle all workspace skills
+- [ ] Publish collection
+
+Dependencies: publish-browser-testing, publish-container-spawning
+Priority: low
+
+### cloud-workspace-provisioning
+- [ ] Pre-install @agent-relay skills in cloud workspace images
+- [ ] Or: fetch on workspace creation
+- [ ] Make configurable per-workspace
+
+Dependencies: publish-workspace-capabilities
+Priority: medium
+
+## Example Skill Content
+
+```markdown
+---
+name: workspace-capabilities
+description: Browser testing and container spawning for agent-relay workspaces
+---
+
+# Workspace Capabilities
+
+This workspace may have additional capabilities available.
+
+## Checking Availability
+
+Before using these features, verify they're available:
+
+\`\`\`typescript
+// Check for browser testing
+const hasBrowser = process.env.DISPLAY !== undefined;
+
+// Check for container spawning
+const hasDocker = existsSync('/var/run/docker.sock');
+\`\`\`
+
+## Browser Testing
+
+[Content about Playwright, screenshots, VNC...]
+
+## Container Spawning
+
+[Content about Docker, presets, resource limits...]
+```
+
+## User Flow
+
+```bash
+# Option A: Global install (if prpm supports it)
+prpm install --global @agent-relay/workspace-pack
+
+# Option B: User directory workaround
+cd ~/.agent-relay
+prpm install @agent-relay/workspace-pack
+
+# Option C: Cloud workspace (automatic)
+# Skills pre-installed, just use them
+```
+
+## Why PRPM Over Custom
+
+| Custom System | PRPM |
+|--------------|------|
+| Build registry | ✅ Already exists |
+| Build CLI | ✅ Already exists |
+| Build lockfile | ✅ Already exists |
+| Version management | ✅ Already exists |
+| Format conversion | ✅ Already exists |
+
+**PRPM gives us distribution for free. We just publish packages.**
+
+## Open Questions for PRPM
+
+1. **Global installs** - `prpm install --global`?
+2. **Multiple lockfile locations** - project + user?
+3. **Conditional activation** - `activationCondition` field?
+
+May need to contribute these features or work around them.
+
+## References
+
+- `prpm.lock` - Current installed packages
+- `.claude/skills/prpm-json-best-practices-skill/` - How to create packages
+- `docs/tasks/workspace-capabilities.tasks.md` - Runtime capability discovery
+- Implementation: `src/daemon/services/browser-testing.ts`, `container-spawner.ts`

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