@brutalsystems/muster 0.7.11 → 0.7.14

package/dist/mcp-tools.js

@@ -0,0 +1,134 @@
+/**
+ * The `run`, `list`, `stop` and `output` tools exactly as the MCP server
+ * advertises them.
+ *
+ * Extracted from `src/muster.ts` so it can be ASSERTED against `runSchema`
+ * rather than kept in step by hand. One request shape had two hand-maintained
+ * descriptions and nothing checked that they agreed, and four fields drifted
+ * across two branches: `level`, then `identity`, `model` and `plugin`. Because
+ * the schema is `additionalProperties: false`, an omitted key is not merely
+ * undocumented — a conformant client is told it is INVALID.
+ * `test/mcp-run-schema.test.ts` is what ends that class.
+ */
+export const MCP_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", "opencode"],
+                },
+                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"],
+                },
+                open: {
+                    type: "boolean",
+                    description: "Open the tmux session in a terminal viewer (macOS only).",
+                },
+                terminal: {
+                    type: "string",
+                    enum: ["auto", "terminal", "iterm2", "ghostty"],
+                    description: "Viewer app; requires open. Auto uses Terminal.app.",
+                },
+                permissions: {
+                    type: "string",
+                    enum: ["auto", "deny", "bypass"],
+                    description: "Defaults to config (deny). Auto requires workspace-write; bypass requires authorized full-access.",
+                },
+                sandbox: {
+                    type: "string",
+                    enum: ["read-only", "workspace-write", "full-access"],
+                    description: "Defaults to config (read-only). Full access requires config authorization.",
+                },
+                level: {
+                    type: "string",
+                    enum: ["read", "work", "open"],
+                    description: "A spelling of a legal permissions/sandbox pair: read is deny + read-only, work is auto + workspace-write, open is bypass + full-access. Naming a level and either flag is an error.",
+                },
+                mcp: {
+                    type: "array",
+                    items: { type: "string", pattern: "^[a-zA-Z0-9_-]+$" },
+                    description: "Configured MCP server names. Omit for session defaults; [] disables all. Tasks have no defaults.",
+                },
+                project: {
+                    type: "string",
+                    pattern: "^[a-zA-Z0-9_-]+$",
+                    description: "A project named in config.toml, used instead of cwd. Naming both is an error.",
+                },
+                requestKey: {
+                    type: "string",
+                    minLength: 1,
+                    maxLength: 200,
+                    description: "Caller-owned identity for this launch. Repeating it returns the launch it already produced instead of starting another; repeating it with different parameters is refused.",
+                },
+                plugin: {
+                    type: "array",
+                    items: { type: "string", pattern: "^[a-zA-Z0-9_-]+$" },
+                    description: "Configured OpenCode plugin names. Omit for session defaults; [] disables all. OpenCode only.",
+                },
+                model: {
+                    type: "string",
+                    minLength: 1,
+                    description: "PROVIDER/MODEL, overriding the configured [opencode] model. OpenCode only.",
+                },
+                identity: {
+                    type: "string",
+                    pattern: "^[a-zA-Z0-9_-]+$",
+                    description: "A named identity created by `muster setup-identity`; the agent runs as that account instead of inheriting the ambient environment. A non-local requester is bounded by its profile's identities.",
+                },
+                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,
+        },
+    },
+];
+/**
+ * runSchema keys deliberately absent from the advertised `run` inputSchema.
+ *
+ * Empty today, and it stays here rather than being implicit: adding a field to
+ * runSchema without either advertising it or naming it here — with a reason —
+ * fails the drift test. That is the point. An entry is a decision that MCP
+ * callers may not set the field, not a place to park an oversight.
+ */
+export const RUN_MCP_OMITTED = [];

package/dist/muster.js

@@ -6,11 +6,12 @@ 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";
 import { formatHuman, humanColorEnabled } from "./format.js";
 import { checkPlugins, npmRegistry } from "./doctor.js";
-import { loadConfig } from "./config.js";
+import { loadConfig, musterHome } from "./config.js";
+import { describeIdentities, setupIdentity } from "./identity-cli.js";
+import { MCP_TOOLS } from "./mcp-tools.js";
 const listSchema = z
     .object({ kind: z.enum(["session", "task"]).optional() })
     .strict();
