@drakon-systems/multi-clawd 1.0.0

package/dist/setup-core.js

@@ -0,0 +1,140 @@
+import { isSecretRefShape } from "./token-resolution.js";
+const PLUGIN_ID = "multi-clawd";
+function assertAccountId(id) {
+    const trimmed = id?.trim();
+    if (!trimmed)
+        throw new Error("account id must be non-empty");
+    if (trimmed === "claude-cli") {
+        throw new Error(`account id "${trimmed}" collides with the bundled backend id`);
+    }
+    return trimmed;
+}
+export function buildMainAccount(opts) {
+    return { id: assertAccountId(opts.id), label: opts.label, native: true };
+}
+export function buildSecondAccount(opts) {
+    const id = assertAccountId(opts.id);
+    const dirError = validateSecondConfigDir(opts.configDir);
+    if (dirError)
+        throw new Error(dirError);
+    const account = { id, label: opts.label, configDir: opts.configDir };
+    switch (opts.tokenSource.kind) {
+        case "ref":
+            if (!isSecretRefShape(opts.tokenSource.ref)) {
+                throw new Error('secret ref must be { "source": "...", "provider": "...", "id": "..." } — e.g. { "source": "exec", "provider": "onepassword", "id": "op://Vault/Item/field" }');
+            }
+            account.oauthTokenRef = opts.tokenSource.ref;
+            break;
+        case "file":
+            account.oauthTokenFile = opts.tokenSource.path;
+            break;
+        case "dir-login":
+            break;
+    }
+    return account;
+}
+export function validateSecondConfigDir(dir) {
+    const d = (dir ?? "").trim().replace(/\/+$/, "");
+    if (!d.startsWith("~/") && !d.startsWith("/")) {
+        return `config dir must be an absolute path or start with ~/ (got "${dir}")`;
+    }
+    if (d === "~/.claude" || /\/\.claude$/.test(d)) {
+        return "that's the DEFAULT Claude config dir — it belongs to your main (native) login; pick an isolated dir like ~/.claw2";
+    }
+    if (d.startsWith("~/.claude/") || d.includes("/.claude/")) {
+        return "the second account's dir must not live inside ~/.claude — it must be fully isolated from the main login";
+    }
+    return undefined;
+}
+export function buildPool(accountIds, opts) {
+    const pool = {
+        id: opts?.id?.trim() || "clawd",
+        accounts: accountIds,
+    };
+    if (opts?.label)
+        pool.label = opts.label;
+    return pool;
+}
+function asRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v)
+        ? v
+        : undefined;
+}
+export function planFromExisting(config) {
+    const cfg = asRecord(config) ?? {};
+    const plugins = asRecord(cfg.plugins);
+    const allow = Array.isArray(plugins?.allow) ? plugins?.allow : undefined;
+    const entries = asRecord(plugins?.entries);
+    const entry = asRecord(entries?.[PLUGIN_ID]);
+    const entryConfig = asRecord(entry?.config);
+    const accounts = Array.isArray(entryConfig?.accounts)
+        ? entryConfig?.accounts
+        : [];
+    return {
+        hasPluginEntry: entry !== undefined,
+        accountIds: accounts
+            .map((a) => asRecord(a)?.id)
+            .filter((id) => typeof id === "string"),
+        hasPool: asRecord(entryConfig?.pool) !== undefined,
+        hasAllowList: allow !== undefined,
+        allowListed: allow?.includes(PLUGIN_ID) ?? false,
+    };
+}
+export function mergeSetupIntoConfig(existing, plan) {
+    const config = JSON.parse(JSON.stringify(asRecord(existing) ?? {}));
+    const changes = [];
+    const plugins = (config.plugins = asRecord(config.plugins) ?? {});
+    const entries = (plugins.entries = asRecord(plugins.entries) ?? {});
+    const entry = (entries[PLUGIN_ID] = asRecord(entries[PLUGIN_ID]) ?? {});
+    if (entry.enabled !== true) {
+        entry.enabled = true;
+        changes.push(`enable plugins.entries["${PLUGIN_ID}"]`);
+    }
+    const entryConfig = (entry.config = asRecord(entry.config) ?? {});
+    const accounts = (entryConfig.accounts = Array.isArray(entryConfig.accounts)
+        ? entryConfig.accounts
+        : []);
+    for (const planned of plan.accounts) {
+        const existingIdx = accounts.findIndex((a) => asRecord(a)?.id === planned.id);
+        const plannedClean = Object.fromEntries(Object.entries(planned).filter(([, v]) => v !== undefined));
+        if (existingIdx === -1) {
+            accounts.push(plannedClean);
+            changes.push(`add account "${planned.id}"`);
+        }
+        else {
+            const current = asRecord(accounts[existingIdx]) ?? {};
+            const merged = { ...current, ...plannedClean };
+            if (JSON.stringify(merged) !== JSON.stringify(current)) {
+                accounts[existingIdx] = merged;
+                changes.push(`update account "${planned.id}"`);
+            }
+        }
+    }
+    if (plan.pool) {
+        if (asRecord(entryConfig.pool)) {
+            const samePool = JSON.stringify(entryConfig.pool) === JSON.stringify(plan.pool);
+            if (!samePool)
+                changes.push(`pool already exists — skipped (edit it by hand if you want changes)`);
+        }
+        else {
+            entryConfig.pool = plan.pool;
+            changes.push(`add pool "${plan.pool.id}" over [${plan.pool.accounts.join(", ")}]`);
+        }
+    }
+    if (Array.isArray(plugins.allow) && !plugins.allow.includes(PLUGIN_ID)) {
+        plugins.allow.push(PLUGIN_ID);
+        changes.push(`append "${PLUGIN_ID}" to plugins.allow`);
+    }
+    if (plan.modelRungs.length > 0) {
+        const agents = (config.agents = asRecord(config.agents) ?? {});
+        const defaults = (agents.defaults = asRecord(agents.defaults) ?? {});
+        const models = (defaults.models = asRecord(defaults.models) ?? {});
+        for (const rung of plan.modelRungs) {
+            if (!(rung in models)) {
+                models[rung] = {};
+                changes.push(`register model "${rung}"`);
+            }
+        }
+    }
+    return { config, changes };
+}

