clauderipple 0.9.4 → 0.10.0

package/dist/router/src/remote-tunnel.js

@@ -0,0 +1,320 @@
+// Reverse SSH tunnels to remote hosts that run Claude Code for Claude Desktop (issue #67).
+//
+// Each configured host gets one long-lived `ssh -N -R 127.0.0.1:<remote port>:127.0.0.1:<proxy
+// port> <host>`, owned by the router because the router is what launchd / the Windows supervisor /
+// systemd already keeps alive. A tunnel that exits is started again with capped backoff; each time
+// one comes up the CA and agent files on that host are brought up to date (remote-host.ts), and
+// again when the router regenerates the agent files.
+//
+// Children are killed when the router exits, and their pids are recorded: a router that died
+// without killing them (SIGKILL) would otherwise leave an orphan holding the remote port, and every
+// new tunnel would then fail `ExitOnForwardFailure` for as long as the orphan lives.
+import { execFileSync, spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { BATCH_OPTIONS, SSH_MISSING, extraSshOptions, sshExecutable } from "./remote-host.js";
+/**
+ * The tunnel's argv. `-v` is there for one line: `remote forward success for: listen …` is how
+ * ssh says the remote port is actually bound (measured, OpenSSH 10.3). Every other debug line is
+ * dropped before the log; `ExitOnForwardFailure` makes a forward that cannot bind an exit.
+ */
+export function tunnelArgs(host, port, target) {
+    return [
+        "-N",
+        "-v",
+        ...BATCH_OPTIONS,
+        "-o", "ExitOnForwardFailure=yes",
+        "-o", "ServerAliveInterval=15",
+        "-o", "ServerAliveCountMax=3",
+        "-R", `127.0.0.1:${port}:${target.host}:${target.port}`,
+        ...extraSshOptions(),
+        host,
+    ];
+}
+/** The connection target a router listening on `host` is reached at: a wildcard bind means loopback. */
+export function proxyConnectHost(listenHost) {
+    return listenHost === "0.0.0.0" || listenHost === "::" || listenHost === "" ? "127.0.0.1" : listenHost;
+}
+function defaultProcessCommand(pid) {
+    try {
+        if (process.platform === "win32") {
+            const out = execFileSync("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", `(Get-CimInstance Win32_Process -Filter "ProcessId=${pid}").CommandLine`], { encoding: "utf8", windowsHide: true, timeout: 15_000 });
+            return out.trim() || null;
+        }
+        const out = execFileSync("ps", ["-o", "command=", "-p", String(pid)], { encoding: "utf8", timeout: 5_000 });
+        return out.trim() || null;
+    }
+    catch {
+        return null; // ps exits 1 when no such process
+    }
+}
+export class RemoteTunnels {
+    entries = new Map();
+    deps;
+    backoff;
+    closed = false;
+    constructor(deps) {
+        this.deps = deps;
+        this.backoff = deps.backoff ?? { baseMs: 1_000, maxMs: 60_000, stableMs: 60_000 };
+    }
+    now() {
+        return this.deps.now?.() ?? Date.now();
+    }
+    /**
+     * Kill ssh children a previous router left running. Only a pid whose command line is still our
+     * tunnel for that host and port is killed: a pid the OS has since given to something else is not.
+     */
+    cleanupStale() {
+        let records = [];
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.deps.pidFile, "utf8"));
+            if (Array.isArray(parsed.tunnels))
+                records = parsed.tunnels.filter((r) => !!r && typeof r.pid === "number" && typeof r.host === "string" && typeof r.port === "number");
+        }
+        catch {
+            return 0;
+        }
+        const lookup = this.deps.processCommand ?? defaultProcessCommand;
+        const kill = this.deps.kill ?? ((pid) => process.kill(pid, "SIGTERM"));
+        let killed = 0;
+        for (const r of records) {
+            if (r.pid === process.pid)
+                continue;
+            const cmd = lookup(r.pid);
+            if (!cmd || !/\bssh(\.exe)?\b/i.test(cmd) || !cmd.includes(`127.0.0.1:${r.port}:`) || !cmd.includes(r.host))
+                continue;
+            try {
+                kill(r.pid);
+                killed++;
+                this.deps.log.info(`remote ${r.host}: killed tunnel pid ${r.pid} left by a previous router`);
+            }
+            catch (e) {
+                this.deps.log.warn(`remote ${r.host}: cannot kill stale tunnel pid ${r.pid}: ${e.message}`);
+            }
+        }
+        this.writePids();
+        return killed;
+    }
+    /** Start tunnels for new hosts, stop removed ones, restart one whose port or target changed. */
+    reconcile(hosts) {
+        if (this.closed)
+            return;
+        const target = this.deps.proxyTarget();
+        const wanted = new Map(hosts.map((h) => [h.host, h]));
+        for (const [host, entry] of this.entries) {
+            const want = wanted.get(host);
+            if (!want || want.port !== entry.port || entry.target.host !== target.host || entry.target.port !== target.port) {
+                this.stop(entry);
+                this.entries.delete(host);
+                this.deps.log.info(`remote ${host}: tunnel stopped${want ? " (port changed)" : " (host removed)"}`);
+            }
+        }
+        for (const h of hosts) {
+            if (this.entries.has(h.host))
+                continue;
+            const entry = {
+                host: h.host, port: h.port, target, child: null, state: "starting", since: this.now(), upAt: null, lastError: null,
+                attempt: 0, restarts: 0, timer: null, settle: null, stopped: false, synced: null, syncedPrint: null, syncing: false,
+            };
+            this.entries.set(h.host, entry);
+            this.start(entry);
+        }
+        this.writePids();
+    }
+    status() {
+        return [...this.entries.values()].map((e) => ({
+            host: e.host,
+            port: e.port,
+            state: e.state,
+            since: new Date(e.since).toISOString(),
+            lastError: e.lastError,
+            pid: e.child?.pid ?? null,
+            restarts: e.restarts,
+            synced: e.synced === null ? null : new Date(e.synced).toISOString(),
+        }));
+    }
+    /** The agent files or the CA changed here: copy them to every host whose tunnel is up. */
+    assetsChanged() {
+        if (!this.deps.fingerprint)
+            return;
+        const print = this.deps.fingerprint();
+        for (const e of this.entries.values())
+            if (e.state === "up" && e.syncedPrint !== print)
+                void this.sync(e);
+    }
+    /** Kill every tunnel. Synchronous, so it can run from an `exit` handler. */
+    stopAll() {
+        this.closed = true;
+        for (const e of this.entries.values())
+            this.stop(e);
+        this.entries.clear();
+        this.writePids();
+    }
+    setState(e, state) {
+        if (e.state !== state)
+            e.since = this.now();
+        e.state = state;
+    }
+    start(e) {
+        if (e.stopped || this.closed)
+            return;
+        e.timer = null;
+        this.setState(e, "starting");
+        let child;
+        try {
+            child = (this.deps.spawn ?? ((cmd, args) => spawn(cmd, args, { stdio: ["ignore", "ignore", "pipe"], windowsHide: true })))(sshExecutable(), tunnelArgs(e.host, e.port, e.target));
+        }
+        catch (err) {
+            this.gone(e, null, err.message);
+            return;
+        }
+        e.child = child;
+        this.writePids();
+        this.deps.log.info(`remote ${e.host}: starting tunnel 127.0.0.1:${e.port} on the host → ${e.target.host}:${e.target.port}${child.pid ? ` (pid ${child.pid})` : ""}`);
+        let buffered = "";
+        let said = null; // this child's own last word, not an earlier one's
+        child.stderr?.on("data", (d) => {
+            buffered += d.toString();
+            let i;
+            while ((i = buffered.indexOf("\n")) >= 0) {
+                const line = buffered.slice(0, i).replace(/\r$/, "");
+                buffered = buffered.slice(i + 1);
+                if (e.child === child)
+                    said = this.stderrLine(e, line) ?? said;
+            }
+        });
+        child.on("error", (err) => {
+            if (e.child !== child)
+                return;
+            this.gone(e, child, err.code === "ENOENT" ? SSH_MISSING : err.message, err.code === "ENOENT");
+        });
+        // `close`, not `exit`: it comes after stderr has been read to the end, so the reason ssh gave
+        // for leaving is in `said` by then.
+        child.on("close", (code, signal) => {
+            if (e.child !== child)
+                return;
+            this.gone(e, child, said ?? `ssh exited (${signal ?? `code ${code}`})`);
+        });
+        const settleMs = this.deps.settleMs ?? 15_000;
+        e.settle = setTimeout(() => {
+            if (e.child === child && e.state === "starting")
+                this.up(e);
+        }, settleMs);
+        e.settle.unref?.();
+    }
+    /** Returns the line when it is something ssh said to a person (an error, a warning). */
+    stderrLine(e, line) {
+        if (!line.trim())
+            return null;
+        if (/^debug\d?: remote forward success for: listen/.test(line)) {
+            this.up(e);
+            return null;
+        }
+        if (/^debug\d?:/.test(line))
+            return null; // `-v` noise
+        // `-v` also lets through ssh's verbose-level notices, which carry no prefix (measured: the
+        // "Authenticated to … using "publickey"" line on every connect). They are not errors.
+        if (/^(Authenticated to |Transferred: |Bytes per second|Warning: Permanently added )/.test(line)) {
+            this.deps.log.info(`remote ${e.host}: ${line.trim()}`);
+            return null;
+        }
+        e.lastError = line.trim();
+        this.deps.log.warn(`remote ${e.host}: ${line.trim()}`);
+        return line.trim();
+    }
+    up(e) {
+        if (e.state === "up")
+            return;
+        if (e.settle)
+            clearTimeout(e.settle);
+        e.settle = null;
+        this.setState(e, "up");
+        e.upAt = this.now();
+        e.lastError = null;
+        this.deps.log.info(`remote ${e.host}: tunnel up (127.0.0.1:${e.port} on the host)`);
+        // Each (re)start copies again: the host may have lost or changed the files while we were away.
+        e.syncedPrint = null;
+        void this.sync(e);
+    }
+    async sync(e) {
+        if (!this.deps.sync || e.syncing)
+            return;
+        e.syncing = true;
+        const print = this.deps.fingerprint?.() ?? null;
+        try {
+            await this.deps.sync(e.host);
+            e.synced = this.now();
+            e.syncedPrint = print;
+            this.deps.log.info(`remote ${e.host}: CA and agent files synced`);
+        }
+        catch (err) {
+            this.deps.log.warn(`remote ${e.host}: sync failed: ${err.message}`);
+        }
+        finally {
+            e.syncing = false;
+        }
+        // Something changed while this one ran: catch up once.
+        if (this.deps.fingerprint && e.state === "up" && e.syncedPrint !== null && this.deps.fingerprint() !== e.syncedPrint)
+            void this.sync(e);
+    }
+    gone(e, child, reason, sshMissing = false) {
+        if (child && e.child !== child)
+            return;
+        e.child = null;
+        if (e.settle)
+            clearTimeout(e.settle);
+        e.settle = null;
+        this.writePids();
+        if (e.stopped || this.closed) {
+            this.setState(e, "down");
+            return;
+        }
+        if (e.upAt !== null && this.now() - e.upAt >= this.backoff.stableMs)
+            e.attempt = 0;
+        e.upAt = null;
+        e.lastError = reason;
+        const delay = sshMissing ? this.backoff.maxMs : Math.min(this.backoff.maxMs, this.backoff.baseMs * 2 ** e.attempt);
+        e.attempt++;
+        this.setState(e, sshMissing ? "down" : "backoff");
+        this.deps.log.warn(`remote ${e.host}: tunnel ${sshMissing ? "cannot start" : "down"}: ${reason}; retrying in ${Math.round(delay / 1000)}s`);
+        e.timer = setTimeout(() => {
+            e.restarts++;
+            this.start(e);
+        }, delay);
+        e.timer.unref?.();
+    }
+    stop(e) {
+        e.stopped = true;
+        if (e.timer)
+            clearTimeout(e.timer);
+        if (e.settle)
+            clearTimeout(e.settle);
+        e.timer = e.settle = null;
+        const child = e.child;
+        e.child = null;
+        this.setState(e, "down");
+        if (child) {
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                /* already gone */
+            }
+        }
+    }
+    writePids() {
+        const tunnels = [];
+        for (const e of this.entries.values())
+            if (e.child?.pid)
+                tunnels.push({ pid: e.child.pid, host: e.host, port: e.port });
+        if (tunnels.length === 0 && !fs.existsSync(this.deps.pidFile))
+            return; // a router with no remote hosts leaves no file
+        try {
+            fs.mkdirSync(path.dirname(this.deps.pidFile), { recursive: true });
+            fs.writeFileSync(this.deps.pidFile, JSON.stringify({ tunnels }, null, 2) + "\n");
+        }
+        catch (err) {
+            this.deps.log.warn(`remote: cannot record tunnel pids in ${this.deps.pidFile}: ${err.message}`);
+        }
+    }
+}

