@chorus-aidlc/chorus 0.16.4 → 0.17.0

package/cli/agents.mjs

@@ -0,0 +1,329 @@
+// cli/agents.mjs
+// `chorus agents` — manage this machine's configured agents (the ~/.chorus/daemon.json
+// agents[]): `list` (default), `add` (detect + install plugin + seed creds — the flow
+// formerly reached via `chorus init`, delegated to runInit), and `remove <name|uuid>`.
+// Listing lets a user/agent discover the valid `CHORUS_AGENT_PROFILE` /
+// `chorus mcp --agent <name|uuid>` values without hand-reading the JSON. The `cho_`
+// API key is NEVER emitted by list/remove — not masked, omitted entirely.
+//
+// Peer of the other `chorus` subcommands (login / daemon / mcp); dispatched from
+// chorus.mjs before the server boot path, so every `chorus agents …` help/list/remove
+// path never starts the embedded PostgreSQL.
+
+import { readFileSync } from "node:fs";
+import { loginFilePath } from "./credentials.mjs";
+import { updateDaemonConfig } from "./login.mjs";
+
+/** Read + parse a JSON file, returning null on any error (missing/malformed). */
+function readJsonSafe(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A non-empty trimmed string, or undefined. */
+function nonEmpty(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+/** Compact host for the table (host[:port] only — never userinfo); never throws. */
+function hostOf(url) {
+  if (!url) return "";
+  try {
+    return new URL(url).host;
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * Safe url for machine (--json) output: the origin only (scheme://host[:port]).
+ * Strips any userinfo / path / query so an accidental credential embedded in the
+ * url can never surface. Returns null when absent or unparseable (never echoes
+ * the raw string). Defense-in-depth — the stored API key lives in a separate
+ * `apiKey` field this command never reads.
+ */
+function originOf(url) {
+  if (!url) return null;
+  try {
+    return new URL(url).origin;
+  } catch {
+    return null;
+  }
+}
+
+/** Group help for `chorus agents` (list / add / remove). */
+export function agentsHelpText(version = "") {
+  const v = version ? ` v${version}` : "";
+  return `\
+Chorus${v} — manage this machine's configured agents
+
+USAGE
+  chorus agents [list]              List configured agents (name, UUID, backend)
+  chorus agents --json              Machine-readable list (API keys never included)
+  chorus agents add [flags]         Configure agent(s): detect, install plugin, seed
+                                    credentials (formerly \`chorus init\`; same flags —
+                                    see \`chorus agents add --help\`)
+  chorus agents remove <name|uuid>  Remove a configured agent from ~/.chorus/daemon.json
+
+Each listed UUID or name is a valid value for \`chorus mcp --agent <name|uuid>\` or the
+CHORUS_AGENT_PROFILE environment variable. The API key is never printed.
+`;
+}
+
+/**
+ * Build the redacted agent rows from a parsed daemon.json object.
+ * @param {Record<string, unknown>|null} file
+ * @returns {Array<{index:number, name?:string, uuid?:string, agentType?:string, url?:string, daemonWake?:unknown, flat?:boolean}>}
+ */
+export function collectAgents(file) {
+  if (!file) return [];
+  const rows = [];
+  if (Array.isArray(file.agents)) {
+    file.agents.forEach((a, i) => {
+      if (a && typeof a === "object") {
+        rows.push({
+          index: i,
+          name: nonEmpty(a.agentName) ?? nonEmpty(a.name) ?? nonEmpty(a.label),
+          uuid: nonEmpty(a.agentUuid),
+          agentType: nonEmpty(a.agentType),
+          url: nonEmpty(a.url) ?? nonEmpty(file.url),
+          daemonWake: a.daemonWake,
+        });
+      }
+    });
+  }
+  // Flat single-agent config (no agents[]): synthesize one row from the
+  // deprecated top-level fields so it still shows up.
+  if (rows.length === 0 && (nonEmpty(file.apiKey) || nonEmpty(file.agentUuid))) {
+    rows.push({
+      index: 0,
+      name: nonEmpty(file.agentName),
+      uuid: nonEmpty(file.agentUuid),
+      agentType: nonEmpty(file.agent),
+      url: nonEmpty(file.url),
+      flat: true,
+    });
+  }
+  return rows;
+}
+
+/**
+ * List configured agents (the `chorus agents` / `chorus agents list` body).
+ * Returns an exit code (never calls process.exit).
+ * @param {string[]} argv  flags after the (optional) `list` sub-verb.
+ * @param {object} [opts]
+ * @returns {number}
+ */
+function listAgents(argv = [], opts = {}) {
+  const out = opts.stdout ?? process.stdout;
+  const err = opts.stderr ?? process.stderr;
+  const env = opts.env ?? process.env;
+  const readJson = opts.readJson ?? readJsonSafe;
+  const loginPath = opts.loginPath ?? loginFilePath();
+  const version = opts.version ?? "";
+
+  let json = false;
+  for (const tok of argv) {
+    if (tok === "--help" || tok === "-h") {
+      out.write(agentsHelpText(version));
+      return 0;
+    }
+    if (tok === "--json") {
+      json = true;
+      continue;
+    }
+    err.write(`error: unknown flag: ${tok}\n\n${agentsHelpText(version)}`);
+    return 2;
+  }
+
+  const rows = collectAgents(readJson(loginPath));
+  const active = nonEmpty(env.CHORUS_AGENT_PROFILE);
+  const isActive = (r) => active !== undefined && (r.uuid === active || r.name === active);
+
+  if (json) {
+    // Redacted objects — the apiKey is intentionally never included.
+    const payload = rows.map((r) => ({
+      index: r.index,
+      name: r.name ?? null,
+      uuid: r.uuid ?? null,
+      agentType: r.agentType ?? null,
+      url: originOf(r.url),
+      daemonWake: r.daemonWake ?? null,
+      active: isActive(r),
+    }));
+    out.write(`${JSON.stringify(payload, null, 2)}\n`);
+    return 0;
+  }
+
+  if (rows.length === 0) {
+    out.write(
+      `No agents configured in ${loginPath}.\n` +
+        "Run `chorus agents add` (or `chorus login`) to add one.\n",
+    );
+    return 0;
+  }
+
+  out.write(`Agents in ${loginPath}:\n`);
+  for (const r of rows) {
+    const mark = isActive(r) ? "* " : "  ";
+    const name = r.name ?? "(unnamed)";
+    const uuid = r.uuid ?? "(no uuid)";
+    const bits = [r.agentType ?? "?"];
+    if (r.daemonWake === false) bits.push("wake:off");
+    const host = hostOf(r.url);
+    if (host) bits.push(host);
+    out.write(`${mark}[${r.index}] ${name}  ${uuid}  (${bits.join(", ")})\n`);
+  }
+  if (active) {
+    out.write(
+      rows.some(isActive)
+        ? `\n* = active (CHORUS_AGENT_PROFILE="${active}")\n`
+        : `\n(note: CHORUS_AGENT_PROFILE="${active}" is set but matches no agent above)\n`,
+    );
+  }
+  out.write(
+    "\nPass a UUID or name to `chorus mcp --agent <name|uuid>` or set CHORUS_AGENT_PROFILE.\n" +
+      "API keys are never shown.\n",
+  );
+  return 0;
+}
+
+/** Usage for `chorus agents remove`. */
+function removeHelpText() {
+  return "USAGE\n  chorus agents remove <name|uuid>   Remove a configured agent from ~/.chorus/daemon.json\n";
+}
+
+/**
+ * `chorus agents remove <name|uuid>` — drop the matching `agents[]` entry.
+ * Merge-safe: rewrites daemon.json replacing `agents[]` with the filtered array,
+ * preserving every other agent and all top-level fields. The API key is NEVER
+ * printed. dependency-injected (readJson/writeConfig/loginPath) for tests.
+ * @param {string[]} argv  args after the `remove` word (argv[0] = target).
+ * @param {object} [opts]
+ * @returns {number}
+ */
+export function removeAgent(argv = [], opts = {}) {
+  const out = opts.stdout ?? process.stdout;
+  const err = opts.stderr ?? process.stderr;
+  const readJson = opts.readJson ?? readJsonSafe;
+  const loginPath = opts.loginPath ?? loginFilePath();
+  const writeConfig = opts.writeConfig ?? ((partial) => updateDaemonConfig(partial, { path: loginPath }));
+
+  const first = argv[0];
+  if (first === "--help" || first === "-h") {
+    out.write(removeHelpText());
+    return 0;
+  }
+  const target = nonEmpty(first);
+  if (!target) {
+    err.write("error: `chorus agents remove` requires an agent name or UUID.\n" + removeHelpText());
+    return 2;
+  }
+
+  const file = readJson(loginPath);
+  const agents = file && Array.isArray(file.agents) ? file.agents.filter((a) => a && typeof a === "object") : [];
+  const keysOf = (a) => [a.agentUuid, a.agentName, a.label, a.name].map(nonEmpty).filter((k) => k !== undefined);
+  const matches = [];
+  agents.forEach((a, i) => {
+    if (keysOf(a).includes(target)) matches.push(i);
+  });
+
+  if (matches.length === 0) {
+    err.write(`error: no configured agent matches "${target}" in ${loginPath}.\n`);
+    if (agents.length) {
+      err.write("Configured agents:\n");
+      agents.forEach((a, i) =>
+        err.write(`  [${i}] ${nonEmpty(a.agentName) ?? "(unnamed)"}  ${nonEmpty(a.agentUuid) ?? "(no uuid)"}\n`),
+      );
+    } else {
+      err.write("(none configured)\n");
+    }
+    return 1;
+  }
+  if (matches.length > 1) {
+    err.write(
+      `error: "${target}" is ambiguous — it matches ${matches.length} agents. Use the agent UUID to disambiguate.\n`,
+    );
+    return 2;
+  }
+
+  const idx = matches[0];
+  const removed = agents[idx];
+  const remaining = agents.filter((_, i) => i !== idx);
+  // Replace agents[] wholesale (updateDaemonConfig shallow-merges the patch, so a
+  // new `agents` array overwrites the old one) — preserves every top-level field.
+  writeConfig({ agents: remaining });
+
+  out.write(
+    `Removed agent ${nonEmpty(removed.agentName) ?? "(unnamed)"} (${nonEmpty(removed.agentUuid) ?? "no uuid"}) ` +
+      `from ${loginPath}. ${remaining.length} agent(s) remain.\n`,
+  );
+  // dsh: $DSH_HOME/.env holds a single shared url+key (not per-agent) and is left
+  // untouched. dsh maps to the "offline" daemon agentType bucket — surface the note there.
+  if (nonEmpty(removed.agentType) === "offline") {
+    out.write(
+      "Note: any dsh $DSH_HOME/.env credentials were left untouched (a single shared file) — clear them manually if needed.\n",
+    );
+  }
+  // Claude Code: `chorus agents add` may have written CHORUS_* into the user-global
+  // ~/.claude/settings.json env block. Reverse cleanup is out of scope — leave it in place
+  // (a later re-add overwrites it idempotently) but tell the operator, mirroring the dsh note.
+  if (nonEmpty(removed.agentType) === "claude-code") {
+    out.write(
+      "Note: any CHORUS_* keys written into ~/.claude/settings.json were left untouched — clear them manually if needed.\n",
+    );
+  }
+  // Codex: `chorus agents add` may have written CHORUS_* into ~/.codex/.env (and a keyless
+  // [mcp_servers.chorus] block that references CHORUS_API_KEY via bearer_token_env_var in
+  // ~/.codex/config.toml — no literal key). Reverse cleanup is out of scope — leave it, tell the operator.
+  if (nonEmpty(removed.agentType) === "codex") {
+    out.write(
+      "Note: any CHORUS_* env written into ~/.codex/.env " +
+        "(and the keyless [mcp_servers.chorus] block in ~/.codex/config.toml, which references the key via bearer_token_env_var) were left untouched — clear them manually if needed.\n",
+    );
+  }
+  return 0;
+}
+
+/**
+ * Run `chorus agents [list|add|remove] …`. Dispatches the sub-verb:
+ *   (none) / `list`   → list configured agents
+ *   `add [flags]`     → runInit (the flow formerly reached via `chorus init`)
+ *   `remove <n|uuid>` → removeAgent
+ * A group-level `--help`/`-h` prints the group usage. Never boots the server.
+ * Returns an exit code (or a Promise thereof for `add`).
+ * @param {string[]} argv  argv AFTER the `agents` word.
+ * @param {object} [opts]
+ * @returns {number | Promise<number>}
+ */
+export function runAgents(argv = [], opts = {}) {
+  const out = opts.stdout ?? process.stdout;
+  const err = opts.stderr ?? process.stderr;
+  const version = opts.version ?? "";
+  const first = argv[0];
+
+  if (first === "--help" || first === "-h") {
+    out.write(agentsHelpText(version));
+    return 0;
+  }
+  if (first === "add") {
+    // Delegate to the existing init flow (renamed entry). Dynamic import keeps the
+    // list/remove paths from loading the heavier init subsystem.
+    const runInit = opts.runInit ?? (async (a, o) => (await import("./init.mjs")).runInit(a, o));
+    return runInit(argv.slice(1), { version });
+  }
+  if (first === "remove") {
+    return removeAgent(argv.slice(1), opts);
+  }
+  // An unknown positional sub-verb (not `list`, not a flag) is a usage error.
+  if (first !== undefined && first !== "list" && !first.startsWith("-")) {
+    err.write(`error: unknown \`chorus agents\` subcommand: ${first}\n\n${agentsHelpText(version)}`);
+    return 2;
+  }
+  // Bare `chorus agents`, explicit `list`, or list flags (--json/--help handled inside).
+  return listAgents(first === "list" ? argv.slice(1) : argv, opts);
+}

package/cli/chorus-client.mjs

@@ -76,6 +76,56 @@ export class ChorusClient {
     }
   }
 
+  /**
+   * Like {@link callTool} but returns the tool result's text content VERBATIM,
+   * never JSON-parsed — the byte-faithful form the `chorus mcp call` CLI prints
+   * to stay a drop-in for `chorus-api.sh mcp-tool` (which emits
+   * `.result.content[].text`). `text` is the newline-join of every `content[]`
+   * block whose `type` is `text`. Lazy-connects; retries once on a stateless
+   * 404 / session-expired error, mirroring {@link callTool}.
+   * @param {string} name
+   * @param {Record<string, unknown>} [args]
+   * @returns {Promise<{ isError: boolean, text: string }>}
+   */
+  async callToolRaw(name, args = {}) {
+    if (!this.client || this.status !== "connected") await this.connect();
+    try {
+      return await this.#doCallToolRaw(name, args);
+    } catch (err) {
+      if (this.#isSessionExpired(err)) {
+        this.logger.warn("MCP session expired, reconnecting...");
+        this.status = "reconnecting";
+        this.client = null;
+        this.transport = null;
+        await this.connect();
+        return await this.#doCallToolRaw(name, args);
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * List the tools this connection's API key is permitted to see. Lazy-connects;
+   * retries once on a stateless 404 / session-expired error.
+   * @returns {Promise<Array<{ name: string, description: string }>>}
+   */
+  async listTools() {
+    if (!this.client || this.status !== "connected") await this.connect();
+    try {
+      return await this.#doListTools();
+    } catch (err) {
+      if (this.#isSessionExpired(err)) {
+        this.logger.warn("MCP session expired, reconnecting...");
+        this.status = "reconnecting";
+        this.client = null;
+        this.transport = null;
+        await this.connect();
+        return await this.#doListTools();
+      }
+      throw err;
+    }
+  }
+
   async disconnect() {
     if (this.client) {
       try {
@@ -89,6 +139,25 @@ export class ChorusClient {
     this.status = "disconnected";
   }
 
+  /** @param {string} name @param {Record<string, unknown>} args */
+  async #doCallToolRaw(name, args) {
+    if (!this.client) throw new Error("MCP client not connected");
+    const result = await this.client.callTool({ name, arguments: args });
+    const blocks = /** @type {Array<{type:string,text?:string}>} */ (result.content ?? []);
+    const text = blocks
+      .filter((c) => c.type === "text")
+      .map((c) => c.text ?? "")
+      .join("\n");
+    return { isError: Boolean(result.isError), text };
+  }
+
+  async #doListTools() {
+    if (!this.client) throw new Error("MCP client not connected");
+    const result = await this.client.listTools();
+    const tools = /** @type {Array<{name:string,description?:string}>} */ (result.tools ?? []);
+    return tools.map((t) => ({ name: t.name, description: t.description ?? "" }));
+  }
+
   /** @param {string} name @param {Record<string, unknown>} args */
   async #doCallTool(name, args) {
     if (!this.client) throw new Error("MCP client not connected");

package/cli/claude-spawner.mjs

@@ -329,6 +329,10 @@ export class ClaudeSpawner {
     if (this.creds) {
       if (this.creds.url) childEnv.CHORUS_URL = this.creds.url;
       if (this.creds.apiKey) childEnv.CHORUS_API_KEY = this.creds.apiKey;
+      // Identity profile for the woken session — its hooks/skills pass this to
+      // `chorus mcp --agent`, which resolves the key from ~/.chorus/daemon.json.
+      if (this.creds.agentUuid || this.creds.agentName)
+        childEnv.CHORUS_AGENT_PROFILE = this.creds.agentUuid || this.creds.agentName;
     }
 
     return new Promise((resolve) => {

package/cli/codex-spawner.mjs

@@ -14,12 +14,13 @@
 //     `resume <thread_id>`. (serde: ThreadEvent tag="type", rename="thread.started";
 //     ThreadStartedEvent.thread_id: String — codex-rs/exec/src/exec_events.rs.)
 //   • No `--mcp-config`: Codex reads MCP servers from the user's ~/.codex/config.toml.
-//     The Chorus MCP key there is USER-MANAGED: the installer writes a LITERAL Bearer
-//     header and Codex does NOT expand ${VAR} inside http_headers, so the CHORUS_API_KEY
-//     the daemon exports does NOT reach Codex's MCP auth. The daemon still exports
-//     CHORUS_URL / CHORUS_API_KEY into the child env — but only for the plugin's shell
-//     tooling (chorus-api.sh / SessionStart hooks), never argv and never Codex MCP.
-//     (Multi-agent: two Codex agents with different keys each need their own CODEX_HOME.)
+//     `chorus agents add` writes [mcp_servers.chorus] with bearer_token_env_var =
+//     "CHORUS_API_KEY" — a KEYLESS reference (no literal key in config.toml), and Codex
+//     resolves that env var into `Authorization: Bearer <key>` at connect. So the
+//     CHORUS_API_KEY the daemon exports into the child env below DOES reach Codex's MCP
+//     auth (as well as the plugin's shell tooling — chorus-api.sh / SessionStart hooks);
+//     never argv. (Multi-agent: two Codex agents with different keys each need their own
+//     CODEX_HOME so their config.toml + ~/.codex/.env don't collide.)
 //   • Permission is a SANDBOX mode, not a tool allowlist.
 //
 // Reuses claude-spawner's platform-neutral helpers: parseNdjsonChunk (NDJSON
@@ -276,6 +277,10 @@ export class CodexSpawner {
     if (this.creds) {
       if (this.creds.url) childEnv.CHORUS_URL = this.creds.url;
       if (this.creds.apiKey) childEnv.CHORUS_API_KEY = this.creds.apiKey;
+      // Identity profile for the woken session — its hooks/skills pass this to
+      // `chorus mcp --agent`, which resolves the key from ~/.chorus/daemon.json.
+      if (this.creds.agentUuid || this.creds.agentName)
+        childEnv.CHORUS_AGENT_PROFILE = this.creds.agentUuid || this.creds.agentName;
     }
 
     return new Promise((resolve) => {

package/cli/credentials.mjs

@@ -159,13 +159,26 @@ export function resolveCredentials(flags = {}, deps = {}) {
     if (url && apiKey) return { url, apiKey, source: "env" };
   }
 
-  // 3. Login file (~/.chorus/daemon.json)
+  // 3. Login file (~/.chorus/daemon.json): the flat top-level url/apiKey, else the
+  //    first agents[] entry. The flat top-level agent config is DEPRECATED — `chorus
+  //    init` now writes credentials only into agents[] — so fall back to agents[0]
+  //    so this single-credential resolver (install/daemon-setup gate, legacy flat
+  //    daemon) still resolves from an agents[]-only daemon.json.
   tried.push(`login file (${loginPath}, run \`chorus login\`)`);
   {
     const file = readJson(loginPath);
     if (file) {
-      const url = nonEmpty(file.url);
-      const apiKey = nonEmpty(file.apiKey);
+      let url = nonEmpty(file.url);
+      let apiKey = nonEmpty(file.apiKey);
+      if (!(url && apiKey) && Array.isArray(file.agents)) {
+        const a0 = file.agents.find(
+          (a) => a && typeof a === "object" && nonEmpty(a.url) && nonEmpty(a.apiKey),
+        );
+        if (a0) {
+          url = nonEmpty(a0.url);
+          apiKey = nonEmpty(a0.apiKey);
+        }
+      }
       if (url && apiKey) return { url, apiKey, source: "login-file" };
     }
   }
@@ -194,3 +207,172 @@ export function resolveCredentials(flags = {}, deps = {}) {
       "  • login:   chorus login   (persists to ~/.chorus/daemon.json)\n"
   );
 }
+
+/**
+ * @typedef {Object} McpCredentials
+ * @property {string} url
+ * @property {string} apiKey
+ * @property {string} label  Diagnostic label for the acting identity ("flag" /
+ *   "env" / a `~/.chorus/daemon.json` agent name/label / the flat-resolution source).
+ */
+
+/**
+ * Resolve the url + `cho_` API key AND the acting agent identity for the
+ * `chorus mcp` command group. Unlike `resolveCredentials`, this understands the
+ * multi-agent `agents[]` model and refuses to guess which agent to act as.
+ *
+ * PROFILE identity (AWS-CLI style): a caller can name WHICH agent to act as by
+ * `--agent <name|uuid>` (explicit flag) or the `CHORUS_AGENT_PROFILE` env var,
+ * and this resolves that agent's key from `~/.chorus/daemon.json` — the secret
+ * never has to be threaded through the caller's environment. A profile matches
+ * an `agents[]` entry by its `agentUuid`, `agentName`, or the back-compat
+ * `label`/`name` aliases (exact). Ambiguous (matches >1 entry) → hard error.
+ *
+ * Precedence (owner decision: PREFER profile, fall back to url+key mode when no
+ * profile resolves — the key stays written in daemon.json, url+key is the
+ * fallback so the CLI-absent curl path still works):
+ *   1. Explicit `--agent <name|uuid>` flag → deliberate profile selection from
+ *      `agents[]`, PREFERRED over an explicit url+key pair (no match → hard error
+ *      listing agents). With NO `agents[]` it rides along an explicit `--url/--api-key`
+ *      pair (else the env pair) as the label, else it is a usage error.
+ *   2. Explicit `--url` + `--api-key` flags (no `--agent`) → used directly
+ *      (identity is explicit); a `CHORUS_AGENT_PROFILE` name rides along as the label.
+ *   3. `CHORUS_AGENT_PROFILE` env → ambient profile selection from `agents[]`.
+ *      A match wins over the url+key env pair; NO match falls through (the
+ *      profile "doesn't exist" → url-mode fallback), an ambiguous match throws.
+ *   4. `CHORUS_URL` + `CHORUS_API_KEY` env pair → used directly (url-mode
+ *      fallback / legacy plugin-hook path); a profile name rides as the label.
+ *   5. Exactly one agent in `agents[]` + nothing specified → that agent.
+ *   6. More than one agent + nothing specified → hard error (never pick
+ *      silently), listing the available agents.
+ *   7. No `agents[]` → flat resolution via `resolveCredentials`.
+ *
+ * Each selected agent's `url`/`apiKey` merges over the top-level per-field
+ * defaults (`resolveCredentialDefaults`), so an agent that omits a field
+ * inherits it.
+ *
+ * This never imports `cli/daemon-config.mjs` (which imports THIS module) — it
+ * reads `agents[]` directly to stay cycle-free; only url/apiKey/label matter for
+ * MCP, so per-agent agentType/permissionMode validation is intentionally skipped.
+ *
+ * @param {{ url?: string, apiKey?: string, agent?: string }} flags
+ * @param {ResolveDeps} [deps]
+ * @returns {McpCredentials}
+ * @throws {Error} on ambiguity, a missing `--agent` label, or nothing resolvable.
+ */
+export function resolveMcpCredentials(flags = {}, deps = {}) {
+  const env = deps.env ?? process.env;
+  const readJson = deps.readJson ?? readJsonSafe;
+  const loginPath = deps.loginPath ?? loginFilePath();
+  const flagAgent = nonEmpty(flags.agent);
+  const envProfile = nonEmpty(env.CHORUS_AGENT_PROFILE);
+  // The profile name a caller asked for, whatever its source — used as the
+  // diagnostic label when creds ultimately come from explicit flags / the env pair.
+  const wanted = flagAgent ?? envProfile;
+
+  const envPair = () => {
+    const url = nonEmpty(env.CHORUS_URL);
+    const apiKey = nonEmpty(env.CHORUS_API_KEY);
+    return url && apiKey ? { url, apiKey } : null;
+  };
+  const flagPair = () => {
+    const url = nonEmpty(flags.url);
+    const apiKey = nonEmpty(flags.apiKey);
+    return url && apiKey ? { url, apiKey } : null;
+  };
+
+  // Read agents[] once and pre-resolve every entry (label, its match keys, and
+  // its effective url/apiKey merged over the top-level per-field defaults).
+  const file = readJson(loginPath);
+  const agentEntries =
+    file && Array.isArray(file.agents)
+      ? file.agents.filter((a) => a && typeof a === "object")
+      : [];
+  const hasAgents = agentEntries.length > 0;
+  const defaults = hasAgents ? resolveCredentialDefaults(flags, deps) : { url: undefined, apiKey: undefined };
+  const labelOf = (entry, i) =>
+    nonEmpty(entry.agentName) ?? nonEmpty(entry.label) ?? nonEmpty(entry.name) ?? `agents[${i}]`;
+  const resolved = agentEntries.map((entry, i) => ({
+    label: labelOf(entry, i),
+    // A profile may name an entry by its uuid, its display name, or the
+    // back-compat label/name aliases.
+    keys: [entry.agentUuid, entry.agentName, entry.label, entry.name]
+      .map((k) => nonEmpty(k))
+      .filter((k) => k !== undefined),
+    url: nonEmpty(entry.url) ?? defaults.url,
+    apiKey: nonEmpty(entry.apiKey) ?? defaults.apiKey,
+  }));
+  const labels = resolved.map((a) => a.label).join(", ");
+  const pick = (a) => {
+    if (!a.url || !a.apiKey) {
+      throw new Error(
+        `Agent "${a.label}" in ${loginPath} is missing a url or apiKey (and no top-level default supplies it).`,
+      );
+    }
+    return { url: a.url, apiKey: a.apiKey, label: a.label };
+  };
+  const matchesFor = (name) => resolved.filter((a) => a.keys.includes(name));
+  const selectOrThrow = (name, source) => {
+    const matches = matchesFor(name);
+    if (matches.length === 1) return pick(matches[0]);
+    if (matches.length > 1) {
+      throw new Error(
+        `${source} "${name}" is ambiguous in ${loginPath} — it matches ${matches.length} agents ` +
+          `(${matches.map((m) => m.label).join(", ")}). Use the agent UUID to disambiguate.`,
+      );
+    }
+    return null; // no match
+  };
+
+  // 1. Explicit --agent flag: a deliberate profile selection — PREFERRED over an
+  //    explicit url+key flag pair (owner: "prefer profile"). With NO agents[] to
+  //    match, it rides an explicit flag pair (else the env pair), using the name
+  //    as the diagnostic label; with neither it is a usage error.
+  if (flagAgent) {
+    if (hasAgents) {
+      const hit = selectOrThrow(flagAgent, "--agent");
+      if (hit) return hit;
+      throw new Error(`--agent "${flagAgent}" not found in ${loginPath} agents[]. Available: ${labels}.`);
+    }
+    const pair = flagPair() ?? envPair();
+    if (pair) return { url: pair.url, apiKey: pair.apiKey, label: flagAgent };
+    throw new Error(
+      `--agent "${flagAgent}" was given but ${loginPath} declares no agents[]. ` +
+        `Remove --agent, or configure an agents[] list.`,
+    );
+  }
+
+  // 2. Explicit url+key flag pair (no --agent) — identity is explicit.
+  {
+    const pair = flagPair();
+    if (pair) return { url: pair.url, apiKey: pair.apiKey, label: wanted ?? "flag" };
+  }
+
+  // 3. CHORUS_AGENT_PROFILE env: ambient profile selection. A match wins over the
+  //    url+key env pair; a no-match falls through to url-mode (profile "doesn't
+  //    exist"); an ambiguous match throws.
+  if (envProfile && hasAgents) {
+    const hit = selectOrThrow(envProfile, "CHORUS_AGENT_PROFILE");
+    if (hit) return hit;
+    // no match → fall through to the url-mode fallback below
+  }
+
+  // 4. Env pair (url-mode fallback). Carry the profile name as the label if set.
+  {
+    const pair = envPair();
+    if (pair) return { url: pair.url, apiKey: pair.apiKey, label: wanted ?? "env" };
+  }
+
+  // 5/6. agents[] with nothing specified: auto-single, else hard error.
+  if (hasAgents) {
+    if (resolved.length === 1) return pick(resolved[0]);
+    throw new Error(
+      `Multiple agents are configured in ${loginPath} (${labels}). ` +
+        `Specify which one to act as with --agent <name|uuid> or CHORUS_AGENT_PROFILE.`,
+    );
+  }
+
+  // 7. No agents[] → flat resolution (throws the detailed "could not resolve" error).
+  const flat = resolveCredentials(flags, deps);
+  return { url: flat.url, apiKey: flat.apiKey, label: flat.source };
+}