@drakon-systems/multi-clawd 1.7.4 → 1.8.0

package/README.md

@@ -364,7 +364,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/v1.7.4/SETUP-AGENT.md
+> Read https://raw.githubusercontent.com/Drakon-Systems-Ltd/multi-clawd/v1.8.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/alerts.js

@@ -13,6 +13,9 @@ export function addAlert(state, alert, nowMs) {
 export function clearAlert(state, key) {
     return { alerts: state.alerts.filter((a) => a.key !== key) };
 }
+export function alertKeysWithPrefix(state, prefix) {
+    return state.alerts.filter((a) => a.key.startsWith(prefix)).map((a) => a.key);
+}
 function isLive(alert, nowMs) {
     const ttl = alert.ttlMs ?? DEFAULT_TTL_MS[alert.severity];
     return nowMs - alert.at <= ttl;

package/dist/health.js

@@ -16,10 +16,24 @@ const PERIOD_WINDOW_PATTERN = /(^|_)(minutes?|hours?|days?|weeks?|months?)(_|$)/
 export function isPeriodWindow(window) {
     return PERIOD_WINDOW_PATTERN.test(window);
 }
+export function isOverageWindow(window) {
+    return /overage/i.test(window);
+}
 export function isWarningStatus(status) {
     return /warning/i.test(status);
 }
 export const MAX_RESET_HORIZON_MS = 8 * 24 * 60 * 60 * 1000;
+export const PERIOD_RESET_LESS_BLOCK_MS = 6 * 60 * 60 * 1000;
+export function resetLessBlockMs(window) {
+    return isShortWindow(window) ? MODEL_REJECTED_TTL_MS : PERIOD_RESET_LESS_BLOCK_MS;
+}
+function windowAppliesToModel(w, requestedWindowKey) {
+    if (w.model === undefined)
+        return true;
+    if (requestedWindowKey === undefined)
+        return false;
+    return modelWindowKey(w.model) === requestedWindowKey;
+}
 export function credentialFailureFor(state, nowMs) {
     const credential = state?.credential;
     if (!credential || credential.status !== "failed")
@@ -43,6 +57,8 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
     const requestedWindowKey = requestedModel !== undefined ? modelWindowKey(requestedModel) : undefined;
     let worst = { verdict: "ok" };
     let hasLiveEvidence = false;
+    let overageUtilization;
+    let quotaUtilization;
     for (const [window, w] of Object.entries(state.windows)) {
         const resetMs = typeof w.resetsAt === "number" ? w.resetsAt * 1000 : undefined;
         const resetBearing = resetMs !== undefined && resetMs > nowMs;
@@ -78,13 +94,17 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
                 reason: `${requestedModel} limit hit ${Math.round((nowMs - w.seenAt) / 60000)}m ago (no reset time; TTL block)`,
             };
         }
-        const fresh = resetBearing || nowMs - w.seenAt <= staleAfterMs;
+        const ownBlockMs = w.status === "rejected" && resetMs === undefined && isPeriodWindow(window)
+            ? resetLessBlockMs(window)
+            : 0;
+        const fresh = resetBearing || nowMs - w.seenAt <= Math.max(staleAfterMs, ownBlockMs);
         if (!fresh)
             continue;
         hasLiveEvidence = true;
         if (w.status === "rejected" &&
             resetBearing &&
             isPeriodWindow(window) &&
+            windowAppliesToModel(w, requestedWindowKey) &&
             rejectionStillAssertable(w.seenAt, nowMs)) {
             return {
                 verdict: "exhausted",
@@ -92,21 +112,32 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
                 reason: `${window} rejected until ${new Date(resetMs).toISOString()}`,
             };
         }
-        if (w.status === "rejected" && resetMs === undefined && isPeriodWindow(window)) {
+        if (w.status === "rejected" &&
+            resetMs === undefined &&
+            isPeriodWindow(window) &&
+            windowAppliesToModel(w, requestedWindowKey) &&
+            nowMs - w.seenAt <= resetLessBlockMs(window)) {
             return {
                 verdict: "exhausted",
-                resumeAt: w.seenAt + MODEL_REJECTED_TTL_MS,
-                reason: `${window} rejected ${Math.round((nowMs - w.seenAt) / 60000)}m ago (no reset time; TTL block)`,
+                resumeAt: w.seenAt + resetLessBlockMs(window),
+                reason: `${window} rejected ${Math.round((nowMs - w.seenAt) / 60000)}m ago (no reset time; ${Math.round(resetLessBlockMs(window) / 3600000)}h block)`,
             };
         }
-        if (worst.verdict === "ok" &&
-            typeof w.utilization === "number" &&
+        if (typeof w.utilization === "number" &&
             w.utilization >= threshold &&
             (resetBearing || resetMs === undefined)) {
-            worst = {
-                verdict: "near_limit",
-                reason: `${window} utilization ${w.utilization} >= ${threshold}`,
-            };
+            if (isOverageWindow(window) && !options.rotateOnOverage) {
+                overageUtilization = Math.max(overageUtilization ?? 0, w.utilization);
+            }
+            else if (worst.verdict === "ok") {
+                worst = {
+                    verdict: "near_limit",
+                    reason: `${window} utilization ${w.utilization} >= ${threshold}`,
+                };
+            }
+        }
+        if (!isOverageWindow(window) && typeof w.utilization === "number") {
+            quotaUtilization = Math.max(quotaUtilization ?? 0, w.utilization);
         }
         if (worst.verdict === "ok" &&
             typeof w.utilization !== "number" &&
@@ -121,6 +152,16 @@ export function classifyAccountHealth(state, options, nowMs, requestedModel) {
     }
     if (worst.verdict === "ok" && !hasLiveEvidence)
         return { verdict: "no_data" };
+    if (worst.verdict === "ok" && overageUtilization !== undefined) {
+        const pct = (n) => `${Math.round(n * 100)}%`;
+        worst = {
+            ...worst,
+            overageAdvisory: `paid overage is ${pct(overageUtilization)} spent while real quota is at ` +
+                `${quotaUtilization !== undefined ? pct(quotaUtilization) : "an unreported level"} — ` +
+                `not rotating on spill-over alone. Set pool.rotateOnOverage: true to rotate on it, ` +
+                `or leave it to keep using the overage you have paid for.`,
+        };
+    }
     return worst;
 }
 export function summarizeWindowUsage(state, options, nowMs) {

package/dist/index.js

@@ -14,7 +14,7 @@ import { decideStickySelection } from "./sticky.js";
 import { clearCredentialFailure, mergeHealthStates, parseStoredState, recordCredentialFailure, } from "./shim-core.js";
 import { createTokenRefResolver, isSecretRefShape, } from "./token-resolution.js";
 import { resolveSecretRefValues } from "openclaw/plugin-sdk/secret-ref-runtime";
-import { addAlert, clearAlert, pendingAlertText } from "./alerts.js";
+import { addAlert, alertKeysWithPrefix, clearAlert, pendingAlertText, } from "./alerts.js";
 import { buildAccountChildEnv, tokenFileModeWarning, validateAccountTokenSources, } from "./account-env.js";
 import { diffCatalogModels, formatNewModelNotice, } from "./model-currency.js";
 import { checkAccountCredential, createRefProbeTracker, } from "./login-health.js";
@@ -69,6 +69,10 @@ let loginProbeTimer;
 function raiseAlert(alert) {
     alertState = addAlert(alertState, alert, Date.now());
 }
+export function pendingOperatorAlerts(nowMs) {
+    ingestAlertSpool();
+    return pendingAlertText(alertState, nowMs);
+}
 function ingestAlertSpool() {
     const spool = join(homedir(), ".openclaw", "state", "multi-clawd", "alerts-spool.jsonl");
     let raw;
@@ -476,8 +480,7 @@ export default definePluginEntry({
             const logger = api.logger;
             try {
                 api.on("heartbeat_prompt_contribution", () => {
-                    ingestAlertSpool();
-                    const text = pendingAlertText(alertState, Date.now());
+                    const text = pendingOperatorAlerts(Date.now());
                     return text ? { appendContext: text } : undefined;
                 });
             }
@@ -576,6 +579,7 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
     const options = {
         utilizationThreshold: pool.utilizationThreshold,
         staleAfterMs: pool.staleAfterMs,
+        rotateOnOverage: pool.rotateOnOverage,
     };
     const poolAccount = {
         id: poolId,
@@ -589,9 +593,10 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
     backend.prepareExecution = async (ctx) => {
         const now = Date.now();
         const requestedModel = canonicalModelId(ctx.modelId) ?? ctx.modelId;
-        const verdicts = members.map((a) => ({
-            id: a.id,
-            health: classifyAccountHealth(readHealthState(a.id), options, now, requestedModel),
+        const states = members.map((a) => ({ id: a.id, state: readHealthState(a.id) }));
+        const verdicts = states.map(({ id, state }) => ({
+            id,
+            health: classifyAccountHealth(state, options, now, requestedModel),
         }));
         if (allCredentialFailed(verdicts.map((v) => ({ id: v.id, verdict: v.health.verdict })))) {
             const detail = verdicts
@@ -621,13 +626,33 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
             logger.info(`[multi-clawd] ${line}`);
             raiseAlert({ key: `rotation:${poolId}`, severity: "info", text: line });
         }
+        const exhaustionPrefix = `pool-exhausted:${poolId}:`;
+        for (const key of alertKeysWithPrefix(alertState, exhaustionPrefix)) {
+            const alertedModel = key.slice(exhaustionPrefix.length);
+            const stillExhausted = states.every(({ state }) => classifyAccountHealth(state, options, now, alertedModel).verdict === "exhausted");
+            if (!stillExhausted)
+                alertState = clearAlert(alertState, key);
+        }
         if (verdicts.every((v) => v.health.verdict === "exhausted")) {
             raiseAlert({
-                key: `pool-exhausted:${poolId}:${requestedModel}`,
+                key: `${exhaustionPrefix}${requestedModel}`,
                 severity: "error",
                 text: `pool ${poolId}: every account is exhausted for ${requestedModel} — turns are degrading or falling through the chain`,
             });
         }
+        for (const v of verdicts) {
+            const key = `overage:${poolId}:${v.id}`;
+            if (v.health.overageAdvisory) {
+                raiseAlert({
+                    key,
+                    severity: "info",
+                    text: `pool ${poolId}: account "${v.id}" — ${v.health.overageAdvisory}`,
+                });
+            }
+            else {
+                alertState = clearAlert(alertState, key);
+            }
+        }
         for (const v of verdicts) {
             const key = `credential:${poolId}:${v.id}`;
             if (v.health.verdict === "credential_failed") {

package/dist/shim-core.js

@@ -89,6 +89,7 @@ export function parseStoredState(raw) {
             isUsingOverage: typeof w.isUsingOverage === "boolean" ? w.isUsingOverage : undefined,
             seenAt: w.seenAt,
             rawInfo: typeof w.rawInfo === "string" ? w.rawInfo : undefined,
+            model: typeof w.model === "string" ? w.model : undefined,
         };
     }
     let credential;
@@ -291,7 +292,7 @@ export function clearCredentialFailure(state, now) {
         credential: { status: "ok", seenAt: now },
     };
 }
-export function updateHealthState(state, event, now) {
+export function updateHealthState(state, event, now, model) {
     const key = event.rateLimitType ?? "unknown";
     return {
         ...state,
@@ -305,6 +306,7 @@ export function updateHealthState(state, event, now) {
                 isUsingOverage: event.isUsingOverage,
                 seenAt: now,
                 rawInfo: event.rawInfo,
+                model: model === undefined ? undefined : canonicalizeModelIdForWindow(model),
             },
         },
     };

package/dist/shim.js

@@ -113,7 +113,7 @@ const scanner = createLineScanner((line) => {
     try {
         const event = parseRateLimitEvent(line);
         if (event) {
-            state = updateHealthState(state, event, Date.now());
+            state = updateHealthState(state, event, Date.now(), effectiveModelId());
             persistState();
         }
         const limitHit = parseModelLimitError(line);

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "1.7.4",
+  "version": "1.8.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",
@@ -51,6 +51,10 @@
             "type": "number",
             "description": "Ignore health data older than this. Default 21600000 (6h)."
           },
+          "rotateOnOverage": {
+            "type": "boolean",
+            "description": "Rotate when the seven_day_overage_included window (quota PLUS purchased spill-over) crosses utilizationThreshold. Default false: high utilization there means little paid overage left, not little quota left, so the pool keeps using the overage you have paid for and raises an operator alert instead of deciding for you."
+          },
           "minDwellMs": {
             "type": "number",
             "description": "After rotating away from home, stay on the rotated-to account at least this long before returning home (anti-flap hysteresis; health always overrides). Default 600000 (10min)."

package/package.json

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