@desplega.ai/agent-swarm 1.10.3 → 1.10.8

package/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  lint-and-typecheck:
+    name: Lint and Type Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run Biome linter
+        run: bun run lint
+
+      - name: Run TypeScript type check
+        run: bun run tsc:check
+
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run tests
+        run: bun test
+
+  docker-build:
+    name: Docker Build Test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+
+    strategy:
+      matrix:
+        dockerfile: [Dockerfile, Dockerfile.worker]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./${{ matrix.dockerfile }}
+          push: false
+          tags: test-image:latest

package/.github/workflows/{docker-publish.yml → docker-and-deploy.yml}

@@ -1,4 +1,4 @@
-name: Docker Build and Publish
+name: Docker Build + Publish + Deploy
 
 on:
   push:
@@ -50,6 +50,7 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          no-cache: true
 
   build-and-push-worker:
     runs-on: ubuntu-latest
@@ -90,3 +91,27 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          no-cache: true
+
+  # deploy:
+  #   name: Deploy
+  #   runs-on: ubuntu-latest
+  #
+  #   needs:
+  #     - build-and-push-server
+  #     - build-and-push-worker
+  #
+  #   steps:
+  #     - name: Checkout
+  #       id: checkout
+  #       uses: actions/checkout@v4
+  #
+  #     - name: Deploy Agent Swarm
+  #       uses: tarasyarema/dokploy-deploy-action@main
+  #       with:
+  #         application_id: h4or-knfw2HWkTzjLmrn8
+  #         application_name: agent-swarm-nrz8v0
+  #         dokploy_url: https://app.dokploy.com
+  #         auth_token: ${{ secrets.DOKPLOY_TOKEN }}
+  #         wait_for_completion: true
+  #         restart: true

package/Dockerfile

@@ -35,10 +35,13 @@ RUN chmod +x /usr/local/bin/agent-swarm-api
 # Copy package.json for version info
 COPY package.json ./
 
-# Database will be created in /app (mount /app for persistence)
-VOLUME /app
+# Create data directory for SQLite (WAL mode needs .sqlite, .sqlite-wal, .sqlite-shm on same filesystem)
+RUN mkdir -p /app/data
 
 ENV PORT=3013
+ENV DATABASE_PATH=/app/data/agent-swarm-db.sqlite
+
+VOLUME /app/data
 
 EXPOSE 3013
 
@@ -49,6 +52,6 @@ HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
 # Print version on startup and run the server
 CMD echo "=== Agent Swarm API v$(cat /app/package.json | grep '\"version\"' | cut -d'"' -f4) ===" && \
     echo "Port: $PORT" && \
-    echo "Database: /app/agent-swarm-db.sqlite" && \
+    echo "Database: $DATABASE_PATH" && \
     echo "==============================" && \
     exec /usr/local/bin/agent-swarm-api

package/README.md

@@ -4,6 +4,14 @@
   <img src="assets/agent-swarm.png" alt="Agent Swarm" width="800">
 </p>
 
+https://github.com/user-attachments/assets/bd308567-d21e-44a5-87ec-d25aeb1de3d3
+
+<p align="center">
+  <a href="https://discord.gg/3XtmPdXm">
+    <img src="https://img.shields.io/badge/Discord-Join%20Community-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Join Discord">
+  </a>
+</p>
+
 > Agent orchestration layer MCP for Claude Code, Codex, Gemini CLI, and more!
 
 ## Table of Contents

package/biome.json

