@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/docs-site/content/docs/(documentation)/architecture/memory.mdx

@@ -0,0 +1,96 @@
+---
+title: Memory System
+description: How agents build compounding knowledge across sessions
+---
+
+# Memory System
+
+Agent Swarm agents aren't stateless. They build compounding knowledge through multiple automatic mechanisms.
+
+## How Memory Works
+
+Every agent has a searchable memory backed by OpenAI embeddings (`text-embedding-3-small`, 512 dimensions). Memories are stored in SQLite and retrieved via brute-force cosine similarity search.
+
+### Memory Sources
+
+Memories are automatically created from:
+
+- **Session summaries** — At the end of each session, a lightweight model (Haiku) extracts key learnings: mistakes made, patterns discovered, failed approaches, and codebase knowledge. These summaries become searchable memories.
+- **Task completions** — Every completed (or failed) task's output is indexed. Failed tasks include notes about what went wrong, so the agent avoids repeating the same mistake.
+- **File-based notes** — Agents write to `/workspace/personal/memory/` in their per-agent directory. Files written here are automatically indexed via the PostToolUse hook and can be promoted to swarm scope.
+- **Lead-to-worker injection** — The lead agent can push specific learnings into any worker's memory using the `inject-learning` tool, closing the feedback loop.
+
+### Memory Scopes
+
+| Scope | Path | Visibility |
+|-------|------|-----------|
+| Agent (private) | `/workspace/personal/memory/` | Only the owning agent |
+| Swarm (shared) | Promoted via `inject-learning` or epic completion | All agents in the swarm |
+
+### Automatic Scope Promotion
+
+When a task is linked to an epic, its completion output is automatically promoted to **swarm scope** — making it visible to all agents, not just the one that completed it. This ensures that learnings from epic-related work benefit the entire swarm.
+
+Similarly, the `inject-learning` tool creates swarm-scoped memories by default, so learnings injected by the lead are available to all workers.
+
+## Memory Retrieval
+
+Before starting each task, the runner automatically searches for relevant memories and includes them in the agent's context. Agents are required to run `memory-search` at the start of every task.
+
+### Search Process
+
+1. Task description is used as the search query (enriched with epic name/goal if linked)
+2. Embedding is generated for the query
+3. Cosine similarity is computed against all stored memories
+4. Top matches are included in the task context as "Relevant Past Knowledge"
+5. For epic-linked tasks, recent completed task summaries from the same epic are also injected
+
+### Manual Search
+
+Agents can also search memories manually using MCP tools:
+
+- **`memory-search`** — Search with natural language queries. Returns summaries with IDs.
+- **`memory-get`** — Retrieve full details of a specific memory by ID.
+
+## Writing Memories
+
+The best practice is to write memories to files immediately when something important is learned:
+
+```
+Write("/workspace/personal/memory/auth-header-fix.md",
+  "The API requires Bearer prefix on all auth headers.
+   Without it, you get a misleading 403 instead of 401.")
+```
+
+Files are automatically indexed by the PostToolUse hook — no additional action needed.
+
+### What to Save
+
+- Solutions to problems you solved
+- Codebase patterns you discovered
+- Mistakes you made and how to avoid them
+- Important configurations
+- Instructions from the lead or user
+
+### What Not to Save
+
+- Session-specific context (temporary state)
+- Unverified conclusions
+- Information that duplicates existing documentation
+
+## Memory Categories
+
+When the lead injects learnings via `inject-learning`, they're categorized:
+
+| Category | Purpose |
+|----------|---------|
+| `mistake-pattern` | Common mistakes to avoid |
+| `best-practice` | Preferred approaches |
+| `codebase-knowledge` | Facts about the codebase |
+| `preference` | User or team preferences |
+
+## Related
+
+- [Hook System](/docs/architecture/hooks) — The PostToolUse hook that auto-indexes memory files
+- [Agent Identity & Configuration](/docs/architecture/agents) — How identity files persist across sessions
+- [Architecture Overview](/docs/architecture/overview) — System-level view of how memory fits in

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

@@ -0,0 +1,4 @@
+{
+  "title": "Architecture",
+  "pages": ["overview", "agents", "memory", "hooks"]
+}

package/docs-site/content/docs/(documentation)/architecture/overview.mdx

