@cortexkit/common-auth 0.2.4 → 0.2.6

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/commands/builtins.d.ts

@@ -0,0 +1,71 @@
+import type { AddInput, PoolLockSpec, PoolRow, PoolStore, RemoveOptions } from '../store/index.js';
+import type { CommandInvocation, KnobValues, MenuChoice, MenuKnob } from './model.js';
+import type { ResolvedSection } from './seam.js';
+/**
+ * What a plugin's login hands back. `ready` adds the account now. `pending`
+ * means the user must finish somewhere else (a browser, a device code):
+ * `message` tells them how, and the account is added when `completion`
+ * settles, with the result sent to the invocation that started it.
+ */
+export type LoginOutcome = {
+    status: 'ready';
+    account: AddInput;
+} | {
+    status: 'pending';
+    message: string;
+    /** Resolves with the account to add, or undefined when the user gave up. */
+    completion: Promise<AddInput | undefined>;
+} | {
+    status: 'cancelled';
+    message?: string;
+};
+export interface AccountsSectionOptions {
+    /** What to show as an account's identity; defaults to its recorded identity. */
+    describeIdentity?(row: PoolRow): string | undefined;
+    /** The plugin's login; without it the section offers no add action. */
+    login?: {
+        label?: string;
+        knobs?: MenuKnob[];
+        run(values: KnobValues, invocation: CommandInvocation): Promise<LoginOutcome>;
+    };
+    /** Passed to `store.remove`: a reason refuses removing that id. */
+    protect?: RemoveOptions['protect'];
+}
+export interface QuotaSectionOptions {
+    /** The quota scope to show (`all` or a model family); defaults to `all`. */
+    scope?: string;
+    /**
+     * Checks quota now for the named rows. Without it, the menu asks the store
+     * for a reading of each row and waits for the pulls to settle.
+     */
+    check?(ids: readonly string[], invocation: CommandInvocation): Promise<void>;
+}
+export interface RoutingSectionOptions {
+    /**
+     * Further `routing.mode` values the plugin routes as `ordered` with the
+     * former main row moved (`main-first`, `fallback-first`), offered between
+     * `ordered` and `sticky-balanced`.
+     */
+    orderedVariants?: MenuChoice[];
+    formerMainId?: string;
+}
+export interface LimitsSectionOptions {
+    /**
+     * The quota window labels a floor can be set for. Defaults to every label
+     * the pool's quota readings carry, or `primary` when there are none.
+     */
+    labels?: readonly string[];
+}
+export interface BuiltinOptions {
+    store: PoolStore;
+    extraLocks?: readonly PoolLockSpec[];
+    now: () => number;
+    accounts?: AccountsSectionOptions;
+    quota?: QuotaSectionOptions;
+    routing?: RoutingSectionOptions;
+    limits?: LimitsSectionOptions;
+}
+/** `disabledReason` recorded when the user disables an account from the menu. */
+export declare const MENU_DISABLED_REASON = "disabled from the command menu";
+/** The four built-in sections, in their fixed order, from one read of the store. */
+export declare function builtinSections(options: BuiltinOptions): Promise<ResolvedSection[]>;