@cortexkit/anthropic-auth-core 2.0.2 → 2.1.0

package/dist/internal-types/claustrum/watch.d.ts

@@ -0,0 +1,141 @@
+import type { ClaustrumLogger } from './errors.js';
+/**
+ * How a host currently learns about changes, for logs and status displays.
+ * `watching`: a watch was accepted and is open, so polling is reduced to a
+ * slow safety read. `polling`: no watch is open yet (not started, opening, or
+ * re-subscribing after a close), so the host polls at its usual interval.
+ * `fallback`: the watch is unavailable (an older module or client, a refusal,
+ * the watch limit, or repeated failures), so the host polls at its usual
+ * interval and may try a watch again later. Never carries secrets.
+ */
+export type WatchMode = 'watching' | 'polling' | 'fallback';
+/**
+ * While a vault watch is healthy, the roster is still read this often: the
+ * watch carries no history, so a lost notice or a silently dead stream is
+ * caught within this period.
+ */
+export declare const SAFETY_POLL_MS: number;
+/**
+ * After a watch fails without being accepted, the host polls and tries one
+ * new watch this much later, so a refusing or draining module is never asked
+ * in a tight loop.
+ */
+export declare const WATCH_RETRY_MS: number;
+/**
+ * First wait before re-subscribing a watch that closed after it had been
+ * accepted. It doubles for each further close in a row, up to WATCH_RETRY_MS.
+ */
+export declare const RESUBSCRIBE_BACKOFF_MS = 1000;
+/**
+ * The fields every change notice carries, from the vault's watchScoped and
+ * insula's usage.watch alike.
+ */
+export interface ChangeNotice {
+    readonly kind: string;
+    readonly epoch: string;
+    readonly seq: number;
+}
+/**
+ * Tells whether a notice follows the previous one with nothing lost between
+ * them. `seq` restarts at 1 for every watch and `epoch` names the sending
+ * module's process lifetime. A sequence gap (notices are sheddable), a
+ * different epoch (the module restarted) or a notice of an unknown kind all
+ * mean changes may have been missed, so the caller must re-read everything.
+ */
+export declare class ChangeNoticeReader {
+    #private;
+    /**
+     * Begin a new watch, whose first notice is seq 1 again. The epoch is kept,
+     * so a module restart between two watches still reads as a break.
+     */
+    restart(): void;
+    continuous(notice: ChangeNotice): boolean;
+}
+/**
+ * Runs `read` with at most one call in flight and at most one more queued
+ * behind it, however many requests arrive meanwhile. A request made while a
+ * read is running may have arrived after that read took its snapshot, so it
+ * earns exactly one more read; any further requests share that one.
+ */
+export declare class CoalescedRead {
+    #private;
+    constructor(read: () => Promise<void>, onError: (error: unknown) => void);
+    /** The read in flight (including its queued follow-up), if any. */
+    get running(): Promise<void> | undefined;
+    request(): Promise<void>;
+}
+/** A vault watch notice: `view` is the same digest `list_scoped` returns. */
+export interface ScopedWatchNoticeShape extends ChangeNotice {
+    readonly view: string;
+}
+/**
+ * How a vault watch ended, as claustrum-client 0.12.0 reports it. `refused`
+ * and `not_accepting` both mean the watch closed before its first notice; the
+ * client then made one `list_scoped` read to learn why, and `refused` carries
+ * that read's refusal.
+ */
+export type ScopedWatchEnd = {
+    readonly kind: 'refused';
+    readonly error: unknown;
+} | {
+    readonly kind: 'transport_lost';
+    readonly error: unknown;
+} | {
+    readonly kind: 'ended' | 'not_accepting' | 'unsupported' | 'stopped';
+};
+export interface ScopedWatchHandle {
+    stop(): void;
+    readonly closed: Promise<ScopedWatchEnd>;
+}
+/**
+ * The part of a vault client that can watch. claustrum-client added
+ * `watchScoped` in 0.12.0; the peer range still admits 0.6.2, so it is
+ * optional and detected at run time.
+ */
+export interface ScopedWatchSource {
+    watchScoped?(onNotice: (notice: ScopedWatchNoticeShape) => void, options?: {
+        enrollmentToken?: string;
+    }): ScopedWatchHandle;
+}
+export interface ScopedRosterWatchOptions {
+    client: ScopedWatchSource;
+    /** The enrollment token, read again for every watch so a new one is used. */
+    enrollmentToken: () => Promise<string>;
+    /** The view of the roster this host last discovered; undefined for none. */
+    view: () => string | undefined;
+    /**
+     * The host's existing discovery: `list_scoped`, the roster commit and
+     * everything that follows it. The watch never reads the vault list itself.
+     * `view` is the view the newest notice carried.
+     */
+    discover: (view: string) => Promise<unknown>;
+    /**
+     * The vault refused the watch, and the confirming `list_scoped` read it
+     * with this error (a revoked enrollment ends both with `not_found`). Handle
+     * it as discovery handles the same refusal from `list_scoped`.
+     */
+    onRefused: (error: unknown) => void;
+    onTransportLost?: () => void;
+    onReachable?: () => void;
+    onError?: (error: unknown) => void;
+    onMode?: (mode: WatchMode) => void;
+    logger?: ClaustrumLogger;
+    now?: () => number;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+}
+/**
+ * Keeps one vault `watchScoped` open for a host and runs the host's discovery
+ * when a notice shows the visible account list changed. Discovery runs only
+ * when the notice's view differs from the last discovered roster's view, when
+ * a notice shows a gap or a new epoch, or on the first notice of a watch that
+ * was re-subscribed after a close (the time between two watches was not
+ * observed). It never opens a second watch while one is open.
+ */
+export declare class ScopedRosterWatch {
+    #private;
+    constructor(options: ScopedRosterWatchOptions);
+    get mode(): WatchMode;
+    start(): void;
+    stop(): void;
+}

