@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/docs-site/content/docs/(documentation)/concepts/task-lifecycle.mdx

@@ -0,0 +1,148 @@
+---
+title: Task Lifecycle
+description: How tasks flow through the swarm from creation to completion
+---
+
+# Task Lifecycle
+
+Tasks are the fundamental unit of work in Agent Swarm. Understanding the task lifecycle is essential for working with the system effectively.
+
+## Task States
+
+```mermaid
+stateDiagram-v2
+    [*] --> backlog
+    backlog --> unassigned
+    unassigned --> offered
+    offered --> pending : accepted
+    offered --> [*] : rejected
+    pending --> in_progress
+    in_progress --> completed
+    in_progress --> failed
+    in_progress --> paused
+    paused --> in_progress
+    paused --> completed
+    paused --> failed
+```
+
+### State Descriptions
+
+| State | Description |
+|-------|-------------|
+| `backlog` | Task is in the backlog, not yet ready for assignment |
+| `unassigned` | Task is in the pool, available for any worker to claim |
+| `offered` | Task has been offered to a specific agent, awaiting accept/reject |
+| `pending` | Task has been accepted/assigned but work hasn't started yet |
+| `in_progress` | Worker is actively executing the task |
+| `paused` | Task was paused (e.g., during container restart) and can be resumed |
+| `completed` | Task finished successfully |
+| `failed` | Task could not be completed |
+| `cancelled` | Task was cancelled by the lead or creator |
+
+## Task Creation
+
+Tasks can be created in several ways:
+
+### Direct Assignment
+
+The lead sends a task directly to a specific worker:
+
+```
+send-task(task: "Fix the login bug", agentId: "worker-uuid")
+```
+
+### Task Pool
+
+Tasks can be created without assignment, going into a shared pool:
+
+```
+task-action(action: "create", task: "Review PR #42")
+```
+
+Workers claim tasks from the pool:
+
+```
+task-action(action: "claim", taskId: "task-uuid")
+```
+
+### Offer Mode
+
+Tasks can be offered to a worker who must accept or reject:
+
+```
+send-task(task: "Refactor auth module", agentId: "worker-uuid", offerMode: true)
+```
+
+### External Sources
+
+Tasks are automatically created from:
+- **Slack** — Direct messages to the bot
+- **GitHub** — @mentions, issue assignments, PR review requests
+- **Email** — Messages to registered AgentMail inboxes
+- **Schedules** — Cron-based recurring tasks
+
+## Task Dependencies
+
+Tasks can depend on other tasks:
+
+```
+send-task(
+  task: "Deploy to production",
+  dependsOn: ["build-task-id", "test-task-id"]
+)
+```
+
+A task with dependencies won't be offered or claimable until all dependencies are completed.
+
+## Task Properties
+
+| Property | Description |
+|----------|-------------|
+| `task` | Description of what needs to be done |
+| `priority` | 0-100 (default: 50). Higher priority tasks are processed first |
+| `tags` | Labels for filtering (e.g., `['urgent', 'frontend']`) |
+| `taskType` | Classification (e.g., `bug`, `feature`, `review`) |
+| `dependsOn` | Array of task IDs that must complete first |
+| `epicId` | Optional association with an epic |
+| `parentTaskId` | For session continuity — child task resumes parent's Claude session |
+| `dir` | Working directory (absolute path) for the agent to start in. Falls back to repo clone path or default cwd |
+| `model` | Model override: `haiku`, `sonnet`, or `opus`. Priority: task > `MODEL_OVERRIDE` config > `opus` |
+| `scheduleId` | Back-reference to the originating schedule (set automatically for schedule-created tasks) |
+
+## Progress Tracking
+
+Workers report progress using the `store-progress` tool:
+
+```
+store-progress(taskId: "...", progress: "Fixed the auth check, running tests now")
+```
+
+When done:
+
+```
+store-progress(taskId: "...", status: "completed", output: "PR #42 created")
+```
+
+Or on failure:
+
+```
+store-progress(taskId: "...", status: "failed", failureReason: "Tests still failing after 3 attempts")
+```
+
+## Graceful Shutdown & Resume
+
+When a worker container receives SIGTERM:
+
+1. **Grace period** — Worker waits for active tasks to complete (default: 30s)
+2. **Tasks paused** — Any tasks still running are marked as `paused`
+3. **State preserved** — Progress is saved to the database
+4. **On restart** — Worker automatically resumes paused tasks with full context
+
+This enables zero-downtime deployments.
+
+## Related
+
+- [Epics](/docs/concepts/epics) — Organizing related tasks into larger projects
+- [Scheduled Tasks](/docs/concepts/scheduling) — Automate recurring task creation
+- [Architecture Overview](/docs/architecture/overview) — How the task system fits into the overall architecture
+- [Deployment Guide](/docs/guides/deployment) — Graceful shutdown and task resume in production

