@desplega.ai/agent-swarm 1.2.1 → 1.9.0

package/src/cli.tsx

@@ -5,6 +5,7 @@ import { useEffect, useState } from "react";
 import pkg from "../package.json";
 import { runClaude } from "./claude.ts";
 import { runHook } from "./commands/hook.ts";
+import { runLead } from "./commands/lead.ts";
 import { Setup } from "./commands/setup.tsx";
 import { runWorker } from "./commands/worker.ts";
 
@@ -29,6 +30,8 @@ interface ParsedArgs {
   restore: boolean;
   yes: boolean;
   yolo: boolean;
+  systemPrompt: string;
+  systemPromptFile: string;
   additionalArgs: string[];
 }
 
@@ -42,6 +45,8 @@ function parseArgs(args: string[]): ParsedArgs {
   let restore = false;
   let yes = false;
   let yolo = false;
+  let systemPrompt = "";
+  let systemPromptFile = "";
   let additionalArgs: string[] = [];
 
   // Find if there's a "--" separator for additional args
@@ -70,10 +75,29 @@ function parseArgs(args: string[]): ParsedArgs {
       yes = true;
     } else if (arg === "--yolo") {
       yolo = true;
+    } else if (arg === "--system-prompt") {
+      systemPrompt = mainArgs[i + 1] || systemPrompt;
+      i++;
+    } else if (arg === "--system-prompt-file") {
+      systemPromptFile = mainArgs[i + 1] || systemPromptFile;
+      i++;
     }
   }
 
