@mrrlin-dev/external-agents 0.2.4 → 0.2.6

package/README.md

@@ -86,9 +86,32 @@ Open the local dashboard with `external-agents ui` and you'll get a page like:
 
 Once installed, add one block to your MCP client config.
 
-The package ships a dedicated `external-agents-mcp` binary — the MCP server entry — so client configs are plain command lines with no args.
+The package ships a dedicated `external-agents-mcp` binary — the MCP server entry — so client configs are plain command lines with no args. **Both Claude Code and Codex expose a one-liner** for this; you should never have to hand-edit config files unless you want to.
+
+### Claude Code
+
+```bash
+claude mcp add external-agents external-agents-mcp
+```
+
+(Uses the native `claude mcp add <name> <command>` — the CLI writes the block into `~/.claude.json` for you and Claude Code picks it up on next start.)
+
+### Codex
+
+```bash
+codex mcp add external-agents -- external-agents-mcp
+```
+
+(Uses the native `codex mcp add <name> -- <command>` — the CLI writes `[mcp_servers.external-agents]` into `~/.codex/config.toml`.)
+
+### Cursor
+
+Settings → MCP → Add server → command `external-agents-mcp`, no args.
+
+### Manual (any other client)
+
+If your MCP client doesn't have a one-liner, the config block is:
 
-**Claude Code** (`~/.claude.json`):
 ```json
 {
   "mcpServers": {
@@ -100,14 +123,15 @@ The package ships a dedicated `external-agents-mcp` binary — the MCP server en
 }
 ```
 
-**Codex Code** (`~/.codex/config.toml`):
+or TOML equivalent:
+
 ```toml
 [mcp_servers.external-agents]
 command = "external-agents-mcp"
 args = []
 ```
 
-**Cursor** — Settings → MCP → Add server → command `external-agents-mcp`, no args.
+No publishing step — the MCP server is just `external-agents-mcp` on your PATH once you `npm i -g @mrrlin-dev/external-agents`. Nothing to host, nothing to expose over the network; it's a stdio-transport MCP server that runs locally, same as any other npm-installed CLI.
 
 Your primary agent now has these low-level tools (build your own exec/review flows on top):
 

package/cli.js

@@ -18,28 +18,16 @@ import { loadRegistry } from "./lib/registry.js";
 import { readState, writeState, probeInstalled } from "./lib/state.js";
 import { runAny, resolveEscalation, parseExhaustionSignal, getStats } from "./lib/dispatch.js";
 import { pickAgents } from "./lib/pick.js";
+import { persistCredential, bootEnv, KEYS_FILE } from "./lib/credentials.js";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { spawn } from "node:child_process";
 
-// bootEnv duplicated from server.js so CLI + server load the same env context.
-function bootEnv() {
-  try {
-    const kiloAuthPath = path.join(os.homedir(), ".local/share/kilo/auth.json");
-    if (fs.existsSync(kiloAuthPath)) {
-      const a = JSON.parse(fs.readFileSync(kiloAuthPath, "utf-8"));
-      if (!process.env.DEEPSEEK_API_KEY && a.deepseek?.key) process.env.DEEPSEEK_API_KEY = a.deepseek.key;
-    }
-    const llmKeysPath = path.join(os.homedir(), "Library/Application Support/io.datasette.llm/keys.json");
-    if (!process.env.GEMINI_API_KEY || !process.env.GEMINI_API_KEY.startsWith("AIza")) {
-      if (fs.existsSync(llmKeysPath)) {
-        const k = JSON.parse(fs.readFileSync(llmKeysPath, "utf-8"));
-        if (k.gemini) process.env.GEMINI_API_KEY = k.gemini;
-      }
-    }
-  } catch {}
-}
+// CLI + MCP server share the same env-loading logic — see lib/credentials.js.
+// This ensures `external-agents set-credential FOO_KEY ...` followed by
+// `external-agents probe some-agent` reads the just-written keys.env, and the
+// two invocation surfaces (CLI here, MCP server in server.js) never drift.
 bootEnv();
 
 const REGISTRY_PATH = path.join(path.dirname(new URL(import.meta.url).pathname), "agents.yaml");
