@cortexkit/common-auth 0.2.4 → 0.2.5

package/dist/cachekeep/manager.js

@@ -0,0 +1,424 @@
+import { isWithinCacheKeepWindow } from './window.js';
+const DEFAULT_TTL_MS = 5 * 60_000;
+const DEFAULT_MAX_IDLE_WARM_MS = 60 * 60_000;
+const DEFAULT_MAX_SUBAGENT_IDLE_MS = 30 * 60_000;
+const DEFAULT_TICK_INTERVAL_MS = 60_000;
+const DEFAULT_MAX_TARGETS = 32;
+const DEFAULT_MAX_BYTES = 8 * 1024 * 1024;
+const DEFAULT_WARM_TIMEOUT_MS = 30_000;
+const DEFAULT_BACKOFF_MS = 10 * 60_000;
+function positive(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? value
+        : fallback;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * Keeps idle prompt caches warm: one target per session holding the latest
+ * request body, replayed just before the provider's cache would expire.
+ *
+ * Bounds, in the order they act: the clock window gates capture and warming
+ * (targets captured earlier survive outside it); idle caps prune a target its
+ * session stopped using (`sustain` lifts only the main-session cap); the
+ * target-count and byte caps evict the least recently touched target; a
+ * per-target warm cap retires short-lived sessions; and a failed warm backs
+ * that target off without touching the others.
+ */
+export class CacheKeepManager {
+    targets = new Map();
+    adapter;
+    now;
+    log;
+    ttlMs;
+    leadMs;
+    maxIdleWarmMs;
+    maxSubagentIdleMs;
+    tickIntervalMs;
+    maxTargets;
+    maxBytes;
+    warmTimeoutMs;
+    backoff;
+    getWindow;
+    getSustain;
+    setIntervalImpl;
+    clearIntervalImpl;
+    timer = null;
+    startedAt = null;
+    totalBytes = 0;
+    tickPromise = null;
+    disposed = false;
+    abortController = new AbortController();
+    constructor(options) {
+        this.adapter = options.adapter;
+        this.now = options.now;
+        this.log = options.logger;
+        this.ttlMs = positive(options.ttlMs, DEFAULT_TTL_MS);
+        this.tickIntervalMs = positive(options.tickIntervalMs, DEFAULT_TICK_INTERVAL_MS);
+        // One tick of slack so a target that becomes due between ticks is still
+        // warmed before its cache expires.
+        this.leadMs = positive(options.leadMs, this.tickIntervalMs + 15_000);
+        this.maxIdleWarmMs = positive(options.maxIdleWarmMs, DEFAULT_MAX_IDLE_WARM_MS);
+        this.maxSubagentIdleMs = positive(options.maxSubagentIdleMs, DEFAULT_MAX_SUBAGENT_IDLE_MS);
+        this.maxTargets = positive(options.maxTargets, DEFAULT_MAX_TARGETS);
+        this.maxBytes = positive(options.maxBytes, DEFAULT_MAX_BYTES);
+        this.warmTimeoutMs = positive(options.warmTimeoutMs, DEFAULT_WARM_TIMEOUT_MS);
+        this.backoff = options.backoffMs ?? DEFAULT_BACKOFF_MS;
+        this.getWindow = options.getWindow;
+        this.getSustain = options.getSustain;
+        this.setIntervalImpl = options.setIntervalImpl ?? globalThis.setInterval;
+        this.clearIntervalImpl =
+            options.clearIntervalImpl ?? globalThis.clearInterval;
+    }
+    /**
+     * Capture a session's latest request. The freshest body replaces the
+     * previous one and restarts its cache clock, idle clock and warm count.
+     * Arms the timer.
+     */
+    track(input) {
+        const { sessionKey, bodyText } = input;
+        this.pruneStale();
+        const bodyBytes = Buffer.byteLength(bodyText, 'utf8');
+        if (bodyBytes > this.maxBytes) {
+            this.log?.debug('cachekeep track skipped (body exceeds maxBytes)', {
+                sessionKey,
+                bodyBytes,
+                maxBytes: this.maxBytes,
+            });
+            return { tracked: false, reason: 'body-exceeds-max-bytes' };
+        }
+        const window = this.getWindow?.();
+        if (window && !isWithinCacheKeepWindow(window, new Date(this.now()))) {
+            this.log?.debug('cachekeep track skipped (outside window)', {
+                sessionKey,
+                startHour: window.startHour,
+                endHour: window.endHour,
+            });
+            return { tracked: false, reason: 'outside-window' };
+        }
+        // Delete before re-adding so a retracked session is also the most recent
+        // in insertion order.
+        this.drop(sessionKey);
+        while (this.targets.size >= this.maxTargets ||
+            (this.totalBytes + bodyBytes > this.maxBytes && this.targets.size > 0)) {
+            const evictKey = this.leastRecentlyTouched();
+            if (evictKey === undefined)
+                break;
+            this.log?.debug('cachekeep evicted least recently used target', {
+                sessionKey: evictKey,
+            });
+            this.drop(evictKey);
+        }
+        const isSubagent = input.isSubagent === true;
+        const accountId = input.accountId || undefined;
+        const profile = this.adapter.profile?.({
+            bodyText,
+            isSubagent,
+            accountId,
+            meta: input.meta,
+        });
+        const ttlMs = positive(profile?.ttlMs, this.ttlMs);
+        const now = this.now();
+        this.targets.set(sessionKey, {
+            bodyText,
+            bodyBytes,
+            accountId,
+            isSubagent,
+            meta: input.meta,
+            ttlMs,
+            maxWarms: profile?.maxWarms !== undefined && profile.maxWarms > 0
+                ? Math.floor(profile.maxWarms)
+                : undefined,
+            maxIdleMs: profile?.maxIdleMs !== undefined
+                ? positive(profile.maxIdleMs, this.idleDefault(isSubagent))
+                : undefined,
+            cacheExpiresAt: now + ttlMs,
+            lastRealRequestAt: now,
+            failures: 0,
+            warmCount: 0,
+        });
+        this.totalBytes += bodyBytes;
+        this.log?.debug('cachekeep captured target', { sessionKey, accountId });
+        this.start();
+        return { tracked: true };
+    }
+    /** Forget a session, e.g. when the host deletes it. */
+    remove(sessionKey) {
+        if (this.drop(sessionKey)) {
+            this.log?.debug('cachekeep removed target', { sessionKey });
+        }
+    }
+    start() {
+        this.disposed = false;
+        if (this.timer)
+            return;
+        this.startedAt = this.now();
+        this.timer = this.setIntervalImpl(() => {
+            void this.tick().catch((error) => {
+                this.log?.warn('cachekeep tick failed', { error: errorMessage(error) });
+            });
+        }, this.tickIntervalMs);
+        if (typeof this.timer === 'object' && 'unref' in this.timer) {
+            this.timer.unref();
+        }
+        this.log?.debug('cachekeep started', {
+            ttlMs: this.ttlMs,
+            leadMs: this.leadMs,
+            maxIdleWarmMs: this.maxIdleWarmMs,
+        });
+    }
+    /** Disarm, abort any warm in flight and forget every target. */
+    stop() {
+        this.disposed = true;
+        this.abortController.abort();
+        this.abortController = new AbortController();
+        if (this.timer) {
+            this.clearIntervalImpl(this.timer);
+            this.timer = null;
+        }
+        this.startedAt = null;
+        this.targets.clear();
+        this.totalBytes = 0;
+        this.log?.debug('cachekeep stopped');
+    }
+    /** A snapshot without captured bodies, which can hold prompt content. */
+    status() {
+        const window = this.getWindow?.();
+        return {
+            running: this.timer !== null,
+            tracked: this.targets.size,
+            totalBytes: this.totalBytes,
+            generatedAt: this.now(),
+            startedAt: this.startedAt,
+            ttlMs: this.ttlMs,
+            leadMs: this.leadMs,
+            maxIdleWarmMs: this.maxIdleWarmMs,
+            maxSubagentIdleMs: this.maxSubagentIdleMs,
+            sustain: this.getSustain?.() === true,
+            ...(window ? { window } : {}),
+            targets: [...this.targets].map(([sessionKey, target]) => ({
+                sessionKey,
+                accountId: target.accountId,
+                isSubagent: target.isSubagent,
+                cacheExpiresAt: target.cacheExpiresAt,
+                lastRealRequestAt: target.lastRealRequestAt,
+                ...(target.lastWarmedAt !== undefined
+                    ? { lastWarmedAt: target.lastWarmedAt }
+                    : {}),
+                ...(target.backoffUntil !== undefined
+                    ? { backoffUntil: target.backoffUntil }
+                    : {}),
+                failures: target.failures,
+                warmCount: target.warmCount,
+                ttlMs: target.ttlMs,
+                bodyBytes: target.bodyBytes,
+            })),
+        };
+    }
+    /**
+     * Prune, then warm every target within `leadMs` of expiry that is not
+     * backing off. Overlapping calls share the tick already running, so a slow
+     * warm never stacks a second send for the same target.
+     */
+    tick() {
+        if (this.tickPromise)
+            return this.tickPromise;
+        const run = this.runTick().finally(() => {
+            if (this.tickPromise === run)
+                this.tickPromise = null;
+        });
+        this.tickPromise = run;
+        return run;
+    }
+    async runTick() {
+        this.pruneStale();
+        // Outside the window nothing fires, but captured targets stay so they
+        // warm again when it reopens.
+        const window = this.getWindow?.();
+        if (window && !isWithinCacheKeepWindow(window, new Date(this.now()))) {
+            return;
+        }
+        const now = this.now();
+        const leadBound = now + this.leadMs;
+        for (const [sessionKey, target] of [...this.targets]) {
+            if (this.disposed)
+                return;
+            if (this.targets.get(sessionKey) !== target)
+                continue;
+            if (target.backoffUntil !== undefined && now < target.backoffUntil) {
+                continue;
+            }
+            if (target.cacheExpiresAt > leadBound)
+                continue;
+            await this.warm(sessionKey, target);
+        }
+    }
+    isCurrent(sessionKey, target) {
+        return !this.disposed && this.targets.get(sessionKey) === target;
+    }
+    view(sessionKey, target) {
+        return {
+            sessionKey,
+            accountId: target.accountId,
+            bodyText: target.bodyText,
+            isSubagent: target.isSubagent,
+            meta: target.meta,
+            warmCount: target.warmCount,
+            ttlMs: target.ttlMs,
+        };
+    }
+    fail(sessionKey, target, message, fields = {}) {
+        if (!this.isCurrent(sessionKey, target))
+            return;
+        target.failures += 1;
+        const delay = typeof this.backoff === 'function'
+            ? this.backoff({ sessionKey, failures: target.failures })
+            : this.backoff;
+        target.backoffUntil =
+            this.now() + (Number.isFinite(delay) && delay > 0 ? delay : 0);
+        this.log?.warn(message, {
+            sessionKey,
+            accountId: target.accountId,
+            failures: target.failures,
+            backoffUntil: target.backoffUntil,
+            ...fields,
+        });
+    }
+    async warm(sessionKey, target) {
+        const view = this.view(sessionKey, target);
+        if (this.adapter.activeAccount) {
+            let active;
+            try {
+                active = await this.adapter.activeAccount(sessionKey, view);
+            }
+            catch (error) {
+                this.fail(sessionKey, target, 'cachekeep skip (active account unknown)', {
+                    error: errorMessage(error),
+                });
+                return;
+            }
+            if (!this.isCurrent(sessionKey, target))
+                return;
+            if (active !== undefined && active !== target.accountId) {
+                this.log?.debug('cachekeep dropped target (session changed account)', {
+                    sessionKey,
+                    accountId: target.accountId,
+                    activeAccountId: active,
+                });
+                this.drop(sessionKey);
+                return;
+            }
+        }
+        let body;
+        try {
+            body = await this.adapter.buildBody(view);
+        }
+        catch (error) {
+            this.fail(sessionKey, target, 'cachekeep skip (replay body unbuildable)', {
+                error: errorMessage(error),
+            });
+            return;
+        }
+        if (!this.isCurrent(sessionKey, target))
+            return;
+        const signal = AbortSignal.any([
+            AbortSignal.timeout(this.warmTimeoutMs),
+            this.abortController.signal,
+        ]);
+        let response;
+        let text = '';
+        try {
+            response = await this.adapter.send({ target: view, body, signal });
+            // Drain the body so the connection is released; its text is only
+            // diagnostic.
+            text = await response.text().catch(() => '');
+        }
+        catch (error) {
+            this.fail(sessionKey, target, 'cachekeep failed', {
+                error: errorMessage(error),
+            });
+            return;
+        }
+        if (!this.isCurrent(sessionKey, target))
+            return;
+        if (!response.ok) {
+            this.fail(sessionKey, target, 'cachekeep failed', {
+                status: response.status,
+                responseBody: text.slice(0, 600),
+            });
+            return;
+        }
+        let usage;
+        try {
+            usage = this.adapter.readUsage?.({ target: view, response, text });
+        }
+        catch {
+            // Usage is for the log line only and must never fail a warm that worked.
+        }
+        const now = this.now();
+        target.cacheExpiresAt = now + target.ttlMs;
+        target.lastWarmedAt = now;
+        target.backoffUntil = undefined;
+        target.failures = 0;
+        target.warmCount += 1;
+        this.log?.debug('cachekeep fired', {
+            sessionKey,
+            accountId: target.accountId,
+            warmCount: target.warmCount,
+            ...usage,
+        });
+        if (target.maxWarms !== undefined && target.warmCount >= target.maxWarms) {
+            this.log?.debug('cachekeep retired target (warm cap reached)', {
+                sessionKey,
+                warmCount: target.warmCount,
+            });
+            this.drop(sessionKey);
+        }
+    }
+    idleDefault(isSubagent) {
+        return isSubagent ? this.maxSubagentIdleMs : this.maxIdleWarmMs;
+    }
+    pruneStale() {
+        const now = this.now();
+        const sustain = this.getSustain?.() === true;
+        for (const [sessionKey, target] of [...this.targets]) {
+            // Sustain exempts main sessions from the idle cap only; the window,
+            // count, byte and warm caps still apply to them.
+            if (sustain && !target.isSubagent)
+                continue;
+            const maxIdleMs = target.maxIdleMs ?? this.idleDefault(target.isSubagent);
+            if (target.lastRealRequestAt >= now - maxIdleMs)
+                continue;
+            this.log?.debug('cachekeep pruned idle target', {
+                sessionKey,
+                accountId: target.accountId,
+                lastRealRequestAt: target.lastRealRequestAt,
+                maxIdleMs,
+            });
+            this.drop(sessionKey);
+        }
+    }
+    leastRecentlyTouched() {
+        let evictKey;
+        let evictTouchedAt = Number.POSITIVE_INFINITY;
+        for (const [key, target] of this.targets) {
+            // A warm counts as a touch, so a session kept warm outlives one whose
+            // only activity is an older real request.
+            const touchedAt = Math.max(target.lastRealRequestAt, target.lastWarmedAt ?? 0);
+            if (touchedAt < evictTouchedAt) {
+                evictKey = key;
+                evictTouchedAt = touchedAt;
+            }
+        }
+        return evictKey;
+    }
+    drop(sessionKey) {
+        const target = this.targets.get(sessionKey);
+        if (!target)
+            return false;
+        this.totalBytes -= target.bodyBytes;
+        this.targets.delete(sessionKey);
+        return true;
+    }
+}

package/dist/cachekeep/window.d.ts

@@ -0,0 +1,13 @@
+/** A local clock-hour range in which idle caches are kept warm. */
+export interface CacheKeepWindow {
+    startHour: number;
+    endHour: number;
+}
+/**
+ * Reads a persisted `{ startHour, endHour }` pair. Anything other than two
+ * distinct whole hours in 0-23 is no window at all, which callers treat as
+ * "always warm".
+ */
+export declare function normalizeCacheKeepWindow(value: unknown): CacheKeepWindow | undefined;
+/** Whether the local hour of `now` falls inside the window; no window is never inside. */
+export declare function isWithinCacheKeepWindow(window: CacheKeepWindow | undefined, now?: Date): boolean;

package/dist/cachekeep/window.js

@@ -0,0 +1,33 @@
+/**
+ * Reads a persisted `{ startHour, endHour }` pair. Anything other than two
+ * distinct whole hours in 0-23 is no window at all, which callers treat as
+ * "always warm".
+ */
+export function normalizeCacheKeepWindow(value) {
+    if (!value || typeof value !== 'object')
+        return undefined;
+    const record = value;
+    const startHour = Number(record.startHour);
+    const endHour = Number(record.endHour);
+    if (!Number.isInteger(startHour) ||
+        !Number.isInteger(endHour) ||
+        startHour < 0 ||
+        startHour > 23 ||
+        endHour < 0 ||
+        endHour > 23 ||
+        startHour === endHour) {
+        return undefined;
+    }
+    return { startHour, endHour };
+}
+/** Whether the local hour of `now` falls inside the window; no window is never inside. */
+export function isWithinCacheKeepWindow(window, now = new Date()) {
+    if (!window)
+        return false;
+    const hour = now.getHours();
+    if (window.startHour < window.endHour) {
+        return hour >= window.startHour && hour < window.endHour;
+    }
+    // Overnight wrap (e.g. 22-6): in window at or after the start, or before the end.
+    return hour >= window.startHour || hour < window.endHour;
+}

package/dist/dump/index.d.ts

@@ -1 +1,90 @@
-export {};
+export interface DumpLogger {
+    debug(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+}
+export interface DumpOptions {
+    /** Directory dumps are written to; a function is read on every dump. */
+    dir: string | (() => string);
+    /** Initial state; `setEnabled` switches it at runtime. Default off. */
+    enabled?: boolean;
+    /** Written into every filename. Default the current process id. */
+    pid?: number;
+    /** Clock for filenames and `createdAt`. Default `Date.now`. */
+    now?: () => number;
+    logger?: DumpLogger;
+    /**
+     * Key names redacted wherever they appear in headers, request metadata and
+     * the body, on top of the common credential set. Compared lower-cased with
+     * `-` and `_` removed, so `ChatGPT-Account-Id` and `chatgptAccountId` match
+     * `chatgptaccountid`.
+     */
+    secretKeys?: readonly string[];
+    /** Value patterns scrubbed from every string, on top of the common token patterns. */
+    secretPatterns?: readonly RegExp[];
+    /**
+     * Keys, at any depth of the body, whose values are declarations rather than
+     * data: their strings are scrubbed but their key names are never redacted.
+     * Default `['tools']`.
+     */
+    schemaKeys?: readonly string[];
+    /**
+     * Provider summary of the parsed body, stored in the metadata as `body`.
+     * It receives the redacted body.
+     */
+    summarize?: (body: Record<string, unknown>) => Record<string, unknown>;
+}
+export interface DumpInput {
+    /** The session the request belongs to; missing means `session-unknown`. */
+    session?: string | null;
+    /**
+     * Diff baseline group: a dump is diffed against the previous dump of the
+     * same session and channel (for example, one per transport).
+     */
+    channel: string;
+    /** Finer label for the filename, e.g. prewarm or main; it does not split the baseline. */
+    phase?: string;
+    bodyText: string;
+    accountId?: string;
+    url?: string;
+    method?: string;
+    headers?: ConstructorParameters<typeof Headers>[0];
+    status?: number;
+    error?: string;
+    /** Extra metadata, redacted like the body. */
+    meta?: Record<string, unknown>;
+}
+export interface DumpDiff {
+    changed: boolean;
+    firstByte: number;
+    lastPreviousByte: number;
+    lastCurrentByte: number;
+    changedPreviousBytes?: number;
+    changedCurrentBytes?: number;
+    previousBytes: number;
+    currentBytes: number;
+}
+export interface DumpResult {
+    id: string;
+    files: {
+        body: string;
+        metadata: string;
+        request: string;
+    };
+}
+export interface Dumper {
+    isEnabled(): boolean;
+    setEnabled(enabled: boolean): void;
+    /**
+     * Write `<id>.body.json`, `<id>.meta.json` and `<id>.request.json`. Returns
+     * undefined when dumps are off or the write failed; dumping is diagnostic
+     * and never throws into the request path.
+     */
+    dump(input: DumpInput): Promise<DumpResult | undefined>;
+}
+/**
+ * Where two bodies first and last differ, in string offsets into the dumped
+ * (redacted) text. Offsets count UTF-16 units, as the plugins' cache analysis
+ * always has.
+ */
+export declare function diffDumpBodies(previous: string | undefined, current: string): DumpDiff | null;
+export declare function createDumper(options: DumpOptions): Dumper;