@chorus-aidlc/chorus 0.16.4 → 0.17.0

package/cli/mcp-args.mjs

@@ -0,0 +1,280 @@
+// cli/mcp-args.mjs
+// Pure, dependency-injected argument parser + assembler for the `chorus mcp`
+// command group (call / whoami / list). No direct IO — file/stdin reads are
+// injected so this is fully unit-testable. This is the byte-faithful
+// replacement for the plugin's `json_encode_file` bash helper: a file's raw
+// bytes become a JSON *string* value (equivalent to `jq -Rs '.'`), never
+// re-parsed. See openspec/changes/add-cli-mcp-native-client/design.md.
+
+/** Thrown on any structural / usage problem. The command layer maps it to a
+ * stderr diagnostic + a non-zero (usage) exit code. */
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+}
+
+const ACTIONS = new Set(["call", "whoami", "list"]);
+
+/** Flags that consume the following token as their value (or `--flag=value`). */
+const VALUE_FLAGS = new Set(["--arg", "--arg-file", "--args-file", "--agent", "--url", "--api-key"]);
+
+/**
+ * @typedef {Object} ParsedMcp
+ * @property {boolean} help            `--help`/`-h` requested (short-circuits).
+ * @property {"call"|"whoami"|"list"|null} action
+ * @property {string|null} tool        Tool name (call only).
+ * @property {string|null} positionalJson  Base arguments as a JSON string.
+ * @property {string|null} argsFile    Base arguments from a JSON file (`-`=stdin).
+ * @property {Array<{type:"arg"|"arg-file", key:string, raw:string}>} overrides
+ *   Per-key overrides in command-line order. `type:"arg"` raw is the literal /
+ *   `@file` value; `type:"arg-file"` raw is the path.
+ * @property {{ agent?:string, url?:string, apiKey?:string }} creds
+ */
+
+/**
+ * Parse the argv AFTER the `mcp` subcommand word (i.e. `process.argv.slice(3)`).
+ * Structural only — file/stdin reads and JSON parsing happen in assembleArgs.
+ * @param {string[]} argv
+ * @returns {ParsedMcp}
+ * @throws {UsageError}
+ */
+export function parseMcpArgs(argv) {
+  const out = /** @type {ParsedMcp} */ ({
+    help: false,
+    action: null,
+    tool: null,
+    positionalJson: null,
+    argsFile: null,
+    overrides: [],
+    creds: {},
+  });
+
+  // A leading --help/-h (before any action) is a group help request.
+  const tokens = [...argv];
+  const positionals = [];
+
+  for (let i = 0; i < tokens.length; i++) {
+    const tok = tokens[i];
+
+    if (tok === "--help" || tok === "-h") {
+      out.help = true;
+      continue;
+    }
+
+    if (tok.startsWith("--")) {
+      // Support both `--flag value` and `--flag=value`.
+      let name = tok;
+      let inlineValue = null;
+      const eq = tok.indexOf("=");
+      if (eq !== -1) {
+        name = tok.slice(0, eq);
+        inlineValue = tok.slice(eq + 1);
+      }
+
+      if (!VALUE_FLAGS.has(name)) {
+        throw new UsageError(`Unknown flag: ${name}`);
+      }
+
+      const value = inlineValue !== null ? inlineValue : tokens[++i];
+      if (value === undefined) {
+        throw new UsageError(`Flag ${name} requires a value`);
+      }
+
+      switch (name) {
+        case "--arg": {
+          const kv = splitKeyValue(value, "--arg");
+          out.overrides.push({ type: "arg", key: kv.key, raw: kv.value });
+          break;
+        }
+        case "--arg-file": {
+          const kv = splitKeyValue(value, "--arg-file");
+          out.overrides.push({ type: "arg-file", key: kv.key, raw: kv.value });
+          break;
+        }
+        case "--args-file":
+          out.argsFile = value;
+          break;
+        case "--agent":
+          out.creds.agent = value;
+          break;
+        case "--url":
+          out.creds.url = value;
+          break;
+        case "--api-key":
+          out.creds.apiKey = value;
+          break;
+      }
+      continue;
+    }
+
+    // Bare positional.
+    positionals.push(tok);
+  }
+
+  // First positional = action.
+  if (positionals.length === 0) {
+    if (out.help) return out; // `chorus mcp --help`
+    throw new UsageError("Missing action. Expected: call | whoami | list");
+  }
+  const action = positionals[0];
+  if (!ACTIONS.has(action)) {
+    throw new UsageError(`Unknown action "${action}". Expected: call | whoami | list`);
+  }
+  out.action = /** @type {"call"|"whoami"|"list"} */ (action);
+
+  if (action === "call") {
+    // positionals[1] = tool, positionals[2] = base JSON. No more.
+    out.tool = positionals[1] ?? null;
+    if (!out.help && !out.tool) throw new UsageError("`chorus mcp call` requires a <tool> name");
+    if (positionals.length > 3) {
+      throw new UsageError(
+        "Too many positional arguments. Usage: chorus mcp call <tool> ['<json>'] [flags]",
+      );
+    }
+    out.positionalJson = positionals[2] ?? null;
+  } else {
+    // whoami / list take no positional beyond the action.
+    if (positionals.length > 1) {
+      throw new UsageError(`\`chorus mcp ${action}\` takes no positional arguments`);
+    }
+    if (out.overrides.length || out.positionalJson || out.argsFile) {
+      throw new UsageError(`\`chorus mcp ${action}\` does not accept --arg/--arg-file/--args-file`);
+    }
+  }
+
+  return out;
+}
+
+/** Split `key=value` on the FIRST `=`. */
+function splitKeyValue(token, flag) {
+  const eq = token.indexOf("=");
+  if (eq === -1) throw new UsageError(`${flag} expects key=value (got "${token}")`);
+  const key = token.slice(0, eq);
+  if (!key) throw new UsageError(`${flag} has an empty key (got "${token}")`);
+  return { key, value: token.slice(eq + 1) };
+}
+
+/**
+ * Build the tool `arguments` object from a parsed `call`. Layers sources, later
+ * overriding earlier, applied in command-line order:
+ *   1. base = positional JSON XOR --args-file (both → error; neither → {}).
+ *   2/3/4. --arg literal / --arg-file / @file → per-key overrides (files → string).
+ * File-fill sources inject file bytes as a JSON string (never JSON-parsed).
+ * At most one source may consume stdin (`-`).
+ *
+ * @param {ParsedMcp} parsed
+ * @param {{ readFile: (path:string)=>string, readStdin: ()=>string }} io
+ * @returns {Record<string, unknown>}
+ * @throws {UsageError}
+ */
+export function assembleArgs(parsed, io) {
+  const { readFile, readStdin } = io;
+  let stdinUsed = false;
+  const consumeStdin = () => {
+    if (stdinUsed) throw new UsageError("stdin (-) can only be consumed by one argument");
+    stdinUsed = true;
+    try {
+      return readStdin();
+    } catch (e) {
+      throw new UsageError(`cannot read stdin: ${/** @type {Error} */ (e).message}`);
+    }
+  };
+  // A file-read failure (missing path, permissions) is a usage error, not a
+  // transport/tool error — wrap it as UsageError so the command layer maps it to
+  // the usage exit code (2), never the tool-error exit code (1).
+  const readPath = (path) => {
+    if (path === "-") return consumeStdin();
+    try {
+      return readFile(path);
+    } catch (e) {
+      throw new UsageError(`cannot read file "${path}": ${/** @type {Error} */ (e).message}`);
+    }
+  };
+
+  // 1. Base object.
+  if (parsed.positionalJson !== null && parsed.argsFile !== null) {
+    throw new UsageError(
+      "Provide the base arguments either as a positional JSON string OR --args-file, not both",
+    );
+  }
+  let args = {};
+  const rawBase =
+    parsed.positionalJson !== null
+      ? parsed.positionalJson
+      : parsed.argsFile !== null
+        ? readPath(parsed.argsFile)
+        : null;
+  if (rawBase !== null) {
+    let parsedBase;
+    try {
+      parsedBase = JSON.parse(rawBase);
+    } catch (err) {
+      const src = parsed.positionalJson !== null ? "positional JSON argument" : `--args-file (${parsed.argsFile})`;
+      throw new UsageError(`Invalid JSON in ${src}: ${/** @type {Error} */ (err).message}`);
+    }
+    if (parsedBase === null || typeof parsedBase !== "object" || Array.isArray(parsedBase)) {
+      throw new UsageError("Base arguments must be a JSON object");
+    }
+    args = parsedBase;
+  }
+
+  // 2/3/4. Per-key overrides in command-line order.
+  for (const ov of parsed.overrides) {
+    if (ov.type === "arg-file") {
+      args[ov.key] = readPath(ov.raw);
+      continue;
+    }
+    // type === "arg": interpret the raw value.
+    const raw = ov.raw;
+    if (raw.startsWith("@@")) {
+      // Escape: `@@rest` → literal `@rest`.
+      args[ov.key] = "@" + raw.slice(2);
+    } else if (raw.startsWith("@")) {
+      // `@path` file sugar (`@-` → stdin).
+      args[ov.key] = readPath(raw.slice(1));
+    } else {
+      args[ov.key] = raw;
+    }
+  }
+
+  return args;
+}
+
+/** Help text for the `chorus mcp` command group. */
+export function mcpHelpText(version = "") {
+  const v = version ? ` v${version}` : "";
+  return `\
+Chorus${v} — native MCP client
+
+USAGE
+  chorus mcp call <tool> ['<json>'] [arg flags]   Call an MCP tool as the resolved agent
+  chorus mcp whoami                               Print this agent's own UUID
+  chorus mcp list                                 List the tools this agent may call
+
+ARGUMENT FLAGS (call)
+  <json>                Positional JSON object — the base arguments
+  --args-file <path>    Read the whole arguments object from a JSON file ('-' = stdin)
+  --arg key=value       Set key to the literal string value
+  --arg-file key=<path> Set key to a file's raw bytes as a string ('-' = stdin)
+  --arg key=@<path>     Shorthand for --arg-file ('@-' = stdin; '@@x' = literal '@x')
+                        (later --arg/--arg-file override earlier keys, in order)
+
+CREDENTIALS (all actions)
+  --url <url>           Chorus server URL          (env: CHORUS_URL)
+  --api-key <cho_...>   Agent API key              (env: CHORUS_API_KEY)
+  --agent <name|uuid>   Act as an agent from ~/.chorus/daemon.json agents[],
+                        matched by its agentUuid or agentName (env:
+                        CHORUS_AGENT_PROFILE). The key is read from daemon.json —
+                        no need to pass/export CHORUS_API_KEY. A profile is
+                        preferred over CHORUS_URL/CHORUS_API_KEY; required when
+                        several agents are configured and no profile/flags/env.
+
+OUTPUT
+  call    prints the tool result's text verbatim on success (drop-in for
+          chorus-api.sh mcp-tool); tool/transport errors go to stderr, exit != 0.
+  whoami  prints the bare agent UUID.
+  list    prints one 'name — description' line per permitted tool.
+`;
+}

