@drakon-systems/multi-clawd 1.2.3 → 1.3.1

package/README.md

@@ -11,7 +11,7 @@ same model, next account, full harness on every hop.
 
 [![OpenClaw plugin](https://img.shields.io/badge/OpenClaw-plugin-ff4f00)](https://docs.openclaw.ai/plugins)
 [![npm](https://img.shields.io/badge/npm-%40drakon--systems%2Fmulti--clawd-cb3837)](https://www.npmjs.com/package/@drakon-systems/multi-clawd)
-[![version](https://img.shields.io/badge/version-1.0.1-4c9aff)](CHANGELOG.md)
+[![version](https://img.shields.io/npm/v/%40drakon-systems%2Fmulti-clawd?color=4c9aff&label=version)](CHANGELOG.md)
 [![license: MIT](https://img.shields.io/badge/license-MIT-2ea44f)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)](tsconfig.json)
 
@@ -21,6 +21,37 @@ same model, next account, full harness on every hop.
 
 ---
 
+## Quick start
+
+```bash
+npm i -g @drakon-systems/multi-clawd   # the CLI (once)
+
+multi-clawd update    # install (or update) the OpenClaw plugin — right flags, restart, doctor
+multi-clawd setup     # guided wizard: accounts, isolated second login, pool, watchdog
+multi-clawd explain   # your whole setup in plain English — accounts, chain, live health
+multi-clawd doctor    # health check (add --probe for a live end-to-end turn)
+```
+
+That's the entire lifecycle. `update` installs the plugin when it's missing and
+upgrades it when it's not — nobody types registry flags. `setup` walks you
+through the whole shape below and merges config **non-destructively** (backup
+first, existing accounts never overwritten, re-runs are no-ops). Prefer not to
+install anything? Every command also runs as
+`npx @drakon-systems/multi-clawd <command>`.
+
+**The 3-step picture** `setup` walks you through:
+
+1. **Main account** — your existing `claude` login, used as-is (nothing to do).
+2. **Second account** — lives in its **own isolated config dir** (a separate
+   Claude "app", e.g. `~/.claw2`), so the two logins can never clobber each
+   other; token via a secret-manager reference (recommended), token file, or
+   the dir's own login.
+3. **The pool** — one backend id (`clawd/…`) fronting both: every launch runs
+   on the first account that isn't nearly maxed out, and your fallback chain
+   routes through it.
+
+Then `multi-clawd explain` shows you exactly what you built.
+
 ## Why
 
 OpenClaw's bundled `claude-cli` backend runs Claude Code on a **single**
@@ -113,20 +144,24 @@ Code backend runs.
 
 ## Install
 
-**From npm (recommended):**
+**The CLI does it all (recommended)** — see [Quick start](#quick-start):
+
+```bash
+npm i -g @drakon-systems/multi-clawd && multi-clawd update
+```
+
+`update` runs the registry install with the right flags, offers the gateway
+restart, and finishes with a doctor health check. Prefer the raw form?
 
 ```bash
 openclaw plugins install @drakon-systems/multi-clawd --pin
 openclaw gateway restart
 ```
 
-The gateway pulls the prebuilt package — no clone, no build step, nothing to
-keep in sync. `--pin` records the exact resolved version, so an upgrade is a
-deliberate `@latest`, never a surprise. `openclaw` itself is a *peer*
-dependency (the host provides it), so the install stays lean. Confirm with
-`openclaw plugins list` (expect `multi-clawd` enabled) — it also shows the
-install path; run the doctor from there:
-`node <install-path>/scripts/doctor.mjs`.
+Either way the gateway pulls the prebuilt package — no clone, no build step,
+nothing to keep in sync. `--pin` records the exact resolved version, so an
+upgrade is a deliberate act, never a surprise. `openclaw` itself is a *peer*
+dependency (the host provides it), so the install stays lean.
 
 **From ClawHub (alternative registry):**
 
@@ -171,7 +206,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.1",
   "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;