multiagents 0.1.0

package/orchestrator/guardrails.ts

@@ -0,0 +1,243 @@
+// ============================================================================
+// multiagents — Guardrail Enforcement
+// ============================================================================
+// Checks guardrail limits (duration, message counts, agent counts, etc.)
+// and enforces them by pausing/warning as needed.
+// ============================================================================
+
+import type { Guardrail, GuardrailState } from "../shared/types.ts";
+import type { BrokerClient } from "../shared/broker-client.ts";
+import type { AgentEvent } from "./monitor.ts";
+import { log } from "../shared/utils.ts";
+
+const LOG_PREFIX = "guardrails";
+
+/** Result of checking a single guardrail. */
+export interface GuardrailCheck {
+  guardrail: GuardrailState;
+  status: "ok" | "warning" | "triggered";
+  message: string;
+}
+
+/**
+ * Check all guardrails for a session and return their current status.
+ * Fetches guardrail state from the broker (which computes usage).
+ */
+export async function checkGuardrails(
+  sessionId: string,
+  brokerClient: BrokerClient,
+): Promise<GuardrailCheck[]> {
+  const guardrails = await brokerClient.getGuardrails(sessionId);
+  const checks: GuardrailCheck[] = [];
+
+  for (const g of guardrails) {
+    const { usage } = g;
+
+    if (usage.status === "triggered") {
+      checks.push({
+        guardrail: g,
+        status: "triggered",
+        message: `${g.label} reached limit: ${usage.current}/${usage.limit} ${g.unit} (${Math.round(usage.percent * 100)}%)`,
+      });
+    } else if (usage.status === "warning") {
+      checks.push({
+        guardrail: g,
+        status: "warning",
+        message: `${g.label} approaching limit: ${usage.current}/${usage.limit} ${g.unit} (${Math.round(usage.percent * 100)}%)`,
+      });
+    } else {
+      checks.push({
+        guardrail: g,
+        status: "ok",
+        message: `${g.label}: ${usage.current}/${usage.limit} ${g.unit} (${Math.round(usage.percent * 100)}%)`,
+      });
+    }
+  }
+
+  return checks;
+}
+
+/**
+ * Run guardrail checks and enforce limits:
+ * - Emit warning events when warn_at_percent is reached
+ * - Pause session when a guardrail is triggered at 100%
+ */
+export async function enforceGuardrails(
+  sessionId: string,
+  brokerClient: BrokerClient,
+  onEvent: (event: AgentEvent) => void,
+): Promise<void> {
+  const checks = await checkGuardrails(sessionId, brokerClient);
+
+  for (const check of checks) {
+    // Skip monitor-only stats — they never trigger enforcement
+    if (check.guardrail.action === "monitor") continue;
+
+    if (check.status === "warning") {
+      onEvent({
+        type: "guardrail_warning",
+        severity: "warning",
+        slotId: -1,
+        sessionId,
+        message: check.message,
+        data: {
+          guardrail_id: check.guardrail.id,
+          usage_percent: check.guardrail.usage.percent,
+          current: check.guardrail.usage.current,
+          limit: check.guardrail.usage.limit,
+        },
+      });
+    }
+
+    if (check.status === "triggered") {
+      const { guardrail } = check;
+
+      if (guardrail.action === "pause") {
+        log(LOG_PREFIX, `Guardrail triggered — pausing session: ${check.message}`);
+        await pauseForGuardrail(sessionId, guardrail, brokerClient);
+
+        onEvent({
+          type: "guardrail_triggered",
+          severity: "critical",
+          slotId: -1,
+          sessionId,
+          message: `Session paused: ${check.message}`,
+          data: {
+            guardrail_id: guardrail.id,
+            action: "pause",
+            suggested_increases: guardrail.suggested_increases,
+            adjustable: guardrail.adjustable,
+          },
+        });
+      } else if (guardrail.action === "stop") {
+        log(LOG_PREFIX, `Guardrail triggered — stop action: ${check.message}`);
+
+        onEvent({
+          type: "guardrail_triggered",
+          severity: "critical",
+          slotId: -1,
+          sessionId,
+          message: `Guardrail stop: ${check.message}`,
+          data: {
+            guardrail_id: guardrail.id,
+            action: "stop",
+            suggested_increases: guardrail.suggested_increases,
+            adjustable: guardrail.adjustable,
+          },
+        });
+      } else if (guardrail.action === "warn") {
+        onEvent({
+          type: "guardrail_triggered",
+          severity: "warning",
+          slotId: -1,
+          sessionId,
+          message: check.message,
+          data: {
+            guardrail_id: guardrail.id,
+            action: "warn",
+          },
+        });
+      }
+    }
+  }
+}
+
+/**
+ * Pause the entire session due to a guardrail being triggered.
+ * Sends control messages to all connected agents and marks session as paused.
+ */
+export async function pauseForGuardrail(
+  sessionId: string,
+  guardrail: Guardrail | GuardrailState,
+  brokerClient: BrokerClient,
+): Promise<void> {
+  // Mark session as paused
+  await brokerClient.updateSession({
+    id: sessionId,
+    status: "paused",
+    pause_reason: `Guardrail triggered: ${guardrail.label} (${guardrail.id})`,
+    paused_at: Date.now(),
+  });
+
+  // Pause all connected slots
+  const slots = await brokerClient.listSlots(sessionId);
+  for (const slot of slots) {
+    if (slot.status === "connected" && !slot.paused) {
+      await brokerClient.updateSlot({
+        id: slot.id,
+        paused: true,
+        paused_at: Date.now(),
+      });
+
+      // Hold messages for paused agents
+      await brokerClient.holdMessages(sessionId, slot.id);
+
+      // Send control message if agent has a peer connection
+      if (slot.peer_id) {
+        await brokerClient.sendMessage({
+          from_id: "orchestrator",
+          to_id: slot.peer_id,
+          text: JSON.stringify({
+            action: "pause",
+            reason: `Guardrail "${guardrail.label}" reached limit`,
+            guardrail_id: guardrail.id,
+            adjustable: guardrail.adjustable,
+            suggested_increases: guardrail.suggested_increases,
+          }),
+          msg_type: "control",
+          session_id: sessionId,
+        });
+      }
+    }
+  }
+
+  log(LOG_PREFIX, `Session ${sessionId} paused for guardrail: ${guardrail.id}`);
+}
+
+/**
+ * Resume a session after a guardrail limit has been adjusted upward.
+ * Unpauses all slots and releases held messages.
+ */
+export async function resumeAfterGuardrailAdjusted(
+  sessionId: string,
+  brokerClient: BrokerClient,
+): Promise<void> {
+  // Update session status
+  await brokerClient.updateSession({
+    id: sessionId,
+    status: "active",
+    pause_reason: null,
+    paused_at: null,
+  });
+
+  // Resume all paused slots
+  const slots = await brokerClient.listSlots(sessionId);
+  for (const slot of slots) {
+    if (slot.paused) {
+      await brokerClient.updateSlot({
+        id: slot.id,
+        paused: false,
+        paused_at: null,
+      });
+
+      // Release held messages
+      await brokerClient.releaseHeldMessages(sessionId, slot.id);
+
+      // Send resume control message
+      if (slot.peer_id) {
+        await brokerClient.sendMessage({
+          from_id: "orchestrator",
+          to_id: slot.peer_id,
+          text: JSON.stringify({
+            action: "resume",
+            reason: "Guardrail limit adjusted",
+          }),
+          msg_type: "control",
+          session_id: sessionId,
+        });
+      }
+    }
+  }
+
+  log(LOG_PREFIX, `Session ${sessionId} resumed after guardrail adjustment`);
+}

