@cortexkit/opencode-antigravity-auth 2.2.1 → 3.0.1

package/src/common-auth-embedded/routing/sticky.js

@@ -0,0 +1,339 @@
+// `sticky-balanced` routing: openai-auth's quota-weighted session placement
+// and pin-break classification, judged over the quota projection rather than
+// openai-auth's fixed primary/secondary snapshot.
+import { budgetExhaustedResetAt, projectQuota, } from '../quota/projection.js';
+import { admit, } from './admission.js';
+import { isPinValid } from './pins.js';
+export const QUOTA_STALENESS_MS = 15 * 60_000;
+export const MIN_RESET_HOURS = 1 / 60;
+export const MIN_WEIGHT = 1e-6;
+/** The projection's time, else the caller's cache-entry time. */
+export function snapshotCheckedAt(quota, entryCheckedAt) {
+    for (const checkedAt of [quota?.checkedAt, entryCheckedAt]) {
+        if (typeof checkedAt === 'number' && Number.isFinite(checkedAt)) {
+            return checkedAt;
+        }
+    }
+    return undefined;
+}
+/**
+ * The status rule used when the adapter supplies none, carried from
+ * openai-auth: 401 and 403 are permanent; no response, 0, a non-finite
+ * status, 429 and 5xx are transient; anything else leaves the row healthy.
+ * A provider whose 403 can mean an organisation or model policy rather than
+ * a dead account supplies its own classifier and can fall back to this one
+ * for the statuses it does not single out.
+ */
+export function defaultStickyStatusClass(status) {
+    if (status === 401 || status === 403)
+        return 'permanent';
+    if (status === undefined ||
+        status === 0 ||
+        !Number.isFinite(status) ||
+        (status >= 500 && status <= 599) ||
+        status === 429) {
+        return 'transient';
+    }
+    return 'healthy';
+}
+function windowReadings(quota) {
+    // Every reading is an independent constraint, so all of them are judged:
+    // a third window (for example a short window beside two weekly ones) can
+    // be the one that is nearly spent. Longest known window first, unknown
+    // lengths last, as openai-auth sorts, so a break decision with several
+    // spent windows names the longest. Tombstones and absence records carry no
+    // capacity figure and are left out.
+    return quota.limits
+        .filter((limit) => limit.kind === 'reading')
+        .sort((left, right) => {
+        const leftKnown = left.windowMinutes !== undefined;
+        const rightKnown = right.windowMinutes !== undefined;
+        if (leftKnown !== rightKnown)
+            return leftKnown ? -1 : 1;
+        if (leftKnown && rightKnown) {
+            return (right.windowMinutes ?? 0) - (left.windowMinutes ?? 0);
+        }
+        return 0;
+    });
+}
+/** Classifies whether a pinned session should leave its row after a failure. */
+export function decideStickyBreak(input) {
+    const statusClass = (input.classifyStatus ?? defaultStickyStatusClass)(input.status);
+    if (statusClass === 'permanent') {
+        return { action: 'migrate', reason: 'permanent' };
+    }
+    if (!input.quota)
+        return { action: 'retain', reason: 'unknown' };
+    const checkedAt = snapshotCheckedAt(input.quota, input.quotaCheckedAt);
+    if (checkedAt === undefined ||
+        !Number.isFinite(checkedAt) ||
+        input.now - checkedAt > QUOTA_STALENESS_MS) {
+        return { action: 'retain', reason: 'stale' };
+    }
+    // After the stale check, so a stale snapshot never judges the account on a
+    // reading the killswitch would consider below its floor.
+    if (input.killswitchPasses === false) {
+        return { action: 'migrate', reason: 'killswitch' };
+    }
+    for (const limit of windowReadings(input.quota)) {
+        const remaining = limit.remainingPercent;
+        if (typeof remaining === 'number' &&
+            Number.isFinite(remaining) &&
+            remaining <= 0) {
+            return {
+                action: 'migrate',
+                reason: 'exhausted',
+                window: { scope: limit.scope, label: limit.label },
+                ...(typeof limit.resetsAt === 'string'
+                    ? { resetsAt: limit.resetsAt }
+                    : {}),
+            };
+        }
+    }
+    // A reached credit budget is exhaustion on its own axis, judged by the same
+    // signal admission uses so the two never disagree on what "spent" means.
+    const budgetReset = budgetExhaustedResetAt(input.quota, input.now);
+    if (budgetReset) {
+        return {
+            action: 'migrate',
+            reason: 'exhausted',
+            resetsAt: budgetReset.resetsAt,
+        };
+    }
+    return { action: 'retain', reason: statusClass };
+}
+export function sustainableWindowWeight(window, reservePercent, now) {
+    const spendable = Math.max(0, window.remainingPercent - reservePercent);
+    if (spendable <= 0)
+        return 0;
+    if (!window.resetsAt)
+        return spendable;
+    const resetMs = Date.parse(window.resetsAt);
+    // A lapsed reset cannot yield a spend rate: the divisor would clamp to
+    // MIN_RESET_HOURS and inflate the weight about sixty-fold on stale
+    // information, so the un-rate-adjusted spendable capacity is used instead.
+    if (!Number.isFinite(resetMs) || resetMs <= now)
+        return spendable;
+    const hours = Math.max((resetMs - now) / 3_600_000, MIN_RESET_HOURS);
+    return spendable / hours;
+}
+function compareAccountIds(left, right) {
+    if (left < right)
+        return -1;
+    if (left > right)
+        return 1;
+    return 0;
+}
+function candidateWeight(candidate, now) {
+    if (!candidate.quota)
+        return undefined;
+    const quotaCheckedAt = snapshotCheckedAt(candidate.quota, candidate.quotaCheckedAt);
+    if (quotaCheckedAt === undefined ||
+        now - quotaCheckedAt > QUOTA_STALENESS_MS) {
+        return undefined;
+    }
+    // Missing reserve data must leave a window usable rather than silently
+    // excluding its account.
+    // The account is as constrained as its tightest window, whichever it is.
+    const weights = windowReadings(candidate.quota).map((limit) => sustainableWindowWeight({
+        remainingPercent: limit.remainingPercent ?? Number.NaN,
+        ...(limit.resetsAt === undefined ? {} : { resetsAt: limit.resetsAt }),
+    }, candidate.reservePercent[limit.label] ?? 0, now));
+    // The credit budget is a third pressure axis on its own reset clock. It has
+    // no configured reserve, and a malformed reading is ignored rather than
+    // allowed to zero the account's weight.
+    const budget = candidate.quota.budget;
+    if (budget &&
+        typeof budget.remainingPercent === 'number' &&
+        Number.isFinite(budget.remainingPercent)) {
+        weights.push(sustainableWindowWeight({
+            remainingPercent: budget.remainingPercent,
+            ...(budget.resetsAt === undefined
+                ? {}
+                : { resetsAt: budget.resetsAt }),
+        }, 0, now));
+    }
+    const weight = weights.length > 0 ? Math.min(...weights) : 0;
+    return weight > 0 ? { candidate, quotaCheckedAt, weight } : undefined;
+}
+/**
+ * Places a session: the lowest projected pressure among candidates with a
+ * fresh positive weight, else (`mode-fallback`) the first candidate in
+ * configured order, preferring one with an applicable reset credit.
+ */
+export function selectStickyCandidate(input) {
+    // A candidate killed by the killswitch is excluded from BOTH weighted
+    // placement and the fallback branch, which must never become a way to
+    // spend on a killed account.
+    const eligibleCandidates = input.candidates.filter((candidate) => candidate.killswitchPasses !== false);
+    if (input.candidates.length === 0) {
+        throw new Error('Cannot select a sticky candidate: input.candidates is empty');
+    }
+    if (eligibleCandidates.length === 0)
+        return undefined;
+    const weighted = eligibleCandidates
+        .map((candidate) => candidateWeight(candidate, input.now))
+        .filter((candidate) => candidate !== undefined);
+    if (weighted.length > 0) {
+        weighted.sort((left, right) => {
+            // MIN_WEIGHT only guards the division; every weight here is positive.
+            const leftScore = ((input.pendingBytes.get(left.candidate.accountId) ?? 0) +
+                input.requestBytes) /
+                Math.max(left.weight, MIN_WEIGHT);
+            const rightScore = ((input.pendingBytes.get(right.candidate.accountId) ?? 0) +
+                input.requestBytes) /
+                Math.max(right.weight, MIN_WEIGHT);
+            return (leftScore - rightScore ||
+                left.candidate.configuredOrder - right.candidate.configuredOrder ||
+                compareAccountIds(left.candidate.accountId, right.candidate.accountId));
+        });
+        const selected = weighted[0];
+        if (selected) {
+            return {
+                accountId: selected.candidate.accountId,
+                quotaCheckedAt: selected.quotaCheckedAt,
+                source: 'weighted',
+            };
+        }
+    }
+    input.onEmptyWeightedSet?.();
+    const fallback = [...eligibleCandidates].sort((left, right) => {
+        const leftHasCredits = (left.resetCreditsApplicable ?? 0) > 0 ? 1 : 0;
+        const rightHasCredits = (right.resetCreditsApplicable ?? 0) > 0 ? 1 : 0;
+        return (rightHasCredits - leftHasCredits ||
+            left.configuredOrder - right.configuredOrder ||
+            compareAccountIds(left.accountId, right.accountId));
+    })[0];
+    if (!fallback) {
+        throw new Error('Cannot select a sticky candidate: input.candidates is empty');
+    }
+    return {
+        accountId: fallback.accountId,
+        quotaCheckedAt: snapshotCheckedAt(fallback.quota, fallback.quotaCheckedAt),
+        source: 'mode-fallback',
+    };
+}
+/**
+ * Routes one request in `sticky-balanced` mode. A valid pin whose row is
+ * admitted, not excluded and not killed is dispatched as is. Otherwise
+ * selection runs over the non-excluded rows; each selected row admission
+ * refused is removed and selection re-runs, so the loop ends either on an
+ * admitted row or with no admissible account.
+ */
+export function routeSticky(input) {
+    const admission = admit(input);
+    const admitted = new Map(admission.admitted.map((row) => [row.id, row]));
+    const refusals = new Map(admission.refused.map((r) => [r.id, r]));
+    const excluded = new Set(admission.excluded.map((row) => row.id));
+    const validIds = new Set(input.rows.map((row) => row.id));
+    const pinValid = input.pin !== undefined &&
+        isPinValid(input.pin, validIds, input.identities?.get(input.pin.accountId));
+    if (pinValid && input.pin) {
+        const pinned = admitted.get(input.pin.accountId);
+        if (pinned && input.killswitch?.get(pinned.id) !== false) {
+            return {
+                outcome: 'dispatch',
+                accountId: pinned.id,
+                source: 'pin',
+                ...(pinned.projection?.checkedAt === undefined
+                    ? {}
+                    : { quotaCheckedAt: pinned.projection.checkedAt }),
+                pin: { action: 'retain' },
+                refusedSelections: [],
+                admission,
+            };
+        }
+    }
+    // A spent window with a future reset, a spent credit budget and a killswitch
+    // verdict all say the pinned row will not serve until some known later time,
+    // so the pin may move. A row refused for want of a usable reading, or
+    // excluded by a short rate-limit mark or refresh backoff, may serve again on
+    // the next reading, so its pin stays.
+    const pinRefusal = input.pin ? refusals.get(input.pin.accountId) : undefined;
+    const pinMoves = pinValid &&
+        input.pin !== undefined &&
+        input.refusedPinPolicy === 'move-on-confirmed-exhaustion' &&
+        (input.killswitch?.get(input.pin.accountId) === false ||
+            pinRefusal?.reason === 'exhausted' ||
+            pinRefusal?.reason === 'budget-spent');
+    const reserveFor = (row) => {
+        const perRow = typeof input.rowReservePercent === 'function'
+            ? input.rowReservePercent(row)
+            : input.rowReservePercent?.get(row.id);
+        return perRow ?? input.reservePercent ?? {};
+    };
+    const scope = input.scope;
+    let candidates = input.rows
+        .map((row, configuredOrder) => ({ row, configuredOrder }))
+        .filter(({ row }) => !excluded.has(row.id))
+        .map(({ row, configuredOrder }) => {
+        const killswitchPasses = input.killswitch?.get(row.id);
+        const credits = input.resetCreditsApplicable?.get(row.id);
+        return {
+            accountId: row.id,
+            quota: row.kind === 'api-key'
+                ? undefined
+                : (admitted.get(row.id)?.projection ??
+                    projectQuota(row.quota, scope)),
+            reservePercent: reserveFor(row),
+            configuredOrder,
+            ...(credits === undefined ? {} : { resetCreditsApplicable: credits }),
+            ...(killswitchPasses === undefined ? {} : { killswitchPasses }),
+        };
+    });
+    const refusedSelections = [];
+    const unplaced = pinValid
+        ? { action: 'retain' }
+        : input.pin
+            ? { action: 'clear' }
+            : { action: 'none' };
+    while (candidates.length > 0) {
+        const selection = selectStickyCandidate({
+            candidates,
+            pendingBytes: input.pendingBytes ?? new Map(),
+            requestBytes: input.requestBytes,
+            now: input.now,
+            ...(input.onEmptyWeightedSet
+                ? { onEmptyWeightedSet: input.onEmptyWeightedSet }
+                : {}),
+        });
+        if (!selection)
+            break;
+        const refusal = refusals.get(selection.accountId);
+        if (refusal) {
+            refusedSelections.push(refusal);
+            candidates = candidates.filter((candidate) => candidate.accountId !== selection.accountId);
+            continue;
+        }
+        const identity = input.identities?.get(selection.accountId);
+        return {
+            outcome: 'dispatch',
+            accountId: selection.accountId,
+            source: selection.source,
+            ...(selection.quotaCheckedAt === undefined
+                ? {}
+                : { quotaCheckedAt: selection.quotaCheckedAt }),
+            pin: pinValid && !pinMoves
+                ? { action: 'retain' }
+                : {
+                    action: 'assign',
+                    pin: {
+                        accountId: selection.accountId,
+                        inputBytes: input.requestBytes,
+                        ...(identity === undefined ? {} : { wireIdentity: identity }),
+                        ...(selection.quotaCheckedAt === undefined
+                            ? {}
+                            : { quotaCheckedAt: selection.quotaCheckedAt }),
+                    },
+                },
+            refusedSelections,
+            admission,
+        };
+    }
+    return {
+        outcome: 'no-admissible-account',
+        pin: unplaced,
+        refusedSelections,
+        admission,
+    };
+}