package/dist/internal-types/fs/refresh-file-lock.d.ts

@@ -13,7 +13,7 @@ export interface RefreshFileLock {
     whenLost(): Promise<LockLoss>;
     hasLost(): boolean;
 }
-export declare function acquireRefreshFileLock(options: {
+type RefreshFileLockOptions = {
     name: string;
     ttlMs: number;
     /**
@@ -22,7 +22,6 @@ export declare function acquireRefreshFileLock(options: {
      * be one host's path.
      */
     path: string;
-    now?: () => number;
     renew?: boolean;
     renewIntervalMs?: number;
     /** Notifies a live-owner refusal without awaiting; observer failures are ignored. */
@@ -30,4 +29,11 @@ export declare function acquireRefreshFileLock(options: {
     /** Synchronous, never awaited; throws and returned promise/thenable rejections are isolated. */
     onRenewalTimer?: (event: 'scheduled' | 'cancelled') => void;
     onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-observed' | 'lock-read-ready' | 'lock-missing' | 'stale-lock-confirmed' | 'stale-lock-removed' | 'stale-lock-recreated' | 'eviction-marker-acquired' | 'renewal-owner-confirmed' | 'renewal-marker-unavailable' | 'renewal-write-fenced' | 'renewal-write-ready' | 'renewal-write-finished' | 'relinquish-read' | 'renewal-finished' | 'release-owner-confirmed') => void | Promise<void>;
+};
+/** Filesystem leases share wall time across all callers and processes. */
+export declare function acquireRefreshFileLock(options: RefreshFileLockOptions): Promise<RefreshFileLock | null>;
+/** @internal Clock seam for lease tests; not exported by the package's fs entry point. */
+export declare function acquireRefreshFileLockWithClock(options: RefreshFileLockOptions & {
+    now?: () => number;
 }): Promise<RefreshFileLock | null>;
+export {};

package/dist/internal-types/quota/format.d.ts

@@ -11,8 +11,14 @@ export declare const NO_LIMITS_REPORTED = "no limits reported";
 /**
  * `compact` fits a footer or a sidebar row: each window's figure, the credit
  * budget and the stale marker, without reset times. `full` adds each reset.
+ * `narrow` fits one line per account in a narrow sidebar: `5h 92% · 7d 66%
+ * · Fa 98% left`, the account-wide windows plus at most one model-scoped
+ * window or the budget (as `cr`), and no stale marker (see `isQuotaStale`).
+ * A reading whose windows belong to named groups and that has no
+ * account-wide window reads up to two groups instead:
+ * `Ge 7d 62% · Ot 7d 48% left`.
  */
-export type QuotaTextForm = 'compact' | 'full';
+export type QuotaTextForm = 'compact' | 'full' | 'narrow';
 export interface QuotaTextOptions {
     /** The current time in ms, for reset countdowns and the stale marker. */
     now: number;
@@ -21,6 +27,26 @@ export interface QuotaTextOptions {
     /** Defaults to `QUOTA_STALE_AFTER_MS`. */
     staleAfterMs?: number;
 }
+export interface QuotaWindowPart {
+    kind: 'window' | 'budget';
+    /** The display name of a quota window, or `credits` for the budget. */
+    name: string;
+    /** The shared figure wording, including `credits` for budget figures. */
+    figure: string;
+    /** The unrounded remaining percentage, clamped to 0–100, when known. */
+    remainingPercent?: number;
+    /** A bare relative reset span such as `4d`, only when the reset is future. */
+    resetIn?: string;
+    checkedAt: number;
+    /** Whether the reset followed this reading and has arrived by `now`. */
+    resetSinceReading: boolean;
+}
+export interface QuotaParts {
+    /** Reported windows in display order, followed by the budget when present. */
+    windows: QuotaWindowPart[];
+    /** The shared checked-age wording, present only when the reading is stale. */
+    age?: string;
+}
 /**
  * The name a window is shown under. A general window (scope `all`) is named
  * by its stored length; a model-scoped window keeps the label the plugin
@@ -29,17 +55,31 @@ export interface QuotaTextOptions {
  * were recorded) falls back to its label.
  */
 export declare function quotaWindowName(limit: Pick<ProjectedLimit, 'scope' | 'label' | 'windowMinutes'>): string;
+/**
+ * Structured quota wording for layouts that need one row per window. The
+ * windows use the same filtering and order as `quotaTextParts`; future resets
+ * and the optional age keep the shared formatter's wording.
+ */
+export declare function quotaWindowParts(quota: ProjectedQuota | undefined, options: QuotaTextOptions): QuotaParts;
+/**
+ * Whether the reading is stale: true exactly when the compact and full forms
+ * would end with `checked … ago`. The narrow form leaves that age out to stay
+ * short, so a caller drawing a narrow line uses this to dim it instead.
+ */
+export declare function isQuotaStale(quota: ProjectedQuota | undefined, options: QuotaTextOptions): boolean;
 /**
  * The pieces of a quota text, in order: one per reported window
  * (`5h 58% left, resets 2h`), then the credit budget when there is one, then
  * `checked 3h ago` when the oldest piece shown is stale. Empty when nothing
  * was reported; `formatQuota` turns that into a sentence. A caller printing
- * one line per window (the terminal auth menu) uses these directly.
+ * one line per window (the terminal auth menu) uses these directly. In the
+ * narrow form the pieces are the narrow line's (`5h 92%`, `7d 66% left`).
  */
 export declare function quotaTextParts(quota: ProjectedQuota | undefined, options: QuotaTextOptions): string[];
 /**
  * A row's quota as one line: `5h 58% left · 7d 90% left` in the compact
- * form, with `, resets 2h` after each window in the full form. With nothing
+ * form, with `, resets 2h` after each window in the full form, and
+ * `5h 58% · 7d 90% left` in the narrow form. With nothing
  * reported it is `NO_QUOTA_READING`, or `NO_LIMITS_REPORTED` when the
  * provider answered without a limit for any window.
  */

package/dist/internal-types/quota/index.d.ts

@@ -1,10 +1,10 @@
 export type { QuotaCodec } from './codec.js';
 export { quotaCodec } from './codec.js';
-export type { QuotaTextForm, QuotaTextOptions } from './format.js';
-export { formatQuota, NO_LIMITS_REPORTED, NO_QUOTA_READING, QUOTA_STALE_AFTER_MS, quotaTextParts, quotaWindowName, } from './format.js';
+export type { QuotaParts, QuotaTextForm, QuotaTextOptions, QuotaWindowPart, } from './format.js';
+export { formatQuota, isQuotaStale, NO_LIMITS_REPORTED, NO_QUOTA_READING, QUOTA_STALE_AFTER_MS, quotaTextParts, quotaWindowName, quotaWindowParts, } from './format.js';
 export type { CreditBudgetCleared, CreditBudgetEntry, CreditBudgetReading, QuotaAbsentEntry, QuotaCounter, QuotaEntry, QuotaMap, QuotaReadingEntry, QuotaRetiredEntry, } from './map.js';
 export { ALL_SCOPE, DEFAULT_REQUIRED_LABELS, decodeQuotaMap, emptyQuotaMap, isQuotaMap, } from './map.js';
 export type { ObservedBudget, ObservedPair, ObservedReading, QuotaObservation, } from './merge.js';
 export { isQuotaObservation, mergeQuotaObservation, QuotaCodecError, } from './merge.js';
-export type { ExhaustionReset, ProjectedBudget, ProjectedLimit, ProjectedQuota, } from './projection.js';
+export type { ExhaustionReset, ProjectedBudget, ProjectedLimit, ProjectedQuota, QuotaGroup, } from './projection.js';
 export { budgetExhaustedResetAt, futureResetAt, projectQuota, readsExhausted, } from './projection.js';

package/dist/internal-types/quota/projection.d.ts

@@ -19,6 +19,15 @@ export interface ProjectedBudget {
     remainingPercent?: number;
     resetsAt?: string;
 }
+/**
+ * A named group of windows, such as antigravity-auth's `Gemini` and
+ * `Other models`: every window stored under `scope` belongs to it, and
+ * `label` is the group's display name.
+ */
+export interface QuotaGroup {
+    scope: string;
+    label: string;
+}
 export interface ProjectedQuota {
     scope: string;
     /** One entry per label: longest known window first, unknown lengths last. */
@@ -31,6 +40,13 @@ export interface ProjectedQuota {
     /** Present only when the stored budget is a reading, not cleared. */
     budget?: ProjectedBudget;
     counters?: Record<string, QuotaCounter>;
+    /**
+     * The named groups the windows belong to, in the order the plugin lists
+     * them. Set only by a plugin whose windows all belong to such groups; the
+     * narrow form then shows one item per group (see `formatQuota`).
+     * `projectQuota` never sets it.
+     */
+    groups?: readonly QuotaGroup[];
 }
 /**
  * Resolves `map` for a request in `scope` (`all` or a model family). A family

package/dist/internal-types/routing/admission.d.ts

@@ -0,0 +1,93 @@
+import { type QuotaMap } from '../quota/map.js';
+import { type ProjectedQuota } from '../quota/projection.js';
+export type RowKind = 'oauth' | 'api-key';
+export interface RoutingRow {
+    id: string;
+    kind: RowKind;
+    /** The row's stored quota map; absent is the same as an empty map. */
+    quota?: QuotaMap;
+}
+export interface WindowRef {
+    scope: string;
+    label: string;
+}
+export interface ExclusionInputs {
+    /** Row id to the time (ms) a rate-limit mark expires. */
+    rateLimitMarks?: ReadonlyMap<string, number>;
+    /** Row id to the time (ms) a failed refresh may be retried. */
+    refreshBackoff?: ReadonlyMap<string, number>;
+}
+export interface AdmissionInput extends ExclusionInputs {
+    rows: readonly RoutingRow[];
+    /** `all` (the default) or a model family. */
+    scope?: string;
+    /** Labels the scope requires an entry for; defaults to `['primary']`. */
+    requiredLabels?: readonly string[];
+    now: number;
+    /**
+     * Called synchronously, once per refusal at gates 2 to 4, with the row id.
+     * Its return value is ignored and never awaited, so a pull the caller
+     * starts from here cannot delay the refusal.
+     */
+    requestPull?: (rowId: string) => void;
+}
+export type AdmissionRefusal = {
+    id: string;
+    stage: 1;
+    gate: 2;
+    reason: 'needs-first-reading';
+    pullRequested: true;
+} | {
+    id: string;
+    stage: 1;
+    gate: 3;
+    reason: 'unknown-window';
+    window: WindowRef;
+    pullRequested: true;
+} | {
+    id: string;
+    stage: 1;
+    gate: 4;
+    reason: 'unknown-reset';
+    window: WindowRef;
+    pullRequested: true;
+} | {
+    id: string;
+    stage: 1;
+    gate: 5;
+    reason: 'exhausted';
+    window: WindowRef;
+    resetsAt: string;
+    resetAtMs: number;
+} | {
+    id: string;
+    stage: 2;
+    reason: 'budget-spent';
+    resetsAt: string;
+    resetAtMs: number;
+};
+export interface AdmissionExclusion {
+    id: string;
+    reason: 'rate-limited' | 'refresh-backoff';
+    until: number;
+}
+export interface AdmittedRow {
+    id: string;
+    kind: RowKind;
+    /** The projection admission judged; absent for API-key rows. */
+    projection?: ProjectedQuota;
+    /** Set when a spent budget was kept because no other path survived. */
+    lastPath?: true;
+}
+export interface AdmissionResult {
+    /** In input order. */
+    admitted: AdmittedRow[];
+    refused: AdmissionRefusal[];
+    excluded: AdmissionExclusion[];
+    /** Ids a pull was requested for, in input order. */
+    pulls: string[];
+}
+/** The exclusion that applies to `id` at `now`, if any. */
+export declare function exclusionFor(id: string, inputs: ExclusionInputs, now: number): AdmissionExclusion | undefined;
+/** Runs both admission stages over `input.rows`. */
+export declare function admit(input: AdmissionInput): AdmissionResult;

package/dist/internal-types/routing/index.d.ts

@@ -0,0 +1,8 @@
+export type { AdmissionExclusion, AdmissionInput, AdmissionRefusal, AdmissionResult, AdmittedRow, ExclusionInputs, RoutingRow, RowKind, WindowRef, } from './admission.js';
+export { admit, exclusionFor } from './admission.js';
+export type { OrderedAttempt, OrderedPlacement, OrderedRoute, OrderedRouteInput, ResolvedRoutingMode, RoutingMode, } from './ordered.js';
+export { DEFAULT_FORMER_MAIN_ID, nextOrderedAttempt, orderForPlacement, resolveRoutingMode, routeOrdered, } from './ordered.js';
+export type { StickyPin } from './pins.js';
+export { isPinValid, pendingBytesForPins } from './pins.js';
+export type { PinAction, StickyBreakDecision, StickyRoute, StickyRouteInput, StickySelection, StickySelectionCandidate, StickySelectionInput, StickyStatusClass, StickyStatusClassifier, } from './sticky.js';
+export { decideStickyBreak, defaultStickyStatusClass, MIN_RESET_HOURS, MIN_WEIGHT, QUOTA_STALENESS_MS, routeSticky, selectStickyCandidate, snapshotCheckedAt, sustainableWindowWeight, } from './sticky.js';

package/dist/internal-types/routing/ordered.d.ts

@@ -0,0 +1,47 @@
+import { type AdmissionInput, type AdmissionResult } from './admission.js';
+export type RoutingMode = 'ordered' | 'sticky-balanced';
+/** Where `ordered` routing places the former main row. */
+export type OrderedPlacement = 'roster' | 'main-first' | 'fallback-first';
+export interface ResolvedRoutingMode {
+    mode: RoutingMode;
+    placement: OrderedPlacement;
+}
+/** The former main row's id when the caller supplies none. */
+export declare const DEFAULT_FORMER_MAIN_ID = "main";
+/**
+ * Resolves a persisted `routing.mode` value. `main-first` and
+ * `fallback-first` are aliases of `ordered` that move the former main row;
+ * an absent or unrecognised value is `ordered` in roster order. The
+ * persisted value is only read here, never rewritten.
+ */
+export declare function resolveRoutingMode(value: unknown): ResolvedRoutingMode;
+/**
+ * Orders `ids` (in roster order) for a placement: `main-first` moves the row
+ * named `formerMainId` to the front, `fallback-first` to the back, and
+ * `roster` (or a missing former main row) keeps roster order.
+ */
+export declare function orderForPlacement(ids: readonly string[], placement: OrderedPlacement, formerMainId?: string): string[];
+export interface OrderedRouteInput extends AdmissionInput {
+    placement?: OrderedPlacement;
+    formerMainId?: string;
+    /** Killswitch verdict per row; `false` drops the row, a missing row passes. */
+    killswitch?: ReadonlyMap<string, boolean>;
+}
+export interface OrderedRoute {
+    /** Admitted, non-killed row ids in the order they are to be tried. */
+    order: string[];
+    admission: AdmissionResult;
+}
+export declare function routeOrdered(input: OrderedRouteInput): OrderedRoute;
+export interface OrderedAttempt {
+    id: string;
+    /** The response status; undefined when no response arrived. */
+    status?: number;
+}
+/**
+ * The next row to try, given the attempts so far: the first row when none
+ * has been tried, the next untried row when the last attempt's status is one
+ * of `retryStatuses`, and undefined otherwise (the last response stands) or
+ * when every row has been tried.
+ */
+export declare function nextOrderedAttempt(order: readonly string[], attempts: readonly OrderedAttempt[], retryStatuses: readonly number[]): string | undefined;

package/dist/internal-types/routing/pins.d.ts

@@ -0,0 +1,22 @@
+export interface StickyPin {
+    accountId: string;
+    /** The row's recorded wire identity when the pin was made, if known. */
+    wireIdentity?: string;
+    /** The request size recorded with the pin; weighs pending bytes. */
+    inputBytes?: number;
+    /** The projection time the placement was judged on. */
+    quotaCheckedAt?: number;
+}
+/**
+ * A pin survives while its row id is in `validIds` and the row still holds
+ * the account it was placed on. Only two known, differing identities prove
+ * the account changed: an unknown identity on either side keeps the pin,
+ * because re-placing a session on missing evidence throws its cache away.
+ */
+export declare function isPinValid(pin: StickyPin, validIds: ReadonlySet<string>, currentIdentity: string | undefined): boolean;
+/**
+ * Sums the request bytes of every other session's pin per row, as openai-auth
+ * does. A pin counts only while it was judged on the row's current
+ * projection time, so a fresh reading resets the row's pending load.
+ */
+export declare function pendingBytesForPins(pins: Iterable<readonly [sessionKey: string, pin: StickyPin]>, quotaCheckedAtById: ReadonlyMap<string, number | undefined>, excludedSessionKey?: string): Map<string, number>;

package/dist/internal-types/routing/sticky.d.ts

@@ -0,0 +1,158 @@
+import { type ProjectedQuota } from '../quota/projection.js';
+import { type AdmissionInput, type AdmissionRefusal, type AdmissionResult, type RoutingRow, type WindowRef } from './admission.js';
+import { type StickyPin } from './pins.js';
+export declare const QUOTA_STALENESS_MS: number;
+export declare const MIN_RESET_HOURS: number;
+export declare const MIN_WEIGHT = 0.000001;
+/** The projection's time, else the caller's cache-entry time. */
+export declare function snapshotCheckedAt(quota: ProjectedQuota | null | undefined, entryCheckedAt?: number): number | undefined;
+export type StickyBreakDecision = {
+    action: 'retain';
+    reason: 'unknown' | 'stale' | 'healthy' | 'transient';
+} | {
+    action: 'migrate';
+    reason: 'exhausted' | 'permanent' | 'killswitch';
+    /** The exhausted limit, named by its (scope, label), not its position. */
+    window?: WindowRef;
+    resetsAt?: string;
+};
+/**
+ * How the adapter reads a failed response's HTTP status for the break
+ * decision. `permanent` moves the session off its row before any quota is
+ * consulted; `transient` and `healthy` keep it unless the quota says the row
+ * is spent. A missing status means the request failed without a response.
+ */
+export type StickyStatusClass = 'permanent' | 'transient' | 'healthy';
+export type StickyStatusClassifier = (status: number | undefined) => StickyStatusClass;
+/**
+ * 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 declare function defaultStickyStatusClass(status: number | undefined): StickyStatusClass;
+/** Classifies whether a pinned session should leave its row after a failure. */
+export declare function decideStickyBreak(input: {
+    quota: ProjectedQuota | null | undefined;
+    quotaCheckedAt?: number;
+    status?: number;
+    now: number;
+    killswitchPasses?: boolean;
+    /** Defaults to `defaultStickyStatusClass`. */
+    classifyStatus?: StickyStatusClassifier;
+}): StickyBreakDecision;
+export declare function sustainableWindowWeight(window: {
+    remainingPercent: number;
+    resetsAt?: string;
+}, reservePercent: number, now: number): number;
+export interface StickySelectionCandidate {
+    accountId: string;
+    quota: ProjectedQuota | null | undefined;
+    quotaCheckedAt?: number;
+    /** Reserve percent per window label; a missing label reserves nothing. */
+    reservePercent: Readonly<Record<string, number>>;
+    configuredOrder: number;
+    resetCreditsApplicable?: number;
+    /** `false` excludes the candidate from weighted and fallback placement. */
+    killswitchPasses?: boolean;
+}
+export interface StickySelectionInput {
+    candidates: readonly StickySelectionCandidate[];
+    pendingBytes: ReadonlyMap<string, number>;
+    requestBytes: number;
+    now: number;
+    onEmptyWeightedSet?: () => void;
+}
+export interface StickySelection {
+    accountId: string;
+    quotaCheckedAt?: number;
+    source: 'weighted' | 'mode-fallback';
+}
+/**
+ * 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 declare function selectStickyCandidate(input: StickySelectionInput): StickySelection | undefined;
+/** Reserve percent per window label; a missing label reserves nothing. */
+export type ReservePercent = Readonly<Record<string, number>>;
+/**
+ * Reserve percentages per row: a map keyed by row id, or a function of the
+ * row. A row the map lacks, or for which the function returns undefined,
+ * takes the shared `reservePercent`.
+ */
+export type RowReservePercent = ReadonlyMap<string, ReservePercent> | ((row: RoutingRow) => ReservePercent | undefined);
+/**
+ * What a valid pin does when its row is not dispatched.
+ *
+ * `keep`: the pin is retained whatever kept its row from this request.
+ *
+ * `move-on-confirmed-exhaustion`: the pin moves to the row this request is
+ * dispatched to when its own row was refused as confirmed exhausted (a spent
+ * window with a future reset, or a spent credit budget) or killed by the
+ * killswitch. A refusal for unknown quota (no reading yet, a missing window,
+ * an exhausted reading without a usable reset) and an exclusion (rate-limit
+ * mark, refresh backoff) keep the pin while this request is served elsewhere.
+ * With no admissible row the pin is retained either way.
+ */
+export type RefusedPinPolicy = 'keep' | 'move-on-confirmed-exhaustion';
+export interface StickyRouteInput extends AdmissionInput {
+    requestBytes: number;
+    /** Bytes already committed per row, for example from other sessions' pins. */
+    pendingBytes?: ReadonlyMap<string, number>;
+    /** Killswitch verdict per row; a missing row passes. */
+    killswitch?: ReadonlyMap<string, boolean>;
+    /** Reserve percent per window label, for every row without its own. */
+    reservePercent?: ReservePercent;
+    /** Per-row reserves, which replace `reservePercent` for the rows they cover. */
+    rowReservePercent?: RowReservePercent;
+    /** Defaults to `keep`. */
+    refusedPinPolicy?: RefusedPinPolicy;
+    resetCreditsApplicable?: ReadonlyMap<string, number>;
+    /** The session's current pin, if it has one. */
+    pin?: StickyPin;
+    /** Each row's recorded wire identity; missing means unknown. */
+    identities?: ReadonlyMap<string, string | undefined>;
+    onEmptyWeightedSet?: () => void;
+}
+/**
+ * What the caller does with the session's pin: keep it, replace it with
+ * `pin`, or drop it. Under the default `keep` policy a valid pin is always
+ * kept, even when this request was routed elsewhere because its row was
+ * refused, excluded or killed; `refusedPinPolicy` can move it instead.
+ */
+export type PinAction = {
+    action: 'retain';
+} | {
+    action: 'assign';
+    pin: StickyPin;
+} | {
+    action: 'clear';
+} | {
+    action: 'none';
+};
+export type StickyRoute = {
+    outcome: 'dispatch';
+    accountId: string;
+    source: 'pin' | 'weighted' | 'mode-fallback';
+    quotaCheckedAt?: number;
+    pin: PinAction;
+    /** Rows that selection chose and admission then refused, in selection order. */
+    refusedSelections: AdmissionRefusal[];
+    admission: AdmissionResult;
+} | {
+    outcome: 'no-admissible-account';
+    pin: PinAction;
+    refusedSelections: AdmissionRefusal[];
+    admission: AdmissionResult;
+};
+/**
+ * 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 declare function routeSticky(input: StickyRouteInput): StickyRoute;

package/dist/internal-types/setup/command-error.d.ts

@@ -0,0 +1,32 @@
+import type { SetupHostEnrollment } from './types.js';
+/**
+ * Keeps the Pi install refusal message stable while exposing safe process details.
+ * A clipped tail can start inside a credential, so discard its first line—or
+ * the whole tail if it has no newline—before redacting.
+ */
+export declare class SetupCommandError extends Error {
+    readonly step = "pi-install";
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    readonly stderrTail: string;
+    constructor(details: {
+        exitCode: number | null;
+        signal: string | null;
+        stderrTail: string;
+        stderrTruncated?: boolean;
+    });
+}
+/** The line setup prints for one host's outcome, e.g. `Pi: not connected`. */
+export declare function setupEnrollmentLine({ host, outcome, }: SetupHostEnrollment): string;
+/**
+ * Remember which hosts a failed setup left connected to the vault, against the
+ * thrown value. Only objects can carry a record; a thrown primitive is left as
+ * it is, and the printed lines are then the only report.
+ */
+export declare function recordSetupEnrollment(failure: unknown, enrollment: readonly SetupHostEnrollment[]): void;
+/**
+ * The per-host vault enrollment outcomes a failed `runSetup` recorded for the
+ * value it threw, or `undefined` when setup failed before any host's enrollment
+ * began, or the value is not one setup threw (or is not an object).
+ */
+export declare function setupEnrollment(error: unknown): readonly SetupHostEnrollment[] | undefined;

package/dist/internal-types/setup/command.d.ts

@@ -0,0 +1,3 @@
+import type { SetupIO, SetupPlugin, SetupResult } from './types.js';
+export declare const AMBIGUOUS_OPENCODE_MESSAGE = "Multiple OpenCode generations found. Choose --opencode=1|2|both before running noninteractive setup.";
+export declare function runSetup(plugin: SetupPlugin, argv?: readonly string[], io?: SetupIO): Promise<SetupResult>;