@drakon-systems/multi-clawd 1.8.10 → 1.9.1

package/dist/retry-plan.js

@@ -0,0 +1,70 @@
+import { classifyAccountHealth } from "./health.js";
+export const RETRY_ROSTER_ENV = "MULTI_CLAWD_RETRY_ACCOUNTS";
+const CREDENTIAL_ENV_KEYS = ["CLAUDE_CONFIG_DIR", "CLAUDE_CODE_OAUTH_TOKEN"];
+export function parseRetryRoster(raw) {
+    if (!raw)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(parsed))
+        return [];
+    const out = [];
+    for (const entry of parsed) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const e = entry;
+        if (typeof e.id !== "string" || !e.id)
+            continue;
+        if (typeof e.stateFile !== "string" || !e.stateFile)
+            continue;
+        const env = {};
+        if (e.env && typeof e.env === "object") {
+            for (const [k, v] of Object.entries(e.env)) {
+                if (typeof v === "string")
+                    env[k] = v;
+            }
+        }
+        out.push({ id: e.id, stateFile: e.stateFile, env });
+    }
+    return out;
+}
+export function retryArming(argv, roster) {
+    if (roster.length === 0) {
+        return { armed: false, reason: "no secret-free sibling account to retry onto" };
+    }
+    if (argv.includes("--resume")) {
+        return {
+            armed: false,
+            reason: "resumed session — its Claude session lives in this account's config dir",
+        };
+    }
+    if (!argv.some((a) => a === "stream-json" || a === "--output-format=stream-json")) {
+        return { armed: false, reason: "not a stream-json launch" };
+    }
+    return { armed: true };
+}
+export function chooseRetryAccount(params) {
+    for (const account of params.roster) {
+        const state = params.readState(account.stateFile);
+        const verdict = classifyAccountHealth(state, params.options ?? {}, params.nowMs, params.modelId).verdict;
+        if (verdict === "ok" || verdict === "no_data")
+            return account;
+    }
+    return undefined;
+}
+export function buildRetryEnv(base, account) {
+    const env = { ...base };
+    for (const key of CREDENTIAL_ENV_KEYS)
+        delete env[key];
+    for (const [k, v] of Object.entries(account.env))
+        env[k] = v;
+    env.MULTI_CLAWD_ACCOUNT_ID = account.id;
+    env.MULTI_CLAWD_STATE_FILE = account.stateFile;
+    env[RETRY_ROSTER_ENV] = "";
+    return env;
+}

package/dist/session-handover.js