package/cli/mcp.mjs

@@ -0,0 +1,164 @@
+// cli/mcp.mjs
+// `chorus mcp` command group — the native MCP client surface (call / whoami /
+// list). Thin orchestration over the pure arg engine (cli/mcp-args.mjs), the
+// credential/identity resolver (cli/credentials.mjs), and the MCP client
+// (cli/chorus-client.mjs). All IO + collaborators are injectable so this is
+// unit-testable with fakes. See openspec/changes/add-cli-mcp-native-client/.
+
+import { readFileSync } from "node:fs";
+import { parseMcpArgs, assembleArgs, mcpHelpText, UsageError } from "./mcp-args.mjs";
+import { resolveMcpCredentials } from "./credentials.mjs";
+import { ChorusClient, validateAndFetchIdentity } from "./chorus-client.mjs";
+
+// Exit codes (design.md "Output & exit-code semantics"):
+const EXIT_OK = 0; // success
+const EXIT_TOOL_ERROR = 1; // tool returned isError
+const EXIT_USAGE = 2; // bad flags / JSON / ambiguity / transport / auth
+
+/** First line of a (possibly multi-line) description, for the `list` output. */
+function firstLine(s) {
+  const nl = s.indexOf("\n");
+  return nl === -1 ? s : s.slice(0, nl);
+}
+
+/**
+ * Announce the acting agent on stderr for the identity-oriented actions
+ * (whoami / list) when a NAMED agent was selected from daemon.json agents[].
+ * Never emitted for the flag/env path (label "flag"/"env") and never on
+ * `call` (whose stdout must stay a byte-exact tool payload).
+ */
+function noticeActingAs(creds, err) {
+  if (creds.label && creds.label !== "flag" && creds.label !== "env") {
+    err.write(`(acting as agent "${creds.label}")\n`);
+  }
+}
+
+/**
+ * Run `chorus mcp <action> …`. Returns an exit code — never calls
+ * `process.exit` (the entry module owns process lifetime).
+ *
+ * @param {string[]} argv  argv AFTER the `mcp` word (process.argv.slice(3)).
+ * @param {{
+ *   version?: string,
+ *   stdout?: { write(s:string):unknown },
+ *   stderr?: { write(s:string):unknown },
+ *   makeClient?: (o:{url:string,apiKey:string}) => any,
+ *   readFile?: (path:string)=>string,
+ *   readStdin?: ()=>string,
+ *   resolveCreds?: (flags:any, deps:any)=>{url:string,apiKey:string,label:string},
+ *   credsDeps?: any,
+ * }} [opts]
+ * @returns {Promise<number>}
+ */
+export async function runMcp(argv, opts = {}) {
+  const version = opts.version ?? "";
+  const out = opts.stdout ?? process.stdout;
+  const err = opts.stderr ?? process.stderr;
+  const makeClient = opts.makeClient ?? ((o) => new ChorusClient(o));
+  const readFile = opts.readFile ?? ((p) => readFileSync(p, "utf8"));
+  // fd 0 = stdin; readFileSync(0) drains it synchronously (fine for a one-shot CLI).
+  const readStdin = opts.readStdin ?? (() => readFileSync(0, "utf8"));
+  const resolveCreds = opts.resolveCreds ?? resolveMcpCredentials;
+
+  // 1. Parse (structural).
+  let parsed;
+  try {
+    parsed = parseMcpArgs(argv);
+  } catch (e) {
+    if (e instanceof UsageError) {
+      err.write(`error: ${e.message}\n\n${mcpHelpText(version)}`);
+      return EXIT_USAGE;
+    }
+    throw e;
+  }
+
+  if (parsed.help || !parsed.action) {
+    out.write(mcpHelpText(version));
+    return EXIT_OK;
+  }
+
+  // 2. Resolve credentials + acting identity.
+  let creds;
+  try {
+    creds = resolveCreds(parsed.creds, opts.credsDeps ?? {});
+  } catch (e) {
+    err.write(`error: ${/** @type {Error} */ (e).message}\n`);
+    return EXIT_USAGE;
+  }
+
+  // 3. Dispatch the action.
+  if (parsed.action === "call") {
+    let args;
+    try {
+      args = assembleArgs(parsed, { readFile, readStdin });
+    } catch (e) {
+      if (e instanceof UsageError) {
+        err.write(`error: ${e.message}\n`);
+        return EXIT_USAGE;
+      }
+      throw e;
+    }
+    const client = makeClient({ url: creds.url, apiKey: creds.apiKey });
+    try {
+      const { isError, text } = await client.callToolRaw(parsed.tool, args);
+      if (isError) {
+        // Tool-level error → stderr, non-zero, stdout stays empty.
+        err.write(text.endsWith("\n") ? text : `${text}\n`);
+        return EXIT_TOOL_ERROR;
+      }
+      // Success → verbatim text on stdout, matching `chorus-api.sh mcp-tool`'s
+      // `jq -r` (which appends a single trailing newline).
+      out.write(`${text}\n`);
+      return EXIT_OK;
+    } catch (e) {
+      err.write(`error: ${/** @type {Error} */ (e).message}\n`);
+      return EXIT_USAGE;
+    } finally {
+      await safeDisconnect(client);
+    }
+  }
+
+  if (parsed.action === "whoami") {
+    noticeActingAs(creds, err);
+    try {
+      // Fresh identity via chorus_checkin every call — no on-disk cache.
+      const identity = await validateAndFetchIdentity(
+        { url: creds.url, apiKey: creds.apiKey },
+        { makeClient },
+      );
+      out.write(`${identity.uuid}\n`);
+      return EXIT_OK;
+    } catch (e) {
+      err.write(`error: ${/** @type {Error} */ (e).message}\n`);
+      return EXIT_USAGE;
+    }
+  }
+
+  if (parsed.action === "list") {
+    noticeActingAs(creds, err);
+    const client = makeClient({ url: creds.url, apiKey: creds.apiKey });
+    try {
+      const tools = await client.listTools();
+      for (const t of tools) {
+        out.write(t.description ? `${t.name} — ${firstLine(t.description)}\n` : `${t.name}\n`);
+      }
+      return EXIT_OK;
+    } catch (e) {
+      err.write(`error: ${/** @type {Error} */ (e).message}\n`);
+      return EXIT_USAGE;
+    } finally {
+      await safeDisconnect(client);
+    }
+  }
+
+  return EXIT_USAGE;
+}
+
+/** Disconnect without letting a teardown error mask the real result. */
+async function safeDisconnect(client) {
+  try {
+    if (client && typeof client.disconnect === "function") await client.disconnect();
+  } catch {
+    // ignore
+  }
+}

