@openlimiter/core 0.4.0 → 1.3.1

package/dist/acquire/coordination.js

@@ -0,0 +1,292 @@
+/**
+ * Who refreshes the cache, and how a terminal gets fresh bars with no daemon.
+ *
+ * Two questions live here, and they are different questions.
+ *
+ * The first is ownership. A machine running the desktop tray already has a
+ * refresher, and a status line that polls anyway doubles the traffic the
+ * provider sees for no new information. So a cache carrying a desktop write
+ * inside the last interval is a cache the command line tool leaves alone.
+ *
+ * The second is freshness without a background service. A status line render
+ * reads the cache and nothing else, and when the cache is older than a minute
+ * it starts a detached refresh under a lock and returns immediately. The render
+ * never waits for the network; the next render shows what the refresh found.
+ */
+import { randomUUID } from "node:crypto";
+import { lstat, open, readFile, unlink, utimes } from "node:fs/promises";
+import path from "node:path";
+import { readJsonFileSafely, resolveStateDirectory, writeFileAtomically } from "../cache.js";
+import { canonicalJson } from "../normalizer.js";
+import { DESKTOP_OWNERSHIP_SECONDS } from "./cadence.js";
+/**
+ * How old the cache may be before a render starts a refresh behind itself.
+ *
+ * A minute, which is the number Lucas's own status line has used for months. It
+ * is short enough that a person who opens a terminal sees current bars and long
+ * enough that a status line redrawing on every keystroke starts nothing.
+ */
+export const CACHE_REFRESH_STALE_SECONDS = 60;
+/** The lock one detached refresh holds, beside the cache lock and separate. */
+export const REFRESH_LOCK_NAME = "openlimiter-refresh.lock";
+/**
+ * How often a running refresh says it is still alive.
+ *
+ * The lock's modification time is the signal, so the heartbeat only touches the
+ * file and never rewrites it: the token inside has to stay byte for byte the
+ * same, because that token is what proves ownership at every write below.
+ */
+export const REFRESH_LOCK_HEARTBEAT_MILLISECONDS = 10_000;
+/**
+ * How long a silent lock is honoured before it is treated as abandoned.
+ *
+ * Six missed heartbeats. The bound used to be a flat two minutes measured from
+ * when the lock was TAKEN, which quietly assumed a whole round fits in two
+ * minutes; seven providers, two of them two hop, each with a fifteen second
+ * budget, does not fit, so a legitimate refresh could be declared dead and
+ * raced by the next status line render. Measuring from the last heartbeat
+ * instead means the bound is about liveness rather than about duration, and a
+ * round may take as long as it takes.
+ */
+export const REFRESH_LOCK_STALE_MILLISECONDS = 60_000;
+function errorCode(error) {
+    return error.code;
+}
+/** The newest observation in a set of rows, in epoch milliseconds, or null. */
+export function newestObservedMilliseconds(snapshots) {
+    let newest = null;
+    for (const snapshot of snapshots) {
+        const observed = Date.parse(snapshot.observedAt);
+        if (!Number.isFinite(observed))
+            continue;
+        if (newest === null || observed > newest)
+            newest = observed;
+    }
+    return newest;
+}
+/**
+ * How old the freshest row is, in seconds.
+ *
+ * An empty cache has no age, which the caller reads as "refresh": there is
+ * nothing to be stale, and nothing to show either.
+ */
+export function cacheAgeSeconds(snapshots, now) {
+    const current = Date.parse(now);
+    const newest = newestObservedMilliseconds(snapshots);
+    if (!Number.isFinite(current) || newest === null)
+        return null;
+    return (current - newest) / 1_000;
+}
+/**
+ * Whether a writer has kept this cache fresh inside the ownership window.
+ *
+ * Absent markers answer false, which is the backward compatible reading: a
+ * cache written before this field existed says nothing about who wrote it, and
+ * a reader that assumed a desktop was running would stop refreshing on a
+ * machine that has none.
+ */
+export function writerHoldsCache(snapshots, writer, now, withinSeconds = DESKTOP_OWNERSHIP_SECONDS) {
+    const current = Date.parse(now);
+    if (!Number.isFinite(current))
+        return false;
+    return snapshots.some((snapshot) => {
+        if (snapshot.writer !== writer)
+            return false;
+        const observed = Date.parse(snapshot.observedAt);
+        if (!Number.isFinite(observed))
+            return false;
+        /* A row stamped in the future is a clock disagreement, not a fresh write,
+           and treating it as ownership would silence this machine indefinitely. */
+        if (observed > current)
+            return false;
+        return current - observed <= withinSeconds * 1_000;
+    });
+}
+/** Whether a running desktop is already keeping this cache fresh. */
+export function desktopHoldsCache(snapshots, now, withinSeconds = DESKTOP_OWNERSHIP_SECONDS) {
+    return writerHoldsCache(snapshots, "desktop", now, withinSeconds);
+}
+/** Stamp rows with the process that is about to write them. */
+export function withWriter(snapshots, writer) {
+    return snapshots.map((snapshot) => ({ ...snapshot, writer }));
+}
+/**
+ * Whether this render should start a refresh behind itself.
+ *
+ * Three inputs and no side effects, so the whole policy is one testable
+ * function rather than a condition spread across two commands.
+ */
+export function shouldStartRefresh(snapshots, now, staleSeconds = CACHE_REFRESH_STALE_SECONDS) {
+    if (desktopHoldsCache(snapshots, now)) {
+        return { refresh: false, reason: "desktop_running" };
+    }
+    const age = cacheAgeSeconds(snapshots, now);
+    if (age !== null && age <= staleSeconds)
+        return { refresh: false, reason: "fresh" };
+    return { refresh: true };
+}
+/* ------------------------------------------------------------------ lock */
+function lockPath(directory) {
+    return path.join(directory, REFRESH_LOCK_NAME);
+}
+/**
+ * Whether a refresh is running right now.
+ *
+ * A lock file older than the stale bound is not a running refresh, it is a
+ * process that died, and it is reported as free so the next render can take
+ * over. Nothing is deleted here: reclaiming belongs to the acquisition below,
+ * which does it under the same create attempt that would have failed.
+ */
+export async function refreshLockHeld(directory = resolveStateDirectory(), nowMilliseconds = Date.now()) {
+    try {
+        const observed = await lstat(lockPath(directory));
+        if (!Number.isFinite(observed.mtimeMs))
+            return true;
+        return nowMilliseconds - observed.mtimeMs < REFRESH_LOCK_STALE_MILLISECONDS;
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT")
+            return false;
+        /* A lock we cannot even inspect is treated as held. Refusing to refresh is
+           recoverable; two refreshes racing on one credential is not. */
+        return true;
+    }
+}
+/**
+ * Take the refresh lock, or say why not.
+ *
+ * Exclusive creation is the whole mechanism: the operating system decides the
+ * winner, so two terminals starting a refresh in the same millisecond produce
+ * exactly one round of requests. The token inside the file is checked before
+ * the release, so a process that lost its lock to the stale reclaim cannot
+ * delete the lock its successor is holding.
+ */
+export async function acquireRefreshLock(directory = resolveStateDirectory(), nowMilliseconds = Date.now()) {
+    const target = lockPath(directory);
+    const token = JSON.stringify({ at: nowMilliseconds, id: randomUUID(), pid: process.pid });
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const handle = await open(target, "wx", 0o600);
+            try {
+                await handle.writeFile(token, "utf8");
+            }
+            finally {
+                await handle.close().catch(() => undefined);
+            }
+            const owns = async () => {
+                try {
+                    return (await readFile(target, "utf8")) === token;
+                }
+                catch {
+                    return false;
+                }
+            };
+            /*
+             * The heartbeat is unreferenced, so it can never hold the process open
+             * past the work it was watching, and it stops touching the file the
+             * moment this holder stops owning it.
+             */
+            const beat = setInterval(() => {
+                void (async () => {
+                    if (!(await owns()))
+                        return;
+                    const stamp = new Date();
+                    await utimes(target, stamp, stamp).catch(() => undefined);
+                })();
+            }, REFRESH_LOCK_HEARTBEAT_MILLISECONDS);
+            beat.unref();
+            return {
+                ok: true,
+                stillOwned: owns,
+                release: async () => {
+                    clearInterval(beat);
+                    if (!(await owns()))
+                        return;
+                    await unlink(target).catch(() => undefined);
+                }
+            };
+        }
+        catch (error) {
+            const code = errorCode(error);
+            if (code !== "EEXIST" && code !== "EPERM" && code !== "EACCES") {
+                return { ok: false, reason: "unavailable" };
+            }
+            if (attempt > 0)
+                return { ok: false, reason: "held" };
+            if (await refreshLockHeld(directory, nowMilliseconds)) {
+                return { ok: false, reason: "held" };
+            }
+            await unlink(target).catch(() => undefined);
+        }
+    }
+    return { ok: false, reason: "held" };
+}
+/* ------------------------------------------------------------ detachment */
+/** The file that remembers a refresh this machine could not start. */
+export const REFRESH_SPAWN_FAILURE_NAME = "openlimiter-refresh-spawn.json";
+/**
+ * Remember that a background refresh could not be started.
+ *
+ * A detached spawn fails asynchronously: the executable is missing, or the
+ * platform refuses, and the error arrives after the status line has already
+ * drawn and returned. There is nobody left to tell at that point, so the fact
+ * is written down instead and doctor reads it back. Best effort throughout,
+ * because a machine that cannot start a refresh may well not be able to write
+ * this either, and neither failure may break a render.
+ */
+export async function recordRefreshSpawnFailure(directory, now) {
+    await writeFileAtomically(path.join(directory, REFRESH_SPAWN_FAILURE_NAME), canonicalJson({ at: now, version: 1 })).catch(() => undefined);
+}
+/** When the last background refresh failed to start, if one did. */
+export async function readRefreshSpawnFailure(directory = resolveStateDirectory()) {
+    const document = await readJsonFileSafely(path.join(directory, REFRESH_SPAWN_FAILURE_NAME), 4_096);
+    if (!document.ok)
+        return null;
+    const value = document.value;
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return null;
+    const at = value["at"];
+    return typeof at === "string" && Number.isFinite(Date.parse(at)) ? at : null;
+}
+/** Forget it, which a refresh that actually ran is the proof of. */
+export async function clearRefreshSpawnFailure(directory = resolveStateDirectory()) {
+    await unlink(path.join(directory, REFRESH_SPAWN_FAILURE_NAME)).catch(() => undefined);
+}
+/**
+ * Start a refresh behind the caller, and never wait for it.
+ *
+ * Everything expensive happens in the child. This function creates one lock
+ * file and hands the operating system a detached process, so the render that
+ * called it returns in the time a file create takes. A failure to spawn is
+ * reported and never thrown: a status line that cannot start a refresh still
+ * has to draw the bars it already has.
+ */
+export async function spawnDetachedRefresh(options) {
+    const decision = shouldStartRefresh(options.snapshots, options.now, options.staleSeconds ?? CACHE_REFRESH_STALE_SECONDS);
+    if (!decision.refresh)
+        return { spawned: false, reason: decision.reason };
+    if (options.openLimiterScript === "")
+        return { spawned: false, reason: "no_script" };
+    const directory = options.stateDirectory ?? resolveStateDirectory();
+    /*
+     * The parent only checks the lock; the child takes it. Taking it here would
+     * mean releasing it here, and the parent exits long before the child has
+     * finished, which would leave every render starting one more refresh.
+     */
+    if (await refreshLockHeld(directory)) {
+        return { spawned: false, reason: "already_running" };
+    }
+    try {
+        options.spawn(options.nodeExecutable, [options.openLimiterScript, "refresh", "--detached"], {
+            onError: () => {
+                void recordRefreshSpawnFailure(directory, options.now);
+            }
+        });
+        return { spawned: true };
+    }
+    catch {
+        await recordRefreshSpawnFailure(directory, options.now);
+        return { spawned: false, reason: "failed" };
+    }
+}
+//# sourceMappingURL=coordination.js.map

