clauderipple 0.9.4 → 0.10.0

package/dist/remote/src/relay.js

@@ -0,0 +1,438 @@
+// The host's side of the relay. One outbound control socket that never gives up — the same
+// liveness numbers as the phone's link and Paseo's daemon (spec): ping every 10 s, stale after
+// 30 s of silence, abandoned if not ready 8 s after it was created, backoff min(30 s, n × 1 s)
+// forever. When the relay says a phone arrived, the host opens one data socket for it, answers the
+// phone's handshake (e2ee.ts) and hands the decrypted channel to HostServer like any other phone.
+// The relay sees ciphertext only; the pairing token is checked inside the channel, as on the
+// direct path.
+//
+// A pong proves only that the relay's edge answers this socket, not that phones reach it: on
+// 2026-10-15 the relay kept sending every phone to a replaced socket that never answered its close,
+// while this socket stayed "connected" and phones sat at "connecting" (see Room.host). So after
+// each hello and every ROUTE_CHECK_MS the host also walks the phone's path itself — a client socket
+// to its own room must come back "open" — and reconnects when it does not.
+import { BACKOFF_CAP_MS, FRAME_CAP, PING_MS, READY_MS, RELAY_CLOSE, RELAY_FRAME_CAP, STALE_MS } from "./protocol.js";
+import path from "node:path";
+import { fromB64u, hostAccept, toB64u } from "./e2ee.js";
+import { readJson, writeFileAtomic } from "./fsutil.js";
+/** The host's long-term X25519 key pair (its public half goes in the pairing link), made once, kept 0600. */
+export function loadHostKey(dir, nacl) {
+    const file = path.join(dir, "host-key.json");
+    const stored = readJson(file);
+    if (stored?.publicKey && stored.secretKey) {
+        const kp = { publicKey: fromB64u(stored.publicKey), secretKey: fromB64u(stored.secretKey) };
+        if (kp.publicKey.length === 32 && kp.secretKey.length === 32)
+            return kp;
+        throw new Error(`${file} is damaged; remove it to make a new key (every phone then pairs again)`);
+    }
+    const kp = nacl.box.keyPair();
+    writeFileAtomic(file, JSON.stringify({ publicKey: toB64u(kp.publicKey), secretKey: toB64u(kp.secretKey) }, null, 2) + "\n");
+    return kp;
+}
+const OPEN = 1;
+export function relayBackoff(attempt) {
+    return Math.min(BACKOFF_CAP_MS, Math.max(1, attempt) * 1000);
+}
+/** First walk of the phone's path after a hello, then every ROUTE_CHECK_MS while connected. */
+export const ROUTE_FIRST_MS = 2_000;
+export const ROUTE_CHECK_MS = 5 * 60_000;
+/** A probe phone that is not let through ("open") within this has no route to this host. */
+export const ROUTE_TIMEOUT_MS = 10_000;
+/** A ping timer this late means the process did not run (sleep, or a blocked event loop). */
+export const STALL_MS = 5_000;
+/** After such a stall, how long a fresh ping has to be answered before the socket is called dead. */
+export const STALL_GRACE_MS = 5_000;
+function wsOrigin(relay) {
+    const u = new URL(relay);
+    return `${u.protocol === "https:" ? "wss:" : "ws:"}//${u.host}`;
+}
+const toBytes = (data) => Array.isArray(data) ? new Uint8Array(Buffer.concat(data)) : data instanceof ArrayBuffer ? new Uint8Array(data) : new Uint8Array(data.buffer, data.byteOffset, data.byteLength);
+const toText = (data) => Buffer.from(toBytes(data)).toString("utf8");
+/**
+ * One phone through the relay, after the handshake: a Peer whose frames are sealed and opened
+ * here. Anything that does not open — altered, replayed, out of order, or plaintext — ends it.
+ */
+export class SecurePeer {
+    OPEN = OPEN;
+    ws;
+    channel;
+    handlers = { message: [], close: [], error: [] };
+    closed = false;
+    constructor(ws, channel) {
+        this.ws = ws;
+        this.channel = channel;
+        ws.on("message", (data, isBinary) => {
+            if (this.closed)
+                return;
+            const bytes = toBytes(data);
+            if (!isBinary || bytes.length > RELAY_FRAME_CAP) {
+                this.fail(4400, "bad frame");
+                return;
+            }
+            let text;
+            try {
+                text = channel.open(bytes);
+            }
+            catch {
+                this.fail(4400, "bad frame");
+                return;
+            }
+            if (text.length > FRAME_CAP) {
+                this.fail(1009, "frame over cap");
+                return;
+            }
+            for (const fn of this.handlers.message)
+                fn(text);
+        });
+        ws.on("close", () => this.end());
+        ws.on("error", (e) => { for (const fn of this.handlers.error)
+            fn(e); });
+    }
+    get readyState() { return this.closed ? 3 : this.ws.readyState; }
+    get bufferedAmount() { return this.ws.bufferedAmount; }
+    send(text) {
+        if (this.closed)
+            return;
+        this.ws.send(this.channel.seal(text));
+    }
+    close(code = 1000, reason = "") { try {
+        this.ws.close(code, reason);
+    }
+    catch { /* gone */ } this.end(); }
+    terminate() { try {
+        this.ws.terminate();
+    }
+    catch { /* gone */ } this.end(); }
+    on(event, fn) {
+        this.handlers[event].push(fn);
+        return this;
+    }
+    fail(code, reason) { this.close(code, reason); }
+    end() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        for (const fn of this.handlers.close)
+            fn();
+    }
+}
+export class RelayHost {
+    state = "connecting";
+    attempt = 0;
+    /** Consecutive route checks that found no way from a phone to this host. */
+    routeFailures = 0;
+    deps;
+    now;
+    setTimer;
+    clearTimer;
+    sock = null;
+    lastRx = 0;
+    downSince = null;
+    timers = { retry: null, ping: null, ready: null, route: null };
+    stopped = false;
+    data = new Set();
+    probe = null;
+    /** A route check passed on the current control socket (said once per connection). */
+    routeConfirmed = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.now = deps.now ?? Date.now;
+        this.setTimer = deps.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = deps.clearTimer ?? ((id) => clearTimeout(id));
+    }
+    start() { this.stopped = false; this.connect(); }
+    stop() {
+        this.stopped = true;
+        this.clearAll();
+        try {
+            this.sock?.close(1000, "stop");
+        }
+        catch { /* gone */ }
+        this.sock = null;
+        for (const d of this.data)
+            try {
+                d.close(1001, "host stopping");
+            }
+            catch { /* gone */ }
+        this.data.clear();
+    }
+    log(line) { this.deps.log?.(`relay: ${line}`); }
+    headers() { return { "x-ripple-host-secret": this.deps.secret }; }
+    clearAll() {
+        for (const k of ["retry", "ping", "ready", "route"])
+            if (this.timers[k] !== null) {
+                this.clearTimer(this.timers[k]);
+                this.timers[k] = null;
+            }
+        const probe = this.probe;
+        this.probe = null;
+        if (probe)
+            try {
+                probe.terminate();
+            }
+            catch { /* gone */ }
+    }
+    connect() {
+        if (this.stopped)
+            return;
+        this.state = "connecting";
+        let sock;
+        try {
+            sock = this.deps.makeSocket(`${wsOrigin(this.deps.relay)}/ws/host?server=${encodeURIComponent(this.deps.serverId)}`, this.headers());
+        }
+        catch (e) {
+            this.log(e.message);
+            this.fail(null);
+            return;
+        }
+        this.sock = sock;
+        let ready = false;
+        // From creation: a connect that hangs after a network change fires neither open nor close for minutes.
+        this.timers.ready = this.setTimer(() => {
+            this.timers.ready = null;
+            if (!ready && this.sock === sock) {
+                this.log(`no hello within ${READY_MS / 1000} s; trying again`);
+                try {
+                    sock.terminate();
+                }
+                catch { /* gone */ }
+                this.fail(sock);
+            }
+        }, READY_MS);
+        sock.on("open", () => { if (this.sock === sock)
+            this.lastRx = this.now(); });
+        sock.on("message", (data) => {
+            if (this.sock !== sock)
+                return;
+            this.lastRx = this.now();
+            const text = Buffer.isBuffer(data) ? data.toString("utf8") : Array.isArray(data) ? Buffer.concat(data).toString("utf8") : Buffer.from(data).toString("utf8");
+            if (text === "pong")
+                return;
+            let msg;
+            try {
+                msg = JSON.parse(text);
+            }
+            catch {
+                return;
+            }
+            if (msg.relay === "hello" && !ready) {
+                ready = true;
+                if (this.timers.ready !== null) {
+                    this.clearTimer(this.timers.ready);
+                    this.timers.ready = null;
+                }
+                if (this.attempt > 0)
+                    this.log(`connected again after ${this.attempt} attempt(s), ${Math.round((this.now() - (this.downSince ?? this.now())) / 1000)} s without the relay`);
+                else
+                    this.log(`connected to ${this.deps.relay}`);
+                this.state = "open";
+                this.attempt = 0;
+                this.downSince = null;
+                this.armPing(sock);
+                this.routeConfirmed = false;
+                this.armRouteCheck(sock, ROUTE_FIRST_MS);
+            }
+            else if (msg.relay === "connect" && typeof msg.conn === "string")
+                this.openData(msg.conn);
+        });
+        sock.on("unexpected-response", (_req, res) => {
+            // 403: another host already holds this server id with a different secret. Retrying is still right (it may be a stale room), but say so.
+            this.log(`refused with HTTP ${res.statusCode ?? "?"}`);
+            // With a listener here, `ws` leaves the handshake to us; end it so the close (and the retry) follow now.
+            try {
+                sock.terminate();
+            }
+            catch { /* gone */ }
+        });
+        sock.on("close", (code, reason) => {
+            if (this.sock !== sock)
+                return;
+            const why = reason ? String(reason) : "";
+            if (code === RELAY_CLOSE.replaced) {
+                // This process keeps one control socket, so a replacement came from somewhere else: another
+                // ripple-host with the same server id and secret. Back off fully rather than trade the room
+                // back and forth with it every second.
+                this.log(`replaced by another connection with this server id (a second ripple-host sharing this host.json?); retrying in ${BACKOFF_CAP_MS / 1000} s`);
+                this.fail(sock, BACKOFF_CAP_MS);
+                return;
+            }
+            if (ready)
+                this.log(`connection closed (${code}${why ? ` ${why}` : ""})`);
+            this.fail(sock);
+        });
+        sock.on("error", () => { });
+    }
+    /** The current control socket ended: retry after the backoff, or after `wait` when given. */
+    fail(sock, wait) {
+        if (sock && this.sock !== sock)
+            return;
+        this.sock = null;
+        this.clearAll();
+        if (this.stopped)
+            return;
+        this.attempt++;
+        this.downSince ??= this.now();
+        this.state = "waiting";
+        this.timers.retry = this.setTimer(() => { this.timers.retry = null; this.connect(); }, wait ?? relayBackoff(this.attempt));
+    }
+    armPing(sock) {
+        let due = this.now() + PING_MS;
+        let graceUntil = 0;
+        const loop = () => {
+            this.timers.ping = null;
+            if (this.sock !== sock)
+                return;
+            const now = this.now();
+            const late = now - due;
+            if (late > STALL_MS) {
+                // This process did not run for a while: the Mac slept, or something blocked the event
+                // loop. A pong that arrived meanwhile may still be queued behind this timer, so silence
+                // proves nothing yet; ping, and judge a moment later.
+                this.log(`timers ran ${Math.round(late / 1000)} s late (sleep or a blocked event loop); checking the connection`);
+                graceUntil = now + STALL_GRACE_MS;
+            }
+            else if (now - this.lastRx > STALE_MS && now >= graceUntil) {
+                // Half-open: no frame, not even a pong, for 30 s. Drop it ourselves rather than wait for TCP.
+                this.log(`nothing from the relay for ${Math.round((now - this.lastRx) / 1000)} s; dropping the connection`);
+                try {
+                    sock.terminate();
+                }
+                catch { /* gone */ }
+                this.fail(sock);
+                return;
+            }
+            if (sock.readyState === OPEN)
+                try {
+                    sock.send("ping");
+                }
+                catch { /* close follows */ }
+            const next = now < graceUntil ? STALL_GRACE_MS : PING_MS;
+            due = now + next;
+            this.timers.ping = this.setTimer(loop, next);
+        };
+        this.timers.ping = this.setTimer(loop, PING_MS);
+    }
+    armRouteCheck(sock, ms) {
+        if (this.timers.route !== null)
+            this.clearTimer(this.timers.route);
+        this.timers.route = this.setTimer(() => { this.timers.route = null; this.checkRoute(sock); }, ms);
+    }
+    /**
+     * Walk the phone's path: a client socket to this host's own room must be let through ("open"),
+     * which takes the relay sending "connect" to the socket this host holds and this host's data
+     * socket arriving. The probe then leaves; it never says hello, so HostServer never sees it.
+     */
+    checkRoute(sock) {
+        if (this.sock !== sock || this.stopped)
+            return;
+        let probe;
+        try {
+            probe = this.deps.makeSocket(`${wsOrigin(this.deps.relay)}/ws/client?server=${encodeURIComponent(this.deps.serverId)}`, {});
+        }
+        catch (e) {
+            this.log(`route check could not start: ${e.message}`);
+            this.armRouteCheck(sock, ROUTE_CHECK_MS);
+            return;
+        }
+        this.probe = probe;
+        let settled = false;
+        const finish = (ok, why) => {
+            if (settled)
+                return;
+            settled = true;
+            this.clearTimer(timeout);
+            if (this.probe === probe)
+                this.probe = null;
+            try {
+                probe.close(1000, "route check");
+            }
+            catch { /* gone */ }
+            if (this.sock !== sock || this.stopped)
+                return;
+            if (ok) {
+                if (this.routeFailures > 0)
+                    this.log(`phones reach this host again (after ${this.routeFailures} failed route check(s))`);
+                else if (!this.routeConfirmed)
+                    this.log("route check: phones reach this host");
+                this.routeConfirmed = true;
+                this.routeFailures = 0;
+                this.armRouteCheck(sock, ROUTE_CHECK_MS);
+                return;
+            }
+            this.routeFailures++;
+            // Said once per streak (then every tenth), not every retry.
+            if (this.routeFailures === 1 || this.routeFailures % 10 === 0)
+                this.log(`route check failed (${why}): a phone cannot reach this host through the relay; reconnecting (failure ${this.routeFailures})`);
+            try {
+                sock.terminate();
+            }
+            catch { /* gone */ }
+            // Growing waits: a route the relay keeps broken is retried, not hammered.
+            this.fail(sock, relayBackoff(5 * this.routeFailures));
+        };
+        const timeout = this.setTimer(() => finish(false, `not let through within ${ROUTE_TIMEOUT_MS / 1000} s`), ROUTE_TIMEOUT_MS);
+        probe.on("message", (data, isBinary) => {
+            if (isBinary)
+                return;
+            try {
+                if (JSON.parse(toText(data)).relay === "open")
+                    finish(true, "");
+            }
+            catch { /* not ours */ }
+        });
+        probe.on("close", (code) => finish(false, code === RELAY_CLOSE.hostOffline ? "the relay says this host is offline" : `closed ${code}`));
+        probe.on("unexpected-response", (_req, res) => {
+            finish(false, `HTTP ${res.statusCode ?? "?"}`);
+            try {
+                probe.terminate();
+            }
+            catch { /* gone */ }
+        });
+        probe.on("error", () => { });
+    }
+    /** A phone is waiting in the room: open its data socket and answer its handshake. */
+    openData(conn) {
+        if (!/^[\w-]{8,64}$/.test(conn))
+            return;
+        let ws;
+        try {
+            ws = this.deps.makeSocket(`${wsOrigin(this.deps.relay)}/ws/host-data?server=${encodeURIComponent(this.deps.serverId)}&conn=${encodeURIComponent(conn)}`, this.headers());
+        }
+        catch {
+            return;
+        }
+        this.data.add(ws);
+        let done = false;
+        const timer = this.setTimer(() => { if (!done)
+            try {
+                ws.terminate();
+            }
+            catch { /* gone */ } }, READY_MS * 2);
+        const onHello = (data, isBinary) => {
+            if (done)
+                return;
+            done = true;
+            this.clearTimer(timer);
+            try {
+                if (isBinary)
+                    throw new Error("handshake must be text");
+                const bytes = toBytes(data);
+                if (bytes.length > 4096)
+                    throw new Error("handshake too large");
+                const { text, channel } = hostAccept(this.deps.nacl, this.deps.hostKey, new TextDecoder().decode(bytes));
+                ws.send(text);
+                this.deps.onPeer(new SecurePeer(ws, channel));
+            }
+            catch (e) {
+                this.deps.log?.(`relay: phone handshake failed: ${e.message}`);
+                try {
+                    ws.close(4400, "handshake");
+                }
+                catch { /* gone */ }
+            }
+        };
+        ws.on("message", onHello);
+        ws.on("close", () => { this.data.delete(ws); this.clearTimer(timer); });
+        ws.on("error", () => { });
+    }
+}