package/dist/shim-core.js

@@ -0,0 +1,218 @@
+export const PRUNE_AFTER_MS = 14 * 24 * 60 * 60 * 1000;
+const RAW_INFO_MAX_CHARS = 512;
+export function createLineScanner(onLine) {
+    let buffer = "";
+    return {
+        push(chunk) {
+            buffer += chunk;
+            let idx;
+            while ((idx = buffer.indexOf("\n")) !== -1) {
+                onLine(buffer.slice(0, idx));
+                buffer = buffer.slice(idx + 1);
+            }
+        },
+        flush() {
+            if (buffer.length > 0) {
+                onLine(buffer);
+                buffer = "";
+            }
+        },
+    };
+}
+export function parseRateLimitEvent(line) {
+    if (!line.includes('"rate_limit_event"'))
+        return undefined;
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof record !== "object" || record === null)
+        return undefined;
+    const r = record;
+    if (r.type !== "rate_limit_event")
+        return undefined;
+    const info = r.rate_limit_info;
+    if (typeof info !== "object" || info === null)
+        return undefined;
+    const i = info;
+    if (typeof i.status !== "string" || i.status.length === 0)
+        return undefined;
+    const rateLimitType = typeof i.rateLimitType === "string" ? i.rateLimitType : undefined;
+    const event = {
+        status: i.status,
+        rateLimitType,
+        resetsAt: typeof i.resetsAt === "number" ? i.resetsAt : undefined,
+        utilization: typeof i.utilization === "number" ? i.utilization : undefined,
+        isUsingOverage: typeof i.isUsingOverage === "boolean" ? i.isUsingOverage : undefined,
+    };
+    if (rateLimitType === undefined) {
+        event.rawInfo = JSON.stringify(info).slice(0, RAW_INFO_MAX_CHARS);
+    }
+    return event;
+}
+export function classifyStateReadFailure(err) {
+    if (typeof err === "object" &&
+        err !== null &&
+        err.code === "ENOENT") {
+        return "absent";
+    }
+    return "unreadable";
+}
+export function parseStoredState(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return undefined;
+    const p = parsed;
+    if (typeof p.windows !== "object" || p.windows === null)
+        return undefined;
+    const windows = {};
+    for (const [key, value] of Object.entries(p.windows)) {
+        if (typeof value !== "object" || value === null)
+            continue;
+        const w = value;
+        if (typeof w.status !== "string" || typeof w.seenAt !== "number")
+            continue;
+        windows[key] = {
+            status: w.status,
+            resetsAt: typeof w.resetsAt === "number" ? w.resetsAt : undefined,
+            utilization: typeof w.utilization === "number" ? w.utilization : undefined,
+            isUsingOverage: typeof w.isUsingOverage === "boolean" ? w.isUsingOverage : undefined,
+            seenAt: w.seenAt,
+            rawInfo: typeof w.rawInfo === "string" ? w.rawInfo : undefined,
+        };
+    }
+    return {
+        accountId: typeof p.accountId === "string" ? p.accountId : "unknown",
+        updatedAt: typeof p.updatedAt === "number" ? p.updatedAt : undefined,
+        windows,
+    };
+}
+export function mergeHealthStates(disk, live, now, pruneAfterMs = PRUNE_AFTER_MS) {
+    const merged = { ...disk.windows };
+    for (const [key, w] of Object.entries(live.windows)) {
+        const existing = merged[key];
+        if (!existing || w.seenAt >= existing.seenAt)
+            merged[key] = w;
+    }
+    const windows = canonicalizeModelWindowKeys(merged);
+    if (now !== undefined) {
+        for (const [key, w] of Object.entries(windows)) {
+            if (now - w.seenAt > pruneAfterMs)
+                delete windows[key];
+        }
+    }
+    const updatedAt = Math.max(disk.updatedAt ?? 0, live.updatedAt ?? 0);
+    return {
+        accountId: live.accountId,
+        updatedAt: updatedAt > 0 ? updatedAt : undefined,
+        windows,
+    };
+}
+const MODEL_ID_PROVIDER_PREFIXES = [
+    "clawd/",
+    "claude-cli/",
+    "anthropic/",
+];
+const CLAW_ACCOUNT_PREFIX_RE = /^claw\d+\//;
+export function canonicalizeModelIdForWindow(modelId) {
+    const clawMatch = CLAW_ACCOUNT_PREFIX_RE.exec(modelId);
+    if (clawMatch)
+        return modelId.slice(clawMatch[0].length);
+    for (const prefix of MODEL_ID_PROVIDER_PREFIXES) {
+        if (modelId.startsWith(prefix))
+            return modelId.slice(prefix.length);
+    }
+    return modelId;
+}
+export function modelWindowKey(modelId) {
+    return `model:${canonicalizeModelIdForWindow(modelId)}`;
+}
+export function canonicalizeModelWindowKeys(windows) {
+    const out = {};
+    for (const [key, w] of Object.entries(windows)) {
+        const canonicalKey = key.startsWith("model:")
+            ? modelWindowKey(key.slice("model:".length))
+            : key;
+        const existing = out[canonicalKey];
+        if (!existing || w.seenAt >= existing.seenAt)
+            out[canonicalKey] = w;
+    }
+    return out;
+}
+const LIMIT_TEXT_RE = /reached your (.{1,40}?) limit/i;
+export function parseModelLimitError(line) {
+    if (!/reached your /i.test(line))
+        return undefined;
+    let record;
+    try {
+        record = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof record !== "object" || record === null)
+        return undefined;
+    const r = record;
+    const isErrorRecord = r.type === "error" ||
+        r.is_error === true ||
+        (typeof r.subtype === "string" && r.subtype.startsWith("error"));
+    if (!isErrorRecord)
+        return undefined;
+    const texts = [];
+    if (typeof r.result === "string")
+        texts.push(r.result);
+    if (typeof r.error === "string")
+        texts.push(r.error);
+    if (typeof r.error === "object" && r.error !== null) {
+        const msg = r.error.message;
+        if (typeof msg === "string")
+            texts.push(msg);
+    }
+    for (const text of texts) {
+        const match = LIMIT_TEXT_RE.exec(text);
+        if (match)
+            return { displayName: match[1].trim() };
+    }
+    return undefined;
+}
+export function recordModelLimit(state, modelId, now, resetsAt) {
+    return {
+        ...state,
+        updatedAt: now,
+        windows: {
+            ...state.windows,
+            [modelWindowKey(modelId)]: {
+                status: "rejected",
+                resetsAt,
+                seenAt: now,
+            },
+        },
+    };
+}
+export function updateHealthState(state, event, now) {
+    const key = event.rateLimitType ?? "unknown";
+    return {
+        ...state,
+        updatedAt: now,
+        windows: {
+            ...state.windows,
+            [key]: {
+                status: event.status,
+                resetsAt: event.resetsAt,
+                utilization: event.utilization,
+                isUsingOverage: event.isUsingOverage,
+                seenAt: now,
+                rawInfo: event.rawInfo,
+            },
+        },
+    };
+}