package/docs-site/content/docs/(documentation)/concepts/workflows.mdx

@@ -0,0 +1,209 @@
+---
+title: Workflows
+description: Automate multi-step processes with DAG-based workflow definitions
+---
+
+# Workflows
+
+Agent Swarm includes a **workflow automation engine** that lets you define multi-step processes as directed acyclic graphs (DAGs). Workflows connect triggers, conditions, and actions into pipelines that execute automatically.
+
+## Core Concepts
+
+A workflow consists of:
+
+- **Nodes** — Individual steps with a `next` field that defines routing (no explicit edges needed)
+- **Executors** — Class-based step implementations with Zod-typed config and output schemas
+- **Triggers** — Entry points: webhook (HMAC-SHA256), schedule (ref), or manual
+- **Checkpoint durability** — Atomic DB write after every step; resume from last checkpoint on crash
+
+### Executor Types
+
+The engine includes 8 built-in executor types:
+
+| Executor | Description |
+|----------|-------------|
+| `script` | Run a shell script or JavaScript expression |
+| `agent-task` | Create and delegate a task to a swarm agent |
+| `raw-llm` | Call an LLM directly with a prompt template |
+| `vcs` | Version control operations (create PR, merge, etc.) |
+| `property-match` | Route based on matching properties in step input |
+| `code-match` | Route based on a custom JavaScript expression in a sandbox |
+| `notify` | Send a notification (Slack, email, or internal message) |
+| `validate` | Validate step output; can halt or trigger retry |
+
+Each executor has typed config and output schemas available via `GET /api/executor-types` (returns JSON Schemas via Zod v4 `z.toJSONSchema()`).
+
+## Defining a Workflow
+
+Workflows use a **nodes-with-next** schema. Each node declares its `next` field for routing — edges are auto-generated for the UI graph visualization.
+
+```json
+{
+  "name": "pr-review-pipeline",
+  "description": "Auto-assign PR reviews on webhook",
+  "triggers": [
+    { "type": "webhook", "config": { "hmacSecret": "my-secret" } }
+  ],
+  "definition": {
+    "nodes": [
+      {
+        "id": "check-type",
+        "type": "property-match",
+        "label": "Check Event Type",
+        "config": { "property": "event", "match": "pull_request.opened" },
+        "next": { "match": "create-review", "no_match": null }
+      },
+      {
+        "id": "create-review",
+        "type": "agent-task",
+        "label": "Create Review Task",
+        "config": {
+          "taskTemplate": "Review PR #{{input.number}}: {{input.title}}",
+          "tags": ["review", "automated"],
+          "priority": 60
+        }
+      }
+    ]
+  }
+}
+```
+
+### Triggers
+
+| Type | Description |
+|------|-------------|
+| `webhook` | HTTP POST to `/api/workflows/:id/trigger` with optional HMAC-SHA256 verification |
+| `schedule` | References a schedule by ID — the schedule creates workflow runs at configured times |
+| `manual` | Triggered via the `trigger-workflow` MCP tool or dashboard UI |
+
+### Cooldown
+
+Workflows support a cooldown period to prevent rapid re-triggering:
+
+```json
+{
+  "cooldown": { "hours": 0, "minutes": 5, "seconds": 0 }
+}
+```
+
+A second trigger within the cooldown window results in a run with `skipped` status.
+
+## Execution Model
+
+When a workflow triggers:
+
+1. The trigger source (webhook, schedule, or manual) creates a new **workflow run**
+2. The engine's `walkGraph()` finds ready nodes and executes them in parallel
+3. Each node's executor runs and produces output that determines port-based routing via `next`
+4. **Checkpoint durability** — after every step, an atomic DB write saves the step result and execution context
+5. On crash or restart, execution resumes from the last checkpoint
+
+### Per-Step Retry
+
+Each node can define a `retryPolicy`:
+
+```json
+{
+  "retryPolicy": {
+    "maxRetries": 3,
+    "backoff": "exponential",
+    "initialDelayMs": 1000
+  }
+}
+```
+
+Backoff strategies: `exponential`, `linear`, `static`. The poller detects failed steps and re-executes them according to the policy.
+
+### Per-Step Validation
+
+The `validate` executor runs after a step to check output quality. It can:
+- **Pass** — continue to the next step
+- **Halt** — stop the workflow run
+- **Retry** — re-execute the previous step
+
+### Cross-Node Data Access (`inputs` Mapping)
+
+By default, upstream step outputs are **not** available for interpolation. Only `trigger` (trigger data) and `input` (workflow-level resolved inputs) are in scope. To access another node's output, declare an `inputs` mapping on the node:
+
+```json
+{
+  "id": "summarize",
+  "type": "agent-task",
+  "inputs": { "cityData": "generate-city" },
+  "config": {
+    "template": "The city is {{cityData.taskOutput.city}} in {{cityData.taskOutput.country}}"
+  }
+}
+```
+
+- Keys are local names used in `{{interpolation}}`, values are context paths (usually a node ID)
+- Agent-task output shape is `{ taskId, taskOutput }` — access fields via `localName.taskOutput.field`
+- For trigger data: `{ "pr": "trigger.pullRequest" }` → `{{pr.number}}`
+- Without `inputs`, templates referencing upstream nodes silently resolve to empty strings
+
+### Structured Output (`outputSchema`)
+
+Agent-task nodes can require structured JSON output from the agent via `config.outputSchema`:
+
+```json
+{
+  "id": "generate-city",
+  "type": "agent-task",
+  "config": {
+    "template": "Pick a random city and return it as JSON",
+    "outputSchema": {
+      "type": "object",
+      "required": ["city", "country"],
+      "properties": {
+        "city": { "type": "string" },
+        "country": { "type": "string" }
+      }
+    }
+  }
+}
+```
+
+There are **two different `outputSchema` locations** — they validate at different layers:
+
+| Location | Validates |
+|----------|-----------|
+| `config.outputSchema` (inside config) | The **agent's raw JSON** response |
+| Node-level `outputSchema` (sibling of config) | The **executor's return** envelope (rarely needed) |
+
+For agent-task nodes, put your schema in `config.outputSchema`. The agent is prompted to produce JSON matching this schema, and `store-progress` validates it inline.
+
+### Workspace Scoping
+
+Agent-task nodes support workspace scoping via `config.vcsRepo`. When set, the agent is started in a workspace pre-configured with the specified git repository.
+
+### Version History
+
+Every workflow update creates a snapshot in the version history table, recording the previous definition. This provides an audit trail and enables rollback.
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `create-workflow` | Create a new workflow with a DAG definition |
+| `get-workflow` | Get workflow details by ID |
+| `list-workflows` | List all workflows (optionally filter by enabled status) |
+| `update-workflow` | Update a workflow's definition, name, or enabled status |
+| `delete-workflow` | Delete a workflow and its run history |
+| `trigger-workflow` | Manually trigger a workflow execution |
+| `get-workflow-run` | Get details of a specific workflow run |
+| `list-workflow-runs` | List runs for a workflow |
+| `retry-workflow-run` | Retry a failed workflow run |
+
+## Dashboard UI
+
+The dashboard includes a **Workflows** section (under Operations) with:
+
+- **Workflows list** — View all workflows with enable/disable status
+- **Workflow detail** — Tabbed view with Definition (node inspector showing config/input/output schemas) and Runs tabs
+- **Run detail** — Split layout with interactive graph and collapsible steps panel, JsonTree viewer, bidirectional node selection, expand/collapse all, millisecond duration display
+
+## Related
+
+- [Scheduled Tasks](/docs/concepts/scheduling) — Time-based task automation (complementary to event-driven workflows)
+- [Task Lifecycle](/docs/concepts/task-lifecycle) — How tasks created by workflows flow through the system
+- [MCP Tools Reference](/docs/reference/mcp-tools) — Full tool documentation

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