@@ -0,0 +1,117 @@
+import { copyFileSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+export const SESSION_DIRS_ENV = "MULTI_CLAWD_SESSION_DIRS";
+const SESSION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+export function resumeSessionId(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        let value;
+        if (arg === "--resume" || arg === "-r")
+            value = argv[i + 1];
+        else if (arg.startsWith("--resume="))
+            value = arg.slice("--resume=".length);
+        if (value !== undefined)
+            return SESSION_ID_RE.test(value) ? value : undefined;
+    }
+    return undefined;
+}
+export function effectiveConfigDir(env) {
+    const dir = env.CLAUDE_CONFIG_DIR?.trim();
+    return dir ? dir : join(homedir(), ".claude");
+}
+export function parseSessionDirs(raw) {
+    if (!raw)
+        return [];
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed))
+            return [];
+        return parsed.filter((d) => typeof d === "string" && d.trim().length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+export const nodeHandoverFs = {
+    listDirs(dir) {
+        try {
+            return readdirSync(dir, { withFileTypes: true })
+                .filter((d) => d.isDirectory())
+                .map((d) => d.name);
+        }
+        catch {
+            return [];
+        }
+    },
+    mtimeMs(path) {
+        try {
+            const st = statSync(path);
+            return st.isFile() ? st.mtimeMs : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    },
+};
+export function planSessionHandover(params) {
+    const fs = params.fs ?? nodeHandoverFs;
+    const file = `${params.sessionId}.jsonl`;
+    const dirs = [params.targetDir, ...params.memberDirs.filter((d) => d !== params.targetDir)];
+    let newest;
+    for (const dir of dirs) {
+        const projects = join(dir, "projects");
+        for (const sub of fs.listDirs(projects)) {
+            const path = join(projects, sub, file);
+            const mtime = fs.mtimeMs(path);
+            if (mtime === undefined)
+                continue;
+            if (!newest || mtime > newest.mtime)
+                newest = { dir, sub, path, mtime };
+        }
+    }
+    if (!newest)
+        return { action: "none", reason: "not-found" };
+    if (newest.dir === params.targetDir)
+        return { action: "none", reason: "already-local" };
+    return {
+        action: "copy",
+        from: newest.path,
+        to: join(params.targetDir, "projects", newest.sub, file),
+        fromDir: newest.dir,
+    };
+}
+export function applySessionHandover(plan) {
+    const tmp = join(dirname(plan.to), `.${basename(plan.to)}.handover-${process.pid}`);
+    mkdirSync(dirname(plan.to), { recursive: true, mode: 0o700 });
+    try {
+        copyFileSync(plan.from, tmp);
+        renameSync(tmp, plan.to);
+    }
+    catch (err) {
+        rmSync(tmp, { force: true });
+        throw err;
+    }
+}
+export function handoverForLaunch(argv, env, deps = {}) {
+    const sessionId = resumeSessionId(argv);
+    if (!sessionId)
+        return undefined;
+    const memberDirs = parseSessionDirs(env[SESSION_DIRS_ENV]);
+    if (memberDirs.length === 0)
+        return undefined;
+    const targetDir = effectiveConfigDir(env);
+    try {
+        const plan = planSessionHandover({ sessionId, targetDir, memberDirs, fs: deps.fs });
+        if (plan.action === "none") {
+            return plan.reason === "not-found"
+                ? `resume handover: session ${sessionId.slice(0, 8)} is in no pool account's config dir — leaving the launch as-is`
+                : undefined;
+        }
+        (deps.apply ?? applySessionHandover)(plan);
+        return `resume handover: session ${sessionId.slice(0, 8)} copied from ${plan.fromDir} into ${targetDir} (newer copy)`;
+    }
+    catch (err) {
+        return `resume handover failed for session ${sessionId.slice(0, 8)}: ${err instanceof Error ? err.message : String(err)}`;
+    }
+}

package/dist/setup-core.js

@@ -157,3 +157,28 @@ export function existingAccountDefaults(config, id) {
 export function looksLikeSecretRef(id) {
     return id.includes("://");
 }
+export function buildDirectSetting(account, choice) {
+    switch (choice.kind) {
+        case "skip":
+            return undefined;
+        case "reuse":
+            if (account.native || (!account.oauthTokenRef && !account.oauthTokenFile)) {
+                throw new Error(`account "${account.id}" has no setup-token to reuse — a native or config-dir login needs its own \`claude setup-token\` for the direct route`);
+            }
+            return true;
+        case "ref":
+            if (!isSecretRefShape(choice.ref)) {
+                throw new Error('secret ref must be { "source": "...", "provider": "...", "id": "..." }');
+            }
+            return { tokenRef: choice.ref };
+        case "file": {
+            const path = choice.path?.trim();
+            if (!path)
+                throw new Error("a token file path is required");
+            return { tokenFile: path };
+        }
+    }
+}
+export function canReuseCliTokenForDirect(account) {
+    return !account.native && Boolean(account.oauthTokenRef || account.oauthTokenFile);
+}

package/dist/shim.js

@@ -5,6 +5,8 @@ import { classifyStateReadFailure, clearCredentialFailure, createLineScanner, me
 import { rewriteModelArg } from "./degrade.js";
 import { parseModelLimitError, recordModelLimit } from "./shim-core.js";
 import { canonicalModelId } from "./models.js";
+import { buildRetryEnv, chooseRetryAccount, parseRetryRoster, retryArming, RETRY_ROSTER_ENV, } from "./retry-plan.js";
+import { handoverForLaunch } from "./session-handover.js";
 function resolveClaudeCommand() {
     const override = process.env.MULTI_CLAWD_CLAUDE_BIN;
     if (override) {
@@ -20,8 +22,8 @@ function resolveClaudeCommand() {
     }
     return { command: "claude", prependArgs: [] };
 }
-const stateFile = process.env.MULTI_CLAWD_STATE_FILE;
-const accountId = process.env.MULTI_CLAWD_ACCOUNT_ID ?? "unknown";
+let stateFile = process.env.MULTI_CLAWD_STATE_FILE;
+let accountId = process.env.MULTI_CLAWD_ACCOUNT_ID ?? "unknown";
 let state = { accountId, windows: {} };
 function preserveCorruptState(raw) {
     if (!stateFile)
@@ -87,11 +89,48 @@ if (modelOverride) {
         process.stderr.write(`[multi-clawd shim] degrading model for this launch → ${modelOverride}\n`);
     }
 }
-const child = spawn(command, childArgs, {
+{
+    const note = handoverForLaunch(childArgs, process.env);
+    if (note)
+        process.stderr.write(`[multi-clawd shim] ${note}\n`);
+}
+const retryRoster = parseRetryRoster(process.env[RETRY_ROSTER_ENV]);
+const arming = retryArming(childArgs, retryRoster);
+let retryArmed = arming.armed;
+if (!retryArmed && retryRoster.length > 0 && arming.reason) {
+    process.stderr.write(`[multi-clawd shim] in-turn retry unavailable: ${arming.reason}\n`);
+}
+let child = spawn(command, childArgs, {
     stdio: ["pipe", "pipe", "inherit"],
     env: process.env,
 });
-process.stdin.pipe(child.stdin);
+const STDIN_REPLAY_CAP_BYTES = 8 * 1024 * 1024;
+let stdinReplay = [];
+let stdinReplayBytes = 0;
+let stdinEnded = false;
+if (retryArmed) {
+    process.stdin.on("data", (chunk) => {
+        if (retryArmed) {
+            stdinReplayBytes += chunk.length;
+            if (stdinReplayBytes > STDIN_REPLAY_CAP_BYTES) {
+                retryArmed = false;
+                stdinReplay = [];
+                releaseHeldOutput();
+            }
+            else {
+                stdinReplay.push(chunk);
+            }
+        }
+        child.stdin.write(chunk);
+    });
+    process.stdin.on("end", () => {
+        stdinEnded = true;
+        child.stdin.end();
+    });
+}
+else {
+    process.stdin.pipe(child.stdin);
+}
 function effectiveModelId() {
     const idx = childArgs.indexOf("--model");
     if (idx < 0 || idx + 1 >= childArgs.length)
@@ -109,7 +148,7 @@ function guessLimitResetsAt() {
     return undefined;
 }
 let sawAuthFailure = false;
-const scanner = createLineScanner((line) => {
+function observeLine(line) {
     try {
         const event = parseRateLimitEvent(line);
         if (event) {
@@ -135,12 +174,154 @@ const scanner = createLineScanner((line) => {
     }
     catch {
     }
-});
-child.stdout.on("data", (chunk) => {
+}
+const scanner = createLineScanner(observeLine);
+const HOLD_CAP_BYTES = 256 * 1024;
+const HOLD_MAX_MS = Number(process.env.MULTI_CLAWD_HOLD_MAX_MS ?? 10_000);
+let held = [];
+let heldBytes = 0;
+let holdTail = "";
+let retryUsed = false;
+function isPreambleRecord(line) {
+    if (line.length === 0)
+        return true;
+    try {
+        const record = JSON.parse(line);
+        if (record.type === "system" || record.type === "rate_limit_event")
+            return true;
+        if (record.type === "assistant" && record.message?.model === "<synthetic>")
+            return true;
+        return false;
+    }
+    catch {
+        return false;
+    }
+}
+function releaseHeldOutput() {
+    if (held.length > 0) {
+        process.stdout.write(held.join(""));
+        held = [];
+        heldBytes = 0;
+    }
+    if (holdTail.length > 0) {
+        process.stdout.write(holdTail);
+        scanner.push(holdTail);
+        holdTail = "";
+    }
+    retryArmed = false;
+    stdinReplay = [];
+}
+function readSiblingState(file) {
+    try {
+        return parseStoredState(readFileSync(file, "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+function attemptRetry() {
+    if (!retryArmed || retryUsed)
+        return false;
+    const model = effectiveModelId();
+    const target = chooseRetryAccount({
+        roster: retryRoster,
+        readState: readSiblingState,
+        modelId: model,
+        nowMs: Date.now(),
+    });
+    if (!target) {
+        process.stderr.write(`[multi-clawd shim] model limit on ${accountId} with no healthy sibling to retry onto — ` +
+            `passing the failure through to the host's chain\n`);
+        releaseHeldOutput();
+        return false;
+    }
+    retryUsed = true;
+    retryArmed = false;
+    process.stderr.write(`[multi-clawd shim] model limit on ${accountId}${model ? ` for ${model}` : ""} — ` +
+        `retrying this turn on ${target.id} (nothing forwarded downstream yet)\n`);
+    held = [];
+    heldBytes = 0;
+    holdTail = "";
+    const previous = child;
+    previous.stdout.removeAllListeners();
+    previous.removeAllListeners("close");
+    previous.removeAllListeners("error");
+    try {
+        previous.kill("SIGTERM");
+    }
+    catch {
+    }
+    accountId = target.id;
+    stateFile = target.stateFile;
+    state = { accountId, windows: {} };
+    sawAuthFailure = false;
+    child = spawn(command, childArgs, {
+        stdio: ["pipe", "pipe", "inherit"],
+        env: buildRetryEnv(process.env, target),
+    });
+    attachChildHandlers();
+    for (const chunk of stdinReplay)
+        child.stdin.write(chunk);
+    if (stdinEnded)
+        child.stdin.end();
+    stdinReplay = [];
+    return true;
+}
+function onArmedChunk(chunk) {
+    holdTail += chunk.toString("utf8");
+    while (retryArmed) {
+        const idx = holdTail.indexOf("\n");
+        if (idx < 0)
+            break;
+        const raw = holdTail.slice(0, idx + 1);
+        holdTail = holdTail.slice(idx + 1);
+        const line = raw.trim();
+        observeLine(line);
+        if (parseModelLimitError(line) && attemptRetry())
+            return;
+        held.push(raw);
+        heldBytes += raw.length;
+        if (!isPreambleRecord(line) || heldBytes > HOLD_CAP_BYTES) {
+            releaseHeldOutput();
+            return;
+        }
+    }
+    if (!retryArmed && holdTail.length > 0) {
+        const rest = holdTail;
+        holdTail = "";
+        process.stdout.write(rest);
+        scanner.push(rest);
+    }
+}
+if (retryArmed) {
+    const holdTimer = setTimeout(() => {
+        if (!retryArmed)
+            return;
+        process.stderr.write(`[multi-clawd shim] in-turn retry window closed after ${HOLD_MAX_MS}ms — releasing the stream\n`);
+        releaseHeldOutput();
+    }, HOLD_MAX_MS);
+    holdTimer.unref?.();
+}
+function onPassthroughChunk(chunk) {
     process.stdout.write(chunk);
     scanner.push(chunk.toString("utf8"));
-});
-child.stdout.on("end", () => scanner.flush());
+}
+function attachChildHandlers() {
+    const armedForThisChild = retryArmed;
+    child.stdout.on("data", (chunk) => {
+        if (armedForThisChild && retryArmed)
+            onArmedChunk(chunk);
+        else
+            onPassthroughChunk(chunk);
+    });
+    child.stdout.on("end", () => {
+        if (retryArmed)
+            releaseHeldOutput();
+        scanner.flush();
+    });
+    child.on("close", onChildClose);
+    child.on("error", onChildError);
+}
 for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
     process.on(signal, () => {
         child.kill(signal);
@@ -159,7 +340,7 @@ function clearRecordedAuthFailureOnSuccess() {
     catch {
     }
 }
-child.on("close", (code, signal) => {
+function onChildClose(code, signal) {
     if (signal) {
         process.kill(process.pid, signal);
         return;
@@ -167,8 +348,9 @@ child.on("close", (code, signal) => {
     if ((code ?? 0) === 0)
         clearRecordedAuthFailureOnSuccess();
     process.exit(code ?? 0);
-});
-child.on("error", (err) => {
+}
+function onChildError(err) {
     process.stderr.write(`[multi-clawd shim] failed to spawn claude: ${String(err)}\n`);
     process.exit(127);
-});
+}
+attachChildHandlers();

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "1.8.10",
+  "version": "1.9.1",
   "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",
@@ -163,9 +163,74 @@
             "defaultModel": {
               "type": "string",
               "description": "Model id used for live probes (openclaw models status). Defaults to claude-fable-5."
+            },
+            "direct": {
+              "description": "Opt this account into the gateway's direct Anthropic route (anthropic/* models) as well as the CLI. `true` reuses the account's own setup-token (oauthTokenRef / oauthTokenFile). A native or config-dir login is a rotating grant that is never copied, so it needs an explicit setup-token: {\"tokenRef\": {...}} or {\"tokenFile\": \"...\"}. `multi-clawd update`/`setup` store it as the OpenClaw auth profile anthropic:<id>, and the plugin keeps auth.order.anthropic in pool-health order. Omit to leave the account CLI-only (unchanged behaviour).",
+              "anyOf": [
+                {
+                  "type": "boolean"
+                },
+                {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "properties": {
+                    "tokenRef": {
+                      "type": "object",
+                      "additionalProperties": true,
+                      "description": "Secret reference resolving to a `claude setup-token` value for THIS account, e.g. {\"source\":\"exec\",\"provider\":\"onepassword\",\"id\":\"op://Vault/Item/field\"}.",
+                      "properties": {
+                        "source": {
+                          "type": "string"
+                        },
+                        "provider": {
+                          "type": "string"
+                        },
+                        "id": {
+                          "type": "string"
+                        }
+                      }
+                    },
+                    "tokenFile": {
+                      "type": "string",
+                      "description": "Path to a 0600 file holding a `claude setup-token` value for THIS account. Mutually exclusive with tokenRef."
+                    },
+                    "profileId": {
+                      "type": "string",
+                      "description": "OpenClaw auth profile id. Default anthropic:<account id>. Must start with anthropic:."
+                    }
+                  }
+                }
+              ]
             }
           }
         }
+      },
+      "directRoute": {
+        "type": "object",
+        "additionalProperties": false,
+        "description": "The gateway's direct Anthropic route (anthropic/* models), active only when at least one account sets `direct`. The plugin keeps each listed agent's auth.order.anthropic in pool-health order (via `openclaw models auth order set`), so a nearly-maxed account is tried last before it errors; OpenClaw's own cooldowns and in-turn rotation handle the rest.",
+        "properties": {
+          "agents": {
+            "type": "array",
+            "items": {
+              "type": "string",
+              "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$"
+            },
+            "description": "Agents whose anthropic auth order is managed. Default [\"main\"]."
+          },
+          "manageOrder": {
+            "type": "boolean",
+            "description": "Keep the order in pool-health order. Default true. false = credentials are still synced by setup/update, the order is left to you."
+          },
+          "intervalMs": {
+            "type": "number",
+            "description": "How often the order is re-planned from health files. Default 60000; minimum 15000. The CLI is only invoked when the plan changes (or hourly to re-assert)."
+          },
+          "openclawCommand": {
+            "type": "string",
+            "description": "OpenClaw CLI used for auth-store reads/writes. Default \"openclaw\" on PATH."
+          }
+        }
       }
     }
   }

package/package.json

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