@inetafrica/open-claudia 2.0.3 → 2.0.5

package/core/jobs.js

@@ -0,0 +1,99 @@
+// Unified persistent store for scheduled work — both one-shot wakeups
+// the agent set for itself ("check back in 30 min") and recurring crons
+// (user-defined or agent-defined). Survives bot restarts.
+//
+// Entry shape:
+//   {
+//     id: "job_<ts>_<rand>",
+//     kind: "wakeup" | "cron",
+//     adapter: "<adapter-id>",       // e.g. "telegram-1" / "kazee-1"
+//     adapterType: "telegram"|"kazee",
+//     channelId: "<chat or channel id>",
+//     canonicalUserId: "telegram:<id>" or "<email>",
+//     project: "<project-name>" or null,
+//     prompt: "<text to send as if user>",
+//     label: "<short>",
+//     source: "agent" | "user",
+//     // wakeup-only
+//     fireAt: <ms epoch>,
+//     // cron-only
+//     schedule: "<5-field cron>",
+//     // session pinning (per choice a/i):
+//     sessionKey: "lastSessionId" | "cursorSessionId" | "codexSessionId" | null,
+//     sessionId: "<claude-session-id>" | null,
+//     createdAt: <ms>,
+//     lastFireAt: <ms> | null,
+//     lastFireOk: true|false|null,
+//   }
+
+const fs = require("fs");
+const path = require("path");
+const { JOBS_FILE } = require("./config");
+
+function load() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(JOBS_FILE, "utf-8"));
+    return Array.isArray(raw) ? raw : [];
+  } catch (e) { return []; }
+}
+
+function save(list) {
+  fs.mkdirSync(path.dirname(JOBS_FILE), { recursive: true });
+  const tmp = `${JOBS_FILE}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(list, null, 2));
+  fs.renameSync(tmp, JOBS_FILE);
+}
+
+function nextId(kind) {
+  return `${kind}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function add(job) {
+  const list = load();
+  const entry = { createdAt: Date.now(), lastFireAt: null, lastFireOk: null, ...job };
+  if (!entry.id) entry.id = nextId(entry.kind || "job");
+  list.push(entry);
+  save(list);
+  return entry;
+}
+
+function remove(id) {
+  const list = load();
+  const idx = list.findIndex((j) => j.id === id);
+  if (idx < 0) return null;
+  const [removed] = list.splice(idx, 1);
+  save(list);
+  return removed;
+}
+
+function update(id, patch) {
+  const list = load();
+  const idx = list.findIndex((j) => j.id === id);
+  if (idx < 0) return null;
+  list[idx] = { ...list[idx], ...patch };
+  save(list);
+  return list[idx];
+}
+
+function get(id) {
+  return load().find((j) => j.id === id) || null;
+}
+
+function listForChannel(adapter, channelId) {
+  return load().filter((j) =>
+    String(j.channelId) === String(channelId) &&
+    (j.adapter === adapter || j.adapterType === adapter),
+  );
+}
+
+function listAll() { return load(); }
+
+function listByCanonicalUser(canonicalUserId) {
+  return load().filter((j) => j.canonicalUserId === canonicalUserId);
+}
+
+module.exports = {
+  load, save, add, remove, update, get,
+  listAll, listForChannel, listByCanonicalUser,
+  nextId,
+};

package/core/loopback.js

@@ -15,6 +15,9 @@ const http = require("http");
 const os = require("os");
 const crypto = require("crypto");
 const { CONFIG_DIR } = require("./config");
+const jobsStore = require("./jobs");
+const tasksStore = require("./tasks");
+const scheduler = require("./scheduler");
 
 const INFO_DIR = path.join(CONFIG_DIR, "loopback");
 const INFO_FILE = path.join(INFO_DIR, `${process.pid}.json`);
@@ -58,7 +61,173 @@ function readBodyToFile(req, dest) {
   });
 }
 