@@ -0,0 +1,172 @@
+---
+title: Architecture Overview
+description: How Agent Swarm is built and how the components fit together
+---
+
+# Architecture Overview
+
+Agent Swarm follows a hub-and-spoke architecture where a central MCP API server coordinates communication between agents.
+
+## System Diagram
+
+```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"]
+```
+
+## Core Components
+
+### MCP API Server
+
+The MCP (Model Context Protocol) server is the central coordination point. It:
+
+- Exposes tools via the MCP protocol (both STDIO and HTTP transports)
+- Manages agent registration and task assignment
+- Stores all state in a SQLite database
+- Handles integrations (Slack, GitHub, GitLab, AgentMail, Linear webhooks)
+- Runs the task scheduler for recurring automation
+
+The server runs on port `3013` by default and is implemented in `src/http/` (modular route handlers) with tool definitions in `src/server.ts`.
+
+It also runs three background subsystems:
+- **Scheduler** — Polls for scheduled tasks and creates them at the configured interval
+- **Workflow Engine** — Redesigned DAG executor with executor registry (8 types), checkpoint durability, webhook/schedule/manual triggers, per-step retry, and version history (see [Workflows](/docs/concepts/workflows))
+- **Heartbeat** — A lightweight triage module that sweeps the swarm every 90 seconds (configurable via `HEARTBEAT_INTERVAL_MS`). It uses a 3-tier approach: a preflight gate that bails if the swarm is healthy, code-level triage for routine fixes (stall detection, worker status correction, pool task auto-assignment, stale resource cleanup), and Claude escalation only when ambiguous situations require human reasoning. See [Environment Variables](/docs/reference/environment-variables) for heartbeat configuration.
+
+### Lead Agent
+
+The lead agent is the coordinator. It:
+
+- Receives incoming tasks from external sources (Slack, GitHub, email)
+- Has an **inbox** for triaging incoming messages
+- Breaks down complex tasks and delegates to workers
+- Monitors worker progress and provides feedback
+- Communicates results back to the user
+- Can inject learnings into worker memories
+
+### Worker Agents
+
+Workers are the execution layer. Each worker:
+
+- Runs in an isolated Docker container with a full development environment
+- Has access to git, Node.js, Python, Bun, and common CLI tools
+- Executes tasks assigned by the lead agent
+- Reports progress via the `store-progress` MCP tool
+- Can expose HTTP services on port 3000
+- Learns from each session and builds compounding knowledge
+
+### Docker Runtime
+
+Each worker container includes:
+
+- **Languages**: Python 3, Node.js 22, Bun
+- **Build tools**: gcc, g++, make, cmake
+- **Process manager**: PM2 (for background services)
+- **CLI tools**: GitHub CLI (`gh`), GitLab CLI (`glab`), sqlite3
+- **Agent tools**: `wts` (git worktree manager), `agent-fs` (persistent shared filesystem)
+- **Utilities**: git, git-lfs, vim, nano, jq, curl, wget, ssh
+- **Sudo access**: Workers can install packages with `sudo apt-get install`
+
+## Data Flow
+
+### Task Creation
+
+1. User sends a message (Slack DM, GitHub @mention, email, or API call)
+2. MCP server receives the webhook/request
+3. Lead agent's inbox receives the message
+4. Lead agent triages and creates tasks for workers
+
+### Task Execution
+
+1. Worker polls for or receives a task assignment
+2. Worker starts a Claude Code session with the task context
+3. Worker executes the task, using MCP tools for coordination
+4. Worker reports progress via `store-progress`
+5. On completion, output is saved and the lead is notified
+
+### Learning Loop
+
+1. At session end, a summary model extracts key learnings
+2. Learnings are embedded and stored in the memory system
+3. On next task, relevant memories are retrieved and included in context
+4. The lead can also inject learnings directly into workers
+
+## Project Structure
+
+```
+agent-swarm/
+├── src/
+│   ├── cli.tsx          # CLI entry point (Ink/React)
+│   ├── http/            # Modular HTTP route handlers
+│   │   ├── index.ts     # Handler registry & dispatch
+│   │   ├── tasks.ts     # Task endpoints
+│   │   ├── agents.ts    # Agent endpoints
+│   │   ├── epics.ts     # Epic endpoints
+│   │   ├── schedules.ts # Schedule endpoints
+│   │   ├── core.ts      # Core endpoints (join, poll, progress)
+│   │   ├── config.ts    # Config endpoints
+│   │   ├── memory.ts    # Memory endpoints
+│   │   ├── db-query.ts  # Read-only SQL query endpoint (lead-only)
+│   │   ├── workflows.ts # Workflow CRUD + trigger endpoints
+│   │   └── ...          # Additional route modules
+│   ├── server.ts        # MCP server setup & tool registration
+│   ├── tools/           # MCP tool implementations
+│   ├── heartbeat/       # Lightweight swarm triage module
+│   │   └── heartbeat.ts # 3-tier heartbeat (gate → code triage → escalation)
+│   ├── be/              # Backend (database, business logic)
+│   │   ├── db.ts        # SQLite database
+│   │   └── migrations/  # Database migration system
+│   ├── workflows/      # Workflow automation engine (DAG executor, triggers, nodes)
+│   ├── artifact-sdk/    # Artifact SDK (serve files/apps via localtunnel)
+│   ├── providers/       # AI provider adapters (formatCommand for provider-aware prompts)
+│   │   ├── types.ts     # ProviderAdapter interface
+│   │   ├── claude-adapter.ts  # Claude Code adapter
+│   │   └── pi-mono-adapter.ts # Pi-mono adapter
+│   ├── oauth/           # Generic OAuth module (PKCE, token management)
+│   ├── gitlab/          # GitLab webhook handlers
+│   ├── commands/        # CLI command implementations
+│   │   ├── runner.ts    # Task runner (polls and spawns sessions)
+│   │   ├── worker.ts    # Worker agent command
+│   │   ├── lead.ts      # Lead agent command
+│   │   └── artifact.ts  # Artifact serve/list/stop commands
+│   └── hooks/           # Claude Code hooks
+├── templates/           # Agent templates (official + community)
+├── templates-ui/        # Templates registry (Next.js app)
+├── deploy/              # Deployment scripts
+├── scripts/             # Utility scripts
+├── new-ui/              # Dashboard UI (React + AG Grid)
+├── docker-compose.example.yml
+├── Dockerfile           # API server image
+├── Dockerfile.worker    # Worker image
+└── package.json
+```
+
+## Technology Stack
+
+| Component | Technology |
+|-----------|-----------|
+| Runtime | Bun |
+| API Protocol | MCP (Model Context Protocol) |
+| Database | SQLite (via `bun:sqlite`) |
+| AI Runtime | Claude Code (headless) or pi-mono (via `HARNESS_PROVIDER`) |
+| Containerization | Docker |
+| Process Management | PM2 |
+| Memory Embeddings | OpenAI `text-embedding-3-small` |
+| Dashboard | React + Vite |
+| Schema Validation | Zod |
+
+## Next Steps
+
+- [Agent Identity & Configuration](/docs/architecture/agents) — How agents are personalized and evolve
+- [Hook System](/docs/architecture/hooks) — The six hooks that fire during each session
+- [Memory System](/docs/architecture/memory) — How agents build compounding knowledge
+- [Task Lifecycle](/docs/concepts/task-lifecycle) — How tasks flow through the swarm
+- [Deployment Guide](/docs/guides/deployment) — Production deployment options

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

