@brutalsystems/muster 0.1.0

package/dist/muster.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { Muster } from "./run.js";
+import { runSchema } from "./guard.js";
+import { delay } from "./identity/processes.js";
+const listSchema = z
+    .object({ kind: z.enum(["session", "task"]).optional() })
+    .strict();
+const idSchema = z.object({ id: z.string().min(1) }).strict();
+const help = `Usage:
+  muster run <codex|claude> --prompt TEXT [--cwd DIR] [--kind session|task] [--host ID] [-- RUNTIME_OPTIONS]
+  muster list [--kind session|task]
+  muster stop <id>
+  muster output <id>
+  muster mcp
+
+pty launches print their record and keep this process running. Ctrl-C stops the
+owned pty session. tmux launches survive this process exiting.
+MCP: install deliberately in the one authorized session, never at user scope.
+`;
+const text = (value) => ({
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+});
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv[0] === "--help" || argv[0] === "-h") {
+        process.stdout.write(help);
+        return;
+    }
+    const mcp = argv.length === 0 || argv[0] === "mcp";
+    if (mcp && argv.length > 1)
+        throw new Error("mcp takes no arguments");
+    const muster = await Muster.create();
+    let shutdown;
+    const close = () => (shutdown ??= (async () => {
+        await muster.close();
+    })());
+    for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"])
+        process.once(signal, () => {
+            void close().then(() => process.exit(0), (e) => {
+                process.stderr.write(String(e) + "\n");
+                process.exit(1);
+            });
+        });
+    if (mcp) {
+        const server = new Server({ name: "muster", version: "0.1.0" }, { capabilities: { tools: {} } });
+        server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: "run",
+                    description: "Launch an instructed agent. Sessions return only when reachable; tasks return a non-messageable run handle.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            runtime: { type: "string", enum: ["codex", "claude"] },
+                            prompt: { type: "string", minLength: 1 },
+                            cwd: { type: "string" },
+                            kind: {
+                                type: "string",
+                                enum: ["session", "task"],
+                                default: "session",
+                            },
+                            host: {
+                                type: "string",
+                                enum: ["auto", "tmux", "pty", "macos-terminal"],
+                            },
+                            args: { type: "array", items: { type: "string" } },
+                        },
+                        required: ["runtime", "prompt"],
+                        additionalProperties: false,
+                    },
+                },
+                {
+                    name: "list",
+                    description: "List Muster-owned sessions and tasks, including host capabilities.",
+                    inputSchema: {
+                        type: "object",
+                        properties: { kind: { type: "string", enum: ["session", "task"] } },
+                        additionalProperties: false,
+                    },
+                },
+                {
+                    name: "stop",
+                    description: "Stop a Muster-owned run by durable id or unambiguous peer name.",
+                    inputSchema: {
+                        type: "object",
+                        properties: { id: { type: "string", minLength: 1 } },
+                        required: ["id"],
+                        additionalProperties: false,
+                    },
+                },
+                {
+                    name: "output",
+                    description: "Read captured output from a task run.",
+                    inputSchema: {
+                        type: "object",
+                        properties: { id: { type: "string", minLength: 1 } },
+                        required: ["id"],
+                        additionalProperties: false,
+                    },
+                },
+            ],
+        }));
+        server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+            try {
+                const args = params.arguments ?? {};
+                switch (params.name) {
+                    case "run":
+                        return text(await muster.run(runSchema.parse(args), `mcp:${server.getClientVersion()?.name ?? "unknown"}`));
+                    case "list":
+                        return text(await muster.list(listSchema.parse(args).kind));
+                    case "stop":
+                        return text(await muster.stop(idSchema.parse(args).id));
+                    case "output":
+                        return text(await muster.output(idSchema.parse(args).id));
+                    default:
+                        throw new Error(`Unknown tool ${params.name}`);
+                }
+            }
+            catch (e) {
+                return {
+                    content: [{ type: "text", text: e.message }],
+                    isError: true,
+                };
+            }
+        });
+        server.onclose = () => {
+            void close().catch((e) => {
+                process.stderr.write(String(e) + "\n");
+                process.exitCode = 1;
+            });
+        };
+        server.onerror = (e) => process.stderr.write(`[muster] ${e.message}\n`);
+        await server.connect(new StdioServerTransport());
+        return;
+    }
+    try {
+        const command = argv.shift();
+        const { values, positionals } = parseArgs({
+            args: argv,
+            allowPositionals: true,
+            strict: true,
+            options: {
+                prompt: { type: "string" },
+                cwd: { type: "string" },
+                kind: { type: "string" },
+                host: { type: "string" },
+            },
+        });
+        if (command === "run") {
+            const runtime = positionals[0];
+            const args = positionals.slice(1);
+            const record = await muster.run({ runtime, ...values, args });
+            process.stdout.write(JSON.stringify(record) + "\n");
+            if (record.kind === "session" && record.host === "pty") {
+                process.stderr.write("[muster] pty: not watchable or attachable; this process owns the session. Ctrl-C stops it.\n");
+                while (await muster.hasOwnedPty())
+                    await delay(250);
+            }
+        }
+        else if (command === "list") {
+            if (positionals.length)
+                throw new Error("list takes no positional arguments");
+            process.stdout.write(JSON.stringify(await muster.list(listSchema.parse(values).kind)) + "\n");
+        }
+        else if (command === "stop" || command === "output") {
+            if (positionals.length !== 1 || Object.keys(values).length)
+                throw new Error(`${command} requires exactly one id`);
+            const { id } = idSchema.parse({ id: positionals[0] });
+            if (command === "stop")
+                process.stdout.write(JSON.stringify(await muster.stop(id)) + "\n");
+            else
+                process.stdout.write(await muster.output(id));
+        }
+        else
+            throw new Error(help);
+    }
+    finally {
+        await close();
+    }
+}
+main().catch((e) => {
+    process.stderr.write(`[muster] ${e.message}\n`);
+    process.exitCode = 1;
+});