package/src/common-auth-embedded/rpc/client.d.ts

@@ -0,0 +1,3 @@
+export type { ApplyRequest, ApplyResult, OpenDialogPayload, RpcNotification, } from './notifications.js';
+export { type DiscoverPortFileOptions, discoverPortFile, type PortFileEntry, } from './port-file.js';
+export * from './rpc-client.js';

package/src/common-auth-embedded/rpc/client.js

@@ -0,0 +1,2 @@
+export { discoverPortFile, } from './port-file.js';
+export * from './rpc-client.js';

package/src/common-auth-embedded/rpc/index.d.ts

@@ -0,0 +1,10 @@
+export * from './notifications.js';
+export * from './port-file.js';
+export * from './rpc-client.js';
+export * from './rpc-server.js';
+export * from './server-registry.js';
+/** Pass methods bound to the caller’s logger channel; RPC uses no-op methods when no logger is supplied. */
+export interface RpcLogChannel {
+    warn(message: string, data?: unknown): void;
+    debug(message: string, data?: unknown): void;
+}

package/src/common-auth-embedded/rpc/index.js

@@ -0,0 +1,5 @@
+export * from './notifications.js';
+export * from './port-file.js';
+export * from './rpc-client.js';
+export * from './rpc-server.js';
+export * from './server-registry.js';