package/dist/shim.js

@@ -0,0 +1,151 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { classifyStateReadFailure, createLineScanner, mergeHealthStates, parseRateLimitEvent, parseStoredState, updateHealthState, } from "./shim-core.js";
+import { rewriteModelArg } from "./degrade.js";
+import { parseModelLimitError, recordModelLimit } from "./shim-core.js";
+import { canonicalModelId } from "./models.js";
+function resolveClaudeCommand() {
+    const override = process.env.MULTI_CLAWD_CLAUDE_BIN;
+    if (override) {
+        try {
+            const parsed = JSON.parse(override);
+            if (Array.isArray(parsed) && parsed.length > 0 && parsed.every((p) => typeof p === "string")) {
+                return { command: parsed[0], prependArgs: parsed.slice(1) };
+            }
+        }
+        catch {
+        }
+        return { command: override, prependArgs: [] };
+    }
+    return { command: "claude", prependArgs: [] };
+}
+const stateFile = process.env.MULTI_CLAWD_STATE_FILE;
+const accountId = process.env.MULTI_CLAWD_ACCOUNT_ID ?? "unknown";
+let state = { accountId, windows: {} };
+function preserveCorruptState(raw) {
+    if (!stateFile)
+        return;
+    const preservedPath = `${stateFile}.corrupt-${Date.now()}`;
+    let preserved = false;
+    if (raw !== undefined) {
+        try {
+            writeFileSync(preservedPath, raw, { mode: 0o600 });
+            preserved = true;
+        }
+        catch {
+        }
+    }
+    const note = preserved
+        ? `preserved copy: ${preservedPath}`
+        : "original bytes could not be preserved";
+    process.stderr.write(`[multi-clawd shim] state file unreadable/corrupt — starting fresh (${note})\n`);
+}
+function readPersistedState() {
+    if (!stateFile)
+        return undefined;
+    let raw;
+    try {
+        raw = readFileSync(stateFile, "utf8");
+    }
+    catch (err) {
+        if (classifyStateReadFailure(err) === "absent")
+            return undefined;
+        preserveCorruptState(undefined);
+        return undefined;
+    }
+    const parsed = parseStoredState(raw);
+    if (parsed === undefined) {
+        preserveCorruptState(raw);
+        return undefined;
+    }
+    return parsed;
+}
+function persistState() {
+    if (!stateFile)
+        return;
+    try {
+        const disk = readPersistedState();
+        if (disk)
+            state = mergeHealthStates(disk, state, Date.now());
+        mkdirSync(dirname(stateFile), { recursive: true });
+        const tmp = `${stateFile}.tmp-${process.pid}`;
+        writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+        renameSync(tmp, stateFile);
+    }
+    catch (err) {
+        process.stderr.write(`[multi-clawd shim] state write failed: ${String(err)}\n`);
+    }
+}
+const { command, prependArgs } = resolveClaudeCommand();
+let childArgs = [...prependArgs, ...process.argv.slice(2)];
+const modelOverride = process.env.MULTI_CLAWD_MODEL_OVERRIDE;
+if (modelOverride) {
+    const before = childArgs.join(" ");
+    childArgs = rewriteModelArg(childArgs, modelOverride);
+    if (childArgs.join(" ") !== before) {
+        process.stderr.write(`[multi-clawd shim] degrading model for this launch → ${modelOverride}\n`);
+    }
+}
+const child = spawn(command, childArgs, {
+    stdio: ["pipe", "pipe", "inherit"],
+    env: process.env,
+});
+process.stdin.pipe(child.stdin);
+function effectiveModelId() {
+    const idx = childArgs.indexOf("--model");
+    if (idx < 0 || idx + 1 >= childArgs.length)
+        return undefined;
+    const raw = childArgs[idx + 1];
+    return canonicalModelId(raw) ?? raw;
+}
+function guessLimitResetsAt() {
+    const nowS = Date.now() / 1000;
+    for (const [key, w] of Object.entries(state.windows)) {
+        if (key.includes("seven_day") && typeof w.resetsAt === "number" && w.resetsAt > nowS) {
+            return w.resetsAt;
+        }
+    }
+    return undefined;
+}
+const scanner = createLineScanner((line) => {
+    try {
+        const event = parseRateLimitEvent(line);
+        if (event) {
+            state = updateHealthState(state, event, Date.now());
+            persistState();
+        }
+        const limitHit = parseModelLimitError(line);
+        if (limitHit) {
+            const model = effectiveModelId();
+            if (model) {
+                state = recordModelLimit(state, model, Date.now(), guessLimitResetsAt());
+                persistState();
+                process.stderr.write(`[multi-clawd shim] model limit hit recorded: ${model} (reported as "${limitHit.displayName}")\n`);
+            }
+        }
+    }
+    catch {
+    }
+});
+child.stdout.on("data", (chunk) => {
+    process.stdout.write(chunk);
+    scanner.push(chunk.toString("utf8"));
+});
+child.stdout.on("end", () => scanner.flush());
+for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+    process.on(signal, () => {
+        child.kill(signal);
+    });
+}
+child.on("close", (code, signal) => {
+    if (signal) {
+        process.kill(process.pid, signal);
+        return;
+    }
+    process.exit(code ?? 0);
+});
+child.on("error", (err) => {
+    process.stderr.write(`[multi-clawd shim] failed to spawn claude: ${String(err)}\n`);
+    process.exit(127);
+});