package/dist/naming.js

@@ -0,0 +1,68 @@
+/** Vendored from Tin Can src/naming.ts at fbaaea5842fd4a5c86849d7f51c8e16b8683b058 (MIT). */
+/** Peer naming per the handoff §7: slug for humans, canonical id for the log. */
+export function slugify(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * The last three hex characters, not the first. Codex thread ids are UUIDv7:
+ * their leading hex is a shared timestamp, so every live thread on a machine
+ * starts with the same three characters and a leading suffix disambiguates
+ * nothing. The trailing characters are random in both v4 and v7.
+ */
+export function suffixOf(uuid) {
+    return uuid
+        .replace(/[^0-9a-f]/gi, "")
+        .slice(-3)
+        .toLowerCase();
+}
+export function assignNames(peers) {
+    const slugs = peers.map((peer) => {
+        const s = peer.rawName ? slugify(peer.rawName) : "";
+        return s.length > 0 ? s : "thread";
+    });
+    const counts = new Map();
+    for (const s of slugs)
+        counts.set(s, (counts.get(s) ?? 0) + 1);
+    return peers.map((peer, i) => {
+        const slug = slugs[i];
+        const suffix = suffixOf(peer.uuid);
+        const qualified = `${slug}.${suffix}`;
+        // An unnamed thread has no name to stand on, so it always carries its suffix.
+        const collides = (counts.get(slug) ?? 0) > 1 || peer.rawName === null;
+        return {
+            ...peer,
+            slug,
+            suffix,
+            canonicalId: `${peer.runtime}:${qualified}`,
+            display: collides ? qualified : slug,
+        };
+    });
+}
+export function resolvePeer(peers, input) {
+    const q = input.trim().toLowerCase();
+    const qualified = (p) => `${p.slug}.${p.suffix}`;
+    const exact = peers.filter((p) => p.display.toLowerCase() === q ||
+        qualified(p) === q ||
+        p.canonicalId.toLowerCase() === q);
+    if (exact.length === 1)
+        return { ok: true, peer: exact[0] };
+    if (exact.length > 1)
+        return { ok: false, reason: "ambiguous", candidates: exact.map(qualified) };
+    const prefixed = peers.filter((p) => p.slug.startsWith(q) || qualified(p).startsWith(q));
+    if (prefixed.length === 1)
+        return { ok: true, peer: prefixed[0] };
+    if (prefixed.length > 1)
+        return {
+            ok: false,
+            reason: "ambiguous",
+            candidates: prefixed.map(qualified),
+        };
+    return {
+        ok: false,
+        reason: "unknown",
+        candidates: peers.map((p) => p.display),
+    };
+}

package/dist/reach/claude.js

@@ -0,0 +1,18 @@
+import net from "node:net";
+export function claudeReachable(socketPath, deadline) {
+    return new Promise((resolve) => {
+        const conn = net.createConnection(socketPath);
+        let settled = false;
+        const timer = setTimeout(() => finish(false), Math.max(1, Math.min(250, deadline - Date.now())));
+        function finish(result) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            conn.destroy();
+            resolve(result);
+        }
+        conn.once("connect", () => finish(true));
+        conn.once("error", () => finish(false));
+    });
+}

package/dist/reach/codex.js