package/src/common-auth-embedded/rpc/notifications.d.ts

@@ -0,0 +1,73 @@
+export interface ApplyRequest {
+    command: string;
+    arguments: string;
+    sessionId?: string;
+}
+export interface ApplyResult {
+    text: string;
+    knobs: Record<string, unknown>;
+}
+export interface OpenDialogPayload {
+    command: string;
+    text: string;
+    knobs: Record<string, unknown>;
+}
+export interface RpcNotification {
+    id: number;
+    type: 'open-dialog';
+    payload: OpenDialogPayload;
+    sessionId?: string;
+}
+export interface NotificationScope {
+    rpcRoot: string;
+    directoryPrefix: string;
+    registrationSessionId: string;
+    /**
+     * Strict session isolation. When true, `pushNotification` and
+     * `drainNotifications` refuse an absent or empty session id (throwing
+     * `RpcSessionRequiredError`) and a drain returns only that session's own
+     * notifications: no notification reaches every session. A strict scope is
+     * a separate queue from the same scope without the flag, so a lenient
+     * caller cannot push into it or drain it.
+     *
+     * Off by default: without it, a drain with no session returns every
+     * session's notifications and a push with no session reaches every
+     * session, which plugins that drain from one process-wide TUI rely on.
+     */
+    requireSession?: boolean;
+    /**
+     * What a drain with no session id returns, and what it acknowledges.
+     *
+     * - `'all'` (default): every queued notification, broadcasts and every
+     *   session's targeted ones; a sessionless acknowledgement removes
+     *   nothing. A plugin that drains from one process-wide TUI relies on this.
+     * - `'broadcast-only'`: broadcasts only (notifications pushed without a
+     *   session), never a session's targeted ones, for a TUI that polls before
+     *   it knows its session. A sessionless acknowledgement removes the
+     *   acknowledged broadcasts and leaves every targeted notification queued.
+     *   It also answers `isTuiConnected(scope, undefined)`: true while any
+     *   drain on the queue, with or without a session, happened within the
+     *   connection window.
+     *
+     * The option governs each call made with this scope; it does not split the
+     * queue, so a push through a scope without it lands in the same queue.
+     */
+    sessionlessDrain?: 'all' | 'broadcast-only';
+}
+/** A strict notification scope was used without a session id. */
+export declare class RpcSessionRequiredError extends Error {
+    readonly operation: 'push' | 'drain';
+    constructor(operation: 'push' | 'drain');
+}
+/** True for a session id a strict scope accepts: a non-empty string. */
+export declare function isSessionId(value: unknown): value is string;
+export declare function pushNotification(scope: NotificationScope, payload: OpenDialogPayload, sessionId?: string): void;
+export declare function drainNotifications(scope: NotificationScope, lastReceivedId?: number, sessionId?: string): RpcNotification[];
+/**
+ * True when a TUI drained within the last 3000 ms. With a session id, that
+ * session drained. Without one, a broadcast-only scope answers whether any
+ * drain happened; a default scope answers false, since it only tracks
+ * sessions.
+ */
+export declare function isTuiConnected(scope: NotificationScope, sessionId: string | undefined): boolean;
+export declare function resetNotificationsForTest(scope: NotificationScope): void;

