@juspay/neurolink 12.24.1 → 12.25.1

package/dist/proxy/accountRanking.d.ts

@@ -1,4 +1,4 @@
-import type { ProxyAccountRoutingReason, ProxyAccountSortMetrics, ProxyPassthroughAccount } from "../types/index.js";
+import type { ProxyAccountPrecedenceReason, ProxyAccountRankingPolicy, ProxyAccountRoutingReason, ProxyAccountSortMetrics, ProxyAccountSpillMove, ProxyAffinityPrecedenceSkipReason, ProxyPassthroughAccount } from "../types/index.js";
 /**
  * The pre-existing "spend the soonest-expiring weekly allowance first" order.
  * Moved verbatim from claudeProxyRoutes.ts — availability → quota-evidence
@@ -8,15 +8,78 @@ import type { ProxyAccountRoutingReason, ProxyAccountSortMetrics, ProxyPassthrou
  */
 export declare function compareExpiryFirst(a: ProxyPassthroughAccount, b: ProxyPassthroughAccount, metricsByKey: ReadonlyMap<string, ProxyAccountSortMetrics>, primaryKey: string | undefined): [number, ProxyAccountRoutingReason];
 /**
- * Orders accounts by the configured ranking and reports the reason that
- * placed rank 0. PR1 ships only `expiry-first`; PR2 (Task 11) adds
- * `headroom-first` plus the affinity/prefer-primary precedence layer.
+ * Availability → quota-evidence quality → session saturation → model-scoped
+ * saturation → highest headroom (min(1 - sessionUsed, 1 - weeklyUsed), reset-
+ * freshened via the same accountSortMetrics values compareExpiryFirst uses)
+ * → soonest weekly reset → configured primary → insertion order. An account
+ * whose headroom cannot be computed sorts after every account whose can.
+ */
+export declare function compareHeadroomFirst(a: ProxyPassthroughAccount, b: ProxyPassthroughAccount, metricsByKey: ReadonlyMap<string, ProxyAccountSortMetrics>, primaryKey: string | undefined): [number, ProxyAccountRoutingReason];
+/**
+ * Whether an account may hold a session binding or take the primary's place:
+ * usable and not session-saturated.
+ */
+export declare function isPrecedenceEligible(metrics: ProxyAccountSortMetrics | undefined): boolean;
+/**
+ * Applies the precedence order a fill-first request tries: (1) the bound
+ * (session-affinity) account, (2) the configured primary, (3) the rest in
+ * ranking order. Shared by rankAccounts (for the quota-ordered path) and the
+ * route directly (for quota-off fill-first, where the base order is never
+ * comparator-sorted but affinity/prefer-primary must still apply per spec).
+ * `strategy: round-robin` ignores all five policy keys and never calls this.
+ *
+ * When affinity applies and prefer-primary is also on, and the configured
+ * primary is itself eligible (usable, not session-saturated) and is not the
+ * bound account, the primary is placed second — [bound, primary, ...rest] —
+ * so a request that cannot use its bound account's session still prefers
+ * the primary over the rest of the ranking. The reported reason stays
+ * "session_affinity" since the bound account still won rank 0.
+ */
+export declare function applyAffinityAndPrimary(args: {
+    orderedAccounts: ProxyPassthroughAccount[];
+    metricsByKey: ReadonlyMap<string, ProxyAccountSortMetrics>;
+    affinityKey?: string;
+    primaryKey?: string;
+    preferPrimary?: boolean;
+}): {
+    orderedAccounts: ProxyPassthroughAccount[];
+    reason: ProxyAccountPrecedenceReason | null;
+    affinitySkippedReason: ProxyAffinityPrecedenceSkipReason | null;
+};
+/**
+ * Orders accounts by the configured ranking (`expiry-first` or
+ * `headroom-first`), applies the affinity/prefer-primary precedence, and
+ * reports the reason that placed rank 0.
  */
 export declare function rankAccounts(args: {
     accounts: ProxyPassthroughAccount[];
     metricsByKey: ReadonlyMap<string, ProxyAccountSortMetrics>;
     primaryKey: string | undefined;
+    ranking?: ProxyAccountRankingPolicy;
+    affinityKey?: string;
+    preferPrimary?: boolean;
 }): {
     orderedAccounts: ProxyPassthroughAccount[];
     reason: ProxyAccountRoutingReason;
+    affinitySkippedReason: ProxyAffinityPrecedenceSkipReason | null;
+};
+/**
+ * For a request without an active binding: if the current first choice is
+ * already at spillInflight in-flight requests, try the next account below
+ * that threshold that is usable and not session-saturated — the same
+ * eligibility as every precedence step. An account with no metrics, an
+ * unusable one or a saturated one is never a spill target even if its
+ * in-flight count is low. If there is no eligible account under the
+ * threshold, spill does nothing. `spill.inflight` records the SOURCE
+ * account's count — the number that triggered the move, not the
+ * destination's.
+ */
+export declare function applySpill(args: {
+    orderedAccounts: ProxyPassthroughAccount[];
+    inflightByKey: ReadonlyMap<string, number>;
+    metricsByKey: ReadonlyMap<string, ProxyAccountSortMetrics>;
+    spillInflight: number;
+}): {
+    orderedAccounts: ProxyPassthroughAccount[];
+    spill: ProxyAccountSpillMove | null;
 };