@@ -185,6 +173,41 @@ function cmdProbe(args) {
   console.log(JSON.stringify({ id: agentId, ...result, checked }));
 }
 
+// `external-agents set-credential ENV_NAME [value]` — persist a credential to
+// ~/.local/state/external-agents/keys.env (0600). Two input paths:
+//   - value supplied as an argument (fine for scripts)
+//   - value read from stdin when the argument is `-` or omitted (safer for
+//     interactive use — no shell-history leak, no ps-listing exposure).
+// After persisting, the current process env is updated so a follow-up probe /
+// dispatch inside the same shell script sees the new value.
+async function cmdSetCredential(args) {
+  const [envName, valueArg] = args;
+  if (!envName) {
+    die("usage: external-agents set-credential <ENV_NAME> [<value> | -]\n  <value> may be `-` (or omitted) to read from stdin", 2);
+  }
+  let value = valueArg;
+  if (!value || value === "-") {
+    // Read from stdin. If a TTY, prompt on stderr.
+    if (process.stdin.isTTY) {
+      process.stderr.write(`Enter value for ${envName} (echoed): `);
+    }
+    value = await new Promise((resolve) => {
+      let buf = "";
+      process.stdin.setEncoding("utf-8");
+      process.stdin.on("data", (chunk) => { buf += chunk; });
+      process.stdin.on("end", () => resolve(buf.replace(/\r?\n$/, "")));
+    });
+  }
+  try {
+    const persistedTo = persistCredential(envName, value);
+    // Print to stderr so stdout stays clean for scripting; do NOT echo the value.
+    console.error(`external-agents: ${envName} persisted to ${persistedTo}`);
+    console.error(`  Restart your MCP client (Codex / Claude Code) so its external-agents-mcp instance re-reads keys.env at startup.`);
+  } catch (e) {
+    die(`set-credential failed: ${e.message}`, 2);
+  }
+}
+
 // `external-agents ui` — spawn the loopback dashboard (ui.js) inline so the CLI
 // stays the single entry point. ui.js runs its server at top level and blocks;
 // we spawn it as a child so cli.js does not need to import server-lifecycle code
