claude-code-controller 0.2.0 → 0.4.0

package/dist/api/index.cjs

@@ -44,7 +44,7 @@ var ActionTracker = class {
         requestId: parsed.requestId,
         timestamp: parsed.timestamp,
         planContent: parsed.planContent,
-        action: `POST /agents/${agent}/approve-plan`
+        action: `POST /agents/${agent}/approve`
       });
     };
     const onPermission = (agent, parsed) => {
@@ -55,7 +55,7 @@ var ActionTracker = class {
         timestamp: parsed.timestamp,
         toolName: parsed.toolName,
         description: parsed.description,
-        action: `POST /agents/${agent}/approve-permission`
+        action: `POST /agents/${agent}/approve`
       });
     };
     const onIdle = (agent) => {
@@ -444,6 +444,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);
@@ -811,6 +814,11 @@ function createLogger(level = "info") {
 }
 
 // src/controller.ts
+var PROTOCOL_ONLY_TYPES = /* @__PURE__ */ new Set([
+  "shutdown_approved",
+  "plan_approval_response",
+  "permission_response"
+]);
 var AGENT_COLORS = [
   "#00FF00",
   "#00BFFF",
@@ -935,6 +943,7 @@ var ClaudeCodeController = class extends import_node_events.EventEmitter {
       color,
       claudeBinary: this.claudeBinary,
       permissions: opts.permissions,
+      permissionMode: opts.permissionMode,
       env
     });
     this.emit("agent:spawned", opts.name, proc.pid ?? 0);
@@ -1003,11 +1012,7 @@ var ClaudeCodeController = class extends import_node_events.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);
@@ -1040,7 +1045,7 @@ var ClaudeCodeController = class extends import_node_events.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];
@@ -1202,6 +1207,454 @@ function sleep2(ms) {
   return new Promise((r) => setTimeout(r, ms));
 }
 
+// src/claude.ts
+var import_node_events2 = require("events");
+var import_node_crypto3 = require("crypto");
+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 import_node_events2.EventEmitter {
+  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-${(0, import_node_crypto3.randomUUID)().slice(0, 8)}`;
+    const env = buildEnv(opts);
+    const { permissionMode } = resolvePermissions(opts.permissions);
+    const controller = new ClaudeCodeController({
+      teamName: `claude-${(0, import_node_crypto3.randomUUID)().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-${(0, import_node_crypto3.randomUUID)().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)
+});
+
 // src/api/routes.ts
 var SAFE_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
 var SAFE_TASK_ID_RE = /^[0-9]{1,10}$/;
@@ -1243,6 +1696,28 @@ function buildRoutes(state) {
       session: state.controller !== null
     });
   });
