@cortexkit/common-auth 0.2.4 → 0.2.5

package/dist/auth-menu/terminal.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The terminal the menu draws on and reads keys from. The process's own
+ * stdin and stdout satisfy it; tests pass a scripted stand-in, so the full
+ * key-in, frame-out path runs without a real TTY.
+ */
+export interface MenuTerminal {
+    input: MenuInput;
+    output: MenuOutput;
+    /**
+     * Where SIGINT and SIGTERM are heard while a selector holds raw mode, so a
+     * kill restores the terminal. Defaults to nothing: raw mode turns Ctrl-C
+     * into a key the selector already handles.
+     */
+    signals?: MenuSignals;
+}
+export interface MenuInput {
+    /** True only on an interactive terminal; anything else gets a plain list. */
+    readonly isTTY?: boolean;
+    readonly isRaw?: boolean;
+    setRawMode(mode: boolean): unknown;
+    resume(): unknown;
+    pause(): unknown;
+    on(event: 'data', listener: (data: Buffer | string) => void): unknown;
+    removeListener(event: 'data', listener: (data: Buffer | string) => void): unknown;
+}
+export interface MenuOutput {
+    write(text: string): unknown;
+    readonly columns?: number;
+    readonly rows?: number;
+}
+export interface MenuSignals {
+    once(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+    removeListener(signal: 'SIGINT' | 'SIGTERM', listener: () => void): unknown;
+}
+/** The current process's terminal, with its signals. */
+export declare function processTerminal(): MenuTerminal;
+/**
+ * Whether keys can be read one at a time. Only the input is checked, as the
+ * plugins' menus always did: output piped to a file still gets the menu.
+ */
+export declare function isInteractive(terminal: MenuTerminal): boolean;
+/** Writes one line of plain output below the menu. */
+export declare function printLine(terminal: MenuTerminal, line?: string): void;

package/dist/auth-menu/terminal.js

@@ -0,0 +1,19 @@
+/** The current process's terminal, with its signals. */
+export function processTerminal() {
+    return {
+        input: process.stdin,
+        output: process.stdout,
+        signals: process,
+    };
+}
+/**
+ * Whether keys can be read one at a time. Only the input is checked, as the
+ * plugins' menus always did: output piped to a file still gets the menu.
+ */
+export function isInteractive(terminal) {
+    return terminal.input.isTTY === true;
+}
+/** Writes one line of plain output below the menu. */
+export function printLine(terminal, line = '') {
+    terminal.output.write(`${line}\n`);
+}

package/dist/cachekeep/index.d.ts

@@ -1 +1,4 @@
-export {};
+export type { CacheKeepAdapter, CacheKeepBackoff, CacheKeepLogger, CacheKeepManagerOptions, CacheKeepProfile, CacheKeepSendInput, CacheKeepStatus, CacheKeepTargetStatus, CacheKeepTargetView, CacheKeepTrackInput, CacheKeepTrackResult, } from './manager.js';
+export { CacheKeepManager } from './manager.js';
+export type { CacheKeepWindow } from './window.js';
+export { isWithinCacheKeepWindow, normalizeCacheKeepWindow, } from './window.js';

package/dist/cachekeep/index.js

@@ -1,2 +1,2 @@
-// Placeholder so the export resolves until this subpath is built.
-export {};
+export { CacheKeepManager } from './manager.js';
+export { isWithinCacheKeepWindow, normalizeCacheKeepWindow, } from './window.js';

package/dist/cachekeep/manager.d.ts

@@ -0,0 +1,214 @@
+import { type CacheKeepWindow } from './window.js';
+export interface CacheKeepLogger {
+    debug(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+}
+/**
+ * Per-target overrides a plugin derives from the captured request, usually
+ * from its model: how long the provider keeps that model's prompt cache, how
+ * many warms a session of that kind is worth, and how long it may sit idle.
+ * Evaluated once at capture time and kept on the target.
+ */
+export interface CacheKeepProfile {
+    /** Provider cache lifetime for this request; defaults to the manager's `ttlMs`. */
+    ttlMs?: number;
+    /** Drop the target after this many successful warms; unlimited when absent. */
+    maxWarms?: number;
+    /** Idle bound replacing the main or subagent default for this target. */
+    maxIdleMs?: number;
+}
+/** What the plugin sees of a tracked target. */
+export interface CacheKeepTargetView<M> {
+    sessionKey: string;
+    accountId: string | undefined;
+    bodyText: string;
+    isSubagent: boolean;
+    meta: M;
+    warmCount: number;
+    ttlMs: number;
+}
+export interface CacheKeepSendInput<M> {
+    target: CacheKeepTargetView<M>;
+    /** The replay body `buildBody` returned. */
+    body: string;
+    /** Aborted on the warm timeout and when the manager stops. */
+    signal: AbortSignal;
+}
+/**
+ * The provider half of keep-warm. The manager decides when and what to warm;
+ * the plugin turns a captured request into a replay, resolves the account's
+ * credential, sends it and reads usage back.
+ */
+export interface CacheKeepAdapter<M> {
+    /** Build the replay body from the captured one. A throw backs the target off. */
+    buildBody(target: CacheKeepTargetView<M>): string | Promise<string>;
+    /**
+     * Resolve the target account's credential and send the replay. A throw
+     * (including "no credential") or a non-2xx response backs the target off.
+     */
+    send(input: CacheKeepSendInput<M>): Promise<Response>;
+    /** Read usage from a successful response, for the log line only. */
+    readUsage?(input: {
+        target: CacheKeepTargetView<M>;
+        response: Response;
+        text: string;
+    }): Record<string, unknown> | undefined;
+    /** Per-target TTL, warm cap and idle bound, from the captured request. */
+    profile?(input: {
+        bodyText: string;
+        isSubagent: boolean;
+        accountId: string | undefined;
+        meta: M;
+    }): CacheKeepProfile | undefined;
+    /**
+     * The account the session routes to now, asked before every warm. A
+     * different account than the one that served the captured request drops
+     * the target: its cache lives on the old account, which the session has
+     * left, and replaying on the new one would only write a cache nobody asked
+     * for. `undefined` means the plugin holds no session-to-account binding and
+     * the captured account stands. A throw backs the target off.
+     */
+    activeAccount?(sessionKey: string, target: CacheKeepTargetView<M>): string | undefined | Promise<string | undefined>;
+}
+export type CacheKeepBackoff = number | ((input: {
+    sessionKey: string;
+    failures: number;
+}) => number);
+export interface CacheKeepManagerOptions<M> {
+    adapter: CacheKeepAdapter<M>;
+    now: () => number;
+    logger?: CacheKeepLogger;
+    /** Default provider cache lifetime. Default 5 minutes. */
+    ttlMs?: number;
+    /** Warm this long before the cache expires. Default one tick plus 15 s. */
+    leadMs?: number;
+    /** Idle bound for main sessions, from their last real request. Default 1 h. */
+    maxIdleWarmMs?: number;
+    /** Idle bound for subagent sessions. Default 30 minutes. */
+    maxSubagentIdleMs?: number;
+    /** How often the timer runs a tick. Default 60 s. */
+    tickIntervalMs?: number;
+    /** Most sessions tracked at once. Default 32. */
+    maxTargets?: number;
+    /** Total captured body bytes (UTF-8). Default 8 MiB. */
+    maxBytes?: number;
+    /** One deadline for credential resolution and the send. Default 30 s. */
+    warmTimeoutMs?: number;
+    /** Delay after a failed warm, fixed or by consecutive failures. Default 10 minutes. */
+    backoffMs?: CacheKeepBackoff;
+    /** The configured clock window; undefined means always warm. Read on every call. */
+    getWindow?: () => CacheKeepWindow | undefined;
+    /** When true, main sessions are exempt from idle pruning. Read on every call. */
+    getSustain?: () => boolean;
+    setIntervalImpl?: typeof globalThis.setInterval;
+    clearIntervalImpl?: typeof globalThis.clearInterval;
+}
+export type CacheKeepTrackResult = {
+    tracked: true;
+} | {
+    tracked: false;
+    reason: 'body-exceeds-max-bytes' | 'outside-window';
+};
+export type CacheKeepTrackInput<M> = {
+    sessionKey: string;
+    bodyText: string;
+    /** The account that served this request; the one a warm replays on. */
+    accountId?: string;
+    isSubagent?: boolean;
+} & (undefined extends M ? {
+    /** Plugin data handed back to the adapter, e.g. replay headers. */ meta?: M;
+} : {
+    /** Plugin data handed back to the adapter, e.g. replay headers. */ meta: M;
+});
+export interface CacheKeepTargetStatus {
+    sessionKey: string;
+    accountId: string | undefined;
+    isSubagent: boolean;
+    cacheExpiresAt: number;
+    lastRealRequestAt: number;
+    lastWarmedAt?: number;
+    backoffUntil?: number;
+    failures: number;
+    warmCount: number;
+    ttlMs: number;
+    bodyBytes: number;
+}
+export interface CacheKeepStatus {
+    running: boolean;
+    tracked: number;
+    totalBytes: number;
+    generatedAt: number;
+    startedAt: number | null;
+    ttlMs: number;
+    leadMs: number;
+    maxIdleWarmMs: number;
+    maxSubagentIdleMs: number;
+    sustain: boolean;
+    window?: CacheKeepWindow;
+    targets: CacheKeepTargetStatus[];
+}
+/**
+ * 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 declare class CacheKeepManager<M = undefined> {
+    private readonly targets;
+    private readonly adapter;
+    private readonly now;
+    private readonly log;
+    private readonly ttlMs;
+    private readonly leadMs;
+    private readonly maxIdleWarmMs;
+    private readonly maxSubagentIdleMs;
+    private readonly tickIntervalMs;
+    private readonly maxTargets;
+    private readonly maxBytes;
+    private readonly warmTimeoutMs;
+    private readonly backoff;
+    private readonly getWindow;
+    private readonly getSustain;
+    private readonly setIntervalImpl;
+    private readonly clearIntervalImpl;
+    private timer;
+    private startedAt;
+    private totalBytes;
+    private tickPromise;
+    private disposed;
+    private abortController;
+    constructor(options: CacheKeepManagerOptions<M>);
+    /**
+     * 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: CacheKeepTrackInput<M>): CacheKeepTrackResult;
+    /** Forget a session, e.g. when the host deletes it. */
+    remove(sessionKey: string): void;
+    start(): void;
+    /** Disarm, abort any warm in flight and forget every target. */
+    stop(): void;
+    /** A snapshot without captured bodies, which can hold prompt content. */
+    status(): CacheKeepStatus;
+    /**
+     * 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(): Promise<void>;
+    private runTick;
+    private isCurrent;
+    private view;
+    private fail;
+    private warm;
+    private idleDefault;
+    private pruneStale;
+    private leastRecentlyTouched;
+    private drop;
+}