package/src/common-auth-embedded/rpc/notifications.js

@@ -0,0 +1,100 @@
+/** A strict notification scope was used without a session id. */
+export class RpcSessionRequiredError extends Error {
+    operation;
+    constructor(operation) {
+        super(`a ${operation} on a strict notification scope needs a session id`);
+        this.name = 'RpcSessionRequiredError';
+        this.operation = operation;
+    }
+}
+/** True for a session id a strict scope accepts: a non-empty string. */
+export function isSessionId(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+const queues = new Map();
+function state(scope) {
+    const key = JSON.stringify([
+        scope.rpcRoot,
+        scope.directoryPrefix,
+        scope.registrationSessionId,
+        ...(scope.requireSession === true ? ['strict'] : []),
+    ]);
+    let value = queues.get(key);
+    if (!value) {
+        value = {
+            queue: [],
+            nextId: 1,
+            lastDrainAtBySession: new Map(),
+            lastDrainAtAny: 0,
+        };
+        queues.set(key, value);
+    }
+    return value;
+}
+const QUEUE_CAP = 100;
+const TUI_CONNECTED_WINDOW_MS = 3_000;
+export function pushNotification(scope, payload, sessionId) {
+    if (scope.requireSession === true && !isSessionId(sessionId))
+        throw new RpcSessionRequiredError('push');
+    const value = state(scope);
+    value.queue.push({
+        id: value.nextId++,
+        type: 'open-dialog',
+        payload,
+        sessionId,
+    });
+    if (value.queue.length > QUEUE_CAP)
+        value.queue = value.queue.slice(-QUEUE_CAP);
+}
+export function drainNotifications(scope, lastReceivedId = 0, sessionId) {
+    // A strict queue holds only session-scoped notifications (its push refuses
+    // the rest), so the ordinary match below already gives a strict drain
+    // nothing but its own session's notifications.
+    if (scope.requireSession === true && !isSessionId(sessionId))
+        throw new RpcSessionRequiredError('drain');
+    const value = state(scope);
+    const now = Date.now();
+    value.lastDrainAtAny = now;
+    if (sessionId !== undefined)
+        value.lastDrainAtBySession.set(sessionId, now);
+    const broadcastOnly = scope.sessionlessDrain === 'broadcast-only';
+    const matches = (n) => sessionId === undefined
+        ? !broadcastOnly || n.sessionId === undefined
+        : n.sessionId === undefined || n.sessionId === sessionId;
+    if (lastReceivedId > 0) {
+        value.queue = value.queue.filter((n) => {
+            if (n.id > lastReceivedId)
+                return true;
+            // A sessionless ack in broadcast-only mode consumes the broadcasts it
+            // was shown; in the default mode it consumes nothing, since it was
+            // shown targeted notifications other sessions still have to receive.
+            if (sessionId === undefined)
+                return !broadcastOnly || n.sessionId !== undefined;
+            return n.sessionId !== sessionId;
+        });
+    }
+    return value.queue.filter((n) => n.id > lastReceivedId && matches(n));
+}
+/**
+ * True when a TUI drained within the last 3000 ms. With a session id, that
+ * session drained. Without one, a broadcast-only scope answers whether any
+ * drain happened; a default scope answers false, since it only tracks
+ * sessions.
+ */
+export function isTuiConnected(scope, sessionId) {
+    const now = Date.now();
+    const value = state(scope);
+    const at = sessionId !== undefined
+        ? (value.lastDrainAtBySession.get(sessionId) ?? 0)
+        : scope.sessionlessDrain === 'broadcast-only'
+            ? value.lastDrainAtAny
+            : 0;
+    return at > 0 && now - at < TUI_CONNECTED_WINDOW_MS;
+}
+export function resetNotificationsForTest(scope) {
+    const value = state(scope);
+    value.queue = [];
+    value.nextId = 1;
+    value.lastDrainAtBySession.clear();
+    value.lastDrainAtAny = 0;
+}

package/src/common-auth-embedded/rpc/port-file.d.ts

@@ -0,0 +1,33 @@
+import type { RpcLogChannel } from './index.js';
+export interface PortFileEntry {
+    port: number;
+    token: string;
+    pid: number;
+    startedAt: number;
+}
+export declare function createManagedRpcStateDirPredicate(directoryPrefix: string): (name: string) => boolean;
+export declare function isManagedRpcStateDir(name: string, directoryPrefix: string): boolean;
+export declare function getRpcDir(rpcRoot: string, directoryPrefix: string, projectDirectory: string): string;
+export declare function writePortFile(dir: string, entry: {
+    port: number;
+    token: string;
+    pid: number;
+}, options?: {
+    secureDir?: boolean;
+    beforeWrite?: () => void | Promise<void>;
+    /** Test seam for forcing staging-name collisions; defaults to randomUUID. */
+    stageName?: () => string;
+}): Promise<string>;
+export declare function sweepRpcState(root: string, activeDir: string, isManagedDir: (name: string) => boolean, log?: RpcLogChannel): Promise<void>;
+export interface DiscoverPortFileOptions {
+    /**
+     * Return only the expected PID's entry, or null; never fall back to
+     * another live server. Without an expected PID nothing matches, so the
+     * result is null. Off by default, when a missing or unmatched expected PID
+     * falls back to the newest live entry.
+     */
+    exactPid?: boolean;
+}
+/** Internal cache validation: probe only the selected file and its PID. */
+export declare function portFileIdentity(dir: string, entry: PortFileEntry): Promise<string | null>;
+export declare function discoverPortFile(dir: string, expectedPid?: number, options?: DiscoverPortFileOptions): Promise<PortFileEntry | null>;