@desplega.ai/agent-swarm 1.9.0 → 1.10.0

package/src/commands/runner.ts

@@ -33,6 +33,8 @@ export interface RunnerConfig {
   defaultPrompt: string;
   /** Metadata type for log files, e.g., "worker_metadata" */
   metadataType: string;
+  /** Optional capabilities of the agent */
+  capabilities?: string[];
 }
 
 export interface RunnerOptions {
@@ -40,7 +42,9 @@ export interface RunnerOptions {
   yolo?: boolean;
   systemPrompt?: string;
   systemPromptFile?: string;
+  logsDir?: string;
   additionalArgs?: string[];
+  aiLoop?: boolean; // Use AI-based loop (old behavior)
 }
 
 interface RunClaudeIterationOptions {
@@ -51,6 +55,118 @@ interface RunClaudeIterationOptions {
   role: string;
 }
 
+/** Trigger types returned by the poll API */
+interface Trigger {
+  type: "task_assigned" | "task_offered" | "unread_mentions" | "pool_tasks_available";
+  taskId?: string;
+  task?: unknown;
+  mentionsCount?: number;
+  count?: number;
+}
+
+/** Options for polling */
+interface PollOptions {
+  apiUrl: string;
+  apiKey: string;
+  agentId: string;
+  pollInterval: number;
+  pollTimeout: number;
+}
+
+/** Register agent via HTTP API */
+async function registerAgent(opts: {
+  apiUrl: string;
+  apiKey: string;
+  agentId: string;
+  name: string;
+  isLead: boolean;
+  capabilities?: string[];
+}): Promise<void> {
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    "X-Agent-ID": opts.agentId,
+  };
+  if (opts.apiKey) {
+    headers.Authorization = `Bearer ${opts.apiKey}`;
+  }
+
+  const response = await fetch(`${opts.apiUrl}/api/agents`, {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      name: opts.name,
+      isLead: opts.isLead,
+      capabilities: opts.capabilities,
+    }),
+  });
+
+  if (!response.ok) {
+    const error = await response.text();
+    throw new Error(`Failed to register agent: ${response.status} ${error}`);
+  }
+}
+
+/** Poll for triggers via HTTP API */
+async function pollForTrigger(opts: PollOptions): Promise<Trigger | null> {
+  const startTime = Date.now();
+  const headers: Record<string, string> = {
+    "X-Agent-ID": opts.agentId,
+  };
+  if (opts.apiKey) {
+    headers.Authorization = `Bearer ${opts.apiKey}`;
+  }
+
+  while (Date.now() - startTime < opts.pollTimeout) {
+    try {
+      const response = await fetch(`${opts.apiUrl}/api/poll`, {
+        method: "GET",
+        headers,
+      });
+
+      if (!response.ok) {
+        console.warn(`[runner] Poll request failed: ${response.status}`);
+        await Bun.sleep(opts.pollInterval);
+        continue;
+      }
+
+      const data = (await response.json()) as { trigger: Trigger | null };
+      if (data.trigger) {
+        return data.trigger;
+      }
+    } catch (error) {
+      console.warn(`[runner] Poll request error: ${error}`);
+    }
+
+    await Bun.sleep(opts.pollInterval);
+  }
+
+  return null; // Timeout reached, no trigger found
+}
+
+/** Build prompt based on trigger type */
+function buildPromptForTrigger(trigger: Trigger, defaultPrompt: string): string {
+  switch (trigger.type) {
+    case "task_assigned":
+      // Use the work-on-task command with task ID
+      return `/work-on-task ${trigger.taskId}`;
+
+    case "task_offered":
+      // Use the review-offered-task command to accept/reject
+      return `/review-offered-task ${trigger.taskId}`;
+
+    case "unread_mentions":
+      // Check messages
+      return "/swarm-chat";
+
+    case "pool_tasks_available":
+      // Let lead review and assign tasks
+      return defaultPrompt;
+
+    default:
+      return defaultPrompt;
+  }
+}
+
 async function runClaudeIteration(opts: RunClaudeIterationOptions): Promise<number> {
   const { role } = opts;
   const CMD = [
@@ -139,7 +255,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   setupShutdownHandlers(role);
 
   const sessionId = process.env.SESSION_ID || crypto.randomUUID().slice(0, 8);
-  const baseLogDir = process.env.LOG_DIR || "/logs";
+  const baseLogDir = opts.logsDir || process.env.LOG_DIR || "/logs";
   const logDir = `${baseLogDir}/${sessionId}`;
 
   await mkdir(logDir, { recursive: true });
@@ -149,10 +265,14 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
 
   // Get agent identity and swarm URL for base prompt
   const agentId = process.env.AGENT_ID || "unknown";
+
+  const apiUrl = process.env.MCP_BASE_URL || "http://localhost:3013";
   const swarmUrl = process.env.SWARM_URL || "localhost";
 
+  const capabilities = config.capabilities;
+
   // Generate base prompt that's always included
-  const basePrompt = getBasePrompt({ role, agentId, swarmUrl });
+  const basePrompt = getBasePrompt({ role, agentId, swarmUrl, capabilities });
 
   // Resolve additional system prompt: CLI flag > env var
   let additionalSystemPrompt: string | undefined;
@@ -189,67 +309,175 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
     : basePrompt;
 
   console.log(`[${role}] Starting ${role}`);
+  console.log(`[${role}] Agent ID: ${agentId}`);
   console.log(`[${role}] Session ID: ${sessionId}`);
   console.log(`[${role}] Log directory: ${logDir}`);
   console.log(`[${role}] YOLO mode: ${isYolo ? "enabled" : "disabled"}`);
   console.log(`[${role}] Prompt: ${prompt}`);
-  console.log(`[${role}] Swarm URL: ${swarmUrl}`);
+  console.log(`[${role}] API URL: ${apiUrl}`);
+  console.log(`[${role}] Swarm URL: ${apiUrl}`);
   console.log(`[${role}] Base prompt: included (${basePrompt.length} chars)`);
   console.log(
     `[${role}] Additional system prompt: ${additionalSystemPrompt ? "provided" : "none"}`,
   );
   console.log(`[${role}] Total system prompt length: ${resolvedSystemPrompt.length} chars`);
 
+  const isAiLoop = opts.aiLoop || process.env.AI_LOOP === "true";
+  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
+
   let iteration = 0;
 
-  while (true) {
-    iteration++;
-    const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const logFile = `${logDir}/${timestamp}.jsonl`;
-
-    console.log(`\n[${role}] === Iteration ${iteration} ===`);
-    console.log(`[${role}] Logging to: ${logFile}`);
-
-    const metadata = {
-      type: metadataType,
-      sessionId,
-      iteration,
-      timestamp: new Date().toISOString(),
-      prompt,
-      yolo: isYolo,
-    };
-    await Bun.write(logFile, `${JSON.stringify(metadata)}\n`);
-
-    const exitCode = await runClaudeIteration({
-      prompt,
-      logFile,
-      systemPrompt: resolvedSystemPrompt,
-      additionalArgs: opts.additionalArgs,
-      role,
-    });
-
-    if (exitCode !== 0) {
-      const errorLog = {
-        timestamp: new Date().toISOString(),
+  if (!isAiLoop) {
+    // NEW: Runner-level polling mode
+    console.log(`[${role}] Mode: runner-level polling (use --ai-loop for AI-based polling)`);
+
+    // Register agent before starting
+    const agentName = process.env.AGENT_NAME || `${role}-${agentId.slice(0, 8)}`;
+    try {
+      await registerAgent({
+        apiUrl,
+        apiKey,
+        agentId,
+        name: agentName,
+        isLead: role === "lead",
+        capabilities: config.capabilities,
+      });
+      console.log(`[${role}] Registered as "${agentName}" (ID: ${agentId})`);
+    } catch (error) {
+      console.error(`[${role}] Failed to register: ${error}`);
+      process.exit(1);
+    }
+
+    while (true) {
+      console.log(`\n[${role}] Polling for triggers...`);
+
+      const trigger = await pollForTrigger({
+        apiUrl,
+        apiKey,
+        agentId,
+        pollInterval: POLL_INTERVAL_MS,
+        pollTimeout: POLL_TIMEOUT_MS,
+      });
+
+      if (!trigger) {
+        console.log(`[${role}] No trigger found, polling again...`);
+        continue;
+      }
+
+      console.log(`[${role}] Trigger received: ${trigger.type}`);
+
+      // Build prompt based on trigger
+      const triggerPrompt = buildPromptForTrigger(trigger, prompt);
+
+      iteration++;
+      const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+      const logFile = `${logDir}/${timestamp}.jsonl`;
+
+      console.log(`\n[${role}] === Iteration ${iteration} ===`);
+      console.log(`[${role}] Logging to: ${logFile}`);
+      console.log(`[${role}] Prompt: ${triggerPrompt}`);
+
+      const metadata = {
+        type: metadataType,
+        sessionId,
         iteration,
-        exitCode,
-        error: true,
+        timestamp: new Date().toISOString(),
+        prompt: triggerPrompt,
+        trigger: trigger.type,
+        yolo: isYolo,
       };
+      await Bun.write(logFile, `${JSON.stringify(metadata)}\n`);
+
+      const exitCode = await runClaudeIteration({
+        prompt: triggerPrompt,
+        logFile,
+        systemPrompt: resolvedSystemPrompt,
+        additionalArgs: opts.additionalArgs,
+        role,
+      });
+
+      if (exitCode !== 0) {
+        const errorLog = {
+          timestamp: new Date().toISOString(),
+          iteration,
+          exitCode,
+          trigger: trigger.type,
+          error: true,
+        };
+
+        const errorsFile = `${logDir}/errors.jsonl`;
+        const errorsFileRef = Bun.file(errorsFile);
+        const existingErrors = (await errorsFileRef.exists()) ? await errorsFileRef.text() : "";
+        await Bun.write(errorsFile, `${existingErrors}${JSON.stringify(errorLog)}\n`);
+
+        if (!isYolo) {
+          console.error(`[${role}] Claude exited with code ${exitCode}. Stopping.`);
+          console.error(`[${role}] Error logged to: ${errorsFile}`);
+          process.exit(exitCode);
+        }
 
-      const errorsFile = `${logDir}/errors.jsonl`;
-      const errorsFileRef = Bun.file(errorsFile);
-      const existingErrors = (await errorsFileRef.exists()) ? await errorsFileRef.text() : "";
-      await Bun.write(errorsFile, `${existingErrors}${JSON.stringify(errorLog)}\n`);
-
-      if (!isYolo) {
-        console.error(`[${role}] Claude exited with code ${exitCode}. Stopping.`);
-        console.error(`[${role}] Error logged to: ${errorsFile}`);
-        process.exit(exitCode);
+        console.warn(`[${role}] Claude exited with code ${exitCode}. YOLO mode - continuing...`);
       }
 
-      console.warn(`[${role}] Claude exited with code ${exitCode}. YOLO mode - continuing...`);
+      console.log(`[${role}] Iteration ${iteration} complete. Polling for next trigger...`);
     }
+  } else {
+    // Original AI-loop mode (existing behavior)
+    console.log(`[${role}] Mode: AI-based polling (legacy)`);
+
+    while (true) {
+      iteration++;
+      const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+      const logFile = `${logDir}/${timestamp}.jsonl`;
+
+      console.log(`\n[${role}] === Iteration ${iteration} ===`);
+      console.log(`[${role}] Logging to: ${logFile}`);
 
-    console.log(`[${role}] Iteration ${iteration} complete. Starting next iteration...`);
+      const metadata = {
+        type: metadataType,
+        sessionId,
+        iteration,
+        timestamp: new Date().toISOString(),
+        prompt,
+        yolo: isYolo,
+      };
+      await Bun.write(logFile, `${JSON.stringify(metadata)}\n`);
+
+      const exitCode = await runClaudeIteration({
+        prompt,
+        logFile,
+        systemPrompt: resolvedSystemPrompt,
+        additionalArgs: opts.additionalArgs,
+        role,
+      });
+
+      if (exitCode !== 0) {
+        const errorLog = {
+          timestamp: new Date().toISOString(),
+          iteration,
+          exitCode,
+          error: true,
+        };
+
+        const errorsFile = `${logDir}/errors.jsonl`;
+        const errorsFileRef = Bun.file(errorsFile);
+        const existingErrors = (await errorsFileRef.exists()) ? await errorsFileRef.text() : "";
+        await Bun.write(errorsFile, `${existingErrors}${JSON.stringify(errorLog)}\n`);
+
+        if (!isYolo) {
+          console.error(`[${role}] Claude exited with code ${exitCode}. Stopping.`);
+          console.error(`[${role}] Error logged to: ${errorsFile}`);
+          process.exit(exitCode);
+        }
+
+        console.warn(`[${role}] Claude exited with code ${exitCode}. YOLO mode - continuing...`);
+      }
+
+      console.log(`[${role}] Iteration ${iteration} complete. Starting next iteration...`);
+    }
   }
 }

package/src/commands/worker.ts

@@ -1,3 +1,4 @@
+import { getEnabledCapabilities } from "@/server.ts";
 import { type RunnerConfig, type RunnerOptions, runAgent } from "./runner.ts";
 
 export type WorkerOptions = RunnerOptions;
@@ -6,6 +7,7 @@ const workerConfig: RunnerConfig = {
   role: "worker",
   defaultPrompt: "/start-worker",
   metadataType: "worker_metadata",
+  capabilities: getEnabledCapabilities(),
 };
 
 export async function runWorker(opts: WorkerOptions) {

package/src/http.ts

@@ -10,6 +10,7 @@ import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import { createServer } from "@/server";
 import {
   closeDb,
+  createAgent,
   getAgentById,
   getAgentWithTasks,
   getAllAgents,
@@ -24,8 +25,11 @@ import {
   getInboxSummary,
   getLogsByAgentId,
   getLogsByTaskId,
+  getOfferedTasksForAgent,
+  getPendingTaskForAgent,
   getServicesByAgentId,
   getTaskById,
+  getUnassignedTasksCount,
   postMessage,
   updateAgentStatus,
 } from "./be/db";
@@ -209,6 +213,147 @@ const httpServer = createHttpServer(async (req, res) => {
     return;
   }
 
+  // ============================================================================
+  // Runner-Level Polling Endpoints
+  // ============================================================================
+
+  const pathSegments = getPathSegments(req.url || "");
+
+  // POST /api/agents - Register a new agent (or return existing if already registered)
+  if (
+    req.method === "POST" &&
+    pathSegments[0] === "api" &&
+    pathSegments[1] === "agents" &&
+    !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.name || typeof body.name !== "string") {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing or invalid 'name' field" }));
+      return;
+    }
+
+    // Use X-Agent-ID header if provided, otherwise generate new UUID
+    const agentId = myAgentId || crypto.randomUUID();
+
+    // Use transaction to ensure atomicity of check-and-create/update
+    const result = getDb().transaction(() => {
+      // Check if agent already exists
+      const existingAgent = getAgentById(agentId);
+      if (existingAgent) {
+        // Update status to idle if offline
+        if (existingAgent.status === "offline") {
+          updateAgentStatus(existingAgent.id, "idle");
+        }
+        return { agent: getAgentById(agentId), created: false };
+      }
+
+      // Create new agent
+      const agent = createAgent({
+        id: agentId,
+        name: body.name,
+        isLead: body.isLead ?? false,
+        status: "idle",
+        description: body.description,
+        role: body.role,
+        capabilities: body.capabilities,
+      });
+
+      return { agent, created: true };
+    })();
+
+    res.writeHead(result.created ? 201 : 200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(result.agent));
+    return;
+  }
+
+  // GET /api/poll - Poll for triggers (tasks, mentions, etc.)
+  if (req.method === "GET" && pathSegments[0] === "api" && pathSegments[1] === "poll") {
+    if (!myAgentId) {
+      res.writeHead(400, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: "Missing X-Agent-ID header" }));
+      return;
+    }
+
+    // Use transaction for consistent reads across all trigger checks
+    const result = getDb().transaction(() => {
+      const agent = getAgentById(myAgentId);
+      if (!agent) {
+        return { error: "Agent not found", status: 404 };
+      }
+
+      // Check for offered tasks first (highest priority)
+      const offeredTasks = getOfferedTasksForAgent(myAgentId);
+      const firstOfferedTask = offeredTasks[0];
+      if (firstOfferedTask) {
+        return {
+          trigger: {
+            type: "task_offered",
+            taskId: firstOfferedTask.id,
+            task: firstOfferedTask,
+          },
+        };
+      }
+
+      // Check for pending tasks (assigned directly to this agent)
+      const pendingTask = getPendingTaskForAgent(myAgentId);
+      if (pendingTask) {
+        return {
+          trigger: {
+            type: "task_assigned",
+            taskId: pendingTask.id,
+            task: pendingTask,
+          },
+        };
+      }
+
+      // For lead agents, check for unread mentions
+      if (agent.isLead) {
+        const inbox = getInboxSummary(myAgentId);
+        if (inbox.mentionsCount > 0) {
+          return {
+            trigger: {
+              type: "unread_mentions",
+              mentionsCount: inbox.mentionsCount,
+            },
+          };
+        }
+
+        // Check for tasks needing assignment (unassigned tasks in pool)
+        const unassignedCount = getUnassignedTasksCount();
+        if (unassignedCount > 0) {
+          return {
+            trigger: {
+              type: "pool_tasks_available",
+              count: unassignedCount,
+            },
+          };
+        }
+      }
+
+      // No trigger found
+      return { trigger: null };
+    })();
+
+    // Handle error case
+    if ("error" in result) {
+      res.writeHead(result.status ?? 500, { "Content-Type": "application/json" });
+      res.end(JSON.stringify({ error: result.error }));
+      return;
+    }
+
+    res.writeHead(200, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(result));
+    return;
+  }
+
   // GET /ecosystem - Generate PM2 ecosystem config for agent's services
   if (req.method === "GET" && req.url === "/ecosystem") {
     if (!myAgentId) {
@@ -249,7 +394,6 @@ const httpServer = createHttpServer(async (req, res) => {
   // REST API Endpoints (for frontend dashboard)
   // ============================================================================
 
-  const pathSegments = getPathSegments(req.url || "");
   const queryParams = parseQueryParams(req.url || "");
 
   // GET /api/agents - List all agents (optionally with tasks)

package/src/prompts/base-prompt.ts

@@ -38,9 +38,9 @@ As a worker agent of the swarm, you are responsible for executing tasks assigned
 #### Useful tools for workers
 
 - poll-task: Automatically waits for new tasks assigned by the lead or claimed from the unassigned pool.
-- read-messages: To read messages sent to you by the lead or other workers, by default when a task is found, it will auto-assign it to you.
 - store-progress: Critical tool to save your work and progress on tasks!
 - task-action: Manage tasks with different actions like claim, release, accept, reject, and complete.
+- read-messages: If communications enabled, use it to read messages sent to you by the lead or other workers, by default when a task is found, it will auto-assign it to you.
 `;
 
 const BASE_PROMPT_FILESYSTEM = `
@@ -57,8 +57,7 @@ const BASE_PROMPT_FILESYSTEM = `
 const BASE_PROMPT_GUIDELINES = `
 ### Agent Swarm Operational Guidelines
 
-- Communication: Use the /swarm-chat command to communicate with other agents and the human operator. Keep everyone informed of your progress and any issues you encounter. It will allow you to see the internal Slack-like communication platform to: create and view channels (or DMs), read messages, and post messages.
--
+- Follow the communicationes ettiquette and protocols established for the swarm. If not stated, do not use the chat features, focus on your tasks.
 `;
 
 const BASE_PROMPT_SYSTEM = `
@@ -67,7 +66,9 @@ const BASE_PROMPT_SYSTEM = `
 You have a full Ubuntu environment with some packages pre-installed: node, bun, python3, curl, wget, git, gh, jq, etc.
 
 If you need to install additional packages, use "sudo apt-get install {package_name}".
+`;
 
+const BASE_PROMPT_SERVICES = `
 ### External Swarm Access & Service Registry
 
 Port 3000 is exposed for web apps or APIs. Use PM2 for robust process management:
@@ -108,6 +109,7 @@ export type BasePromptArgs = {
   role: string;
   agentId: string;
   swarmUrl: string;
+  capabilities?: string[];
 };
 
 export const getBasePrompt = (args: BasePromptArgs): string => {
@@ -127,5 +129,17 @@ export const getBasePrompt = (args: BasePromptArgs): string => {
   prompt += BASE_PROMPT_GUIDELINES;
   prompt += BASE_PROMPT_SYSTEM.replace("{swarmUrl}", swarmUrl);
 
+  if (!args.capabilities || args.capabilities.includes("services")) {
+    prompt += BASE_PROMPT_SERVICES;
+  }
+
+  if (args.capabilities) {
+    prompt += `
+### Capabilities enabled for this agent:
+
+- ${args.capabilities.join("\n- ")}
+`;
+  }
+
   return prompt;
 };