clauderipple 0.2.0

package/dist/router/src/bootstrap.js

@@ -0,0 +1,80 @@
+// The CLI fetches /api/claude_cli/bootstrap once per session. Two fields matter to us:
+//   additional_model_options  → the CLI's own /model list (NOT the app picker; docs/ARCHITECTURE.md §3)
+//   auto_compact_windows      → per-model compaction thresholds; routed models are unknown to the CLI
+//                               and would otherwise fall back to 200K.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const BOOTSTRAP_PATH = "/api/claude_cli/bootstrap";
+/**
+ * Model ids named in the user's agent definitions (~/.claude/agents/*.md frontmatter `model:`),
+ * e.g. `gpt-5.6-terra@high`. The CLI only accepts ids it saw in its bootstrap list; an agent whose
+ * model id is unknown silently runs on the parent session's Claude model (measured 2026-09-13 after
+ * the picker ids lost their `@effort` suffix). Any such id whose base is routable is injected too.
+ */
+export function agentModelIds(dirs = [path.join(os.homedir(), ".claude", "agents")]) {
+    const out = new Set();
+    for (const dir of dirs) {
+        let files;
+        try {
+            files = fs.readdirSync(dir).filter((f) => f.endsWith(".md"));
+        }
+        catch {
+            continue;
+        }
+        for (const f of files) {
+            try {
+                const head = fs.readFileSync(path.join(dir, f), "utf8").slice(0, 8192);
+                const m = /^model:\s*['"]?([A-Za-z0-9._\/:\-]+(?:@[a-z]+)?)/m.exec(head);
+                if (m)
+                    out.add(m[1]);
+            }
+            catch {
+                /* unreadable: skip */
+            }
+        }
+    }
+    return [...out];
+}
+function routable(id, cfg) {
+    const base = id.split("@")[0];
+    if (cfg.cli.extraModels.some((m) => m.model === base))
+        return true;
+    if (cfg.routes[base] || cfg.aliases[base])
+        return true;
+    return cfg.direct.some((d) => base.startsWith(d.prefix));
+}
+export function injectBootstrap(body, cfg, agentDirs) {
+    const known = new Set(cfg.cli.extraModels.map((m) => m.model));
+    const fromAgents = agentModelIds(agentDirs)
+        .filter((id) => !known.has(id) && routable(id, cfg))
+        .map((id) => {
+        const [base, effort] = id.split("@");
+        const named = cfg.cli.extraModels.find((m) => m.model === base);
+        return { model: id, name: `${named?.name ?? base}${effort ? ` · ${effort}` : ""}` };
+    });
+    const extra = [...cfg.cli.extraModels, ...fromAgents];
+    const win = cfg.cli.autoCompactWindow;
+    if (extra.length === 0 && !win)
+        return body;
+    let j;
+    try {
+        j = JSON.parse(body.toString("utf8"));
+    }
+    catch {
+        return body;
+    }
+    if (extra.length > 0) {
+        const existing = Array.isArray(j.additional_model_options) ? j.additional_model_options : [];
+        j.additional_model_options = [...existing, ...extra];
+    }
+    if (win) {
+        const acw = { ...(j.auto_compact_windows ?? {}) };
+        for (const m of extra)
+            acw[m.model] = win;
+        for (const alias of Object.keys(cfg.routes))
+            acw[alias] = win;
+        j.auto_compact_windows = acw;
+    }
+    return Buffer.from(JSON.stringify(j));
+}

package/dist/router/src/certs.js

@@ -0,0 +1,65 @@
+// Per-host leaf certificates minted at runtime from the local CA (picker mode terminates
+// claude.ai in addition to api.anthropic.com). Pure node:crypto like the installer, so no
+// openssl binary is needed; results are cached in <home>/certs/<host>.pem|key and reused
+// across restarts.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import tls from "node:tls";
+import { createLeaf } from "./x509.js";
+export class CertStore {
+    home;
+    contexts = new Map();
+    constructor(home) {
+        this.home = home;
+    }
+    /** Context for `host`; mints a leaf on first use. Throws if the CA key is missing. */
+    contextFor(host) {
+        const cached = this.contexts.get(host);
+        if (cached)
+            return cached;
+        const { cert, key } = this.leafFor(host);
+        const ctx = tls.createSecureContext({ cert, key });
+        this.contexts.set(host, ctx);
+        return ctx;
+    }
+    /** Register a pre-existing leaf (the installer's api.anthropic.com leaf). */
+    register(host, certPem, keyPem) {
+        this.contexts.set(host, tls.createSecureContext({ cert: certPem, key: keyPem }));
+    }
+    has(host) {
+        return this.contexts.has(host);
+    }
+    leafFor(host) {
+        if (!/^[a-z0-9.-]+$/i.test(host))
+            throw new Error(`refusing to mint a certificate for "${host}"`);
+        const dir = path.join(this.home, "certs");
+        const certFile = path.join(dir, `${host}.pem`);
+        const keyFile = path.join(dir, `${host}.key`);
+        if (fs.existsSync(certFile) && fs.existsSync(keyFile)) {
+            const cert = fs.readFileSync(certFile);
+            // re-mint when within 30 days of expiry
+            try {
+                const notAfter = new crypto.X509Certificate(cert).validTo;
+                if (Date.parse(notAfter) - Date.now() > 30 * 86400_000)
+                    return { cert, key: fs.readFileSync(keyFile) };
+            }
+            catch {
+                /* unparseable cache entry: fall through and mint a fresh one */
+            }
+        }
+        const caPem = path.join(this.home, "ca.pem");
+        const caKey = path.join(this.home, "ca.key");
+        if (!fs.existsSync(caKey))
+            throw new Error(`CA key missing (${caKey}); re-run the installer`);
+        fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const leaf = createLeaf({
+            host,
+            caCertPem: fs.readFileSync(caPem, "utf8"),
+            caKeyPem: fs.readFileSync(caKey, "utf8"),
+        });
+        fs.writeFileSync(certFile, leaf.certPem);
+        fs.writeFileSync(keyFile, leaf.keyPem, { mode: 0o600 });
+        return { cert: Buffer.from(leaf.certPem), key: Buffer.from(leaf.keyPem) };
+    }
+}

package/dist/router/src/compat.js

@@ -0,0 +1,172 @@
+// Sanitise Claude Code's Anthropic-only request extensions for providers that expose
+// an Anthropic-shaped Messages endpoint without implementing Anthropic's full feature set.
+// Pure: callers receive a new object and an audit list; the input is never mutated.
+export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max", "ultra"];
+export const STRICT_COMPAT_CAPS = {
+    effortLevels: [],
+    thinking: "none",
+    betas: false,
+    cacheControl: true,
+};
+export function resolveCompatibleCaps(preset, override) {
+    return {
+        effortLevels: [...(override?.effortLevels ?? preset?.effortLevels ?? STRICT_COMPAT_CAPS.effortLevels)],
+        thinking: override?.thinking ?? preset?.thinking ?? STRICT_COMPAT_CAPS.thinking,
+        betas: override?.betas ?? preset?.betas ?? STRICT_COMPAT_CAPS.betas,
+        cacheControl: override?.cacheControl ?? preset?.cacheControl ?? STRICT_COMPAT_CAPS.cacheControl,
+    };
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+/** `anthropic-version` stays intact; only unsupported beta flags are removed. */
+export function forwardCompatibleHeader(name, caps) {
+    return name.toLowerCase() !== "anthropic-beta" || caps.betas;
+}
+/**
+ * Return the nearest supported canonical effort level. Unknown requested levels fall back
+ * to the provider's lowest listed level, which is safer than forwarding a rejected value.
+ */
+export function clampEffort(effort, supported) {
+    if (supported.includes(effort))
+        return effort;
+    const requested = EFFORT_LEVELS.indexOf(effort);
+    const canonical = supported
+        .map((value) => ({ value, index: EFFORT_LEVELS.indexOf(value) }))
+        .filter((entry) => entry.index >= 0);
+    if (requested < 0 || canonical.length === 0)
+        return supported[0] ?? effort;
+    return canonical.reduce((best, candidate) => Math.abs(candidate.index - requested) < Math.abs(best.index - requested) ? candidate : best).value;
+}
+function stripCacheControl(value) {
+    if (Array.isArray(value)) {
+        let count = 0;
+        const out = value.map((item) => {
+            const next = stripCacheControl(item);
+            count += next.count;
+            return next.value;
+        });
+        return { value: out, count };
+    }
+    const source = record(value);
+    if (!source)
+        return { value, count: 0 };
+    let count = 0;
+    const out = {};
+    for (const [key, child] of Object.entries(source)) {
+        if (key === "cache_control") {
+            count++;
+            continue;
+        }
+        const next = stripCacheControl(child);
+        out[key] = next.value;
+        count += next.count;
+    }
+    return { value: out, count };
+}
+/**
+ * Remove extensions Claude Code sends only to Anthropic. This deliberately retains content
+ * verbatim except cache_control when the provider explicitly rejects prompt caching.
+ */
+export function sanitizeForCompatible(json, caps) {
+    const out = { ...json };
+    const changes = [];
+    const thinking = record(out.thinking);
+    if (thinking) {
+        if (thinking.type === "adaptive") {
+            if (caps.thinking === "enabled") {
+                out.thinking = { type: "enabled", budget_tokens: 8192 };
+                changes.push("thinking adaptive→enabled");
+            }
+            else {
+                delete out.thinking;
+                changes.push("thinking");
+            }
+        }
+        else {
+            const next = { ...thinking };
+            let removed = false;
+            for (const key of ["block_binding", "display"]) {
+                if (key in next) {
+                    delete next[key];
+                    removed = true;
+                }
+            }
+            if (removed) {
+                out.thinking = next;
+                changes.push("thinking");
+            }
+        }
+    }
+    for (const key of ["context_management", "container", "thread", "diagnostics"]) {
+        if (key in out) {
+            delete out[key];
+            changes.push(key);
+        }
+    }
+    const outputConfig = record(out.output_config);
+    if (outputConfig) {
+        const effort = typeof outputConfig.effort === "string" ? outputConfig.effort : undefined;
+        if (!effort || caps.effortLevels.length === 0) {
+            delete out.output_config;
+            changes.push(effort ? `effort ${effort}→removed` : "output_config");
+        }
+        else {
+            const clamped = clampEffort(effort, caps.effortLevels);
+            out.output_config = { effort: clamped };
+            if (clamped !== effort)
+                changes.push(`effort ${effort}→${clamped}`);
+            else if (Object.keys(outputConfig).length !== 1)
+                changes.push("output_config");
+        }
+    }
+    if (Array.isArray(out.tools)) {
+        const kept = [];
+        const droppedNames = new Set();
+        let deferred = 0;
+        let dropped = 0;
+        for (const tool of out.tools) {
+            const source = record(tool);
+            if (!source) {
+                kept.push(tool);
+                continue;
+            }
+            if (source.type !== undefined && source.type !== "custom") {
+                dropped++;
+                if (typeof source.name === "string")
+                    droppedNames.add(source.name);
+                continue;
+            }
+            const next = { ...source };
+            if ("defer_loading" in next) {
+                delete next.defer_loading;
+                deferred++;
+            }
+            kept.push(next);
+        }
+        if (deferred > 0)
+            changes.push(`defer_loading×${deferred}`);
+        if (dropped > 0)
+            changes.push(`server_tools×${dropped}`);
+        if (deferred > 0 || dropped > 0)
+            out.tools = kept;
+        const toolChoice = record(out.tool_choice);
+        if (toolChoice && typeof toolChoice.name === "string" && droppedNames.has(toolChoice.name)) {
+            delete out.tool_choice;
+            changes.push("tool_choice");
+        }
+    }
+    if (!caps.cacheControl) {
+        let removed = 0;
+        for (const key of ["system", "messages"]) {
+            if (!(key in out))
+                continue;
+            const next = stripCacheControl(out[key]);
+            out[key] = next.value;
+            removed += next.count;
+        }
+        if (removed > 0)
+            changes.push(`cache_control×${removed}`);
+    }
+    return { json: out, changes };
+}

package/dist/router/src/config.js

@@ -0,0 +1,179 @@
+// Configuration: one JSON file, hot-reloaded on mtime change.
+// Home directory layout (default ~/.clauderipple):
+//   config.json   this file
+//   ca.pem ca.key leaf.pem leaf.key   generated by the installer
+//   logs/router.log (+ rotated .1 .2 ...)
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const PICKER_HOSTS_DEFAULT = ["claude.ai"];
+export function terminateHosts(c) {
+    const hosts = [c.upstream];
+    if (c.picker?.enabled)
+        hosts.push(...(c.picker.hosts ?? PICKER_HOSTS_DEFAULT));
+    return hosts;
+}
+export const DEFAULTS = {
+    listen: { host: "127.0.0.1", port: 8790 },
+    upstream: "api.anthropic.com",
+    providers: {},
+    routes: {},
+    direct: [],
+    aliases: {},
+    effortClamp: { ultra: "max" },
+    cli: { extraModels: [] },
+    health: { maxConsecutiveUpstreamFailures: 20 },
+    log: { maxBytes: 5 * 1024 * 1024, keep: 3 },
+};
+export function homeDir() {
+    return process.env.CLAUDERIPPLE_HOME ?? path.join(os.homedir(), ".clauderipple");
+}
+export function configPath() {
+    return path.join(homeDir(), "config.json");
+}
+function merge(base, over) {
+    return {
+        ...base,
+        ...over,
+        listen: { ...base.listen, ...(over.listen ?? {}) },
+        cli: { ...base.cli, ...(over.cli ?? {}) },
+        health: { ...base.health, ...(over.health ?? {}) },
+        log: { ...base.log, ...(over.log ?? {}) },
+        effortClamp: { ...base.effortClamp, ...(over.effortClamp ?? {}) },
+        ...((over.admin ?? base.admin) ? { admin: over.admin ?? base.admin } : {}),
+        ...(over.picker ? { picker: { ...over.picker } } : {}),
+    };
+}
+function validModels(models) {
+    return Array.isArray(models) && models.every((model) => model !== null && typeof model === "object" &&
+        typeof model.id === "string" &&
+        (model.name === undefined || typeof model.name === "string") &&
+        (model.effortLevels === undefined ||
+            (Array.isArray(model.effortLevels) && model.effortLevels.every((level) => typeof level === "string"))));
+}
+export function validate(c) {
+    const errors = [];
+    for (const [alias, r] of Object.entries(c.routes)) {
+        if (!c.providers[r.provider])
+            errors.push(`route ${alias}: unknown provider "${r.provider}"`);
+        if (!r.model)
+            errors.push(`route ${alias}: missing model`);
+    }
+    for (const d of c.direct) {
+        if (!c.providers[d.provider])
+            errors.push(`direct ${d.prefix}: unknown provider "${d.provider}"`);
+    }
+    for (const [name, p] of Object.entries(c.providers)) {
+        // Carried by every provider that puts together a system prompt, so checked once for all of them.
+        const shared = p;
+        if (shared.identity !== undefined && typeof shared.identity !== "boolean")
+            errors.push(`provider ${name}: identity must be true or false`);
+        if (shared.instructionsAppend !== undefined && typeof shared.instructionsAppend !== "string")
+            errors.push(`provider ${name}: instructionsAppend must be a string`);
+        if (p.type === "anthropic-compatible") {
+            if (!/^https?:\/\//.test(p.url))
+                errors.push(`provider ${name}: url must start with http:// or https://`);
+            if (p.preset !== undefined && typeof p.preset !== "string")
+                errors.push(`provider ${name}: preset must be a string`);
+            if (p.models !== undefined && !validModels(p.models)) {
+                errors.push(`provider ${name}: models must be entries with string id, optional string name, and optional string[] effortLevels`);
+            }
+            if (p.caps !== undefined) {
+                const caps = p.caps;
+                if (!caps || typeof caps !== "object" || Array.isArray(caps) ||
+                    (caps.effortLevels !== undefined && (!Array.isArray(caps.effortLevels) || caps.effortLevels.some((level) => typeof level !== "string"))) ||
+                    (caps.thinking !== undefined && caps.thinking !== "enabled" && caps.thinking !== "none") ||
+                    (caps.betas !== undefined && typeof caps.betas !== "boolean") ||
+                    (caps.cacheControl !== undefined && typeof caps.cacheControl !== "boolean")) {
+                    errors.push(`provider ${name}: caps must contain effortLevels?: string[], thinking?: "enabled"|"none", betas?: boolean, cacheControl?: boolean`);
+                }
+            }
+        }
+        else if (p.type === "chatgpt") {
+            if (p.models !== undefined && !validModels(p.models)) {
+                errors.push(`provider ${name}: models must be entries with string id, optional string name, and optional string[] effortLevels`);
+            }
+            if (p.url && !/^https?:\/\//.test(p.url))
+                errors.push(`provider ${name}: url must start with http:// or https://`);
+        }
+        else if (p.type === "openai-compatible") {
+            if (!/^https?:\/\//.test(p.url))
+                errors.push(`provider ${name}: url must start with http:// or https://`);
+            if (p.wire !== undefined && p.wire !== "chat" && p.wire !== "responses")
+                errors.push(`provider ${name}: wire must be "chat" or "responses"`);
+            if (p.preset !== undefined && typeof p.preset !== "string")
+                errors.push(`provider ${name}: preset must be a string`);
+            if (p.headers !== undefined && (!p.headers || typeof p.headers !== "object" || Array.isArray(p.headers) || Object.values(p.headers).some((value) => typeof value !== "string"))) {
+                errors.push(`provider ${name}: headers must be a string record`);
+            }
+            if (p.models !== undefined && !validModels(p.models)) {
+                errors.push(`provider ${name}: models must be entries with string id, optional string name, and optional string[] effortLevels`);
+            }
+            if (p.caps !== undefined && (!p.caps || typeof p.caps !== "object" || Array.isArray(p.caps) ||
+                (p.caps.effortLevels !== undefined && (!Array.isArray(p.caps.effortLevels) || p.caps.effortLevels.some((level) => typeof level !== "string"))) ||
+                (p.caps.reasoning !== undefined && p.caps.reasoning !== "effort" && p.caps.reasoning !== "none"))) {
+                errors.push(`provider ${name}: caps must contain effortLevels?: string[], reasoning?: "effort"|"none"`);
+            }
+        }
+        else if (p.type === "anthropic") {
+            if (p.auth !== "api-key" && p.auth !== "claude-code")
+                errors.push(`provider ${name}: auth must be "api-key" or "claude-code"`);
+            if (p.apiKey !== undefined && typeof p.apiKey !== "string")
+                errors.push(`provider ${name}: apiKey must be a string`);
+            if (p.models !== undefined && !validModels(p.models)) {
+                errors.push(`provider ${name}: models must be entries with string id, optional string name, and optional string[] effortLevels`);
+            }
+        }
+        else {
+            errors.push(`provider ${name}: unknown type "${p.type}"`);
+        }
+    }
+    if (!(c.listen.port > 0 && c.listen.port < 65536))
+        errors.push("listen.port out of range");
+    if (c.listen.openaiPort !== undefined && !(c.listen.openaiPort >= 0 && c.listen.openaiPort < 65536))
+        errors.push("listen.openaiPort out of range");
+    return errors;
+}
+export class ConfigStore {
+    current = DEFAULTS;
+    mtimeMs = -1;
+    file;
+    onChange;
+    constructor(file = configPath(), onChange) {
+        this.file = file;
+        this.onChange = onChange;
+        this.reload(true);
+    }
+    /** Cheap: one stat per call. Called per request. */
+    get() {
+        this.reload(false);
+        return this.current;
+    }
+    reload(initial) {
+        let st;
+        try {
+            st = fs.statSync(this.file);
+        }
+        catch {
+            if (initial)
+                this.onChange?.(this.current, [`no config at ${this.file}; using defaults`]);
+            this.mtimeMs = -1;
+            return;
+        }
+        if (st.mtimeMs === this.mtimeMs)
+            return;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(this.file, "utf8"));
+            const next = merge(DEFAULTS, parsed);
+            const errors = validate(next);
+            if (errors.length === 0 || initial)
+                this.current = next;
+            this.mtimeMs = st.mtimeMs;
+            this.onChange?.(this.current, errors);
+        }
+        catch (e) {
+            this.mtimeMs = st.mtimeMs; // do not re-parse a broken file on every request
+            this.onChange?.(this.current, [`config parse error: ${e.message}`]);
+        }
+    }
+}

package/dist/router/src/health.js

@@ -0,0 +1,45 @@
+// Self-healing: a long-lived process whose resolver or socket layer has gone bad
+// stays bad (observed: 10h of ENOTFOUND, 11 remote-control workers lost). After N
+// consecutive upstream *connect-level* failures with no success in between, exit
+// with a distinctive code so the supervisor restarts a fresh process.
+export const EXIT_UPSTREAM_UNREACHABLE = 75;
+const CONNECT_ERRORS = new Set([
+    "ENOTFOUND",
+    "EAI_AGAIN",
+    "EAI_FAIL",
+    "ECONNREFUSED",
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "ENETDOWN",
+]);
+export function isConnectError(e) {
+    const code = e?.code;
+    return typeof code === "string" && CONNECT_ERRORS.has(code);
+}
+export class UpstreamHealth {
+    consecutive = 0;
+    tripped = false;
+    limit;
+    onTrip;
+    constructor(limit, onTrip) {
+        this.limit = limit;
+        this.onTrip = onTrip;
+    }
+    success() {
+        this.consecutive = 0;
+    }
+    failure(e) {
+        if (!isConnectError(e))
+            return;
+        this.consecutive++;
+        if (!this.tripped && this.consecutive >= this.limit()) {
+            this.tripped = true;
+            this.onTrip(this.consecutive);
+        }
+    }
+    get consecutiveFailures() {
+        return this.consecutive;
+    }
+}

package/dist/router/src/identity.js

@@ -0,0 +1,51 @@
+// A routed model reads Claude Code's system prompt, which opens with "You are Claude Code,
+// Anthropic's official CLI for Claude". Nothing else tells the model what it is, so without a line
+// of its own DeepSeek answers that it is Claude (measured 2026-09-16). This is that line, and the
+// fixed addendum that may follow the prompt, shared by every provider that can carry one.
+//
+// The text must stay constant across the turns of a session or the prompt cache misses: the
+// identity depends on the model and the effort only, both fixed for a route, and the addendum is
+// configuration. Changing either costs one cache miss.
+/** The sentence put in front of the system prompt. Effort is named because a model cannot see its own setting. */
+export function identityLine(model, effort) {
+    const reasoning = effort ? ` (reasoning effort: ${effort})` : "";
+    return `You are ${model}${reasoning}, answering through Claude Code, a terminal-based coding agent.`;
+}
+/** The identity line, when enabled, in the order it belongs: before the caller's own system text. */
+export function identityPrefix(opts) {
+    return (opts.identity ?? true) ? identityLine(opts.model, opts.effort) : null;
+}
+/** The configured addendum, trimmed, or null when there is none to add. */
+export function instructionsSuffix(opts) {
+    const text = opts.instructionsAppend?.trim();
+    return text ? text : null;
+}
+/**
+ * Wraps an Anthropic Messages body's `system` with the identity line and the addendum, in place.
+ * A string system stays a string; a block array stays an array, and the added blocks carry no
+ * cache_control of their own so the caller's breakpoints keep their meaning.
+ */
+export function applyIdentityToAnthropicBody(json, opts) {
+    const prefix = identityPrefix(opts);
+    const suffix = instructionsSuffix(opts);
+    if (!prefix && !suffix)
+        return;
+    const system = json.system;
+    if (system === undefined || system === null || system === "") {
+        json.system = [prefix, suffix].filter(Boolean).join("\n\n");
+        return;
+    }
+    if (typeof system === "string") {
+        json.system = [prefix, system, suffix].filter(Boolean).join("\n\n");
+        return;
+    }
+    if (Array.isArray(system)) {
+        const blocks = system;
+        json.system = [
+            ...(prefix ? [{ type: "text", text: prefix }] : []),
+            ...blocks,
+            ...(suffix ? [{ type: "text", text: suffix }] : []),
+        ];
+    }
+    // Any other shape is left alone: it is not something this router put together.
+}