@drakon-systems/multi-clawd 2.5.1 → 2.6.0

package/README.md

@@ -31,6 +31,7 @@ multi-clawd setup     # guided wizard: accounts, isolated second login, pool, wa
 multi-clawd login claw2   # launch the right Claude sign-in for an account (or re-auth it)
 multi-clawd explain   # your whole setup in plain English — accounts, chain, live health
 multi-clawd explain --history --since 7d   # per-account launches, retries, rotations
+multi-clawd explain --json   # live health plus a rough weekly pace estimate, machine-readable
 multi-clawd account disable claw2 --dry-run  # preview benching an account
 multi-clawd chain     # audit your model routing — what actually serves each turn
 multi-clawd direct    # the direct anthropic/* route: status, or `direct sync` (v1.9, optional)
@@ -415,7 +416,7 @@ openclaw plugins install (Get-Location).Path
 **Or let your agent install it.** Running an OpenClaw assistant or Claude
 Code on the target machine already? Paste it this and go make coffee:
 
-> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v2.5.1/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v2.6.0/SETUP-AGENT.md
 > and follow it to set up multi-clawd on this machine. I own a second
 > Claude account — ask me when you need me to log in.
 

package/dist/explain-core.js

@@ -30,6 +30,49 @@ export function renderUsageLine(usage, nowMs) {
     })
         .join(" · ");
 }
