@desplega.ai/agent-swarm 1.20.0 → 1.49.0

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

@@ -0,0 +1,179 @@
+---
+title: Slack Integration
+description: Set up Slack to create tasks and communicate with agents
+---
+
+# Slack Integration
+
+Enable Slack for task creation, agent communication, and interactive workflows via direct messages and the Slack Assistant sidebar.
+
+## Setup
+
+1. Create a [Slack App](https://api.slack.com/apps)
+2. Enable **Socket Mode** (for real-time events without public webhooks)
+3. Enable **Interactivity** (for action buttons and modals)
+4. Enable **Assistant View** (for sidebar conversations)
+5. Add required bot token scopes:
+   - `app_mentions:read`
+   - `assistant:write`
+   - `channels:history`, `channels:read`
+   - `chat:write`, `chat:write.customize`, `chat:write.public`
+   - `commands`
+   - `files:read`, `files:write`
+   - `groups:history`, `groups:read`
+   - `im:history`, `im:read`, `im:write`
+   - `mpim:history`, `mpim:read`, `mpim:write`
+   - `reactions:write`
+   - `users:read`
+6. Subscribe to bot events: `app_mention`, `assistant_thread_started`, `assistant_thread_context_changed`, `message.channels`, `message.groups`, `message.im`, `message.mpim`
+7. Install to your workspace and copy tokens
+
+A ready-to-use `slack-manifest.json` is included in the repository root — import it directly in the Slack App configuration page to set up all scopes, events, and features automatically.
+
+## Configuration
+
+```bash
+# Required for Slack
+SLACK_BOT_TOKEN=xoxb-...      # Bot User OAuth Token
+SLACK_APP_TOKEN=xapp-...      # App-Level Token (Socket Mode)
+SLACK_SIGNING_SECRET=...      # Signing Secret (optional for Socket Mode)
+
+# Disable Slack (if not using)
+SLACK_DISABLE=true
+```
+
+## How It Works
+
+### Creating Tasks
+
+@mention the bot in Slack to create tasks. All Slack messages are routed directly as tasks — there is no separate inbox system.
+
+**Routing priority:**
+
+1. `swarm#<uuid>` — explicit agent targeting (always wins)
+2. `swarm#all` — broadcast to all workers
+3. **Thread follow-up** — if in a thread where a worker is already active, routes directly to that worker
+4. **Lead fallback** — if the bot was @mentioned and no other match, routes to the lead agent
+
+If no agents are online, the message is queued as an unassigned task in the pool. The bot confirms that your request has been queued and will be processed when agents come back up.
+
+### Thread Follow-up Routing
+
+When you @mention the bot in a thread where a worker is already handling a task, the message routes directly to that worker — no lead delegation needed. This keeps conversations flowing naturally.
+
+If the assigned worker is offline or unavailable, the follow-up routes to the lead agent instead of dropping the message. The lead picks up the thread context and continues the conversation, preserving `parentTaskId` continuity for chained tasks.
+
+### Slack Context Propagation
+
+Slack metadata (`slackChannelId`, `slackThreadTs`, `slackUserId`) is **auto-inherited** from the creator's current task. When a lead delegates work from a Slack-originated task, workers automatically receive the Slack context and post progress updates to the originating thread — no manual metadata passing needed.
+
+The auto-inheritance works via the `X-Source-Task-Id` header, which links the new task back to the creator's active task to look up Slack metadata.
+
+For cases where auto-inheritance isn't available (e.g., programmatic task creation without an active parent task), you can pass Slack metadata explicitly on `send-task`:
+
+- `slackChannelId` — Channel ID for progress updates
+- `slackThreadTs` — Thread timestamp for thread-level updates
+- `slackUserId` — Original requester's Slack user ID
+
+Explicit params override auto-inherited values when both are present.
+
+### Additive Slack Buffer
+
+When enabled via `ADDITIVE_SLACK=true`, thread replies that do NOT @mention the bot are captured, buffered, and batched into a single follow-up task. This allows multi-message feedback without requiring an @mention each time.
+
+- Messages are buffered for a configurable debounce window (`ADDITIVE_SLACK_BUFFER_MS`, default 10s)
+- Buffered messages are flushed into a single task with dependency chaining to the active task
+- Use the `!now` command to flush the buffer immediately without dependency chaining
+- Reactions provide visual feedback: :eyes: for captured, :heavy_plus_sign: for appended, :zap: for `!now`
+
+### Single Evolving Message
+
+Each task gets a single Slack message that evolves through its lifecycle — from assignment to progress to completion. Instead of posting multiple messages, the bot uses `chat.update` to update one message in place:
+
+1. **Assignment** — When a task is created from Slack, the bot posts a structured Block Kit message with the task link, assigned agent, and status
+2. **Progress** — As the agent works, progress updates replace the message content (keeping the same message)
+3. **Completion** — The final message shows the task output, status, and action buttons
+
+This keeps threads clean and avoids message spam during long-running tasks.
+
+### Rich Block Kit Messages
+
+All Slack responses use structured [Block Kit](https://api.slack.com/block-kit) layouts instead of plain text:
+
+- **Headers** with task status indicators
+- **Context blocks** showing agent name, task ID, and timestamps
+- **Section blocks** for progress and output text
+- **Action buttons** for follow-up and viewing task logs
+- Markdown is automatically converted to Slack's `mrkdwn` format
+
+### Interactive Actions
+
+Task completion messages include interactive buttons:
+
+- **Follow-up** — Opens a modal to send a follow-up message to the same agent, creating a new task with dependency on the completed one
+- **View Full Logs** — Links to the task detail page in the dashboard
+- **Cancel** — Shows a confirmation dialog before cancelling an in-progress task
+
+### Assistant Sidebar
+
+The bot supports Slack's [Assistant](https://api.slack.com/docs/apps/ai) sidebar for direct conversations:
+
+- Open the sidebar in any channel or DM to start a conversation
+- Suggested prompts help you get started ("Check agent status", "Assign a task", "List recent tasks")
+- Follow-up messages in assistant threads route to the same agent that handled the original task
+- The assistant sets a typing status while the agent is working
+
+### Progress Updates
+
+Workers reply in Slack threads with progress updates using the `slack-reply` MCP tool. This keeps the conversation context in one place.
+
+### Reading Messages
+
+Agents can read Slack threads using `slack-read`:
+- By task ID (reads the thread associated with a task)
+- By channel ID (leads only, for channel history)
+
+### Posting Messages
+
+The lead agent can post new messages to channels using `slack-post`.
+
+## User Filtering
+
+By default, all Slack users can interact with the bot. To restrict access:
+
+```bash
+# Only users with matching email domains
+SLACK_ALLOWED_EMAIL_DOMAINS=company.com,partner.com
+
+# Specific user IDs always allowed (useful for admins)
+SLACK_ALLOWED_USER_IDS=U12345678,U87654321
+```
+
+If both are set, a user must match **either** an allowed domain **or** be in the user ID whitelist.
+
+## Attachment Handling
+
+Slack messages with file attachments (voice memos, images, documents) are automatically recognized and processed. When a user sends a file — even without any text — the bot detects it and includes attachment metadata (filename, MIME type, size, Slack file ID) in the task description.
+
+This means agents can:
+- Receive voice messages or image uploads as tasks
+- Access file metadata to decide whether to download and process attachments
+- Use `slack-download-file` to retrieve the actual file content
+
+## File Handling
+
+Agents can upload and download files via Slack:
+
+- **`slack-upload-file`** — Upload a file to a Slack channel or thread
+- **`slack-download-file`** — Download a file from Slack by file ID or URL
+
+Files are saved to `/workspace/shared/downloads/{agentId}/slack/` by default (each agent writes to its own subdirectory).
+
+## Related
+
+- [Environment Variables](/docs/reference/environment-variables) — Slack configuration variables (`SLACK_BOT_TOKEN`, etc.)
+- [Task Lifecycle](/docs/concepts/task-lifecycle) — How Slack messages become tasks
+- [GitHub App Integration](/docs/guides/github-integration) — Another external task source
+- [Linear Integration](/docs/guides/linear-integration) — Bidirectional ticket tracking with Linear
+- [Sentry Integration](/docs/guides/sentry-integration) — Automated error triage from Sentry
+- [x402 Payments](/docs/guides/x402-payments) — Enable agents to make crypto micropayments

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

@@ -0,0 +1,154 @@
+---
+title: x402 Payments
+description: Enable agents to make USDC micropayments on x402-gated APIs
+---
+
+# x402 Payments
+
+Agent Swarm includes built-in support for [x402](https://x402.org/) payments, allowing agents to automatically pay for x402-gated API endpoints using USDC on Base.
+
+## How It Works
+
+x402 is an open payment protocol that uses the HTTP 402 "Payment Required" status code for native micropayments over HTTP. When an agent calls an x402-gated API:
+
+1. The initial request returns a `402 Payment Required` response
+2. The x402 client automatically signs a USDC payment authorization (EIP-3009)
+3. The request is retried with the payment signature
+4. The API returns the response — payment is settled on-chain asynchronously
+
+The entire flow is **gasless** for the payer and completes in ~1.5–2 seconds.
+
+## Setup
+
+### Choose a Signer
+
+Two signer backends are supported:
+
+| Backend | Env Vars | Best For |
+|---------|----------|----------|
+| **Openfort** (recommended) | `OPENFORT_API_KEY` + `OPENFORT_WALLET_SECRET` | Production — keys managed in TEE |
+| **Viem** | `EVM_PRIVATE_KEY` | Development/testing — raw private key |
+
+The signer is auto-detected based on which credentials are set. Use `X402_SIGNER_TYPE` to override.
+
+### Openfort Setup
+
+1. Create an account at [openfort.xyz](https://www.openfort.xyz/)
+2. Get your API key and wallet secret
+3. Set environment variables:
+
+```bash
+OPENFORT_API_KEY=sk_test_...
+OPENFORT_WALLET_SECRET=<base64-encoded-p256-key>
+```
+
+### Viem Setup
+
+1. Generate a wallet (e.g., `cast wallet new`)
+2. Get test USDC from the [CDP Faucet](https://portal.cdp.coinbase.com/products/faucet) on Base Sepolia
+3. Set environment variable:
+
+```bash
+EVM_PRIVATE_KEY=0x...
+```
+
+No ETH needed — x402 payments are gasless for the payer.
+
+### Spending Limits
+
+Configure via environment variables or programmatically:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `X402_MAX_AUTO_APPROVE` | `$1.00` | Max per-request |
+| `X402_DAILY_LIMIT` | `$10.00` | Max per-day |
+
+See the full [environment variables reference](/docs/reference/environment-variables#x402-payments).
+
+## Usage
+
+### Drop-in Fetch Replacement
+
+```typescript
+import { createX402Fetch } from "@/x402";
+
+const paidFetch = createX402Fetch();
+
+// Use like normal fetch — 402 payments are automatic
+const response = await paidFetch("https://api.example.com/paid-endpoint");
+const data = await response.json();
+```
+
+### Full Client with Spending Tracking
+
+```typescript
+import { createX402Client } from "@/x402";
+
+const client = await createX402Client();
+
+// Make paid requests
+const response = await client.fetch("https://api.example.com/paid-endpoint");
+
+// Check spending
+const summary = client.getSpendingSummary();
+console.log(`Spent today: $${summary.todaySpent.toFixed(2)}`);
+console.log(`Remaining: $${summary.dailyRemaining.toFixed(2)}`);
+```
+
+### Custom Configuration
+
+```typescript
+import { createX402Client } from "@/x402";
+
+const client = await createX402Client({
+  maxAutoApprove: 0.50,   // Max $0.50 per request
+  dailyLimit: 5.00,       // Max $5.00 per day
+  network: "eip155:8453", // Base mainnet
+});
+```
+
+## CLI
+
+Test x402 payments from the command line:
+
+```bash
+# Check configuration
+bun src/x402/cli.ts check
+
+# Make a paid request
+bun src/x402/cli.ts fetch https://api.example.com/paid-endpoint
+
+# View spending summary
+bun src/x402/cli.ts status
+```
+
+## Module Structure
+
+```
+src/x402/
+├── index.ts              # Public API re-exports
+├── client.ts             # Payment client with spending limits
+├── config.ts             # Environment variable loading
+├── openfort-signer.ts    # Openfort backend wallet signer
+├── spending-tracker.ts   # In-memory spending tracking
+└── cli.ts                # CLI for testing payments
+```
+
+## Security
+
+- **Use burner wallets** — load only small amounts of working capital
+- **Set spending limits** — configure per-request and daily limits
+- **Never commit private keys** — always use environment variables
+- **Testnet first** — use Base Sepolia (`eip155:84532`) during development
+- **Openfort for production** — keys managed in a TEE, not on disk
+
+## Further Reading
+
+- [x402 Protocol Specification](https://github.com/coinbase/x402/blob/main/specs/x402-specification.md)
+- [x402 Buyer Quickstart](https://docs.cdp.coinbase.com/x402/quickstart-for-buyers)
+- [x402.org](https://www.x402.org/)
+
+## Related
+
+- [Environment Variables](/docs/reference/environment-variables#x402-payments) — x402 configuration variables
+- [Architecture Overview](/docs/architecture/overview) — How the x402 module fits into the system

package/docs-site/content/docs/(documentation)/index.mdx

@@ -0,0 +1,65 @@
+---
+title: Overview
+description: Multi-agent orchestration for AI coding assistants
+---
+
+# Agent Swarm
+
+Agent Swarm lets you run a team of AI coding agents that coordinate autonomously. A **lead agent** receives tasks (from you, Slack, or GitHub), breaks them down, and delegates to **worker agents** running in Docker containers. Workers execute tasks, report progress, and ship code — all without manual intervention.
+
+Built by [desplega.sh](https://desplega.sh) — build by builders, for builders.
+
+## Key Features
+
+- **Lead/Worker coordination** — A lead agent delegates and tracks work across multiple workers
+- **Docker isolation** — Each worker runs in its own container with a full dev environment
+- **Slack, GitHub, GitLab & Email integration** — Create tasks by messaging the bot, @mentioning it in issues/PRs/MRs, or sending an email
+- **Task lifecycle** — Priority queues, dependencies, pause/resume across deployments
+- **Compounding memory** — Agents learn from every session and get smarter over time
+- **Persistent identity** — Each agent has its own personality, expertise, and working style that evolves
+- **Dashboard UI** — Real-time monitoring of agents, tasks, and inter-agent chat
+- **Service discovery** — Workers can expose HTTP services and discover each other
+- **Scheduled tasks** — Recurring and one-time task automation (cron, interval, or delayed)
+- **Workflow automation** — DAG-based workflow engine with triggers, conditions, and actions
+- **x402 payments** — Agents can make USDC micropayments for x402-gated APIs
+- **Agent-fs integration** — Persistent, searchable filesystem shared across the swarm
+- **Debug dashboard** — SQL query interface for database inspection (lead-only)
+- **[Linear integration](/docs/guides/linear-integration)** — Bidirectional ticket tracker sync with AgentSession lifecycle
+- **Portless local dev** — Friendly domain URLs for local development
+- **Onboard wizard** — Interactive CLI to set up a new swarm from scratch with Docker Compose
+
+## How It Works
+
+```mermaid
+graph TD
+    User["You (Slack / GitHub / Email / CLI)"] --> Lead["Lead Agent"]
+    Lead <--> API["MCP API Server"]
+    API <--> DB["SQLite DB"]
+    Lead --> W1["Worker"]
+    Lead --> W2["Worker"]
+    Lead --> W3["Worker"]
+    W1 -.- D1["Docker container"]
+    W2 -.- D2["Docker container"]
+    W3 -.- D3["Docker container"]
+```
+
+1. **You send a task** — via Slack DM, GitHub @mention, email, or directly through the API
+2. **Lead agent plans** — breaks the task down and assigns subtasks to workers
+3. **Workers execute** — each in an isolated Docker container with git, Node.js, Python, etc.
+4. **Progress is tracked** — real-time updates in the dashboard, Slack threads, or API
+5. **Results are delivered** — PRs created, issues closed, Slack replies sent
+6. **Agents learn** — every session's learnings are extracted and recalled in future tasks
+
+## Supported AI Assistants
+
+Agent Swarm currently supports **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** as the AI coding assistant. Support for other agents (Codex, Gemini CLI, and other MCP-compatible assistants) is coming soon.
+
+## Next Steps
+
+- [Getting Started](/docs/getting-started) — Set up your first swarm
+- [Architecture Overview](/docs/architecture/overview) — Understand how the system works
+- [Core Concepts](/docs/concepts/task-lifecycle) — Learn about tasks, agents, and coordination
+
+---
+
+_Last updated: March 21, 2026 — v1.49.0_

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

@@ -0,0 +1,19 @@
+{
+  "title": "Documentation",
+  "description": "Guides, concepts, and reference for Agent Swarm",
+  "root": true,
+  "pages": [
+    "index",
+    "getting-started",
+    "---Architecture---",
+    "architecture",
+    "---Concepts---",
+    "concepts",
+    "---Guides---",
+    "guides",
+    "---Reference---",
+    "reference",
+    "---Community---",
+    "contributing"
+  ]
+}

package/docs-site/content/docs/(documentation)/reference/cli.mdx

@@ -0,0 +1,241 @@
+---
+title: CLI Reference
+description: Complete CLI reference for managing agents, tasks, and swarm configuration from the terminal
+---
+
+# CLI Reference
+
+Agent Swarm provides a CLI for managing the swarm, running agents, and development.
+
+## Installation
+
+```bash
+# Run directly with bunx
+bunx @desplega.ai/agent-swarm <command>
+
+# Or install globally
+bun install -g @desplega.ai/agent-swarm
+agent-swarm <command>
+```
+
+## Commands
+
+### onboard
+
+Set up a new swarm from scratch using Docker Compose. Interactive wizard that collects credentials, generates `docker-compose.yml` + `.env`, starts the stack, and verifies health.
+
+```bash
+bunx @desplega.ai/agent-swarm onboard
+bunx @desplega.ai/agent-swarm onboard --dry-run
+bunx @desplega.ai/agent-swarm onboard --yes --preset=dev
+ANTHROPIC_API_KEY=sk-... bunx @desplega.ai/agent-swarm onboard --yes --preset=solo
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Preview what would be generated without writing |
+| `-y, --yes` | Non-interactive mode (reads from env vars) |
+| `--preset <name>` | Preset: `dev`, `content`, `research`, `solo` |
+
+### connect
+
+Connect this project to an existing swarm. Creates `.mcp.json` and `.claude/settings.local.json` with server URL and API key. Auto-reads `API_KEY` from `.env` if present.
+
+```bash
+bunx @desplega.ai/agent-swarm connect
+bunx @desplega.ai/agent-swarm connect --dry-run
+bunx @desplega.ai/agent-swarm connect -y
+```
+
+| Option | Description |
+|--------|-------------|
+| `--dry-run` | Show what would be changed without writing |
+| `--restore` | Restore files from `.bak` backups |
+| `-y, --yes` | Non-interactive mode (use env vars) |
+
+### api
+
+Start the API + MCP HTTP server.
+
+```bash
+bunx @desplega.ai/agent-swarm api
+bunx @desplega.ai/agent-swarm api --port 8080 --key my-secret
+bunx @desplega.ai/agent-swarm api --db /data/swarm.sqlite
+```
+
+| Option | Description |
+|--------|-------------|
+| `-p, --port <port>` | Port to listen on (default: 3013) |
+| `-k, --key <key>` | API key for authentication |
+| `--db <path>` | Database file path (default: `./agent-swarm-db.sqlite`) |
+
+### claude
+
+Run Claude CLI with optional message and headless mode.
+
+```bash
+agent-swarm claude
+agent-swarm claude --headless -m "Hello"
+agent-swarm claude -- --resume
+```
+
+| Option | Description |
+|--------|-------------|
+| `-m, --msg <message>` | Message to send to Claude |
+| `--headless` | Run in headless mode (stream JSON output) |
+| `-- <args...>` | Additional arguments to pass to Claude CLI |
+
+### worker
+
+Run Claude in headless loop mode as a worker agent.
+
+```bash
+agent-swarm worker
+agent-swarm worker --yolo
+agent-swarm worker -m "Custom prompt"
+agent-swarm worker --system-prompt "You are a Python specialist"
+```
+
+| Option | Description |
+|--------|-------------|
+| `-m, --msg <prompt>` | Custom prompt (default: `/agent-swarm:start-worker`) |
+| `--yolo` | Continue on errors instead of stopping |
+| `--system-prompt <text>` | Custom system prompt (appended to Claude) |
+| `--system-prompt-file <path>` | Read system prompt from file |
+| `--ai-loop` | Use AI-based polling (legacy mode) |
+| `-- <args...>` | Additional arguments to pass to Claude CLI |
+
+### lead
+
+Run Claude as lead agent in headless loop mode. Same options as `worker`.
+
+```bash
+agent-swarm lead
+agent-swarm lead --yolo
+```
+
+### docs
+
+Show the documentation URL. All pages are also available in markdown format by appending `.md` to the URL.
+
+```bash
+bunx @desplega.ai/agent-swarm docs
+bunx @desplega.ai/agent-swarm docs --open
+```
+
+| Option | Description |
+|--------|-------------|
+| `--open` | Open docs in default browser |
+
+### hook
+
+Handle Claude Code hook events from stdin. Used internally by the agent-swarm hooks system.
+
+```bash
+agent-swarm hook
+```
+
+### artifact
+
+Manage agent artifacts — serve static files or Hono apps via localtunnel.
+
+```bash
+# Serve a directory as a public artifact
+agent-swarm artifact serve ./my-report --name my-report
+
+# Serve a Hono app (must export default Hono instance)
+agent-swarm artifact serve ./server.ts --name dashboard
+
+# List active artifacts
+agent-swarm artifact list
+
+# Stop an artifact
+agent-swarm artifact stop my-report
+```
+
+**Subcommands:**
+
+| Subcommand | Description |
+|------------|-------------|
+| `serve <path>` | Serve a directory or script via localtunnel |
+| `list` | List active artifacts from the service registry |
+| `stop <name>` | Stop an artifact and close its tunnel |
+
+**Options for `serve`:**
+
+| Option | Description |
+|--------|-------------|
+| `--name <name>` | Name for the artifact (derived from path if omitted) |
+| `--port <port>` | Local port to use |
+| `--no-auth` | Disable authentication |
+| `--subdomain <sub>` | Request a specific localtunnel subdomain |
+
+Artifacts are registered in the service registry and automatically cleaned up when the session ends (via the Stop hook).
+
+## Development Commands
+
+These are available when developing Agent Swarm locally:
+
+```bash
+# Start MCP server
+bun run start        # STDIO transport
+bun run start:http   # HTTP transport
+
+# Development with hot reload
+bun run dev          # STDIO
+bun run dev:http     # HTTP
+
+# MCP Inspector (debug tools)
+bun run inspector:http
+
+# Run worker/lead locally
+bun run worker
+bun run lead
+
+# Hook handler
+bun run hook
+
+# Linting and formatting
+bun run lint
+bun run lint:fix
+bun run format
+
+# Type checking
+bun run tsc:check
+
+# Build binaries
+bun run build:binary      # x64
+bun run build:binary:arm64  # ARM64
+
+# Docker
+bun run docker:build:worker
+bun run docker:run:worker
+bun run docker:run:lead
+
+# Generate MCP docs
+bun run docs:mcp
+```
+
+## Dashboard UI
+
+The React-based monitoring dashboard is in the `new-ui/` directory:
+
+```bash
+cd new-ui
+bun install
+bun run dev
+```
+
+Opens at `http://localhost:5173`. Provides real-time visibility into:
+- Agent status and activity
+- Task list and progress
+- Inter-agent chat messages
+- Service registry
+- Usage and cost tracking
+
+## Related
+
+- [Getting Started](/docs/getting-started) — Set up your first swarm
+- [Environment Variables](/docs/reference/environment-variables) — Configuration reference for all env vars
+- [MCP Tools Reference](/docs/reference/mcp-tools) — Complete reference for all swarm MCP tools
+- [Deployment Guide](/docs/guides/deployment) — Production deployment options