-  return { command, port, key, msg, headless, dryRun, restore, yes, yolo, additionalArgs };
+  return {
+    command,
+    port,
+    key,
+    msg,
+    headless,
+    dryRun,
+    restore,
+    yes,
+    yolo,
+    systemPrompt,
+    systemPromptFile,
+    additionalArgs,
+  };
 }
 
 function Help() {
@@ -136,6 +160,12 @@ function Help() {
           </Box>
           <Text>Run Claude in headless loop mode</Text>
         </Box>
+        <Box>
+          <Box width={12}>
+            <Text color="green">lead</Text>
+          </Box>
+          <Text>Run Claude as lead agent in headless loop</Text>
+        </Box>
         <Box>
           <Box width={12}>
             <Text color="green">version</Text>
@@ -211,21 +241,33 @@ function Help() {
       </Box>
 
       <Box marginTop={1} flexDirection="column">
-        <Text bold>Options for 'worker':</Text>
+        <Text bold>Options for 'worker' and 'lead':</Text>
         <Box>
-          <Box width={24}>
+          <Box width={30}>
             <Text color="yellow">-m, --msg {"<prompt>"}</Text>
           </Box>
           <Text>Custom prompt (default: /agent-swarm:start-worker)</Text>
         </Box>
         <Box>
-          <Box width={24}>
+          <Box width={30}>
             <Text color="yellow">--yolo</Text>
           </Box>
           <Text>Continue on errors instead of stopping</Text>
         </Box>
         <Box>
-          <Box width={24}>
+          <Box width={30}>
+            <Text color="yellow">--system-prompt {"<text>"}</Text>
+          </Box>
+          <Text>Custom system prompt (appended to Claude)</Text>
+        </Box>
+        <Box>
+          <Box width={30}>
+            <Text color="yellow">--system-prompt-file {"<path>"}</Text>
+          </Box>
+          <Text>Read system prompt from file</Text>
+        </Box>
+        <Box>
+          <Box width={30}>
             <Text color="yellow">-- {"<args...>"}</Text>
           </Box>
           <Text>Additional arguments to pass to Claude CLI</Text>
@@ -246,6 +288,12 @@ function Help() {
         <Text dimColor> {binName} worker</Text>
         <Text dimColor> {binName} worker --yolo</Text>
         <Text dimColor> {binName} worker -m "Custom prompt"</Text>
+        <Text dimColor> {binName} worker --system-prompt "You are a Python specialist"</Text>
+        <Text dimColor> {binName} worker --system-prompt-file ./prompts/specialist.txt</Text>
+        <Text dimColor> {binName} lead</Text>
+        <Text dimColor> {binName} lead --yolo</Text>
+        <Text dimColor> {binName} lead -m "Custom prompt"</Text>
+        <Text dimColor> {binName} lead --system-prompt "You are a project coordinator"</Text>
       </Box>
 
       <Box marginTop={1} flexDirection="column">
@@ -282,10 +330,28 @@ function Help() {
         </Box>
         <Box>
           <Box width={24}>
-            <Text color="magenta">WORKER_YOLO</Text>
+            <Text color="magenta">YOLO</Text>
           </Box>
           <Text>If "true", worker continues on errors</Text>
         </Box>
+        <Box>
+          <Box width={32}>
+            <Text color="magenta">LOG_DIR</Text>
+          </Box>
+          <Text>Directory for agent logs, defaults to ./logs</Text>
+        </Box>
+        <Box>
+          <Box width={32}>
+            <Text color="magenta">SYSTEM_PROMPT</Text>
+          </Box>
+          <Text>Custom system prompt for worker</Text>
+        </Box>
+        <Box>
+          <Box width={32}>
+            <Text color="magenta">SYSTEM_PROMPT_FILE</Text>
+          </Box>
+          <Text>Path to system prompt file</Text>
+        </Box>
       </Box>
     </Box>
   );
@@ -363,23 +429,50 @@ function ClaudeRunner({ msg, headless, additionalArgs }: ClaudeRunnerProps) {
   return null;
 }
 
-interface WorkerRunnerProps {
+interface RunnerProps {
   prompt: string;
   yolo: boolean;
+  systemPrompt: string;
+  systemPromptFile: string;
   additionalArgs: string[];
 }
 
-function WorkerRunner({ prompt, yolo, additionalArgs }: WorkerRunnerProps) {
+function WorkerRunner({
+  prompt,
+  yolo,
+  systemPrompt,
+  systemPromptFile,
+  additionalArgs,
+}: RunnerProps) {
   const { exit } = useApp();
 
   useEffect(() => {
     runWorker({
       prompt: prompt || undefined,
       yolo,
+      systemPrompt: systemPrompt || undefined,
+      systemPromptFile: systemPromptFile || undefined,
       additionalArgs,
     }).catch((err) => exit(err));
     // Note: runWorker runs indefinitely, so we don't call exit() on success
-  }, [prompt, yolo, additionalArgs, exit]);
+  }, [prompt, yolo, systemPrompt, systemPromptFile, additionalArgs, exit]);
+
+  return null;
+}
+
+function LeadRunner({ prompt, yolo, systemPrompt, systemPromptFile, additionalArgs }: RunnerProps) {
+  const { exit } = useApp();
+
+  useEffect(() => {
+    runLead({
+      prompt: prompt || undefined,
+      yolo,
+      systemPrompt: systemPrompt || undefined,
+      systemPromptFile: systemPromptFile || undefined,
+      additionalArgs,
+    }).catch((err) => exit(err));
+    // Note: runLead runs indefinitely, so we don't call exit() on success
+  }, [prompt, yolo, systemPrompt, systemPromptFile, additionalArgs, exit]);
 
   return null;
 }
@@ -414,7 +507,20 @@ function Version() {
 }
 
 function App({ args }: { args: ParsedArgs }) {
-  const { command, port, key, msg, headless, dryRun, restore, yes, yolo, additionalArgs } = args;
+  const {
+    command,
+    port,
+    key,
+    msg,
+    headless,
+    dryRun,
+    restore,
+    yes,
+    yolo,
+    systemPrompt,
+    systemPromptFile,
+    additionalArgs,
+  } = args;
 
   switch (command) {
     case "setup":
@@ -424,7 +530,25 @@ function App({ args }: { args: ParsedArgs }) {
     case "claude":
       return <ClaudeRunner msg={msg} headless={headless} additionalArgs={additionalArgs} />;
     case "worker":
-      return <WorkerRunner prompt={msg} yolo={yolo} additionalArgs={additionalArgs} />;
+      return (
+        <WorkerRunner
+          prompt={msg}
+          yolo={yolo}
+          systemPrompt={systemPrompt}
+          systemPromptFile={systemPromptFile}
+          additionalArgs={additionalArgs}
+        />
+      );
+    case "lead":
+      return (
+        <LeadRunner
+          prompt={msg}
+          yolo={yolo}
+          systemPrompt={systemPrompt}
+          systemPromptFile={systemPromptFile}
+          additionalArgs={additionalArgs}
+        />
+      );
     case "version":
       return <Version />;
     case "help":

package/src/commands/lead.ts

@@ -0,0 +1,13 @@
+import { type RunnerConfig, type RunnerOptions, runAgent } from "./runner.ts";
+
+export type LeadOptions = RunnerOptions;
+
+const leadConfig: RunnerConfig = {
+  role: "lead",
+  defaultPrompt: "/start-leader",
+  metadataType: "lead_metadata",
+};
+
+export async function runLead(opts: LeadOptions) {
+  return runAgent(leadConfig, opts);
+}

package/src/commands/runner.ts

@@ -0,0 +1,255 @@
+import { mkdir } from "node:fs/promises";
+import { getBasePrompt } from "../prompts/base-prompt.ts";
+import { prettyPrintLine, prettyPrintStderr } from "../utils/pretty-print.ts";
+
+/** Save PM2 process list for persistence across container restarts */
+async function savePm2State(role: string): Promise<void> {
+  try {
+    console.log(`[${role}] Saving PM2 process list...`);
+    await Bun.$`pm2 save`.quiet();
+    console.log(`[${role}] PM2 state saved`);
+  } catch {
+    // PM2 not available or no processes - silently ignore
+  }
+}
+
+/** Setup signal handlers for graceful shutdown */
+function setupShutdownHandlers(role: string): void {
+  const shutdown = async (signal: string) => {
+    console.log(`\n[${role}] Received ${signal}, shutting down...`);
+    await savePm2State(role);
+    process.exit(0);
+  };
+
+  process.on("SIGINT", () => shutdown("SIGINT"));
+  process.on("SIGTERM", () => shutdown("SIGTERM"));
+}
+
+/** Configuration for a runner role (worker or lead) */
+export interface RunnerConfig {
+  /** Role name for logging, e.g., "worker" or "lead" */
+  role: string;
+  /** Default prompt if none provided */
+  defaultPrompt: string;
+  /** Metadata type for log files, e.g., "worker_metadata" */
+  metadataType: string;
+}
+
+export interface RunnerOptions {
+  prompt?: string;
+  yolo?: boolean;
+  systemPrompt?: string;
+  systemPromptFile?: string;
+  additionalArgs?: string[];
+}
+
+interface RunClaudeIterationOptions {
+  prompt: string;
+  logFile: string;
+  systemPrompt?: string;
+  additionalArgs?: string[];
+  role: string;
+}
+
+async function runClaudeIteration(opts: RunClaudeIterationOptions): Promise<number> {
+  const { role } = opts;
+  const CMD = [
+    "claude",
+    "--verbose",
+    "--output-format",
+    "stream-json",
+    "--dangerously-skip-permissions",
+    "--allow-dangerously-skip-permissions",
+    "--permission-mode",
+    "bypassPermissions",
+    "-p",
+    opts.prompt,
+  ];
+
+  if (opts.additionalArgs && opts.additionalArgs.length > 0) {
+    CMD.push(...opts.additionalArgs);
+  }
+
+  if (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)`);
+
+  const logFileHandle = Bun.file(opts.logFile).writer();
+  let stderrOutput = "";
+
+  const proc = Bun.spawn(CMD, {
+    env: process.env,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  let stdoutChunks = 0;
+  let stderrChunks = 0;
+
+  const stdoutPromise = (async () => {
+    if (proc.stdout) {
+      for await (const chunk of proc.stdout) {
+        stdoutChunks++;
+        const text = new TextDecoder().decode(chunk);
+        logFileHandle.write(text);
+
+        const lines = text.split("\n");
+        for (const line of lines) {
+          prettyPrintLine(line, role);
+        }
+      }
+    }
+  })();
+
+  const stderrPromise = (async () => {
+    if (proc.stderr) {
+      for await (const chunk of proc.stderr) {
+        stderrChunks++;
+        const text = new TextDecoder().decode(chunk);
+        stderrOutput += text;
+        prettyPrintStderr(text, role);
+        logFileHandle.write(
+          `${JSON.stringify({ type: "stderr", content: text, timestamp: new Date().toISOString() })}\n`,
+        );
+      }
+    }
+  })();
+
+  await Promise.all([stdoutPromise, stderrPromise]);
+  await logFileHandle.end();
+  const exitCode = await proc.exited;
+
+  if (exitCode !== 0 && stderrOutput) {
+    console.error(`\x1b[31m[${role}] Full stderr:\x1b[0m\n${stderrOutput}`);
+  }
+
+  if (stdoutChunks === 0 && stderrChunks === 0) {
+    console.warn(`\x1b[33m[${role}] WARNING: No output from Claude - check auth/startup\x1b[0m`);
+  }
+
+  return exitCode ?? 1;
+}
+
+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 = process.env.LOG_DIR || "/logs";
+  const logDir = `${baseLogDir}/${sessionId}`;
+
+  await mkdir(logDir, { recursive: true });
+
+  const prompt = opts.prompt || defaultPrompt;
+  const isYolo = opts.yolo || process.env.YOLO === "true";
+
+  // Get agent identity and swarm URL for base prompt
+  const agentId = process.env.AGENT_ID || "unknown";
+  const swarmUrl = process.env.SWARM_URL || "localhost";
+
+  // Generate base prompt that's always included
+  const basePrompt = getBasePrompt({ role, agentId, swarmUrl });
+
+  // Resolve additional system prompt: CLI flag > env var
+  let additionalSystemPrompt: string | undefined;
+  const systemPromptText = opts.systemPrompt || process.env.SYSTEM_PROMPT;
+  const systemPromptFilePath = opts.systemPromptFile || process.env.SYSTEM_PROMPT_FILE;
+
+  if (systemPromptText) {
+    additionalSystemPrompt = systemPromptText;
+    console.log(
+      `[${role}] Using additional system prompt from ${opts.systemPrompt ? "CLI flag" : "env var"}`,
+    );
+  } else if (systemPromptFilePath) {
+    try {
+      const file = Bun.file(systemPromptFilePath);
+      if (!(await file.exists())) {
+        console.error(`[${role}] ERROR: System prompt file not found: ${systemPromptFilePath}`);
+        process.exit(1);
+      }
+      additionalSystemPrompt = await file.text();
+      console.log(`[${role}] Loaded additional system prompt from file: ${systemPromptFilePath}`);
+      console.log(
+        `[${role}] Additional system prompt length: ${additionalSystemPrompt.length} characters`,
+      );
+    } catch (error) {
+      console.error(`[${role}] ERROR: Failed to read system prompt file: ${systemPromptFilePath}`);
+      console.error(error);
+      process.exit(1);
+    }
+  }
+
+  // Combine base prompt with any additional system prompt
+  const resolvedSystemPrompt = additionalSystemPrompt
+    ? `${basePrompt}\n\n${additionalSystemPrompt}`
+    : basePrompt;
+
+  console.log(`[${role}] Starting ${role}`);
+  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}] 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`);
+
+  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(),
+        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...`);
+  }
+}