package/dist/sticky.js

@@ -0,0 +1,24 @@
+import { choosePoolAccount } from "./health.js";
+export const DEFAULT_MIN_DWELL_MS = 10 * 60 * 1000;
+export function decideStickySelection(params) {
+    const { verdicts, sticky, nowMs } = params;
+    const minDwellMs = params.minDwellMs ?? DEFAULT_MIN_DWELL_MS;
+    const home = verdicts[0];
+    const healthChoice = choosePoolAccount(verdicts);
+    if (!healthChoice)
+        return { account: home.id };
+    const stickyVerdict = sticky
+        ? verdicts.find((v) => v.id === sticky.account)?.verdict
+        : undefined;
+    const stickyUsable = stickyVerdict === "ok" || stickyVerdict === "no_data";
+    if (sticky && sticky.account !== home.id && stickyUsable) {
+        const homeUsable = home.verdict === "ok" || home.verdict === "no_data";
+        if (homeUsable && nowMs - sticky.since >= minDwellMs) {
+            return { account: home.id };
+        }
+        return { account: sticky.account, sticky };
+    }
+    if (healthChoice === home.id)
+        return { account: home.id };
+    return { account: healthChoice, sticky: { account: healthChoice, since: nowMs } };
+}

package/dist/token-resolution.js

