@desplega.ai/agent-swarm 1.2.0 → 1.9.0

package/docker-compose.example.yml

@@ -0,0 +1,137 @@
+# Docker Compose for Agent Swarm
+#
+# Usage:
+#   docker-compose -f docker-compose.example.yml --env-file .env up -d
+#
+# What it does:
+#  - Sets up an API service and multiple worker/lead agents
+#  - Deploys 2 worker agents and 1 lead agent by default
+#  - Uses volumes for persistent storage of logs, db and agent workspaces
+
+services:
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile
+
+    environment:
+      - ENV=${ENV:-development}
+      - API_KEY=${API_KEY}
+
+      - MCP_BASE_URL=${MCP_BASE_URL:-http://localhost:3013}
+      - APP_URL=${APP_URL:-http://localhost:5175}
+
+      # Optional: Enable Slack integration
+      - SLACK_DISABLE=${SLACK_DISABLE:-false}
+      - SLACK_BOT_TOKEN=${SLACK_BOT_TOKEN:-}
+      - SLACK_APP_TOKEN=${SLACK_APP_TOKEN:-}
+
+    ports:
+      - "3013:3013"
+
+    volumes:
+      # For the sqlite database
+      - swarm_api:/app
+
+    restart: unless-stopped
+
+  worker-1:
+    build:
+      context: .
+      dockerfile: Dockerfile.worker
+
+    environment:
+      - CLAUDE_CODE_OAUTH_TOKEN=${CLAUDE_CODE_OAUTH_TOKEN}
+      - API_KEY=${API_KEY}
+      - AGENT_ID=${AGENT_ID}
+      - AGENT_ROLE=worker
+
+      - MCP_BASE_URL=${MCP_BASE_URL:-http://api:3013}
+
+      # Optional environment variables
+      - SESSION_ID=${SESSION_ID:-}
+      - YOLO=${YOLO:-false}
+      # GitHub credentials for git push and PR operations
+      - GITHUB_TOKEN=${GITHUB_TOKEN:-}
+      - GITHUB_EMAIL=${GITHUB_EMAIL:-}
+      - GITHUB_NAME=${GITHUB_NAME:-}
+      # Service registry URL (for service discovery)
+      - SWARM_URL=${SWARM_URL:-localhost}
+
+    ports:
+      # Expose service port for PM2 processes
+      - "${SERVICE_PORT:-3001}:3000"
+
+    volumes:
+      - swarm_logs:/logs
+      # Optional: mount a workspace directory for persistent work
+      - swarm_shared:/workspace/shared
+      - swarm_worker_1/personal:/workspace/personal
+
+    restart: unless-stopped
+
+  worker-2:
+    build:
+      context: .
+      dockerfile: Dockerfile.worker
+
+    environment:
+      - CLAUDE_CODE_OAUTH_TOKEN=${CLAUDE_CODE_OAUTH_TOKEN}
+      - API_KEY=${API_KEY}
+      - AGENT_ID=${AGENT_ID_2}
+      - AGENT_ROLE=worker
+
+      - MCP_BASE_URL=${MCP_BASE_URL:-http://api:3013}
+
+      # Same as above...
+
+    ports:
+      # Expose service port for PM2 processes
+      - "${SERVICE_PORT:-3002}:3000"
+
+    volumes:
+      - swarm_logs:/logs
+      - swarm_shared:/workspace/shared
+      - swarm_worker_2/personal:/workspace/personal
+
+    restart: unless-stopped
+
+  lead:
+    build:
+      context: .
+      dockerfile: Dockerfile.worker
+
+    environment:
+      - CLAUDE_CODE_OAUTH_TOKEN=${CLAUDE_CODE_OAUTH_TOKEN}
+      - API_KEY=${API_KEY}
+      - AGENT_ID=${AGENT_ID_LEAD}
+
+      # Important: Lead agent role
+      - AGENT_ROLE=lead
+
+      - MCP_BASE_URL=${MCP_BASE_URL:-http://api:3013}
+
+      # Same as above...
+
+    ports:
+      # Expose service port for PM2 processes
+      - "${SERVICE_PORT:-3003}:3000"
+
+    volumes:
+      - swarm_logs:/logs
+      - swarm_shared:/workspace/shared
+      - swarm_personal_lead:/workspace/personal
+
+    restart: unless-stopped
+
+volumes:
+  swarm_api:
+  swarm_logs:
+  swarm_shared:
+  swarm_lead:
+  swarm_worker_1:
+  swarm_worker_2:
+
+networks:
+  default:
+    driver: bridge

package/docker-entrypoint.sh

@@ -12,20 +12,79 @@ if [ -z "$API_KEY" ]; then
     exit 1
 fi
 
+# Role defaults to worker, can be set to "lead"
+ROLE="${AGENT_ROLE:-worker}"
 MCP_URL="${MCP_BASE_URL:-http://host.docker.internal:3013}"
 
-echo "=== Agent Swarm Worker ==="
+# Determine YOLO mode based on role
+if [ "$ROLE" = "lead" ]; then
+    YOLO_MODE="${LEAD_YOLO:-false}"
+else
+    YOLO_MODE="${WORKER_YOLO:-false}"
+fi
+
+echo "=== Agent Swarm ${ROLE^} ==="
 echo "Agent ID: ${AGENT_ID:-<not set>}"
 echo "MCP Base URL: $MCP_URL"
-echo "YOLO Mode: ${WORKER_YOLO:-false}"
+echo "YOLO Mode: $YOLO_MODE"
 echo "Session ID: ${SESSION_ID:-<auto-generated>}"
 echo "Working Directory: /workspace"
 echo "=========================="
 
+# Initialize PM2 daemon for background service management
+echo ""
+echo "=== PM2 Initialization ==="
+echo "PM2 Home: ${PM2_HOME:-~/.pm2}"
+# Ensure PM2 home directory exists (for persistence in /workspace)
+mkdir -p "${PM2_HOME:-$HOME/.pm2}"
+pm2 startup > /dev/null 2>&1 || true
+
+# Restore services from ecosystem (database-driven, more reliable than pm2 resurrect)
+ECOSYSTEM_FILE="/workspace/ecosystem.config.js"
+if [ -n "$AGENT_ID" ]; then
+    echo "Fetching ecosystem config from MCP server..."
+    if curl -s -f -H "Authorization: Bearer ${API_KEY}" \
+       -H "X-Agent-ID: ${AGENT_ID}" \
+       "${MCP_URL}/ecosystem" > /tmp/ecosystem.json 2>/dev/null; then
+
+        # Check if there are any apps to start
+        APP_COUNT=$(cat /tmp/ecosystem.json | jq -r '.apps | length' 2>/dev/null || echo "0")
+
+        if [ "$APP_COUNT" -gt "0" ]; then
+            echo "Found $APP_COUNT registered service(s)"
+            # Convert JSON to JS module
+            echo "module.exports = $(cat /tmp/ecosystem.json);" > "$ECOSYSTEM_FILE"
+            echo "Starting services from ecosystem file..."
+            pm2 start "$ECOSYSTEM_FILE" || true
+            pm2 list
+        else
+            echo "No services registered for this agent"
+        fi
+        rm -f /tmp/ecosystem.json
+    else
+        echo "Could not fetch ecosystem config (MCP server may be unavailable)"
+    fi
+else
+    echo "AGENT_ID not set, skipping ecosystem restore"
+fi
+
+# Fallback: try pm2 resurrect for any locally saved processes
+if pm2 resurrect 2>/dev/null; then
+    pm2 list 2>/dev/null || true
+fi
+echo "=========================="
+
+# Cleanup function for graceful shutdown
+cleanup() {
+    echo ""
+    echo "Shutting down PM2 processes..."
+    pm2 kill 2>/dev/null || true
+}
+trap cleanup EXIT SIGINT SIGTERM
+
 # Create .mcp.json in /workspace (project-level config)
 echo "Creating MCP config in /workspace..."
 if [ -n "$AGENT_ID" ]; then
-    # With AGENT_ID header
     cat > /workspace/.mcp.json << EOF
 {
   "mcpServers": {
@@ -41,7 +100,6 @@ if [ -n "$AGENT_ID" ]; then
 }
 EOF
 else
-    # Without AGENT_ID header
     cat > /workspace/.mcp.json << EOF
 {
   "mcpServers": {
@@ -57,6 +115,164 @@ else
 EOF
 fi
 
-# Run the worker using compiled binary
-echo "Starting worker..."
-exec /usr/local/bin/agent-swarm worker "$@"
+# Configure GitHub authentication if token is provided
+echo ""
+echo "=== GitHub Authentication ==="
+if [ -n "$GITHUB_TOKEN" ]; then
+    echo "Configuring GitHub authentication..."
+
+    # gh CLI will automatically use GITHUB_TOKEN env var for API calls
+    # Just need to configure git to use gh as credential helper
+    gh auth setup-git
+
+    # Set git user config for commits (use env vars or defaults)
+    GIT_EMAIL="${GITHUB_EMAIL:-worker-agent@desplega.ai}"
+    GIT_NAME="${GITHUB_NAME:-Worker Agent}"
+    git config --global user.email "$GIT_EMAIL"
+    git config --global user.name "$GIT_NAME"
+
+    echo "GitHub authentication configured successfully"
+    echo "Git user: $GIT_NAME <$GIT_EMAIL>"
+else
+    echo "WARNING: GITHUB_TOKEN not set - git push operations will fail"
+fi
+echo "=============================="
+
+# Execute startup script if found
+STARTUP_SCRIPT_STRICT="${STARTUP_SCRIPT_STRICT:-true}"
+echo ""
+echo "=== Startup Script Detection (${ROLE}) ==="
+
+# Find startup script matching /workspace/start-up.* pattern
+STARTUP_SCRIPT=""
+for pattern in start-up.sh start-up.bash start-up.js start-up.ts start-up.bun start-up; do
+    if [ -f "/workspace/${pattern}" ]; then
+        STARTUP_SCRIPT="/workspace/${pattern}"
+        break
+    fi
+done
+
+if [ -n "$STARTUP_SCRIPT" ]; then
+    echo "Found startup script: $STARTUP_SCRIPT"
+
+    # Check if file is executable
+    if [ ! -x "$STARTUP_SCRIPT" ]; then
+        echo "Script is not executable, checking for shebang..."
+    fi
+
+    # Read first line to check for shebang
+    FIRST_LINE=$(head -n 1 "$STARTUP_SCRIPT")
+
+    if [[ "$FIRST_LINE" =~ ^#! ]]; then
+        # Has shebang - extract interpreter
+        INTERPRETER="${FIRST_LINE#\#!}"
+        # Trim whitespace
+        INTERPRETER=$(echo "$INTERPRETER" | xargs)
+        echo "Detected shebang interpreter: $INTERPRETER"
+
+        # Check if it's an env-based shebang (#!/usr/bin/env bash)
+        if [[ "$INTERPRETER" =~ ^/usr/bin/env ]]; then
+            ACTUAL_INTERPRETER=$(echo "$INTERPRETER" | awk '{print $2}')
+            echo "Using env interpreter: $ACTUAL_INTERPRETER"
+            INTERPRETER="$ACTUAL_INTERPRETER"
+        fi
+
+        echo "Executing startup script with interpreter: $INTERPRETER"
+        # Always use the interpreter explicitly to avoid permission issues
+        # Use || true to prevent set -e from exiting before we can handle the error
+        $INTERPRETER "$STARTUP_SCRIPT" || EXIT_CODE=$?
+        EXIT_CODE=${EXIT_CODE:-0}
+    else
+        # No shebang, try to infer from extension
+        EXTENSION="${STARTUP_SCRIPT##*.}"
+        echo "No shebang found, inferring from extension: .$EXTENSION"
+
+        case "$EXTENSION" in
+            sh|bash)
+                echo "Executing with bash..."
+                bash "$STARTUP_SCRIPT" || EXIT_CODE=$?
+                ;;
+            js)
+                echo "Executing with node..."
+                node "$STARTUP_SCRIPT" || EXIT_CODE=$?
+                ;;
+            ts)
+                echo "Executing with bun (TypeScript)..."
+                bun run "$STARTUP_SCRIPT" || EXIT_CODE=$?
+                ;;
+            bun)
+                echo "Executing with bun..."
+                bun run "$STARTUP_SCRIPT" || EXIT_CODE=$?
+                ;;
+            *)
+                # Try to execute directly if executable
+                if [ -x "$STARTUP_SCRIPT" ]; then
+                    echo "Executing directly (executable bit set)..."
+                    "$STARTUP_SCRIPT" || EXIT_CODE=$?
+                else
+                    echo "WARNING: Unknown extension and not executable, trying bash..."
+                    bash "$STARTUP_SCRIPT" || EXIT_CODE=$?
+                fi
+                ;;
+        esac
+        EXIT_CODE=${EXIT_CODE:-0}
+    fi
+
+    # Handle exit code
+    if [ $EXIT_CODE -ne 0 ]; then
+        echo ""
+        echo "ERROR: Startup script failed with exit code $EXIT_CODE"
+
+        if [ "$STARTUP_SCRIPT_STRICT" = "true" ]; then
+            echo "STARTUP_SCRIPT_STRICT=true - Exiting..."
+            exit $EXIT_CODE
+        else
+            echo "STARTUP_SCRIPT_STRICT=false - Continuing despite error..."
+        fi
+    else
+        echo "Startup script completed successfully"
+    fi
+else
+    echo "No startup script found (looked for /workspace/start-up.*)"
+    echo "Skipping startup script execution"
+fi
+
+echo ""
+echo "=== Workspace Initialization ==="
+
+PERSONAL_DIR="/workspace/personal"
+mkdir -p "$PERSONAL_DIR"
+
+if [ ! -f "$PERSONAL_DIR/todos.md" ]; then
+    echo "Creating personal todos.md..."
+    cat > "$PERSONAL_DIR/todos.md" << EOF
+# My TODOs
+
+## Current
+- [ ] <task here>
+EOF
+else
+    echo "Personal todo.md already exists, skipping creation"
+fi
+
+SHARED_DIR="/workspace/shared/thoughts"
+
+# Create shared thoughts directories
+if [ -n "$AGENT_ID" ]; then
+    AGENT_THOUGHTS_DIR="$SHARED_DIR/$AGENT_ID"
+    echo "Creating shared thoughts directories for agent ID $AGENT_ID..."
+    mkdir -p "$AGENT_THOUGHTS_DIR/plans"
+    mkdir -p "$AGENT_THOUGHTS_DIR/research"
+fi
+
+# shared always
+echo "Creating shared thoughts directories..."
+mkdir -p "$SHARED_DIR/shared/plans"
+mkdir -p "$SHARED_DIR/shared/research"
+
+echo "==============================="
+echo ""
+
+# Run the agent using compiled binary
+echo "Starting $ROLE..."
+exec /usr/local/bin/agent-swarm "$ROLE" "$@"

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.2.0",
+  "version": "1.9.0",
   "description": "Agent orchestration layer MCP for Claude Code, Codex, Gemini CLI, and more!",
-  "module": "src/stdio.ts",
+  "module": "src/http.ts",
   "type": "module",
   "bin": {
     "agent-swarm": "./src/cli.tsx"
@@ -19,6 +19,8 @@
     "claude:headless": "bun src/cli.tsx claude --headless",
     "worker": "bun src/cli.tsx worker",
     "worker:yolo": "bun src/cli.tsx worker --yolo",
+    "lead": "bun src/cli.tsx lead",
+    "lead:yolo": "bun src/cli.tsx lead --yolo",
     "dev": "bun --hot src/stdio.ts",
     "dev:http": "bun --hot src/http.ts",
     "start": "bun src/stdio.ts",
@@ -30,8 +32,14 @@
     "format": "biome format --write src",
     "build:binary": "bun build ./src/cli.tsx --compile --target=bun-linux-x64 --outfile ./dist/agent-swarm",
     "build:binary:arm64": "bun build ./src/cli.tsx --compile --target=bun-linux-arm64 --outfile ./dist/agent-swarm",
-    "docker:build:worker": "docker build -f Dockerfile.worker -t agent-swarm-worker .",
-    "docker:run:worker": "docker run --rm -it --env-file .env.docker -v ./logs:/logs agent-swarm-worker"
+    "docker:build:worker": "docker build -f Dockerfile.worker -t agent-swarm-worker:latest .",
+    "docker:run:worker": "docker run --rm -it --env-file .env.docker -p 3202:3000 -v ./logs:/logs -v ./work/shared:/workspace/shared -v ./work/worker-1:/workspace/personal agent-swarm-worker:latest",
+    "docker:run:lead": "docker run --rm -it --env-file .env.docker-lead -e AGENT_ROLE=lead -p 3201:3000 -v ./logs:/logs -v ./work/shared:/workspace/shared -v ./work/lead:/workspace/personal agent-swarm-worker:latest",
+    "deploy:install": "bun deploy/install.ts",
+    "deploy:update": "bun deploy/update.ts",
+    "deploy:uninstall": "bun deploy/uninstall.ts",
+    "deploy:docker": "bun deploy/docker-push.ts",
+    "docs:mcp": "bun scripts/generate-mcp-docs.ts"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.9",
@@ -43,6 +51,7 @@
   "dependencies": {
     "@inkjs/ui": "^2.0.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
+    "@slack/bolt": "^4.6.0",
     "@types/react": "^19.2.7",
     "date-fns": "^4.1.0",
     "ink": "^6.5.1",

package/{cc-plugin → plugin}/.claude-plugin/plugin.json

@@ -7,7 +7,7 @@
         "email": "contact@desplega.ai"
     },
     "homepage": "https://desplega.ai",
-    "repository": "https://github.com/desplega-ai/ai-toolbox",
+    "repository": "https://github.com/desplega-ai/agent-swarm",
     "keywords": ["ai", "agent", "toolbox", "plugin", "swarm"],
     "license": "MIT"
 }

package/plugin/README.md

@@ -0,0 +1 @@
+Need to work on this, currently not exposed to the CC marketplace, so no need for a README yet.

package/plugin/agents/codebase-analyzer.md

@@ -0,0 +1,143 @@
+---
+name: codebase-analyzer
+description: Analyzes codebase implementation details. Call the codebase-analyzer agent when you need to find detailed information about specific components. As always, the more detailed your request prompt, the better! :)
+tools: Read, Grep, Glob, LS
+model: inherit
+---
+
+You are a specialist at understanding HOW code works. Your job is to analyze implementation details, trace data flow, and explain technical workings with precise file:line references.
+
+## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY
+- DO NOT suggest improvements or changes unless the user explicitly asks for them
+- DO NOT perform root cause analysis unless the user explicitly asks for them
+- DO NOT propose future enhancements unless the user explicitly asks for them
+- DO NOT critique the implementation or identify "problems"
+- DO NOT comment on code quality, performance issues, or security concerns
+- DO NOT suggest refactoring, optimization, or better approaches
+- ONLY describe what exists, how it works, and how components interact
+
+## Core Responsibilities
+
+1. **Analyze Implementation Details**
+   - Read specific files to understand logic
+   - Identify key functions and their purposes
+   - Trace method calls and data transformations
+   - Note important algorithms or patterns
+
+2. **Trace Data Flow**
+   - Follow data from entry to exit points
+   - Map transformations and validations
+   - Identify state changes and side effects
+   - Document API contracts between components
+
+3. **Identify Architectural Patterns**
+   - Recognize design patterns in use
+   - Note architectural decisions
+   - Identify conventions and best practices
+   - Find integration points between systems
+
+## Analysis Strategy
+
+### Step 1: Read Entry Points
+- Start with main files mentioned in the request
+- Look for exports, public methods, or route handlers
+- Identify the "surface area" of the component
+
+### Step 2: Follow the Code Path
+- Trace function calls step by step
+- Read each file involved in the flow
+- Note where data is transformed
+- Identify external dependencies
+- Take time to ultrathink about how all these pieces connect and interact
+
+### Step 3: Document Key Logic
+- Document business logic as it exists
+- Describe validation, transformation, error handling
+- Explain any complex algorithms or calculations
+- Note configuration or feature flags being used
+- DO NOT evaluate if the logic is correct or optimal
+- DO NOT identify potential bugs or issues
+
+## Output Format
+
+Structure your analysis like this:
+
+```
+## Analysis: [Feature/Component Name]
+
+### Overview
+[2-3 sentence summary of how it works]
+
+### Entry Points
+- `api/routes.js:45` - POST /webhooks endpoint
+- `handlers/webhook.js:12` - handleWebhook() function
+
+### Core Implementation
+
+#### 1. Request Validation (`handlers/webhook.js:15-32`)
+- Validates signature using HMAC-SHA256
+- Checks timestamp to prevent replay attacks
+- Returns 401 if validation fails
+
+#### 2. Data Processing (`services/webhook-processor.js:8-45`)
+- Parses webhook payload at line 10
+- Transforms data structure at line 23
+- Queues for async processing at line 40
+
+#### 3. State Management (`stores/webhook-store.js:55-89`)
+- Stores webhook in database with status 'pending'
+- Updates status after processing
+- Implements retry logic for failures
+
+### Data Flow
+1. Request arrives at `api/routes.js:45`
+2. Routed to `handlers/webhook.js:12`
+3. Validation at `handlers/webhook.js:15-32`
+4. Processing at `services/webhook-processor.js:8`
+5. Storage at `stores/webhook-store.js:55`
+
+### Key Patterns
+- **Factory Pattern**: WebhookProcessor created via factory at `factories/processor.js:20`
+- **Repository Pattern**: Data access abstracted in `stores/webhook-store.js`
+- **Middleware Chain**: Validation middleware at `middleware/auth.js:30`
+
+### Configuration
+- Webhook secret from `config/webhooks.js:5`
+- Retry settings at `config/webhooks.js:12-18`
+- Feature flags checked at `utils/features.js:23`
+
+### Error Handling
+- Validation errors return 401 (`handlers/webhook.js:28`)
+- Processing errors trigger retry (`services/webhook-processor.js:52`)
+- Failed webhooks logged to `logs/webhook-errors.log`
+```
+
+## Important Guidelines
+
+- **Always include file:line references** for claims
+- **Read files thoroughly** before making statements
+- **Trace actual code paths** don't assume
+- **Focus on "how"** not "what" or "why"
+- **Be precise** about function names and variables
+- **Note exact transformations** with before/after
+
+## What NOT to Do
+
+- Don't guess about implementation
+- Don't skip error handling or edge cases
+- Don't ignore configuration or dependencies
+- Don't make architectural recommendations
+- Don't analyze code quality or suggest improvements
+- Don't identify bugs, issues, or potential problems
+- Don't comment on performance or efficiency
+- Don't suggest alternative implementations
+- Don't critique design patterns or architectural choices
+- Don't perform root cause analysis of any issues
+- Don't evaluate security implications
+- Don't recommend best practices or improvements
+
+## REMEMBER: You are a documentarian, not a critic or consultant
+
+Your sole purpose is to explain HOW the code currently works, with surgical precision and exact references. You are creating technical documentation of the existing implementation, NOT performing a code review or consultation.
+
+Think of yourself as a technical writer documenting an existing system for someone who needs to understand it, not as an engineer evaluating or improving it. Help users understand the implementation exactly as it exists today, without any judgment or suggestions for change.