@drakon-systems/multi-clawd 1.8.11 → 1.9.2

package/dist/index.js

@@ -14,13 +14,18 @@ import { createTokenRefResolver, isSecretRefShape, } from "./token-resolution.js
 import { resolveSecretRefValues } from "openclaw/plugin-sdk/secret-ref-runtime";
 import { resolvePoolExecutionArgs } from "./tool-cap.js";
 import { RETRY_ROSTER_ENV } from "./retry-plan.js";
+import { SESSION_DIRS_ENV } from "./session-handover.js";
 import { addAlert, alertKeysWithPrefix, clearAlert, pendingAlertText, } from "./alerts.js";
 import { healthStateFile, clearAccountCredentialFailure } from "./credential-state.js";
 export { healthStateFile, clearAccountCredentialFailure };
-import { buildAccountChildEnv, tokenFileModeWarning, validateAccountTokenSources, } from "./account-env.js";
+import { accountConfigDir, buildAccountChildEnv, tokenFileModeWarning, validateAccountTokenSources, } from "./account-env.js";
 import { diffCatalogModels, formatNewModelNotice, } from "./model-currency.js";
 import { checkAccountCredential, keychainServiceForConfigDir, createRefProbeTracker, } from "./login-health.js";
 import { execFileSync } from "node:child_process";