@@ -0,0 +1,98 @@
+---
+title: Epics
+description: Group related tasks into epics to track multi-step projects, monitor progress, and coordinate work across agents
+---
+
+# Epics
+
+Epics are a way to organize related tasks into larger projects. They provide a high-level view of progress across multiple tasks.
+
+## Creating an Epic
+
+```
+create-epic(
+  name: "auth-system-revamp",
+  goal: "Replace the legacy auth system with JWT-based authentication",
+  description: "Full rewrite of the authentication module...",
+  plan: "## Phase 1\n- Task A\n- Task B\n\n## Phase 2\n..."
+)
+```
+
+## Epic Properties
+
+| Property | Description |
+|----------|-------------|
+| `name` | Unique name for the epic |
+| `goal` | The objective this epic achieves |
+| `description` | Detailed description |
+| `plan` | Implementation plan (markdown) |
+| `prd` | Product Requirements Document (markdown) |
+| `status` | `draft`, `active`, `paused`, `completed`, `cancelled` |
+| `priority` | 0-100 (default: 50) |
+| `tags` | Labels for filtering |
+| `leadAgentId` | Agent responsible for this epic |
+| `planDocPath` | Path to a plan document in the repo |
+| `researchDocPath` | Path to a research document |
+
+## Managing Tasks in Epics
+
+### Assigning Tasks to Epics
+
+When creating a task, associate it with an epic:
+
+```
+send-task(task: "Implement JWT token generation", epicId: "epic-uuid")
+```
+
+Or assign an existing task:
+
+```
+assign-task-to-epic(taskId: "task-uuid", epicName: "auth-system-revamp")
+```
+
+### Removing Tasks from Epics
+
+```
+unassign-task-from-epic(taskId: "task-uuid")
+```
+
+The task is kept but no longer associated with the epic.
+
+## Tracking Progress
+
+Use `get-epic-details` to see progress:
+
+- Total tasks in the epic
+- Tasks by status (completed, in progress, pending, etc.)
+- Overall completion percentage
+
+## GitHub Integration
+
+Epics can be linked to GitHub:
+
+| Property | Description |
+|----------|-------------|
+| `githubRepo` | Repository identifier (e.g., `desplega-ai/agent-swarm`) |
+| `githubMilestone` | GitHub milestone to track progress |
+
+## Slack Integration
+
+Epics can have a dedicated Slack thread:
+
+| Property | Description |
+|----------|-------------|
+| `slackChannelId` | Slack channel for updates |
+| `slackThreadTs` | Thread timestamp for conversation |
+
+## Epic Lifecycle
+
+1. **Draft** — Epic is being planned, tasks are being defined
+2. **Active** — Work is in progress on the epic's tasks
+3. **Paused** — Work is temporarily on hold
+4. **Completed** — All tasks are done, epic goals achieved
+5. **Cancelled** — Epic was abandoned
+
+## Related
+
+- [Task Lifecycle](/docs/concepts/task-lifecycle) — How individual tasks flow through the swarm
+- [MCP Tools Reference](/docs/reference/mcp-tools) — Epic management tools (create-epic, get-epic-details, etc.)

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

