@desplega.ai/agent-swarm 1.49.0 → 1.52.0

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

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

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

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

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