@desplega.ai/agent-swarm 1.49.0 → 1.52.0

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

@@ -1,79 +0,0 @@
----
-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

@@ -1,171 +0,0 @@
----
-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

@@ -1,81 +0,0 @@
----
-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

@@ -1,93 +0,0 @@
----
-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

@@ -1,98 +0,0 @@
----
-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

@@ -1,13 +0,0 @@
-{
-  "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

@@ -1,52 +0,0 @@
----
-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