@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/.claude/settings.json

@@ -0,0 +1,84 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code post-task"
+          }
+        ]
+      },
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code post-todo"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code pre-task"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code session-end"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code session-start"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code stop"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "entire hooks claude-code user-prompt-submit"
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "deny": [
+      "Read(./.entire/metadata/**)"
+    ]
+  }
+}

package/.claude/settings.local.json

@@ -111,5 +111,7 @@
         ]
       }
     ]
-  }
+  },
+  "spinnerTipsEnabled": false,
+  "prefersReducedMotion": true
 }

package/.entire/settings.json

@@ -0,0 +1,4 @@
+{
+  "enabled": true,
+  "telemetry": false
+}

package/.env.docker.example

@@ -1,38 +1,55 @@
-# Docker Worker Environment Variables
+# Docker Worker / Lead Agent Environment Variables
 # Copy this file to .env.docker and fill in your values
+# Full reference: docs/ENVS.md
 
-# Required
+# ---- Required ----
 # Run `claude setup-token` to get your OAuth token
 CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
 API_KEY=your-api-key-here
 
-# Optional (auto-generated if not provided)
+# ---- Agent Identity ----
+# Keep AGENT_ID stable across restarts for task resume and identity persistence
 AGENT_ID=
-MCP_BASE_URL=http://host.docker.internal:3013
-
-# Service Registry (PM2 background services)
-# Port mapping for exposed services (default: 3000)
-SERVICE_PORT=3000
-
-# To re-use an existing session, set SESSION_ID to the desired value
-# Will be used for log directory paths
-SESSION_ID=
-
-# If true, enables YOLO mode for the agent (default: false)
-# which will keep spawning claudes even if an iteration fails
-YOLO=false
+AGENT_NAME=
+AGENT_ROLE=worker                       # "worker" or "lead"
 
-# If true, the worker will exit if the startup script fails (default: true)
-STARTUP_SCRIPT_STRICT=true
-
-# System Prompt (optional - customize agent behavior)
+# ---- Networking ----
+MCP_BASE_URL=http://host.docker.internal:3013
+SWARM_URL=swarm.example.com             # Base domain for service discovery
+# Host ports for exposed services (used in docker-compose.example.yml).
+# These names and defaults are examples — adjust to fit your setup.
+# In isolated environments (each container in its own network namespace),
+# you can map all services to the same port (e.g. 3000:3000).
+# LEAD_PORT=3020
+# WORKER1_PORT=3021
+# WORKER2_PORT=3022
+
+# ---- Behavior ----
+YOLO=false                               # Keep spawning sessions even if one fails
+# MAX_CONCURRENT_TASKS=1                 # Parallel tasks (default: 1 for worker, 2 for lead)
+# SHUTDOWN_TIMEOUT=30000                 # Grace period (ms) before pausing tasks on shutdown
+
+# ---- Logging ----
+# SESSION_ID=                            # Reuse to continue logging to the same folder
+# LOG_DIR=/logs                          # Base directory for session logs
+
+# ---- System Prompt (optional) ----
 SYSTEM_PROMPT=
 SYSTEM_PROMPT_FILE=
 
-# For the agent exposed services (optional)
-SWARM_URL=swarm.example.com
+# ---- Templates (optional) ----
+# TEMPLATE_ID=official/coder             # Template for initial profile (fetched on first boot)
+# TEMPLATE_REGISTRY_URL=https://templates.agent-swarm.dev
+
+# ---- Startup ----
+STARTUP_SCRIPT_STRICT=true               # Exit if startup script fails
+
+# ---- GitHub (for git operations) ----
+GITHUB_TOKEN=                            # Personal access token for gh CLI and git push
+GITHUB_EMAIL=worker-agent@desplega.ai    # Git commit email
+GITHUB_NAME=Worker Agent                 # Git commit name
 
-# Sentry Integration (optional - for issue investigation)
+# ---- Sentry (optional) ----
 # Create an Organization Auth Token at https://sentry.io/settings/{org}/auth-tokens/
 # Required scopes: event:read, project:read, org:read
 SENTRY_AUTH_TOKEN=

package/.env.example

@@ -1,9 +1,19 @@
 # Define your API key or leave empty for no auth
 API_KEY=
 
-# Server port (default: 3013)
+# Server port (default: 3013, worktrees get a random port in 3100-3999)
 PORT=3013
 
+# ── Portless (local dev with friendly URLs) ─────────────────────────────
+# Replaces port-based URLs with domain names. See CONTRIBUTING.md.
+# Install: bun add -g portless
+# HTTPS:   portless trust && portless proxy start --https
+#
+# When using portless, set these in your .env:
+# MCP_BASE_URL=https://api.swarm.localhost:1355
+# APP_URL=https://ui.swarm.localhost:1355
+# ────────────────────────────────────────────────────────────────────────
+
 # Swarm URL for service discovery (e.g., swarm.example.com)
 # Services are accessible at https://{AGENT_ID}.{SWARM_URL}
 SWARM_URL=localhost
