aura-code 0.3.0

package/dist/util/env.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getApiKey = getApiKey;
+exports.getEnv = getEnv;
+/**
+ * Provider-agnostic env-var reader.
+ *
+ * Tries, in order:
+ *   1. The canonical UPPER_SNAKE_CASE var (most SDKs read this)
+ *   2. The lowercase variant (some shells / dotenv loaders normalise to this)
+ *   3. Common alternates passed as `aliases`
+ *
+ * Returns `undefined` if none are set, never throws. Returns `undefined`
+ * (NOT '') for empty / whitespace / placeholder values, so callers can use
+ * the `??` operator and have it fall through to the next fallback.
+ */
+function getApiKey(canonical, ...aliases) {
+    const names = [canonical, canonical.toLowerCase(), ...aliases];
+    for (const name of names) {
+        const v = process.env[name];
+        if (v && v.trim() && v !== 'your_api_key_here')
+            return v;
+    }
+    return undefined;
+}
+/**
+ * Same idea for non-secret env vars (base URLs, model names).
+ * Returns `undefined` for unset / empty / whitespace, so `??` chains work.
+ */
+function getEnv(canonical, ...aliases) {
+    const names = [canonical, canonical.toLowerCase(), ...aliases];
+    for (const name of names) {
+        const v = process.env[name];
+        if (v && v.trim())
+            return v;
+    }
+    return undefined;
+}
+//# sourceMappingURL=env.js.map

package/dist/util/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/util/env.ts"],"names":[],"mappings":";;AAYA,8BAOC;AAMD,wBAOC;AAhCD;;;;;;;;;;;GAWG;AACH,SAAgB,SAAS,CAAC,SAAiB,EAAE,GAAG,OAAiB;IAC/D,MAAM,KAAK,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,WAAW,EAAE,EAAE,GAAG,OAAO,CAAC,CAAC;IAC/D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,mBAAmB;YAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,SAAgB,MAAM,CAAC,SAAiB,EAAE,GAAG,OAAiB;IAC5D,MAAM,KAAK,GAAG,CAAC,SAAS,EAAE,SAAS,CAAC,WAAW,EAAE,EAAE,GAAG,OAAO,CAAC,CAAC;IAC/D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC5B,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE;YAAE,OAAO,CAAC,CAAC;IAC9B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/util/errors.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Unified error type for API calls. All provider SDK errors are normalised
+ * into this so retry / circuit-breaker / fallback layers can reason about
+ * them uniformly.
+ */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly retriable: boolean;
+    readonly provider: string;
+    readonly retryAfterMs?: number;
+    /** Tokens used in the failing request, if known (for TPM tracking) */
+    readonly tokens?: {
+        input: number;
+        output: number;
+    };
+    /** Cause chain — original SDK error preserved for debugging */
+    readonly cause?: unknown;
+    constructor(opts: {
+        message: string;
+        status?: number;
+        retriable?: boolean;
+        provider: string;
+        retryAfterMs?: number;
+        tokens?: {
+            input: number;
+            output: number;
+        };
+        cause?: unknown;
+    });
+}
+/**
+ * Classify an HTTP status as retriable. 429 and 5xx are retriable; 4xx (except 429) are not.
+ * Network errors (status 0) default to retriable.
+ */
+export declare function defaultRetriable(status: number): boolean;
+/**
+ * Normalise any error from any provider SDK into an ApiError. We inspect the
+ * error shape, pull out the HTTP status, and read Retry-After if present.
+ */
+export declare function normaliseError(e: unknown, provider: string): ApiError;
+/** Did the error come from Gemini specifically? */
+export declare function isGoogle(e: unknown): boolean;

