@drakon-systems/multi-clawd 1.2.2 → 1.3.0

package/README.md

@@ -171,7 +171,8 @@ npx @drakon-systems/multi-clawd update
 One command: checks the registry, installs the new version with the right
 flags, offers the gateway restart, and finishes with a doctor health check.
 (`npm i -g @drakon-systems/multi-clawd` once, and it's just `multi-clawd
-update` — with `multi-clawd setup` and `multi-clawd doctor` alongside.)
+update` — with `multi-clawd setup`, `multi-clawd explain` (your setup in
+plain English), and `multi-clawd doctor` alongside.)
 
 ```bash
 # From source:

package/dist/explain-core.js

@@ -0,0 +1,97 @@
+export function describeAccount(acc) {
+    if (acc.native) {
+        return "the machine's main `claude` login (default config dir; OS keychain on macOS)";
+    }
+    const parts = [];
+    if (acc.configDir)
+        parts.push(`its own isolated login dir: ${acc.configDir}`);
+    if (acc.oauthTokenRef) {
+        parts.push(`token resolved from ${acc.oauthTokenRef.provider ?? "a secret provider"} via a secret reference (never stored in plain text)`);
+    }
+    else if (acc.oauthTokenFile) {
+        parts.push(`token file at ${acc.oauthTokenFile}`);
+    }
+    else if (acc.configDir) {
+        parts.push(`uses the login stored inside that dir`);
+    }
+    return parts.join("; ") || "no credential source configured";
+}
+export function annotateChainRef(ref, pool) {
+    const slash = ref.indexOf("/");
+    const provider = slash > 0 ? ref.slice(0, slash) : undefined;
+    if (pool && provider === pool.id) {
+        const order = pool.accounts.join(", then ");
+        return `pool → ${order} (same model, next account before any tier drop)`;
+    }
+    if (!pool && provider && /^claw/.test(provider)) {
+        return `no pool configured — runs on the single account "${provider}"`;
+    }
+    if (provider && /^claw\d+$/.test(provider)) {
+        return `pinned to only ${provider} — no cross-account failover on this rung`;
+    }
+    if (provider === "anthropic" || provider === "claude-cli") {
+        return "direct to Anthropic — bypasses the pool (no cross-account failover)";
+    }
+    if (provider && provider.startsWith("claw")) {
+        return `runs on "${provider}"`;
+    }
+    return "leaves Claude — a different provider entirely";
+}
+const VERDICT_WORDS = {
+    ok: "OK — ready to serve",
+    no_data: "no recent telemetry — treated as healthy",
+    near_limit: "NEAR ITS LIMIT — the pool will hand over before it hard-fails",
+    exhausted: "EXHAUSTED",
+};
+export function renderExplanation(model) {
+    const lines = [];
+    lines.push("ACCOUNTS");
+    for (const acc of model.accounts) {
+        lines.push(`  ${acc.id}${acc.label ? `  "${acc.label}"` : ""}`);
+        lines.push(`    → ${describeAccount(acc)}`);
+    }
+    lines.push("");
+    if (model.pool) {
+        const pct = Math.round((model.pool.utilizationThreshold ?? 0.85) * 100);
+        lines.push(`POOL  ${model.pool.id}  (${model.pool.accounts.join(" → ")})`);
+        lines.push(`  Every Claude launch runs on the first account that is NOT nearly maxed`);
+        lines.push(`  out — hand-over at ${pct}% of any rate window, home account reclaims`);
+        lines.push(`  automatically once its window resets.`);
+        const ladder = model.pool.degrade?.ladder ?? [];
+        if (ladder.length > 0) {
+            lines.push(`  If the WHOLE pool is exhausted: step down to ${ladder.join(" → ")} first.`);
+        }
+        if ((model.pool.degrade?.pins?.length ?? 0) > 0) {
+            lines.push(`  ${model.pool.degrade?.pins?.length} pinned lane(s) never tier-drop.`);
+        }
+    }
+    else {
+        lines.push("POOL  (no pool configured — each account is a standalone backend)");
+    }
+    lines.push("");
+    if (model.chain?.primary || model.chain?.fallbacks?.length) {
+        lines.push("FAILOVER CHAIN  (agents.defaults)");
+        const rungs = [model.chain.primary, ...(model.chain.fallbacks ?? [])].filter((r) => typeof r === "string");
+        rungs.forEach((ref, i) => {
+            lines.push(`  ${i + 1}. ${ref}`);
+            lines.push(`       ${annotateChainRef(ref, model.pool)}`);
+        });
+    }
+    else {
+        lines.push("FAILOVER CHAIN  (none found under agents.defaults)");
+    }
+    lines.push("");
+    if (model.health.length > 0) {
+        lines.push("RIGHT NOW");
+        for (const h of model.health) {
+            const word = VERDICT_WORDS[h.verdict] ?? h.verdict;
+            lines.push(`  ${h.id}: ${word}${h.detail ? ` — ${h.detail}` : ""}`);
+        }
+        if (model.pool) {
+            lines.push(model.stickyAccount
+                ? `  pool is rotated onto ${model.stickyAccount} (returns home when the home window resets)`
+                : `  pool is on its home account (no rotation active)`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/setup-core.js

@@ -138,3 +138,22 @@ export function mergeSetupIntoConfig(existing, plan) {
     }
     return { config, changes };
 }
+export function existingAccountDefaults(config, id) {
+    const entries = asRecord(asRecord(asRecord(config)?.plugins)?.entries);
+    const entryConfig = asRecord(asRecord(entries?.["multi-clawd"])?.config);
+    const accounts = Array.isArray(entryConfig?.accounts) ? entryConfig?.accounts : [];
+    const acc = accounts.map(asRecord).find((a) => a?.id === id);
+    if (!acc)
+        return undefined;
+    return {
+        configDir: typeof acc.configDir === "string" ? acc.configDir : undefined,
+        label: typeof acc.label === "string" ? acc.label : undefined,
+        hasCredentials: acc.native === true ||
+            acc.oauthTokenRef !== undefined ||
+            acc.oauthTokenFile !== undefined ||
+            typeof acc.configDir === "string",
+    };
+}
+export function looksLikeSecretRef(id) {
+    return id.includes("://");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/multi-clawd",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "description": "Multi-account Claude Code failover for OpenClaw — register additional Claude (Max/Pro) logins as first-class CLI backends and keep the full skills/MCP harness across every account.",
   "type": "module",
   "license": "MIT",

package/scripts/cli.mjs

@@ -33,6 +33,7 @@ function usage() {
 ${BOLD}🦞 multi-clawd${RESET} — multi-account Claude failover for OpenClaw
 
   ${BOLD}setup${RESET}     guided setup wizard (accounts, pool, watchdog)
+  ${BOLD}explain${RESET}   your setup in plain English — accounts, pool, fallback chain
   ${BOLD}update${RESET}    update the plugin to the latest version
   ${BOLD}doctor${RESET}    health check (add --probe for a live turn)
   ${BOLD}version${RESET}   show CLI + installed plugin versions
@@ -204,10 +205,78 @@ async function healWatchdogUnit() {
   }
 }
 
+/** `explain` — gather config + live health, render the plain-English view. */
+async function explain() {
+  const { readFileSync: rf, existsSync } = await import("node:fs");
+  const { homedir } = await import("node:os");
+  let ec, health, shim;
+  try {
+    ec = await import(resolve(__dirname, "..", "dist", "explain-core.js"));
+    health = await import(resolve(__dirname, "..", "dist", "health.js"));
+    shim = await import(resolve(__dirname, "..", "dist", "shim-core.js"));
+  } catch {
+    console.error("explain: built dist/ is missing — reinstall the package.");
+    process.exit(1);
+  }
+  let config = {};
+  try {
+    config = JSON.parse(rf(join(homedir(), ".openclaw", "openclaw.json"), "utf8"));
+  } catch {
+    console.error("explain: could not read ~/.openclaw/openclaw.json");
+    process.exit(1);
+  }
+  const pc = config?.plugins?.entries?.["multi-clawd"]?.config ?? {};
+  const accounts = Array.isArray(pc.accounts) ? pc.accounts : [];
+  const pool = pc.pool
+    ? { ...pc.pool, id: pc.pool.id?.trim() || "clawd", accounts: pc.pool.accounts ?? [] }
+    : undefined;
+  const chain = config?.agents?.defaults?.model;
+  const stateDir = join(homedir(), ".openclaw", "state", "multi-clawd");
+  const now = Date.now();
+  const rel = (ms) => {
+    const m = Math.round((ms - now) / 60000);
+    return m >= 90 ? `~${Math.round(m / 60)}h` : `~${m}m`;
+  };
+  const healthRows = accounts.map((a) => {
+    let state;
+    try {
+      state = shim.parseStoredState(rf(join(stateDir, `${a.id}.json`), "utf8"));
+    } catch {
+      /* no telemetry yet */
+    }
+    const h = health.classifyAccountHealth(state, {
+      utilizationThreshold: pool?.utilizationThreshold,
+      staleAfterMs: pool?.staleAfterMs,
+    }, now);
+    let detail = h.reason;
+    if (h.verdict === "exhausted" && h.resumeAt) {
+      detail = `${h.reason ?? "limit hit"} — back in ${rel(h.resumeAt)}`;
+    }
+    return { id: a.id, verdict: h.verdict, detail };
+  });
+  let stickyAccount;
+  if (pool) {
+    try {
+      const sticky = JSON.parse(rf(join(stateDir, `pool-${pool.id}.sticky.json`), "utf8"));
+      if (sticky?.account && sticky.account !== pool.accounts[0]) stickyAccount = sticky.account;
+    } catch {
+      /* no sticky state */
+    }
+  }
+  console.log(`\n${BOLD}🦞 multi-clawd — your setup, in plain English${RESET}\n`);
+  console.log(
+    ec.renderExplanation({ accounts, pool, chain, health: healthRows, stickyAccount }),
+  );
+  console.log(`\n${DIM}(health checks: multi-clawd doctor · change things: multi-clawd setup)${RESET}`);
+}
+
 switch (cmd) {
   case "setup":
     runSibling("setup.mjs", rest);
     break;
+  case "explain":
+    await explain();
+    break;
   case "doctor":
     runSibling("doctor.mjs", rest);
     break;

package/scripts/setup.mjs

@@ -41,7 +41,7 @@ try {
   console.error("setup: built dist/ modules are missing — run `npm run build` first (source checkout) or reinstall the plugin.");
   process.exit(1);
 }
-const { buildMainAccount, buildSecondAccount, buildPool, validateSecondConfigDir, planFromExisting, mergeSetupIntoConfig } = core;
+const { buildMainAccount, buildSecondAccount, buildPool, validateSecondConfigDir, planFromExisting, mergeSetupIntoConfig, existingAccountDefaults, looksLikeSecretRef } = core;
 
 // Line-queued prompts: interactive AND pipe-safe. With piped stdin, readline
 // emits every buffered line immediately — a plain question() would capture one
@@ -128,9 +128,29 @@ if (await yes("Add your MAIN account (the machine's existing `claude` login) to
 // ── second account ───────────────────────────────────────────────────────────
 if (await yes("Set up a SECOND Claude account (its own isolated config dir)?")) {
   const id = await ask("  id for the second account:", "claw2");
+  // Existing-aware: this account may already be fully configured. Pressing
+  // Enter through prompts must NEVER overwrite a working account, so the
+  // default here is to keep it exactly as it is.
+  const prior = existingAccountDefaults(existing, id);
+  if (prior?.hasCredentials) {
+    console.log(
+      `  "${id}" is already configured${prior.label ? ` (${prior.label}` : " ("}${prior.configDir ? `, dir ${prior.configDir})` : ")"}.`,
+    );
+    if (await yes("  Keep its existing credentials and config unchanged?", true)) {
+      accounts.push({ id });
+      console.log("  ✅ keeping as-is");
+    } else {
+      await secondAccountFlow(id, prior);
+    }
+  } else {
+    await secondAccountFlow(id, prior);
+  }
+}
+
+async function secondAccountFlow(id, prior) {
   let configDir;
   for (;;) {
-    configDir = await ask("  isolated config dir:", `~/.${id}`);
+    configDir = await ask("  isolated config dir:", prior?.configDir ?? `~/.${id}`);
     const err = validateSecondConfigDir(configDir);
     if (!err) break;
     console.log(`  ✗ ${err}`);
@@ -158,12 +178,19 @@ if (await yes("Set up a SECOND Claude account (its own isolated config dir)?"))
     let refId;
     for (;;) {
       refId = await ask("  secret reference (e.g. op://Vault/Item/field):");
-      if (refId) break;
-      if (stdinClosed) {
-        console.error("setup: a secret reference is required for token source 1 — aborting (nothing written).");
-        process.exit(1);
+      if (!refId) {
+        if (stdinClosed) {
+          console.error("setup: a secret reference is required for token source 1 — aborting (nothing written).");
+          process.exit(1);
+        }
+        console.log("  ✗ the reference is required (it is NOT the token itself — just the pointer to it; answer 3 above for no token)");
+        continue;
+      }
+      if (!looksLikeSecretRef(refId)) {
+        console.log(`  ⚠ "${refId}" doesn't look like a secret reference (expected something URI-like, e.g. op://Vault/Item/field)`);
+        if (!(await yes("  Use it anyway?", false))) continue;
       }
-      console.log("  ✗ the reference is required (it is NOT the token itself — just the pointer to it)");
+      break;
     }
     tokenSource = { kind: "ref", ref: { source: "exec", provider, id: refId } };
   } else if (choice === "2") {
@@ -171,7 +198,7 @@ if (await yes("Set up a SECOND Claude account (its own isolated config dir)?"))
   } else {
     tokenSource = { kind: "dir-login" };
   }
-  accounts.push(buildSecondAccount({ id, label: await ask("  label:", "Second Claude"), configDir, tokenSource }));
+  accounts.push(buildSecondAccount({ id, label: await ask("  label:", prior?.label ?? "Second Claude"), configDir, tokenSource }));
 }
 
 if (accounts.length === 0 && state.accountIds.length === 0) {