@@ -211,6 +234,7 @@ switch (subcmd) {
   case "probe":    cmdProbe(args); break;
   case "stats":    cmdStats(flags); break;
   case "ui":       cmdUi(flags); break;
+  case "set-credential": await cmdSetCredential(args); break;
   case "help":
   case "--help":
   case undefined:
@@ -220,7 +244,8 @@ switch (subcmd) {
   status [--json]
   probe <agent-id>
   stats [--since ISO] [--json]
-  ui [--port N] [--host H]        # local dashboard for setting keys + inspecting state (default http://127.0.0.1:4711)`);
+  ui [--port N] [--host H]        # local dashboard for setting keys + inspecting state (default http://127.0.0.1:4711)
+  set-credential <ENV_NAME> [<value> | -]  # persist a key to ~/.local/state/external-agents/keys.env (0600); '-' or omitted = read from stdin`);
     process.exit(subcmd ? 0 : 2);
   default: die(`unknown subcommand: ${subcmd}`, 2);
 }

package/lib/credentials.js

@@ -0,0 +1,100 @@
+// Persistent credential store for external-agents.
+//
+// Backing file: ~/.local/state/external-agents/keys.env (mode 0600, one
+// KEY=value per line, no quotes). This is the operator-facing store — it wins
+// over legacy per-provider stores (Kilo's auth.json, Simon Willison's llm keys,
+// per-entry @file: refs) at bootEnv time.
+//
+// Exposed as a plain module (no side effects at import time) so both the MCP
+// server (server.js) and the CLI (cli.js) can import from here without spinning
+// up an MCP transport.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export const KEYS_FILE = path.join(os.homedir(), ".local/state/external-agents/keys.env");
+
+export function loadKeysFile() {
+  try {
+    if (!fs.existsSync(KEYS_FILE)) return {};
+    const raw = fs.readFileSync(KEYS_FILE, "utf-8");
+    const out = {};
+    for (const line of raw.split(/\r?\n/)) {
+      const t = line.trim();
+      if (!t || t.startsWith("#")) continue;
+      const eq = t.indexOf("=");
+      if (eq < 0) continue;
+      const k = t.slice(0, eq).trim();
+      const v = t.slice(eq + 1);
+      if (k) out[k] = v;
+    }
+    return out;
+  } catch (e) {
+    console.error(`external-agents: WARN — keys.env unreadable: ${e.message}`);
+    return {};
+  }
+}
+
+export function saveKeysFile(kv) {
+  const dir = path.dirname(KEYS_FILE);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const body = Object.entries(kv)
+    .filter(([k, v]) => k && typeof v === "string")
+    .map(([k, v]) => `${k}=${v}`).join("\n") + "\n";
+  const tmp = KEYS_FILE + ".tmp." + process.pid + "." + Date.now();
+  fs.writeFileSync(tmp, body, { mode: 0o600 });
+  fs.renameSync(tmp, KEYS_FILE);
+}
+
+// Populate process.env from all credential sources this package knows about,
+// in priority order:
+//   1. keys.env (UI-persisted / `set-credential` — operator's explicit choice)
+//   2. Kilo auth store (~/.local/share/kilo/auth.json) — DeepSeek only
+//   3. Simon Willison's llm CLI keys (~/Library/Application Support/io.datasette.llm/keys.json) — AI Studio Gemini
+// Never overrides an already-set env var. Same logic in server.js and cli.js
+// used to drift — this is the single source of truth now.
+export function bootEnv() {
+  try {
+    // 1. UI-persisted / set-credential keys — highest priority
+    const persisted = loadKeysFile();
+    for (const [k, v] of Object.entries(persisted)) {
+      if (!process.env[k]) process.env[k] = v;
+    }
+    // 2. Kilo auth store — DeepSeek key
+    const kiloAuthPath = path.join(os.homedir(), ".local/share/kilo/auth.json");
+    if (fs.existsSync(kiloAuthPath)) {
+      const kiloAuth = JSON.parse(fs.readFileSync(kiloAuthPath, "utf-8"));
+      if (!process.env.DEEPSEEK_API_KEY && kiloAuth.deepseek?.key) {
+        process.env.DEEPSEEK_API_KEY = kiloAuth.deepseek.key;
+      }
+    }
+    // 3. llm-key store — AI Studio Gemini `AIza...` key
+    const llmKeysPath = path.join(os.homedir(), "Library/Application Support/io.datasette.llm/keys.json");
+    if (!process.env.GEMINI_API_KEY || !process.env.GEMINI_API_KEY.startsWith("AIza")) {
+      if (fs.existsSync(llmKeysPath)) {
+        const llmKeys = JSON.parse(fs.readFileSync(llmKeysPath, "utf-8"));
+        if (llmKeys.gemini) process.env.GEMINI_API_KEY = llmKeys.gemini;
+      }
+    }
+  } catch (e) {
+    console.error(`external-agents: WARN — bootEnv failed: ${e.message}`);
+  }
+}
+
+// Persist a credential to the keys.env store AND inject into the current
+// process's env so subsequent calls in the same process see it. Returns the
+// path the credential was persisted to so callers can report it back to the
+// operator. Env-var-name is validated: SHOUTY_SNAKE_CASE only.
+export function persistCredential(envName, value) {
+  if (!envName || !/^[A-Z_][A-Z0-9_]*$/.test(envName)) {
+    throw new Error(`invalid env var name: ${JSON.stringify(envName)} (expected SHOUTY_SNAKE_CASE)`);
+  }
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error("credential value must be a non-empty string");
+  }
+  const persisted = loadKeysFile();
+  persisted[envName] = value;
+  saveKeysFile(persisted);
+  process.env[envName] = value;
+  return KEYS_FILE;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrrlin-dev/external-agents",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "One MCP server for every LLM you talk to — direct-API dispatcher across Gemini, DeepSeek, Groq, OpenRouter, Cerebras, and more. Part of mrrlin.com.",
   "type": "module",
   "main": "server.js",

package/server.js

@@ -16,86 +16,12 @@ import { pickAgents } from "./lib/pick.js";
 
 const REGISTRY = loadRegistry("./agents.yaml");
 
-// Env-var boot injection. Look for credentials in known local stores and populate
-// process.env for aider/other CLIs. Never overrides an already-set var.
-// UI-set persisted keys — loaded FIRST (highest precedence) so a value the
-// operator saved via /api/set_credential wins over whatever legacy stores
-// contain. File format: one KEY=value per line, no quotes. Mode 0600.
-const KEYS_FILE = path.join(os.homedir(), ".local/state/external-agents/keys.env");
-
-function loadKeysFile() {
-  try {
-    if (!fs.existsSync(KEYS_FILE)) return {};
-    const raw = fs.readFileSync(KEYS_FILE, "utf-8");
-    const out = {};
-    for (const line of raw.split(/\r?\n/)) {
-      const t = line.trim();
-      if (!t || t.startsWith("#")) continue;
-      const eq = t.indexOf("=");
-      if (eq < 0) continue;
-      const k = t.slice(0, eq).trim();
-      const v = t.slice(eq + 1);
-      if (k) out[k] = v;
-    }
-    return out;
-  } catch (e) {
-    console.error(`external-agents-spike: WARN — keys.env unreadable: ${e.message}`);
-    return {};
-  }
-}
-
-function saveKeysFile(kv) {
-  const dir = path.dirname(KEYS_FILE);
-  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const body = Object.entries(kv)
-    .filter(([k, v]) => k && typeof v === "string")
-    .map(([k, v]) => `${k}=${v}`).join("\n") + "\n";
-  const tmp = KEYS_FILE + ".tmp." + process.pid + "." + Date.now();
-  fs.writeFileSync(tmp, body, { mode: 0o600 });
-  fs.renameSync(tmp, KEYS_FILE);
-}
-
-function bootEnv() {
-  try {
-    // 1. UI-persisted keys (highest priority — operator explicitly set them)
-    const persisted = loadKeysFile();
-    for (const [k, v] of Object.entries(persisted)) {
-      if (!process.env[k]) process.env[k] = v;
-    }
-
-    // 2. Kilo auth store (legacy — DeepSeek key only; the Google proxy token
-    //    in Kilo does NOT work against direct Google API)
-    const kiloAuthPath = path.join(os.homedir(), ".local/share/kilo/auth.json");
-    if (fs.existsSync(kiloAuthPath)) {
-      const kiloAuth = JSON.parse(fs.readFileSync(kiloAuthPath, "utf-8"));
-      if (!process.env.DEEPSEEK_API_KEY && kiloAuth.deepseek?.key) {
-        process.env.DEEPSEEK_API_KEY = kiloAuth.deepseek.key;
-      }
-    }
-    // 3. llm-key store (AI Studio Gemini key, `AIza...` format)
-    const llmKeysPath = path.join(os.homedir(), "Library/Application Support/io.datasette.llm/keys.json");
-    if (!process.env.GEMINI_API_KEY || !process.env.GEMINI_API_KEY.startsWith("AIza")) {
-      if (fs.existsSync(llmKeysPath)) {
-        const llmKeys = JSON.parse(fs.readFileSync(llmKeysPath, "utf-8"));
-        if (llmKeys.gemini) process.env.GEMINI_API_KEY = llmKeys.gemini;
-      }
-    }
-  } catch (e) {
-    console.error(`external-agents-spike: WARN — bootEnv failed: ${e.message}`);
-  }
-}
+// Env-var boot injection lives in the shared credentials module (single source
+// of truth for CLI + MCP server + UI). Priority: keys.env → Kilo auth store →
+// llm keys. Never overrides an already-set env var.
+import { KEYS_FILE, loadKeysFile, persistCredential, bootEnv } from "./lib/credentials.js";
 bootEnv();
 
-// Exposed for the set_credential MCP tool + /api/set_credential UI route.
-export function persistCredential(envName, value) {
-  if (!envName || !/^[A-Z_][A-Z0-9_]*$/.test(envName)) throw new Error("invalid env var name");
-  const persisted = loadKeysFile();
-  persisted[envName] = value;
-  saveKeysFile(persisted);
-  // Also inject into the running process env so THIS session sees it immediately.
-  process.env[envName] = value;
-}
-
 function findAgent(id) {
   return REGISTRY.agents.find((a) => a.id === id);
 }