package/dist/util/errors.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiError = void 0;
+exports.defaultRetriable = defaultRetriable;
+exports.normaliseError = normaliseError;
+exports.isGoogle = isGoogle;
+/**
+ * Unified error type for API calls. All provider SDK errors are normalised
+ * into this so retry / circuit-breaker / fallback layers can reason about
+ * them uniformly.
+ */
+class ApiError extends Error {
+    status;
+    retriable;
+    provider;
+    retryAfterMs;
+    /** Tokens used in the failing request, if known (for TPM tracking) */
+    tokens;
+    /** Cause chain — original SDK error preserved for debugging */
+    cause;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'ApiError';
+        this.status = opts.status ?? 0;
+        this.retriable = opts.retriable ?? defaultRetriable(opts.status ?? 0);
+        this.provider = opts.provider;
+        this.retryAfterMs = opts.retryAfterMs;
+        this.tokens = opts.tokens;
+        this.cause = opts.cause;
+    }
+}
+exports.ApiError = ApiError;
+/**
+ * Classify an HTTP status as retriable. 429 and 5xx are retriable; 4xx (except 429) are not.
+ * Network errors (status 0) default to retriable.
+ */
+function defaultRetriable(status) {
+    if (status === 0)
+        return true; // network/timeout
+    if (status === 429)
+        return true; // rate limited
+    if (status === 408)
+        return true; // request timeout
+    if (status === 529)
+        return true; // Anthropic overloaded
+    if (status >= 500 && status < 600)
+        return true;
+    return false;
+}
+/**
+ * Normalise any error from any provider SDK into an ApiError. We inspect the
+ * error shape, pull out the HTTP status, and read Retry-After if present.
+ */
+function normaliseError(e, provider) {
+    // Already normalised
+    if (e instanceof ApiError)
+        return e;
+    // Anthropic / OpenAI / Google SDKs all throw errors with a `status` and sometimes `headers`.
+    const err = e;
+    const status = err.status ?? err.statusCode ?? 0;
+    const message = err.message ?? String(e);
+    const retryAfterMs = parseRetryAfter(err.headers) ?? parseGoogleRetryAfter(err.errorDetails);
+    // Network/timeout: status 0
+    const isNetwork = status === 0 || err.code === 'ETIMEDOUT' || err.code === 'ECONNRESET' || err.code === 'ENOTFOUND' || err.name === 'AbortError';
+    return new ApiError({
+        message: isNetwork ? `Network error: ${message}` : `HTTP ${status}: ${message}`,
+        status: isNetwork ? 0 : status,
+        retriable: isNetwork || defaultRetriable(status),
+        provider,
+        retryAfterMs,
+        cause: e,
+    });
+}
+function parseRetryAfter(headers) {
+    if (!headers)
+        return undefined;
+    const v = headers['retry-after'] ?? headers['Retry-After'] ?? headers['x-ratelimit-reset'];
+    if (!v)
+        return undefined;
+    // Could be "120" (seconds) or an HTTP date
+    const seconds = Number(v);
+    if (!isNaN(seconds))
+        return Math.round(seconds * 1000);
+    const date = Date.parse(v);
+    if (!isNaN(date))
+        return Math.max(0, date - Date.now());
+    return undefined;
+}
+/**
+ * Google Gemini's error responses include an `errorDetails` array. The relevant
+ * entry has `@type: type.googleapis.com/google.rpc.RetryInfo` and a `retryDelay`
+ * string like "27s". We parse it into milliseconds.
+ */
+function parseGoogleRetryAfter(details) {
+    if (!details || details.length === 0)
+        return undefined;
+    for (const d of details) {
+        const type = d['@type'] ?? '';
+        if (type.includes('RetryInfo')) {
+            const raw = d.retryDelay ?? d.RetryInfo?.retryDelay;
+            if (!raw)
+                continue;
+            // Formats: "27s", "1500ms", "27.5s"
+            const m = String(raw).trim().match(/^(\d+(?:\.\d+)?)(ms|s)?$/);
+            if (m) {
+                const n = parseFloat(m[1]);
+                const unit = m[2] ?? 's';
+                return Math.round(unit === 'ms' ? n : n * 1000);
+            }
+        }
+    }
+    return undefined;
+}
+/** Did the error come from Gemini specifically? */
+function isGoogle(e) {
+    if (e instanceof ApiError)
+        return e.provider === 'Google';
+    const err = e;
+    return Boolean(err.message?.includes('GoogleGenerativeAI') || err.name?.includes('GoogleGenerative'));
+}
+//# sourceMappingURL=errors.js.map

