@brutalsystems/muster 0.1.0 → 0.2.0

package/README.md

@@ -31,6 +31,7 @@ node dist/muster.js run codex --prompt 'Review the authentication flow'
 node dist/muster.js run claude --prompt 'Summarize the project' --host tmux
 node dist/muster.js run codex --kind task --prompt 'Explain the test layout'
 node dist/muster.js list
+node dist/muster.js list --format human
 node dist/muster.js list --kind task
 node dist/muster.js output RUN_ID
 node dist/muster.js stop THREAD_OR_SESSION_OR_RUN_ID
@@ -42,6 +43,21 @@ emit JSON; `output` prints the captured task output. `stop` also accepts an
 unambiguous peer name or canonical address, refusing ambiguity with candidates.
 Use the durable ID to stop a session whose runtime has renamed it.
 
+For readable terminal output, add `--format human` to `run`, `list`, or `stop`:
+
+```sh
+muster run codex --prompt 'Review this project' --format human
+muster list --format human
+muster stop THREAD_OR_SESSION_OR_RUN_ID --format human
+```
+
+Human output keeps full IDs and shows directory, host, state, and relevant
+attach/output/stop commands with actual IDs. pty sessions are labeled as not
+watchable or attachable. `--format json` is explicit JSON; omitting the flag
+still returns JSON. Put Muster options before any `-- RUNTIME_OPTIONS`.
+`output` always prints captured task text and does not accept `--format`.
+MCP tools retain their existing JSON responses.
+
 `run` accepts an optional `--` followed by runtime arguments. The normal allowlist
 is `--model` / `-m`, plus Claude's `--effort`. Unknown options, bundled short
 options, config injection and permission overrides are refused. Prompt strings

package/dist/format.js

@@ -0,0 +1,49 @@
+function clean(value) {
+    return String(value ?? "-").replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, (c) => c === "\n"
+        ? "\\n"
+        : c === "\r"
+            ? "\\r"
+            : c === "\t"
+                ? "\\t"
+                : "\\u" + c.charCodeAt(0).toString(16).padStart(4, "0"));
+}
+function argument(value) {
+    return /^[a-zA-Z0-9_.:-]+$/.test(value)
+        ? value
+        : "'" + value.replaceAll("'", "'\\''") + "'";
+}
+function recordHuman(record) {
+    const id = record.id ?? record.thread_id ?? record.session_id;
+    if (record.stopped === true)
+        return `Stopped ${clean(id)}.`;
+    const lines = [
+        `${clean(record.runtime)} · ${clean(record.kind)} · ${clean(record.state)}`,
+        `  ID: ${clean(id)}`,
+    ];
+    if (record.canonical_id)
+        lines.push(`  Address: ${clean(record.canonical_id)}`);
+    lines.push(`  Directory: ${clean(record.cwd)}`);
+    if (record.host)
+        lines.push(`  Host: ${clean(record.host)}${record.host === "pty" ? " (not watchable or attachable)" : ""}`);
+    if (record.exit_code !== undefined)
+        lines.push(`  Exit code: ${clean(record.exit_code)}`);
+    if (record.signal)
+        lines.push(`  Signal: ${clean(record.signal)}`);
+    if (record.error)
+        lines.push(`  Error: ${clean(record.error)}`);
+    const live = ["starting", "running", "idle", "busy"].includes(record.state ?? "");
+    if (live && record.attach_hint)
+        lines.push(`  Attach: ${clean(record.attach_hint)}`);
+    if (record.kind === "task" && id)
+        lines.push(`  Output: muster output ${argument(clean(id))}`);
+    if (live && id)
+        lines.push(`  Stop: muster stop ${argument(clean(id))}`);
+    return lines.join("\n");
+}
+export function formatHuman(value) {
+    if (Array.isArray(value))
+        return value.length
+            ? value.map(recordHuman).join("\n\n") + "\n"
+            : "No Muster runs.\n";
+    return recordHuman(value) + "\n";
+}

package/dist/muster.js

@@ -7,17 +7,21 @@ import { z } from "zod";
 import { Muster } from "./run.js";
 import { runSchema } from "./guard.js";
 import { delay } from "./identity/processes.js";
+import { formatHuman } from "./format.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 list [--kind session|task] [--format json|human]
+  muster stop <id> [--format json|human]
   muster output <id>
   muster mcp
 
+run also accepts --format json|human before -- RUNTIME_OPTIONS.
+run, list and stop default to JSON. output prints raw task text.
+
 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.
@@ -47,7 +51,7 @@ async function main() {
             });
         });
     if (mcp) {
-        const server = new Server({ name: "muster", version: "0.1.0" }, { capabilities: { tools: {} } });
+        const server = new Server({ name: "muster", version: "0.2.0" }, { capabilities: { tools: {} } });
         server.setRequestHandler(ListToolsRequestSchema, async () => ({
             tools: [
                 {
@@ -140,7 +144,7 @@ async function main() {
     }
     try {
         const command = argv.shift();
-        const { values, positionals } = parseArgs({
+        const { values: parsed, positionals } = parseArgs({
             args: argv,
             allowPositionals: true,
             strict: true,
@@ -149,13 +153,20 @@ async function main() {
                 cwd: { type: "string" },
                 kind: { type: "string" },
                 host: { type: "string" },
+                format: { type: "string" },
             },
         });
+        const { format = "json", ...values } = parsed;
+        if (format !== "json" && format !== "human")
+            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");
+        const print = (value) => process.stdout.write(format === "human" ? formatHuman(value) : JSON.stringify(value) + "\n");
         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");
+            print(record);
             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())
@@ -165,14 +176,14 @@ async function main() {
         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");
+            print(await muster.list(listSchema.parse(values).kind));
         }
         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");
+                print(await muster.stop(id));
             else
                 process.stdout.write(await muster.output(id));
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/muster",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Launch instructed, reachable local agent sessions",
   "type": "module",
   "engines": {