package/dist/proxy/accountRanking.js

@@ -71,16 +71,196 @@ export function compareExpiryFirst(a, b, metricsByKey, primaryKey) {
     }
     return [0, "insertion_order"];
 }
+function headroomFor(m) {
+    if (m.sessionUsed === null || m.weeklyUsed === null) {
+        return null;
+    }
+    return Math.min(1 - m.sessionUsed, 1 - m.weeklyUsed);
+}
 /**
- * Orders accounts by the configured ranking and reports the reason that
- * placed rank 0. PR1 ships only `expiry-first`; PR2 (Task 11) adds
- * `headroom-first` plus the affinity/prefer-primary precedence layer.
+ * Availability → quota-evidence quality → session saturation → model-scoped
+ * saturation → highest headroom (min(1 - sessionUsed, 1 - weeklyUsed), reset-
+ * freshened via the same accountSortMetrics values compareExpiryFirst uses)
+ * → soonest weekly reset → configured primary → insertion order. An account
+ * whose headroom cannot be computed sorts after every account whose can.
+ */
+export function compareHeadroomFirst(a, b, metricsByKey, primaryKey) {
+    const ma = metricsByKey.get(a.key);
+    const mb = metricsByKey.get(b.key);
+    if (!ma || !mb) {
+        return [0, "insertion_order"];
+    }
+    if (ma.usable !== mb.usable) {
+        return [ma.usable ? -1 : 1, "availability"];
+    }
+    if (!ma.usable && !mb.usable) {
+        const au = ma.coolingUntil || Number.POSITIVE_INFINITY;
+        const bu = mb.coolingUntil || Number.POSITIVE_INFINITY;
+        return [
+            au === bu ? 0 : au - bu,
+            au === bu ? "insertion_order" : "cooldown_recovery",
+        ];
+    }
+    if (ma.quotaEvidenceRank !== mb.quotaEvidenceRank) {
+        return [ma.quotaEvidenceRank - mb.quotaEvidenceRank, "quota_evidence"];
+    }
+    if (ma.saturated !== mb.saturated) {
+        return [ma.saturated ? 1 : -1, "session_headroom"];
+    }
+    if (ma.scopedSaturated !== mb.scopedSaturated) {
+        return [ma.scopedSaturated ? 1 : -1, "scoped_headroom"];
+    }
+    const ha = headroomFor(ma);
+    const hb = headroomFor(mb);
+    if (ha !== hb) {
+        if (ha === null) {
+            return [1, "headroom"];
+        }
+        if (hb === null) {
+            return [-1, "headroom"];
+        }
+        return [hb - ha, "headroom"];
+    }
+    if (ma.weeklyReset !== mb.weeklyReset) {
+        return [ma.weeklyReset - mb.weeklyReset, "weekly_reset"];
+    }
+    if (primaryKey && (a.key === primaryKey) !== (b.key === primaryKey)) {
+        return [a.key === primaryKey ? -1 : 1, "configured_primary"];
+    }
+    return [0, "insertion_order"];
+}
+/**
+ * Whether an account may hold a session binding or take the primary's place:
+ * usable and not session-saturated.
+ */
+export function isPrecedenceEligible(metrics) {
+    return !!metrics && metrics.usable && !metrics.saturated;
+}
+/**
+ * Applies the precedence order a fill-first request tries: (1) the bound
+ * (session-affinity) account, (2) the configured primary, (3) the rest in
+ * ranking order. Shared by rankAccounts (for the quota-ordered path) and the
+ * route directly (for quota-off fill-first, where the base order is never
+ * comparator-sorted but affinity/prefer-primary must still apply per spec).
+ * `strategy: round-robin` ignores all five policy keys and never calls this.
+ *
+ * When affinity applies and prefer-primary is also on, and the configured
+ * primary is itself eligible (usable, not session-saturated) and is not the
+ * bound account, the primary is placed second — [bound, primary, ...rest] —
+ * so a request that cannot use its bound account's session still prefers
+ * the primary over the rest of the ranking. The reported reason stays
+ * "session_affinity" since the bound account still won rank 0.
+ */
+export function applyAffinityAndPrimary(args) {
+    const { orderedAccounts, metricsByKey, affinityKey, primaryKey, preferPrimary = false, } = args;
+    const isEligible = (key) => isPrecedenceEligible(metricsByKey.get(key));
+    let affinitySkippedReason = null;
+    if (affinityKey) {
+        const bound = orderedAccounts.find((a) => a.key === affinityKey);
+        if (bound && isEligible(affinityKey)) {
+            const primaryGoesSecond = preferPrimary &&
+                !!primaryKey &&
+                primaryKey !== affinityKey &&
+                isEligible(primaryKey);
+            const primary = primaryGoesSecond
+                ? orderedAccounts.find((a) => a.key === primaryKey)
+                : undefined;
+            const remainder = orderedAccounts.filter((a) => a.key !== affinityKey && a.key !== primary?.key);
+            return {
+                orderedAccounts: primary
+                    ? [bound, primary, ...remainder]
+                    : [bound, ...remainder],
+                reason: "session_affinity",
+                affinitySkippedReason: null,
+            };
+        }
+        const boundMetrics = metricsByKey.get(affinityKey);
+        affinitySkippedReason =
+            !bound || !boundMetrics?.usable ? "unusable" : "session_saturated";
+    }
+    if (preferPrimary && primaryKey) {
+        const primary = orderedAccounts.find((a) => a.key === primaryKey);
+        if (primary && isEligible(primaryKey)) {
+            return {
+                orderedAccounts: [
+                    primary,
+                    ...orderedAccounts.filter((a) => a.key !== primaryKey),
+                ],
+                reason: "preferred_primary",
+                affinitySkippedReason,
+            };
+        }
+    }
+    return { orderedAccounts, reason: null, affinitySkippedReason };
+}
+/**
+ * Orders accounts by the configured ranking (`expiry-first` or
+ * `headroom-first`), applies the affinity/prefer-primary precedence, and
+ * reports the reason that placed rank 0.
  */
 export function rankAccounts(args) {
-    const { accounts, metricsByKey, primaryKey } = args;
-    const orderedAccounts = [...accounts].sort((a, b) => compareExpiryFirst(a, b, metricsByKey, primaryKey)[0]);
-    const reason = orderedAccounts.length < 2
+    const { accounts, metricsByKey, primaryKey, ranking = "expiry-first", affinityKey, preferPrimary, } = args;
+    const compare = ranking === "headroom-first" ? compareHeadroomFirst : compareExpiryFirst;
+    const baseOrder = [...accounts].sort((a, b) => compare(a, b, metricsByKey, primaryKey)[0]);
+    const precedence = applyAffinityAndPrimary({
+        orderedAccounts: baseOrder,
+        metricsByKey,
+        affinityKey,
+        primaryKey,
+        preferPrimary,
+    });
+    if (precedence.reason) {
+        return {
+            orderedAccounts: precedence.orderedAccounts,
+            reason: precedence.reason,
+            affinitySkippedReason: precedence.affinitySkippedReason,
+        };
+    }
+    const reason = baseOrder.length < 2
         ? "single_account"
-        : compareExpiryFirst(orderedAccounts[0], orderedAccounts[1], metricsByKey, primaryKey)[1];
-    return { orderedAccounts, reason };
+        : compare(baseOrder[0], baseOrder[1], metricsByKey, primaryKey)[1];
+    return {
+        orderedAccounts: baseOrder,
+        reason,
+        affinitySkippedReason: precedence.affinitySkippedReason,
+    };
+}
+/**
+ * For a request without an active binding: if the current first choice is
+ * already at spillInflight in-flight requests, try the next account below
+ * that threshold that is usable and not session-saturated — the same
+ * eligibility as every precedence step. An account with no metrics, an
+ * unusable one or a saturated one is never a spill target even if its
+ * in-flight count is low. If there is no eligible account under the
+ * threshold, spill does nothing. `spill.inflight` records the SOURCE
+ * account's count — the number that triggered the move, not the
+ * destination's.
+ */
+export function applySpill(args) {
+    const { orderedAccounts, inflightByKey, metricsByKey, spillInflight } = args;
+    const first = orderedAccounts[0];
+    if (spillInflight <= 0 || !first) {
+        return { orderedAccounts, spill: null };
+    }
+    const firstInflight = inflightByKey.get(first.key) ?? 0;
+    if (firstInflight < spillInflight) {
+        return { orderedAccounts, spill: null };
+    }
+    const rest = orderedAccounts.slice(1);
+    const targetIndex = rest.findIndex((account) => isPrecedenceEligible(metricsByKey.get(account.key)) &&
+        (inflightByKey.get(account.key) ?? 0) < spillInflight);
+    if (targetIndex === -1) {
+        return { orderedAccounts, spill: null };
+    }
+    const target = rest[targetIndex];
+    const reordered = [
+        target,
+        first,
+        ...rest.slice(0, targetIndex),
+        ...rest.slice(targetIndex + 1),
+    ];
+    return {
+        orderedAccounts: reordered,
+        spill: { from: first.key, to: target.key, inflight: firstInflight },
+    };
 }