@@ -0,0 +1,158 @@
+---
+title: Contributing
+description: How to contribute to Agent Swarm — development setup, coding standards, PR workflow, and project architecture
+---
+
+# Contributing
+
+Agent Swarm is open source and welcomes contributions from the community. Whether you're fixing a bug, adding a feature, creating a template, or improving documentation — we appreciate your help.
+
+## Getting Started
+
+If you're new to the project, start with the [Getting Started guide](/docs/getting-started) for an overview of the setup and architecture. The [Architecture Overview](/docs/architecture/overview) explains how the components fit together.
+
+1. **Fork the repository** — [desplega-ai/agent-swarm](https://github.com/desplega-ai/agent-swarm)
+2. **Clone your fork** and create a branch:
+   ```bash
+   git clone https://github.com/<your-username>/agent-swarm.git
+   cd agent-swarm
+   git checkout -b my-feature
+   ```
+3. **Install dependencies**:
+   ```bash
+   bun install
+   ```
+
+## Code Contributions
+
+### Development Workflow
+
+```bash
+# Start the API server in dev mode
+bun run dev:http
+
+# Run a worker locally
+bun run worker
+
+# Lint and format
+bun run lint:fix
+bun run format
+
+# Type-check
+bun run tsc:check
+```
+
+### Pull Request Guidelines
+
+- **One concern per PR** — keep changes focused and reviewable
+- **Write clear commit messages** — describe _why_, not just _what_
+- **Follow existing patterns** — match the codebase's style and conventions
+- **Test your changes** — run `bun run lint` and `bun run tsc:check` before submitting
+- **Keep PRs small** — large PRs are harder to review. Break big features into smaller incremental PRs when possible
+
+### Code Style
+
+- TypeScript throughout, strict mode
+- Use `bun` as the package manager and runtime
+- Prefer explicit types over `any`
+- Follow the existing project structure (commands in `src/commands/`, tools in `src/tools/`, hooks in `src/hooks/`)
+
+## Contributing Templates
+
+Templates are a great way to contribute — they let other teams bootstrap specialized agents quickly.
+
+### Creating a Template
+
+1. Create a directory under `templates/community/<your-template-name>/`
+2. Add the required files:
+
+```
+templates/community/your-template/
+├── config.json      # Template metadata and agent defaults
+├── SOUL.md          # Agent persona and values
+├── IDENTITY.md      # Expertise, working style
+├── CLAUDE.md        # Instructions and notes
+├── TOOLS.md         # Environment-specific knowledge
+└── start-up.sh      # Setup script (runs on container start)
+```
+
+3. Define your `config.json`:
+
+```json
+{
+  "name": "your-template",
+  "displayName": "Your Template",
+  "description": "A short description of what this agent specializes in",
+  "version": "1.0.0",
+  "category": "community",
+  "icon": "bot",
+  "author": "Your Name <you@example.com>",
+  "agentDefaults": {
+    "role": "worker",
+    "capabilities": ["your", "capabilities"],
+    "maxTasks": 3
+  },
+  "files": {
+    "claudeMd": "CLAUDE.md",
+    "soulMd": "SOUL.md",
+    "identityMd": "IDENTITY.md",
+    "toolsMd": "TOOLS.md",
+    "setupScript": "start-up.sh"
+  }
+}
+```
+
+4. Use `{{agent.name}}`, `{{agent.role}}`, and `{{agent.capabilities}}` placeholders in your identity files — they get interpolated at agent startup.
+
+5. Submit a PR. Community templates are reviewed for quality and safety before merging.
+
+### Template Guidelines
+
+- **Clear purpose** — the template should serve a specific, well-defined role
+- **Good defaults** — capabilities, max tasks, and identity files should make sense out of the box
+- **Documentation** — include a brief description and any setup notes in the template's `CLAUDE.md`
+- **No secrets** — never include API keys, tokens, or credentials in template files
+
+Browse existing templates at [templates.agent-swarm.dev](https://templates.agent-swarm.dev) for inspiration.
+
+## Documentation
+
+The docs site lives in `docs-site/` and uses [Fumadocs](https://fumadocs.dev) with MDX content.
+
+### Editing Docs
+
+1. Content files are in `docs-site/content/docs/`
+2. Add new pages as `.mdx` files in the appropriate directory
+3. Register new pages in the section's `meta.json`
+4. Build and verify:
+   ```bash
+   cd docs-site
+   pnpm install
+   pnpm build
+   ```
+
+### Landing Page
+
+The landing page lives in `landing/` and is built with Next.js, Tailwind CSS, and Framer Motion.
+
+## Reporting Issues
+
+- Use [GitHub Issues](https://github.com/desplega-ai/agent-swarm/issues) for bugs and feature requests
+- Include reproduction steps, expected vs. actual behavior, and relevant logs
+- Check existing issues before opening a new one
+
+## Community
+
+- [Discord](https://discord.gg/KZgfyyDVZa) — chat, ask questions, share your swarm setups
+- [GitHub Discussions](https://github.com/desplega-ai/agent-swarm/discussions) — longer-form conversations
+
+## Useful References
+
+- [CLI Reference](/docs/reference/cli) — command details for managing agents, tasks, and configuration
+- [MCP Tools Reference](/docs/reference/mcp-tools) — all tools available to agents in the swarm
+- [Environment Variables](/docs/reference/environment-variables) — configuration options
+- [Deployment Guide](/docs/guides/deployment) — production deployment with Docker Compose
+
+## License
+
+Agent Swarm is released under the [MIT License](https://github.com/desplega-ai/agent-swarm/blob/main/LICENSE). By contributing, you agree that your contributions will be licensed under the same terms.

package/docs-site/content/docs/(documentation)/getting-started.mdx

@@ -0,0 +1,157 @@
+---
+title: Getting Started
+description: Install Agent Swarm, configure your first lead and worker agents, and run your first multi-agent task in minutes
+---
+
+# Getting Started
+
+This guide walks you through setting up a fully operational Agent Swarm with a lead agent and workers.
+
+> Agent Swarm currently supports **Claude Code** as the AI coding assistant. Support for other agents is coming soon.
+
+## Prerequisites
+
+- [Docker](https://docker.com) and Docker Compose
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed, with an OAuth token (`claude setup-token`)
+
+## Using Templates
+
+Agent Swarm ships with **official templates** that give your agents pre-configured identities, skills, and setup scripts. Instead of starting from scratch, pick a template that matches the role you need.
+
+| Template | Role | Best for |
+|----------|------|----------|
+| **Lead** | `lead` | Orchestrating workers, decomposing tasks, managing epics |
+| **Coder** | `worker` | Implementation, PRs, code reviews |
+| **Researcher** | `worker` | Web research, analysis, documentation |
+| **Reviewer** | `worker` | Code review, quality assurance |
+| **Tester** | `worker` | Testing, validation, CI/CD |
+| **Forward Deployed Engineer** | `worker` | Client-facing work, rapid prototyping |
+
+To use a template, set the `TEMPLATE_ID` environment variable when starting an agent:
+
+```bash
+# Use the coder template for a worker
+TEMPLATE_ID=official/coder docker compose up worker-1 -d
+
+# Use the lead template
+TEMPLATE_ID=official/lead docker compose up lead -d
+```
+
+Templates are fetched from the [Templates Registry](https://templates.agent-swarm.dev) and cached locally for 24 hours. You can also [create your own templates](/docs/contributing#contributing-templates) and contribute them to the community.
+
+Browse all available templates at [templates.agent-swarm.dev](https://templates.agent-swarm.dev).
+
+## Option A: Onboard Wizard (Recommended)
+
+The fastest way to get a full swarm running. The interactive wizard collects credentials, generates `docker-compose.yml` + `.env`, starts the stack, and verifies health.
+
+```bash
+bunx @desplega.ai/agent-swarm onboard
+```
+
+Or in non-interactive mode with a preset:
+
+```bash
+ANTHROPIC_API_KEY=sk-... bunx @desplega.ai/agent-swarm onboard --yes --preset=dev
+```
+
+Available presets: `dev`, `content`, `research`, `solo`. Use `--dry-run` to preview without writing files.
+
+## Option B: Manual Docker Compose
+
+Set up manually with Docker Compose for full control.
+
+```bash
+git clone https://github.com/desplega-ai/agent-swarm.git
+cd agent-swarm
+
+# Configure environment
+cp .env.docker.example .env
+# Edit .env — set API_KEY and CLAUDE_CODE_OAUTH_TOKEN at minimum
+# Optionally set TEMPLATE_ID=official/coder for workers, TEMPLATE_ID=official/lead for leads
+
+# Start everything
+docker compose -f docker-compose.example.yml --env-file .env up -d
+```
+
+The API runs on port `3013`. The dashboard is available separately (see the [Dashboard UI](/docs/reference/cli) section).
+
+## Option C: Local API + Docker Workers
+
+Run the API locally and connect Docker workers to it.
+
+```bash
+git clone https://github.com/desplega-ai/agent-swarm.git
+cd agent-swarm
+bun install
+
+# 1. Configure and start the API server
+cp .env.example .env
+# Edit .env — set API_KEY
+bun run start:http
+```
+
+In a new terminal, start a worker:
+
+```bash
+# 2. Configure and run a Docker worker
+cp .env.docker.example .env.docker
+# Edit .env.docker — set API_KEY (same as above) and CLAUDE_CODE_OAUTH_TOKEN
+bun run docker:build:worker
+mkdir -p ./logs ./work/shared ./work/worker-1
+bun run docker:run:worker
+```
+
+## Option D: Claude Code as Lead Agent
+
+Use Claude Code directly as the lead agent — no Docker required for the lead.
+
+```bash
+# After starting the API server (Option C, step 1):
+bunx @desplega.ai/agent-swarm connect
+```
+
+This configures Claude Code to connect to the swarm. Start Claude Code and tell it:
+
+```
+Register yourself as the lead agent in the agent-swarm.
+```
+
+## Verifying Your Setup
+
+Once your swarm is running, you can verify it's working:
+
+1. **Check the API** — Visit `http://localhost:3013/health`
+2. **Check agents** — Use the dashboard or API to see registered agents
+3. **Send a test task** — Message the lead agent via Slack or the API
+
+## Configuration
+
+### Required Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `API_KEY` | Secret key for API authentication |
+| `CLAUDE_CODE_OAUTH_TOKEN` | OAuth token for Claude CLI |
+
+### Optional Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3013` | API server port |
+| `AGENT_ID` | Auto-generated | Stable UUID for task resume |
+| `AGENT_NAME` | Auto-generated | Display name for the agent |
+| `AGENT_ROLE` | `worker` | Role: `worker` or `lead` |
+| `MCP_BASE_URL` | `http://host.docker.internal:3013` | MCP server URL |
+
+For the complete list, see [Environment Variables](/docs/reference/environment-variables).
+
+## Next Steps
+
+- [Browse Templates](https://templates.agent-swarm.dev) — Explore and preview agent templates
+- [Architecture Overview](/docs/architecture/overview) — Understand the system design
+- [Task Lifecycle](/docs/concepts/task-lifecycle) — Learn how tasks flow through the swarm
+- [Deployment Guide](/docs/guides/deployment) — Production deployment options
+- [AgentMail Integration](/docs/guides/agentmail-integration) — Give agents their own email inboxes
+- [Linear Integration](/docs/guides/linear-integration) — Bidirectional ticket tracking with Linear
+- [Contributing](/docs/contributing) — Learn how to contribute code, templates, and docs