agent-relay 1.1.0 → 1.2.0

package/docs/proposals/custom-commands.md

@@ -0,0 +1,368 @@
+# Custom Relay Commands: Design Spec
+
+> **Status:** Proposal
+> **Decision Required:** Which implementation approach?
+> **Created:** 2026-01-04
+
+---
+
+## Overview
+
+Allow users to define custom command patterns that trigger code execution when agents output them.
+
+```
+->deploy:staging     →  executes user-defined deploy script
+->jira:create "Bug"  →  runs Jira integration, returns ticket ID
+->test:e2e           →  runs tests, injects results back to agent
+```
+
+---
+
+## Use Cases
+
+### DevOps & CI/CD
+```
+->deploy:staging              # Deploy to environment
+->rollback:prod               # Rollback last deployment
+->build:docker                # Build and push container
+```
+
+### Integrations
+```
+->jira:create "Login broken"  # Create ticket, return ID
+->slack:#team "Build done"    # Post to Slack channel
+->github:pr "Feature X"       # Create pull request
+```
+
+### Testing & Quality
+```
+->test:unit                   # Run unit tests
+->test:e2e --headed           # Run E2E with browser
+->lint:fix                    # Run linter with autofix
+```
+
+### Context & Knowledge
+```
+->load:api-docs               # Inject API documentation
+->search:codebase "auth"      # Search and inject results
+->context:clear               # Clear injected context
+```
+
+### Agent Coordination
+```
+->assign:Alice "Review PR"    # Assign task + notify
+->escalate:Lead "Blocked"     # Escalate with context
+->handoff:Bob                 # Transfer work to another agent
+```
+
+---
+
+## Design Options
+
+### Option A: Script Directory (Convention-Based)
+
+**Pattern:** `->cmd:{name} {args}` → `.relay/commands/{name}.sh {args}`
+
+```
+.relay/
+  commands/
+    deploy.sh      # ->cmd:deploy staging
+    test.sh        # ->cmd:test unit
+    jira.sh        # ->cmd:jira create "Bug title"
+```
+
+**Example script:**
+```bash
+#!/bin/bash
+# .relay/commands/deploy.sh
+ENV="$1"
+./scripts/deploy.sh "$ENV" 2>&1
+echo "[DEPLOY] Completed deployment to $ENV"
+```
+
+**Pros:**
+- Zero configuration
+- Works with any language (bash, python, node)
+- Easy to understand
+
+**Cons:**
+- Single prefix (`->cmd:`)
+- Limited pattern matching
+- No validation or typing
+
+---
+
+### Option B: YAML Configuration
+
+**Config file:** `.relay/commands.yaml`
+
+```yaml
+commands:
+  # Simple script mapping
+  deploy:
+    pattern: "->deploy:{env}"
+    run: "./scripts/deploy.sh $env"
+
+  # With validation
+  test:
+    pattern: "->test:{suite}"
+    run: "npm test -- --suite=$suite"
+    validate:
+      suite: ["unit", "e2e", "integration"]
+    timeout: 300000
+
+  # Integration with response handling
+  jira:
+    pattern: "->jira:create {title}"
+    run: "node .relay/integrations/jira.js create '$title'"
+    response: inject  # inject | silent | broadcast
+
+  # Restricted command
+  deploy-prod:
+    pattern: "->deploy:prod"
+    run: "./scripts/deploy.sh prod"
+    security:
+      requireApproval: true
+      allowedAgents: ["Lead"]
+```
+
+**Pros:**
+- Custom prefixes per command
+- Validation rules
+- Security controls
+- Configurable response handling
+
+**Cons:**
+- Requires configuration
+- YAML can get complex
+
+---
+
+### Option C: TypeScript Handlers (Programmatic)
+
+**Handler file:** `.relay/commands/deploy.ts`
+
+```typescript
+import { defineCommand, type CommandContext } from 'agent-relay';
+
+export default defineCommand({
+  // Pattern with named captures
+  pattern: /^->deploy:(?<env>staging|prod)$/,
+
+  // Optional validation
+  validate({ env }) {
+    if (env === 'prod' && !process.env.PROD_DEPLOY_ENABLED) {
+      return 'Production deploys are disabled';
+    }
+  },
+
+  // Execution
+  async execute(ctx: CommandContext) {
+    const { env } = ctx.match.groups;
+    const { agent, inject, broadcast } = ctx;
+
+    // Run deployment
+    const result = await ctx.exec(`./deploy.sh ${env}`);
+
+    // Inject response to calling agent
+    await inject(`[DEPLOY] ${env}: ${result.stdout}`);
+
+    // Optionally notify others
+    if (env === 'prod') {
+      await broadcast(`Production deployed by ${agent.name}`);
+    }
+
+    // Return structured data (stored in message metadata)
+    return {
+      env,
+      success: result.exitCode === 0,
+      duration: result.duration,
+    };
+  },
+});
+```
+
+**Auto-discovery:** All `.ts` files in `.relay/commands/` are loaded.
+
+**Pros:**
+- Full programmatic control
+- Type safety
+- Can interact with relay (inject, broadcast, spawn)
+- Async/await support
+- Structured return data
+
+**Cons:**
+- Requires TypeScript knowledge
+- More complex setup
+- Needs compilation step
+
+---
+
+### Option D: Hybrid (Recommended)
+
+Combine A + B: Convention with optional configuration.
+
+**Default behavior (zero config):**
+```
+->cmd:deploy staging  →  .relay/commands/deploy.sh staging
+```
+
+**With config (opt-in):**
+```yaml
+# .relay/commands.yaml
+commands:
+  deploy:
+    pattern: "->deploy:{env}"  # Custom prefix
+    run: ".relay/commands/deploy.sh $env"
+
+  # Or inline script
+  notify:
+    pattern: "->notify:{channel} {message}"
+    run: |
+      curl -X POST "$SLACK_WEBHOOK" \
+        -d "{\"channel\": \"$channel\", \"text\": \"$message\"}"
+```
+
+**Progression:**
+1. Start with `->cmd:name` convention (no config)
+2. Add `.relay/commands.yaml` when you need custom patterns
+3. Use `.ts` handlers for complex logic (future)
+
+---
+
+## Response Handling
+
+| Mode | Behavior | Use Case |
+|------|----------|----------|
+| `inject` | Output sent to calling agent | Default - agent sees result |
+| `silent` | No response | Fire-and-forget (notifications) |
+| `broadcast` | Output to all agents | Team-wide announcements |
+| `reply:{agent}` | Output to specific agent | Targeted responses |
+
+**Default:** `inject` (most useful for agent workflows)
+
+---
+
+## Security Model
+
+### Execution Context
+- Commands run in project directory
+- Inherit environment from daemon
+- Can access `RELAY_*` env vars
+
+### Access Control (Optional)
+```yaml
+commands:
+  deploy-prod:
+    pattern: "->deploy:prod"
+    run: "./deploy.sh prod"
+    security:
+      # Require human approval in dashboard
+      requireApproval: true
+
+      # Restrict to specific agents
+      allowedAgents: ["Lead", "DevOps"]
+
+      # Rate limiting
+      rateLimit: "1/hour"
+
+      # Audit logging
+      audit: true
+```
+
+### Sandboxing (Future)
+- Optional Docker/VM isolation
+- Resource limits (CPU, memory, time)
+- Network restrictions
+
+---
+
+## Implementation Plan
+
+### Phase 1: Script Directory (MVP)
+- [ ] Detect `->cmd:{name}` pattern in parser
+- [ ] Execute `.relay/commands/{name}.sh` with args
+- [ ] Inject stdout back to agent
+- [ ] Handle errors gracefully
+
+### Phase 2: YAML Configuration
+- [ ] Parse `.relay/commands.yaml`
+- [ ] Support custom patterns
+- [ ] Add validation rules
+- [ ] Response mode configuration
+
+### Phase 3: Dashboard Integration
+- [ ] Show command executions in dashboard
+- [ ] Approval workflow UI
+- [ ] Audit log viewer
+
+### Phase 4: TypeScript Handlers (Future)
+- [ ] Hot-reload `.ts` command files
+- [ ] Provide `CommandContext` API
+- [ ] Type definitions package
+
+---
+
+## Decision Required
+
+**Which approach should we implement first?**
+
+| Option | Complexity | Flexibility | Time to MVP |
+|--------|------------|-------------|-------------|
+| A. Script Directory | Low | Low | 1-2 days |
+| B. YAML Config | Medium | High | 3-5 days |
+| C. TypeScript | High | Very High | 1-2 weeks |
+| D. Hybrid (A→B) | Low→Medium | Progressive | 2 days + iterate |
+
+**Recommendation:** Option D (Hybrid)
+- Ship script directory first (works immediately)
+- Add YAML config based on user feedback
+- TypeScript handlers as future enhancement
+
+---
+
+## Open Questions
+
+1. **Prefix:** Single `->cmd:` or allow any `->prefix:`?
+2. **Discovery:** Auto-discover scripts or require registration?
+3. **Async:** How to handle long-running commands (>30s)?
+4. **Errors:** Inject error output or handle differently?
+5. **Chaining:** Can command output trigger another command?
+
+---
+
+## Examples
+
+### Minimal Setup (Phase 1)
+```bash
+# Create command
+mkdir -p .relay/commands
+cat > .relay/commands/deploy.sh << 'EOF'
+#!/bin/bash
+echo "Deploying to $1..."
+./scripts/deploy.sh "$1"
+echo "Done!"
+EOF
+chmod +x .relay/commands/deploy.sh
+
+# Agent uses it
+->cmd:deploy staging
+```
+
+### With Configuration (Phase 2)
+```yaml
+# .relay/commands.yaml
+commands:
+  deploy:
+    pattern: "->deploy:{env}"
+    run: ".relay/commands/deploy.sh $env"
+    validate:
+      env: ["staging", "prod"]
+    security:
+      requireApproval:
+        when: "$env == 'prod'"
+```
+
+---
+
+*Spec created 2026-01-04*

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`