package/dist/remote/src/router.js

@@ -0,0 +1,208 @@
+const EFFORTS = ["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"];
+const LABELS = {
+    chatgpt: "ChatGPT", anthropic: "Claude", openrouter: "OpenRouter", deepseek: "DeepSeek",
+    "opencode-go": "OpenCode Go", "opencode-zen": "OpenCode Zen", "google-gemini": "Google Gemini",
+};
+const toEffort = (s) => (s && EFFORTS.includes(s) ? s : null);
+const base = (id) => id.split("@")[0].replace(/-\d{8}$/, "");
+export class RouterClient {
+    adminUrl;
+    fetch;
+    constructor(adminUrl, fetchImpl = globalThis.fetch) {
+        this.adminUrl = adminUrl.replace(/\/$/, "");
+        this.fetch = fetchImpl;
+    }
+    async get(path) {
+        const res = await this.fetch(this.adminUrl + path, { signal: AbortSignal.timeout(4000) });
+        if (!res.ok)
+            throw new Error(`router ${path}: HTTP ${res.status}`);
+        return (await res.json());
+    }
+    /** Every chat model the router routes, grouped by provider, judge-only models left out (ARCHITECTURE §3b). */
+    async models() {
+        const [opts, levels] = await Promise.all([this.get("/api/mod-options"), this.get("/api/effort-levels")]);
+        return groupModels(opts, levels);
+    }
+    /** The router's own `GET /api/limits` body, unvalidated: `rippleStatus` reads it at the boundary. */
+    async limits() { return this.get("/api/limits"); }
+    /** The router's own `GET /api/mod-settings` body, unvalidated: `rippleStatus` reads it at the boundary. */
+    async modSettings() { return this.get("/api/mod-settings"); }
+    /** What a spawned CLI needs to go through the router: the same two keys `~/.claude/settings.json` carries (ARCHITECTURE §1). */
+    async status() {
+        try {
+            const s = await this.get("/api/status");
+            const proxyEnv = {};
+            const proxy = s.settings?.HTTPS_PROXY ?? (s.listen ? `http://${s.listen.host}:${s.listen.port}` : undefined);
+            if (proxy)
+                proxyEnv.HTTPS_PROXY = proxy;
+            if (s.settings?.NODE_EXTRA_CA_CERTS)
+                proxyEnv.NODE_EXTRA_CA_CERTS = s.settings.NODE_EXTRA_CA_CERTS;
+            // Readiness problems name one provider needing attention (measured: "provider:opencode-go"
+            // while that provider still answered); they are not "the router is down", so they do not turn the banner on.
+            return { ok: true, proxyEnv };
+        }
+        catch (e) {
+            return { ok: false, problem: e.message, proxyEnv: {} };
+        }
+    }
+    /** The mod's figures for one Claude Code session, from the router's own request records. */
+    async figures(sessionId, mainModel, contextWindow) {
+        const [reqs, status, window] = await Promise.all([
+            this.get(`/api/requests?kind=messages&n=400&session=${encodeURIComponent(sessionId)}`).catch(() => ({ requests: [] })),
+            this.get("/api/status").catch(() => ({})),
+            contextWindow ?? this.catalogWindow(mainModel),
+        ]);
+        return computeFigures(reqs.requests, mainModel, window, status, Date.now());
+    }
+    windows = null;
+    /**
+     * The router's catalogue window for a model (`GET /api/context-windows`), for a session whose CLI
+     * never told us one: a Claude app session. Read at most every 10 minutes; unknown or an older
+     * router without the endpoint is null.
+     */
+    async catalogWindow(model) {
+        // Claude Code's own suffix: "[1m]" is the million-token variant of the same model.
+        if (/\[1m\]$/i.test(model))
+            return 1_000_000;
+        if (!this.windows || Date.now() - this.windows.at > 10 * 60_000) {
+            const body = await this.get("/api/context-windows").catch(() => null);
+            const raw = body?.windows && typeof body.windows === "object" ? body.windows : null;
+            // A failed read is not cached: the next refresh asks again.
+            if (raw) {
+                const map = {};
+                for (const [id, value] of Object.entries(raw))
+                    if (typeof value === "number" && value > 0)
+                        map[id] = value;
+                this.windows = { at: Date.now(), map };
+            }
+        }
+        const map = this.windows?.map ?? {};
+        const id = model.replace(/\[[^\]]*\]$/, "");
+        return map[model] ?? map[id] ?? map[base(id)] ?? null;
+    }
+}
+export function groupModels(opts, levels) {
+    const usable = new Map(opts.providers.map((p) => [p.name, p.usable]));
+    const groups = new Map();
+    for (const m of opts.models) {
+        if (m.judgeOnly)
+            continue;
+        const ladder = levels.providers[m.provider];
+        const efforts = (ladder?.models?.[m.model] ?? ladder?.default ?? []).map(toEffort).filter((e) => e !== null && e !== "none" && e !== "minimal");
+        const ok = usable.get(m.provider) ?? false;
+        let g = groups.get(m.provider);
+        if (!g) {
+            g = { provider: m.provider, label: LABELS[m.provider] ?? m.provider, usable: ok, models: [] };
+            groups.set(m.provider, g);
+        }
+        g.models.push({ model: m.model, name: m.name, provider: m.provider, efforts, usable: ok });
+    }
+    return Array.from(groups.values());
+}
+/**
+ * Cache % is read over all input of the session's main-model requests; context % is the latest
+ * main request's input over the window the CLI reported for the model. Unknown stays null.
+ * `route` is where that same latest request went (the router's target, not the model asked for).
+ */
+export function computeFigures(records, mainModel, contextWindow, status, now) {
+    const main = base(mainModel);
+    let read = 0, all = 0;
+    let effort = null;
+    let latest = -Infinity;
+    let lastInput = null;
+    let route = null;
+    const workers = new Map();
+    for (const r of records) {
+        const target = r.target ?? r.source ?? "";
+        if (base(target) === main || base(r.source ?? "") === main) {
+            const u = r.usage ?? {};
+            read += u.cached ?? 0;
+            all += (u.input ?? 0) + (u.cached ?? 0) + (u.cacheWrite ?? 0);
+            const at = r.at ? Date.parse(r.at) : 0;
+            const input = (u.input ?? 0) + (u.cached ?? 0) + (u.cacheWrite ?? 0);
+            // A request still streaming has no usage yet; it would read as an empty context (measured: 0% mid-turn).
+            if (at > latest && input > 0) {
+                latest = at;
+                effort = toEffort(r.effort) ?? effort;
+                lastInput = input;
+                route = { model: target.replace(/@[^@]*$/, ""), provider: r.provider ?? "", ok: r.ok === true, status: typeof r.status === "number" ? r.status : null };
+            }
+        }
+        else if (target) {
+            const key = base(target);
+            const w = workers.get(key) ?? { model: key, provider: r.provider ?? "", requests: 0 };
+            w.requests++;
+            workers.set(key, w);
+        }
+    }
+    const windows = status.claude?.accounts?.[0]?.quota?.rate_limits;
+    const five = [windows?.primary, windows?.secondary].find((w) => w?.window_minutes === 300);
+    return {
+        effort,
+        cachePct: all > 0 ? Math.round((read / all) * 1000) / 10 : null,
+        contextPct: contextWindow && lastInput !== null ? Math.min(100, Math.round((lastInput / contextWindow) * 1000) / 10) : null,
+        contextTokens: lastInput,
+        contextWindow: contextWindow && contextWindow > 0 ? contextWindow : null,
+        route,
+        fiveHourPct: typeof five?.used_percent === "number" ? five.used_percent : null,
+        fiveHourResetAt: typeof five?.reset_at === "number" ? five.reset_at * 1000 : null,
+        workers: Array.from(workers.values()).sort((a, b) => b.requests - a.requests),
+        at: now,
+    };
+}
+// ---- the mod's host-wide status -----------------------------------------------------------------
+const obj = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : {});
+const WINDOW_KINDS = ["five_hour", "seven_day", "scoped", "window"];
+/**
+ * What the ClaudeRipple mod is set to, from the router's `GET /api/mod-settings` and `GET /api/limits`.
+ * Both bodies are read at the boundary: a malformed piece is dropped, never thrown on. The
+ * flattening follows the mod's own `routerLimitItems` (packages/mod/hooks/session.ts): a window
+ * whose reset has passed is gone, a reset under 1e12 is epoch seconds, Claude's windows lead and the
+ * other providers keep the router's order.
+ */
+export function rippleStatus(limitsJson, modSettingsJson, now) {
+    const settings = obj(obj(modSettingsJson).settings);
+    const modes = Array.isArray(settings.modes) ? settings.modes.map(obj) : [];
+    const active = typeof settings.activeMode === "string" ? modes.find((m) => m.id === settings.activeMode) : undefined;
+    const mode = active && typeof active.id === "string" && typeof active.name === "string"
+        ? { id: active.id, name: active.name, since: typeof settings.activeSince === "number" && Number.isFinite(settings.activeSince) ? settings.activeSince : null }
+        : null;
+    const providers = Array.isArray(obj(limitsJson).providers) ? obj(limitsJson).providers.map(obj) : [];
+    const limits = [];
+    const claude = [];
+    for (const p of providers) {
+        const provider = typeof p.provider === "string" ? p.provider : "";
+        if (!provider || !Array.isArray(p.accounts))
+            continue;
+        const title = typeof p.title === "string" && p.title ? p.title : LABELS[provider] ?? provider;
+        const accounts = p.accounts.map(obj).filter((a) => Array.isArray(a.windows));
+        const into = p.type === "anthropic" ? claude : limits;
+        accounts.forEach((a, index) => {
+            for (const w of a.windows.map(obj)) {
+                const kind = WINDOW_KINDS.find((k) => k === w.kind);
+                if (!kind || typeof w.used_percent !== "number" || !Number.isFinite(w.used_percent))
+                    continue;
+                const resetAt = typeof w.reset_at === "number" && Number.isFinite(w.reset_at) ? w.reset_at * (w.reset_at < 1e12 ? 1000 : 1) : null;
+                if (resetAt !== null && resetAt <= now)
+                    continue;
+                into.push({
+                    provider, title,
+                    ...(accounts.length > 1 ? { account: `#${(typeof a.account === "number" ? a.account : index) + 1}` } : {}),
+                    kind,
+                    label: (kind === "scoped" || kind === "window") && typeof w.label === "string" ? w.label : null,
+                    usedPct: Math.round(w.used_percent * 10) / 10,
+                    windowMinutes: typeof w.window_minutes === "number" && w.window_minutes > 0 ? w.window_minutes : null,
+                    resetAt,
+                });
+            }
+        });
+    }
+    return {
+        mode,
+        effortAuto: settings.effortAuto === true,
+        effortFloor: toEffort(typeof settings.floor === "string" ? settings.floor : undefined),
+        effortCeiling: toEffort(typeof settings.ceiling === "string" ? settings.ceiling : undefined),
+        limits: [...claude, ...limits],
+        at: now,
+    };
+}

package/dist/remote/src/sdk-launcher.js

@@ -0,0 +1,18 @@
+// npm's Windows batch launcher needs cmd.exe; native .exe and SDK's bundled CLI stay direct.
+import { spawn } from "node:child_process";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+export function batchCommand(command, args) {
+    // cmd expands these even inside quotes. Refuse rather than execute a different command.
+    const words = [command, ...args];
+    if (words.some(word => /[\r\n"%!^&|<>]/.test(word)))
+        throw new Error("unsafe character in Windows Claude batch launcher arguments; use claude.exe instead");
+    return words.map(word => `"${word}"`).join(" ");
+}
+export function launcherOptions(binary, platform = process.platform) {
+    if (platform !== "win32" || !binary || !/\.(cmd|bat)$/i.test(binary))
+        return {};
+    return { spawnClaudeCodeProcess: options => spawn(batchCommand(options.command, options.args), {
+            cwd: options.cwd, env: options.env, signal: options.signal, shell: true, windowsHide: true, stdio: ["pipe", "pipe", "pipe"],
+        }) };
+}
+export const sdkQuery = input => query({ ...input, options: { ...input.options, ...launcherOptions(input.options?.pathToClaudeCodeExecutable) } });