-const KINDS = new Set(["send-file", "send-voice", "send-photo"]);
+const SEND_KINDS = new Set(["send-file", "send-voice", "send-photo"]);
+const JSON_KINDS = new Set([
+  "schedule-wakeup", "cron-add", "cron-remove", "job-list",
+  "task-add", "task-plan", "task-update", "task-remove", "task-list", "task-tree", "task-clear-completed",
+]);
+
+function readBodyAsString(req, max = 64 * 1024) {
+  return new Promise((resolve, reject) => {
+    let buf = "";
+    req.on("data", (d) => {
+      buf += d.toString();
+      if (buf.length > max) {
+        req.destroy();
+        reject(new Error("body too large"));
+      }
+    });
+    req.on("end", () => resolve(buf));
+    req.on("error", reject);
+  });
+}
+
+async function handleSend(req, res, url, kind) {
+  const channelId = url.searchParams.get("channelId");
+  const adapterId = url.searchParams.get("adapter");
+  const caption = url.searchParams.get("caption") || "";
+  const fileName = url.searchParams.get("fileName") || `file-${Date.now()}.bin`;
+  if (!channelId || !adapterId) return reply(res, 400, { error: "missing channelId/adapter" });
+  const adapter = registry.findAdapter(adapterId);
+  if (!adapter) return reply(res, 400, { error: `unknown adapter ${adapterId}` });
+
+  const safeName = path.basename(fileName).replace(/[^A-Za-z0-9._-]/g, "_") || `file-${Date.now()}`;
+  const tmp = path.join(os.tmpdir(), `oc-loopback-${process.pid}-${Date.now()}-${safeName}`);
+  await readBodyToFile(req, tmp);
+
+  let ok = false;
+  try {
+    if (kind === "send-voice") {
+      ok = await adapter.sendVoice(channelId, tmp);
+    } else if (kind === "send-photo" && typeof adapter.sendPhoto === "function") {
+      ok = await adapter.sendPhoto(channelId, tmp, caption);
+    } else {
+      ok = await adapter.sendFile(channelId, tmp, caption);
+    }
+  } finally {
+    if (kind !== "send-voice") { try { fs.unlinkSync(tmp); } catch (e) {} }
+  }
+  return reply(res, ok ? 200 : 500, { ok });
+}
+
+async function handleJson(req, res, url, kind) {
+  const body = await readBodyAsString(req);
+  let payload = {};
+  if (body.trim()) {
+    try { payload = JSON.parse(body); }
+    catch (e) { return reply(res, 400, { error: "invalid JSON body" }); }
+  }
+  const channelId = String(payload.channelId || url.searchParams.get("channelId") || "");
+  const adapterId = String(payload.adapter || url.searchParams.get("adapter") || "");
+  if (!channelId || !adapterId) return reply(res, 400, { error: "missing channelId/adapter" });
+  const adapter = registry.findAdapter(adapterId);
+  if (!adapter) return reply(res, 400, { error: `unknown adapter ${adapterId}` });
+
+  if (kind === "schedule-wakeup") {
+    const fireAt = Number(payload.fireAt);
+    if (!Number.isFinite(fireAt) || fireAt <= 0) return reply(res, 400, { error: "missing/invalid fireAt" });
+    if (!payload.prompt) return reply(res, 400, { error: "missing prompt" });
+    const job = scheduler.addJob({
+      kind: "wakeup",
+      adapter: adapterId,
+      adapterType: adapter.type,
+      channelId,
+      canonicalUserId: payload.canonicalUserId || null,
+      project: payload.project || null,
+      prompt: String(payload.prompt),
+      label: String(payload.label || payload.prompt).slice(0, 60),
+      source: payload.source || "agent",
+      fireAt,
+      sessionKey: payload.sessionKey || null,
+      sessionId: payload.sessionId || null,
+    });
+    return reply(res, 200, { ok: true, job });
+  }
+
+  if (kind === "cron-add") {
+    if (!payload.schedule || !payload.prompt) return reply(res, 400, { error: "missing schedule/prompt" });
+    const job = scheduler.addJob({
+      kind: "cron",
+      adapter: adapterId,
+      adapterType: adapter.type,
+      channelId,
+      canonicalUserId: payload.canonicalUserId || null,
+      project: payload.project || null,
+      prompt: String(payload.prompt),
+      label: String(payload.label || payload.prompt).slice(0, 60),
+      source: payload.source || "agent",
+      schedule: String(payload.schedule),
+      sessionKey: payload.sessionKey || null,
+      sessionId: payload.sessionId || null,
+    });
+    return reply(res, 200, { ok: true, job });
+  }
+
+  if (kind === "cron-remove") {
+    const id = payload.id || url.searchParams.get("id");
+    if (!id) return reply(res, 400, { error: "missing id" });
+    const removed = scheduler.removeJob(id);
+    return reply(res, removed ? 200 : 404, { ok: !!removed, removed });
+  }
+
+  if (kind === "job-list") {
+    const list = jobsStore.listForChannel(adapterId, channelId);
+    return reply(res, 200, { ok: true, jobs: list });
+  }
+
+  if (kind === "task-add") {
+    if (!payload.content) return reply(res, 400, { error: "missing content" });
+    try {
+      const t = tasksStore.add(adapterId, channelId, payload.content, {
+        parentId: payload.parentId || null,
+        description: payload.description || null,
+      });
+      return reply(res, 200, { ok: true, task: t });
+    } catch (e) { return reply(res, 400, { error: e.message }); }
+  }
+
+  if (kind === "task-plan") {
+    if (!payload.title) return reply(res, 400, { error: "missing title" });
+    const subs = Array.isArray(payload.subtasks) ? payload.subtasks : [];
+    if (subs.length === 0) return reply(res, 400, { error: "subtasks must be a non-empty array" });
+    const result = tasksStore.plan(adapterId, channelId, payload.title, subs, {
+      description: payload.description || null,
+    });
+    return reply(res, 200, { ok: true, plan: result });
+  }
+
+  if (kind === "task-tree") {
+    const t = tasksStore.tree(adapterId, channelId);
+    return reply(res, 200, { ok: true, tree: t });
+  }
+
+  if (kind === "task-update") {
+    if (!payload.id) return reply(res, 400, { error: "missing id" });
+    const patch = {};
+    if (payload.status) patch.status = payload.status;
+    if (typeof payload.content === "string") patch.content = payload.content;
+    const t = tasksStore.update(adapterId, channelId, payload.id, patch);
+    return reply(res, t ? 200 : 404, { ok: !!t, task: t });
+  }
+
+  if (kind === "task-remove") {
+    if (!payload.id) return reply(res, 400, { error: "missing id" });
+    const removed = tasksStore.remove(adapterId, channelId, payload.id);
+    return reply(res, removed ? 200 : 404, { ok: !!removed, removed });
+  }
+
+  if (kind === "task-list") {
+    const list = tasksStore.list(adapterId, channelId, payload.status ? { status: payload.status } : {});
+    return reply(res, 200, { ok: true, tasks: list });
+  }
+
+  if (kind === "task-clear-completed") {
+    const remaining = tasksStore.clearCompleted(adapterId, channelId);
+    return reply(res, 200, { ok: true, tasks: remaining });
+  }
+
+  return reply(res, 404, { error: "not found" });
+}
 
 async function handle(req, res) {
   try {
@@ -66,32 +235,9 @@ async function handle(req, res) {
     if (!authOk(req)) return reply(res, 401, { error: "unauthorized" });
     const url = new URL(req.url, "http://127.0.0.1");
     const kind = url.pathname.slice(1);
-    if (!KINDS.has(kind)) return reply(res, 404, { error: "not found" });
-    const channelId = url.searchParams.get("channelId");
-    const adapterId = url.searchParams.get("adapter");
-    const caption = url.searchParams.get("caption") || "";
-    const fileName = url.searchParams.get("fileName") || `file-${Date.now()}.bin`;
-    if (!channelId || !adapterId) return reply(res, 400, { error: "missing channelId/adapter" });
-    const adapter = registry.findAdapter(adapterId);
-    if (!adapter) return reply(res, 400, { error: `unknown adapter ${adapterId}` });
-
-    const safeName = path.basename(fileName).replace(/[^A-Za-z0-9._-]/g, "_") || `file-${Date.now()}`;
-    const tmp = path.join(os.tmpdir(), `oc-loopback-${process.pid}-${Date.now()}-${safeName}`);
-    await readBodyToFile(req, tmp);
-
-    let ok = false;
-    try {
-      if (kind === "send-voice") {
-        ok = await adapter.sendVoice(channelId, tmp); // adapter unlinks on success/failure
-      } else if (kind === "send-photo" && typeof adapter.sendPhoto === "function") {
-        ok = await adapter.sendPhoto(channelId, tmp, caption);
-      } else {
-        ok = await adapter.sendFile(channelId, tmp, caption);
-      }
-    } finally {
-      if (kind !== "send-voice") { try { fs.unlinkSync(tmp); } catch (e) {} }
-    }
-    return reply(res, ok ? 200 : 500, { ok });
+    if (SEND_KINDS.has(kind)) return handleSend(req, res, url, kind);
+    if (JSON_KINDS.has(kind)) return handleJson(req, res, url, kind);
+    return reply(res, 404, { error: "not found" });
   } catch (e) {
     console.error("loopback handle error:", e.message);
     return reply(res, 500, { error: e.message });

package/core/runner.js

@@ -35,6 +35,18 @@ function chatEnvOverlay() {
   }
   const tinfo = transcriptProjectInfo();
   if (tinfo && tinfo.transcriptPath) overlay.OC_TRANSCRIPT_PATH = tinfo.transcriptPath;
+  try {
+    const state = currentState();
+    if (state) {
+      if (state.userId) overlay.OC_CANONICAL_USER_ID = String(state.userId);
+      const key = getActiveSessionKey(state);
+      const sid = state[key];
+      if (sid) {
+        overlay.OC_LAST_SESSION_ID = String(sid);
+        overlay.OC_LAST_SESSION_KEY = key;
+      }
+    }
+  } catch (e) { /* no chat context (e.g. startup) — skip */ }
   return overlay;
 }
 

package/core/scheduler.js

@@ -0,0 +1,249 @@
+// Unified scheduler — owns every timer the bot has running. Replaces
+// the old core/cron.js. Loads jobs.json on boot, schedules wakeups
+// (setTimeout) and crons (node-cron), and fires each one in the right
+// chat context with the right session pinned.
+//
+// When a wakeup fires the agent wakes up inside the SAME Claude session
+// it was in when it scheduled the wakeup (per design choice a/i). If
+// the channel is busy with a live turn the fire is deferred 30s and
+// retried. One-shot wakeups self-delete; crons persist.
+
+const path = require("path");
+const fs = require("fs");
+const cron = require("node-cron");
+
+const { CRONS_FILE, WORKSPACE, CHAT_ID } = require("./config");
+const jobs = require("./jobs");
+const { runInChat } = require("./context");
+const { getUserState, userStates } = require("./state");
+const { canonicalForTelegram, canonicalForChannel } = require("./identity");
+const { send } = require("./io");
+
+const MISSED_WAKEUP_GRACE_MS = 60 * 60 * 1000;
+const DEFER_BUSY_MS = 30 * 1000;
+
+const timers = new Map();
+let adapters = [];
+
+function setAdapters(list) {
+  adapters = Array.isArray(list) ? list.slice() : [];
+}
+
+function resolveAdapter(job) {
+  if (job.adapter) {
+    const byId = adapters.find((a) => a.id === job.adapter);
+    if (byId) return byId;
+  }
+  if (job.adapterType) {
+    const byType = adapters.find((a) => a.type === job.adapterType);
+    if (byType) return byType;
+  }
+  return adapters[0] || null;
+}
+
+function projectDir(job) {
+  if (!job.project) return null;
+  if (path.isAbsolute(job.project)) return job.project;
+  if (!WORKSPACE) return null;
+  return path.join(WORKSPACE, job.project);
+}
+
+function deriveCanonicalUserId(adapter, job) {
+  if (job.canonicalUserId) return job.canonicalUserId;
+  if (!adapter) return null;
+  return canonicalForChannel(adapter.type, job.channelId);
+}
+
+function deriveUserId(adapter, job) {
+  if (job.userId) return String(job.userId);
+  if (adapter && adapter.type === "telegram") return String(job.channelId);
+  return String(job.canonicalUserId || job.channelId || "");
+}
+
+async function fireJob(job, retry = 0) {
+  const adapter = resolveAdapter(job);
+  if (!adapter) {
+    console.error(`scheduler: no adapter for job ${job.id} (${job.label || job.kind})`);
+    return;
+  }
+  const canonicalUserId = deriveCanonicalUserId(adapter, job);
+  const userId = deriveUserId(adapter, job);
+
+  const ctx = {
+    adapter,
+    channelId: String(job.channelId),
+    canonicalUserId,
+    userId,
+    transport: adapter.type,
+    raw: null,
+  };
+
+  await runInChat(ctx, async () => {
+    const state = getUserState(canonicalUserId);
+    if (state.runningProcess) {
+      if (retry < 4) {
+        console.log(`scheduler: ${job.id} busy, deferring ${DEFER_BUSY_MS / 1000}s (retry ${retry + 1})`);
+        setTimeout(() => fireJob(job, retry + 1), DEFER_BUSY_MS);
+        return;
+      }
+      console.warn(`scheduler: ${job.id} still busy after retries, skipping`);
+      jobs.update(job.id, { lastFireAt: Date.now(), lastFireOk: false });
+      return;
+    }
+
+    const cwd = projectDir(job) || (state.currentSession && state.currentSession.dir) || WORKSPACE || process.cwd();
+    const label = job.label || (job.kind === "cron" ? "Scheduled cron" : "Scheduled wakeup");
+
+    try {
+      await send(`Wakeup: ${label}`);
+    } catch (e) { /* non-fatal */ }
+
+    const wrappedPrompt = job.kind === "cron"
+      ? `[Scheduled cron \"${label}\" fired at ${new Date().toISOString()}]\n${job.prompt}`
+      : `[Scheduled wakeup \"${label}\" fired at ${new Date().toISOString()}]\n${job.prompt}`;
+
+    const { runClaude } = require("./runner");
+    const runOpts = {};
+    if (job.sessionId) runOpts.resumeSessionId = job.sessionId;
+    try {
+      await runClaude(wrappedPrompt, cwd, null, runOpts);
+      jobs.update(job.id, { lastFireAt: Date.now(), lastFireOk: true });
+    } catch (e) {
+      console.error(`scheduler: ${job.id} run error:`, e.message);
+      jobs.update(job.id, { lastFireAt: Date.now(), lastFireOk: false });
+      try { await send(`Wakeup "${label}" failed: ${e.message}`); } catch (_) {}
+    }
+  });
+
+  if (job.kind === "wakeup") {
+    jobs.remove(job.id);
+    timers.delete(job.id);
+  }
+}
+
+function scheduleJob(job) {
+  if (timers.has(job.id)) {
+    const prev = timers.get(job.id);
+    if (prev.stop) prev.stop();
+    if (prev.timeout) clearTimeout(prev.timeout);
+    timers.delete(job.id);
+  }
+  if (job.kind === "wakeup") {
+    const delay = Math.max(0, (job.fireAt || 0) - Date.now());
+    const timeout = setTimeout(() => fireJob(job), delay);
+    timers.set(job.id, { timeout });
+  } else if (job.kind === "cron") {
+    if (!cron.validate(job.schedule)) {
+      console.error(`scheduler: invalid cron schedule for ${job.id}: ${job.schedule}`);
+      return;
+    }
+    const task = cron.schedule(job.schedule, () => fireJob(job));
+    timers.set(job.id, { stop: () => task.stop() });
+  }
+}
+
+function unscheduleJob(id) {
+  const t = timers.get(id);
+  if (!t) return;
+  if (t.stop) t.stop();
+  if (t.timeout) clearTimeout(t.timeout);
+  timers.delete(id);
+}
+
+function migrateLegacyCrons() {
+  try {
+    if (!CRONS_FILE || !fs.existsSync(CRONS_FILE)) return 0;
+    const raw = JSON.parse(fs.readFileSync(CRONS_FILE, "utf-8"));
+    if (!Array.isArray(raw) || raw.length === 0) return 0;
+    const existing = new Set(jobs.listAll().map((j) => j.id));
+    const tg = adapters.find((a) => a.type === "telegram");
+    const adapterId = tg ? tg.id : (adapters[0] && adapters[0].id);
+    const adapterType = tg ? "telegram" : (adapters[0] && adapters[0].type);
+    const channelId = tg ? (CHAT_ID || "") : "";
+    const canonicalUserId = adapterType === "telegram"
+      ? canonicalForTelegram(CHAT_ID || "")
+      : canonicalForChannel(adapterType || "", channelId);
+    let migrated = 0;
+    for (const c of raw) {
+      if (!c || !c.schedule || !c.prompt) continue;
+      if (c.id && existing.has(c.id)) continue;
+      jobs.add({
+        id: c.id || jobs.nextId("cron"),
+        kind: "cron",
+        adapter: adapterId,
+        adapterType,
+        channelId: String(channelId),
+        canonicalUserId,
+        project: c.project || null,
+        prompt: c.prompt,
+        label: c.label || (c.prompt || "").slice(0, 50),
+        source: "user",
+        schedule: c.schedule,
+        sessionKey: null,
+        sessionId: null,
+      });
+      migrated++;
+    }
+    if (migrated > 0) {
+      const backup = `${CRONS_FILE}.migrated`;
+      try { fs.renameSync(CRONS_FILE, backup); } catch (e) {}
+      console.log(`scheduler: migrated ${migrated} legacy cron(s) to jobs.json (backup: ${backup})`);
+    }
+    return migrated;
+  } catch (e) {
+    console.error("scheduler: legacy migration failed:", e.message);
+    return 0;
+  }
+}
+
+function fireMissedWakeupsOnce() {
+  const now = Date.now();
+  for (const job of jobs.listAll()) {
+    if (job.kind !== "wakeup") continue;
+    if (!job.fireAt) continue;
+    if (job.fireAt >= now) continue;
+    if (now - job.fireAt > MISSED_WAKEUP_GRACE_MS) {
+      jobs.remove(job.id);
+      continue;
+    }
+    setTimeout(() => fireJob({ ...job, label: `${job.label || "wakeup"} (missed)` }), 1000);
+  }
+}
+
+function initScheduler(adapterList) {
+  setAdapters(adapterList);
+  migrateLegacyCrons();
+  for (const job of jobs.listAll()) {
+    try { scheduleJob(job); }
+    catch (e) { console.error(`scheduler: failed to schedule ${job.id}:`, e.message); }
+  }
+  fireMissedWakeupsOnce();
+  console.log(`scheduler: loaded ${jobs.listAll().length} job(s)`);
+}
+
+function addJob(spec) {
+  const job = jobs.add(spec);
+  try { scheduleJob(job); }
+  catch (e) { console.error(`scheduler: failed to schedule new ${job.id}:`, e.message); }
+  return job;
+}
+
+function removeJob(id) {
+  unscheduleJob(id);
+  return jobs.remove(id);
+}
+
+function stopAll() {
+  for (const [id] of timers) unscheduleJob(id);
+}
+
+module.exports = {
+  setAdapters,
+  initScheduler,
+  scheduleJob,
+  unscheduleJob,
+  addJob,
+  removeJob,
+  stopAll,
+  fireJob,
+};

package/core/subagent.js

@@ -0,0 +1,109 @@
+// Sub-agents: spawn a fresh, throwaway Claude process for focused
+// research or sub-tasks. No session resume, no shared state with the
+// caller's turn — the output is captured as text and returned. The
+// caller (a parent Claude turn invoking the CLI via Bash) decides what
+// to do with the result.
+
+const { spawn } = require("child_process");
+const { CLAUDE_PATH, MAX_PROCESS_TIMEOUT, botSubprocessEnv } = require("./config");
+const { redactSensitive } = require("./redact");
+const { claudeSubprocessEnv } = require("./auth-flow");
+
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const MAX_OUTPUT_BYTES = 64 * 1024;
+
+const concurrentByChannel = new Map();
+
+function buildSubagentSystemPrompt(role) {
+  return [
+    "You are a sub-agent spawned by another Claude assistant via Open Claudia.",
+    "Your reply is captured as raw text and returned to the parent agent — there is no user reading it directly.",
+    "Stay focused on the prompt. Be concise. Return findings; do not chat.",
+    "You do not have access to the parent's chat session, files in /tmp from the parent, or the loopback send tools.",
+    "You can use Read, Glob, Grep, Bash for read-only research. Do not start long-running processes.",
+    role ? `Role: ${role}` : "",
+  ].filter(Boolean).join("\n");
+}
+
+function trackStart(channelId) {
+  if (!channelId) return 0;
+  const cur = concurrentByChannel.get(channelId) || 0;
+  concurrentByChannel.set(channelId, cur + 1);
+  return cur + 1;
+}
+
+function trackEnd(channelId) {
+  if (!channelId) return;
+  const cur = concurrentByChannel.get(channelId) || 0;
+  if (cur <= 1) concurrentByChannel.delete(channelId);
+  else concurrentByChannel.set(channelId, cur - 1);
+}
+
+function concurrentCount(channelId) {
+  return concurrentByChannel.get(channelId) || 0;
+}
+
+async function spawnSubagent(prompt, opts = {}) {
+  const cwd = opts.cwd || process.cwd();
+  const role = opts.role || null;
+  const channelId = opts.channelId || null;
+  const timeoutMs = Math.min(opts.timeoutMs || DEFAULT_TIMEOUT_MS, MAX_PROCESS_TIMEOUT || DEFAULT_TIMEOUT_MS);
+
+  const count = trackStart(channelId);
+  if (count > 3) {
+    console.warn(`subagent: ${count} concurrent sub-agents on channel ${channelId}`);
+  }
+
+  return new Promise((resolve, reject) => {
+    const args = [
+      "-p",
+      "--output-format", opts.json ? "json" : "text",
+      "--verbose",
+      "--append-system-prompt", buildSubagentSystemPrompt(role),
+      "--dangerously-skip-permissions",
+      prompt,
+    ];
+    const env = { ...botSubprocessEnv(), ...claudeSubprocessEnv() };
+    const proc = spawn(CLAUDE_PATH, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+
+    let out = "";
+    let err = "";
+    let truncated = false;
+
+    proc.stdout.on("data", (d) => {
+      if (out.length + d.length > MAX_OUTPUT_BYTES) {
+        out += d.toString().slice(0, Math.max(0, MAX_OUTPUT_BYTES - out.length));
+        truncated = true;
+      } else {
+        out += d.toString();
+      }
+    });
+    proc.stderr.on("data", (d) => {
+      if (err.length < MAX_OUTPUT_BYTES) err += d.toString();
+    });
+
+    const t = setTimeout(() => {
+      try { proc.kill("SIGTERM"); } catch (e) {}
+      reject(new Error(`subagent timed out after ${Math.round(timeoutMs / 1000)}s`));
+    }, timeoutMs);
+
+    proc.on("error", (e) => {
+      clearTimeout(t);
+      trackEnd(channelId);
+      reject(e);
+    });
+    proc.on("close", (code) => {
+      clearTimeout(t);
+      trackEnd(channelId);
+      const text = redactSensitive(out.trim());
+      const stderrText = redactSensitive(err.trim());
+      if (code !== 0 && !text) {
+        const msg = stderrText || `subagent exited with code ${code}`;
+        return reject(new Error(msg));
+      }
+      resolve({ text, truncated, stderr: stderrText, code });
+    });
+  });
+}
+
+module.exports = { spawnSubagent, concurrentCount };