package/dist/util/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/util/errors.ts"],"names":[],"mappings":";;;AAuCA,4CAOC;AAMD,wCA8BC;AAyCD,4BAIC;AA/HD;;;;GAIG;AACH,MAAa,QAAS,SAAQ,KAAK;IACxB,MAAM,CAAS;IACf,SAAS,CAAU;IACnB,QAAQ,CAAS;IACjB,YAAY,CAAU;IAC/B,sEAAsE;IAC7D,MAAM,CAAqC;IACpD,+DAA+D;IACtD,KAAK,CAAW;IAEzB,YAAY,IAQX;QACC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;QAC/B,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,gBAAgB,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC;QACtE,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC9B,IAAI,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;QAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;IAC1B,CAAC;CACF;AA5BD,4BA4BC;AAED;;;GAGG;AACH,SAAgB,gBAAgB,CAAC,MAAc;IAC7C,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC,CAAU,kBAAkB;IAC1D,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC,CAAQ,eAAe;IACvD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC,CAAQ,kBAAkB;IAC1D,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC,CAAQ,uBAAuB;IAC/D,IAAI,MAAM,IAAI,GAAG,IAAI,MAAM,GAAG,GAAG;QAAE,OAAO,IAAI,CAAC;IAC/C,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;GAGG;AACH,SAAgB,cAAc,CAAC,CAAU,EAAE,QAAgB;IACzD,qBAAqB;IACrB,IAAI,CAAC,YAAY,QAAQ;QAAE,OAAO,CAAC,CAAC;IAEpC,6FAA6F;IAC7F,MAAM,GAAG,GAAG,CAQX,CAAC;IAEF,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,UAAU,IAAI,CAAC,CAAC;IACjD,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC;IACzC,MAAM,YAAY,GAAG,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,qBAAqB,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IAE7F,4BAA4B;IAC5B,MAAM,SAAS,GAAG,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,IAAI,GAAG,CAAC,IAAI,KAAK,WAAW,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,CAAC;IAEjJ,OAAO,IAAI,QAAQ,CAAC;QAClB,OAAO,EAAE,SAAS,CAAC,CAAC,CAAC,kBAAkB,OAAO,EAAE,CAAC,CAAC,CAAC,QAAQ,MAAM,KAAK,OAAO,EAAE;QAC/E,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM;QAC9B,SAAS,EAAE,SAAS,IAAI,gBAAgB,CAAC,MAAM,CAAC;QAChD,QAAQ;QACR,YAAY;QACZ,KAAK,EAAE,CAAC;KACT,CAAC,CAAC;AACL,CAAC;AAED,SAAS,eAAe,CAAC,OAAgC;IACvD,IAAI,CAAC,OAAO;QAAE,OAAO,SAAS,CAAC;IAC/B,MAAM,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,OAAO,CAAC,aAAa,CAAC,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC3F,IAAI,CAAC,CAAC;QAAE,OAAO,SAAS,CAAC;IACzB,2CAA2C;IAC3C,MAAM,OAAO,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,CAAC;IACvD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC3B,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IACxD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;GAIG;AACH,SAAS,qBAAqB,CAC5B,OAA+F;IAE/F,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IACvD,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;QAC9B,IAAI,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;YAC/B,MAAM,GAAG,GAAG,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,SAAS,EAAE,UAAU,CAAC;YACpD,IAAI,CAAC,GAAG;gBAAE,SAAS;YACnB,oCAAoC;YACpC,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,0BAA0B,CAAC,CAAC;YAC/D,IAAI,CAAC,EAAE,CAAC;gBACN,MAAM,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC3B,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC;gBACzB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;YAClD,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,mDAAmD;AACnD,SAAgB,QAAQ,CAAC,CAAU;IACjC,IAAI,CAAC,YAAY,QAAQ;QAAE,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC;IAC1D,MAAM,GAAG,GAAG,CAAwC,CAAC;IACrD,OAAO,OAAO,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,oBAAoB,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,QAAQ,CAAC,kBAAkB,CAAC,CAAC,CAAC;AACxG,CAAC"}