package/dist/proxy/proxyAnalysis.js

@@ -25,6 +25,17 @@ const ROUTING_STRATEGIES = new Set(PROXY_ACCOUNT_ROUTING_STRATEGIES);
 const ROUTING_MODES = new Set(PROXY_ACCOUNT_ROUTING_MODES);
 const ROUTING_REASONS = new Set(PROXY_ACCOUNT_ROUTING_REASONS);
 const ROUTING_ACCOUNT_TYPES = new Set(PROXY_ACCOUNT_TYPES);
+const ROUTING_RANKINGS = new Set([
+    "expiry-first",
+    "headroom-first",
+]);
+const AFFINITY_SKIP_REASONS = new Set([
+    "unusable",
+    "session_saturated",
+    "expired",
+    "no_session",
+    "disabled",
+]);
 const COOLING_REASONS = new Set(ACCOUNT_COOLING_REASONS);
 const QUOTA_FRESHNESS_VALUES = new Set([
     "unknown",
@@ -211,6 +222,61 @@ function routingCandidateValue(value) {
         scopedResetAt: candidate.scopedResetAt,
     };
 }
+function plainObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function routingPolicyValue(value) {
+    const policy = plainObject(value);
+    if (!policy ||
+        typeof policy.ranking !== "string" ||
+        !ROUTING_RANKINGS.has(policy.ranking) ||
+        typeof policy.preferPrimary !== "boolean" ||
+        typeof policy.sessionAffinity !== "boolean" ||
+        !Number.isInteger(policy.sessionAffinityIdleTtlMs) ||
+        !Number.isInteger(policy.spillInflight)) {
+        return undefined;
+    }
+    return {
+        ranking: policy.ranking,
+        preferPrimary: policy.preferPrimary,
+        sessionAffinity: policy.sessionAffinity,
+        sessionAffinityIdleTtlMs: policy.sessionAffinityIdleTtlMs,
+        spillInflight: policy.spillInflight,
+    };
+}
+function routingAffinityValue(value) {
+    const affinity = plainObject(value);
+    if (!affinity ||
+        typeof affinity.sessionBound !== "boolean" ||
+        !isNullableString(affinity.boundAccount) ||
+        typeof affinity.applied !== "boolean" ||
+        (affinity.skippedReason !== null &&
+            (typeof affinity.skippedReason !== "string" ||
+                !AFFINITY_SKIP_REASONS.has(affinity.skippedReason)))) {
+        return undefined;
+    }
+    return {
+        sessionBound: affinity.sessionBound,
+        boundAccount: affinity.boundAccount,
+        applied: affinity.applied,
+        skippedReason: affinity.skippedReason,
+    };
+}
+function routingSpillValue(value) {
+    const spill = plainObject(value);
+    const from = stringValue(spill?.from);
+    const to = stringValue(spill?.to);
+    if (!spill ||
+        !from ||
+        !to ||
+        !Number.isInteger(spill.inflight) ||
+        spill.inflight < 0) {
+        return undefined;
+    }
+    return { from, to, inflight: spill.inflight };
+}
 function routingDecisionValue(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return null;
@@ -259,8 +325,18 @@ function routingDecisionValue(value) {
         rotationOffset: decision.rotationOffset,
         initialAccount: decision.initialAccount,
         candidates: candidates,
+        ...optionalEvidence("policy", routingPolicyValue(decision.policy)),
+        ...optionalEvidence("affinity", routingAffinityValue(decision.affinity)),
+        ...optionalEvidence("spill", routingSpillValue(decision.spill)),
     };
 }
+// Evidence is optional per decision; a field that is absent or malformed is
+// left out rather than rejecting a decision that is otherwise valid.
+function optionalEvidence(key, value) {
+    return value === undefined
+        ? {}
+        : { [key]: value };
+}
 function percentile(sorted, fraction) {
     if (sorted.length === 0) {
         return null;

package/dist/proxy/proxyConfig.d.ts

@@ -10,7 +10,7 @@
  * YAML parsing uses `js-yaml` when available (dynamic import), otherwise
  * falls back to JSON.parse.
  */
-import type { LoadProxyConfigOptions, ProxyConfigFile } from "../types/index.js";
+import type { LoadProxyConfigOptions, ProxyConfigFile, ProxyRoutingConfig } from "../types/index.js";
 /** Default on-disk path used when `proxy start` is not given `--config`. */
 export declare function defaultProxyConfigPath(): string;
 /** Resolve `--config` the same way `proxy start` / `proxy install` do. */
@@ -30,6 +30,29 @@ export declare function resolveEnvVars(value: string, env?: Record<string, strin
  * Returns an array of human-readable error strings (empty = valid).
  */
 export declare function validateProxyConfig(config: unknown): string[];
+/**
+ * Parse the optional `routing` section from a raw proxy config object.
+ *
+ * Extracts:
+ * - `strategy` ("round-robin" | "fill-first")
+ * - `model-mappings` / `modelMappings` — array of {from, to, provider}
+ * - `fallback-chain` / `fallbackChain` — array of {provider, model, reasoningEffort?}
+ * - `auto-fallback` / `autoFallback` — opt in to an unspecified provider
+ * - `max-inflight-per-account` / `maxInflightPerAccount` — concurrency cap
+ * - `passthroughModels` / `passthrough-models` — array of model IDs
+ * - `quota-routing` / `quotaRouting` — quota-aware fill-first ordering
+ * - `session-soft-limit` / `sessionSoftLimit` — proactive handoff threshold
+ * - `session-reset-tolerance-ms` / `sessionResetToleranceMs` — reset bucket
+ * - `account-allowlist` / `accountAllowlist` — allowed Anthropic account IDs
+ * - `account-ranking` / `accountRanking` — expiry-first | headroom-first
+ * - `prefer-primary` / `preferPrimary` — bias ranking toward primaryAccount
+ * - `session-affinity` / `sessionAffinity` — sticky-session binding
+ * - `session-affinity-idle-ttl-ms` / `sessionAffinityIdleTtlMs` — idle unbind
+ * - `spill-inflight` / `spillInflight` — overflow threshold for sticky sessions
+ *
+ * Accepts both camelCase and kebab-case keys for YAML-friendliness.
+ */
+export declare function parseRoutingConfig(raw: Record<string, unknown> | undefined): Partial<ProxyRoutingConfig> | undefined;
 /**
  * Load and parse a proxy configuration file (YAML or JSON).
  *

package/dist/proxy/proxyConfig.js

@@ -213,6 +213,10 @@ const CODEX_REASONING_EFFORTS = [
 function isCodexReasoningEffort(value) {
     return CODEX_REASONING_EFFORTS.some((effort) => effort === value);
 }
+const MIN_SESSION_AFFINITY_IDLE_TTL_MS = 60_000;
+const MAX_SESSION_AFFINITY_IDLE_TTL_MS = 86_400_000;
+const MIN_SPILL_INFLIGHT = 0;
+const MAX_SPILL_INFLIGHT = 100;
 function kebabToCamelRoutingKey(kebabKey) {
     return kebabKey.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
 }
@@ -243,6 +247,20 @@ function readLegacyRoutingKey(routing, kebabKey) {
     const wasNull = value === undefined && (rawKebab === null || rawCamel === null);
     return { value, wasNull };
 }
+/**
+ * Reads a routing policy key under its kebab-case or camelCase spelling,
+ * choosing by presence rather than with `??`: `??` treats an explicit
+ * kebab-case `null` as absent and falls through to an unset camelCase key,
+ * so the same null would be silently defaulted under one spelling and
+ * rejected under the other. Unlike `readLegacyRoutingKey`, a `null` is
+ * returned as-is so validation rejects it: these five keys never accepted it.
+ */
+function readRoutingPolicyKey(routing, kebabKey) {
+    const camelKey = kebabToCamelRoutingKey(kebabKey);
+    return routing[kebabKey] !== undefined
+        ? routing[kebabKey]
+        : routing[camelKey];
+}
 /**
  * Validate the shape of a parsed proxy config.
  * Returns an array of human-readable error strings (empty = valid).
@@ -359,6 +377,48 @@ export function validateProxyConfig(config) {
                 errors.push("routing.session-reset-tolerance-ms must be a positive integer");
             }
         }
+        const rawAccountRanking = readRoutingPolicyKey(routing, "account-ranking");
+        if (rawAccountRanking !== undefined &&
+            rawAccountRanking !== "expiry-first" &&
+            rawAccountRanking !== "headroom-first") {
+            errors.push("routing.account-ranking must be expiry-first or headroom-first");
+        }
+        const rawPreferPrimary = readRoutingPolicyKey(routing, "prefer-primary");
+        const normalizedPreferPrimary = typeof rawPreferPrimary === "string"
+            ? rawPreferPrimary.trim().toLowerCase()
+            : undefined;
+        if (rawPreferPrimary !== undefined &&
+            typeof rawPreferPrimary !== "boolean" &&
+            normalizedPreferPrimary !== "true" &&
+            normalizedPreferPrimary !== "false") {
+            errors.push("routing.prefer-primary must be a boolean");
+        }
+        const rawSessionAffinity = readRoutingPolicyKey(routing, "session-affinity");
+        const normalizedSessionAffinity = typeof rawSessionAffinity === "string"
+            ? rawSessionAffinity.trim().toLowerCase()
+            : undefined;
+        if (rawSessionAffinity !== undefined &&
+            typeof rawSessionAffinity !== "boolean" &&
+            normalizedSessionAffinity !== "true" &&
+            normalizedSessionAffinity !== "false") {
+            errors.push("routing.session-affinity must be a boolean");
+        }
+        const rawAffinityTtl = readRoutingPolicyKey(routing, "session-affinity-idle-ttl-ms");
+        if (rawAffinityTtl !== undefined &&
+            (typeof rawAffinityTtl !== "number" ||
+                !Number.isInteger(rawAffinityTtl) ||
+                rawAffinityTtl < MIN_SESSION_AFFINITY_IDLE_TTL_MS ||
+                rawAffinityTtl > MAX_SESSION_AFFINITY_IDLE_TTL_MS)) {
+            errors.push("routing.session-affinity-idle-ttl-ms must be an integer between 60000 and 86400000");
+        }
+        const rawSpillInflight = readRoutingPolicyKey(routing, "spill-inflight");
+        if (rawSpillInflight !== undefined &&
+            (typeof rawSpillInflight !== "number" ||
+                !Number.isInteger(rawSpillInflight) ||
+                rawSpillInflight < MIN_SPILL_INFLIGHT ||
+                rawSpillInflight > MAX_SPILL_INFLIGHT)) {
+            errors.push("routing.spill-inflight must be an integer between 0 and 100");
+        }
     }
     if (!hasAccounts && !hasRouting) {
         errors.push('Config must contain at least one of "accounts" or "routing"');
@@ -434,10 +494,15 @@ function warnPlaintextApiKeys(accounts) {
  * - `session-soft-limit` / `sessionSoftLimit` — proactive handoff threshold
  * - `session-reset-tolerance-ms` / `sessionResetToleranceMs` — reset bucket
  * - `account-allowlist` / `accountAllowlist` — allowed Anthropic account IDs
+ * - `account-ranking` / `accountRanking` — expiry-first | headroom-first
+ * - `prefer-primary` / `preferPrimary` — bias ranking toward primaryAccount
+ * - `session-affinity` / `sessionAffinity` — sticky-session binding
+ * - `session-affinity-idle-ttl-ms` / `sessionAffinityIdleTtlMs` — idle unbind
+ * - `spill-inflight` / `spillInflight` — overflow threshold for sticky sessions
  *
  * Accepts both camelCase and kebab-case keys for YAML-friendliness.
  */
-function parseRoutingConfig(raw) {
+export function parseRoutingConfig(raw) {
     if (!raw || typeof raw !== "object") {
         return undefined;
     }
@@ -603,8 +668,10 @@ function parseRoutingConfig(raw) {
         }
     }
     // Primary account (accept kebab-case or camelCase). Email or label of the
-    // Anthropic account that should be tried first ("home"). Resolved to a
-    // stable key (anthropic:<email>) at proxy boot; absence preserves the
+    // Anthropic account used as "home": under quota routing it is the
+    // ranking's final tiebreaker unless prefer-primary is set, and it is
+    // tried first only when quota routing is disabled. Resolved to a stable
+    // key (anthropic:<email>) at proxy boot; absence preserves the
     // pre-existing insertion-order behavior.
     const rawPrimary = (raw["primary-account"] ?? raw.primaryAccount);
     if (rawPrimary !== undefined) {
@@ -626,6 +693,67 @@ function parseRoutingConfig(raw) {
             ...new Set(rawAccountAllowlist.map((entry) => String(entry).trim())),
         ];
     }
+    const rawAccountRanking = readRoutingPolicyKey(raw, "account-ranking");
+    if (rawAccountRanking !== undefined) {
+        if (rawAccountRanking === "expiry-first" ||
+            rawAccountRanking === "headroom-first") {
+            result.accountRanking = rawAccountRanking;
+        }
+        else {
+            logger.warn(`[proxy-config] Ignoring routing.accountRanking: expected expiry-first|headroom-first, got ${String(rawAccountRanking)}`);
+        }
+    }
+    const rawPreferPrimary = readRoutingPolicyKey(raw, "prefer-primary");
+    if (rawPreferPrimary !== undefined) {
+        if (typeof rawPreferPrimary === "boolean") {
+            result.preferPrimary = rawPreferPrimary;
+        }
+        else if (typeof rawPreferPrimary === "string" &&
+            ["true", "false"].includes(rawPreferPrimary.trim().toLowerCase())) {
+            result.preferPrimary = rawPreferPrimary.trim().toLowerCase() === "true";
+        }
+        else {
+            logger.warn(`[proxy-config] Ignoring routing.preferPrimary: expected boolean, got ${typeof rawPreferPrimary}`);
+        }
+    }
+    const rawSessionAffinity = readRoutingPolicyKey(raw, "session-affinity");
+    if (rawSessionAffinity !== undefined) {
+        if (typeof rawSessionAffinity === "boolean") {
+            result.sessionAffinity = rawSessionAffinity;
+        }
+        else if (typeof rawSessionAffinity === "string" &&
+            ["true", "false"].includes(rawSessionAffinity.trim().toLowerCase())) {
+            result.sessionAffinity =
+                rawSessionAffinity.trim().toLowerCase() === "true";
+        }
+        else {
+            logger.warn(`[proxy-config] Ignoring routing.sessionAffinity: expected boolean, got ${typeof rawSessionAffinity}`);
+        }
+    }
+    const rawAffinityTtl = readRoutingPolicyKey(raw, "session-affinity-idle-ttl-ms");
+    if (rawAffinityTtl !== undefined) {
+        if (typeof rawAffinityTtl === "number" &&
+            Number.isInteger(rawAffinityTtl) &&
+            rawAffinityTtl >= MIN_SESSION_AFFINITY_IDLE_TTL_MS &&
+            rawAffinityTtl <= MAX_SESSION_AFFINITY_IDLE_TTL_MS) {
+            result.sessionAffinityIdleTtlMs = rawAffinityTtl;
+        }
+        else {
+            logger.warn(`[proxy-config] Ignoring routing.sessionAffinityIdleTtlMs: expected integer between 60000 and 86400000, got ${String(rawAffinityTtl)}`);
+        }
+    }
+    const rawSpillInflight = readRoutingPolicyKey(raw, "spill-inflight");
+    if (rawSpillInflight !== undefined) {
+        if (typeof rawSpillInflight === "number" &&
+            Number.isInteger(rawSpillInflight) &&
+            rawSpillInflight >= MIN_SPILL_INFLIGHT &&
+            rawSpillInflight <= MAX_SPILL_INFLIGHT) {
+            result.spillInflight = rawSpillInflight;
+        }
+        else {
+            logger.warn(`[proxy-config] Ignoring routing.spillInflight: expected integer between 0 and 100, got ${String(rawSpillInflight)}`);
+        }
+    }
     return result;
 }
 // ---------------------------------------------------------------------------

package/dist/proxy/routingEvidence.d.ts

@@ -1,7 +1,7 @@
 /** Schema-v1 routing evidence values shared by emitters and offline readers. */
 export declare const PROXY_ACCOUNT_ROUTING_STRATEGIES: readonly ["round-robin", "fill-first"];
 export declare const PROXY_ACCOUNT_ROUTING_MODES: readonly ["quota", "primary", "round_robin", "single_account"];
-export declare const PROXY_ACCOUNT_ROUTING_REASONS: readonly ["single_account", "round_robin", "configured_primary", "insertion_order", "availability", "cooldown_recovery", "quota_evidence", "quota_probe", "session_headroom", "scoped_headroom", "session_reset", "weekly_reset", "weekly_utilization", "scoped_utilization"];
+export declare const PROXY_ACCOUNT_ROUTING_REASONS: readonly ["single_account", "round_robin", "configured_primary", "insertion_order", "availability", "cooldown_recovery", "quota_evidence", "quota_probe", "session_headroom", "scoped_headroom", "session_reset", "weekly_reset", "weekly_utilization", "scoped_utilization", "headroom", "session_affinity", "preferred_primary", "spill_inflight", "routing_policy_error"];
 export declare const PROXY_ACCOUNT_TYPES: readonly ["oauth", "api_key"];
 export declare const ACCOUNT_COOLING_REASONS: readonly ["weekly", "session", "unified", "transient", "auth"];
 /**

package/dist/proxy/routingEvidence.js

@@ -26,6 +26,11 @@ export const PROXY_ACCOUNT_ROUTING_REASONS = [
     "weekly_reset",
     "weekly_utilization",
     "scoped_utilization",
+    "headroom",
+    "session_affinity",
+    "preferred_primary",
+    "spill_inflight",
+    "routing_policy_error",
 ];
 export const PROXY_ACCOUNT_TYPES = ["oauth", "api_key"];
 export const ACCOUNT_COOLING_REASONS = [

package/dist/proxy/runtimeConfig.js

@@ -229,6 +229,11 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
         .digest("hex")
         .slice(0, 16);
     const useOverage = routing?.useOverage ?? "auto";
+    const accountRanking = routing?.accountRanking ?? "expiry-first";
+    const preferPrimary = routing?.preferPrimary ?? false;
+    const sessionAffinity = routing?.sessionAffinity ?? false;
+    const sessionAffinityIdleTtlMs = routing?.sessionAffinityIdleTtlMs ?? 3_600_000;
+    const spillInflight = routing?.spillInflight ?? 0;
     const fingerprintSource = JSON.stringify({
         strategy,
         passthrough: options.passthrough,
@@ -239,6 +244,11 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
         sessionSoftLimit,
         sessionResetToleranceMs,
         useOverage,
+        accountRanking,
+        preferPrimary,
+        sessionAffinity,
+        sessionAffinityIdleTtlMs,
+        spillInflight,
     });
     const configHash = createHash("sha256")
         .update(fingerprintSource)
@@ -259,6 +269,11 @@ async function buildCandidate(options, generation, allowMissingConfig, allowMiss
             sessionSoftLimit,
             sessionResetToleranceMs,
             useOverage,
+            accountRanking,
+            preferPrimary,
+            sessionAffinity,
+            sessionAffinityIdleTtlMs,
+            spillInflight,
         }),
         configFilePresent,
         envFilePresent,