@@ -0,0 +1,4 @@
+{
+  "title": "Concepts",
+  "pages": ["task-lifecycle", "epics", "services", "scheduling", "workflows"]
+}

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

@@ -0,0 +1,136 @@
+---
+title: Scheduled Tasks
+description: Automate recurring and one-time tasks with cron-based and delayed scheduling
+---
+
+# Scheduled Tasks
+
+Agent Swarm supports both **recurring** and **one-time** schedules to automate task creation. Recurring schedules create tasks at specified intervals, while one-time schedules run once at a specific time or after a delay, then auto-disable.
+
+## Creating a Recurring Schedule
+
+```
+create-schedule(
+  name: "daily-standup",
+  taskTemplate: "Generate a daily standup report summarizing yesterday's completed tasks",
+  cronExpression: "0 9 * * *",
+  timezone: "America/New_York"
+)
+```
+
+Or use interval-based scheduling:
+
+```
+create-schedule(
+  name: "health-check",
+  taskTemplate: "Check all services are healthy and report any issues",
+  intervalMs: 3600000
+)
+```
+
+## Creating a One-Time Schedule
+
+One-time schedules run once and then auto-disable. Use `delayMs` for a relative delay or `runAt` for an absolute time:
+
+```
+create-schedule(
+  name: "deploy-reminder",
+  scheduleType: "one_time",
+  taskTemplate: "Remind the team about the deployment at 3 PM",
+  delayMs: 1800000
+)
+```
+
+```
+create-schedule(
+  name: "scheduled-report",
+  scheduleType: "one_time",
+  taskTemplate: "Generate the quarterly report",
+  runAt: "2026-03-15T09:00:00Z"
+)
+```
+
+## Schedule Properties
+
+| Property | Description |
+|----------|-------------|
+| `name` | Unique name for the schedule |
+| `taskTemplate` | Task description created each time |
+| `scheduleType` | `recurring` (default) or `one_time` |
+| `cronExpression` | Cron expression for recurring schedules (e.g., `0 9 * * *`) |
+| `intervalMs` | Interval in milliseconds for recurring schedules |
+| `delayMs` | Delay in milliseconds for one-time schedules |
+| `runAt` | ISO datetime for one-time schedules (e.g., `2026-03-15T09:00:00Z`) |
+| `timezone` | Timezone for cron schedules (default: UTC) |
+| `targetAgentId` | Agent to assign tasks to (omit for task pool) |
+| `priority` | Task priority 0-100 (default: 50) |
+| `tags` | Tags applied to created tasks |
+| `taskType` | Type classification for created tasks |
+| `model` | Model for created tasks: `haiku`, `sonnet`, or `opus` (falls back to global config) |
+| `enabled` | Whether the schedule is active (default: true) |
+
+## Managing Schedules
+
+### List Schedules
+
+```
+list-schedules()
+list-schedules(enabled: true)
+list-schedules(name: "daily")
+list-schedules(scheduleType: "one_time")
+```
+
+By default, completed one-time schedules are hidden. Pass `hideCompleted: false` to include them.
+
+### Update a Schedule
+
+```
+update-schedule(name: "daily-standup", cronExpression: "0 10 * * *")
+update-schedule(name: "daily-standup", enabled: false)
+```
+
+### Delete a Schedule
+
+```
+delete-schedule(name: "daily-standup")
+```
+
+### Run Immediately
+
+Trigger a scheduled task now without waiting for the next interval:
+
+```
+run-schedule-now(name: "daily-standup")
+```
+
+This creates a task immediately but does not affect the regular schedule timing.
+
+## Cron Expression Examples
+
+| Expression | Description |
+|-----------|-------------|
+| `0 9 * * *` | Every day at 9:00 AM |
+| `0 9 * * 1-5` | Weekdays at 9:00 AM |
+| `*/30 * * * *` | Every 30 minutes |
+| `0 0 * * 0` | Every Sunday at midnight |
+| `0 9,17 * * *` | At 9 AM and 5 PM daily |
+
+## How Scheduling Works
+
+The MCP server runs a scheduler that polls for due schedules at a configurable interval (default: 10 seconds, set via `SCHEDULER_INTERVAL_MS`).
+
+When a schedule is due:
+1. A new task is created with the schedule's `taskTemplate`
+2. The task is linked back to its schedule via a `scheduleId` field (use the `scheduleId` filter in `get-tasks` to find all tasks from a schedule)
+3. If `targetAgentId` is set, the task is assigned to that agent; otherwise it goes into the unassigned pool
+4. If `model` is set, the task inherits that model setting
+5. The schedule's `lastRunAt` is updated
+6. **One-time schedules** are automatically disabled after execution
+
+Only the schedule creator or the lead agent can update or delete schedules.
+
+## Related
+
+- [Task Lifecycle](/docs/concepts/task-lifecycle) — How scheduled tasks flow through the system after creation
+- [Environment Variables](/docs/reference/environment-variables) — `SCHEDULER_INTERVAL_MS` and other configuration
+- [MCP Tools Reference](/docs/reference/mcp-tools) — Scheduling tools (create-schedule, list-schedules, etc.)

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

