@drakon-systems/multi-clawd 1.2.3 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/multi-clawd",
-  "version": "1.2.3",
+  "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;