@@ -19,6 +29,10 @@ SLACK_APP_TOKEN=xapp-...      # App-Level Token (for Socket Mode)
 SLACK_SIGNING_SECRET=...      # Signing Secret (optional for Socket Mode)
 SLACK_DISABLE=true            # Set to "true" to disable Slack integration
 
+# Additive Slack — buffer non-mention thread replies and batch into follow-up tasks
+# ADDITIVE_SLACK=true                     # Enable thread message buffering (default: false)
+# ADDITIVE_SLACK_BUFFER_MS=10000          # Debounce window in ms (default: 10000)
+
 # Slack User Filtering (optional - leave empty to allow all users)
 # SLACK_ALLOWED_EMAIL_DOMAINS=desplega.ai,partner.com  # Comma-separated email domains
 # SLACK_ALLOWED_USER_IDS=U12345678,U87654321           # Comma-separated Slack user IDs to always allow
@@ -38,3 +52,27 @@ GITHUB_APP_PRIVATE_KEY=           # Private key: raw PEM with \n escapes, OR bas
 
 # Scheduler configuration
 SCHEDULER_INTERVAL_MS=10000       # Polling interval for scheduled tasks (default: 10 seconds)
+
+# AgentMail Integration (optional)
+# AGENTMAIL_DISABLE=true                # Set to skip AgentMail integration
+AGENTMAIL_WEBHOOK_SECRET=               # Svix signing secret for webhook verification
+
+# ── Linear Integration ──
+# Create an OAuth app at: https://linear.app/settings/api/applications
+# 1. Set Actor to "Application"
+# 2. Set Callback URL to your /api/trackers/linear/callback endpoint
+# 3. Enable "Agent session events" in webhook settings
+# 4. Set Webhook URL to your /api/trackers/linear/webhook endpoint
+# 5. Copy Client ID, Client Secret, and Webhook Signing Secret below
+# 6. Start server, then visit /api/trackers/linear/authorize to complete OAuth
+#
+# LINEAR_DISABLE=true                    # Set to disable Linear integration
+# LINEAR_CLIENT_ID=                      # OAuth app client ID
+# LINEAR_CLIENT_SECRET=                  # OAuth app client secret (shown once on creation)
+# LINEAR_REDIRECT_URI=http://localhost:3013/api/trackers/linear/callback
+# With portless: LINEAR_REDIRECT_URI=https://api.swarm.localhost:1355/api/trackers/linear/callback
+# LINEAR_SIGNING_SECRET=                 # Webhook signing secret (from app settings)
+
+# Memory system - OpenAI embeddings (API server only, NOT needed in workers)
+# Optional: system works without it but memory search degrades to recency-based
+OPENAI_API_KEY=

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,78 @@
+name: Bug Report
+description: Report a bug or unexpected behavior
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill out the sections below.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: A clear description of the bug.
+      placeholder: "When I do X, Y happens instead of Z."
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: How can we reproduce this?
+      placeholder: |
+        1. Start the API server with `bun run start:http`
+        2. Send a task via ...
+        3. See error in ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen?
+    validations:
+      required: true
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of Agent Swarm is affected?
+      options:
+        - API Server
+        - Worker / Runner
+        - Lead Agent
+        - Dashboard UI
+        - CLI (`bunx @desplega.ai/agent-swarm`)
+        - Slack Integration
+        - GitHub Integration
+        - AgentMail Integration
+        - Memory System
+        - Docker / Deployment
+        - Other
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Any relevant environment details.
+      placeholder: |
+        - OS: Ubuntu 22.04
+        - Bun version: 1.x
+        - Deployment: Docker Compose / Local
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Logs / Screenshots
+      description: Paste any relevant log output or screenshots.
+      render: shell
+    validations:
+      required: false

package/.github/ISSUE_TEMPLATE/community-template.yml