+import { collectDirectMembers } from "./direct-route.js";
+import { createDirectOrderController, isValidAgentId } from "./direct-sync.js";
+import { createOpenclawRunner } from "./openclaw-runner.js";
+import { HISTORY_IDENTITY_CONFIG_KEY, describeEnsureResult, ensureIdentityProfiles, identityProfileId, loadProviderAuthSdk, } from "./history-identity.js";
 const CLI_FRESH_WATCHDOG_DEFAULTS = {
     noOutputTimeoutRatio: 0.8,
     minMs: 180_000,
@@ -396,6 +401,7 @@ export function buildBackend(account, execMode) {
         resolveExecutionArgs: resolvePoolExecutionArgs,
         sideQuestionToolMode: "disabled",
         ownsNativeCompaction: true,
+        defaultAuthProfileId: identityProfileId(account.id),
         config: {
             command: process.execPath,
             args: [SHIM_PATH, ...BASE_ARGS, ...permissionModeArgs(execMode)],
@@ -506,6 +512,9 @@ export default definePluginEntry({
             "startup-pluginConfig",
         ];
         if (accounts.length === 0) {
+            const mode = api.registrationMode;
+            if (mode === undefined || mode === "full")
+                stopDirectOrderSync();
             api.logger.warn(`[multi-clawd] no accounts configured — nothing to register (sources: ${candidates
                 .map((c, i) => `${sourceNames[i]}=${hasAccounts(c) ? "ok" : c ? "empty" : "absent"}`)
                 .join(", ")})`);
@@ -545,6 +554,12 @@ export default definePluginEntry({
             api.registerProvider(buildCatalogProvider(normalized));
         }
         registerPoolBackend(api, cfg.pool, accounts, seen, execMode);
+        startHistoryIdentityEnsure({
+            backendIds: [...seen],
+            enabled: cfg[HISTORY_IDENTITY_CONFIG_KEY] !== false,
+            registrationMode: api.registrationMode,
+            logger: api.logger,
+        });
         {
             const logger = api.logger;
             try {
@@ -557,10 +572,66 @@ export default definePluginEntry({
                 logger.warn(`[multi-clawd] heartbeat alert hook unavailable: ${String(err)}`);
             }
             startLoginHealthProbe(accounts.filter((a) => seen.has(a.id.trim())), logger);
+            startDirectOrderSync({
+                accounts: accounts.filter((a) => seen.has(a.id.trim())),
+                pool: cfg.pool,
+                directRoute: cfg.directRoute,
+                registrationMode: api.registrationMode,
+                configOrder: () => {
+                    const root = (runtimeConfigLoader?.() ?? api.config);
+                    const order = root?.auth?.order?.anthropic;
+                    return Array.isArray(order) ? order.filter((v) => typeof v === "string") : undefined;
+                },
+                logger,
+            });
         }
         api.logger.info(`[multi-clawd] registered ${seen.size} backend(s)+provider(s): ${[...seen].join(", ")}`);
     },
 });
+let historyIdentitySdkLoader = loadProviderAuthSdk;
+let historyIdentityPending;
+export function setProviderAuthSdkLoaderForTests(loader) {
+    historyIdentitySdkLoader = loader ?? loadProviderAuthSdk;
+    historyIdentityPending = undefined;
+}
+export function awaitHistoryIdentityEnsure() {
+    return historyIdentityPending ?? Promise.resolve(undefined);
+}
+function startHistoryIdentityEnsure(params) {
+    const { logger } = params;
+    if (params.registrationMode !== undefined && params.registrationMode !== "full")
+        return;
+    if (!params.enabled) {
+        logger.info("[multi-clawd] history identity: disabled by config (historyIdentity: false)");
+        return;
+    }
+    if (params.backendIds.length === 0 || historyIdentityPending)
+        return;
+    const ids = [...params.backendIds];
+    historyIdentityPending = (async () => {
+        try {
+            const sdk = await historyIdentitySdkLoader();
+            if (!sdk) {
+                logger.warn("[multi-clawd] history identity: this OpenClaw does not expose openclaw/plugin-sdk/provider-auth store writers — skipped (CLI history reseed stays auth-unknown)");
+                return undefined;
+            }
+            const result = await ensureIdentityProfiles(ids, sdk);
+            const line = `[multi-clawd] history identity: ${describeEnsureResult(result)}`;
+            if (result.failed.length > 0)
+                logger.warn(line);
+            else
+                logger.info(line);
+            return result;
+        }
+        catch (err) {
+            logger.warn(`[multi-clawd] history identity: ${String(err)}`);
+            return undefined;
+        }
+        finally {
+            historyIdentityPending = undefined;
+        }
+    })();
+}
 function readHealthState(accountId) {
     try {
         return JSON.parse(readFileSync(healthStateFile(accountId), "utf8"));
@@ -742,6 +813,7 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
             if (roster.length > 0)
                 env[RETRY_ROSTER_ENV] = JSON.stringify(roster);
         }
+        env[SESSION_DIRS_ENV] = JSON.stringify([...new Set(members.map(accountConfigDir))]);
         if (ladder.length > 0) {
             const pinned = matchesPin(pins, {
                 agentDir: ctx.agentDir ?? "",
@@ -778,3 +850,84 @@ export function registerPoolBackend(api, pool, accounts, registeredIds, execMode
         }
     })();
 }
+let directTimer;
+let directInitial;
+let directController;
+export function stopDirectOrderSync() {
+    if (directTimer)
+        clearInterval(directTimer);
+    if (directInitial)
+        clearTimeout(directInitial);
+    directTimer = undefined;
+    directInitial = undefined;
+    directController = undefined;
+}
+export function startDirectOrderSync(params) {
+    const { logger } = params;
+    const mode = params.registrationMode;
+    if (mode !== undefined && mode !== "full")
+        return { active: false, members: [] };
+    const { members, problems } = collectDirectMembers(params.accounts, params.pool?.accounts ?? []);
+    for (const p of problems) {
+        logger.warn(`[multi-clawd] direct route: account "${p.accountId}" skipped — ${p.reason}`);
+    }
+    if (members.length === 0 || params.directRoute?.manageOrder === false) {
+        stopDirectOrderSync();
+        return { active: false, members: members.map((m) => m.accountId) };
+    }
+    const requested = params.directRoute?.agents?.length ? params.directRoute.agents : ["main"];
+    const agents = requested.filter((a) => {
+        if (isValidAgentId(a))
+            return true;
+        logger.warn(`[multi-clawd] direct route: ignoring agent id ${JSON.stringify(a)} in directRoute.agents — letters, digits, "_" and "-" only`);
+        return false;
+    });
+    if (agents.length === 0) {
+        stopDirectOrderSync();
+        return { active: false, members: members.map((m) => m.accountId) };
+    }
+    const intervalMs = Math.max(15_000, params.directRoute?.intervalMs ?? 60_000);
+    const healthOptions = {
+        utilizationThreshold: params.pool?.utilizationThreshold,
+        staleAfterMs: params.pool?.staleAfterMs,
+        rotateOnOverage: params.pool?.rotateOnOverage,
+    };
+    const signature = JSON.stringify({
+        members: members.map((m) => m.profileId),
+        agents,
+        intervalMs,
+        healthOptions,
+        minDwellMs: params.pool?.minDwellMs,
+        command: params.directRoute?.openclawCommand,
+    });
+    if (directController?.signature === signature && directTimer) {
+        return { active: true, members: members.map((m) => m.accountId) };
+    }
+    stopDirectOrderSync();
+    const stickyFile = join(homedir(), ".openclaw", "state", "multi-clawd", "direct-order.sticky.json");
+    const controller = createDirectOrderController({
+        members,
+        agents,
+        runner: createOpenclawRunner(params.directRoute?.openclawCommand ?? "openclaw"),
+        readHealth: (id) => readHealthState(id),
+        healthOptions,
+        minDwellMs: params.pool?.minDwellMs,
+        configOrder: params.configOrder,
+        readSticky: () => readStickyEntry(stickyFile),
+        writeSticky: (entry) => writeStickyEntry(stickyFile, entry, logger),
+        logger,
+    });
+    directController = { signature, tick: controller.tick };
+    const tick = () => void controller.tick().catch((err) => logger.warn(`[multi-clawd] direct route tick failed: ${String(err)}`));
+    directInitial = setTimeout(tick, Math.min(30_000, intervalMs));
+    directInitial.unref?.();
+    directTimer = setInterval(tick, intervalMs);
+    directTimer.unref?.();
+    logger.info(`[multi-clawd] direct route: keeping anthropic order for agent(s) ${agents.join(", ")} in pool-health order — ${members
+        .map((m) => `${m.accountId}=${m.profileId}`)
+        .join(", ")}`);
+    return { active: true, members: members.map((m) => m.accountId) };
+}
+export async function runDirectOrderTickNow() {
+    return directController?.tick();
+}

package/dist/openclaw-runner.js

@@ -0,0 +1,42 @@
+import { spawn } from "node:child_process";
+const MAX_CAPTURE = 1024 * 1024;
+export function createOpenclawRunner(command = "openclaw") {
+    return (args, opts) => new Promise((resolve) => {
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        let child;
+        try {
+            child = spawn(command, args, { stdio: ["pipe", "pipe", "pipe"], shell: false });
+        }
+        catch (err) {
+            resolve({ code: 127, stdout: "", stderr: String(err.message) });
+            return;
+        }
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            finish({ code: 124, stdout, stderr: `${stderr}\ntimed out` });
+        }, opts?.timeoutMs ?? 60_000);
+        timer.unref?.();
+        child.stdout?.on("data", (d) => {
+            if (stdout.length < MAX_CAPTURE)
+                stdout += d.toString("utf8");
+        });
+        child.stderr?.on("data", (d) => {
+            if (stderr.length < MAX_CAPTURE)
+                stderr += d.toString("utf8");
+        });
+        child.on("error", (err) => finish({ code: 127, stdout, stderr: `${stderr}\n${err.message}` }));
+        child.on("close", (code) => finish({ code: code ?? 1, stdout, stderr }));
+        child.stdin?.on("error", () => {
+        });
+        child.stdin?.end(opts?.input ?? "");
+    });
+}

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

@@ -6,6 +6,7 @@ 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) {
@@ -88,6 +89,11 @@ if (modelOverride) {
         process.stderr.write(`[multi-clawd shim] degrading model for this launch → ${modelOverride}\n`);
     }
 }
+{
+    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;

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "multi-clawd",
   "name": "multi-clawd",
-  "version": "1.8.11",
+  "version": "1.9.2",
   "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,78 @@
             "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:."
+                    }
+                  }
+                }
+              ]
             }
           }
         }
+      },
+      "historyIdentity": {
+        "type": "boolean",
+        "description": "Store one identity-only OpenClaw auth profile per registered backend id (<id>:multi-clawd-identity — a name, no token) and point the backend's defaultAuthProfileId at it, so OpenClaw's CLI history boundary can bind and a fresh Claude session is reseeded with prior context instead of `cli session history refused across auth boundary: reason=auth-unknown`. Default true. false = no auth-store writes; the reseed refusal stays."
+      },
+      "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.11",
+  "version": "1.9.2",
   "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",