package/cli/spawner-select.mjs

@@ -6,22 +6,65 @@
 // injected purely through the shared wake(...) contract.
 //
 // The function is TOTAL: resolveAgentType has already rejected unknown values
-// before this runs, so an unrecognized type here is not a user error path — we
+// before this runs, so an UNRECOGNIZED type here is not a user error path — we
 // fall back to the safe default (claude-code) rather than throw.
+//
+// The `offline` type is the ONE known value that must NEVER reach that default:
+// it is a non-wakeable classification (an agent parked in daemon.json only for the
+// `chorus mcp` proxy key), so it gets an explicit branch returning the
+// OfflineSpawner — a fail-closed no-op that logs and never spawns a subprocess.
+// Without this branch, adding `offline` to KNOWN_AGENTS would let it fall through
+// and silently wake Claude — the exact fail-open bug this guards against.
 
 import { ClaudeSpawner } from "./claude-spawner.mjs";
 import { CodexSpawner } from "./codex-spawner.mjs";
 import { DshSpawner } from "./dsh-spawner.mjs";
 import { KiroSpawner } from "./kiro-spawner.mjs";
 
+/**
+ * A fail-closed spawner for the `offline` agentType. It satisfies the shared
+ * wake(...) contract so the daemon's pipeline stays backend-agnostic, but it never
+ * spawns a process, never invokes `onChild` (so no server turn advances to
+ * running), and never falls through to a real backend. It simply logs that the
+ * agent is offline and resolves with a terminal no-op result (exitCode: null —
+ * matching the "skipping wake" convention of the real backends when their CLI is
+ * absent). An offline agent exists in daemon.json solely so `chorus mcp` can proxy
+ * through its key; the daemon must not wake it.
+ */
+export class OfflineSpawner {
+  /** @param {{ logger?: any }} [opts] */
+  constructor({ logger } = {}) {
+    this.logger = logger;
+  }
+
+  /**
+   * @param {{ sessionId?: string }} [params]
+   * @returns {Promise<{ sessionId: string, exitCode: null, isNew: false }>}
+   */
+  async wake({ sessionId } = {}) {
+    this.logger?.warn?.(
+      "[Chorus] agent backend is 'offline' — no local agent to wake; dropping this wake " +
+        "(offline agents are proxied via `chorus mcp` only, never spawned).",
+    );
+    return { sessionId: sessionId ?? "", exitCode: null, isNew: false };
+  }
+}
+
 /**
  * Construct the spawner backend for `agentType`.
- * @param {string} agentType  "claude-code" | "codex" | "kiro" | "dsh" (already validated upstream).
+ * @param {string} agentType  "claude-code" | "codex" | "kiro" | "dsh" | "offline"
+ *   (already validated upstream). "offline" → OfflineSpawner (fail-closed no-op).
  * @param {{ logger?: any, permissionMode?: "chorus"|"yolo", creds?: { url: string, apiKey: string } }} [opts]
  * @returns {import("./codex-spawner.mjs").Spawner}
  */
 export function selectSpawner(agentType, opts = {}) {
   const { logger, permissionMode, creds } = opts;
+  if (agentType === "offline") {
+    // Fail-closed: an offline agent has no local backend. Return the no-op spawner
+    // explicitly so we NEVER fall through to the claude-code default below and wake
+    // Claude for an agent the operator classified as offline.
+    return new OfflineSpawner({ logger });
+  }
   if (agentType === "codex") {
     return new CodexSpawner({ logger, permissionMode, creds });
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chorus-aidlc/chorus",
-  "version": "0.16.4",
+  "version": "0.17.0",
   "description": "The Agent Harness for AI-Human Collaboration — session lifecycle, task state, sub-agent orchestration, observability, and failure recovery",
   "homepage": "https://github.com/Chorus-AIDLC/Chorus",
   "repository": {