@@ -22,11 +23,17 @@ const help = `Usage:
   muster stop <id> [--format json|human]
   muster output <id>
   muster doctor [--format json|human]
+  muster setup-identity --identity NAME --agent <codex|claude|opencode> [--token-env VAR]
+  muster identities [--format json|human]
   muster mcp
   muster --version
 
 run also accepts --format json|human, --permissions auto|deny|bypass,
 and --sandbox read-only|workspace-write|full-access before -- RUNTIME_OPTIONS.
+--level read|work|open names a legal permissions and sandbox pair: read is
+deny + read-only, work is auto + workspace-write, open is bypass + full-access
+and still requires allow_dangerous_flags. Naming both a level and either flag
+is an error rather than a precedence rule.
 --open displays a tmux session on macOS. --terminal accepts auto (Terminal.app),
 terminal, iterm2, or ghostty, and requires --open.
 --mcp NAME is repeatable and replaces configured session defaults; --no-mcp
@@ -58,6 +65,27 @@ MCP: install deliberately in the one authorized session, never at user scope.
 const text = (value) => ({
     content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
 });
+/**
+ * Human rendering for `identities`, kept local rather than added to
+ * format.ts's RecordView/DoctorView: an identity record shares no field with
+ * either of those shapes.
+ */
+function identitiesHuman(view, color) {
+    const paint = (value, code) => color ? `[${code}m${value}` : value;
+    const lines = [];
+    if (!view.identities.length)
+        lines.push("No identities.");
+    for (const identity of view.identities) {
+        const code = identity.auth.state === "configured" ? 32 : 31;
+        lines.push(`${paint(identity.name, 1)} (${identity.agent}) — ${paint(identity.auth.state, code)}: ${identity.auth.detail}`);
+    }
+    if (view.staleGrants.length) {
+        lines.push("");
+        for (const grant of view.staleGrants)
+            lines.push(paint(`stale grant: profile ${grant.profile} names identity ${grant.identity}, which does not exist`, 33));
+    }
+    return lines.join("\n") + "\n";
+}
 async function main() {
     const argv = process.argv.slice(2);
     if (argv[0] === "--help" || argv[0] === "-h") {
@@ -86,106 +114,20 @@ async function main() {
     if (mcp) {
         const server = new Server({ name: "muster", version }, { 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", "opencode"],
-                            },
-                            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"],
-                            },
-                            open: {
-                                type: "boolean",
-                                description: "Open the tmux session in a terminal viewer (macOS only).",
-                            },
-                            terminal: {
-                                type: "string",
-                                enum: ["auto", "terminal", "iterm2", "ghostty"],
-                                description: "Viewer app; requires open. Auto uses Terminal.app.",
-                            },
-                            permissions: {
-                                type: "string",
-                                enum: ["auto", "deny", "bypass"],
-                                description: "Defaults to config (deny). Auto requires workspace-write; bypass requires authorized full-access.",
-                            },
-                            sandbox: {
-                                type: "string",
-                                enum: ["read-only", "workspace-write", "full-access"],
-                                description: "Defaults to config (read-only). Full access requires config authorization.",
-                            },
-                            mcp: {
-                                type: "array",
-                                items: { type: "string", pattern: "^[a-zA-Z0-9_-]+$" },
-                                description: "Configured MCP server names. Omit for session defaults; [] disables all. Tasks have no defaults.",
-                            },
-                            project: {
-                                type: "string",
-                                pattern: "^[a-zA-Z0-9_-]+$",
-                                description: "A project named in config.toml, used instead of cwd. Naming both is an error.",
-                            },
-                            requestKey: {
-                                type: "string",
-                                minLength: 1,
-                                maxLength: 200,
-                                description: "Caller-owned identity for this launch. Repeating it returns the launch it already produced instead of starting another; repeating it with different parameters is refused.",
-                            },
-                            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,
-                    },
-                },
-            ],
+            tools: MCP_TOOLS,
         }));
         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"}`));
+                        return text(await muster.run(args, {
+                            kind: "local",
+                            // The client's self-reported name was never authentication; it
+                            // is a label on a local requester, which is what it always was
+                            // in substance.
+                            label: `mcp:${server.getClientVersion()?.name ?? "unknown"}`,
+                        }));
                     case "list":
                         return text(await muster.list(listSchema.parse(args).kind));
                     case "stop":