@@ -0,0 +1,62 @@
+export function redactRefError(_ref, error) {
+    const errorClass = error instanceof Error ? error.constructor.name : typeof error;
+    return `credential_resolution_failed (${errorClass})`;
+}
+export function isSecretRefShape(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v.source === "string" &&
+        v.source.length > 0 &&
+        typeof v.provider === "string" &&
+        v.provider.length > 0 &&
+        typeof v.id === "string" &&
+        v.id.length > 0);
+}
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+function cacheKey(ref) {
+    return `${ref.source}\u0000${ref.provider}\u0000${ref.id}`;
+}
+export function createTokenRefResolver(options) {
+    const reportError = (ref, error) => {
+        options.onError?.(ref, options.redact ? redactRefError(ref, error) : error);
+    };
+    const ttlMs = options.ttlMs ?? DEFAULT_TTL_MS;
+    const cache = new Map();
+    const fromCache = (ref, nowMs) => {
+        const hit = cache.get(cacheKey(ref));
+        if (hit && hit.expiresAt > nowMs)
+            return hit.value;
+        return undefined;
+    };
+    return {
+        peek(ref, nowMs = Date.now()) {
+            return fromCache(ref, nowMs);
+        },
+        async resolveDetailed(ref, nowMs = Date.now()) {
+            const cached = fromCache(ref, nowMs);
+            if (cached !== undefined)
+                return { value: cached };
+            let resolved;
+            try {
+                const values = await options.resolveRefs([ref]);
+                resolved =
+                    values.get(`${ref.source}:${ref.provider}:${ref.id}`) ?? values.get(ref.id);
+            }
+            catch (error) {
+                reportError(ref, error);
+                return { failure: "provider_error" };
+            }
+            if (typeof resolved !== "string" || resolved.trim().length === 0) {
+                reportError(ref, new Error(`secret ref resolved to ${resolved === undefined ? "nothing" : typeof resolved}`));
+                return { failure: "empty_result" };
+            }
+            const value = resolved.trim();
+            cache.set(cacheKey(ref), { value, expiresAt: nowMs + ttlMs });
+            return { value };
+        },
+        async resolve(ref, nowMs = Date.now()) {
+            return (await this.resolveDetailed(ref, nowMs)).value;
+        },
+    };
+}