+  api.post("/ask", async (c) => {
+    const body = await c.req.json();
+    if (!body.prompt) {
+      return c.json({ error: "prompt is required" }, 400);
+    }
+    try {
+      const response = await claude(body.prompt, {
+        model: body.model,
+        apiKey: body.apiKey,
+        baseUrl: body.baseUrl,
+        timeout: body.timeout,
+        cwd: body.cwd,
+        permissions: body.permissions,
+        env: body.env,
+        logLevel: "warn"
+      });
+      return c.json({ response });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Agent failed to respond";
+      return c.json({ error: message }, 500);
+    }
+  });
   api.get("/session", (c) => {
     if (!state.controller) {
       return c.json({ initialized: false, teamName: "" });
@@ -1268,11 +1743,15 @@ function buildRoutes(state) {
           await oldController.shutdown();
         }
       }
+      const env = { ...body.env };
+      if (body.apiKey) env.ANTHROPIC_AUTH_TOKEN = body.apiKey;
+      if (body.baseUrl) env.ANTHROPIC_BASE_URL = body.baseUrl;
+      if (body.timeout != null) env.API_TIMEOUT_MS = String(body.timeout);
       const controller = new ClaudeCodeController({
         teamName: body.teamName,
         cwd: body.cwd,
         claudeBinary: body.claudeBinary,
-        env: body.env,
+        env,
         logLevel: body.logLevel ?? "info"
       });
       try {
@@ -1329,26 +1808,6 @@ function buildRoutes(state) {
     const pending = approvals.length + unassignedTasks.length + idleAgents.length;
     return c.json({ pending, approvals, unassignedTasks, idleAgents });
   });
-  api.get("/actions/approvals", (_c) => {
-    getController(state);
-    return _c.json(state.tracker.getPendingApprovals());
-  });
-  api.get("/actions/tasks", async (c) => {
-    const ctrl = getController(state);
-    const tasks = await ctrl.tasks.list();
-    const unassigned = tasks.filter((t) => !t.owner && t.status !== "completed").map((t) => ({
-      id: t.id,
-      subject: t.subject,
-      description: t.description,
-      status: t.status,
-      action: `POST /tasks/${t.id}/assign`
-    }));
-    return c.json(unassigned);
-  });
-  api.get("/actions/idle-agents", (_c) => {
-    getController(state);
-    return _c.json(state.tracker.getIdleAgents());
-  });
   api.get("/agents", async (c) => {
     const ctrl = getController(state);
     const config = await ctrl.team.getConfig();
@@ -1369,13 +1828,25 @@ function buildRoutes(state) {
     validateName(body.name, "name");
     const agentType = body.type || "general-purpose";
     state.tracker.registerAgentType(body.name, agentType);
+    const agentEnv = { ...body.env };
+    if (body.apiKey) agentEnv.ANTHROPIC_AUTH_TOKEN = body.apiKey;
+    if (body.baseUrl) agentEnv.ANTHROPIC_BASE_URL = body.baseUrl;
+    if (body.timeout != null) agentEnv.API_TIMEOUT_MS = String(body.timeout);
+    const permissionsArray = Array.isArray(body.permissions) ? body.permissions : void 0;
+    const PRESET_MAP = {
+      edit: "acceptEdits",
+      plan: "plan",
+      ask: "default"
+    };
+    const permissionMode = typeof body.permissions === "string" && !Array.isArray(body.permissions) ? PRESET_MAP[body.permissions] : void 0;
     const handle = await ctrl.spawnAgent({
       name: body.name,
       type: body.type,
       model: body.model,
       cwd: body.cwd,
-      permissions: body.permissions,
-      env: body.env
+      permissions: permissionsArray,
+      permissionMode,
+      env: Object.keys(agentEnv).length > 0 ? agentEnv : void 0
     });
     return c.json(
       {
@@ -1427,7 +1898,7 @@ function buildRoutes(state) {
     await ctrl.sendShutdownRequest(name);
     return c.json({ ok: true });
   });
-  api.post("/agents/:name/approve-plan", async (c) => {
+  api.post("/agents/:name/approve", async (c) => {
     const ctrl = getController(state);
     const name = c.req.param("name");
     validateName(name, "name");
@@ -1435,28 +1906,14 @@ function buildRoutes(state) {
     if (!body.requestId) {
       return c.json({ error: "requestId is required" }, 400);
     }
-    await ctrl.sendPlanApproval(
-      name,
-      body.requestId,
-      body.approve ?? true,
-      body.feedback
-    );
-    state.tracker.resolveApproval(body.requestId);
-    return c.json({ ok: true });
-  });
-  api.post("/agents/:name/approve-permission", async (c) => {
-    const ctrl = getController(state);
-    const name = c.req.param("name");
-    validateName(name, "name");
-    const body = await c.req.json();
-    if (!body.requestId) {
-      return c.json({ error: "requestId is required" }, 400);
+    if (!body.type || !["plan", "permission"].includes(body.type)) {
+      return c.json({ error: 'type must be "plan" or "permission"' }, 400);
+    }
+    if (body.type === "plan") {
+      await ctrl.sendPlanApproval(name, body.requestId, body.approve ?? true, body.feedback);
+    } else {
+      await ctrl.sendPermissionResponse(name, body.requestId, body.approve ?? true);
     }
-    await ctrl.sendPermissionResponse(
-      name,
-      body.requestId,
-      body.approve ?? true
-    );
     state.tracker.resolveApproval(body.requestId);
     return c.json({ ok: true });
   });