package/dist/router/src/requestlog.js

@@ -2,11 +2,9 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import zlib from "node:zlib";
 import path from "node:path";
+import { UsageHistory, addTotals, emptyTotals, finishTotals, recordTotals, sortByVolume } from "./usage-history.js";
 const DEFAULT_MAX_BYTES = 20 * 1024 * 1024;
 const MAX_CARRY = 64 * 1024;
-function emptyBucket() {
-    return { count: 0, ok: 0, failed: 0, input: 0, cached: 0, cacheWrite: 0, output: 0, cacheHitPercent: 0, avgMs: 0 };
-}
 function isRecord(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -21,13 +19,29 @@ export class RequestLog {
     max;
     maxBytes;
     records;
+    history;
     constructor(file, max = 2000, maxBytes = DEFAULT_MAX_BYTES) {
         this.file = file;
         this.max = max;
         this.maxBytes = maxBytes;
-        this.records = this.load();
+        const persisted = this.readRecords(this.file);
+        this.records = persisted.slice(-this.max);
+        this.history = new UsageHistory(path.join(path.dirname(file), "usage-hourly.jsonl"));
+        // Replay what the history has not seen yet: the `.1` file first when it may hold a record above
+        // the watermark, so the first run backfills both files. Its mtime is its last append, and a
+        // record starts before it is written, so an mtime at or below the watermark hour rules it out;
+        // the first record of requests.jsonl does not, since a long request that straddled the rotation
+        // starts earlier than records left in `.1`. The history skips everything at or below its
+        // watermark, so a restart counts no hour twice.
+        const watermark = this.history.watermark;
+        const rotatedHour = usageHourOfFile(`${file}.1`);
+        const replay = rotatedHour !== null && (watermark === null || rotatedHour > watermark)
+            ? [...this.readRecords(`${file}.1`), ...persisted]
+            : persisted;
+        this.history.replay(replay);
     }
     add(record) {
+        this.history.add(record);
         this.records.push(record);
         if (this.records.length > this.max)
             this.records.splice(0, this.records.length - this.max);
@@ -64,47 +78,34 @@ export class RequestLog {
     }
     /** Summarise records at or after an epoch timestamp in milliseconds. */
     summary(sinceMs) {
-        const total = emptyBucket();
-        const providers = {};
-        const cacheBases = new Map();
-        const add = (bucket, record) => {
-            bucket.count++;
-            if (record.ok)
-                bucket.ok++;
-            else if (!record.resent)
-                bucket.failed++;
-            bucket.avgMs += record.ms;
-            if (record.usage) {
-                bucket.input += record.usage.input;
-                bucket.cached += record.usage.cached;
-                bucket.cacheWrite += record.usage.cacheWrite ?? 0;
-                bucket.output += record.usage.output;
-                // A cache write is input the model read fresh, so it counts against the hit rate. Leaving it
-                // out read a turn that wrote 2,218 tokens and uncached 2 as a 100% hit (2026-09-23).
-                cacheBases.set(bucket, (cacheBases.get(bucket) ?? 0) + record.usage.input + record.usage.cached + (record.usage.cacheWrite ?? 0));
-            }
-        };
+        const total = emptyTotals();
+        const providers = new Map();
+        const models = new Map();
         for (const record of this.records) {
             const at = Date.parse(record.at);
             if (!Number.isFinite(at) || at < sinceMs)
                 continue;
-            const provider = providers[record.provider] ?? (providers[record.provider] = emptyBucket());
-            add(total, record);
-            add(provider, record);
+            const provider = providers.get(record.provider) ?? providers.set(record.provider, emptyTotals()).get(record.provider);
+            const key = `${record.provider}\u0000${record.target}`;
+            const model = models.get(key) ?? models.set(key, { totals: emptyTotals(), provider: record.provider, model: record.target }).get(key);
+            for (const bucket of [total, provider, model.totals])
+                addTotals(bucket, recordTotals(record));
         }
-        for (const bucket of [total, ...Object.values(providers)]) {
-            if (bucket.count > 0)
-                bucket.avgMs = Math.round(bucket.avgMs / bucket.count);
-            const base = cacheBases.get(bucket) ?? 0;
-            bucket.cacheHitPercent = base > 0 ? Math.round((bucket.cached / base) * 1000) / 10 : 0;
-        }
-        return { total, providers };
+        const modelsList = [...models.values()].map(({ totals, provider, model }) => ({ ...finishTotals(totals), provider, model }));
+        sortByVolume(modelsList);
+        return {
+            total: finishTotals(total),
+            providers: Object.fromEntries([...providers].map(([name, totals]) => [name, finishTotals(totals)])),
+            models: modelsList,
+        };
+    }
+    /** Durable hourly usage over [fromMs, toMs), beyond the in-memory ring. */
+    usage(fromMs, toMs) {
+        return this.history.summary(fromMs, toMs);
     }
-    load() {
+    readRecords(file) {
         try {
-            if (!fs.existsSync(this.file))
-                return [];
-            const records = fs.readFileSync(this.file, "utf8")
+            return fs.readFileSync(file, "utf8")
                 .split("\n")
                 .flatMap((line) => {
                 try {
@@ -115,13 +116,21 @@ export class RequestLog {
                     return [];
                 }
             });
-            return records.slice(-this.max);
         }
         catch {
             return [];
         }
     }
 }
+/** The hour of a file's last write, or null when it does not exist. */
+function usageHourOfFile(file) {
+    try {
+        return Math.floor(fs.statSync(file).mtimeMs / 3_600_000);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Observes an Anthropic-compatible response without retaining or modifying its bytes.
  * Call feed() after forwarding each response chunk, then finish() on response end.

package/dist/router/src/thinking.js

@@ -1,16 +1,27 @@
 // Thinking blocks another model left in a conversation that is now going to Anthropic.
 //
-// The translated providers hand the CLI their reasoning as `thinking` blocks with no signature —
-// there is no Anthropic signature to give — and an empty `thinking` when the upstream sent a
-// reasoning item without a summary. The CLI keeps them in the transcript, so a session switched
-// from such a model to a Claude model replays them, and Anthropic refuses the whole request:
-// "messages.2.content.0.thinking: each thinking block must contain thinking" (measured 2026-09-28,
-// gpt-6-astra → claude-opus-5-5, every retry of the turn). A block Anthropic wrote always carries a
-// signature, so an unsigned one is foreign and goes; the translated providers drop thinking from
-// replayed history for the same reason (ARCHITECTURE §4, "Cache-safety decisions").
+// The translated providers hand the CLI their reasoning as `thinking` blocks, and an empty `thinking`
+// when the upstream sent a reasoning item without a summary. The CLI keeps them in the transcript, so
+// a session switched from such a model to a Claude model replays them, and Anthropic refuses the
+// whole request: "messages.2.content.0.thinking: each thinking block must contain thinking" (measured
+// 2026-09-28, gpt-6-astra → claude-opus-5-5, every retry of the turn).
+//
+// A block Anthropic wrote always carries a signature of Anthropic's own, a base64 string this router
+// cannot produce. A translation provider cannot produce one either, so it signs with an envelope of
+// its own naming where the reasoning came from (reasoning.ts) — which Anthropic would refuse just as
+// fast, and which is why those go too. What is left that is signed is Anthropic's.
+//
+// The translated adapters themselves keep their own replayed reasoning (that is the point of the
+// envelope), so this is the one place a translated provider's thinking must still be dropped: a
+// CLI-side switch to a Claude model. Gemini and the other translators drop `thinking` on their own.
+import { isOurSignature } from "./reasoning.js";
 function foreign(block) {
     const b = block;
-    return !!b && typeof b === "object" && b.type === "thinking" && !(typeof b.signature === "string" && b.signature.length > 0);
+    if (!b || typeof b !== "object" || b.type !== "thinking")
+        return false;
+    // Unsigned: a translated provider's reasoning with nothing to carry, or an empty reasoning item.
+    // Ours: a translated provider's envelope, which only its own adapter can read back.
+    return !(typeof b.signature === "string" && b.signature.length > 0) || isOurSignature(b.signature);
 }
 /**
  * Removes unsigned thinking blocks from assistant turns, in place, and returns how many went.