@@ -0,0 +1,77 @@
+name: Community Template Submission
+description: Submit a new worker template for the Agent Swarm Templates Registry
+title: "[Template] "
+labels: ["template", "community"]
+body:
+  - type: input
+    id: template-name
+    attributes:
+      label: Template Name
+      description: A short, lowercase name for your template (e.g., "devops", "writer")
+      placeholder: my-template
+    validations:
+      required: true
+
+  - type: input
+    id: display-name
+    attributes:
+      label: Display Name
+      description: Human-readable name shown in the gallery
+      placeholder: DevOps Engineer
+    validations:
+      required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What does this template do? What kind of agent does it configure?
+      placeholder: A DevOps-focused agent that manages CI/CD pipelines, infrastructure, and deployments
+    validations:
+      required: true
+
+  - type: dropdown
+    id: category
+    attributes:
+      label: Agent Type
+      options:
+        - Worker
+        - Lead
+    validations:
+      required: true
+
+  - type: input
+    id: role
+    attributes:
+      label: Role
+      description: The agent role (e.g., "worker", "lead")
+      placeholder: worker
+    validations:
+      required: true
+
+  - type: textarea
+    id: capabilities
+    attributes:
+      label: Capabilities
+      description: List the agent's capabilities (one per line)
+      placeholder: |
+        devops
+        ci-cd
+        infrastructure
+        monitoring
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Why is this template useful?
+      description: Describe the use case and how this template helps users
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional-context
+    attributes:
+      label: Additional Context
+      description: Any additional information, links, or examples

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Questions & Discussion
+    url: https://discord.gg/KZgfyyDVZa
+    about: Ask questions and discuss ideas on Discord
+  - name: Documentation
+    url: https://docs.agent-swarm.dev
+    about: Check the docs for setup guides and reference

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,60 @@
+name: Feature Request
+description: Suggest a new feature or improvement
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Have an idea to make Agent Swarm better? We'd love to hear it!
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or motivation
+      description: What problem does this solve, or what would it enable?
+      placeholder: "I'm always frustrated when..."
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: How do you think this should work?
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Any other approaches you've thought about?
+    validations:
+      required: false
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Component
+      description: Which part of Agent Swarm would this affect?
+      options:
+        - API Server
+        - Worker / Runner
+        - Lead Agent
+        - Dashboard UI
+        - CLI
+        - Integrations (Slack, GitHub, Email)
+        - Memory System
+        - Docker / Deployment
+        - Documentation
+        - Other
+    validations:
+      required: false
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context
+      description: Any other context, mockups, or references.
+    validations:
+      required: false

package/.github/PULL_REQUEST_TEMPLATE/community-template.md

@@ -0,0 +1,29 @@
+## Community Template Submission
+
+### Template Info
+
+- **Name**: <!-- e.g., devops -->
+- **Display Name**: <!-- e.g., DevOps Engineer -->
+- **Category**: community
+- **Role**: <!-- worker or lead -->
+
+### Checklist
+
+- [ ] `config.json` is present and valid JSON
+- [ ] All 5 profile files are present (CLAUDE.md, SOUL.md, IDENTITY.md, TOOLS.md, start-up.sh)
+- [ ] Template uses `{{agent.name}}` and `{{agent.role}}` placeholders where appropriate
+- [ ] `start-up.sh` is executable and starts with `#!/bin/bash`
+- [ ] Tested locally with `TEMPLATE_ID=community/<name>`
+- [ ] Template follows the structure of existing official templates
+
+### Description
+
+<!-- Describe what this template does and why it's useful -->
+
+### Testing
+
+<!-- How did you test this template? -->
+
+---
+
+Questions? Contact us at contact@agent-swarm.dev

package/.github/workflows/ci.yml

@@ -1,12 +1,12 @@
 name: CI
 
 on:
-  pull_request:
-    branches:
-      - main
   push:
     branches:
       - main
+    paths-ignore:
+      - "docs-site/**"
+      - "landing/**"
   workflow_dispatch:
 
 jobs:
@@ -50,27 +50,3 @@ jobs:
 
       - name: Run tests
         run: bun test
-
-  docker-build:
-    name: Docker Build Test
-    runs-on: ubuntu-latest
-    if: github.event_name == 'pull_request'
-
-    strategy:
-      matrix:
-        dockerfile: [Dockerfile, Dockerfile.worker]
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Build Docker image
-        uses: docker/build-push-action@v5
-        with:
-          context: .
-          file: ./${{ matrix.dockerfile }}
-          push: false
-          tags: test-image:latest

package/.github/workflows/docker-and-deploy.yml

@@ -4,15 +4,22 @@ on:
   push:
     branches:
       - main
+    paths-ignore:
+      - "docs-site/**"
+      - "landing/**"
   workflow_dispatch:
 
+concurrency:
+  group: docker-and-deploy
+  cancel-in-progress: true
+
 env:
   REGISTRY: ghcr.io
   IMAGE_NAME: ${{ github.repository }}
 
 jobs:
   build-and-push-server:
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
     permissions:
       contents: read
       packages: write
@@ -42,6 +49,11 @@ jobs:
             type=raw,value=${{ steps.version.outputs.version }}
             type=sha
 
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver: docker
+
       - name: Build and push Docker image
         uses: docker/build-push-action@v5
         with:
@@ -50,10 +62,9 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          no-cache: true
 
   build-and-push-worker:
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
     permissions:
       contents: read
       packages: write
@@ -83,6 +94,11 @@ jobs:
             type=raw,value=${{ steps.version.outputs.version }}
             type=sha
 
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+        with:
+          driver: docker
+
       - name: Build and push Docker image
         uses: docker/build-push-action@v5
         with:
@@ -91,11 +107,10 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
-          no-cache: true
 
   deploy:
     name: Deploy
-    runs-on: ubuntu-latest
+    runs-on: self-hosted
 
     needs:
       - build-and-push-server