claude-code-controller 0.1.0

package/dist/index.js

@@ -0,0 +1,1110 @@
+// src/controller.ts
+import { EventEmitter } from "events";
+import { execSync as execSync2 } from "child_process";
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/team-manager.ts
+import { readFile, writeFile, mkdir, rm } from "fs/promises";
+import { existsSync } from "fs";
+import { randomUUID } from "crypto";
+
+// src/paths.ts
+import { homedir } from "os";
+import { join } from "path";
+var CLAUDE_DIR = join(homedir(), ".claude");
+function teamsDir() {
+  return join(CLAUDE_DIR, "teams");
+}
+function teamDir(teamName) {
+  return join(teamsDir(), teamName);
+}
+function teamConfigPath(teamName) {
+  return join(teamDir(teamName), "config.json");
+}
+function inboxesDir(teamName) {
+  return join(teamDir(teamName), "inboxes");
+}
+function inboxPath(teamName, agentName) {
+  return join(inboxesDir(teamName), `${agentName}.json`);
+}
+function tasksBaseDir() {
+  return join(CLAUDE_DIR, "tasks");
+}
+function tasksDir(teamName) {
+  return join(tasksBaseDir(), teamName);
+}
+function taskPath(teamName, taskId) {
+  return join(tasksDir(teamName), `${taskId}.json`);
+}
+
+// src/team-manager.ts
+var TeamManager = class {
+  teamName;
+  sessionId;
+  log;
+  constructor(teamName, logger) {
+    this.teamName = teamName;
+    this.sessionId = randomUUID();
+    this.log = logger;
+  }
+  /**
+   * Create the team directory structure and config.json.
+   * The controller registers itself as the lead member.
+   */
+  async create(opts) {
+    const dir = teamDir(this.teamName);
+    const inboxDir = inboxesDir(this.teamName);
+    const taskDir = tasksDir(this.teamName);
+    await mkdir(dir, { recursive: true });
+    await mkdir(inboxDir, { recursive: true });
+    await mkdir(taskDir, { recursive: true });
+    const leadName = "controller";
+    const leadAgentId = `${leadName}@${this.teamName}`;
+    const config = {
+      name: this.teamName,
+      description: opts?.description,
+      createdAt: Date.now(),
+      leadAgentId,
+      leadSessionId: this.sessionId,
+      members: [
+        {
+          agentId: leadAgentId,
+          name: leadName,
+          agentType: "controller",
+          joinedAt: Date.now(),
+          tmuxPaneId: "",
+          cwd: opts?.cwd || process.cwd(),
+          subscriptions: []
+        }
+      ]
+    };
+    await this.writeConfig(config);
+    this.log.info(`Team "${this.teamName}" created`);
+    return config;
+  }
+  /**
+   * Add a member to the team config.
+   */
+  async addMember(member) {
+    const config = await this.getConfig();
+    config.members = config.members.filter((m) => m.name !== member.name);
+    config.members.push(member);
+    await this.writeConfig(config);
+    this.log.debug(`Added member "${member.name}" to team`);
+  }
+  /**
+   * Remove a member from the team config.
+   */
+  async removeMember(name) {
+    const config = await this.getConfig();
+    config.members = config.members.filter((m) => m.name !== name);
+    await this.writeConfig(config);
+    this.log.debug(`Removed member "${name}" from team`);
+  }
+  /**
+   * Read the current team config.
+   */
+  async getConfig() {
+    const path = teamConfigPath(this.teamName);
+    if (!existsSync(path)) {
+      throw new Error(
+        `Team "${this.teamName}" does not exist (no config.json)`
+      );
+    }
+    const raw = await readFile(path, "utf-8");
+    return JSON.parse(raw);
+  }
+  /**
+   * Check if the team already exists on disk.
+   */
+  exists() {
+    return existsSync(teamConfigPath(this.teamName));
+  }
+  /**
+   * Destroy the team: remove all team directories and task directories.
+   */
+  async destroy() {
+    const dir = teamDir(this.teamName);
+    const taskDir = tasksDir(this.teamName);
+    if (existsSync(dir)) {
+      await rm(dir, { recursive: true, force: true });
+    }
+    if (existsSync(taskDir)) {
+      await rm(taskDir, { recursive: true, force: true });
+    }
+    this.log.info(`Team "${this.teamName}" destroyed`);
+  }
+  async writeConfig(config) {
+    const path = teamConfigPath(this.teamName);
+    await writeFile(path, JSON.stringify(config, null, 2), "utf-8");
+  }
+};
+
+// src/task-manager.ts
+import { readFile as readFile2, writeFile as writeFile2, readdir, mkdir as mkdir2, rm as rm2 } from "fs/promises";
+import { existsSync as existsSync2 } from "fs";
+var TaskManager = class {
+  constructor(teamName, log) {
+    this.teamName = teamName;
+    this.log = log;
+  }
+  nextId = 1;
+  /**
+   * Initialize the task directory. Call after team creation.
+   * Also scans for existing tasks to set the next ID correctly.
+   */
+  async init() {
+    const dir = tasksDir(this.teamName);
+    await mkdir2(dir, { recursive: true });
+    const existing = await this.list();
+    if (existing.length > 0) {
+      const maxId = Math.max(...existing.map((t) => parseInt(t.id, 10)));
+      this.nextId = maxId + 1;
+    }
+  }
+  /**
+   * Create a new task. Returns the assigned task ID.
+   */
+  async create(task) {
+    const id = String(this.nextId++);
+    const full = {
+      id,
+      subject: task.subject,
+      description: task.description,
+      activeForm: task.activeForm,
+      owner: task.owner,
+      status: task.status || "pending",
+      blocks: task.blocks || [],
+      blockedBy: task.blockedBy || [],
+      metadata: task.metadata
+    };
+    await this.writeTask(full);
+    this.log.debug(`Created task #${id}: ${task.subject}`);
+    return id;
+  }
+  /**
+   * Get a task by ID.
+   */
+  async get(taskId) {
+    const path = taskPath(this.teamName, taskId);
+    if (!existsSync2(path)) {
+      throw new Error(`Task #${taskId} not found`);
+    }
+    const raw = await readFile2(path, "utf-8");
+    return JSON.parse(raw);
+  }
+  /**
+   * Update a task. Merges the provided fields.
+   */
+  async update(taskId, updates) {
+    const task = await this.get(taskId);
+    Object.assign(task, updates);
+    await this.writeTask(task);
+    this.log.debug(`Updated task #${taskId}: status=${task.status}`);
+    return task;
+  }
+  /**
+   * Add blocking relationships.
+   */
+  async addBlocks(taskId, blockedTaskIds) {
+    const task = await this.get(taskId);
+    const toAdd = blockedTaskIds.filter((id) => !task.blocks.includes(id));
+    task.blocks.push(...toAdd);
+    await this.writeTask(task);
+    for (const blockedId of toAdd) {
+      const blocked = await this.get(blockedId);
+      if (!blocked.blockedBy.includes(taskId)) {
+        blocked.blockedBy.push(taskId);
+        await this.writeTask(blocked);
+      }
+    }
+  }
+  /**
+   * List all tasks.
+   */
+  async list() {
+    const dir = tasksDir(this.teamName);
+    if (!existsSync2(dir)) return [];
+    const files = await readdir(dir);
+    const tasks = [];
+    for (const file of files) {
+      if (!file.endsWith(".json")) continue;
+      const raw = await readFile2(taskPath(this.teamName, file.replace(".json", "")), "utf-8");
+      tasks.push(JSON.parse(raw));
+    }
+    return tasks.sort((a, b) => parseInt(a.id) - parseInt(b.id));
+  }
+  /**
+   * Delete a task file.
+   */
+  async delete(taskId) {
+    const path = taskPath(this.teamName, taskId);
+    if (existsSync2(path)) {
+      await rm2(path);
+      this.log.debug(`Deleted task #${taskId}`);
+    }
+  }
+  /**
+   * Wait for a task to reach a target status.
+   */
+  async waitFor(taskId, targetStatus = "completed", opts) {
+    const timeout = opts?.timeout ?? 3e5;
+    const interval = opts?.pollInterval ?? 1e3;
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const task = await this.get(taskId);
+      if (task.status === targetStatus) return task;
+      await sleep(interval);
+    }
+    throw new Error(
+      `Timeout waiting for task #${taskId} to reach "${targetStatus}"`
+    );
+  }
+  async writeTask(task) {
+    const path = taskPath(this.teamName, task.id);
+    await writeFile2(path, JSON.stringify(task, null, 4), "utf-8");
+  }
+};
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+// src/process-manager.ts
+import { spawn } from "child_process";
+import { execSync } from "child_process";
+var ProcessManager = class {
+  processes = /* @__PURE__ */ new Map();
+  log;
+  constructor(logger) {
+    this.log = logger;
+  }
+  /**
+   * Spawn a new claude CLI process in teammate mode.
+   * Uses a Python PTY wrapper to provide the terminal the TUI needs.
+   */
+  spawn(opts) {
+    let binary = opts.claudeBinary || "claude";
+    if (!binary.startsWith("/")) {
+      try {
+        binary = execSync(`which ${binary}`, { encoding: "utf-8" }).trim();
+      } catch {
+      }
+    }
+    const claudeArgs = [
+      "--teammate-mode",
+      opts.teammateMode || "auto",
+      "--agent-id",
+      opts.agentId,
+      "--agent-name",
+      opts.agentName,
+      "--team-name",
+      opts.teamName
+    ];
+    if (opts.agentType) {
+      claudeArgs.push("--agent-type", opts.agentType);
+    }
+    if (opts.color) {
+      claudeArgs.push("--agent-color", opts.color);
+    }
+    if (opts.parentSessionId) {
+      claudeArgs.push("--parent-session-id", opts.parentSessionId);
+    }
+    if (opts.model) {
+      claudeArgs.push("--model", opts.model);
+    }
+    if (opts.permissions) {
+      for (const perm of opts.permissions) {
+        claudeArgs.push("--allowedTools", perm);
+      }
+    }
+    this.log.info(
+      `Spawning agent "${opts.agentName}": ${binary} ${claudeArgs.join(" ")}`
+    );
+    const cmdJson = JSON.stringify([binary, ...claudeArgs]);
+    const pythonScript = `
+import pty, os, sys, json, signal, select
+
+cmd = json.loads(sys.argv[1])
+pid, fd = pty.fork()
+if pid == 0:
+    os.execvp(cmd[0], cmd)
+else:
+    signal.signal(signal.SIGTERM, lambda *a: (os.kill(pid, signal.SIGTERM), sys.exit(0)))
+    signal.signal(signal.SIGINT, lambda *a: (os.kill(pid, signal.SIGTERM), sys.exit(0)))
+    try:
+        while True:
+            r, _, _ = select.select([fd, 0], [], [], 1.0)
+            if fd in r:
+                try:
+                    data = os.read(fd, 4096)
+                    if not data:
+                        break
+                    os.write(1, data)
+                except OSError:
+                    break
+            if 0 in r:
+                try:
+                    data = os.read(0, 4096)
+                    if not data:
+                        break
+                    os.write(fd, data)
+                except OSError:
+                    break
+    except:
+        pass
+    finally:
+        try:
+            os.kill(pid, signal.SIGTERM)
+        except:
+            pass
+        _, status = os.waitpid(pid, 0)
+        sys.exit(os.WEXITSTATUS(status) if os.WIFEXITED(status) else 1)
+`;
+    const proc = spawn("python3", ["-c", pythonScript, cmdJson], {
+      cwd: opts.cwd || process.cwd(),
+      stdio: ["pipe", "pipe", "pipe"],
+      env: {
+        ...process.env,
+        CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1",
+        ...opts.env
+      }
+    });
+    this.processes.set(opts.agentName, proc);
+    proc.on("exit", (code, signal) => {
+      this.log.info(
+        `Agent "${opts.agentName}" exited (code=${code}, signal=${signal})`
+      );
+      this.processes.delete(opts.agentName);
+    });
+    proc.on("error", (err) => {
+      this.log.error(`Agent "${opts.agentName}" process error: ${err.message}`);
+      this.processes.delete(opts.agentName);
+    });
+    return proc;
+  }
+  /**
+   * Register a callback for when an agent process exits.
+   */
+  onExit(name, callback) {
+    const proc = this.processes.get(name);
+    if (proc) proc.on("exit", (code) => callback(code));
+  }
+  /**
+   * Get the process for a named agent.
+   */
+  get(name) {
+    return this.processes.get(name);
+  }
+  /**
+   * Check if an agent process is still running.
+   */
+  isRunning(name) {
+    const proc = this.processes.get(name);
+    return proc !== void 0 && proc.exitCode === null && !proc.killed;
+  }
+  /**
+   * Get the PID of a running agent.
+   */
+  getPid(name) {
+    return this.processes.get(name)?.pid;
+  }
+  /**
+   * Kill a specific agent process.
+   */
+  async kill(name, signal = "SIGTERM") {
+    const proc = this.processes.get(name);
+    if (!proc) return;
+    proc.kill(signal);
+    await Promise.race([
+      new Promise((resolve) => proc.on("exit", () => resolve())),
+      new Promise(
+        (resolve) => setTimeout(() => {
+          if (this.processes.has(name)) {
+            this.log.warn(`Force-killing agent "${name}" with SIGKILL`);
+            try {
+              proc.kill("SIGKILL");
+            } catch {
+            }
+          }
+          resolve();
+        }, 5e3)
+      )
+    ]);
+    this.processes.delete(name);
+  }
+  /**
+   * Kill all agent processes.
+   */
+  async killAll() {
+    const names = [...this.processes.keys()];
+    await Promise.all(names.map((name) => this.kill(name)));
+  }
+  /**
+   * Get all running agent names.
+   */
+  runningAgents() {
+    return [...this.processes.keys()].filter((n) => this.isRunning(n));
+  }
+};
+
+// src/inbox.ts
+import { readFile as readFile3, writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
+import { existsSync as existsSync3 } from "fs";
+import { dirname } from "path";
+import { lock } from "proper-lockfile";
+var LOCK_OPTIONS = {
+  retries: { retries: 5, minTimeout: 50, maxTimeout: 500 },
+  stale: 1e4
+};
+async function ensureDir(filePath) {
+  const dir = dirname(filePath);
+  if (!existsSync3(dir)) {
+    await mkdir3(dir, { recursive: true });
+  }
+}
+async function ensureFile(filePath) {
+  await ensureDir(filePath);
+  if (!existsSync3(filePath)) {
+    await writeFile3(filePath, "[]", "utf-8");
+  }
+}
+async function writeInbox(teamName, agentName, message, logger) {
+  const path = inboxPath(teamName, agentName);
+  await ensureFile(path);
+  let release;
+  try {
+    release = await lock(path, LOCK_OPTIONS);
+    const raw = await readFile3(path, "utf-8");
+    const messages = JSON.parse(raw || "[]");
+    messages.push({ ...message, read: false });
+    await writeFile3(path, JSON.stringify(messages, null, 2), "utf-8");
+    logger?.debug(`Wrote message to inbox ${agentName}`, message.from);
+  } finally {
+    if (release) await release();
+  }
+}
+async function readInbox(teamName, agentName) {
+  const path = inboxPath(teamName, agentName);
+  if (!existsSync3(path)) return [];
+  const raw = await readFile3(path, "utf-8");
+  return JSON.parse(raw || "[]");
+}
+async function readUnread(teamName, agentName) {
+  const path = inboxPath(teamName, agentName);
+  if (!existsSync3(path)) return [];
+  let release;
+  try {
+    release = await lock(path, LOCK_OPTIONS);
+    const raw = await readFile3(path, "utf-8");
+    const messages = JSON.parse(raw || "[]");
+    const unread = messages.filter((m) => !m.read);
+    if (unread.length === 0) return [];
+    for (const m of messages) {
+      m.read = true;
+    }
+    await writeFile3(path, JSON.stringify(messages, null, 2), "utf-8");
+    return unread;
+  } finally {
+    if (release) await release();
+  }
+}
+function parseMessage(msg) {
+  try {
+    const parsed = JSON.parse(msg.text);
+    if (parsed && typeof parsed === "object" && "type" in parsed) {
+      return parsed;
+    }
+  } catch {
+  }
+  return { type: "plain_text", text: msg.text };
+}
+
+// src/inbox-poller.ts
+var InboxPoller = class {
+  teamName;
+  agentName;
+  interval;
+  timer = null;
+  log;
+  handlers = [];
+  constructor(teamName, agentName, logger, opts) {
+    this.teamName = teamName;
+    this.agentName = agentName;
+    this.log = logger;
+    this.interval = opts?.pollInterval ?? 500;
+  }
+  /**
+   * Register a handler for new messages.
+   */
+  onMessages(handler) {
+    this.handlers.push(handler);
+  }
+  /**
+   * Start polling.
+   */
+  start() {
+    if (this.timer) return;
+    this.log.debug(
+      `Starting inbox poller for "${this.agentName}" (interval=${this.interval}ms)`
+    );
+    this.timer = setInterval(() => this.poll(), this.interval);
+  }
+  /**
+   * Stop polling.
+   */
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+      this.log.debug(`Stopped inbox poller for "${this.agentName}"`);
+    }
+  }
+  /**
+   * Poll once for new messages.
+   */
+  async poll() {
+    try {
+      const unread = await readUnread(this.teamName, this.agentName);
+      if (unread.length === 0) return [];
+      const events = unread.map((raw) => ({
+        raw,
+        parsed: parseMessage(raw)
+      }));
+      for (const handler of this.handlers) {
+        try {
+          handler(events);
+        } catch (err) {
+          this.log.error("Inbox handler error:", String(err));
+        }
+      }
+      return events;
+    } catch (err) {
+      this.log.error("Inbox poll error:", String(err));
+      return [];
+    }
+  }
+};
+
+// src/agent-handle.ts
+var AgentHandle = class {
+  name;
+  pid;
+  controller;
+  constructor(controller, name, pid) {
+    this.controller = controller;
+    this.name = name;
+    this.pid = pid;
+  }
+  /**
+   * Send a message to this agent.
+   */
+  async send(message, summary) {
+    return this.controller.send(this.name, message, summary);
+  }
+  /**
+   * Wait for a response from this agent.
+   * Returns the text of the first unread plain-text message.
+   */
+  async receive(opts) {
+    const messages = await this.controller.receive(this.name, opts);
+    const texts = messages.map((m) => m.text);
+    return texts.join("\n");
+  }
+  /**
+   * Send a message and wait for the response. Convenience method.
+   */
+  async ask(question, opts) {
+    await this.send(question);
+    return this.receive(opts);
+  }
+  /**
+   * Check if the agent process is still running.
+   */
+  get isRunning() {
+    return this.controller.isAgentRunning(this.name);
+  }
+  /**
+   * Request the agent to shut down gracefully.
+   */
+  async shutdown() {
+    return this.controller.sendShutdownRequest(this.name);
+  }
+  /**
+   * Force-kill the agent process.
+   */
+  async kill() {
+    return this.controller.killAgent(this.name);
+  }
+  /**
+   * Async iterator for agent events (messages from this agent).
+   * Polls the controller's inbox for messages from this agent.
+   */
+  async *events(opts) {
+    const interval = opts?.pollInterval ?? 500;
+    const timeout = opts?.timeout ?? 0;
+    const deadline = timeout > 0 ? Date.now() + timeout : Infinity;
+    while (Date.now() < deadline) {
+      try {
+        const messages = await this.controller.receive(this.name, {
+          timeout: interval,
+          pollInterval: interval
+        });
+        for (const msg of messages) {
+          yield msg;
+        }
+      } catch {
+      }
+      if (!this.isRunning) return;
+    }
+  }
+};
+
+// src/logger.ts
+var LEVELS = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  silent: 4
+};
+function createLogger(level = "info") {
+  const threshold = LEVELS[level];
+  const noop = () => {
+  };
+  const make = (lvl, fn) => (msg, ...args) => {
+    if (LEVELS[lvl] >= threshold) {
+      fn(`[claude-ctrl:${lvl}]`, msg, ...args);
+    }
+  };
+  return {
+    debug: threshold <= LEVELS.debug ? make("debug", console.debug) : noop,
+    info: threshold <= LEVELS.info ? make("info", console.info) : noop,
+    warn: threshold <= LEVELS.warn ? make("warn", console.warn) : noop,
+    error: threshold <= LEVELS.error ? make("error", console.error) : noop
+  };
+}
+var silentLogger = {
+  debug: () => {
+  },
+  info: () => {
+  },
+  warn: () => {
+  },
+  error: () => {
+  }
+};
+
+// src/controller.ts
+var AGENT_COLORS = [
+  "#00FF00",
+  "#00BFFF",
+  "#FF6347",
+  "#FFD700",
+  "#DA70D6",
+  "#40E0D0",
+  "#FF69B4",
+  "#7B68EE"
+];
+var ClaudeCodeController = class extends EventEmitter {
+  teamName;
+  team;
+  tasks;
+  processes;
+  poller;
+  log;
+  cwd;
+  claudeBinary;
+  defaultEnv;
+  colorIndex = 0;
+  initialized = false;
+  constructor(opts) {
+    super();
+    this.teamName = opts?.teamName || `ctrl-${randomUUID2().slice(0, 8)}`;
+    this.cwd = opts?.cwd || process.cwd();
+    this.claudeBinary = opts?.claudeBinary || "claude";
+    this.defaultEnv = opts?.env || {};
+    this.log = opts?.logger || createLogger(opts?.logLevel ?? "info");
+    this.team = new TeamManager(this.teamName, this.log);
+    this.tasks = new TaskManager(this.teamName, this.log);
+    this.processes = new ProcessManager(this.log);
+    this.poller = new InboxPoller(
+      this.teamName,
+      "controller",
+      this.log
+    );
+    this.poller.onMessages((events) => this.handlePollEvents(events));
+  }
+  // ─── Lifecycle ───────────────────────────────────────────────────────
+  /**
+   * Initialize the controller: create the team and start polling.
+   * Must be called before any other operations.
+   */
+  async init() {
+    if (this.initialized) return this;
+    await this.team.create({ cwd: this.cwd });
+    await this.tasks.init();
+    this.poller.start();
+    this.initialized = true;
+    this.log.info(
+      `Controller initialized (team="${this.teamName}")`
+    );
+    return this;
+  }
+  /**
+   * Graceful shutdown:
+   * 1. Send shutdown requests to all agents
+   * 2. Wait briefly for acknowledgment
+   * 3. Kill remaining processes
+   * 4. Clean up team files
+   */
+  async shutdown() {
+    this.log.info("Shutting down controller...");
+    const running = this.processes.runningAgents();
+    const shutdownPromises = [];
+    for (const name of running) {
+      try {
+        await this.sendShutdownRequest(name);
+        shutdownPromises.push(
+          new Promise((resolve) => {
+            const proc = this.processes.get(name);
+            if (!proc) return resolve();
+            const timer = setTimeout(() => resolve(), 1e4);
+            proc.on("exit", () => {
+              clearTimeout(timer);
+              resolve();
+            });
+          })
+        );
+      } catch {
+      }
+    }
+    if (shutdownPromises.length > 0) {
+      await Promise.all(shutdownPromises);
+    }
+    await this.processes.killAll();
+    this.poller.stop();
+    await this.team.destroy();
+    this.initialized = false;
+    this.log.info("Controller shut down");
+  }
+  // ─── Agent Management ────────────────────────────────────────────────
+  /**
+   * Spawn a new Claude Code agent.
+   */
+  async spawnAgent(opts) {
+    this.ensureInitialized();
+    const agentId = `${opts.name}@${this.teamName}`;
+    const color = AGENT_COLORS[this.colorIndex++ % AGENT_COLORS.length];
+    const cwd = opts.cwd || this.cwd;
+    const member = {
+      agentId,
+      name: opts.name,
+      agentType: opts.type || "general-purpose",
+      model: opts.model,
+      joinedAt: Date.now(),
+      tmuxPaneId: "",
+      cwd,
+      subscriptions: []
+    };
+    await this.team.addMember(member);
+    const env = Object.keys(this.defaultEnv).length > 0 || opts.env ? { ...this.defaultEnv, ...opts.env } : void 0;
+    const proc = this.processes.spawn({
+      teamName: this.teamName,
+      agentName: opts.name,
+      agentId,
+      agentType: opts.type || "general-purpose",
+      model: opts.model,
+      cwd,
+      parentSessionId: this.team.sessionId,
+      color,
+      claudeBinary: this.claudeBinary,
+      permissions: opts.permissions,
+      env
+    });
+    this.emit("agent:spawned", opts.name, proc.pid ?? 0);
+    this.processes.onExit(opts.name, (code) => {
+      this.emit("agent:exited", opts.name, code ?? null);
+    });
+    return new AgentHandle(this, opts.name, proc.pid);
+  }
+  // ─── Messaging ───────────────────────────────────────────────────────
+  /**
+   * Send a message to a specific agent.
+   */
+  async send(agentName, message, summary) {
+    this.ensureInitialized();
+    await writeInbox(
+      this.teamName,
+      agentName,
+      {
+        from: "controller",
+        text: message,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        summary
+      },
+      this.log
+    );
+  }
+  /**
+   * Send a structured shutdown request to an agent.
+   */
+  async sendShutdownRequest(agentName) {
+    const requestId = `shutdown-${Date.now()}@${agentName}`;
+    const msg = JSON.stringify({
+      type: "shutdown_request",
+      requestId,
+      from: "controller",
+      reason: "Controller shutdown requested",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    await this.send(agentName, msg);
+  }
+  /**
+   * Broadcast a message to all registered agents (except controller).
+   */
+  async broadcast(message, summary) {
+    this.ensureInitialized();
+    const config = await this.team.getConfig();
+    const agents = config.members.filter((m) => m.name !== "controller");
+    await Promise.all(
+      agents.map((a) => this.send(a.name, message, summary))
+    );
+  }
+  /**
+   * Wait for messages from a specific agent.
+   * Polls the controller's inbox for messages from the given agent.
+   *
+   * Returns when:
+   * - A non-idle message is received (SendMessage from agent), OR
+   * - An idle_notification is received (agent finished its turn),
+   *   in which case the idle message is returned.
+   */
+  async receive(agentName, opts) {
+    const timeout = opts?.timeout ?? 6e4;
+    const interval = opts?.pollInterval ?? 500;
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const unread = await readUnread(this.teamName, "controller");
+      const fromAgent = unread.filter((m) => m.from === agentName);
+      if (fromAgent.length > 0) {
+        const PROTOCOL_TYPES = /* @__PURE__ */ new Set([
+          "shutdown_approved",
+          "plan_approval_response",
+          "permission_response"
+        ]);
+        const meaningful = fromAgent.filter((m) => {
+          const parsed = parseMessage(m);
+          return parsed.type !== "idle_notification" && !PROTOCOL_TYPES.has(parsed.type);
+        });
+        if (meaningful.length > 0) {
+          return opts?.all ? meaningful : [meaningful[0]];
+        }
+        const idles = fromAgent.filter((m) => {
+          const parsed = parseMessage(m);
+          return parsed.type === "idle_notification";
+        });
+        if (idles.length > 0) {
+          return opts?.all ? idles : [idles[0]];
+        }
+      }
+      await sleep2(interval);
+    }
+    throw new Error(
+      `Timeout (${timeout}ms) waiting for message from "${agentName}"`
+    );
+  }
+  /**
+   * Wait for any message from any agent.
+   */
+  async receiveAny(opts) {
+    const timeout = opts?.timeout ?? 6e4;
+    const interval = opts?.pollInterval ?? 500;
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const unread = await readUnread(this.teamName, "controller");
+      const meaningful = unread.filter((m) => {
+        const parsed = parseMessage(m);
+        return parsed.type !== "idle_notification";
+      });
+      if (meaningful.length > 0) {
+        return meaningful[0];
+      }
+      await sleep2(interval);
+    }
+    throw new Error(`Timeout (${timeout}ms) waiting for any message`);
+  }
+  // ─── Tasks ───────────────────────────────────────────────────────────
+  /**
+   * Create a task and optionally notify the assigned agent.
+   */
+  async createTask(task) {
+    this.ensureInitialized();
+    const taskId = await this.tasks.create(task);
+    if (task.owner) {
+      const fullTask = await this.tasks.get(taskId);
+      const assignmentMsg = JSON.stringify({
+        type: "task_assignment",
+        taskId,
+        subject: fullTask.subject,
+        description: fullTask.description,
+        assignedBy: "controller",
+        timestamp: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      await this.send(task.owner, assignmentMsg);
+    }
+    return taskId;
+  }
+  /**
+   * Assign a task to an agent.
+   */
+  async assignTask(taskId, agentName) {
+    const task = await this.tasks.update(taskId, { owner: agentName });
+    const msg = JSON.stringify({
+      type: "task_assignment",
+      taskId,
+      subject: task.subject,
+      description: task.description,
+      assignedBy: "controller",
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    await this.send(agentName, msg);
+  }
+  // ─── Protocol Responses ───────────────────────────────────────────
+  /**
+   * Approve or reject a teammate's plan.
+   * Send this in response to a `plan:approval_request` event.
+   */
+  async sendPlanApproval(agentName, requestId, approve, feedback) {
+    const msg = JSON.stringify({
+      type: "plan_approval_response",
+      requestId,
+      from: "controller",
+      approved: approve,
+      feedback,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    await this.send(agentName, msg);
+  }
+  /**
+   * Approve or reject a teammate's permission/tool-use request.
+   * Send this in response to a `permission:request` event.
+   */
+  async sendPermissionResponse(agentName, requestId, approve) {
+    const msg = JSON.stringify({
+      type: "permission_response",
+      requestId,
+      from: "controller",
+      approved: approve,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    });
+    await this.send(agentName, msg);
+  }
+  /**
+   * Wait for a task to be completed.
+   */
+  async waitForTask(taskId, timeout) {
+    return this.tasks.waitFor(taskId, "completed", { timeout });
+  }
+  // ─── Utilities ───────────────────────────────────────────────────────
+  /**
+   * Check if an agent process is still running.
+   */
+  isAgentRunning(name) {
+    return this.processes.isRunning(name);
+  }
+  /**
+   * Kill a specific agent.
+   */
+  async killAgent(name) {
+    await this.processes.kill(name);
+    await this.team.removeMember(name);
+  }
+  /**
+   * Get the installed Claude Code version.
+   */
+  getClaudeVersion() {
+    try {
+      const version = execSync2(`${this.claudeBinary} --version`, {
+        encoding: "utf-8",
+        timeout: 5e3
+      }).trim();
+      return version;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Verify that the required CLI flags exist in the installed version.
+   */
+  verifyCompatibility() {
+    const version = this.getClaudeVersion();
+    return { compatible: version !== null, version };
+  }
+  // ─── Internal ────────────────────────────────────────────────────────
+  handlePollEvents(events) {
+    for (const event of events) {
+      const { raw, parsed } = event;
+      switch (parsed.type) {
+        case "idle_notification":
+          this.emit("idle", raw.from);
+          break;
+        case "shutdown_approved":
+          this.log.info(
+            `Shutdown approved by "${raw.from}" (requestId=${parsed.requestId})`
+          );
+          this.emit("shutdown:approved", raw.from, parsed);
+          break;
+        case "plan_approval_request":
+          this.log.info(
+            `Plan approval request from "${raw.from}" (requestId=${parsed.requestId})`
+          );
+          this.emit("plan:approval_request", raw.from, parsed);
+          break;
+        case "permission_request":
+          this.log.info(
+            `Permission request from "${raw.from}": ${parsed.toolName} (requestId=${parsed.requestId})`
+          );
+          this.emit("permission:request", raw.from, parsed);
+          break;
+        case "plain_text":
+          this.emit("message", raw.from, raw);
+          break;
+        default:
+          this.emit("message", raw.from, raw);
+      }
+    }
+  }
+  ensureInitialized() {
+    if (!this.initialized) {
+      throw new Error(
+        "Controller not initialized. Call init() first."
+      );
+    }
+  }
+};
+function sleep2(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+export {
+  AgentHandle,
+  ClaudeCodeController,
+  InboxPoller,
+  ProcessManager,
+  TaskManager,
+  TeamManager,
+  createLogger,
+  inboxPath,
+  inboxesDir,
+  parseMessage,
+  readInbox,
+  readUnread,
+  silentLogger,
+  taskPath,
+  tasksBaseDir,
+  tasksDir,
+  teamConfigPath,
+  teamDir,
+  teamsDir,
+  writeInbox
+};
+//# sourceMappingURL=index.js.map