claude-code-controller 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,3 +1,7 @@
+// src/claude.ts
+import { EventEmitter as EventEmitter2 } from "events";
+import { randomUUID as randomUUID3 } from "crypto";
+
 // src/controller.ts
 import { EventEmitter } from "events";
 import { execSync as execSync2 } from "child_process";
@@ -312,6 +316,9 @@ var ProcessManager = class {
     if (opts.model) {
       claudeArgs.push("--model", opts.model);
     }
+    if (opts.permissionMode) {
+      claudeArgs.push("--permission-mode", opts.permissionMode);
+    }
     if (opts.permissions) {
       for (const perm of opts.permissions) {
         claudeArgs.push("--allowedTools", perm);
@@ -695,6 +702,11 @@ var silentLogger = {
 };
 
 // src/controller.ts
+var PROTOCOL_ONLY_TYPES = /* @__PURE__ */ new Set([
+  "shutdown_approved",
+  "plan_approval_response",
+  "permission_response"
+]);
 var AGENT_COLORS = [
   "#00FF00",
   "#00BFFF",
@@ -819,6 +831,7 @@ var ClaudeCodeController = class extends EventEmitter {
       color,
       claudeBinary: this.claudeBinary,
       permissions: opts.permissions,
+      permissionMode: opts.permissionMode,
       env
     });
     this.emit("agent:spawned", opts.name, proc.pid ?? 0);
@@ -887,11 +900,7 @@ var ClaudeCodeController = class extends EventEmitter {
       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 PROTOCOL_TYPES = PROTOCOL_ONLY_TYPES;
         const meaningful = fromAgent.filter((m) => {
           const parsed = parseMessage(m);
           return parsed.type !== "idle_notification" && !PROTOCOL_TYPES.has(parsed.type);
@@ -924,7 +933,7 @@ var ClaudeCodeController = class extends EventEmitter {
       const unread = await readUnread(this.teamName, "controller");
       const meaningful = unread.filter((m) => {
         const parsed = parseMessage(m);
-        return parsed.type !== "idle_notification";
+        return parsed.type !== "idle_notification" && !PROTOCOL_ONLY_TYPES.has(parsed.type);
       });
       if (meaningful.length > 0) {
         return meaningful[0];
@@ -1085,13 +1094,462 @@ var ClaudeCodeController = class extends EventEmitter {
 function sleep2(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
+
+// src/claude.ts
+Symbol.asyncDispose ??= /* @__PURE__ */ Symbol("Symbol.asyncDispose");
+function buildEnv(opts) {
+  const env = { ...opts.env };
+  if (opts.apiKey) env.ANTHROPIC_AUTH_TOKEN = opts.apiKey;
+  if (opts.baseUrl) env.ANTHROPIC_BASE_URL = opts.baseUrl;
+  if (opts.timeout != null) env.API_TIMEOUT_MS = String(opts.timeout);
+  return env;
+}
+function resolvePermissions(preset) {
+  switch (preset) {
+    case "edit":
+      return { permissionMode: "acceptEdits" };
+    case "plan":
+      return { permissionMode: "plan" };
+    case "ask":
+      return { permissionMode: "default" };
+    case "full":
+    default:
+      return { permissionMode: void 0 };
+  }
+}
+function waitForReady(controller, agentName, timeoutMs = 15e3) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const timer = setTimeout(() => {
+      if (settled) return;
+      cleanup();
+      reject(
+        new Error(
+          `Agent "${agentName}" did not become ready within ${timeoutMs}ms`
+        )
+      );
+    }, timeoutMs);
+    const onReady = (name) => {
+      if (name === agentName && !settled) {
+        settled = true;
+        cleanup();
+        resolve();
+      }
+    };
+    const onExit = (name, code) => {
+      if (name === agentName && !settled) {
+        settled = true;
+        cleanup();
+        reject(
+          new Error(
+            `Agent "${agentName}" exited before becoming ready (code=${code})`
+          )
+        );
+      }
+    };
+    const onSpawned = (name) => {
+      if (name === agentName && !settled) {
+        settled = true;
+        cleanup();
+        resolve();
+      }
+    };
+    const cleanup = () => {
+      clearTimeout(timer);
+      controller.removeListener("idle", onReady);
+      controller.removeListener("message", onReady);
+      controller.removeListener("agent:spawned", onSpawned);
+      controller.removeListener("agent:exited", onExit);
+    };
+    controller.on("idle", onReady);
+    controller.on("message", onReady);
+    controller.on("agent:spawned", onSpawned);
+    controller.on("agent:exited", onExit);
+  });
+}
+var Agent = class _Agent extends EventEmitter2 {
+  controller;
+  handle;
+  ownsController;
+  disposed = false;
+  boundListeners = [];
+  constructor(controller, handle, ownsController, behavior) {
+    super();
+    this.controller = controller;
+    this.handle = handle;
+    this.ownsController = ownsController;
+    this.wireEvents();
+    this.wireBehavior(behavior);
+  }
+  /** Create a standalone agent (owns its own controller). */
+  static async create(opts = {}) {
+    const name = opts.name ?? `agent-${randomUUID3().slice(0, 8)}`;
+    const env = buildEnv(opts);
+    const { permissionMode } = resolvePermissions(opts.permissions);
+    const controller = new ClaudeCodeController({
+      teamName: `claude-${randomUUID3().slice(0, 8)}`,
+      cwd: opts.cwd,
+      claudeBinary: opts.claudeBinary,
+      env,
+      logLevel: opts.logLevel ?? "warn",
+      logger: opts.logger
+    });
+    await controller.init();
+    const ready = waitForReady(controller, name, opts.readyTimeout);
+    try {
+      const handle = await controller.spawnAgent({
+        name,
+        type: opts.type ?? "general-purpose",
+        model: opts.model,
+        cwd: opts.cwd,
+        permissionMode
+      });
+      const agent = new _Agent(controller, handle, true, {
+        autoApprove: opts.autoApprove,
+        onPermission: opts.onPermission,
+        onPlan: opts.onPlan
+      });
+      await ready;
+      return agent;
+    } catch (err) {
+      await controller.shutdown().catch(() => {
+      });
+      throw err;
+    }
+  }
+  /** Create an agent within an existing session (session owns the controller). */
+  static async createInSession(controller, name, opts = {}) {
+    const { permissionMode } = resolvePermissions(opts.permissions);
+    const ready = waitForReady(controller, name, opts.readyTimeout);
+    const handle = await controller.spawnAgent({
+      name,
+      type: opts.type ?? "general-purpose",
+      model: opts.model,
+      cwd: opts.cwd,
+      permissionMode,
+      env: opts.env
+    });
+    const agent = new _Agent(controller, handle, false, {
+      autoApprove: opts.autoApprove,
+      onPermission: opts.onPermission,
+      onPlan: opts.onPlan
+    });
+    await ready;
+    return agent;
+  }
+  /** The agent's name. */
+  get name() {
+    return this.handle.name;
+  }
+  /** The agent process PID. */
+  get pid() {
+    return this.handle.pid;
+  }
+  /** Whether the agent process is still running. */
+  get isRunning() {
+    return this.handle.isRunning;
+  }
+  /**
+   * Send a message and wait for the response.
+   *
+   * Uses event-based waiting (via the controller's InboxPoller) instead of
+   * polling `readUnread()` directly, which avoids a race condition where the
+   * poller marks inbox messages as read before `receive()` can see them.
+   */
+  async ask(question, opts) {
+    this.ensureNotDisposed();
+    const timeout = opts?.timeout ?? 12e4;
+    const responsePromise = new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error(`Timeout (${timeout}ms) waiting for response`));
+      }, timeout);
+      const onMsg = (text) => {
+        cleanup();
+        resolve(text);
+      };
+      const onExit = (code) => {
+        cleanup();
+        reject(new Error(`Agent exited (code=${code}) before responding`));
+      };
+      const cleanup = () => {
+        clearTimeout(timer);
+        this.removeListener("message", onMsg);
+        this.removeListener("exit", onExit);
+      };
+      this.on("message", onMsg);
+      this.on("exit", onExit);
+    });
+    const wrapped = `${question}
+
+IMPORTANT: You MUST send your complete answer back using the SendMessage tool. Do NOT just think your answer \u2014 use the SendMessage tool to reply.`;
+    await this.handle.send(wrapped);
+    return responsePromise;
+  }
+  /** Send a message without waiting for a response. */
+  async send(message) {
+    this.ensureNotDisposed();
+    return this.handle.send(message);
+  }
+  /** Wait for the next response from this agent. */
+  async receive(opts) {
+    this.ensureNotDisposed();
+    const timeout = opts?.timeout ?? 12e4;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error(`Timeout (${timeout}ms) waiting for response`));
+      }, timeout);
+      const onMsg = (text) => {
+        cleanup();
+        resolve(text);
+      };
+      const onExit = (code) => {
+        cleanup();
+        reject(new Error(`Agent exited (code=${code}) before responding`));
+      };
+      const cleanup = () => {
+        clearTimeout(timer);
+        this.removeListener("message", onMsg);
+        this.removeListener("exit", onExit);
+      };
+      this.on("message", onMsg);
+      this.on("exit", onExit);
+    });
+  }
+  /**
+   * Close this agent. If standalone, shuts down the entire controller.
+   * If session-owned, kills only this agent's process.
+   */
+  async close() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unwireEvents();
+    if (this.ownsController) {
+      await this.controller.shutdown();
+    } else {
+      await this.handle.kill();
+    }
+  }
+  /** Mark as disposed (used by Session when it closes). */
+  markDisposed() {
+    this.disposed = true;
+    this.unwireEvents();
+  }
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+  wireEvents() {
+    const agentName = this.handle.name;
+    const onMessage = (name, msg) => {
+      if (name === agentName) this.emit("message", msg.text);
+    };
+    const onIdle = (name) => {
+      if (name === agentName) this.emit("idle");
+    };
+    const onPermission = (name, parsed) => {
+      if (name !== agentName) return;
+      let handled = false;
+      const guard = (fn) => () => {
+        if (handled) return Promise.resolve();
+        handled = true;
+        return fn();
+      };
+      this.emit("permission", {
+        requestId: parsed.requestId,
+        toolName: parsed.toolName,
+        description: parsed.description,
+        input: parsed.input,
+        approve: guard(
+          () => this.controller.sendPermissionResponse(agentName, parsed.requestId, true)
+        ),
+        reject: guard(
+          () => this.controller.sendPermissionResponse(agentName, parsed.requestId, false)
+        )
+      });
+    };
+    const onPlan = (name, parsed) => {
+      if (name !== agentName) return;
+      let handled = false;
+      const guard = (fn) => (...args) => {
+        if (handled) return Promise.resolve();
+        handled = true;
+        return fn(...args);
+      };
+      this.emit("plan", {
+        requestId: parsed.requestId,
+        planContent: parsed.planContent,
+        approve: guard(
+          (feedback) => this.controller.sendPlanApproval(agentName, parsed.requestId, true, feedback)
+        ),
+        reject: guard(
+          (feedback) => this.controller.sendPlanApproval(agentName, parsed.requestId, false, feedback)
+        )
+      });
+    };
+    const onExit = (name, code) => {
+      if (name === agentName) this.emit("exit", code);
+    };
+    const onError = (err) => {
+      this.emit("error", err);
+    };
+    this.controller.on("message", onMessage);
+    this.controller.on("idle", onIdle);
+    this.controller.on("permission:request", onPermission);
+    this.controller.on("plan:approval_request", onPlan);
+    this.controller.on("agent:exited", onExit);
+    this.controller.on("error", onError);
+    this.boundListeners = [
+      { event: "message", fn: onMessage },
+      { event: "idle", fn: onIdle },
+      { event: "permission:request", fn: onPermission },
+      { event: "plan:approval_request", fn: onPlan },
+      { event: "agent:exited", fn: onExit },
+      { event: "error", fn: onError }
+    ];
+  }
+  unwireEvents() {
+    for (const { event, fn } of this.boundListeners) {
+      this.controller.removeListener(event, fn);
+    }
+    this.boundListeners = [];
+  }
+  wireBehavior(behavior) {
+    if (!behavior) return;
+    const { autoApprove, onPermission, onPlan } = behavior;
+    if (autoApprove != null) {
+      this.on("permission", (req) => {
+        if (autoApprove === true) {
+          req.approve();
+        } else if (Array.isArray(autoApprove)) {
+          autoApprove.includes(req.toolName) ? req.approve() : req.reject();
+        }
+      });
+      if (autoApprove === true) {
+        this.on("plan", (req) => req.approve());
+      }
+    }
+    if (onPermission) {
+      this.on("permission", onPermission);
+    }
+    if (onPlan) {
+      this.on("plan", onPlan);
+    }
+  }
+  ensureNotDisposed() {
+    if (this.disposed) {
+      throw new Error("Agent has been closed");
+    }
+  }
+};
+var Session = class _Session {
+  controller;
+  defaults;
+  agents = /* @__PURE__ */ new Map();
+  disposed = false;
+  constructor(controller, defaults) {
+    this.controller = controller;
+    this.defaults = defaults;
+  }
+  static async create(opts = {}) {
+    const env = buildEnv(opts);
+    const controller = new ClaudeCodeController({
+      teamName: opts.teamName ?? `session-${randomUUID3().slice(0, 8)}`,
+      cwd: opts.cwd,
+      claudeBinary: opts.claudeBinary,
+      env,
+      logLevel: opts.logLevel ?? "warn",
+      logger: opts.logger
+    });
+    await controller.init();
+    return new _Session(controller, opts);
+  }
+  /** Spawn a named agent in this session. Inherits session defaults. */
+  async agent(name, opts = {}) {
+    this.ensureNotDisposed();
+    const merged = {
+      model: this.defaults.model,
+      cwd: this.defaults.cwd,
+      permissions: this.defaults.permissions,
+      readyTimeout: this.defaults.readyTimeout,
+      autoApprove: this.defaults.autoApprove,
+      onPermission: this.defaults.onPermission,
+      onPlan: this.defaults.onPlan,
+      ...opts
+    };
+    const agent = await Agent.createInSession(
+      this.controller,
+      name,
+      merged
+    );
+    this.agents.set(name, agent);
+    return agent;
+  }
+  /** Get an existing agent by name. */
+  get(name) {
+    return this.agents.get(name);
+  }
+  /** Close all agents and shut down the session. */
+  async close() {
+    if (this.disposed) return;
+    this.disposed = true;
+    for (const agent of this.agents.values()) {
+      agent.markDisposed();
+    }
+    await this.controller.shutdown();
+  }
+  async [Symbol.asyncDispose]() {
+    await this.close();
+  }
+  ensureNotDisposed() {
+    if (this.disposed) {
+      throw new Error("Session has been closed");
+    }
+  }
+};
+async function claudeCall(prompt, opts = {}) {
+  const agent = await Agent.create(opts);
+  try {
+    return await agent.ask(prompt, { timeout: opts.timeout ?? 12e4 });
+  } finally {
+    await agent.close();
+  }
+}
+var claude = Object.assign(claudeCall, {
+  /**
+   * Create a persistent agent for multi-turn conversations.
+   *
+   * @example
+   * ```ts
+   * const agent = await claude.agent({ model: "sonnet" });
+   * const answer = await agent.ask("What is 2+2?");
+   * await agent.close();
+   * ```
+   */
+  agent: (opts) => Agent.create(opts),
+  /**
+   * Create a multi-agent session.
+   *
+   * @example
+   * ```ts
+   * const session = await claude.session({ model: "sonnet" });
+   * const reviewer = await session.agent("reviewer", { model: "opus" });
+   * const coder = await session.agent("coder");
+   * await session.close();
+   * ```
+   */
+  session: (opts) => Session.create(opts)
+});
 export {
+  Agent,
   AgentHandle,
   ClaudeCodeController,
   InboxPoller,
   ProcessManager,
+  Session,
   TaskManager,
   TeamManager,
+  claude,
   createLogger,
   inboxPath,
   inboxesDir,