package/dist/util/rate-limiter.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Token-bucket rate limiter. Each bucket starts full and refills at a
+ * steady rate. `acquire()` waits until a token is available, then consumes
+ * one. Pass `consume(n)` to take multiple tokens at once (used by TPM).
+ */
+export interface RateLimiterOptions {
+    /** Maximum tokens in the bucket (burst size). */
+    capacity: number;
+    /** Tokens added per millisecond. e.g. 50 rpm → 50/60000 ≈ 0.000833 */
+    refillPerMs: number;
+    /** Initial tokens (defaults to capacity). */
+    initialTokens?: number;
+    /** Sleep function for testing. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Called when acquire must wait — useful for observability. */
+    onWait?: (info: {
+        needed: number;
+        waitMs: number;
+    }) => void;
+}
+export declare class RateLimiter {
+    private tokens;
+    private lastRefill;
+    private readonly capacity;
+    private readonly refillPerMs;
+    private readonly sleep;
+    private readonly onWait?;
+    constructor(opts: RateLimiterOptions);
+    /**
+     * Wait until `n` tokens are available, then consume them.
+     * Returns the milliseconds waited (0 if instant).
+     */
+    acquire(n?: number): Promise<number>;
+    /**
+     * Consume tokens without waiting. Returns true if successful, false if
+     * there aren't enough. The bucket is unchanged on false.
+     */
+    tryAcquire(n?: number): boolean;
+    /** Force a token count (e.g. record a successful API call's token cost). */
+    recordUsage(n: number): void;
+    /** Reset the bucket to full. */
+    reset(): void;
+    /** Current token count (after refill). */
+    available(): number;
+    private refill;
+}
+/** RPM → token-bucket config. capacity allows short bursts. */
+export declare function rpmLimiter(rpm: number, opts?: {
+    burst?: number;
+    onWait?: RateLimiterOptions['onWait'];
+}): RateLimiter;
+/**
+ * TPM (tokens per minute) tracker using a sliding window.
+ * Different from RateLimiter: it doesn't block — it just records usage
+ * and exposes whether the current window is under the limit. Used to
+ * inform the retry layer (don't hammer Google when we're already near TPM).
+ */
+export declare class TpmTracker {
+    private window;
+    private readonly windowMs;
+    private readonly limit;
+    constructor(tokensPerMinute: number, windowMs?: number);
+    record(tokens: number, now?: number): void;
+    used(now?: number): number;
+    remaining(now?: number): number;
+    /** True if there's room for `n` more tokens right now. */
+    hasRoomFor(n: number, now?: number): boolean;
+    /** Suggested wait ms before the requested tokens fit, given current usage. */
+    waitMsFor(n: number, now?: number): number;
+    private prune;
+}

