@desplega.ai/agent-swarm 1.49.0 → 1.52.0

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

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

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

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

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

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

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

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

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

@@ -1,104 +0,0 @@
----
-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.)