@@ -17,7 +17,10 @@
 	"linter": {
 		"enabled": true,
 		"rules": {
-			"recommended": true
+			"recommended": true,
+      "style": {
+        "noNonNullAssertion": "off"
+      }
 		}
 	},
 	"javascript": {

package/deploy/prod-db.ts

@@ -3,7 +3,7 @@
 import { $ } from "bun";
 import * as readline from "node:readline";
 
-const DB_PATH = "/var/lib/docker/volumes/agent-swarm-nrz8v0_swarm_api/_data/agent-swarm-db.sqlite";
+const DB_PATH = "/var/lib/docker/volumes/agent-swarm-nrz8v0_swarm_db/_data/agent-swarm-db.sqlite";
 const SSH_HOST = process.argv[2] || "swarm";
 
 console.log(`Connected to ${SSH_HOST}:${DB_PATH}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.10.3",
+  "version": "1.10.8",
   "description": "Agent orchestration layer MCP for Claude Code, Codex, Gemini CLI, and more!",
   "license": "MIT",
   "author": "desplega.ai <contact@desplega.ai>",
@@ -61,7 +61,7 @@
     "docs:mcp": "bun scripts/generate-mcp-docs.ts"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.9",
+    "@biomejs/biome": "^2.3.10",
     "@types/bun": "latest"
   },
   "peerDependencies": {

package/pyproject.toml

@@ -0,0 +1,9 @@
+# Minimal pyproject.toml to satisfy GitHub Actions setup-python cache requirement
+# This file is a workaround for: https://github.com/actions/setup-python/issues/XXX
+# The dokploy-deploy-action uses setup-python with pip caching, which requires
+# a pyproject.toml or requirements.txt even though this is a Node.js/TypeScript project.
+
+[project]
+name = "agent-swarm-deploy-workaround"
+version = "0.0.0"
+description = "Workaround file for GitHub Actions deployment"

package/src/be/db.ts

@@ -24,6 +24,8 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
   }
 
   db = new Database(dbPath, { create: true });
+  console.log(`Database initialized at ${dbPath}`);
+
   db.run("PRAGMA journal_mode = WAL;");
   db.run("PRAGMA foreign_keys = ON;");
 
@@ -333,9 +335,9 @@ export function initDb(dbPath = "./agent-swarm-db.sqlite"): Database {
   return db;
 }
 
-export function getDb(): Database {
+export function getDb(path?: string): Database {
   if (!db) {
-    return initDb();
+    return initDb(path ?? process.env.DATABASE_PATH);
   }
   return db;
 }
@@ -728,6 +730,34 @@ export function getCompletedSlackTasks(): AgentTask[] {
     .map(rowToAgentTask);
 }
 
+/**
+ * Get tasks that were recently finished (completed/failed) by workers (non-lead agents).
+ * Used by leads to know when workers complete tasks.
+ */
+export function getRecentlyFinishedWorkerTasks(since?: string): AgentTask[] {
+  const query = since
+    ? `SELECT t.* FROM agent_tasks t
+       LEFT JOIN agents a ON t.agentId = a.id
+       WHERE t.status IN ('completed', 'failed')
+       AND t.finishedAt > ?
+       AND (a.isLead = 0 OR a.isLead IS NULL)
+       ORDER BY t.finishedAt DESC
+       LIMIT 50`
+    : `SELECT t.* FROM agent_tasks t
+       LEFT JOIN agents a ON t.agentId = a.id
+       WHERE t.status IN ('completed', 'failed')
+       AND t.finishedAt IS NOT NULL
+       AND (a.isLead = 0 OR a.isLead IS NULL)
+       ORDER BY t.finishedAt DESC
+       LIMIT 10`;
+
+  if (since) {
+    return getDb().prepare<AgentTaskRow, [string]>(query).all(since).map(rowToAgentTask);
+  }
+
+  return getDb().prepare<AgentTaskRow, []>(query).all().map(rowToAgentTask);
+}
+
 export function getInProgressSlackTasks(): AgentTask[] {
   return getDb()
     .prepare<AgentTaskRow, []>(

package/src/claude.ts

@@ -7,23 +7,23 @@ type RunCladeOptions = {
 };
 
 export const runClaude = async (opts: RunCladeOptions) => {
-  const CMD = ["claude"];
+  const Cmd = ["claude"];
 
   if (opts.headless) {
-    CMD.push("--verbose");
-    CMD.push("--output-format");
-    CMD.push("stream-json");
-    CMD.push("-p");
-    CMD.push(opts.msg);
+    Cmd.push("--verbose");
+    Cmd.push("--output-format");
+    Cmd.push("stream-json");
+    Cmd.push("-p");
+    Cmd.push(opts.msg);
   }
 
   if (opts.additionalArgs && opts.additionalArgs.length > 0) {
-    CMD.push(...opts.additionalArgs);
+    Cmd.push(...opts.additionalArgs);
   }
 
   console.debug(`[debug] Running in ${opts.headless ? "headless" : "normal"} mode`);
 
-  const proc = Bun.spawn(CMD, {
+  const proc = Bun.spawn(Cmd, {
     env: process.env,
     stdout: opts.headless ? "pipe" : "inherit",
     stdin: opts.headless ? undefined : "inherit",

package/src/commands/runner.ts

@@ -13,10 +13,60 @@ async function savePm2State(role: string): Promise<void> {
   }
 }
 
+/** API configuration for ping/close */
+interface ApiConfig {
+  apiUrl: string;
+  apiKey: string;
+  agentId: string;
+}
+
+/** Ping the server to indicate activity and update status */
+async function pingServer(config: ApiConfig, _role: string): Promise<void> {
+  const headers: Record<string, string> = {
+    "X-Agent-ID": config.agentId,
+  };
+  if (config.apiKey) {
+    headers.Authorization = `Bearer ${config.apiKey}`;
+  }
+
+  try {
+    await fetch(`${config.apiUrl}/ping`, {
+      method: "POST",
+      headers,
+    });
+  } catch {
+    // Silently fail - server might not be running
+  }
+}
+
+/** Mark agent as offline on shutdown */
+async function closeAgent(config: ApiConfig, role: string): Promise<void> {
+  const headers: Record<string, string> = {
+    "X-Agent-ID": config.agentId,
+  };
+  if (config.apiKey) {
+    headers.Authorization = `Bearer ${config.apiKey}`;
+  }
+
+  try {
+    console.log(`[${role}] Marking agent as offline...`);
+    await fetch(`${config.apiUrl}/close`, {
+      method: "POST",
+      headers,
+    });
+    console.log(`[${role}] Agent marked as offline`);
+  } catch {
+    // Silently fail - server might not be running
+  }
+}
+
 /** Setup signal handlers for graceful shutdown */
-function setupShutdownHandlers(role: string): void {
+function setupShutdownHandlers(role: string, apiConfig?: ApiConfig): void {
   const shutdown = async (signal: string) => {
     console.log(`\n[${role}] Received ${signal}, shutting down...`);
+    if (apiConfig) {
+      await closeAgent(apiConfig, role);
+    }
     await savePm2State(role);
     process.exit(0);
   };
@@ -122,11 +172,22 @@ async function flushLogBuffer(
 
 /** Trigger types returned by the poll API */
 interface Trigger {
-  type: "task_assigned" | "task_offered" | "unread_mentions" | "pool_tasks_available";
+  type:
+    | "task_assigned"
+    | "task_offered"
+    | "unread_mentions"
+    | "pool_tasks_available"
+    | "tasks_finished";
   taskId?: string;
   task?: unknown;
   mentionsCount?: number;
   count?: number;
+  tasks?: Array<{
+    id: string;
+    agentId?: string;
+    task: string;
+    status: string;
+  }>;
 }
 
 /** Options for polling */
@@ -136,6 +197,7 @@ interface PollOptions {
   agentId: string;
   pollInterval: number;
   pollTimeout: number;
+  since?: string; // Optional: for filtering finished tasks
 }
 
 /** Register agent via HTTP API */
@@ -183,7 +245,13 @@ async function pollForTrigger(opts: PollOptions): Promise<Trigger | null> {
 
   while (Date.now() - startTime < opts.pollTimeout) {
     try {
-      const response = await fetch(`${opts.apiUrl}/api/poll`, {
+      // Build URL with optional since parameter
+      let url = `${opts.apiUrl}/api/poll`;
+      if (opts.since) {
+        url += `?since=${encodeURIComponent(opts.since)}`;
+      }
+
+      const response = await fetch(url, {
         method: "GET",
         headers,
       });
@@ -224,8 +292,23 @@ function buildPromptForTrigger(trigger: Trigger, defaultPrompt: string): string
       return "/swarm-chat";
 
     case "pool_tasks_available":
-      // Let lead review and assign tasks
-      return defaultPrompt;
+      // Worker: claim a task from the pool
+      // Include the count so worker knows there are tasks available
+      return `There are ${trigger.count} unassigned task(s) available in the pool. Use get-tasks with unassigned: true to see them, then use task-action with action: "claim" to claim one. The claim is first-come-first-serve, so if your claim fails, try another task.`;
+
+    case "tasks_finished":
+      // Lead: simple notification about finished tasks
+      if (trigger.tasks && Array.isArray(trigger.tasks) && trigger.tasks.length > 0) {
+        const taskSummaries = trigger.tasks
+          .map((t) => {
+            const status = t.status === "completed" ? "completed" : "failed";
+            const agentName = t.agentId ? `Agent ${t.agentId.slice(0, 8)}` : "Unknown agent";
+            return `- ${agentName} ${status} task "${t.task?.slice(0, 50)}..." (ID: ${t.id})`;
+          })
+          .join("\n");
+        return `Workers have finished ${trigger.count} task(s):\n${taskSummaries}\n\nReview these results and decide if any follow-up actions are needed.`;
+      }
+      return `Workers have finished ${trigger.count} task(s). Use get-tasks with status "completed" or "failed" to review them.`;
 
     default:
       return defaultPrompt;
@@ -234,7 +317,7 @@ function buildPromptForTrigger(trigger: Trigger, defaultPrompt: string): string
 
 async function runClaudeIteration(opts: RunClaudeIterationOptions): Promise<number> {
   const { role } = opts;
-  const CMD = [
+  const Cmd = [
     "claude",
     "--verbose",
     "--output-format",
@@ -248,11 +331,11 @@ async function runClaudeIteration(opts: RunClaudeIterationOptions): Promise<numb
   ];
 
   if (opts.additionalArgs && opts.additionalArgs.length > 0) {
-    CMD.push(...opts.additionalArgs);
+    Cmd.push(...opts.additionalArgs);
   }
 
   if (opts.systemPrompt) {
-    CMD.push("--append-system-prompt", opts.systemPrompt);
+    Cmd.push("--append-system-prompt", opts.systemPrompt);
   }
 
   console.log(`\x1b[2m[${role}]\x1b[0m \x1b[36m▸\x1b[0m Starting Claude (PID will follow)`);
@@ -260,7 +343,7 @@ async function runClaudeIteration(opts: RunClaudeIterationOptions): Promise<numb
   const logFileHandle = Bun.file(opts.logFile).writer();
   let stderrOutput = "";
 
-  const proc = Bun.spawn(CMD, {
+  const proc = Bun.spawn(Cmd, {
     env: process.env,
     stdout: "pipe",
     stderr: "pipe",
@@ -355,9 +438,6 @@ async function runClaudeIteration(opts: RunClaudeIterationOptions): Promise<numb
 export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   const { role, defaultPrompt, metadataType } = config;
 
-  // Setup graceful shutdown handlers (saves PM2 state on Ctrl+C)
-  setupShutdownHandlers(role);
-
   const sessionId = process.env.SESSION_ID || crypto.randomUUID().slice(0, 8);
   const baseLogDir = opts.logsDir || process.env.LOG_DIR || "/logs";
   const logDir = `${baseLogDir}/${sessionId}`;
@@ -430,8 +510,8 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   const apiKey = process.env.API_KEY || "";
 
   // Constants for polling
-  const POLL_INTERVAL_MS = 2000; // 2 seconds between polls
-  const POLL_TIMEOUT_MS = 60000; // 1 minute timeout before retrying
+  const PollIntervalMs = 2000; // 2 seconds between polls
+  const PollTimeoutMs = 60000; // 1 minute timeout before retrying
 
   let iteration = 0;
 
@@ -439,6 +519,12 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
     // NEW: Runner-level polling mode
     console.log(`[${role}] Mode: runner-level polling (use --ai-loop for AI-based polling)`);
 
+    // Create API config for ping/close
+    const apiConfig: ApiConfig = { apiUrl, apiKey, agentId };
+
+    // Setup graceful shutdown handlers with API config for close on exit
+    setupShutdownHandlers(role, apiConfig);
+
     // Register agent before starting
     const agentName = process.env.AGENT_NAME || `${role}-${agentId.slice(0, 8)}`;
     try {
@@ -456,15 +542,22 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
       process.exit(1);
     }
 
+    // Track last finished task check for leads (to avoid re-processing)
+    let lastFinishedTaskCheck: string | undefined;
+
     while (true) {
+      // Ping server on each iteration to keep status updated
+      await pingServer(apiConfig, role);
+
       console.log(`\n[${role}] Polling for triggers...`);
 
       const trigger = await pollForTrigger({
         apiUrl,
         apiKey,
         agentId,
-        pollInterval: POLL_INTERVAL_MS,
-        pollTimeout: POLL_TIMEOUT_MS,
+        pollInterval: PollIntervalMs,
+        pollTimeout: PollTimeoutMs,
+        since: lastFinishedTaskCheck,
       });
 
       if (!trigger) {
@@ -472,6 +565,11 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
         continue;
       }
 
+      // After getting a tasks_finished trigger, update the timestamp
+      if (trigger.type === "tasks_finished") {
+        lastFinishedTaskCheck = new Date().toISOString();
+      }
+
       console.log(`[${role}] Trigger received: ${trigger.type}`);
 
       // Build prompt based on trigger
@@ -540,7 +638,16 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
     // Original AI-loop mode (existing behavior)
     console.log(`[${role}] Mode: AI-based polling (legacy)`);
 
+    // Create API config for ping/close
+    const apiConfig: ApiConfig = { apiUrl, apiKey, agentId };
+
+    // Setup graceful shutdown handlers with API config for close on exit
+    setupShutdownHandlers(role, apiConfig);
+
     while (true) {
+      // Ping server on each iteration to keep status updated
+      await pingServer(apiConfig, role);
+
       iteration++;
       const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
       const logFile = `${logDir}/${timestamp}.jsonl`;

package/src/http.ts

@@ -12,6 +12,7 @@ import {
   closeDb,
   createAgent,
   createSessionLogs,
+  createTaskExtended,
   getAgentById,
   getAgentWithTasks,
   getAllAgents,
@@ -28,6 +29,7 @@ import {
   getLogsByTaskId,
   getOfferedTasksForAgent,
   getPendingTaskForAgent,
+  getRecentlyFinishedWorkerTasks,
   getServicesByAgentId,
   getSessionLogsByTaskId,
   getTaskById,
@@ -284,6 +286,10 @@ const httpServer = createHttpServer(async (req, res) => {
       return;
     }
 
+    // Get optional 'since' parameter for finished tasks
+    const queryParams = parseQueryParams(req.url || "");
+    const since = queryParams.get("since") || undefined;
+
     // Use transaction for consistent reads across all trigger checks
     const result = getDb().transaction(() => {
       const agent = getAgentById(myAgentId);
@@ -291,7 +297,7 @@ const httpServer = createHttpServer(async (req, res) => {
         return { error: "Agent not found", status: 404 };
       }
 
-      // Check for offered tasks first (highest priority)
+      // Check for offered tasks first (highest priority for both workers and leads)
       const offeredTasks = getOfferedTasksForAgent(myAgentId);
       const firstOfferedTask = offeredTasks[0];
       if (firstOfferedTask) {
@@ -316,8 +322,10 @@ const httpServer = createHttpServer(async (req, res) => {
         };
       }
 
-      // For lead agents, check for unread mentions
       if (agent.isLead) {
+        // === LEAD-SPECIFIC TRIGGERS ===
+
+        // Check for unread mentions
         const inbox = getInboxSummary(myAgentId);
         if (inbox.mentionsCount > 0) {
           return {
@@ -328,7 +336,21 @@ const httpServer = createHttpServer(async (req, res) => {
           };
         }
 
-        // Check for tasks needing assignment (unassigned tasks in pool)
+        // Check for recently finished worker tasks
+        const finishedTasks = getRecentlyFinishedWorkerTasks(since);
+        if (finishedTasks.length > 0) {
+          return {
+            trigger: {
+              type: "tasks_finished",
+              count: finishedTasks.length,
+              tasks: finishedTasks,
+            },
+          };
+        }
+      } else {
+        // === WORKER-SPECIFIC TRIGGERS ===
+
+        // Check for unassigned tasks in pool (workers can claim)
         const unassignedCount = getUnassignedTasksCount();
         if (unassignedCount > 0) {
           return {
@@ -524,6 +546,50 @@ const httpServer = createHttpServer(async (req, res) => {
     return;
   }
 
+  // POST /api/tasks - Create a new task
+  if (
+    req.method === "POST" &&
+    pathSegments[0] === "api" &&
+    pathSegments[1] === "tasks" &&
+    !pathSegments[2]
+  ) {
+    // Parse request body
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) {
+      chunks.push(chunk);
+    }
+    const body = JSON.parse(Buffer.concat(chunks).toString());
+
+    // Validate required fields
+    if (!body.task || typeof body.task !== "string") {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing or invalid 'task' field" }));
+      return;
+    }
+
+    try {
+      // Create task with provided options
+      const task = createTaskExtended(body.task, {
+        agentId: body.agentId || undefined,
+        creatorAgentId: myAgentId || undefined,
+        taskType: body.taskType || undefined,
+        tags: body.tags || undefined,
+        priority: body.priority || 50,
+        dependsOn: body.dependsOn || undefined,
+        offeredTo: body.offeredTo || undefined,
+        source: body.source || "api",
+      });
+
+      res.writeHead(201, { "Content-Type": "application/json" });
+      res.end(JSON.stringify(task));
+    } catch (error) {
+      console.error("[HTTP] Failed to create task:", error);
+      res.writeHead(500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Failed to create task" }));
+    }
+    return;
+  }
+
   // GET /api/tasks/:id - Get single task with logs
   if (
     req.method === "GET" &&

package/src/server.ts

@@ -41,7 +41,8 @@ export function getEnabledCapabilities(): string[] {
 
 export function createServer() {
   // Initialize database with WAL mode
-  initDb();
+  // Uses DATABASE_PATH env var for Docker volume compatibility (WAL needs .sqlite, .sqlite-wal, .sqlite-shm on same filesystem)
+  initDb(process.env.DATABASE_PATH);
 
   const server = new McpServer(
     {