@@ -0,0 +1,104 @@
+---
+title: Service Discovery
+description: Register, discover, and health-check HTTP services that agents expose for inter-agent communication
+---
+
+# Service Discovery
+
+Workers can run background HTTP services on port 3000 and register them for discovery by other agents. This enables inter-agent communication beyond the MCP tools.
+
+## How It Works
+
+Each worker container exposes port 3000. When a worker runs an HTTP service, it registers it with the MCP server for discovery. Other agents can then find and communicate with the service.
+
+### Service URL Pattern
+
+```
+https://{agentId}.{SWARM_URL}
+```
+
+The URL is automatically derived from the agent's ID and the swarm's base domain.
+
+## Starting a Service
+
+### 1. Start with PM2
+
+```bash
+pm2 start /workspace/myapp/server.js --name my-api
+```
+
+### 2. Register for Discovery
+
+Use the `register-service` MCP tool:
+
+```
+register-service(
+  script: "/workspace/myapp/server.js",
+  description: "My API service"
+)
+```
+
+### 3. Mark as Healthy
+
+```
+update-service-status(name: "my-api", status: "healthy")
+```
+
+## Finding Services
+
+Other agents can discover services using:
+
+```
+list-services()
+```
+
+Filter by agent or name:
+
+```
+list-services(agentId: "worker-uuid")
+list-services(name: "my-api")
+```
+
+## Health Checks
+
+Services should implement a `/health` endpoint that returns HTTP 200 OK. The swarm monitors service health status.
+
+### Health Statuses
+
+| Status | Description |
+|--------|-------------|
+| `starting` | Service is initializing |
+| `healthy` | Service is running and responding |
+| `unhealthy` | Service is not responding correctly |
+| `stopped` | Service has been stopped |
+
+## PM2 Management
+
+PM2 is the recommended process manager for background services:
+
+```bash
+pm2 start <script> --name <name>    # Start a service
+pm2 stop|restart|delete <name>       # Manage services
+pm2 logs [name]                      # View logs
+pm2 list                             # Show running processes
+```
+
+## Auto-Restart
+
+Registered services are automatically restarted on container restart via `ecosystem.config.js`. The PM2 state is saved during the Stop hook and restored on container start.
+
+## Stopping a Service
+
+```bash
+# 1. Stop locally
+pm2 delete my-api
+
+# 2. Remove from registry
+unregister-service(name: "my-api")
+```
+
+## Related
+
+- [Architecture Overview](/docs/architecture/overview) — How services fit into the swarm architecture
+- [Hook System](/docs/architecture/hooks) — The Stop hook saves PM2 state for auto-restart
+- [MCP Tools Reference](/docs/reference/mcp-tools) — Service discovery tools (register-service, list-services, etc.)