package/dist/util/rate-limiter.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TpmTracker = exports.RateLimiter = void 0;
+exports.rpmLimiter = rpmLimiter;
+class RateLimiter {
+    tokens;
+    lastRefill;
+    capacity;
+    refillPerMs;
+    sleep;
+    onWait;
+    constructor(opts) {
+        this.capacity = opts.capacity;
+        this.refillPerMs = opts.refillPerMs;
+        this.tokens = opts.initialTokens ?? opts.capacity;
+        this.lastRefill = Date.now();
+        this.sleep = opts.sleep ?? defaultSleep;
+        this.onWait = opts.onWait;
+    }
+    /**
+     * Wait until `n` tokens are available, then consume them.
+     * Returns the milliseconds waited (0 if instant).
+     */
+    async acquire(n = 1) {
+        if (n > this.capacity) {
+            throw new Error(`Cannot acquire ${n} tokens — bucket capacity is ${this.capacity}`);
+        }
+        const start = Date.now();
+        while (true) {
+            this.refill();
+            if (this.tokens >= n) {
+                this.tokens -= n;
+                return Date.now() - start;
+            }
+            // Tokens needed minus what we have, divided by refill rate = wait time
+            const deficit = n - this.tokens;
+            const waitMs = Math.ceil(deficit / this.refillPerMs) + 5;
+            this.onWait?.({ needed: n, waitMs });
+            await this.sleep(waitMs);
+        }
+    }
+    /**
+     * Consume tokens without waiting. Returns true if successful, false if
+     * there aren't enough. The bucket is unchanged on false.
+     */
+    tryAcquire(n = 1) {
+        this.refill();
+        if (this.tokens >= n) {
+            this.tokens -= n;
+            return true;
+        }
+        return false;
+    }
+    /** Force a token count (e.g. record a successful API call's token cost). */
+    recordUsage(n) {
+        this.refill();
+        this.tokens = Math.max(0, this.tokens - n);
+    }
+    /** Reset the bucket to full. */
+    reset() {
+        this.tokens = this.capacity;
+        this.lastRefill = Date.now();
+    }
+    /** Current token count (after refill). */
+    available() {
+        this.refill();
+        return this.tokens;
+    }
+    refill() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        if (elapsed <= 0)
+            return;
+        this.tokens = Math.min(this.capacity, this.tokens + elapsed * this.refillPerMs);
+        this.lastRefill = now;
+    }
+}
+exports.RateLimiter = RateLimiter;
+function defaultSleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+// ── Factory helpers ─────────────────────────────────────────────────────────
+/** RPM → token-bucket config. capacity allows short bursts. */
+function rpmLimiter(rpm, opts) {
+    return new RateLimiter({
+        capacity: opts?.burst ?? Math.max(1, Math.ceil(rpm / 6)), // ~10s burst
+        refillPerMs: rpm / 60_000,
+        onWait: opts?.onWait,
+    });
+}
+/**
+ * TPM (tokens per minute) tracker using a sliding window.
+ * Different from RateLimiter: it doesn't block — it just records usage
+ * and exposes whether the current window is under the limit. Used to
+ * inform the retry layer (don't hammer Google when we're already near TPM).
+ */
+class TpmTracker {
+    window = [];
+    windowMs;
+    limit;
+    constructor(tokensPerMinute, windowMs = 60_000) {
+        this.limit = tokensPerMinute;
+        this.windowMs = windowMs;
+    }
+    record(tokens, now = Date.now()) {
+        this.window.push({ t: now, tokens });
+        this.prune(now);
+    }
+    used(now = Date.now()) {
+        this.prune(now);
+        return this.window.reduce((s, e) => s + e.tokens, 0);
+    }
+    remaining(now = Date.now()) {
+        return Math.max(0, this.limit - this.used(now));
+    }
+    /** True if there's room for `n` more tokens right now. */
+    hasRoomFor(n, now = Date.now()) {
+        return this.used(now) + n <= this.limit;
+    }
+    /** Suggested wait ms before the requested tokens fit, given current usage. */
+    waitMsFor(n, now = Date.now()) {
+        if (this.hasRoomFor(n, now))
+            return 0;
+        // Find the oldest entry that, when evicted, would free enough room
+        let freed = 0;
+        for (const entry of this.window) {
+            freed += entry.tokens;
+            if (this.used(now) - freed + n <= this.limit) {
+                return Math.max(0, entry.t + this.windowMs - now);
+            }
+        }
+        return this.windowMs;
+    }
+    prune(now) {
+        const cutoff = now - this.windowMs;
+        while (this.window.length > 0 && this.window[0].t < cutoff)
+            this.window.shift();
+    }
+}
+exports.TpmTracker = TpmTracker;
+//# sourceMappingURL=rate-limiter.js.map

package/dist/util/rate-limiter.js.map

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

package/dist/util/retry.d.ts

