@brutalsystems/muster 0.1.0

package/dist/run.js

@@ -0,0 +1,424 @@
+import { stat, readFile, writeFile, mkdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+import { loadConfig } from "./config.js";
+import { runSchema, launchArgs, launchEnv } from "./guard.js";
+import { Registry } from "./registry.js";
+import { LaunchLog } from "./log.js";
+import { hosts, selectHost } from "./hosts/index.js";
+import { processRef, isSame, stopTree, delay, descendants, } from "./identity/processes.js";
+import { resolveCodex } from "./identity/codex.js";
+import { resolveClaude } from "./identity/claude.js";
+import { codexReachable } from "./reach/codex.js";
+import { claudeReachable } from "./reach/claude.js";
+import { assertClaudePolicy } from "./claude-policy.js";
+import { codexPolicyArgs } from "./codex-policy.js";
+import { CodexRpc } from "./codex-rpc.js";
+import { assignNames, resolvePeer } from "./naming.js";
+export class Muster {
+    config;
+    home;
+    env;
+    drivers;
+    registry;
+    log;
+    owned = new Set();
+    closing = false;
+    active = new Set();
+    constructor(config, home, env, drivers) {
+        this.config = config;
+        this.home = home;
+        this.env = env;
+        this.drivers = drivers;
+        this.registry = new Registry(home);
+        this.log = new LaunchLog(home);
+    }
+    static async create(opts = {}) {
+        const env = launchEnv(opts.env ?? process.env), home = opts.home ?? join(env.HOME ?? homedir(), ".muster");
+        return new Muster(await loadConfig(home), home, env, opts.drivers ?? hosts());
+    }
+    run(input, requester = "cli") {
+        if (this.closing)
+            return Promise.reject(new Error("Muster is closing"));
+        const operation = this.launch(input, requester);
+        this.active.add(operation);
+        return operation.finally(() => this.active.delete(operation));
+    }
+    async launch(input, requester) {
+        const req = runSchema.parse(input);
+        if (!(await stat(req.cwd)).isDirectory())
+            throw new Error("cwd is not a directory");
+        if (req.kind === "task" && req.host)
+            throw new Error("host applies only to session launches");
+        const argv = launchArgs(req, this.config), driver = req.kind === "session"
+            ? await selectHost(req.host ?? this.config.host, this.drivers)
+            : undefined;
+        let policy = [];
+        if (req.runtime === "claude")
+            await assertClaudePolicy(this.env);
+        const reservation = await this.registry.reserve(req, this.config.max_concurrent);
+        this.owned.add(reservation.launchId);
+        let entry = reservation;
+        const startedAt = Date.now();
+        const deadline = startedAt + this.config.launch_timeout_sec * 1000;
+        let rpc;
+        try {
+            await this.log.write({
+                event: "intent",
+                launch_id: entry.launchId,
+                runtime: req.runtime,
+                kind: req.kind,
+                cwd: req.cwd,
+                prompt: req.prompt,
+                host: driver?.id ?? null,
+                requester,
+                args: req.args,
+            });
+            if (req.runtime === "codex") {
+                policy = await codexPolicyArgs(this.env, req.cwd, deadline);
+                argv.splice(1, 0, ...policy);
+            }
+            if (this.closing)
+                throw new Error("Launch cancelled: Muster is closing");
+            if (req.kind === "task")
+                return await this.startTask(entry, argv);
+            const launched = await driver.launch({
+                argv,
+                cwd: req.cwd,
+                env: this.env,
+                label: req.prompt.slice(0, 48),
+                deadline,
+            });
+            const root = await processRef(launched.pid);
+            if (!root) {
+                await driver.stop(launched.hostRef);
+                throw new Error("process exited during launch");
+            }
+            entry = { ...entry, root, host: driver.id, hostRef: launched.hostRef };
+            await this.registry.update(entry.launchId, entry);
+            let diagnostic = req.runtime === "claude"
+                ? "no Claude session registry found (check terminal for workspace trust or login prompts)"
+                : "no descendant runtime identity found";
+            if (req.runtime === "codex")
+                rpc = new CodexRpc(this.env, req.cwd, policy);
+            while (Date.now() < deadline) {
+                if (deadline - Date.now() < 25)
+                    break;
+                if (await isSame(root)) {
+                    const tracked = (await Promise.all((await descendants(root.pid)).map(processRef))).filter((p) => !!p);
+                    const refs = [...(entry.descendants ?? [])];
+                    for (const ref of tracked)
+                        if (!refs.some((r) => r.pid === ref.pid && r.start === ref.start))
+                            refs.push(ref);
+                    if (refs.length !== (entry.descendants ?? []).length) {
+                        entry = { ...entry, descendants: refs };
+                        await this.registry.update(entry.launchId, { descendants: refs });
+                    }
+                }
+                if (this.closing)
+                    throw new Error("Launch cancelled: Muster is closing");
+                if (!(await isSame(root)))
+                    throw new Error(`process exited at ${((Date.now() - startedAt) / 1000).toFixed(2)}s`);
+                try {
+                    const identity = req.runtime === "codex"
+                        ? await resolveCodex(root.pid, this.env, deadline)
+                        : await resolveClaude(root.pid, this.env, deadline);
+                    if (identity) {
+                        diagnostic =
+                            req.runtime === "codex"
+                                ? "thread id reserved but no rollout"
+                                : "registry exists but inbox socket is not accepting connections";
+                        let metadata;
+                        if (req.runtime === "codex")
+                            metadata = await codexReachable(rpc, identity.id, deadline);
+                        else {
+                            const claude = identity;
+                            if (!(await claudeReachable(claude.socketPath, deadline)))
+                                throw new Error(diagnostic);
+                            metadata = claude;
+                        }
+                        if (Date.now() >= deadline)
+                            throw new Error("readiness completed after launch deadline");
+                        if (!(await isSame(root)) || !(await processRef(identity.pid)))
+                            throw new Error("process exited before readiness completed");
+                        const runtime = req.runtime === "codex" ? "codex" : "claude-code";
+                        const named = assignNames([
+                            { runtime, uuid: identity.id, rawName: metadata.rawName },
+                        ])[0];
+                        const peer = {
+                            kind: "session",
+                            name: named.display,
+                            canonical_id: named.canonicalId,
+                            runtime,
+                            state: metadata.state,
+                            cwd: req.cwd,
+                            ...(req.runtime === "codex"
+                                ? { thread_id: identity.id }
+                                : { session_id: identity.id }),
+                            pid: identity.pid,
+                            host: driver.id,
+                            capabilities: driver.capabilities(),
+                            attach_hint: driver.attachHint(launched.hostRef),
+                        };
+                        entry = await this.registry.update(entry.launchId, {
+                            id: identity.id,
+                            status: "running",
+                            peer,
+                        });
+                        await this.log.write({
+                            event: "ready",
+                            launch_id: entry.launchId,
+                            peer,
+                        });
+                        return peer;
+                    }
+                }
+                catch (e) {
+                    if (Date.now() < deadline)
+                        diagnostic = e.message;
+                }
+                await delay(Math.min(250, Math.max(0, deadline - Date.now())));
+            }
+            throw new Error(`${diagnostic} after ${this.config.launch_timeout_sec}s`);
+        }
+        catch (e) {
+            await this.stopEntry(entry).catch(() => { });
+            const message = e.message;
+            await this.registry.update(entry.launchId, {
+                status: "failed",
+                error: message,
+            });
+            await this.log
+                .write({ event: "failure", launch_id: entry.launchId, error: message })
+                .catch(() => { });
+            throw e;
+        }
+        finally {
+            await rpc?.close();
+        }
+    }
+    async startTask(entry, argv) {
+        const dir = join(this.home, "tasks", entry.id);
+        await mkdir(dir, { recursive: true, mode: 0o700 });
+        const outputPath = join(dir, "output.txt"), exitPath = join(dir, "exit.json"), startPath = join(dir, "start"), specPath = join(dir, "launch.json");
+        await writeFile(specPath, JSON.stringify({
+            argv,
+            cwd: entry.cwd,
+            env: this.env,
+            outputPath,
+            exitPath,
+            startPath,
+            logHome: this.home,
+            launchId: entry.launchId,
+        }), { mode: 0o600 });
+        const child = spawn(process.execPath, [
+            fileURLToPath(new URL("../dist/task-worker.js", import.meta.url)),
+            specPath,
+        ], { detached: true, stdio: "ignore" });
+        await new Promise((resolve, reject) => {
+            child.once("spawn", resolve);
+            child.once("error", reject);
+        });
+        const root = await processRef(child.pid);
+        if (!root) {
+            child.kill();
+            throw new Error("task owner exited during launch");
+        }
+        try {
+            await this.registry.update(entry.launchId, {
+                root,
+                outputPath,
+                exitPath,
+                status: "running",
+            });
+            await writeFile(startPath, "start", { mode: 0o600 });
+            child.unref();
+            const handle = {
+                kind: "task",
+                id: entry.id,
+                runtime: entry.runtime,
+                state: "running",
+                cwd: entry.cwd,
+                pid: root.pid,
+            };
+            await this.log.write({
+                event: "started",
+                launch_id: entry.launchId,
+                run: handle,
+            });
+            return handle;
+        }
+        catch (e) {
+            await stopTree(root);
+            await rm(specPath, { force: true });
+            throw e;
+        }
+    }
+    async stopEntry(entry) {
+        if (!entry.root)
+            return;
+        if (!(await isSame(entry.root))) {
+            for (const ref of entry.descendants ?? [])
+                await stopTree(ref);
+            return;
+        }
+        // Validate the persisted process identity before ever using a window reference.
+        const driver = this.drivers.find((d) => d.id === entry.host);
+        if (driver &&
+            entry.hostRef &&
+            (await driver.list()).some((s) => s.hostRef === entry.hostRef && s.pid === entry.root.pid))
+            await driver.stop(entry.hostRef);
+        else
+            await stopTree(entry.root);
+        for (const ref of entry.descendants ?? [])
+            await stopTree(ref);
+    }
+    async find(id) {
+        const all = await this.registry.all();
+        const exact = all.filter((e) => e.id === id);
+        if (exact.length === 1)
+            return exact[0];
+        if (exact.length > 1)
+            throw new Error(`Ambiguous durable id: ${exact.map((e) => e.runtime + ":" + e.id).join(", ")}`);
+        const peers = all.filter((e) => e.kind === "session" && e.status === "running" && e.peer);
+        const named = peers.map((e) => ({
+            runtime: e.runtime === "codex" ? "codex" : "claude-code",
+            uuid: e.id,
+            rawName: String(e.peer.name),
+            slug: String(e.peer.canonical_id)
+                .split(":")[1]
+                .replace(/\.[^.]*$/, ""),
+            suffix: String(e.peer.canonical_id).split(".").at(-1),
+            canonicalId: String(e.peer.canonical_id),
+            display: String(e.peer.name),
+        }));
+        const result = resolvePeer(named, id);
+        if (!result.ok)
+            throw new Error(`${result.reason}: ${result.candidates.join(", ")}`);
+        return peers[named.indexOf(result.peer)];
+    }
+    async stop(id) {
+        const entry = await this.find(id);
+        await this.stopEntry(entry);
+        await this.registry.update(entry.launchId, { status: "stopped" });
+        await this.log.write({ event: "stopped", launch_id: entry.launchId });
+        return { stopped: true, id: entry.id };
+    }
+    async refreshed(entry) {
+        if (entry.kind !== "session" ||
+            entry.status !== "running" ||
+            !entry.root ||
+            !entry.peer)
+            return entry;
+        const deadline = Date.now() + 1500;
+        let rpc;
+        try {
+            let metadata;
+            if (entry.runtime === "codex") {
+                rpc = new CodexRpc(this.env, entry.cwd);
+                metadata = await codexReachable(rpc, entry.id, deadline);
+            }
+            else {
+                const identity = await resolveClaude(entry.root.pid, this.env, deadline);
+                if (!identity ||
+                    identity.id !== entry.id ||
+                    !(await claudeReachable(identity.socketPath, deadline)))
+                    throw new Error("session unreachable");
+                metadata = identity;
+            }
+            const named = assignNames([
+                {
+                    runtime: entry.runtime === "codex" ? "codex" : "claude-code",
+                    uuid: entry.id,
+                    rawName: metadata.rawName,
+                },
+            ])[0];
+            return await this.registry.update(entry.launchId, {
+                peer: {
+                    ...entry.peer,
+                    state: metadata.state,
+                    name: named.display,
+                    canonical_id: named.canonicalId,
+                },
+            });
+        }
+        catch {
+            return await this.registry.update(entry.launchId, {
+                peer: { ...entry.peer, state: "unreachable" },
+            });
+        }
+        finally {
+            await rpc?.close();
+        }
+    }
+    async list(kind) {
+        const entries = await this.registry.all();
+        const result = [];
+        for (const original of entries) {
+            if (kind && kind !== original.kind)
+                continue;
+            const e = await this.refreshed(original);
+            if (e.kind === "session")
+                result.push({
+                    ...e.peer,
+                    kind: "session",
+                    id: e.id,
+                    runtime: e.peer?.runtime ?? e.runtime,
+                    state: e.status === "running" ? (e.peer?.state ?? "idle") : e.status,
+                    host: e.host,
+                    ...(e.error ? { error: e.error } : {}),
+                });
+            else {
+                let exit;
+                try {
+                    exit = JSON.parse(await readFile(e.exitPath, "utf8"));
+                }
+                catch { }
+                result.push({
+                    kind: "task",
+                    id: e.id,
+                    runtime: e.runtime,
+                    cwd: e.cwd,
+                    state: exit ? "exited" : e.status,
+                    ...(e.root ? { pid: e.root.pid } : {}),
+                    ...(exit ? { exit_code: exit.code, signal: exit.signal } : {}),
+                    ...(e.error ? { error: e.error } : {}),
+                });
+            }
+        }
+        return result;
+    }
+    async output(id) {
+        const entry = await this.find(id);
+        if (entry.kind !== "task")
+            throw new Error("output is available only for task runs");
+        if (!entry.outputPath)
+            return "";
+        try {
+            return await readFile(entry.outputPath, "utf8");
+        }
+        catch (e) {
+            if (e.code === "ENOENT")
+                return "";
+            throw e;
+        }
+    }
+    async close() {
+        this.closing = true;
+        await Promise.allSettled([...this.active]);
+        for (const entry of await this.registry.all())
+            if (entry.host === "pty" &&
+                this.owned.has(entry.launchId) &&
+                entry.status === "running") {
+                await this.stopEntry(entry);
+                await this.registry.update(entry.launchId, { status: "stopped" });
+            }
+    }
+    async hasOwnedPty() {
+        return (await this.registry.all()).some((e) => e.host === "pty" &&
+            this.owned.has(e.launchId) &&
+            e.status === "running");
+    }
+}

package/dist/task-worker.js

@@ -0,0 +1,65 @@
+// A per-task owner captures output and the exit result; no pools, retries or daemon.
+import { readFile, writeFile, rm, open } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { delay, finishOwnedGroup, processRef, stopTree, } from "./identity/processes.js";
+import { LaunchLog } from "./log.js";
+const file = process.argv[2];
+const spec = JSON.parse(await readFile(file, "utf8"));
+await rm(file);
+// The parent records ownership before authorizing the runtime to start.
+const deadline = Date.now() + 10000;
+while (true) {
+    try {
+        await readFile(spec.startPath);
+        await rm(spec.startPath);
+        break;
+    }
+    catch {
+        if (Date.now() > deadline)
+            process.exit(1);
+        await delay(25);
+    }
+}
+const output = await open(spec.outputPath, "a", 0o600);
+const child = spawn(spec.argv[0], spec.argv.slice(1), {
+    cwd: spec.cwd,
+    env: spec.env,
+    stdio: ["ignore", output.fd, output.fd],
+});
+let finished = false;
+async function finish(code, signal, error) {
+    if (finished)
+        return;
+    finished = true;
+    try {
+        await output.close();
+        await new LaunchLog(spec.logHome).write({
+            event: "task_exit",
+            launch_id: spec.launchId,
+            exit_code: code,
+            signal,
+            error,
+        });
+    }
+    finally {
+        try {
+            await writeFile(spec.exitPath, JSON.stringify({ code, signal, error }), {
+                mode: 0o600,
+            });
+        }
+        finally {
+            await finishOwnedGroup(code ?? 1);
+        }
+    }
+}
+child.once("error", (e) => void finish(null, null, e.message));
+child.once("exit", (code, signal) => void finish(code, signal));
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"])
+    process.once(signal, () => {
+        void (async () => {
+            const ref = child.pid ? await processRef(child.pid) : undefined;
+            if (ref)
+                await stopTree(ref);
+            await finish(null, signal);
+        })();
+    });

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@brutalsystems/muster",
+  "version": "0.1.0",
+  "description": "Launch instructed, reachable local agent sessions",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12"
+  },
+  "bin": {
+    "muster": "dist/muster.js"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/prepare-bin.mjs",
+    "test": "vitest run",
+    "test:contract": "MUSTER_CONTRACT=1 vitest run test/contract.test.ts",
+    "postinstall": "node scripts/prepare-pty.mjs",
+    "pretest": "npm run build",
+    "pretest:contract": "npm run build",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "dependencies": {
+    "@iarna/toml": "^2.2.5",
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "node-pty": "^1.1.0",
+    "zod": "^3.25.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "prettier": "^3.9.8",
+    "typescript": "~5.9.0",
+    "vitest": "^4.1.11"
+  },
+  "license": "MIT",
+  "author": "Mike Williams",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "codex",
+    "agents",
+    "agent-launcher"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/BrutalSystems/muster.git"
+  },
+  "bugs": {
+    "url": "https://github.com/BrutalSystems/muster/issues"
+  },
+  "homepage": "https://github.com/BrutalSystems/muster#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "scripts/prepare-pty.mjs",
+    "README.md",
+    "LICENSE",
+    "TINCAN_LICENSE",
+    "CANONICAL_ID.md",
+    "CONTRACT_PROVENANCE.md",
+    "test/fixtures/canonical-id.json"
+  ]
+}

package/scripts/prepare-pty.mjs

@@ -0,0 +1,19 @@
+// node-pty 1.1.0's macOS prebuilt helper ships without its executable bit.
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { chmod, stat } from "node:fs/promises";
+if (process.platform === "darwin") {
+  const require = createRequire(import.meta.url);
+  const root = dirname(require.resolve("node-pty/package.json"));
+  for (const file of [
+    join(root, "prebuilds", `darwin-${process.arch}`, "spawn-helper"),
+    join(root, "build", "Release", "spawn-helper"),
+  ]) {
+    try {
+      const info = await stat(file);
+      await chmod(file, info.mode | 0o111);
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+  }
+}