@@ -0,0 +1,25 @@
+export async function codexReachable(rpc, id, deadline) {
+    const { thread } = await rpc.call("thread/read", { threadId: id }, deadline);
+    if (!thread || thread.id !== id)
+        throw new Error("thread/read returned no matching thread");
+    if (thread.source === "exec")
+        throw new Error("source is exec, not a messageable session");
+    if (thread.ephemeral === true || thread.canAcceptDirectInput === false)
+        throw new Error("thread cannot accept direct input");
+    const listing = await rpc.call("thread/list", { limit: 100, useStateDbOnly: true }, deadline);
+    const metadata = Array.isArray(listing.data)
+        ? listing.data.find((t) => t.id === id)
+        : undefined;
+    // Tin Can derives names from thread/list rather than thread/read.
+    const rawName = typeof metadata?.name === "string" && metadata.name !== ""
+        ? metadata.name
+        : null;
+    const status = metadata?.status ?? thread.status;
+    const state = status === "idle" ||
+        status === undefined ||
+        status?.type === "idle" ||
+        status?.type === "notLoaded"
+        ? "idle"
+        : "busy";
+    return { rawName, state: state };
+}

package/dist/registry.js

@@ -0,0 +1,105 @@
+import { mkdir, readFile, writeFile, rename, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { processRef, isSame, delay, } from "./identity/processes.js";
+export class Registry {
+    home;
+    constructor(home) {
+        this.home = home;
+    }
+    async transaction(fn) {
+        await mkdir(this.home, { recursive: true, mode: 0o700 });
+        const lock = join(this.home, "registry.lock");
+        const deadline = Date.now() + 5000;
+        while (true) {
+            try {
+                await mkdir(lock);
+                break;
+            }
+            catch (e) {
+                if (e.code !== "EEXIST")
+                    throw e;
+                if (Date.now() > deadline)
+                    throw new Error("Registry locked; verify no Muster operation is running before removing registry.lock");
+                await delay(20);
+            }
+        }
+        try {
+            let entries = [];
+            try {
+                const value = JSON.parse(await readFile(join(this.home, "registry.json"), "utf8"));
+                if (!Array.isArray(value))
+                    throw new Error("Invalid registry");
+                entries = value;
+            }
+            catch (e) {
+                if (e.code !== "ENOENT")
+                    throw e;
+            }
+            for (const entry of entries) {
+                if (entry.status === "starting" &&
+                    !(await isSame(entry.owner)) &&
+                    !entry.root) {
+                    entry.status = "failed";
+                    entry.error = "launch owner exited before recording process";
+                }
+                if (["starting", "running"].includes(entry.status) &&
+                    entry.root &&
+                    !(await isSame(entry.root))) {
+                    if (!(await Promise.all((entry.descendants ?? []).map(isSame))).some(Boolean))
+                        entry.status = "exited";
+                }
+            }
+            const result = await fn(entries);
+            const path = join(this.home, `registry.${randomUUID()}.tmp`);
+            await writeFile(path, JSON.stringify(entries, null, 2) + "\n", {
+                mode: 0o600,
+            });
+            await rename(path, join(this.home, "registry.json"));
+            return result;
+        }
+        finally {
+            await rm(lock, { recursive: true });
+        }
+    }
+    async all() {
+        return this.transaction(async (entries) => structuredClone(entries));
+    }
+    async reserve(req, cap) {
+        const owner = await processRef(process.pid);
+        if (!owner)
+            throw new Error("Cannot identify Muster owner process");
+        return this.transaction(async (entries) => {
+            if (entries.filter((e) => e.status === "starting" || e.status === "running")
+                .length >= cap)
+                throw new Error(`Concurrency cap reached (${cap})`);
+            const id = randomUUID();
+            const entry = {
+                ...req,
+                id,
+                launchId: id,
+                status: "starting",
+                createdAt: new Date().toISOString(),
+                owner,
+            };
+            entries.push(entry);
+            return { ...entry };
+        });
+    }
+    async update(id, patch) {
+        return this.transaction(async (entries) => {
+            const byLaunch = entries.find((e) => e.launchId === id);
+            const durable = entries.filter((e) => e.id === id);
+            if (!byLaunch && durable.length > 1)
+                throw new Error("Ambiguous durable id; update by launchId");
+            const entry = byLaunch ?? durable[0];
+            if (!entry)
+                throw new Error(`Unknown launch ${id}`);
+            if (patch.id &&
+                entries.some((e) => e !== entry && e.runtime === entry.runtime && e.id === patch.id))
+                throw new Error("Durable identity already registered");
+            Object.assign(entry, patch);
+            return structuredClone(entry);
+        });
+    }
+}