@@ -229,6 +171,7 @@ async function main() {
                 format: { type: "string" },
                 permissions: { type: "string" },
                 sandbox: { type: "string" },
+                level: { type: "string" },
                 mcp: { type: "string", multiple: true },
                 "no-mcp": { type: "boolean" },
                 plugin: { type: "string", multiple: true },
@@ -236,6 +179,9 @@ async function main() {
                 "no-plugin": { type: "boolean" },
                 "request-key": { type: "string" },
                 project: { type: "string" },
+                identity: { type: "string" },
+                agent: { type: "string" },
+                "token-env": { type: "string" },
             },
         });
         const { format = "json", "no-mcp": noMcp, "no-plugin": noPlugin, "request-key": requestKey, ...values } = parsed;
@@ -257,6 +203,8 @@ async function main() {
             throw new Error("format must be json or human");
         if (command === "output" && parsed.format !== undefined)
             throw new Error("output prints raw task text; --format applies to run, list and stop");
+        if (command === "setup-identity" && parsed.format !== undefined)
+            throw new Error("setup-identity always prints JSON; --format applies to run, list, stop, doctor and identities");
         const print = (value) => process.stdout.write(format === "human"
             ? formatHuman(value, humanColorEnabled(process.stdout.isTTY, process.env))
             : JSON.stringify(value) + "\n");
@@ -281,6 +229,34 @@ async function main() {
                 throw new Error("list takes no positional arguments");
             print(await muster.list(listSchema.parse(values).kind));
         }
+        else if (command === "setup-identity") {
+            if (positionals.length)
+                throw new Error("setup-identity takes no positional arguments");
+            const { identity, agent, "token-env": tokenEnv, } = values;
+            if (!identity || !agent)
+                throw new Error("setup-identity requires --identity and --agent");
+            // Not routed through print(): its RecordView/DoctorView shapes are for
+            // run/list/stop/doctor, and an identity record shares no field with
+            // either, so this always prints JSON.
+            process.stdout.write(JSON.stringify(await setupIdentity({
+                home: musterHome(),
+                name: identity,
+                agent: agent,
+                ...(tokenEnv ? { tokenEnv } : {}),
+            })) + "\n");
+        }
+        else if (command === "identities") {
+            if (positionals.length)
+                throw new Error("identities takes no positional arguments");
+            const cfg = await loadConfig();
+            const view = await describeIdentities(musterHome(), process.env, Object.fromEntries(Object.entries(cfg.requester_profiles).map(([n, p]) => [
+                n,
+                p.identities,
+            ])));
+            process.stdout.write(format === "human"
+                ? identitiesHuman(view, humanColorEnabled(process.stdout.isTTY, process.env))
+                : JSON.stringify(view) + "\n");
+        }
         else if (command === "doctor") {
             if (positionals.length || Object.keys(values).length)
                 throw new Error("doctor takes no arguments");

package/dist/registry.js

@@ -1,7 +1,8 @@
 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";
+import { processRef, isSame, delay, groupAlive, } from "./identity/processes.js";
+import { LOCAL, requesterKey } from "./requester.js";
 /**
  * A request key arrived again with different parameters. Distinct from a launch
  * failure: nothing was attempted, and the caller reused a key it should have
@@ -80,7 +81,11 @@ export class Registry {
                 if (["starting", "running"].includes(entry.status) &&
                     entry.root &&
                     !(await isSame(entry.root))) {
-                    if (!(await Promise.all((entry.descendants ?? []).map(isSame))).some(Boolean))
+                    // The recorded descendants are only those seen during launch, and a
+                    // reparented one is not among them at all. Ask the group before
+                    // concluding the session ended: it is the signal that survives both.
+                    if (!(await Promise.all((entry.descendants ?? []).map(isSame))).some(Boolean) &&
+                        !(entry.group && (await groupAlive(entry.group))))
                         entry.status = "exited";
                 }
             }
@@ -108,19 +113,28 @@ export class Registry {
      * first would reject a retry of a launch that succeeded, which reads as a
      * failure and invites a third attempt.
      */
-    async reserve(req, cap, idem) {
+    async reserve(req, cap, idem, requester = LOCAL) {
         const owner = await processRef(process.pid);
         if (!owner)
             throw new Error("Cannot identify Muster owner process");
+        const scope = requesterKey(requester);
         return this.transaction(async (entries) => {
             if (idem) {
-                const prior = entries.find((e) => e.requestKey === idem.requestKey);
+                // Scoped by requester: two machines may legitimately choose the same
+                // request key, and deduping one into the other would hand a caller a
+                // session it never asked for.
+                const prior = entries.find((e) => e.requestKey === idem.requestKey &&
+                    requesterKey(e.requester ?? LOCAL) === scope);
                 if (prior) {
                     if (prior.paramsFingerprint !== idem.paramsFingerprint)
                         throw new IdempotencyKeyReuse(idem.requestKey, prior.paramsFingerprint ?? "none", idem.paramsFingerprint);
                     return { entry: structuredClone(prior), deduped: true };
                 }
             }
+            // Admission seam: `scope` is the per-requester key a future per-requester
+            // cap and locally-reserved portion would count against, available here
+            // inside the transaction where the accounting has to happen. The cap is
+            // global today.
             if (entries.filter((e) => e.status === "starting" || e.status === "running")
                 .length >= cap)
                 throw new Error(`Concurrency cap reached (${cap})`);
@@ -131,6 +145,7 @@ export class Registry {
                 launchId: id,
                 ...(idem ?? {}),
                 status: "starting",
+                requester,
                 createdAt: new Date().toISOString(),
                 owner,
             };
@@ -147,6 +162,8 @@ export class Registry {
             const entry = byLaunch ?? durable[0];
             if (!entry)
                 throw new Error(`Unknown launch ${id}`);
+            if ("requester" in patch)
+                throw new Error("requester is recorded once and cannot be updated");
             if (patch.id &&
                 entries.some((e) => e !== entry && e.runtime === entry.runtime && e.id === patch.id))
                 throw new Error("Durable identity already registered");

package/dist/requester-policy.js

@@ -0,0 +1,106 @@
+import { LOCAL, requesterKey } from "./requester.js";
+/** A remote tuple with no enrolment. Absence of a grant is a denial. */
+export class RequesterNotEnrolled extends Error {
+    authority;
+    subjectPrefix;
+    constructor(authority, subjectPrefix) {
+        super(`No enrolment for requester ${authority}/${subjectPrefix} — add a [[requesters]] entry to config.toml`);
+        this.authority = authority;
+        this.subjectPrefix = subjectPrefix;
+        this.name = "RequesterNotEnrolled";
+    }
+}
+/**
+ * Enrolled, but the request exceeds the profile. `ceiling` is what a transport
+ * maps to a stable code, so nothing downstream matches on message text.
+ */
+export class RequesterPolicyRefusal extends Error {
+    ceiling;
+    constructor(ceiling, message) {
+        super(message);
+        this.ceiling = ceiling;
+        this.name = "RequesterPolicyRefusal";
+    }
+}
+/** The receiver is misconfigured. Not the requester's fault, so not a refusal. */
+export class RequesterConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RequesterConfigError";
+    }
+}
+/** Ordered weakest to strongest, so a ceiling is one index comparison. */
+const LEVEL_ORDER = ["read", "work", "open"];
+const GRADE_ORDER = ["none", "tool-policy", "kernel"];
+export function resolveRequesterPolicy(requester, config) {
+    if (requester.kind === "local")
+        return {
+            profile: undefined,
+            level: undefined,
+            minEnforcement: undefined,
+            logMode: "full",
+            identities: undefined,
+        };
+    const enrolment = config.requesters.find((e) => e.authority === requester.authority && e.subject === requester.subject);
+    if (!enrolment)
+        throw new RequesterNotEnrolled(requester.authority, requester.subject.slice(0, 4));
+    const profile = config.requester_profiles[enrolment.profile];
+    if (!profile)
+        throw new RequesterConfigError(`Enrolment ${enrolment.authority}/${enrolment.subject} names unknown profile ${enrolment.profile}`);
+    return {
+        profile,
+        level: profile.level,
+        minEnforcement: profile.min_enforcement,
+        // Not a profile setting: the exposure is the receiver's to carry and the
+        // requester's to avoid, so a profile may not opt into full logging.
+        logMode: "metadata",
+        identities: profile.identities,
+    };
+}
+export function assertLevelWithinCeiling(requested, policy) {
+    if (!policy.level)
+        return;
+    if (LEVEL_ORDER.indexOf(requested) > LEVEL_ORDER.indexOf(policy.level))
+        throw new RequesterPolicyRefusal("level", `Level ${requested} exceeds this requester's ceiling of ${policy.level}`);
+}
+/**
+ * May this requester act on this entry?
+ *
+ * Asymmetric on purpose. A local requester is the operator and may stop or read
+ * anything on the machine. A remote requester may act only on launches it asked
+ * for — an entry with no recorded requester predates the field and reads as
+ * local, so it is protected rather than open.
+ */
+export function assertMayAct(entry, requester) {
+    if (requester.kind === "local")
+        return;
+    if (requesterKey(entry.requester ?? LOCAL) !== requesterKey(requester))
+        throw new RequesterPolicyRefusal("not-owner", "this launch belongs to a different requester");
+}
+export function assertEnforcementMeetsMinimum(runtime, grade, policy) {
+    if (!policy.minEnforcement)
+        return;
+    if (GRADE_ORDER.indexOf(grade) < GRADE_ORDER.indexOf(policy.minEnforcement))
+        throw new RequesterPolicyRefusal("enforcement", `Runtime ${runtime} offers ${grade} enforcement and this requester requires ${policy.minEnforcement}`);
+}
+/**
+ * Bound, do not pin — the same shape as allowed_roots, level and
+ * min_enforcement. A local requester is the operator and may name anything.
+ */
+export function resolveIdentityForRequest(requested, policy) {
+    if (!policy.identities)
+        return requested;
+    const granted = policy.identities;
+    if (requested) {
+        if (!granted.includes(requested))
+            throw new RequesterPolicyRefusal("identity", granted.length
+                ? `identity ${requested} is not granted to this requester (granted: ${granted.join(", ")})`
+                : `this requester is granted no identity, so it may not name one`);
+        return requested;
+    }
+    if (granted.length === 1)
+        return granted[0];
+    if (granted.length > 1)
+        throw new RequesterPolicyRefusal("identity", `this requester must name one of: ${granted.join(", ")}`);
+    return undefined;
+}

package/dist/requester.js

@@ -0,0 +1,59 @@
+import { z } from "zod";
+/**
+ * Opaque, and free of control characters. The key encoding must never be able
+ * to confuse two identities, and a NUL or other control byte inside a field is
+ * the way that happens.
+ */
+const opaqueField = (max) => z
+    .string()
+    .min(1)
+    .max(max)
+    .regex(/^[ -~]+$/, "must not contain control characters");
+export const authoritySchema = opaqueField(200);
+export const subjectSchema = opaqueField(400);
+/**
+ * Who asked for a launch.
+ *
+ * `authority` names the identity namespace that authenticated `subject`;
+ * `subject` is a stable opaque identifier within it. Muster treats both as
+ * opaque and hardcodes no namespace, so the spelling an integrator adopts is
+ * configuration rather than a Muster release.
+ *
+ * Muster does not authenticate its caller. Anything able to import Muster or
+ * exec its binary already runs as the owner account. The value here is least
+ * privilege and honest provenance for a trusted local invoker that has already
+ * authenticated a remote peer — not a defence against a compromised same-user
+ * process.
+ */
+export const requesterSchema = z.discriminatedUnion("kind", [
+    z
+        .object({
+        kind: z.literal("local"),
+        label: z.string().min(1).max(200).optional(),
+    })
+        .strict(),
+    z
+        .object({
+        kind: z.literal("remote"),
+        authority: authoritySchema,
+        subject: subjectSchema,
+        label: z.string().min(1).max(200).optional(),
+    })
+        .strict(),
+]);
+export const LOCAL = { kind: "local" };
+/**
+ * The policy and quota key. `label` is not a parameter, which is what keeps a
+ * caller-chosen display string structurally incapable of affecting policy.
+ */
+export function requesterKey(r) {
+    return r.kind === "local"
+        ? "local"
+        : JSON.stringify(["remote", r.authority, r.subject]);
+}
+/** For humans and log lines only; never a key. */
+export function requesterLabel(r) {
+    if (r.label)
+        return r.label;
+    return r.kind === "local" ? "local" : `${r.authority}/${r.subject}`;
+}