package/orchestrator/launcher.ts

@@ -0,0 +1,433 @@
+// ============================================================================
+// multiagents — Agent Launcher
+// ============================================================================
+// Spawns headless agent processes with appropriate CLI flags and env vars.
+// Ensures each agent has MCP access to the multiagents tools for inter-agent
+// communication through the broker.
+// ============================================================================
+
+import type { Subprocess } from "bun";
+import type { AgentType, AgentLaunchConfig, Slot } from "../shared/types.ts";
+import type { BrokerClient } from "../shared/broker-client.ts";
+import { log } from "../shared/utils.ts";
+import { DEFAULT_BROKER_PORT } from "../shared/constants.ts";
+import * as path from "node:path";
+import * as fs from "node:fs";
+
+const LOG_PREFIX = "launcher";
+
+/** Resolved path to cli.ts — used to build MCP server commands. */
+const CLI_PATH = path.resolve(import.meta.dir, "..", "cli.ts");
+
+/** Detection result for an agent CLI binary. */
+interface AgentDetection {
+  available: boolean;
+  version?: string;
+  path?: string;
+}
+
+/** Result of launching an agent process. */
+interface LaunchResult {
+  slotId: number;
+  pid: number;
+  process: Subprocess;
+}
+
+/** CLI binary name for each agent type. */
+const AGENT_COMMANDS: Record<AgentType, string> = {
+  claude: "claude",
+  codex: "codex",
+  gemini: "npx",
+  custom: "",
+};
+
+/**
+ * Detect whether an agent CLI is installed and available on PATH.
+ * Handles both direct binaries (claude, codex) and npx-based tools (gemini).
+ */
+export async function detectAgent(type: AgentType): Promise<AgentDetection> {
+  const cmd = AGENT_COMMANDS[type];
+  if (!cmd) {
+    return { available: false };
+  }
+
+  // Gemini is invoked via npx — check if the package is available
+  if (type === "gemini") {
+    try {
+      const proc = Bun.spawnSync(["npx", "-y", "@google/gemini-cli", "--version"], {
+        timeout: 15_000,
+      });
+      const out = new TextDecoder().decode(proc.stdout).trim();
+      if (proc.exitCode === 0 && out) {
+        return { available: true, version: out.split("\n")[0], path: "npx" };
+      }
+    } catch { /* ok */ }
+    return { available: false };
+  }
+
+  const which = Bun.spawnSync(["which", cmd]);
+  const binPath = new TextDecoder().decode(which.stdout).trim();
+
+  if (which.exitCode !== 0 || !binPath) {
+    return { available: false };
+  }
+
+  // Try to get version
+  let version: string | undefined;
+  try {
+    const proc = Bun.spawnSync([cmd, "--version"]);
+    const out = new TextDecoder().decode(proc.stdout).trim();
+    if (proc.exitCode === 0 && out) {
+      version = out.split("\n")[0];
+    }
+  } catch {
+    // Version detection is best-effort
+  }
+
+  return { available: true, version, path: binPath };
+}
+
+/**
+ * Build the MCP server config for multiagents, specific to an agent type.
+ * Returns the command + args needed to run the MCP server.
+ */
+export function mcpServerCommand(agentType: AgentType): { command: string; args: string[] } {
+  return {
+    command: "bun",
+    args: [CLI_PATH, "mcp-server", "--agent-type", agentType],
+  };
+}
+
+/**
+ * Ensure the project directory has MCP configs and session file so spawned
+ * agents auto-discover the multiagents MCP server and join the session.
+ * Writes config files idempotently — preserves existing entries.
+ */
+export async function ensureMcpConfigs(projectDir: string, sessionId: string): Promise<void> {
+  // --- Claude: .mcp.json ---
+  const mcpJsonPath = path.join(projectDir, ".mcp.json");
+  let mcpConfig: Record<string, unknown> = {};
+  try {
+    const existing = await Bun.file(mcpJsonPath).text();
+    mcpConfig = JSON.parse(existing);
+  } catch { /* file doesn't exist yet */ }
+
+  const mcpServers = (mcpConfig.mcpServers as Record<string, unknown>) ?? {};
+  const claudeMcp = mcpServerCommand("claude");
+  mcpServers["multiagents"] = { command: claudeMcp.command, args: claudeMcp.args };
+  mcpConfig.mcpServers = mcpServers;
+  await Bun.write(mcpJsonPath, JSON.stringify(mcpConfig, null, 2));
+
+  // --- Codex: .codex/config.toml ---
+  const codexDir = path.join(projectDir, ".codex");
+  if (!fs.existsSync(codexDir)) fs.mkdirSync(codexDir, { recursive: true });
+
+  const codexTomlPath = path.join(codexDir, "config.toml");
+  let codexToml = "";
+  try { codexToml = await Bun.file(codexTomlPath).text(); } catch { /* ok */ }
+
+  // Add multiagents section if not present
+  if (!codexToml.includes("[mcp_servers.multiagents]")) {
+    const codexMcp = mcpServerCommand("codex");
+    const entry = `\n[mcp_servers.multiagents]\ncommand = "bun"\nargs = [${codexMcp.args.map(a => JSON.stringify(a)).join(", ")}]\n`;
+    await Bun.write(codexTomlPath, codexToml.trimEnd() + "\n" + entry);
+  }
+
+  // --- Gemini: ~/.gemini/settings.json ---
+  const geminiSettingsPath = path.join(process.env.HOME ?? "", ".gemini", "settings.json");
+  try {
+    let geminiConfig: Record<string, unknown> = {};
+    try {
+      const existing = await Bun.file(geminiSettingsPath).text();
+      geminiConfig = JSON.parse(existing);
+    } catch { /* ok */ }
+
+    const geminiMcpServers = (geminiConfig.mcpServers as Record<string, unknown>) ?? {};
+    if (!geminiMcpServers["multiagents"]) {
+      const geminiMcp = mcpServerCommand("gemini");
+      geminiMcpServers["multiagents"] = {
+        command: geminiMcp.command,
+        args: geminiMcp.args,
+      };
+      geminiConfig.mcpServers = geminiMcpServers;
+      await Bun.write(geminiSettingsPath, JSON.stringify(geminiConfig, null, 2));
+    }
+  } catch {
+    // Gemini config is optional — skip if ~/.gemini doesn't exist
+  }
+
+  // --- Session file: .multiagents/session.json ---
+  // The MCP adapter reads this to auto-join the correct session.
+  const sessionDir = path.join(projectDir, ".multiagents");
+  if (!fs.existsSync(sessionDir)) fs.mkdirSync(sessionDir, { recursive: true });
+
+  const sessionFilePath = path.join(sessionDir, "session.json");
+  const sessionFile = {
+    session_id: sessionId,
+    created_at: new Date().toISOString(),
+    broker_port: DEFAULT_BROKER_PORT,
+  };
+  await Bun.write(sessionFilePath, JSON.stringify(sessionFile, null, 2));
+
+  log(LOG_PREFIX, `MCP configs and session file ensured in ${projectDir}`);
+}
+
+/**
+ * Spawn an agent as a background process with the appropriate CLI flags.
+ *
+ * Creates a slot in the broker, then spawns the agent process with env vars
+ * so the agent's MCP adapter knows which session/slot to join.
+ * Ensures MCP configs are present so agents can communicate via the broker.
+ */
+export async function launchAgent(
+  sessionId: string,
+  projectDir: string,
+  config: AgentLaunchConfig,
+  brokerClient: BrokerClient,
+): Promise<LaunchResult> {
+  // Ensure MCP configs and session file exist before spawning any agent
+  await ensureMcpConfigs(projectDir, sessionId);
+
+  // Create a slot in the broker for this agent
+  const slot = await brokerClient.createSlot({
+    session_id: sessionId,
+    agent_type: config.agent_type,
+    display_name: config.name,
+    role: config.role,
+    role_description: config.role_description,
+  });
+
+  log(LOG_PREFIX, `Created slot ${slot.id} for ${config.name} (${config.agent_type})`);
+
+  // Assign file ownership if specified
+  if (config.file_ownership && config.file_ownership.length > 0) {
+    await brokerClient.assignOwnership({
+      session_id: sessionId,
+      slot_id: slot.id,
+      path_patterns: config.file_ownership,
+      assigned_by: "orchestrator",
+    });
+  }
+
+  // Build the task prompt with role context
+  const taskPrompt = [
+    `You are "${config.name}", role: ${config.role}.`,
+    config.role_description,
+    "",
+    `Your task: ${config.initial_task}`,
+  ].join("\n");
+
+  // Build CLI args based on agent type
+  const args = buildCliArgs(config.agent_type, taskPrompt);
+  const cmd = AGENT_COMMANDS[config.agent_type];
+
+  if (!cmd) {
+    throw new Error(`No CLI command configured for agent type: ${config.agent_type}`);
+  }
+
+  // Build env — unset CLAUDECODE to allow nested Claude sessions
+  const spawnEnv: Record<string, string | undefined> = {
+    ...process.env,
+    MULTIAGENTS_SESSION: sessionId,
+    MULTIAGENTS_ROLE: config.role,
+    MULTIAGENTS_NAME: config.name,
+    MULTIAGENTS_SLOT: String(slot.id),
+  };
+  delete spawnEnv.CLAUDECODE;
+
+  // Spawn the agent process
+  // stdin MUST be "pipe" for MCP stdio transport (bidirectional JSON-RPC)
+  const proc = Bun.spawn([cmd, ...args], {
+    cwd: projectDir,
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+    env: spawnEnv,
+  });
+
+  log(LOG_PREFIX, `Launched ${config.name} (PID ${proc.pid}) in slot ${slot.id}`);
+
+  return {
+    slotId: slot.id,
+    pid: proc.pid,
+    process: proc,
+  };
+}
+
+/**
+ * Build CLI arguments for a specific agent type.
+ *
+ * Key design: each agent gets the multiagents MCP server injected so it can
+ * communicate with teammates through the broker. For Claude this uses
+ * --mcp-config (inline JSON); for Codex this uses -c to override the
+ * mcp_servers config key (replacing any broken global entries).
+ */
+export function buildCliArgs(agentType: AgentType, task: string): string[] {
+  switch (agentType) {
+    case "claude": {
+      // Build inline MCP config JSON for --mcp-config
+      const claudeMcp = mcpServerCommand("claude");
+      const mcpConfigJson = JSON.stringify({
+        mcpServers: {
+          "multiagents": {
+            command: claudeMcp.command,
+            args: claudeMcp.args,
+          },
+        },
+      });
+      return [
+        "--print",
+        "--verbose",
+        "--output-format", "stream-json",
+        "--max-turns", "200",
+        "--dangerously-skip-permissions",
+        "--mcp-config", mcpConfigJson,
+        "-p", task,
+      ];
+    }
+    case "codex": {
+      // Inject multiagents MCP server via dotted-path config overrides.
+      //
+      // CRITICAL: Codex loads ALL MCP servers from ~/.codex/config.toml at
+      // startup. We must neutralize any global entries that would interfere:
+      //
+      // 1. Entries with `url` (like figma) are remote MCP — not supported
+      //    in stdio mode, causes connection errors.
+      // 2. Entries with slow `npx` commands (like chrome-devtools) cause
+      //    10s+ timeouts during MCP handshake.
+      // 3. NEVER use `echo "disabled"` as a dummy — Codex reads stdout as
+      //    JSON-RPC and "disabled" fails to parse, crashing the agent.
+      //
+      // The fix: read ~/.codex/config.toml, find all [mcp_servers.*] keys,
+      // and override each non-multiagents entry with noop-mcp.ts — a tiny
+      // MCP server that completes the JSON-RPC handshake instantly with zero
+      // tools, then stays alive. This avoids:
+      //   - /usr/bin/true: exits immediately → 10s MCP handshake timeout
+      //   - echo "disabled": stdout parsed as JSON-RPC → deserialization crash
+      const noopMcpPath = path.resolve(import.meta.dir, "..", "noop-mcp.ts");
+      const codexMcp = mcpServerCommand("codex");
+      const argsJson = JSON.stringify(codexMcp.args);
+      const overrides: string[] = [
+        // Our MCP server
+        `mcp_servers.multiagents.command="${codexMcp.command}"`,
+        `mcp_servers.multiagents.args=${argsJson}`,
+        'model_reasoning_effort="high"',
+      ];
+
+      // Neutralize global MCP servers by reading config
+      const globalConfigPath = path.join(process.env.HOME ?? "", ".codex", "config.toml");
+      try {
+        const configText = fs.readFileSync(globalConfigPath, "utf-8");
+        // Find all [mcp_servers.XXX] section names
+        const mcpPattern = /\[mcp_servers\.(\w[\w-]*)\]/g;
+        let match;
+        while ((match = mcpPattern.exec(configText)) !== null) {
+          const serverName = match[1];
+          if (serverName !== "multiagents") {
+            // Override with noop-mcp.ts — instant handshake, zero tools
+            overrides.push(`mcp_servers.${serverName}.command="bun"`);
+            overrides.push(`mcp_servers.${serverName}.args=["${noopMcpPath}"]`);
+            // Clear url field if present (remote MCP entries)
+            overrides.push(`mcp_servers.${serverName}.url=""`);
+          }
+        }
+      } catch {
+        // No global config — nothing to neutralize
+      }
+
+      const args: string[] = [
+        "exec",
+        "--sandbox", "workspace-write",
+        "--full-auto",
+        "--json",
+      ];
+      for (const override of overrides) {
+        args.push("-c", override);
+      }
+      args.push(task);
+      return args;
+    }
+    case "gemini": {
+      // Gemini CLI is invoked via npx. MCP is configured at user level
+      // (~/.gemini/settings.json) by ensureMcpConfigs. Use --approval-mode
+      // yolo for fully autonomous operation, --sandbox for safety, and
+      // --output-format stream-json for structured output parsing.
+      return [
+        "-y", "@google/gemini-cli",
+        "--sandbox",
+        "--approval-mode", "yolo",
+        "--output-format", "stream-json",
+        "--allowed-mcp-server-names", "multiagents",
+        "-p", task,
+      ];
+    }
+    case "custom":
+      return [task];
+  }
+}
+
+/**
+ * Build a team context string listing all active slots in the session,
+ * excluding the given slot. Used to orient a new or restarted agent.
+ */
+export async function buildTeamContext(
+  sessionId: string,
+  excludeSlotId: number,
+  brokerClient: BrokerClient,
+): Promise<string> {
+  const slots = await brokerClient.listSlots(sessionId);
+  const teammates = slots.filter((s) => s.id !== excludeSlotId && s.status === "connected");
+
+  if (teammates.length === 0) {
+    return "You are the first agent on this team. No other agents are active yet.";
+  }
+
+  const lines = ["Current team members:"];
+  for (const s of teammates) {
+    const name = s.display_name ?? `Agent #${s.id}`;
+    const role = s.role ?? "unassigned";
+    const status = s.paused ? "paused" : "active";
+    lines.push(`  - ${name} (${s.agent_type}, slot ${s.id}): role="${role}", status=${status}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Announce a new team member to all existing connected slots.
+ * Sends a team_change message so agents can update their mental model.
+ */
+export async function announceNewMember(
+  sessionId: string,
+  newSlot: Slot,
+  config: AgentLaunchConfig,
+  brokerClient: BrokerClient,
+): Promise<void> {
+  const slots = await brokerClient.listSlots(sessionId);
+  const peers = slots.filter((s) => s.id !== newSlot.id && s.status === "connected" && s.peer_id);
+
+  const announcement = [
+    `[Team Update] New member joined: "${config.name}"`,
+    `  Role: ${config.role}`,
+    `  Type: ${config.agent_type}`,
+    `  Slot: ${newSlot.id}`,
+    config.file_ownership?.length
+      ? `  File ownership: ${config.file_ownership.join(", ")}`
+      : "",
+    `  Task: ${config.initial_task}`,
+  ]
+    .filter(Boolean)
+    .join("\n");
+
+  for (const peer of peers) {
+    if (!peer.peer_id) continue;
+    await brokerClient.sendMessage({
+      from_id: "orchestrator",
+      to_id: peer.peer_id,
+      text: announcement,
+      msg_type: "team_change",
+      session_id: sessionId,
+    });
+  }
+
+  log(LOG_PREFIX, `Announced ${config.name} to ${peers.length} existing agents`);
+}