@mu-crew/mu 3.0.0 → 3.2.0

package/dist/extension/mu-pi.js

@@ -0,0 +1,653 @@
+// extension/mu-pi.ts
+import {
+  chmodSync,
+  existsSync as existsSync2,
+  linkSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  rmSync,
+  statSync
+} from "fs";
+import { connect, createServer } from "net";
+import { dirname, join as join2 } from "path";
+
+// src/ctl/protocol.ts
+var CTL_PROTOCOL_VERSION = 1;
+var CTL_OPS = [
+  "hello",
+  "status",
+  "send",
+  "wait",
+  "abort",
+  "fresh"
+];
+var UNKNOWN_OP_PREFIX = "unknown op: ";
+function encode(msg) {
+  return `${JSON.stringify(msg)}
+`;
+}
+var LineDecoder = class {
+  buf = "";
+  push(chunk) {
+    this.buf += chunk;
+    const parts = this.buf.split("\n");
+    this.buf = parts.pop() ?? "";
+    return parts;
+  }
+};
+
+// extension/delegate.ts
+import { execFile } from "child_process";
+import { existsSync } from "fs";
+import { delimiter, join } from "path";
+import { fileURLToPath } from "url";
+var DELEGATE_TOOL = "mu_delegate";
+var DELEGATE_CANCEL_TOOL = "mu_delegate_cancel";
+var DELEGATE_MESSAGE_TYPE = "mu-delegate";
+var DELEGATE_WORKSTREAM = "scratch";
+var DELEGATE_TIMEOUT_S = 3600;
+var W = DELEGATE_WORKSTREAM;
+function delegateEnabled(env = process.env) {
+  if (env.MU_MANAGED_AGENT) return false;
+  if (env.MU_DELEGATE === "0") return false;
+  if (env.MU_MUX || env.HERDR_ENV === "1" || env.TMUX || env.TMUX_PANE) return true;
+  return onPath("tmux", env) || onPath("herdr", env);
+}
+function onPath(bin, env) {
+  return (env.PATH ?? "").split(delimiter).some((d) => d !== "" && existsSync(join(d, bin)));
+}
+function defaultRunner() {
+  let cli;
+  try {
+    const p = fileURLToPath(new URL("../cli.js", import.meta.url));
+    if (existsSync(p)) cli = p;
+  } catch {
+  }
+  return (args, signal) => new Promise((resolve) => {
+    const [cmd, argv] = cli ? [process.execPath, [cli, ...args]] : ["mu", [...args]];
+    execFile(
+      cmd,
+      argv,
+      { maxBuffer: 16 * 1024 * 1024, ...signal ? { signal } : {} },
+      (err, stdout, stderr) => {
+        const code = err ? typeof err.code === "number" ? err.code : 1 : 0;
+        resolve({ code, stdout: String(stdout), stderr: String(stderr || err?.message || "") });
+      }
+    );
+  });
+}
+function delegateMessage(name, agent, pane, tail, attach) {
+  const who = `Delegate ${W}/${name}`;
+  const fate = pane.closed ? "Pane closed." : `Pane kept (${pane.why}).`;
+  const look = [
+    attach ? `Attach: ${attach}` : void 0,
+    `Read: mu agent read ${name} -n 50 -w ${W}`
+  ].filter((x) => x !== void 0);
+  const tailBlock = tail?.trim() ? `
+
+Pane tail:
+${tail.trimEnd()}` : "";
+  switch (agent?.outcome) {
+    case "done":
+      return `${who} finished. ${fate}
+
+${agent.lastText ?? ""}`;
+    case "empty":
+      return `${who} finished without a text answer. ${fate}${tailBlock}`;
+    case "died":
+      return `${who} died before answering. ${fate}${tailBlock}`;
+    case "timeout":
+    case "pending":
+      return [
+        `${who} is still running after ${DELEGATE_TIMEOUT_S}s; stopped waiting. ${fate}`,
+        ...look,
+        `Wait again: mu agent wait ${name} -w ${W} --json`
+      ].join("\n");
+    default:
+      return `${who}: mu agent wait gave no result. ${fate}${tailBlock}`;
+  }
+}
+function registerDelegate(pi, run = defaultRunner()) {
+  if (!delegateEnabled()) return;
+  const inflight = /* @__PURE__ */ new Map();
+  const reserved = /* @__PURE__ */ new Set();
+  const mu = run;
+  const json = (r) => {
+    try {
+      const v = JSON.parse(r.stdout);
+      return typeof v === "object" && v !== null ? v : void 0;
+    } catch {
+      return void 0;
+    }
+  };
+  const failure = (what, r) => new Error(`${what} failed (exit ${r.code}): ${(r.stderr || r.stdout).trim()}`);
+  async function pickName() {
+    const r = await mu(["agent", "list", "-w", W, "--json"]);
+    const agents = json(r)?.agents;
+    const taken = new Set(
+      Array.isArray(agents) ? agents.map((a) => a.name).filter((n) => n) : []
+    );
+    for (let n = 1; ; n++) {
+      const name = `delegate-${n}`;
+      if (!taken.has(name) && !reserved.has(name)) {
+        reserved.add(name);
+        return name;
+      }
+    }
+  }
+  async function spawn(params) {
+    for (let attempt = 0; ; attempt++) {
+      const name = await pickName();
+      const args = ["agent", "spawn", name, "-w", W, "--json"];
+      if (params.workspace === true) args.push("--workspace");
+      if (typeof params.cli === "string" && params.cli) args.push("--cli", params.cli);
+      const r = await mu(args);
+      if (r.code !== 0 && /already exists/.test(r.stderr) && attempt < 3) continue;
+      if (r.code !== 0) {
+        reserved.delete(name);
+        throw failure("mu agent spawn", r);
+      }
+      const out = json(r) ?? {};
+      if (out.ctl !== "ok") {
+        reserved.delete(name);
+        throw new Error(
+          `${W}/${name} spawned but its control socket is ${String(out.ctl)}, so its answer cannot come back. Pane kept; close it with: mu agent close ${name} -w ${W}`
+        );
+      }
+      const steps = Array.isArray(out.nextSteps) ? out.nextSteps : [];
+      const attach = steps.map((s) => s).find((s) => s.intent === "Attach the pane")?.command;
+      return { name, ...typeof attach === "string" ? { attach } : {} };
+    }
+  }
+  async function deliver(name, wait, keep, attach) {
+    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;
+    let pane = { closed: false, why: "keep: true" };
+    if (outcome !== "done" && outcome !== "empty")
+      pane = { closed: false, why: "kept as evidence" };
+    else if (!keep) {
+      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()}` };
+    }
+    await pi.sendMessage(
+      {
+        customType: DELEGATE_MESSAGE_TYPE,
+        content: delegateMessage(name, agent, pane, tail, attach),
+        display: true,
+        details: { name, workstream: W, outcome: outcome ?? null, closed: pane.closed }
+      },
+      { deliverAs: "followUp", triggerTurn: true }
+    );
+  }
+  pi.registerTool({
+    name: DELEGATE_TOOL,
+    label: "mu delegate",
+    description: `Hand one self-contained task to a fresh pi agent in its own mux pane (mu's ${W} workstream) and keep working. Returns at once; the delegate's final answer arrives later as a follow-up message, so do not wait or poll for it. Use it for independent side work (research, a review, a draft, an investigation) you would otherwise do serially. The delegate starts with no context: put everything it needs in task. Several calls run in parallel. The pane is closed after a clean finish unless keep is true; the user can attach to it meanwhile.`,
+    promptSnippet: "Delegate a self-contained task to a background pi agent; its answer arrives later",
+    parameters: {
+      type: "object",
+      properties: {
+        task: { type: "string", description: "The complete task, with all context it needs" },
+        brief: {
+          type: "string",
+          description: "Optional persona or ground rules, sent before the task"
+        },
+        workspace: {
+          type: "boolean",
+          description: "Give it its own VCS workspace (for tasks that edit files)"
+        },
+        cli: {
+          type: "string",
+          description: "Agent CLI key; resolves $MU_<CLI>_COMMAND (default pi)"
+        },
+        keep: {
+          type: "boolean",
+          description: "Keep the pane after it finishes, to talk to it again"
+        }
+      },
+      required: ["task"],
+      additionalProperties: false
+    },
+    async execute(_id, params) {
+      const task = typeof params.task === "string" ? params.task.trim() : "";
+      if (!task) throw new Error("mu_delegate needs a non-empty task");
+      const brief = typeof params.brief === "string" ? params.brief.trim() : "";
+      const keep = params.keep === true;
+      const { name, attach } = await spawn(params);
+      const entry = { abort: new AbortController(), cancelled: false };
+      inflight.set(name, entry);
+      const waiting = mu(
+        ["agent", "wait", name, "-w", W, "--json", "--timeout", String(DELEGATE_TIMEOUT_S)],
+        entry.abort.signal
+      );
+      const sent = await mu(["agent", "send", name, brief ? `${brief}
+
+${task}` : task, "-w", W]);
+      if (sent.code !== 0) {
+        entry.abort.abort();
+        inflight.delete(name);
+        throw failure(`mu agent send to ${W}/${name}`, sent);
+      }
+      void waiting.then(async (r) => {
+        if (inflight.get(name) !== entry || entry.cancelled) return;
+        inflight.delete(name);
+        reserved.delete(name);
+        await deliver(name, r, keep, attach);
+      });
+      const lines = [
+        `Delegated to ${W}/${name}. Its answer arrives as a follow-up message when it finishes; do not wait or poll.`,
+        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, keep }
+      };
+    }
+  });
+  pi.registerTool({
+    name: DELEGATE_CANCEL_TOOL,
+    label: "mu delegate cancel",
+    description: `Stop a delegate started by ${DELEGATE_TOOL}: abort its turn and close its pane (keep: true leaves the pane open). No follow-up message is sent for it afterwards.`,
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Delegate name, e.g. delegate-1" },
+        keep: { type: "boolean", description: "Leave the pane open after aborting" }
+      },
+      required: ["name"],
+      additionalProperties: false
+    },
+    async execute(_id, params) {
+      const name = typeof params.name === "string" ? params.name : "";
+      if (!name) throw new Error("mu_delegate_cancel needs a name");
+      const entry = inflight.get(name);
+      if (entry) entry.cancelled = true;
+      const ab = await mu(["agent", "abort", name, "-w", W]);
+      if (ab.code !== 0) {
+        if (entry) entry.cancelled = false;
+        throw failure(`mu agent abort ${W}/${name}`, ab);
+      }
+      entry?.abort.abort();
+      inflight.delete(name);
+      reserved.delete(name);
+      let text = `Aborted ${W}/${name}.`;
+      if (params.keep === true) text += " Pane kept.";
+      else {
+        const c = await mu(["agent", "close", name, "-w", W]);
+        text += c.code === 0 ? " Pane closed." : ` Pane kept: close refused: ${(c.stderr || c.stdout).trim()}`;
+      }
+      return { content: [{ type: "text", text }], details: { name, workstream: W } };
+    }
+  });
+  pi.on("session_shutdown", (_e, ctx) => {
+    if (inflight.size === 0) return;
+    const names = [...inflight.keys()];
+    for (const e of inflight.values()) e.abort.abort();
+    inflight.clear();
+    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.`;
+    if (ctx?.hasUI && ctx.ui) ctx.ui.notify(msg, "warning");
+    else process.stderr.write(`mu: ${msg}
+`);
+  });
+}
+
+// extension/mu-pi.ts
+var EXT_VERSION = true ? "3.2.0" : void 0;
+var FRESH_COMMAND = "mu-fresh";
+var FRESH_TIMEOUT_MS = 3e4;
+var LAST_TEXT_MAX_BYTES = 64 * 1024;
+var LAST_TEXT_TRUNCATED = "[truncated, see pane]";
+var LIVE_PROBE_MS = 500;
+var V = CTL_PROTOCOL_VERSION;
+function fail(error) {
+  return { v: V, ok: false, error };
+}
+function detectPiVersion() {
+  try {
+    const entry = process.argv[1];
+    if (!entry) return void 0;
+    let dir = dirname(realpathSync(entry));
+    for (let i = 0; i < 6; i++) {
+      const pkgPath = join2(dir, "package.json");
+      if (existsSync2(pkgPath)) {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+        if (typeof pkg === "object" && pkg !== null) {
+          const { name, version } = pkg;
+          if (typeof name === "string" && /pi/.test(name) && typeof version === "string") {
+            return version;
+          }
+        }
+      }
+      const up = dirname(dir);
+      if (up === dir) break;
+      dir = up;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function str(o, k) {
+  const x = o[k];
+  return typeof x === "string" ? x : void 0;
+}
+function num(o, k) {
+  const x = o[k];
+  return typeof x === "number" && Number.isFinite(x) ? x : void 0;
+}
+var SHARED = /* @__PURE__ */ Symbol.for("mu.pi.ctl");
+function sharedMap() {
+  const g = globalThis;
+  g[SHARED] ??= /* @__PURE__ */ new Map();
+  return g[SHARED];
+}
+function lastAssistantText(event) {
+  const msgs = typeof event === "object" && event !== null ? event.messages : void 0;
+  if (!Array.isArray(msgs)) return "";
+  for (let i = msgs.length - 1; i >= 0; i--) {
+    const m = msgs[i];
+    if (typeof m !== "object" || m === null) continue;
+    const { role, content } = m;
+    if (role !== "assistant") continue;
+    if (typeof content === "string") return capText(content);
+    if (!Array.isArray(content)) return "";
+    const parts = content.flatMap((c) => {
+      if (typeof c !== "object" || c === null) return [];
+      const { type, text } = c;
+      return type === "text" && typeof text === "string" ? [text] : [];
+    });
+    return capText(parts.join(""));
+  }
+  return "";
+}
+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");
+  return `${cut.replace(/\uFFFD$/, "")}
+${LAST_TEXT_TRUNCATED}`;
+}
+function inodeOf(path) {
+  try {
+    return statSync(path).ino;
+  } catch {
+    return void 0;
+  }
+}
+function socketIsLive(path) {
+  return new Promise((resolve) => {
+    const c = connect(path);
+    const done = (live) => {
+      clearTimeout(timer);
+      c.destroy();
+      resolve(live);
+    };
+    const timer = setTimeout(() => done(true), LIVE_PROBE_MS);
+    c.once("connect", () => done(true));
+    c.once(
+      "error",
+      (e) => done(e.code !== "ENOENT" && e.code !== "ECONNREFUSED")
+    );
+  });
+}
+var bindSeq = 0;
+function reasonOf(event) {
+  const r = typeof event === "object" && event !== null ? event.reason : void 0;
+  return typeof r === "string" ? r : void 0;
+}
+function muPi(pi) {
+  registerDelegate(pi);
+  serveCtl(pi);
+}
+function serveCtl(pi) {
+  const sock = process.env.MU_CTL_SOCK;
+  if (!sock) return;
+  const sockPath = sock;
+  const piVersion = detectPiVersion();
+  const map = sharedMap();
+  const existing = map.get(sockPath);
+  const g = existing ?? {
+    conns: /* @__PURE__ */ new Set(),
+    waiters: /* @__PURE__ */ new Set(),
+    state: "idle",
+    since: Date.now(),
+    runs: 0,
+    lastText: "",
+    pi,
+    handle
+  };
+  g.pi = pi;
+  g.handle = handle;
+  map.set(sockPath, g);
+  const status = () => ({
+    state: g.state,
+    since: g.since,
+    runs: g.runs,
+    pending: g.ctx?.hasPendingMessages() ?? false
+  });
+  const settleFresh = (r) => {
+    const f = g.fresh;
+    if (!f) return;
+    g.fresh = void 0;
+    f.settle(r);
+  };
+  pi.on("agent_start", (_e, c) => {
+    g.ctx = c;
+    g.state = "busy";
+    g.since = Date.now();
+    if (g.fresh?.armed) settleFresh({ v: V, ok: true, ...status() });
+  });
+  pi.on("agent_end", (e) => {
+    g.endText = lastAssistantText(e);
+  });
+  pi.on("agent_settled", (_e, c) => {
+    g.ctx = c;
+    g.state = "idle";
+    g.since = Date.now();
+    g.runs++;
+    g.lastText = g.endText ?? "";
+    g.endText = void 0;
+    for (const w of [...g.waiters]) w();
+  });
+  pi.registerCommand(FRESH_COMMAND, {
+    description: "mu internal: new session + the prompt mu queued (run by mu agent send --fresh)",
+    handler: async (_args, ctx) => {
+      const f = g.fresh;
+      if (!f) return;
+      try {
+        const r = await ctx.newSession({
+          withSession: async (c) => {
+            g.ctx = c;
+            f.armed = true;
+            await c.sendUserMessage(f.text);
+          }
+        });
+        if (r.cancelled) settleFresh(fail("new session was cancelled"));
+      } catch (e) {
+        settleFresh(fail(e instanceof Error ? e.message : String(e)));
+      }
+      settleFresh({ v: V, ok: true, ...status() });
+    }
+  });
+  function fresh(req) {
+    const text = str(req, "text");
+    if (text === void 0) return fail("fresh needs a string text");
+    if (g.fresh) return fail("a fresh send is already in progress");
+    const busy = !(g.ctx?.isIdle() ?? g.state === "idle");
+    if (busy && req.force !== true) return fail("busy");
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => settleFresh(fail("fresh timed out")), FRESH_TIMEOUT_MS);
+      g.fresh = {
+        text,
+        armed: false,
+        settle: (r) => {
+          clearTimeout(timer);
+          resolve(r);
+        }
+      };
+      Promise.resolve(
+        g.pi.sendUserMessage(`/${FRESH_COMMAND}`, { expandPromptTemplates: true })
+      ).catch((e) => settleFresh(fail(e instanceof Error ? e.message : String(e))));
+    });
+  }
+  async function handle(req, conn) {
+    switch (req.op) {
+      case "hello":
+        return {
+          v: V,
+          ok: true,
+          agent: process.env.MU_AGENT_NAME,
+          workstream: process.env.MU_WORKSTREAM,
+          piVersion,
+          ops: [...CTL_OPS],
+          ...EXT_VERSION !== void 0 ? { extVersion: EXT_VERSION } : {}
+        };
+      case "status":
+        return { v: V, ok: true, ...status() };
+      case "send": {
+        const text = str(req, "text");
+        if (text === void 0) return fail("send needs a string text");
+        const mode = req.mode === "steer" ? "steer" : "followUp";
+        if (g.ctx?.isIdle() ?? g.state === "idle") await g.pi.sendUserMessage(text);
+        else await g.pi.sendUserMessage(text, { deliverAs: mode });
+        return { v: V, ok: true, state: g.state };
+      }
+      case "fresh":
+        return fresh(req);
+      case "wait":
+        return wait(num(req, "afterRuns"), num(req, "timeoutMs"), conn);
+      case "abort":
+        if (!g.ctx) return fail("no pi context yet");
+        g.ctx.abort();
+        return { v: V, ok: true, state: g.state };
+      default:
+        return { ...fail(`${UNKNOWN_OP_PREFIX}${String(req.op)}`), ops: [...CTL_OPS] };
+    }
+  }
+  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 new Promise((resolve) => {
+      let timer;
+      const done = (r) => {
+        g.waiters.delete(waiter);
+        if (timer) clearTimeout(timer);
+        conn.off("close", onClose);
+        resolve(r);
+      };
+      const waiter = () => done({ v: V, ok: true, ...status(), lastText: g.lastText });
+      const onClose = () => done(fail("client closed"));
+      g.waiters.add(waiter);
+      conn.on("close", onClose);
+      if (timeoutMs !== void 0) timer = setTimeout(() => done(fail("timeout")), timeoutMs);
+    });
+  }
+  function onConnection(conn) {
+    g.conns.add(conn);
+    conn.setEncoding("utf8");
+    const dec = new LineDecoder();
+    let seen = false;
+    conn.on("close", () => g.conns.delete(conn));
+    conn.on("error", () => {
+    });
+    conn.on("data", (chunk) => {
+      const line = dec.push(chunk)[0];
+      if (line === void 0 || seen) return;
+      seen = true;
+      let req;
+      try {
+        req = JSON.parse(line);
+      } catch {
+        conn.end(encode(fail("bad json")));
+        return;
+      }
+      if (typeof req !== "object" || req === null) {
+        conn.end(encode(fail("request must be an object")));
+        return;
+      }
+      g.handle(req, conn).then(
+        (r) => {
+          if (!conn.destroyed) conn.end(encode(r));
+        },
+        (e) => {
+          if (!conn.destroyed) conn.end(encode(fail(e instanceof Error ? e.message : String(e))));
+        }
+      );
+    });
+  }
+  async function bind() {
+    mkdirSync(dirname(sockPath), { recursive: true, mode: 448 });
+    if (await socketIsLive(sockPath)) {
+      process.stderr.write(
+        `mu: control socket ${sockPath} is served by another pi; this pi will not take it
+`
+      );
+      return;
+    }
+    rmSync(sockPath, { force: true });
+    const tmp = join2(dirname(sockPath), `.${process.pid.toString(36)}${(++bindSeq).toString(36)}`);
+    rmSync(tmp, { force: true });
+    const s = createServer(onConnection);
+    await new Promise((resolve, reject) => {
+      s.once("error", reject);
+      s.listen(tmp, () => {
+        s.off("error", reject);
+        resolve();
+      });
+    });
+    chmodSync(tmp, 384);
+    try {
+      linkSync(tmp, sockPath);
+    } catch (e) {
+      s.close();
+      if (e.code !== "EEXIST") throw e;
+      process.stderr.write(`mu: control socket ${sockPath} was taken by another pi
+`);
+      return;
+    } finally {
+      rmSync(tmp, { force: true });
+    }
+    g.server = s;
+    g.ino = inodeOf(sockPath);
+  }
+  pi.on("session_start", async (_e, c) => {
+    g.ctx = c;
+    const s = g.server;
+    if (s) {
+      if (g.ino !== void 0 && inodeOf(sockPath) === g.ino) return;
+      g.server = void 0;
+      g.ino = void 0;
+      s.close();
+    }
+    await bind();
+  });
+  pi.on("session_shutdown", async (e) => {
+    const reason = reasonOf(e);
+    if (reason === "new" || reason === "resume" || reason === "fork" || reason === "reload") {
+      return;
+    }
+    const s = g.server;
+    const ino = g.ino;
+    g.server = void 0;
+    g.ino = void 0;
+    map.delete(sockPath);
+    if (!s) return;
+    g.waiters.clear();
+    settleFresh(fail("pi is shutting down"));
+    for (const c of g.conns) c.destroy();
+    await new Promise((resolve) => s.close(() => resolve()));
+    if (ino !== void 0 && inodeOf(sockPath) === ino) rmSync(sockPath, { force: true });
+  });
+}
+export {
+  FRESH_COMMAND,
+  FRESH_TIMEOUT_MS,
+  LAST_TEXT_MAX_BYTES,
+  LAST_TEXT_TRUNCATED,
+  LIVE_PROBE_MS,
+  muPi as default,
+  lastAssistantText
+};
+//# sourceMappingURL=mu-pi.js.map