+const WEEK_MS = 7 * 86_400_000;
+const MIN_PACE_ELAPSED_MS = WEEK_MS / 10;
+const PACE_RESET_SLACK_MS = 3_600_000;
+export function computeWeeklyPace(usage, nowMs) {
+    const u = ["usage:seven_day", "seven_day"]
+        .map((w) => usage?.find((x) => x.window === w))
+        .find((x) => x !== undefined);
+    if (!u || u.resetsAt === undefined)
+        return undefined;
+    if (!Number.isFinite(u.utilization) || u.utilization < 0 || u.utilization > 1)
+        return undefined;
+    if (!Number.isFinite(u.resetsAt) || !Number.isFinite(nowMs))
+        return undefined;
+    const remaining = u.resetsAt - nowMs;
+    if (remaining <= 0 || remaining > WEEK_MS + PACE_RESET_SLACK_MS)
+        return undefined;
+    const elapsed = Math.max(0, WEEK_MS - remaining);
+    if (elapsed < MIN_PACE_ELAPSED_MS)
+        return undefined;
+    const expectedPct = elapsed / WEEK_MS;
+    const projectedExhaustionAt = u.utilization >= 1
+        ? nowMs
+        : u.utilization > 0 ? nowMs + ((1 - u.utilization) * elapsed) / u.utilization : undefined;
+    return {
+        window: u.window,
+        expectedPct,
+        aheadOfPace: u.utilization - expectedPct,
+        projectedExhaustionAt,
+        willLastToReset: projectedExhaustionAt === undefined || projectedExhaustionAt >= u.resetsAt,
+        resetsAt: u.resetsAt,
+        estimate: true,
+    };
+}
+export function renderPaceLine(pace, nowMs) {
+    if (!pace)
+        return undefined;
+    const pts = Math.round(pace.aheadOfPace * 100);
+    const where = pts === 0 ? "on pace" : pts > 0 ? `${pts} points ahead of pace` : `${-pts} points behind pace`;
+    const verdict = pace.willLastToReset
+        ? "should last to the reset"
+        : `could run out in ${relativeUntil(pace.projectedExhaustionAt ?? nowMs, nowMs)}, before the reset in ${relativeUntil(pace.resetsAt, nowMs)}`;
+    return `weekly pace (rough estimate): ~${Math.round(pace.expectedPct * 100)}% of the week gone, ${where}; ${verdict}`;
+}
 export function describeAccount(acc) {
     if (acc.native) {
         return "the machine's main `claude` login (default config dir; OS keychain on macOS)";
@@ -145,6 +188,9 @@ export function renderExplanation(model) {
             const word = VERDICT_WORDS[h.verdict] ?? h.verdict;
             lines.push(`  ${h.id}: ${model.accounts.find((a) => a.id === h.id)?.disabled ? "disabled by operator" : word}${h.detail ? ` — ${h.detail}` : ""}`);
             lines.push(`      usage: ${h.usage?.length ? renderUsageLine(h.usage, nowMs) : "no live telemetry"}`);
+            const paceLine = renderPaceLine(computeWeeklyPace(h.usage, nowMs), nowMs);
+            if (paceLine)
+                lines.push(`      ${paceLine}`);
         }
         if (model.pool) {
             const strategy = poolStrategy(model.pool.strategy);

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Register additional Claude Code logins (Max/Pro accounts) as first-class OpenClaw CLI backends for cross-account failover, keeping the full skills/MCP harness on every account.",
   "cliBackends": [
     "claw1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drakon-systems/multi-clawd",
-  "version": "2.5.1",
+  "version": "2.6.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. Also imports those accounts' setup tokens into Hermes Agent's Anthropic credential pool.",
   "type": "module",
   "license": "MIT",

package/scripts/cli.mjs

@@ -50,6 +50,27 @@ Run via npx (${DIM}npx ${PKG} <command>${RESET}) or install globally
 `);
 }
 
+// Per-command usage, printed for `<command> --help` / `-h` before anything is
+// dispatched, so asking for help never reads config, runs checks, or starts the
+// setup wizard. `hermes` is absent on purpose: it handles its own help.
+const COMMAND_HELP = {
+  setup: "multi-clawd setup [--dry-run]\n\n  Guided setup wizard (accounts, pool, watchdog).\n  --dry-run   preview the changes without writing anything",
+  login: "multi-clawd login [<id>]\n\n  Log a configured account in (or re-auth it). Without <id>, lists the\n  configured accounts to choose from.",
+  account: "multi-clawd account <enable|disable> <id> [--dry-run]\n\n  Disable or enable a pool account.\n  --dry-run   preview the change without writing it",
+  explain: "multi-clawd explain [--json | --history [--since 7d|24h]]\n\n  Your setup in plain English: accounts, pool, fallback chain.\n  --json      machine-readable output\n  --history   recent pool events; --since limits the window",
+  chain: "multi-clawd chain [--raw]\n\n  Audit your model routing: what actually serves each turn.\n  --raw       include raw routing detail",
+  direct: "multi-clawd direct [status | sync [--dry-run] [--yes] [--resync]]\n\n  The direct anthropic/* route. Default is status.\n  sync        store profiles for the direct route\n  --dry-run   preview without writing\n  --yes       skip the confirmation prompt\n  --resync    refresh profiles that are already stored",
+  usage: "multi-clawd usage [--json]\n\n  Live usage per account from the provider: what is left, and what the\n  pool will do.\n  --json      machine-readable output",
+  update: "multi-clawd update\n\n  Update the plugin to the latest version.",
+  doctor: "multi-clawd doctor [--probe] [--probe-pool] [--verbose] [--raw]\n\n  Health check.\n  --probe       run a live turn per account plus the pool\n  --probe-pool  with --probe: probe the pool ref only (one turn)\n  --verbose     show more detail\n  --raw         show raw output",
+  version: "multi-clawd version\n\n  Show CLI and installed plugin versions.",
+};
+
+if (Object.hasOwn(COMMAND_HELP, cmd) && rest.some((a) => a === "--help" || a === "-h")) {
+  console.log(`\n${COMMAND_HELP[cmd]}\n`);
+  process.exit(0);
+}
+
 const { resolveInstallDir } = await import(join(__dirname, "_shared.mjs"));
 
 function installedVersion(installPath) {
@@ -677,11 +698,12 @@ async function healWatchdogUnit() {
 /** `explain` — gather config + live health, render the plain-English view. */
 async function explain(args = []) {
   let historySince;
-  if (args.length) {
+  const asJson = args.length === 1 && args[0] === "--json";
+  if (args.length && !asJson) {
     const allowed = args[0] === "--history" && (args.length === 1 ||
       (args.length === 3 && args[1] === "--since"));
     if (!allowed) {
-      console.error("explain: usage: multi-clawd explain [--history [--since 7d|24h]]");
+      console.error("explain: usage: multi-clawd explain [--json | --history [--since 7d|24h]]");
       process.exitCode = 1;
       return;
     }
@@ -775,6 +797,14 @@ async function explain(args = []) {
       /* no journal yet: every account counts as never served */
     }
   }
+  if (asJson) {
+    // #94: machine-readable health with the display-only weekly pace estimate.
+    console.log(JSON.stringify({
+      at: new Date(now).toISOString(),
+      accounts: healthRows.map((r) => ({ ...r, weeklyPace: ec.computeWeeklyPace(r.usage, now) ?? null })),
+    }, null, 2));
+    return;
+  }
   // v1.9: the direct anthropic/* route, when any account opted in.
   let direct;
   const dctx = await loadDirect(config);