@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/docs-site/content/docs/(documentation)/guides/agentmail-integration.mdx

@@ -0,0 +1,79 @@
+---
+title: AgentMail Integration
+description: Set up AgentMail to give each agent its own email inbox for receiving newsletters, notifications, and external messages
+---
+
+# AgentMail Integration
+
+Give your agents email addresses via [AgentMail](https://agentmail.to). Emails are routed to agents as tasks or inbox messages.
+
+## Setup
+
+1. Create an account at [AgentMail](https://agentmail.to)
+2. Set up a webhook pointing to your server
+
+**Webhook URL:** `https://your-server.com/api/agentmail/webhook`
+
+## Configuration
+
+```bash
+AGENTMAIL_WEBHOOK_SECRET=your-svix-secret
+
+# Optional: filter incoming webhooks by domain
+AGENTMAIL_INBOX_DOMAIN_FILTER=yourdomain.com
+AGENTMAIL_SENDER_DOMAIN_FILTER=gmail.com,company.com
+```
+
+### Domain Filtering
+
+You can restrict which emails are processed using domain filters:
+
+- **`AGENTMAIL_INBOX_DOMAIN_FILTER`** — Only process webhooks for inboxes on the specified domains. Emails to inboxes on other domains are silently dropped.
+- **`AGENTMAIL_SENDER_DOMAIN_FILTER`** — Only process emails from senders on the specified domains. Emails from other sender domains are silently dropped.
+
+Both accept comma-separated domain lists and are optional. When not set, all domains are allowed.
+
+## How It Works
+
+### Email Routing
+
+Agents self-register which inboxes they receive mail from using the `register-agentmail-inbox` MCP tool.
+
+- **Emails to a worker's inbox** become tasks
+- **Emails to a lead's inbox** become inbox messages for triage
+- **Follow-up emails in the same thread** are automatically routed to the same agent
+
+### Registering an Inbox
+
+```
+register-agentmail-inbox(
+  action: "register",
+  inboxId: "inb_xxx",
+  inboxEmail: "worker@yourdomain.com"
+)
+```
+
+### Managing Inboxes
+
+```
+# List your registered inboxes
+register-agentmail-inbox(action: "list")
+
+# Unregister an inbox
+register-agentmail-inbox(action: "unregister", inboxId: "inb_xxx")
+```
+
+### Sending Email
+
+Agents can send emails using AgentMail MCP tools:
+
+- `send_message` — Send a new email
+- `reply_to_message` — Reply to an existing thread
+- `forward_message` — Forward an email
+- `list_threads` — List email threads in an inbox
+
+## Related
+
+- [Environment Variables](/docs/reference/environment-variables) — AgentMail configuration (`AGENTMAIL_WEBHOOK_SECRET`, domain filters)
+- [Task Lifecycle](/docs/concepts/task-lifecycle) — How emails become tasks
+- [Slack Integration](/docs/guides/slack-integration) — Another external task source

package/docs-site/content/docs/(documentation)/guides/deployment.mdx

@@ -0,0 +1,171 @@
+---
+title: Deployment Guide
+description: Deploy Agent Swarm to production with Docker Compose, configure networking, secrets, and persistent storage
+---
+
+# Deployment Guide
+
+Agent Swarm supports multiple deployment options, from Docker Compose to systemd services.
+
+## Docker Compose (Recommended)
+
+The easiest way to deploy a full swarm with API, workers, and lead agent.
+
+### Quick Start
+
+```bash
+cp docker-compose.example.yml docker-compose.yml
+cp .env.docker.example .env
+# Edit .env with your values
+docker-compose up -d
+```
+
+### ARM Compatibility (Apple Silicon)
+
+All services in the docker-compose files include `platform: linux/amd64` to avoid `no matching manifest for linux/arm64/v8` errors on Apple Silicon Macs. The Docker images are built for `linux/amd64` and run via Rosetta emulation.
+
+### What's Included
+
+The example `docker-compose.yml` sets up:
+
+- **API service** (port 3013) — MCP HTTP server
+- **2 Worker agents** — Containerized Claude workers
+- **1 Lead agent** — Coordinator agent
+
+### Volumes
+
+| Volume | Purpose |
+|--------|---------|
+| `swarm_api` | SQLite database persistence |
+| `swarm_logs` | Session logs |
+| `swarm_shared` | Shared workspace between agents |
+| `swarm_lead` | Lead agent's personal workspace |
+| `swarm_worker_*` | Personal workspace per worker |
+
+### Graceful Shutdown
+
+The docker-compose example uses `stop_grace_period: 60s` to allow graceful task pause during deployments. When a container receives SIGTERM:
+
+1. In-progress tasks are **paused** (not failed)
+2. Task state and progress are preserved
+3. After restart, paused tasks are automatically **resumed** with context
+
+Use stable `AGENT_ID` values for each worker to enable task resume after restarts.
+
+### Pre-installed Agent Tools
+
+Worker containers include several tools pre-installed:
+
+- **`wts`** — Git worktree manager for isolated branch work
+- **`agent-fs`** — Persistent, searchable filesystem shared across the swarm (auto-configured on first boot when `AGENT_FS_API_URL` is set). Also available as a Claude plugin.
+- **`qa-use`** — Browser-based UI testing tool
+- **`context-mode`** — Context window compression for data-heavy operations
+
+### Claude Code Version
+
+Claude Code is installed via `npm install -g @anthropic-ai/claude-code@VERSION` with a pinned version (build arg `CLAUDE_CODE_VERSION`). To update the version, change the `CLAUDE_CODE_VERSION` ARG in `Dockerfile.worker` and rebuild.
+
+### Corepack
+
+The worker image sets `COREPACK_HOME=/home/worker/.corepack` to avoid permission errors when running npm/pnpm/yarn as the non-root worker user.
+
+## Docker Worker
+
+### Pull from Registry
+
+```bash
+docker pull ghcr.io/desplega-ai/agent-swarm-worker:latest
+```
+
+### Run
+
+```bash
+docker run --rm -it \
+  -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
+  -e API_KEY=your-api-key \
+  -v ./logs:/logs \
+  -v ./work:/workspace \
+  ghcr.io/desplega-ai/agent-swarm-worker
+```
+
+### With Custom System Prompt
+
+```bash
+docker run --rm -it \
+  -e CLAUDE_CODE_OAUTH_TOKEN=your-token \
+  -e API_KEY=your-api-key \
+  -e SYSTEM_PROMPT="You are a Python specialist" \
+  -v ./logs:/logs \
+  -v ./work:/workspace \
+  ghcr.io/desplega-ai/agent-swarm-worker
+```
+
+## Server Deployment (systemd)
+
+Deploy the MCP server to a Linux host with systemd.
+
+### Prerequisites
+
+- Linux with systemd
+- Bun installed (`curl -fsSL https://bun.sh/install | bash`)
+
+### Install
+
+```bash
+git clone https://github.com/desplega-ai/agent-swarm.git
+cd agent-swarm
+sudo bun deploy/install.ts
+```
+
+This will:
+- Copy files to `/opt/agent-swarm`
+- Create `.env` file (edit to set `API_KEY`)
+- Install systemd service with health checks every 30s
+- Start the service on port 3013
+
+### Management
+
+```bash
+sudo systemctl status agent-swarm    # Check status
+sudo journalctl -u agent-swarm -f    # View logs
+sudo systemctl restart agent-swarm   # Restart
+sudo systemctl stop agent-swarm      # Stop
+```
+
+### Update
+
+```bash
+git pull
+sudo bun deploy/update.ts
+```
+
+## Graceful Shutdown Configuration
+
+```bash
+# Grace period before force-pausing tasks (milliseconds)
+SHUTDOWN_TIMEOUT=30000
+
+# Docker compose stop grace period (should be >= SHUTDOWN_TIMEOUT + buffer)
+stop_grace_period: 60s
+```
+
+### Resume Behavior
+
+When a worker starts, it:
+1. Registers with the MCP server
+2. Checks for paused tasks assigned to its `AGENT_ID`
+3. Resumes each paused task with original context and progress
+
+### Best Practices
+
+- **Use stable Agent IDs** — Set explicit `AGENT_ID` for each worker
+- **Save progress regularly** — Workers should call `store-progress` during long tasks
+- **Test deployments** — Verify tasks resume correctly in staging first
+
+## Related
+
+- [Getting Started](/docs/getting-started) — Initial setup and first deployment
+- [Environment Variables](/docs/reference/environment-variables) — All configuration options
+- [Architecture Overview](/docs/architecture/overview) — How the system components fit together
+- [Task Lifecycle](/docs/concepts/task-lifecycle) — Graceful shutdown and task resume behavior
+- [x402 Payments](/docs/guides/x402-payments) — Enable agents to make USDC micropayments

package/docs-site/content/docs/(documentation)/guides/github-integration.mdx

@@ -0,0 +1,81 @@
+---
+title: GitHub App Integration
+description: Set up GitHub webhooks for automated task creation from PR reviews, issues, and @mentions
+---
+
+# GitHub App Integration
+
+Enable GitHub webhooks for automated task creation from PR reviews, issue assignments, and @mentions.
+
+## Setup
+
+1. Create a [GitHub App](https://github.com/settings/apps/new)
+2. Set webhook URL: `https://your-server.com/api/github/webhook`
+3. Generate a webhook secret
+
+### Required Permissions
+
+- **Issues**: Read & Write
+- **Pull requests**: Read & Write
+
+### Subscribe to Events
+
+- Issues
+- Issue comments
+- Pull requests
+- Pull request reviews
+- Pull request review comments
+- Check runs
+- Check suites
+- Workflow runs
+
+## Configuration
+
+```bash
+# Required for GitHub webhooks
+GITHUB_WEBHOOK_SECRET=your-webhook-secret
+
+# Optional: Bot name for @mentions (default: agent-swarm-bot)
+GITHUB_BOT_NAME=your-bot-name
+
+# Optional: Enable bot reactions (requires GitHub App)
+GITHUB_APP_ID=123456
+GITHUB_APP_PRIVATE_KEY=base64-encoded-key
+
+# Optional: Disable GitHub integration
+GITHUB_DISABLE=true
+```
+
+## Supported Events
+
+| Event | What happens |
+|-------|-------------|
+| Bot assigned to PR/issue | Creates a task for the lead agent |
+| Review requested from bot | Creates a review task |
+| `@bot-name` in comment/issue/PR | Creates a task with the mention context |
+| PR review submitted (on bot's PR) | Creates a notification task with review feedback |
+| CI failure (on PRs with existing tasks) | Creates a CI notification task |
+
+## Bot Reactions
+
+If GitHub App credentials are provided (`GITHUB_APP_ID` and `GITHUB_APP_PRIVATE_KEY`), the bot can react to comments and issues with emoji to acknowledge receipt.
+
+## Worker Git Configuration
+
+Workers need git credentials to create PRs and push code:
+
+```bash
+GITHUB_TOKEN=your-github-token    # For git operations
+GITHUB_EMAIL=worker@desplega.ai   # Git commit email
+GITHUB_NAME=Worker Agent           # Git commit name
+```
+
+## Related
+
+- [GitLab Integration](/docs/guides/gitlab-integration) — GitLab webhook support (same adapter pattern)
+- [Linear Integration](/docs/guides/linear-integration) — Bidirectional ticket tracking with Linear
+- [Environment Variables](/docs/reference/environment-variables) — GitHub configuration variables
+- [Task Lifecycle](/docs/concepts/task-lifecycle) — How GitHub events become tasks
+- [Slack Integration](/docs/guides/slack-integration) — Another external task source
+- [Sentry Integration](/docs/guides/sentry-integration) — Automated error triage from Sentry
+- [AgentMail Integration](/docs/guides/agentmail-integration) — Give agents email addresses

package/docs-site/content/docs/(documentation)/guides/gitlab-integration.mdx

@@ -0,0 +1,93 @@
+---
+title: GitLab Integration
+description: Set up GitLab webhooks for automated task creation from merge requests, issues, and comments
+---
+
+# GitLab Integration
+
+Agent Swarm supports GitLab alongside GitHub through a provider adapter pattern. GitLab webhooks create tasks from MR reviews, issue assignments, and @mentions — just like the GitHub integration.
+
+## Setup
+
+1. Go to your GitLab project or group **Settings > Webhooks**
+2. Set the webhook URL: `https://your-server.com/api/gitlab/webhook`
+3. Set a secret token for verification
+4. Select the events you want to receive
+
+### Events to Enable
+
+- **Merge request events**
+- **Issue events**
+- **Note (comment) events**
+- **Pipeline events**
+
+## Configuration
+
+```bash
+# Required for GitLab webhooks
+GITLAB_WEBHOOK_SECRET=your-webhook-secret
+
+# GitLab API access (PAT or Group Access Token)
+GITLAB_TOKEN=your-gitlab-token
+
+# Optional: GitLab instance URL (default: https://gitlab.com)
+GITLAB_URL=https://gitlab.com
+
+# Optional: Bot name for @mentions (default: agent-swarm-bot)
+GITLAB_BOT_NAME=your-bot-name
+
+# Optional: Disable GitLab integration
+GITLAB_DISABLE=true
+```
+
+## Supported Events
+
+| Event | What happens |
+|-------|-------------|
+| Bot assigned to MR/issue | Creates a task for the lead agent |
+| `@bot-name` in comment/issue/MR | Creates a task with the mention context |
+| Pipeline failure (on MRs with existing tasks) | Creates a CI notification task |
+
+## Worker Git Configuration
+
+Workers have `glab` CLI pre-installed for GitLab operations. Configure git credentials for GitLab repos:
+
+```bash
+GITLAB_TOKEN=your-gitlab-token    # For git operations and glab CLI
+GITLAB_EMAIL=worker@example.com   # Git commit email for GitLab repos
+GITLAB_NAME=Worker Agent          # Git commit name for GitLab repos
+```
+
+The runner automatically detects whether a task targets a GitHub or GitLab repository and uses the appropriate CLI tool (`gh` or `glab`).
+
+## VCS Provider Detection
+
+Agent Swarm uses a provider adapter pattern to support both GitHub and GitLab. When a task is created from a webhook event, the `vcsProvider` field is set automatically. Workers use this to select the right CLI:
+
+| Operation | GitHub (`gh`) | GitLab (`glab`) |
+|---|---|---|
+| Create PR/MR | `gh pr create` | `glab mr create` |
+| View PR/MR | `gh pr view` | `glab mr view` |
+| Review | `gh pr review` | `glab mr approve` / `glab mr note` |
+| Comment on issue | `gh issue comment` | `glab issue note` |
+| Clone | `gh repo clone` | `glab repo clone` |
+
+## Workflow Triggers
+
+GitLab events can trigger [workflows](/docs/concepts/workflows):
+
+- `gitlab.merge_request.opened`
+- `gitlab.merge_request.merged`
+- `gitlab.merge_request.closed`
+- `gitlab.issue.opened`
+- `gitlab.issue.closed`
+- `gitlab.note.created`
+- `gitlab.pipeline.failed`
+- `gitlab.pipeline.success`
+
+## Related
+
+- [GitHub Integration](/docs/guides/github-integration) — GitHub webhook setup
+- [Environment Variables](/docs/reference/environment-variables) — GitLab configuration variables
+- [Workflows](/docs/concepts/workflows) — Automate actions on GitLab events
+- [Task Lifecycle](/docs/concepts/task-lifecycle) — How webhook events become tasks

package/docs-site/content/docs/(documentation)/guides/linear-integration.mdx

@@ -0,0 +1,98 @@
+---
+title: Linear Integration
+description: Connect Agent Swarm to Linear for bidirectional ticket tracking with AgentSession support
+---
+
+# Linear Integration
+
+Agent Swarm integrates with [Linear](https://linear.app) as the first provider in its generic ticket tracker framework. The integration enables bidirectional sync between Linear issues/sessions and swarm tasks.
+
+## Features
+
+- **OAuth-based authentication** — PKCE flow via the generic `oauth4webapi` module
+- **AgentSession support** — Agents appear as participants in Linear's agent panel, with thought/action/response/error activity posts
+- **Bidirectional sync** — Task completion/failure syncs back to Linear; Linear follow-up messages create new swarm tasks
+- **Webhook handling** — HMAC-SHA256 verified webhooks with Linear-Delivery header dedup (5-min TTL)
+- **Dashboard linking** — `externalUrls` on sessions link back to the swarm dashboard
+
+## Setup
+
+### 1. Create a Linear OAuth App
+
+1. Go to Linear > Settings > API > Applications
+2. Create a new application with:
+   - **Actor**: Application
+   - **Callback URL**: `http://localhost:3013/api/trackers/linear/callback` (or your production URL)
+   - **Webhook URL**: `http://localhost:3013/api/trackers/linear/webhook`
+3. Enable "Agent session events" in webhook settings
+4. Copy the Client ID, Client Secret, and Webhook Signing Secret
+
+### 2. Configure Environment
+
+Add to your `.env`:
+
+```bash
+LINEAR_CLIENT_ID=your-client-id
+LINEAR_CLIENT_SECRET=your-client-secret
+LINEAR_REDIRECT_URI=http://localhost:3013/api/trackers/linear/callback
+LINEAR_SIGNING_SECRET=your-webhook-signing-secret
+```
+
+With portless:
+```bash
+LINEAR_REDIRECT_URI=https://api.swarm.localhost:1355/api/trackers/linear/callback
+```
+
+### 3. Complete OAuth
+
+Start the server and visit `/api/trackers/linear/authorize` in your browser to complete the OAuth flow.
+
+## How It Works
+
+### Inbound (Linear to Swarm)
+
+1. A user creates an AgentSession in Linear (assigns work to the agent)
+2. Linear sends a webhook to `/api/trackers/linear/webhook`
+3. The webhook handler creates a swarm task linked to the Linear session
+4. The agent acknowledges the session and begins work
+
+### Outbound (Swarm to Linear)
+
+1. Agent posts activities (thoughts, actions, responses, errors) to the Linear session
+2. On task completion, the response activity is posted and the session is auto-completed
+3. On task failure, an error activity is posted
+4. `externalUrls` are set on the session, linking to the swarm dashboard
+
+### Follow-up Messages
+
+When a user sends a follow-up message in a Linear agent chat:
+1. Linear fires a `prompted` event webhook
+2. The handler creates a new swarm task with the follow-up context
+3. The agent processes the follow-up and responds via session activities
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `tracker-status` | Check tracker connection status |
+| `tracker-link-task` | Link a swarm task to a Linear issue |
+| `tracker-link-epic` | Link a swarm epic to a Linear project |
+| `tracker-unlink` | Remove a tracker link |
+| `tracker-sync-status` | View sync status for linked items |
+| `tracker-map-agent` | Map a swarm agent to a Linear user for assignment routing |
+
+## Architecture
+
+The integration is built on a generic tracker abstraction:
+
+- **`src/oauth/`** — Reusable OAuth module with `oauth_apps`/`oauth_tokens` tables and PKCE support
+- **`src/be/db-queries/tracker.ts`** — Generic `tracker_sync` and `tracker_agent_mapping` tables
+- **Linear provider** — Implements the tracker interface with Linear-specific webhook handling and AgentSession lifecycle
+
+This design makes it straightforward to add other ticket trackers (Jira, GitHub Issues, etc.) in the future.
+
+## Related
+
+- [Environment Variables](/docs/reference/environment-variables#linear-integration) — Linear configuration reference
+- [Task Lifecycle](/docs/concepts/task-lifecycle) — How tasks created from Linear flow through the swarm
+- [Architecture Overview](/docs/architecture/overview) — System architecture including integrations

package/docs-site/content/docs/(documentation)/guides/meta.json

@@ -0,0 +1,13 @@
+{
+  "title": "Guides",
+  "pages": [
+    "deployment",
+    "slack-integration",
+    "github-integration",
+    "gitlab-integration",
+    "agentmail-integration",
+    "sentry-integration",
+    "linear-integration",
+    "x402-payments"
+  ]
+}

package/docs-site/content/docs/(documentation)/guides/sentry-integration.mdx

@@ -0,0 +1,52 @@
+---
+title: Sentry Integration
+description: Enable agents to investigate and triage Sentry issues
+---
+
+# Sentry Integration
+
+Docker workers include `sentry-cli` pre-installed, enabling agents to investigate and triage Sentry issues directly.
+
+## Setup
+
+1. Create an Organization Auth Token at `https://sentry.io/settings/{org}/auth-tokens/` with scopes:
+   - `event:read` — Read issues and events
+   - `project:read` — Read project data
+   - `org:read` — Read organization info
+
+2. Add to your worker environment:
+
+```bash
+SENTRY_AUTH_TOKEN=your-auth-token
+SENTRY_ORG=your-org-slug
+```
+
+3. Verify authentication in a worker:
+
+```bash
+sentry-cli info
+```
+
+## Usage
+
+Workers can use the `/investigate-sentry-issue` command to:
+- Get issue details and stacktraces
+- Analyze breadcrumbs and context
+- Resolve, mute, or unresolve issues
+
+### Examples
+
+```
+/investigate-sentry-issue https://sentry.io/organizations/myorg/issues/123456/
+```
+
+Or just the issue ID:
+
+```
+/investigate-sentry-issue 123456
+```
+
+## Related
+
+- [Environment Variables](/docs/reference/environment-variables) — Sentry configuration (`SENTRY_AUTH_TOKEN`, `SENTRY_ORG`)
+- [Task Lifecycle](/docs/concepts/task-lifecycle) — How Sentry issues become tasks