@@ -0,0 +1,30 @@
+import { ApiError } from './errors.js';
+export interface RetryOptions {
+    /** Maximum number of attempts (not retries — total tries including the first). Default 5. */
+    maxAttempts?: number;
+    /** Base delay in ms for the backoff. Default 1000. */
+    baseDelayMs?: number;
+    /** Maximum delay between retries. Default 30000 (30s). */
+    maxDelayMs?: number;
+    /** Multiplier per attempt. Default 2. */
+    factor?: number;
+    /** Jitter factor 0..1. Default 0.25. */
+    jitter?: number;
+    /** Called before each retry with the attempt number and the upcoming delay. */
+    onRetry?: (info: {
+        attempt: number;
+        delayMs: number;
+        error: ApiError;
+    }) => void;
+    /** Abort signal — abort waits between retries. */
+    signal?: AbortSignal;
+    /** Sleep function for testing. Default global setTimeout. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Wrap an async function with exponential backoff and jitter.
+ * - Honours the error's `retryAfterMs` if set (e.g. parsed from Retry-After header).
+ * - Only retries ApiError instances where `retriable === true`.
+ * - Re-throws the last error if all attempts fail.
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;

package/dist/util/retry.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withRetry = withRetry;
+const errors_js_1 = require("./errors.js");
+/**
+ * Wrap an async function with exponential backoff and jitter.
+ * - Honours the error's `retryAfterMs` if set (e.g. parsed from Retry-After header).
+ * - Only retries ApiError instances where `retriable === true`.
+ * - Re-throws the last error if all attempts fail.
+ */
+async function withRetry(fn, opts = {}) {
+    const maxAttempts = opts.maxAttempts ?? 5;
+    const base = opts.baseDelayMs ?? 1000;
+    const max = opts.maxDelayMs ?? 30_000;
+    const factor = opts.factor ?? 2;
+    const jitter = opts.jitter ?? 0.25;
+    const sleep = opts.sleep ?? defaultSleep;
+    let lastErr;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        if (opts.signal?.aborted)
+            throw new Error('Aborted');
+        try {
+            return await fn();
+        }
+        catch (e) {
+            const err = e instanceof errors_js_1.ApiError ? e : new errors_js_1.ApiError({
+                message: String(e), provider: 'unknown', retriable: false, cause: e,
+            });
+            lastErr = err;
+            if (!err.retriable || attempt === maxAttempts)
+                throw err;
+            const delay = computeDelay({
+                attempt, base, max, factor, jitter,
+                retryAfter: err.retryAfterMs,
+            });
+            opts.onRetry?.({ attempt: attempt + 1, delayMs: delay, error: err });
+            if (opts.signal?.aborted)
+                throw new Error('Aborted');
+            await sleep(delay);
+        }
+    }
+    throw lastErr ?? new errors_js_1.ApiError({ message: 'withRetry exhausted', provider: 'unknown' });
+}
+function computeDelay(opts) {
+    // If the server told us when to retry, prefer that (capped to max).
+    if (opts.retryAfter !== undefined) {
+        return Math.min(opts.max, Math.max(opts.retryAfter, 0));
+    }
+    const exp = opts.base * Math.pow(opts.factor, opts.attempt - 1);
+    const capped = Math.min(opts.max, exp);
+    const jittered = capped * (1 - opts.jitter + Math.random() * opts.jitter * 2);
+    return Math.round(jittered);
+}
+function defaultSleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=retry.js.map

package/dist/util/retry.js.map

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

package/dist/util/sanitize.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Strip HTML tags from a string using a character-level state machine.
+ * Also removes <script> and <style> blocks entirely (including content).
+ * Preserves text content. Decodes common HTML entities afterward.
+ */
+export declare function stripHtml(html: string): string;
+/**
+ * Decode HTML entities in a single pass.
+ * Uses a single regex replacement to avoid sequential decode issues
+ * (e.g., &amp;lt; should become &lt;, not <).
+ */
+export declare function decodeEntities(text: string): string;
+/**
+ * Escape HTML special characters to prevent XSS.
+ */
+export declare function escapeHtml(text: string): string;