package/dist/watchdog-core.js

@@ -0,0 +1,53 @@
+export function decideWatchdogAction(input) {
+    const { state, nowMs } = input;
+    const fresh = input.evictionTimestamp !== undefined &&
+        (state.lastHandled === undefined || input.evictionTimestamp > state.lastHandled);
+    const pending = state.pendingEviction;
+    if (!fresh && !pending) {
+        return { action: "none", reason: "no unhandled eviction", nextState: state };
+    }
+    const logTimestamp = pending?.logTimestamp ?? input.evictionTimestamp;
+    const firstDeferredAt = pending?.firstDeferredAt;
+    const deferCapExceeded = firstDeferredAt !== undefined && nowMs - firstDeferredAt >= input.maxDeferMs;
+    if (input.inFlight && !deferCapExceeded) {
+        return {
+            action: "defer",
+            reason: "turn in-flight — deferring restart",
+            nextState: {
+                ...state,
+                pendingEviction: {
+                    logTimestamp,
+                    firstDeferredAt: firstDeferredAt ?? nowMs,
+                    defers: (pending?.defers ?? 0) + 1,
+                },
+            },
+        };
+    }
+    const sinceRestart = nowMs - (state.lastRestartAt ?? 0);
+    if (sinceRestart < input.restartCooldownMs) {
+        return {
+            action: "defer",
+            reason: "restart cooldown active",
+            nextState: {
+                ...state,
+                pendingEviction: {
+                    logTimestamp,
+                    firstDeferredAt: firstDeferredAt ?? nowMs,
+                    defers: (pending?.defers ?? 0) + 1,
+                },
+            },
+        };
+    }
+    return {
+        action: "restart",
+        reason: deferCapExceeded
+            ? `defer cap exceeded after ${pending?.defers ?? 0} deferral(s) — restarting despite in-flight turn`
+            : pending
+                ? `deferred eviction now safe to handle (${pending.defers} deferral(s))`
+                : "eviction detected, no turn in flight",
+        nextState: {
+            lastHandled: logTimestamp,
+            lastRestartAt: nowMs,
+        },
+    };
+}