package/dist/acquire/coordination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coordination.js","sourceRoot":"","sources":["../../src/acquire/coordination.ts"],"names":[],"mappings":"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"}

package/dist/acquire/credentials.d.ts

@@ -0,0 +1,113 @@
+/** The providers this path can read a credential for. */
+export declare const ACQUISITION_PROVIDERS: readonly ["CLAUDE", "CODEX", "GEMINI_CLI", "ANTIGRAVITY", "GROK", "KIMI", "OPENROUTER"];
+export type AcquisitionProvider = (typeof ACQUISITION_PROVIDERS)[number];
+/** Largest credential document this path will read into memory. */
+export declare const MAX_CREDENTIAL_FILE_BYTES = 65536;
+/**
+ * Why no usable credential came back.
+ *
+ * `absent` is the ordinary answer on a machine that does not run that client.
+ * `expired` is separated from `invalid` because only one of them has an action
+ * a person can take, and the row says so.
+ */
+export type CredentialFailureReason = "absent" | "unreadable" | "invalid" | "expired" | "keychain_not_read";
+/**
+ * Whose login this actually is.
+ *
+ * The one that matters is `shared_code_assist`. Antigravity keeps its token in
+ * the Windows credential store, and when that store holds nothing this reader
+ * falls back to the Gemini CLI's file, which is what the Antigravity client's
+ * own quota shares a backend with. That fallback is legitimate and it is what
+ * every other reader does, but the resulting row is NOT Antigravity's own
+ * login, and presenting it as one would tell a person they had connected
+ * something they never connected. So the origin travels with the credential and
+ * the row says which it is.
+ */
+export declare const CREDENTIAL_ORIGINS: readonly ["vendor_store", "vendor_file", "shared_code_assist", "user_key"];
+export type CredentialOrigin = (typeof CREDENTIAL_ORIGINS)[number];
+export interface AcquiredCredential {
+    /** The bearer secret. Never printed, never logged, never persisted by us. */
+    readonly secret: string;
+    /** The account the provider knows this credential by, when it states one. */
+    readonly accountId: string | null;
+    /** Expiry in epoch milliseconds, when the document states one. */
+    readonly expiresAtMilliseconds: number | null;
+    /** Where this credential came from, so a row can say whose login it is. */
+    readonly origin: CredentialOrigin;
+}
+export type CredentialResult = {
+    ok: true;
+    credential: AcquiredCredential;
+} | {
+    ok: false;
+    reason: CredentialFailureReason;
+};
+export interface CredentialLookupOptions {
+    readonly platform?: NodeJS.Platform;
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    readonly homeDirectory?: string;
+    /** Injected clock, so an expiry test does not depend on the wall clock. */
+    readonly now?: string;
+    /**
+     * How a Windows Credential Manager entry is read.
+     *
+     * Injected so the Antigravity path can be proved without a real credential
+     * on the machine, and so no test ever touches the live credential store.
+     */
+    readonly readWindowsCredential?: WindowsCredentialReader;
+}
+export type WindowsCredentialReader = (target: string) => Promise<{
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: CredentialFailureReason;
+}>;
+/**
+ * Every place a provider's own client is known to keep its credential, in the
+ * order the vendor's own environment variable would win.
+ *
+ * The first readable document that yields a usable secret wins. Order matters
+ * only for a machine carrying two of them, and in that case the explicit
+ * environment variable is the one the person set on purpose.
+ */
+export declare function credentialCandidatePaths(provider: AcquisitionProvider, options?: CredentialLookupOptions): string[];
+/** The Windows Credential Manager target the Antigravity client writes to. */
+export declare const ANTIGRAVITY_CREDENTIAL_TARGET = "gemini:antigravity";
+/** The macOS keychain service Claude Code writes to, which this path skips. */
+export declare const CLAUDE_KEYCHAIN_SERVICE = "Claude Code-credentials";
+/** The issuer a Grok credential file should be read under when it names one. */
+export declare const GROK_PREFERRED_ISSUER = "https://auth.x.ai";
+/**
+ * An expiry, whatever unit the document happened to state it in.
+ *
+ * Seconds, milliseconds and RFC3339 all appear across these six clients. A
+ * value below the seconds ceiling is read as seconds, which is the same rule
+ * every reset parser in this product already uses.
+ */
+export declare function expiryMilliseconds(value: unknown): number | null;
+/**
+ * Read one credential document that has already been parsed.
+ *
+ * Exported so a test can prove every shape without writing a file, and so the
+ * Windows Credential Manager path can reuse exactly the same reader for the
+ * envelope it gets back from the credential store.
+ */
+export declare function readCredentialDocument(provider: AcquisitionProvider, document: unknown, nowMilliseconds: number, origin?: CredentialOrigin): CredentialResult;
+/**
+ * Read the credential a provider's own client stored, from disk.
+ *
+ * The result is one of four things and never a mixture: a usable credential, a
+ * provider that is simply not installed here, a document that could not be
+ * believed, or a login that has run out. Nothing is refreshed and nothing is
+ * written back.
+ */
+export declare function readAcquisitionCredential(provider: AcquisitionProvider, options?: CredentialLookupOptions): Promise<CredentialResult>;
+/**
+ * One sentence per failure, for the row a person actually reads.
+ *
+ * No dashes anywhere, and every sentence names the next step rather than the
+ * internal reason, because a person cannot act on the word "invalid".
+ */
+export declare const CREDENTIAL_FAILURE_SENTENCE: Readonly<Record<CredentialFailureReason, string>>;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/acquire/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../../src/acquire/credentials.ts"],"names":[],"mappings":"AAuBA,yDAAyD;AACzD,eAAO,MAAM,qBAAqB,yFAQxB,CAAC;AAEX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzE,mEAAmE;AACnE,eAAO,MAAM,yBAAyB,QAAS,CAAC;AAEhD;;;;;;GAMG;AACH,MAAM,MAAM,uBAAuB,GAC/B,QAAQ,GACR,YAAY,GACZ,SAAS,GACT,SAAS,GACT,mBAAmB,CAAC;AAExB;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,4EAKrB,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnE,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6EAA6E;IAC7E,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9C,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;CACnC;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,kBAAkB,CAAA;CAAE,GAC5C;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,CAAC;AAEnD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,uBAAuB,CAAC;CAC1D;AAED,MAAM,MAAM,uBAAuB,GAAG,CACpC,MAAM,EAAE,MAAM,KACX,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,uBAAuB,CAAA;CAAE,CAAC,CAAC;AAoC3F;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,GAAE,uBAA4B,GACpC,MAAM,EAAE,CAqDV;AAED,8EAA8E;AAC9E,eAAO,MAAM,6BAA6B,uBAAuB,CAAC;AAElE,+EAA+E;AAC/E,eAAO,MAAM,uBAAuB,4BAA4B,CAAC;AA6DjE,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAEzD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAWhE;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,mBAAmB,EAC7B,QAAQ,EAAE,OAAO,EACjB,eAAe,EAAE,MAAM,EACvB,MAAM,GAAE,gBAAgC,GACvC,gBAAgB,CA4ClB;AAED;;;;;;;GAOG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,gBAAgB,CAAC,CAsD3B;AAED;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,EACtC,QAAQ,CAAC,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAOjD,CAAC"}