@cortexkit/anthropic-auth-core 1.21.0 → 1.23.0

package/dist/quota-manager.js

@@ -51,6 +51,8 @@ export class QuotaManager {
     // --- Inflight deduplication ---
     inflightMain = null;
     inflightMainAccountId;
+    inflightMainAccessToken;
+    inflightMainToken = 0;
     inflightFallbacks = new Map();
     // --- Rate-limiting (scoped per route so a fallback 429 never backs off the
     // main account or vice versa) ---
@@ -62,15 +64,21 @@ export class QuotaManager {
     // --- Config ---
     storage;
     fetchImpl;
+    fetchQuotaSnapshot;
     now;
     onMainQuotaFetched;
     onApiError;
+    onFallbackQuotaFetched;
+    onFallbackApiError;
     constructor(opts) {
         this.storage = opts.storage;
         this.fetchImpl = opts.fetchImpl ?? fetch;
+        this.fetchQuotaSnapshot = opts.fetchQuotaSnapshot;
         this.now = opts.now ?? Date.now;
         this.onMainQuotaFetched = opts.onMainQuotaFetched;
         this.onApiError = opts.onApiError;
+        this.onFallbackQuotaFetched = opts.onFallbackQuotaFetched;
+        this.onFallbackApiError = opts.onFallbackApiError;
         this.seedMainFromStorage(opts.storage, opts.storage?.mainAccountId);
         this.seedMainBackoffFromStorage(opts.storage);
     }
@@ -99,6 +107,12 @@ export class QuotaManager {
         this.bindFallbackLineage(accountId, account);
         return this.fallbacks.get(accountId) ?? null;
     }
+    /** A host transport resolves scoped credentials at dispatch time. */
+    canFetchWithoutAccessToken() {
+        return Boolean(this.fetchQuotaSnapshot &&
+            (this.storage === null ||
+                this.storage?.claustrum?.scopedRoster === true));
+    }
     getAllFallbacks() {
         return this.fallbacks;
     }
@@ -109,11 +123,16 @@ export class QuotaManager {
         this.mainAccountId = mainAccountId;
         this.main = entry;
     }
+    clearMain() {
+        this.mainAccountId = undefined;
+        this.main = null;
+    }
     /** Bind quota state to the account behind the current main credential. */
-    setMainQuotaAccountIdentity(accountIdentity, strict = true) {
+    setMainQuotaAccountIdentity(accountIdentity, strict = true, force = false) {
         const previousIdentityKnown = this.mainQuotaIdentityKnown;
         const previousAccountIdentity = this.mainAccountId;
-        const changed = !previousIdentityKnown ||
+        const changed = force ||
+            !previousIdentityKnown ||
             this.mainAccountId !== accountIdentity ||
             this.mainQuotaIdentityStrict !== strict;
         this.mainQuotaIdentityKnown = true;
@@ -122,7 +141,13 @@ export class QuotaManager {
             return undefined;
         this.mainGeneration += 1;
         this.mainAccountId = accountIdentity;
-        if (accountIdentity !== undefined &&
+        if (force) {
+            this.main = null;
+            this.mainLastApiError = undefined;
+            this.mainQuotaErrorGeneration += 1;
+            this.mainQuotaErrorClearedAt = mergeMainQuotaErrorClearedAt(this.mainQuotaErrorClearedAt, this.now());
+        }
+        else if (accountIdentity !== undefined &&
             this.main?.quota.accountIdentity !== accountIdentity) {
             this.main = null;
         }
@@ -191,14 +216,14 @@ export class QuotaManager {
     async refreshMain(mainAccountIdOrAccessToken, accessToken, expectedIdentityGeneration) {
         const mainAccountId = mainAccountIdOrAccessToken;
         const credential = accessToken ?? mainAccountIdOrAccessToken;
-        if (!credential)
+        if (!credential && !this.canFetchWithoutAccessToken())
             throw new Error('Main OAuth access token is unavailable');
         return (await this.refreshMainWithMetadata(mainAccountId, credential, expectedIdentityGeneration)).quota;
     }
     async refreshMainWithMetadata(mainAccountIdOrAccessToken, accessToken, expectedIdentityGeneration) {
         const effectiveAccountId = mainAccountIdOrAccessToken;
         const credential = accessToken ?? mainAccountIdOrAccessToken;
-        if (!credential)
+        if (!credential && !this.canFetchWithoutAccessToken())
             throw new Error('Main OAuth access token is unavailable');
         if (expectedIdentityGeneration !== undefined &&
             (this.mainGeneration !== expectedIdentityGeneration ||
@@ -211,7 +236,9 @@ export class QuotaManager {
             if (this.mainQuotaIdentityKnown)
                 this.mainGeneration += 1;
         }
-        if (this.inflightMain && this.inflightMainAccountId === effectiveAccountId)
+        if (this.inflightMain &&
+            this.inflightMainAccountId === effectiveAccountId &&
+            this.inflightMainAccessToken === credential)
             return this.inflightMain;
         // Rate-limit — if API recently 429'd, return stale or throw
         if (this.isBackedOff()) {
@@ -221,14 +248,19 @@ export class QuotaManager {
             throw new Error('Quota API rate-limited — try again later');
         }
         this.inflightMainAccountId = effectiveAccountId;
+        this.inflightMainAccessToken = credential;
         const generation = this.mainGeneration;
-        this.inflightMain = this._fetchMain(effectiveAccountId, credential, generation);
+        const inflightToken = ++this.inflightMainToken;
+        this.inflightMain = this._fetchMain(effectiveAccountId, credential ?? '', generation, inflightToken);
         return this.inflightMain;
     }
     async refreshFallback(accountId, accessToken, account) {
         return (await this.refreshFallbackWithMetadata(accountId, accessToken, account)).quota;
     }
     async refreshFallbackWithMetadata(accountId, accessToken, account) {
+        if (!accessToken && !this.canFetchWithoutAccessToken()) {
+            throw new Error('Fallback OAuth access token is unavailable');
+        }
         this.bindFallbackLineage(accountId, account);
         const inflightKey = QuotaManager.fallbackInflightKey(accountId);
         const inflight = this.inflightFallbacks.get(inflightKey);
@@ -255,19 +287,26 @@ export class QuotaManager {
         });
         return promise;
     }
-    async refreshAllFallbacks(accounts) {
+    async refreshAllFallbacks(accounts, resolveAccessToken) {
         const now = this.now();
         for (const account of accounts) {
             if (account.enabled === false)
                 continue;
-            if (!account.access)
+            const accessToken = resolveAccessToken !== undefined
+                ? resolveAccessToken(account)
+                : account.access &&
+                    account.expires !== undefined &&
+                    account.expires > now
+                    ? account.access
+                    : undefined;
+            if (!accessToken)
                 continue;
             this.bindFallbackLineage(account.id, account);
             const cached = this.getFallback(account.id);
             if (cached && now < cached.refreshAfter)
                 continue;
             try {
-                await this.refreshFallback(account.id, account.access, account);
+                await this.refreshFallback(account.id, accessToken, account);
             }
             catch {
                 // Best-effort — keep stale cache entry if fetch fails
@@ -462,6 +501,18 @@ export class QuotaManager {
                 continue;
             if (account.enabled === false)
                 continue;
+            const persistedError = account.lastQuotaRefreshError;
+            const persistedClearAt = quotaSnapshotCheckedAt(account.quota);
+            const currentError = this.fallbackApiErrors.get(account.id);
+            if (persistedError &&
+                quotaBackoffActive(persistedError, this.now()) &&
+                persistedClearAt <= (persistedError.checkedAt ?? 0) &&
+                (!currentError || persistedError.checkedAt >= currentError.checkedAt)) {
+                this.fallbackApiErrors.set(account.id, persistedError);
+            }
+            else if (currentError && persistedClearAt >= currentError.checkedAt) {
+                this.fallbackApiErrors.delete(account.id);
+            }
             if (!account.quota)
                 continue;
             const checkedAt = quotaSnapshotCheckedAt(account.quota);
@@ -553,6 +604,12 @@ export class QuotaManager {
             this.fallbackAuthLineages.set(accountId, observedLineage);
         return true;
     }
+    isClosed = false;
+    close() {
+        this.isClosed = true;
+        this.inflightFallbacks.clear();
+        this.inflightMain = null;
+    }
     /**
      * Serialize API calls through a shared gate so only one
      * quota API request runs at a time, with a minimum gap
@@ -561,6 +618,8 @@ export class QuotaManager {
      */
     _enqueueApiFetch(fn) {
         const gatedFn = async () => {
+            if (this.isClosed)
+                throw new Error('QuotaManager is closed');
             // Wait until minimum gap since last API call
             const elapsed = this.now() - this.lastApiCallAt;
             if (elapsed < QuotaManager.API_CALL_GAP_MS) {
@@ -570,6 +629,8 @@ export class QuotaManager {
                         id.unref();
                 });
             }
+            if (this.isClosed)
+                throw new Error('QuotaManager is closed');
             this.lastApiCallAt = this.now();
             return fn();
         };
@@ -577,7 +638,7 @@ export class QuotaManager {
         this.apiGate = queued.catch(() => { });
         return queued;
     }
-    async _fetchMain(mainAccountId, accessToken, generation) {
+    async _fetchMain(mainAccountId, accessToken, generation, inflightToken) {
         return this._enqueueApiFetch(async () => {
             try {
                 // Re-check backoff inside gate — may have been set by
@@ -611,11 +672,17 @@ export class QuotaManager {
                 }
                 try {
                     const fetchStartedAt = this.now();
-                    const quota = await fetchOAuthQuotaSnapshot({
-                        accessToken,
-                        fetchImpl: this.fetchImpl,
-                        now: this.now,
-                    });
+                    const quota = this.fetchQuotaSnapshot
+                        ? await this.fetchQuotaSnapshot({
+                            kind: 'main',
+                            accountId: mainAccountId,
+                            accessToken,
+                        })
+                        : await fetchOAuthQuotaSnapshot({
+                            accessToken,
+                            fetchImpl: this.fetchImpl,
+                            now: this.now,
+                        });
                     const now = this.now();
                     if (this.mainQuotaIdentityKnown &&
                         this.mainQuotaIdentityStrict &&
@@ -664,7 +731,7 @@ export class QuotaManager {
                 }
             }
             finally {
-                if (this.inflightMainAccountId === mainAccountId) {
+                if (this.inflightMainToken === inflightToken) {
                     this.inflightMain = null;
                     this.inflightMainAccountId = undefined;
                 }
@@ -696,11 +763,18 @@ export class QuotaManager {
                     throw new Error('Quota refresh is already in progress');
                 }
                 try {
-                    const quota = await fetchOAuthQuotaSnapshot({
-                        accessToken,
-                        fetchImpl: this.fetchImpl,
-                        now: this.now,
-                    });
+                    const fetchStartedAt = this.now();
+                    const quota = this.fetchQuotaSnapshot
+                        ? await this.fetchQuotaSnapshot({
+                            kind: 'fallback',
+                            accountId,
+                            accessToken,
+                        })
+                        : await fetchOAuthQuotaSnapshot({
+                            accessToken,
+                            fetchImpl: this.fetchImpl,
+                            now: this.now,
+                        });
                     const now = this.now();
                     if ((this.fallbackGenerations.get(accountId) ?? 0) !== generation) {
                         return {
@@ -715,6 +789,7 @@ export class QuotaManager {
                         checkedAt: completedQuota.checkedAt ?? now,
                     }, account);
                     this.fallbackApiErrors.delete(accountId);
+                    this.onFallbackQuotaFetched?.(accountId, completedQuota, now, fetchStartedAt);
                     return { quota: completedQuota, fetched: true };
                 }
                 finally {
@@ -769,11 +844,13 @@ export class QuotaManager {
         if (QuotaManager.isAuthError(error))
             return;
         const previous = this.fallbackApiErrors.get(accountId);
-        this.fallbackApiErrors.set(accountId, buildQuotaOperationError({
+        const quotaError = buildQuotaOperationError({
             error,
             now: this.now(),
             previous,
             accountIdentity: accountId,
-        }));
+        });
+        this.fallbackApiErrors.set(accountId, quotaError);
+        this.onFallbackApiError?.(accountId, quotaError);
     }
 }

package/dist/relay.d.ts

@@ -11,6 +11,12 @@ export type RelayPatch = {
     deleteCount: number;
     insert: string;
 };
+export type RelayAttemptAuthorization = {
+    headers: Headers;
+    /** Called only for a genuine upstream response, never optimistic/transport status. */
+    onUpstreamStatus?: (status: number) => void;
+};
+export type AuthorizeRelayAttempt = () => Promise<RelayAttemptAuthorization>;
 export declare function getRelayConfig(storage: AccountStorage | null): RelayConfig | null;
 export declare function generateRelayToken(): string;
 export declare function hashBody(body: string): string;
@@ -24,6 +30,8 @@ export declare function sendViaRelay(options: {
     fallback: () => Promise<Response>;
     affinity?: string | null;
     optimisticResponse?: boolean;
+    /** Fresh authorization for every physical relay attempt, including internal retries. */
+    authorizeAttempt?: AuthorizeRelayAttempt;
     /**
      * Observes genuine upstream headers once per delivered response. WebSocket
      * retries before downstream bytes replace staged headers, so the callback

package/dist/relay.js

@@ -2,6 +2,28 @@ import { Buffer } from 'node:buffer';
 import { createHash, randomBytes } from 'node:crypto';
 import { dumpRelayRequest } from './dump.js';
 import { relayLog } from './logger.js';
+class RelayAuthorizationError extends Error {
+    failure;
+    constructor(failure) {
+        super('Relay request authorization failed');
+        this.failure = failure;
+    }
+}
+async function authorizeRelayPayload(payload, authorize) {
+    if (!authorize)
+        return undefined;
+    try {
+        const attempt = await authorize();
+        payload.upstream = {
+            ...payload.upstream,
+            headers: jsonHeaders(attempt.headers),
+        };
+        return attempt;
+    }
+    catch (error) {
+        throw new RelayAuthorizationError(error);
+    }
+}
 class RelayStateMismatchError extends Error {
 }
 class RelayWebSocketConnectionResetError extends Error {
@@ -229,15 +251,29 @@ function updateLocalRelayState(affinity, bodyText, nextHash, revision) {
     cleanupRelaySessionCaches(now);
 }
 async function sendRelayHttp(options) {
-    const { config, payload, bodyText, fallback, signal } = options;
+    const { config, payload, bodyText, fallback, signal, authorizeAttempt } = options;
     let actualPayload = payload;
+    let authorization = authorizeAttempt
+        ? await authorizeRelayPayload(actualPayload, authorizeAttempt)
+        : undefined;
     let response = await postRelay(config, actualPayload, signal);
     if (response.status === 409 && actualPayload.mode === 'patch') {
         relayLog(`state mismatch from relay session=${shortAffinity(actualPayload.affinity)}; retrying full_sync`);
         await response.body?.cancel().catch(() => { });
         actualPayload = createFullSyncPayload(actualPayload, bodyText);
+        authorization = authorizeAttempt
+            ? await authorizeRelayPayload(actualPayload, authorizeAttempt)
+            : undefined;
         response = await postRelay(config, actualPayload, signal);
     }
+    // Old workers already forward Anthropic request IDs. Without upstream
+    // provenance a relay's own 401 must never invalidate an OAuth credential.
+    if (/^req_[A-Za-z0-9_-]+$/.test(response.headers.get('request-id') ?? '')) {
+        try {
+            authorization?.onUpstreamStatus?.(response.status);
+        }
+        catch { }
+    }
     if (!response.ok && response.status >= 500 && config.fallbackToDirect) {
         relayLog(`relay returned ${response.status}; falling back direct session=${shortAffinity(actualPayload.affinity)}`);
         await response.body?.cancel().catch(() => { });
@@ -325,12 +361,12 @@ class PersistentRelaySession {
         this.serverState = undefined;
         this.connecting = undefined;
     }
-    send(payload, bodyText, optimisticResponse = false, onResponseHeaders) {
+    send(payload, bodyText, optimisticResponse = false, onResponseHeaders, authorizeAttempt) {
         this.touch();
         const enqueuedAt = perfNowMs();
         const start = this.queue
             .catch(() => { })
-            .then(() => this.startQueued(payload, bodyText, enqueuedAt, optimisticResponse, onResponseHeaders));
+            .then(() => this.startQueued(payload, bodyText, enqueuedAt, optimisticResponse, onResponseHeaders, authorizeAttempt));
         const result = start.then(async ({ response, getPayload }) => ({
             response: await response,
             payload: getPayload(),
@@ -341,7 +377,7 @@ class PersistentRelaySession {
         this.queue = start.then(({ done }) => done.catch(() => { }), () => { });
         return result;
     }
-    async startQueued(payload, bodyText, enqueuedAt, optimisticResponse, onResponseHeaders) {
+    async startQueued(payload, bodyText, enqueuedAt, optimisticResponse, onResponseHeaders, authorizeAttempt) {
         const connectStart = perfNowMs();
         await this.ensureConnected();
         const connectedAt = perfNowMs();
@@ -364,11 +400,14 @@ class PersistentRelaySession {
             requestPayload.patch = createRelayPatch(localState.body, bodyText);
         }
         relayLog(`perf websocket send_start session=${shortAffinity(this.affinity)} request=${requestPayload.id} mode=${requestPayload.mode} queueMs=${formatMs(connectedAt - enqueuedAt)} connectMs=${formatMs(connectedAt - connectStart)} bodyBytes=${bodyText.length} relayBytes=${JSON.stringify(requestPayload).length}`);
+        const authorization = authorizeAttempt
+            ? await authorizeRelayPayload(requestPayload, authorizeAttempt)
+            : undefined;
         let activePayload = requestPayload;
-        const first = this.sendPayload(requestPayload, bodyText, optimisticResponse, onResponseHeaders);
+        const first = this.sendPayload(requestPayload, bodyText, optimisticResponse, onResponseHeaders, authorizeAttempt, authorization);
         void first.done.catch(() => { });
         let activeDone = first.done;
-        const response = first.response.catch((error) => {
+        const response = first.response.catch(async (error) => {
             if (!(error instanceof RelayStateMismatchError) ||
                 requestPayload.mode !== 'patch') {
                 throw error;
@@ -377,8 +416,11 @@ class PersistentRelaySession {
             fullSync.protocol = 2;
             fullSync.id = createRequestId();
             fullSync.revision = (this.serverState?.revision ?? 0) + 1;
+            const retryAuthorization = authorizeAttempt
+                ? await authorizeRelayPayload(fullSync, authorizeAttempt)
+                : undefined;
             activePayload = fullSync;
-            const retry = this.sendPayload(fullSync, bodyText, optimisticResponse, onResponseHeaders);
+            const retry = this.sendPayload(fullSync, bodyText, optimisticResponse, onResponseHeaders, authorizeAttempt, retryAuthorization);
             void retry.done.catch(() => { });
             activeDone = retry.done;
             return retry.response;
@@ -459,7 +501,7 @@ class PersistentRelaySession {
         });
         await this.connecting;
     }
-    sendPayload(payload, bodyText, optimisticResponse, onResponseHeaders) {
+    sendPayload(payload, bodyText, optimisticResponse, onResponseHeaders, authorizeAttempt, authorization) {
         const socket = this.socket;
         if (!socket || socket.readyState !== WebSocket.OPEN) {
             throw new Error('relay websocket is not connected');
@@ -489,6 +531,8 @@ class PersistentRelaySession {
                 retryAttempts: 0,
                 retryingBeforeResponse: false,
                 onResponseHeaders,
+                authorizeAttempt,
+                authorization,
                 stagedResponseHeaders: undefined,
                 responseHeadersDelivered: false,
             };
@@ -541,6 +585,12 @@ class PersistentRelaySession {
                 retryPayload.protocol = 2;
                 retryPayload.id = createRequestId();
                 retryPayload.revision = (this.serverState?.revision ?? 0) + 1;
+                const authorization = pending.authorizeAttempt
+                    ? await authorizeRelayPayload(retryPayload, pending.authorizeAttempt)
+                    : undefined;
+                if (this.pending !== pending || pending.streamDone)
+                    return;
+                pending.authorization = authorization;
                 pending.payload = retryPayload;
                 pending.accepted = false;
                 pending.acceptedAt = undefined;
@@ -560,7 +610,7 @@ class PersistentRelaySession {
             catch (error) {
                 pending.retryingBeforeResponse = false;
                 if (this.pending === pending)
-                    this.failPending(error);
+                    this.failPending(error instanceof RelayAuthorizationError ? error.failure : error);
             }
         })();
         return true;
@@ -631,8 +681,12 @@ class PersistentRelaySession {
                 return;
             const responseStartedAt = perfNowMs();
             pending.responseStartedAt = responseStartedAt;
+            try {
+                pending.authorization?.onUpstreamStatus?.(message.status);
+            }
+            catch { }
             relayLog(`perf websocket response_start session=${shortAffinity(this.affinity)} request=${pending.payload.id} sentMs=${formatMs(responseStartedAt - pending.sentAt)} upstreamMs=${pending.acceptedAt == null ? 'unknown' : formatMs(responseStartedAt - pending.acceptedAt)} status=${message.status}`);
-            clearTimeout(pending.timeout);
+            this.timers.clearTimeout(pending.timeout);
             if (message.headers)
                 pending.stagedResponseHeaders = new Headers(message.headers);
             this.resolvePendingResponse(pending, message.status, message.statusText, message.headers);
@@ -752,7 +806,7 @@ function getPersistentRelaySession(config, affinity, timers) {
     return session;
 }
 export async function sendViaRelay(options) {
-    const { config, input, init, headers, body, fallback, affinity: explicitAffinity, optimisticResponse, onResponseHeaders, dumpTag, onDumpCreated, setTimeoutImpl = globalThis.setTimeout, clearTimeoutImpl = globalThis.clearTimeout, } = options;
+    const { config, input, init, headers, body, fallback, affinity: explicitAffinity, optimisticResponse, authorizeAttempt, onResponseHeaders, dumpTag, onDumpCreated, setTimeoutImpl = globalThis.setTimeout, clearTimeoutImpl = globalThis.clearTimeout, } = options;
     if (!config || !isRelayableAnthropicRequest(input, body))
         return fallback();
     const affinity = explicitAffinity ||
@@ -797,9 +851,11 @@ export async function sendViaRelay(options) {
                     setTimeout: setTimeoutImpl,
                     clearTimeout: clearTimeoutImpl,
                 });
-                result = await session.send(payload, bodyText, optimisticResponse === true, onResponseHeaders);
+                result = await session.send(payload, bodyText, optimisticResponse === true, onResponseHeaders, authorizeAttempt);
             }
             catch (error) {
+                if (error instanceof RelayAuthorizationError)
+                    throw error;
                 relayLog(`websocket relay failed session=${shortAffinity(affinity)}; trying http relay: ${error instanceof Error ? error.message : String(error)}`);
                 result = await sendRelayHttp({
                     config,
@@ -807,6 +863,7 @@ export async function sendViaRelay(options) {
                     bodyText,
                     fallback,
                     signal: init?.signal,
+                    authorizeAttempt,
                 });
             }
         }
@@ -817,6 +874,7 @@ export async function sendViaRelay(options) {
                 bodyText,
                 fallback,
                 signal: init?.signal,
+                authorizeAttempt,
             });
         }
         relayPerfLog('send', {
@@ -873,6 +931,8 @@ export async function sendViaRelay(options) {
         return result.response;
     }
     catch (error) {
+        if (error instanceof RelayAuthorizationError)
+            throw error.failure;
         if (!config.fallbackToDirect) {
             relayLog(`relay failed session=${shortAffinity(affinity)} and fallbackToDirect=false: ${error instanceof Error ? error.message : String(error)}`);
             throw error;

package/dist/sticky-routing.d.ts

@@ -23,6 +23,7 @@ export type StickyRouteCandidate = {
 export type StickyRouteAssignment = {
     accountId: string;
     family: StickyRouteFamily;
+    affinityModelId?: string;
     assignedAt: number;
     lastSeenAt: number;
     initialInputBytes: number;
@@ -99,6 +100,7 @@ export declare class StickySessionRouter {
         sessionId: string;
         family: StickyRouteFamily;
         modelId?: string;
+        affinityModelId?: string;
         candidates: readonly StickyRouteCandidate[];
         retainAccountIds: ReadonlySet<string>;
         storage: AccountStorage | null;

package/dist/sticky-routing.js

@@ -91,9 +91,16 @@ function normalizeAssignment(value) {
         quotaCheckedAt === undefined) {
         return;
     }
+    if (Object.hasOwn(value, 'affinityModelId') &&
+        typeof value.affinityModelId !== 'string') {
+        return;
+    }
     return {
         accountId: value.accountId,
         family: value.family,
+        affinityModelId: typeof value.affinityModelId === 'string'
+            ? value.affinityModelId
+            : undefined,
         assignedAt,
         lastSeenAt,
         initialInputBytes: Math.max(0, initialInputBytes),
@@ -429,9 +436,14 @@ export class StickySessionRouter {
             return null;
         await this.refreshStateIfChanged();
         const key = sessionKey(input.sessionId);
+        const affinityModelId = input.affinityModelId ?? input.modelId;
+        const matchesAffinity = (assignment) => affinityModelId !== undefined
+            ? assignment.affinityModelId === affinityModelId
+            : assignment.family === input.family;
         const cached = this.state.assignments[key];
         if (cached &&
             this.assignmentIsActive(cached) &&
+            matchesAffinity(cached) &&
             input.retainAccountIds.has(cached.accountId) &&
             !input.excludeAccountIds?.has(cached.accountId)) {
             if (this.now() - cached.lastSeenAt >= STICKY_ROUTING_TOUCH_INTERVAL_MS) {
@@ -451,6 +463,7 @@ export class StickySessionRouter {
             this.prune(state);
             const current = state.assignments[key];
             if (current &&
+                matchesAffinity(current) &&
                 input.retainAccountIds.has(current.accountId) &&
                 !input.excludeAccountIds?.has(current.accountId)) {
                 current.lastSeenAt = this.now();
@@ -462,8 +475,12 @@ export class StickySessionRouter {
                     migrated: false,
                 };
             }
+            const affinityChanged = Boolean(current && !matchesAffinity(current));
+            if (affinityChanged) {
+                delete state.assignments[key];
+            }
             const candidates = input.candidates.filter((candidate) => !input.excludeAccountIds?.has(candidate.accountId));
-            const preferred = input.preferredAccountId
+            const preferred = !affinityChanged && input.preferredAccountId
                 ? candidates.find((candidate) => candidate.accountId === input.preferredAccountId &&
                     stickyRouteCandidateWeight({
                         candidate,
@@ -486,6 +503,7 @@ export class StickySessionRouter {
             const assignment = {
                 accountId: selected.accountId,
                 family: input.family,
+                affinityModelId,
                 assignedAt: now,
                 lastSeenAt: now,
                 initialInputBytes: Math.max(1, input.inputBytes),

package/dist/thinking-binding.d.ts

@@ -0,0 +1,7 @@
+import type { AccountStorage } from './accounts.ts';
+export declare const THINKING_BINDING_CONTROLS_BETA = "thinking-binding-controls-2026-08-01";
+export type ThinkingPrefixMismatchBehavior = 'account-default' | 'error' | 'drop_block';
+export declare function getThinkingPrefixMismatchBehavior(storage: Pick<AccountStorage, 'thinkingBinding'> | null | undefined): ThinkingPrefixMismatchBehavior;
+export declare function hasReplayableThinkingBlocks(body: Record<string, unknown>): boolean;
+export declare function applyThinkingBindingControls(body: Record<string, unknown>, behavior?: ThinkingPrefixMismatchBehavior): boolean;
+export declare function hasThinkingBindingControls(body: Record<string, unknown>): boolean;

package/dist/thinking-binding.js

@@ -0,0 +1,54 @@
+import { isClaudeFable51Model } from './models.js';
+export const THINKING_BINDING_CONTROLS_BETA = 'thinking-binding-controls-2026-08-01';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isReplayableThinkingBlock(block) {
+    if (!isRecord(block))
+        return false;
+    if (block.type === 'thinking') {
+        return typeof block.signature === 'string' && block.signature.length > 0;
+    }
+    if (block.type === 'redacted_thinking') {
+        return typeof block.data === 'string' && block.data.length > 0;
+    }
+    return false;
+}
+export function getThinkingPrefixMismatchBehavior(storage) {
+    const behavior = storage?.thinkingBinding?.prefixMismatchBehavior;
+    return behavior === 'error' || behavior === 'drop_block'
+        ? behavior
+        : 'account-default';
+}
+export function hasReplayableThinkingBlocks(body) {
+    if (!Array.isArray(body.messages))
+        return false;
+    return body.messages.some((message) => {
+        if (!isRecord(message) || message.role !== 'assistant')
+            return false;
+        return (Array.isArray(message.content) &&
+            message.content.some(isReplayableThinkingBlock));
+    });
+}
+export function applyThinkingBindingControls(body, behavior = 'account-default') {
+    if (behavior === 'account-default')
+        return false;
+    if (!isClaudeFable51Model(body.model))
+        return false;
+    if (!hasReplayableThinkingBlocks(body))
+        return false;
+    if (!isRecord(body.thinking) || body.thinking.type === 'disabled')
+        return false;
+    body.thinking.block_binding = {
+        prefix_mismatch_behavior: behavior,
+    };
+    return true;
+}
+export function hasThinkingBindingControls(body) {
+    if (!isRecord(body.thinking))
+        return false;
+    if (!isRecord(body.thinking.block_binding))
+        return false;
+    const behavior = body.thinking.block_binding.prefix_mismatch_behavior;
+    return behavior === 'error' || behavior === 'drop_block';
+}