@mu-crew/mu 3.4.0 → 3.5.0

package/dist/extension/mu-pi.js

@@ -51,11 +51,18 @@ var DELEGATE_CANCEL_TOOL = "mu_delegate_cancel";
 var DELEGATE_MESSAGE_TYPE = "mu-delegate";
 var DELEGATE_WORKSTREAM = "scratch";
 var DELEGATE_STATUS_KEY = "mu-delegate";
-function delegateStatus(n) {
-  return n > 0 ? `${n} delegate${n === 1 ? "" : "s"} running` : void 0;
+var PENDING_CHANNEL = "murmur:pending";
+function delegateStatus(running, starting = 0, queued = 0, failed = 0) {
+  const parts = [];
+  if (running > 0) parts.push(`${running} delegate${running === 1 ? "" : "s"} running`);
+  if (starting > 0) parts.push(`${starting} starting`);
+  if (queued > 0) parts.push(`${queued} queued`);
+  if (failed > 0) parts.push(`${failed} failed`);
+  return parts.length > 0 ? parts.join(", ") : void 0;
 }
 var DELEGATE_TIMEOUT_S = 3600;
 var DELEGATE_MAX_DEFAULT = 16;
+var DELEGATE_QUEUE_FACTOR = 4;
 function delegateMax(env = process.env) {
   const n = Number(env.MU_DELEGATE_MAX);
   return Number.isInteger(n) && n > 0 ? n : DELEGATE_MAX_DEFAULT;
@@ -106,7 +113,7 @@ function formatElapsed(ms) {
 }
 function delegateMessage(name, agent, pane, x = {}) {
   const timeoutS = x.timeoutS ?? DELEGATE_TIMEOUT_S;
-  const who = `Delegate ${W}/${name}`;
+  const who = `Delegate ${W}/${name}${x.queuedAs ? ` (queued as ${x.queuedAs})` : ""}`;
   const took = x.elapsedMs !== void 0 ? ` after ${formatElapsed(x.elapsedMs)}` : "";
   const fate = pane.closed ? "Pane closed." : `Pane kept (${pane.why}).`;
   const look = [
@@ -125,6 +132,13 @@ ${x.tail.trimEnd()}` : "";
 ${agent.lastText ?? ""}`;
     case "empty":
       return `${who} finished${took} without a text answer. ${fate}${ws}${tailBlock}`;
+    case "error":
+      return [
+        `${who} stopped on an API error${took}, after pi's own retries: ${(agent.lastError ?? "unknown error").replace(/[.\s]+$/, "")}. ${fate}${ws}`,
+        "Decide: re-issue the call, or record the check as UNVERIFIED.",
+        ...look,
+        `Close: mu agent close ${name} -w ${W}`
+      ].join("\n");
     case "died":
       return `${who} died${took} before answering. ${fate}${ws}${tailBlock}`;
     case "timeout":
@@ -147,11 +161,28 @@ function registerDelegate(pi, run = defaultRunner()) {
   if (!delegateEnabled()) return;
   const inflight = /* @__PURE__ */ new Map();
   let starting = 0;
+  const queue = [];
+  let queueSeq = 0;
+  const failed = /* @__PURE__ */ new Set();
   const reserved = /* @__PURE__ */ new Set();
   let ui;
+  let lastPending = 0;
+  const reportPending = () => {
+    const count = inflight.size + starting + queue.length;
+    if (count === lastPending) return;
+    lastPending = count;
+    try {
+      pi.events.emit(PENDING_CHANNEL, { source: DELEGATE_TOOL, count });
+    } catch {
+    }
+  };
   const showStatus = () => {
+    reportPending();
     try {
-      ui?.setStatus?.(DELEGATE_STATUS_KEY, delegateStatus(inflight.size));
+      ui?.setStatus?.(
+        DELEGATE_STATUS_KEY,
+        delegateStatus(inflight.size, starting, queue.length, failed.size)
+      );
     } catch {
     }
   };
@@ -161,8 +192,34 @@ function registerDelegate(pi, run = defaultRunner()) {
   const forget = (name) => {
     inflight.delete(name);
     reserved.delete(name);
+    drain();
     showStatus();
   };
+  function drain() {
+    while (queue.length > 0 && inflight.size + starting < delegateMax()) {
+      const q = queue.shift();
+      if (!q) break;
+      starting++;
+      void start(q.params, void 0, q.ctx, q.handle).then(
+        () => {
+        },
+        (e) => {
+          void Promise.resolve(
+            pi.sendMessage(
+              {
+                customType: DELEGATE_MESSAGE_TYPE,
+                content: `Queued delegate ${q.handle} could not start: ${e instanceof Error ? e.message : String(e)}`,
+                display: true,
+                details: { name: q.handle, workstream: W, outcome: null, closed: false }
+              },
+              { deliverAs: "followUp", triggerTurn: true }
+            )
+          ).catch(() => {
+          });
+        }
+      );
+    }
+  }
   const mu = run;
   const json = (r) => {
     try {
@@ -179,6 +236,10 @@ function registerDelegate(pi, run = defaultRunner()) {
     const taken = new Set(
       Array.isArray(agents) ? agents.map((a) => a.name).filter((n) => n) : []
     );
+    if (Array.isArray(agents)) {
+      for (const f of [...failed]) if (!taken.has(f)) failed.delete(f);
+      showStatus();
+    }
     for (let n = 1; ; n++) {
       const name = stem ? n === 1 ? `delegate-${stem}` : `delegate-${stem}-${n}` : `delegate-${n}`;
       if (!taken.has(name) && !reserved.has(name)) {
@@ -230,7 +291,7 @@ function registerDelegate(pi, run = defaultRunner()) {
   async function deliver(name, wait, keep, extras) {
     const agent = json(wait)?.agents?.[0];
     const outcome = agent?.outcome;
-    const tail = outcome === "done" || outcome === "timeout" || outcome === "pending" ? void 0 : (await mu(["agent", "read", name, "-n", "50", "-w", W])).stdout;
+    const tail = outcome === "done" || outcome === "timeout" || outcome === "pending" || outcome === "error" ? void 0 : (await mu(["agent", "read", name, "-n", "50", "-w", W])).stdout;
     let pane = { closed: false, why: "keep: true" };
     if (outcome !== "done" && outcome !== "empty")
       pane = { closed: false, why: "kept as evidence" };
@@ -238,6 +299,10 @@ function registerDelegate(pi, run = defaultRunner()) {
       const c = await mu(["agent", "close", name, "-w", W]);
       pane = c.code === 0 ? { closed: true } : { closed: false, why: `close refused: ${(c.stderr || c.stdout).trim()}` };
     }
+    if (outcome === "error" && !pane.closed) {
+      failed.add(name);
+      showStatus();
+    }
     await pi.sendMessage(
       {
         customType: DELEGATE_MESSAGE_TYPE,
@@ -256,10 +321,106 @@ function registerDelegate(pi, run = defaultRunner()) {
       { deliverAs: "followUp", triggerTurn: true }
     );
   }
+  async function start(params, signal, ctx, queuedAs) {
+    let slotHeld = true;
+    const freeSlot = () => {
+      if (slotHeld) {
+        starting--;
+        showStatus();
+      }
+      slotHeld = false;
+    };
+    showStatus();
+    try {
+      const task = typeof params.task === "string" ? params.task.trim() : "";
+      const brief = typeof params.brief === "string" ? params.brief.trim() : "";
+      const keep = params.keep === true;
+      const t = params.timeout;
+      if (t !== void 0 && !(typeof t === "number" && Number.isFinite(t) && t > 0))
+        throw new Error(
+          `mu_delegate: timeout must be a positive number of seconds (got ${JSON.stringify(t)})`
+        );
+      const timeoutS = typeof t === "number" ? Math.ceil(t) : DELEGATE_TIMEOUT_S;
+      let cwd;
+      if (params.workspace !== true) {
+        cwd = typeof params.cwd === "string" && params.cwd ? params.cwd : ctx?.cwd ?? process.cwd();
+        if (!isDir(cwd)) throw new Error(`mu_delegate: cwd ${cwd} is not a directory`);
+      }
+      const { name, attach, workspace } = await spawn(params, cwd, signal);
+      const entry = { abort: new AbortController(), cancelling: false };
+      inflight.set(name, entry);
+      freeSlot();
+      showStatus();
+      const started = Date.now();
+      const waiting = mu(
+        ["agent", "wait", name, "-w", W, "--json", "--timeout", String(timeoutS)],
+        entry.abort.signal
+      );
+      const sent = await mu(["agent", "send", name, brief ? `${brief}
+
+${task}` : task, "-w", W]);
+      if (sent.code !== 0) {
+        entry.abort.abort();
+        forget(name);
+        const c = await mu(["agent", "close", name, "-w", W]);
+        const pane = c.code === 0 ? "Pane closed." : `Pane kept; close it with: mu agent close ${name} -w ${W}`;
+        throw new Error(`${failure(`mu agent send to ${W}/${name}`, sent).message}. ${pane}`);
+      }
+      const settle = async (r) => {
+        forget(name);
+        try {
+          await deliver(name, r, keep, {
+            timeoutS,
+            elapsedMs: Date.now() - started,
+            ...queuedAs ? { queuedAs } : {},
+            ...attach ? { attach } : {},
+            ...workspace ? { workspace } : {}
+          });
+        } catch (e) {
+          await Promise.resolve(
+            pi.sendMessage(
+              {
+                customType: DELEGATE_MESSAGE_TYPE,
+                content: `Delegate ${W}/${name} settled, but delivering its answer failed: ${e instanceof Error ? e.message : String(e)}. Read it with: mu agent read ${name} -n 50 -w ${W}`,
+                display: true,
+                details: { name, workstream: W, outcome: null, closed: false }
+              },
+              { deliverAs: "followUp", triggerTurn: true }
+            )
+          ).catch(() => {
+          });
+        }
+      };
+      void waiting.then(async (r) => {
+        if (inflight.get(name) !== entry) return;
+        if (entry.cancelling) entry.parked = () => settle(r);
+        else await settle(r);
+      });
+      const lines = [
+        `Delegated to ${W}/${name}. Its answer arrives as a follow-up message when it finishes; do not wait or poll.`,
+        workspace ? `Workspace: ${workspace}` : void 0,
+        attach ? `Attach: ${attach}` : void 0,
+        `Cancel: ${DELEGATE_CANCEL_TOOL} { name: "${name}" }`
+      ].filter((x) => x !== void 0);
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: {
+          name,
+          workstream: W,
+          attach: attach ?? null,
+          workspace: workspace ?? null,
+          keep
+        }
+      };
+    } finally {
+      freeSlot();
+      if (queuedAs) drain();
+    }
+  }
   pi.registerTool({
     name: DELEGATE_TOOL,
     label: "mu delegate",
-    description: `Subagent: run one self-contained task in a fresh pi agent (its own mux pane in mu's ${W} workstream) while you keep working. Use it whenever you would reach for a subagent: research, a review, a draft, an investigation; call it several times to fan out in parallel (at most ${delegateMax()} in flight). The subagent starts with no context, in your working directory: put everything it needs in task. The call returns at once and the answer arrives later as a follow-up message: carry on with other work, or end your turn if your next step needs the answer (the follow-up resumes you). The pane closes after a clean finish; keep: true leaves it open.`,
+    description: `Subagent: run one self-contained task in a fresh pi agent (its own mux pane in mu's ${W} workstream) while you keep working. Use it whenever you would reach for a subagent: research, a review, a draft, an investigation; call it several times to fan out in parallel (at most ${delegateMax()} run at once; up to ${DELEGATE_QUEUE_FACTOR * delegateMax()} more are queued and start as slots free). The subagent starts with no context, in your working directory: put everything it needs in task. The call returns at once and the answer arrives later as a follow-up message: carry on with other work, or end your turn if your next step needs the answer (the follow-up resumes you). The pane closes after a clean finish; keep: true leaves it open.`,
     promptSnippet: "Subagent: delegate a self-contained task to a background pi agent; its answer arrives later as a follow-up",
     parameters: {
       type: "object",
@@ -302,106 +463,43 @@ function registerDelegate(pi, run = defaultRunner()) {
       track(ctx);
       const task = typeof params.task === "string" ? params.task.trim() : "";
       if (!task) throw new Error("mu_delegate needs a non-empty task");
-      const max = delegateMax();
-      if (inflight.size + starting >= max)
+      const t = params.timeout;
+      if (t !== void 0 && !(typeof t === "number" && Number.isFinite(t) && t > 0))
         throw new Error(
-          `mu_delegate: ${inflight.size + starting} delegates already running (MU_DELEGATE_MAX=${max}). End your turn; issue the rest as answers arrive (each answer resumes you).`
+          `mu_delegate: timeout must be a positive number of seconds (got ${JSON.stringify(t)})`
         );
-      starting++;
-      let slotHeld = true;
-      const freeSlot = () => {
-        if (slotHeld) starting--;
-        slotHeld = false;
-      };
-      try {
-        const brief = typeof params.brief === "string" ? params.brief.trim() : "";
-        const keep = params.keep === true;
-        const t = params.timeout;
-        if (t !== void 0 && !(typeof t === "number" && Number.isFinite(t) && t > 0))
-          throw new Error(
-            `mu_delegate: timeout must be a positive number of seconds (got ${JSON.stringify(t)})`
-          );
-        const timeoutS = typeof t === "number" ? Math.ceil(t) : DELEGATE_TIMEOUT_S;
-        let cwd;
-        if (params.workspace !== true) {
-          cwd = typeof params.cwd === "string" && params.cwd ? params.cwd : ctx?.cwd ?? process.cwd();
-          if (!isDir(cwd)) throw new Error(`mu_delegate: cwd ${cwd} is not a directory`);
-        }
-        const { name, attach, workspace } = await spawn(params, cwd, signal);
-        const entry = { abort: new AbortController(), cancelling: false };
-        inflight.set(name, entry);
-        freeSlot();
-        showStatus();
-        const started = Date.now();
-        const waiting = mu(
-          ["agent", "wait", name, "-w", W, "--json", "--timeout", String(timeoutS)],
-          entry.abort.signal
+      if (params.workspace !== true) {
+        const cwd = typeof params.cwd === "string" && params.cwd ? params.cwd : ctx?.cwd ?? process.cwd();
+        if (!isDir(cwd)) throw new Error(`mu_delegate: cwd ${cwd} is not a directory`);
+      }
+      const max = delegateMax();
+      if (inflight.size + starting < max) {
+        starting++;
+        return start(params, signal, ctx);
+      }
+      if (queue.length >= DELEGATE_QUEUE_FACTOR * max)
+        throw new Error(
+          `mu_delegate: ${inflight.size + starting} running and ${queue.length} queued (MU_DELEGATE_MAX=${max}). End your turn; issue the rest as answers arrive (each answer resumes you).`
         );
-        const sent = await mu([
-          "agent",
-          "send",
-          name,
-          brief ? `${brief}
-
-${task}` : task,
-          "-w",
-          W
-        ]);
-        if (sent.code !== 0) {
-          entry.abort.abort();
-          forget(name);
-          const c = await mu(["agent", "close", name, "-w", W]);
-          const pane = c.code === 0 ? "Pane closed." : `Pane kept; close it with: mu agent close ${name} -w ${W}`;
-          throw new Error(`${failure(`mu agent send to ${W}/${name}`, sent).message}. ${pane}`);
-        }
-        const settle = async (r) => {
-          forget(name);
-          try {
-            await deliver(name, r, keep, {
-              timeoutS,
-              elapsedMs: Date.now() - started,
-              ...attach ? { attach } : {},
-              ...workspace ? { workspace } : {}
-            });
-          } catch (e) {
-            await Promise.resolve(
-              pi.sendMessage(
-                {
-                  customType: DELEGATE_MESSAGE_TYPE,
-                  content: `Delegate ${W}/${name} settled, but delivering its answer failed: ${e instanceof Error ? e.message : String(e)}. Read it with: mu agent read ${name} -n 50 -w ${W}`,
-                  display: true,
-                  details: { name, workstream: W, outcome: null, closed: false }
-                },
-                { deliverAs: "followUp", triggerTurn: true }
-              )
-            ).catch(() => {
-            });
-          }
-        };
-        void waiting.then(async (r) => {
-          if (inflight.get(name) !== entry) return;
-          if (entry.cancelling) entry.parked = () => settle(r);
-          else await settle(r);
-        });
-        const lines = [
-          `Delegated to ${W}/${name}. Its answer arrives as a follow-up message when it finishes; do not wait or poll.`,
-          workspace ? `Workspace: ${workspace}` : void 0,
-          attach ? `Attach: ${attach}` : void 0,
-          `Cancel: ${DELEGATE_CANCEL_TOOL} { name: "${name}" }`
-        ].filter((x) => x !== void 0);
-        return {
-          content: [{ type: "text", text: lines.join("\n") }],
-          details: {
-            name,
-            workstream: W,
-            attach: attach ?? null,
-            workspace: workspace ?? null,
-            keep
+      const handle = `queued-${++queueSeq}`;
+      queue.push({
+        handle,
+        params: {
+          ...params,
+          cwd: typeof params.cwd === "string" && params.cwd ? params.cwd : ctx?.cwd ?? process.cwd()
+        },
+        ctx
+      });
+      showStatus();
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Queued as ${handle} (#${queue.length}; ${inflight.size + starting} running, MU_DELEGATE_MAX=${max}). It starts when a slot frees, and its answer arrives as a follow-up message like any delegate's; do not wait or poll. Cancel: ${DELEGATE_CANCEL_TOOL} { name: "${handle}" }`
           }
-        };
-      } finally {
-        freeSlot();
-      }
+        ],
+        details: { name: handle, workstream: W, queued: true, position: queue.length }
+      };
     }
   });
   pi.registerTool({
@@ -421,6 +519,15 @@ ${task}` : task,
       track(ctx);
       const name = typeof params.name === "string" ? params.name : "";
       if (!name) throw new Error("mu_delegate_cancel needs a name");
+      const qi = queue.findIndex((q) => q.handle === name);
+      if (qi >= 0) {
+        queue.splice(qi, 1);
+        showStatus();
+        return {
+          content: [{ type: "text", text: `Dropped ${name} from the queue; it never started.` }],
+          details: { name, workstream: W }
+        };
+      }
       const entry = inflight.get(name);
       if (entry) entry.cancelling = true;
       const ab = await mu(["agent", "abort", name, "-w", W]);
@@ -437,6 +544,7 @@ ${task}` : task,
         entry.abort.abort();
         forget(name);
       }
+      failed.delete(name);
       let text = `Aborted ${W}/${name}.`;
       if (params.keep === true) text += " Pane kept.";
       else {
@@ -447,13 +555,21 @@ ${task}` : task,
     }
   });
   pi.on("session_shutdown", (_e, ctx) => {
-    if (inflight.size === 0) return;
+    if (inflight.size === 0 && queue.length === 0) return;
     const names = [...inflight.keys()];
+    const never = queue.splice(0).map((q) => q.handle);
     for (const e of inflight.values()) e.abort.abort();
     inflight.clear();
     showStatus();
     ui = void 0;
-    const msg = `${names.length} delegate${names.length === 1 ? "" : "s"} still running: ${names.join(", ")}. Their answers will not come back here; use mu agent wait <name> -w ${W} --json.`;
+    const parts = [];
+    if (names.length > 0)
+      parts.push(
+        `${names.length} delegate${names.length === 1 ? "" : "s"} still running: ${names.join(", ")}. Their answers will not come back here; use mu agent wait <name> -w ${W} --json.`
+      );
+    if (never.length > 0)
+      parts.push(`${never.length} queued, never started: ${never.join(", ")}. Re-issue them.`);
+    const msg = parts.join(" ");
     if (ctx?.hasUI && ctx.ui) ctx.ui.notify(msg, "warning");
     else process.stderr.write(`mu: ${msg}
 `);
@@ -590,7 +706,7 @@ function registerNudge(pi, run = defaultRunner(), skillMd = readSkill()) {
 }
 
 // extension/mu-pi.ts
-var EXT_VERSION = true ? "3.4.0" : void 0;
+var EXT_VERSION = true ? "3.5.0" : void 0;
 var FRESH_COMMAND = "mu-fresh";
 var FRESH_TIMEOUT_MS = 3e4;
 function commandName(name) {
@@ -661,6 +777,19 @@ function lastAssistantText(event) {
   }
   return "";
 }
+function lastAssistantError(event) {
+  const msgs = typeof event === "object" && event !== null ? event.messages : void 0;
+  if (!Array.isArray(msgs)) return void 0;
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const m = msgs[i];
+    if (typeof m !== "object" || m === null) continue;
+    const { role, stopReason, errorMessage } = m;
+    if (role !== "assistant") continue;
+    if (stopReason !== "error") return void 0;
+    return typeof errorMessage === "string" && errorMessage !== "" ? capText(errorMessage) : "unknown error";
+  }
+  return void 0;
+}
 function capText(text) {
   if (Buffer.byteLength(text, "utf8") <= LAST_TEXT_MAX_BYTES) return text;
   const cut = Buffer.from(text, "utf8").subarray(0, LAST_TEXT_MAX_BYTES).toString("utf8");
@@ -768,6 +897,7 @@ function serveCtl(pi) {
   });
   pi.on("agent_end", (e) => {
     g.endText = lastAssistantText(e);
+    g.endError = lastAssistantError(e);
   });
   pi.on("agent_settled", (_e, c) => {
     g.ctx = c;
@@ -776,6 +906,8 @@ function serveCtl(pi) {
     g.runs++;
     g.lastText = g.endText ?? "";
     g.endText = void 0;
+    g.lastError = g.endError;
+    g.endError = void 0;
     for (const w of [...g.waiters]) w();
   });
   pi.registerCommand(FRESH_COMMAND, {
@@ -914,9 +1046,13 @@ function serveCtl(pi) {
         return { ...fail(`${UNKNOWN_OP_PREFIX}${String(req.op)}`), ops: [...CTL_OPS] };
     }
   }
+  const settledRun = () => ({
+    lastText: g.lastText,
+    ...g.lastError !== void 0 ? { lastError: g.lastError } : {}
+  });
   function wait(afterRuns, timeoutMs, conn) {
     if (afterRuns !== void 0 && g.runs > afterRuns && g.state === "idle") {
-      return Promise.resolve({ v: V, ok: true, ...status(), lastText: g.lastText });
+      return Promise.resolve({ v: V, ok: true, ...status(), ...settledRun() });
     }
     return new Promise((resolve) => {
       let timer;
@@ -926,7 +1062,7 @@ function serveCtl(pi) {
         conn.off("close", onClose);
         resolve(r);
       };
-      const waiter = () => done({ v: V, ok: true, ...status(), lastText: g.lastText });
+      const waiter = () => done({ v: V, ok: true, ...status(), ...settledRun() });
       const onClose = () => done(fail("client closed"));
       g.waiters.add(waiter);
       conn.on("close", onClose);
@@ -1041,6 +1177,7 @@ export {
   LIVE_PROBE_MS,
   commandName,
   muPi as default,
+  lastAssistantError,
   lastAssistantText,
   promptsDir
 };