@cortexkit/anthropic-auth-core 1.19.0 → 1.20.0

package/dist/quota-manager.d.ts

@@ -12,6 +12,11 @@ export type QuotaEntry = {
     refreshAfter: number;
     checkedAt: number;
 };
+export type QuotaRefreshResult = {
+    quota: OAuthQuotaSnapshot;
+    /** False when backoff or a cross-process lock served the existing cache. */
+    fetched: boolean;
+};
 export type QuotaManagerOptions = {
     storage: AccountStorage | null;
     fetchImpl?: typeof fetch;
@@ -58,7 +63,9 @@ export declare class QuotaManager {
     pushMainFromHeaders(accessToken: string, incoming: OAuthQuotaSnapshot): QuotaEntry;
     pushFallbackFromHeaders(accountId: string, accessToken: string, incoming: OAuthQuotaSnapshot): QuotaEntry;
     refreshMain(accessToken: string): Promise<OAuthQuotaSnapshot>;
+    refreshMainWithMetadata(accessToken: string): Promise<QuotaRefreshResult>;
     refreshFallback(accountId: string, accessToken: string): Promise<OAuthQuotaSnapshot>;
+    refreshFallbackWithMetadata(accountId: string, accessToken: string): Promise<QuotaRefreshResult>;
     refreshAllFallbacks(accounts: OAuthAccount[]): Promise<void>;
     /**
      * Fire-and-forget refresh. Does not await, swallows errors.

package/dist/quota-manager.js

@@ -5,10 +5,10 @@
  * share one QuotaManager instance so they see the same in-memory cache.
  * Handles deduplication, rate-limiting (429 backoff), and staleness.
  */
-import { acquireRefreshFileLock, buildQuotaOperationError, fetchOAuthQuotaSnapshot, getPersistedMainQuota, getQuotaCheckIntervalMs, getQuotaNextRefreshAt, getQuotaRefreshEveryNRequests, getScopedQuotaWindowForModel, isQuotaPolicyAuthError, quotaBackoffActive, } from "./accounts.js";
-import { mergeHeaderQuotaSnapshot } from "./quota-headers.js";
-export { tokenFingerprint } from "./token-fingerprint.js";
-import { tokenFingerprint } from "./token-fingerprint.js";
+import { acquireRefreshFileLock, buildQuotaOperationError, fetchOAuthQuotaSnapshot, getPersistedMainQuota, getQuotaCheckIntervalMs, getQuotaNextRefreshAt, getQuotaRefreshEveryNRequests, getScopedQuotaWindowForModel, isQuotaPolicyAuthError, quotaBackoffActive, quotaSnapshotCheckedAt, } from './accounts.js';
+import { mergeHeaderQuotaSnapshot } from './quota-headers.js';
+export { tokenFingerprint } from './token-fingerprint.js';
+import { tokenFingerprint } from './token-fingerprint.js';
 // Capture real setTimeout before tests can mock globalThis.setTimeout
 const nativeSetTimeout = globalThis.setTimeout;
 function mergePollCompletionWithNewerHeaders(current, polled) {
@@ -158,6 +158,9 @@ export class QuotaManager {
     // Refresh (async, deduplicated, rate-limited)
     // =========================================================================
     async refreshMain(accessToken) {
+        return (await this.refreshMainWithMetadata(accessToken)).quota;
+    }
+    async refreshMainWithMetadata(accessToken) {
         // If the main account/token changed, invalidate the cache (including a
         // persisted seed) BEFORE the backoff short-circuit so a different account's
         // stale quota is never returned while the quota API is backed off.
@@ -172,7 +175,7 @@ export class QuotaManager {
         // Rate-limit — if API recently 429'd, return stale or throw
         if (this.isBackedOff()) {
             if (this.main)
-                return this.main.quota;
+                return { quota: this.main.quota, fetched: false };
             throw new Error('Quota API rate-limited — try again later');
         }
         this.inflightMainFp = fp;
@@ -180,6 +183,10 @@ export class QuotaManager {
         return this.inflightMain;
     }
     async refreshFallback(accountId, accessToken) {
+        return (await this.refreshFallbackWithMetadata(accountId, accessToken))
+            .quota;
+    }
+    async refreshFallbackWithMetadata(accountId, accessToken) {
         // Deduplicate per account+token so a same-label re-login never joins a
         // quota probe that was started with the previous credentials.
         const inflightKey = QuotaManager.fallbackInflightKey(accountId, accessToken);
@@ -190,7 +197,7 @@ export class QuotaManager {
         if (this.isFallbackBackedOff(accountId, accessToken)) {
             const cached = this.getFallback(accountId, accessToken);
             if (cached)
-                return cached.quota;
+                return { quota: cached.quota, fetched: false };
             throw new Error('Quota API rate-limited — try again later');
         }
         const promise = this._fetchFallback(accountId, accessToken);
@@ -319,7 +326,7 @@ export class QuotaManager {
                 continue;
             if (!account.quota)
                 continue;
-            const checkedAt = Math.max(account.quota.five_hour?.checkedAt ?? 0, account.quota.seven_day?.checkedAt ?? 0);
+            const checkedAt = quotaSnapshotCheckedAt(account.quota);
             if (checkedAt <= 0)
                 continue;
             const existing = this.getFallback(account.id, account.access);
@@ -397,7 +404,7 @@ export class QuotaManager {
                 // a preceding queued call while we waited
                 if (this.isBackedOff()) {
                     if (this.main)
-                        return this.main.quota;
+                        return { quota: this.main.quota, fetched: false };
                     throw new Error('Quota API rate-limited — try again later');
                 }
                 const fileLock = await acquireRefreshFileLock({
@@ -406,8 +413,9 @@ export class QuotaManager {
                 });
                 if (!fileLock) {
                     const cached = this.main;
-                    if (cached && this.now() < cached.refreshAfter)
-                        return cached.quota;
+                    if (cached && this.now() < cached.refreshAfter) {
+                        return { quota: cached.quota, fetched: false };
+                    }
                     throw new Error('Quota refresh is already in progress');
                 }
                 try {
@@ -427,7 +435,7 @@ export class QuotaManager {
                     };
                     this.mainLastApiError = undefined;
                     this.onMainQuotaFetched?.(completedQuota, now, this.mainTokenFp, fetchStartedAt);
-                    return completedQuota;
+                    return { quota: completedQuota, fetched: true };
                 }
                 catch (error) {
                     this._handleMainFetchError(error);
@@ -452,7 +460,7 @@ export class QuotaManager {
                 if (this.isFallbackBackedOff(accountId, accessToken)) {
                     const cached = this.getFallback(accountId, accessToken);
                     if (cached)
-                        return cached.quota;
+                        return { quota: cached.quota, fetched: false };
                     throw new Error('Quota API rate-limited — try again later');
                 }
                 const fileLock = await acquireRefreshFileLock({
@@ -461,8 +469,9 @@ export class QuotaManager {
                 });
                 if (!fileLock) {
                     const cached = this.getFallback(accountId, accessToken);
-                    if (cached && this.now() < cached.refreshAfter)
-                        return cached.quota;
+                    if (cached && this.now() < cached.refreshAfter) {
+                        return { quota: cached.quota, fetched: false };
+                    }
                     throw new Error('Quota refresh is already in progress');
                 }
                 try {
@@ -480,7 +489,7 @@ export class QuotaManager {
                     }, accessToken);
                     this.fallbackApiErrors.delete(accountId);
                     this.fallbackErrorTokenFps.delete(accountId);
-                    return completedQuota;
+                    return { quota: completedQuota, fetched: true };
                 }
                 finally {
                     await fileLock.release();

package/dist/quotas.d.ts

@@ -11,13 +11,13 @@ export type QuotaAccountSummary = {
 };
 export declare function formatQuotaMoney(money: QuotaMoney): string;
 export declare function buildFallbackQuotaSummaries(storage: AccountStorage | null, errors?: ReadonlyMap<string, string>): {
-    error?: string | undefined;
-    lastRefreshedAt: number | undefined;
-    tierLabel?: string | undefined;
     name: string;
-    role: "fallback";
+    role: 'fallback';
     enabled: boolean;
     quota: OAuthQuotaSnapshot | undefined;
+    tierLabel?: string | undefined;
+    lastRefreshedAt: number | undefined;
+    error?: string | undefined;
 }[];
 export declare function buildClaudeQuotaSummary(input: {
     accounts: QuotaAccountSummary[];

package/dist/quotas.js

@@ -1,5 +1,5 @@
-import { isOAuthAccount } from "./accounts.js";
-import { formatOAuthAccountTier } from "./oauth-profile.js";
+import { isOAuthAccount } from './accounts.js';
+import { formatOAuthAccountTier } from './oauth-profile.js';
 export const CLAUDE_QUOTAS_COMMAND_NAME = 'claude-quota';
 const WINDOW_LABELS = {
     five_hour: '5h',

package/dist/relay.d.ts

@@ -31,5 +31,9 @@ export declare function sendViaRelay(options: {
      * within an attempt are ignored.
      */
     onResponseHeaders?: (headers: Headers) => void;
+    dumpTag?: import('./dump.ts').DumpTag;
+    onDumpCreated?: (handle: import('./dump.ts').DumpHandle) => void;
+    setTimeoutImpl?: typeof globalThis.setTimeout;
+    clearTimeoutImpl?: typeof globalThis.clearTimeout;
 }): Promise<Response>;
 export declare const WORKER_SCRIPT = "\nasync function hashBody(body) {\n  const bytes = new TextEncoder().encode(body)\n  const digest = await crypto.subtle.digest('SHA-256', bytes)\n  const hex = [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, '0')).join('')\n  return 'sha256:' + hex\n}\n\nfunction applyPatch(base, patch) {\n  return base.slice(0, patch.start) + patch.insert + base.slice(patch.start + patch.deleteCount)\n}\n\nfunction applyPatchSet(base, patch) {\n  if (!Array.isArray(patch)) return applyPatch(base, patch)\n  if (patch.length === 0) return base\n\n  let result = ''\n  let cursor = 0\n  for (const item of patch) {\n    if (item.start < cursor) return { error: 'overlapping patch', status: 400 }\n    result += base.slice(cursor, item.start)\n    result += item.insert\n    cursor = item.start + item.deleteCount\n  }\n  return result + base.slice(cursor)\n}\n\nasync function readState(env, affinity) {\n  const raw = await env.RELAY_STATE.get('session:' + affinity)\n  return raw ? JSON.parse(raw) : null\n}\n\nasync function writeState(env, affinity, state) {\n  await env.RELAY_STATE.put('session:' + affinity, JSON.stringify(state), { expirationTtl: 86400 })\n}\n\nasync function resolveBody(env, payload) {\n  if (payload.mode === 'full_sync') return payload.body\n  if (payload.mode === 'patch') {\n    const state = await readState(env, payload.affinity)\n    if (!state || state.hash !== payload.base_hash) {\n      return { error: 'state mismatch', status: 409 }\n    }\n    return applyPatchSet(state.body, payload.patch)\n  }\n  return { error: 'unknown mode', status: 400 }\n}\n\nasync function prepareUpstream(env, payload) {\n  if ((payload.protocol !== 1 && payload.protocol !== 2) || payload.type !== 'request' || !payload.affinity || !payload.upstream?.url || !payload.next_hash) {\n    return { error: 'invalid payload', status: 400 }\n  }\n\n  const body = await resolveBody(env, payload)\n  if (body && typeof body === 'object' && 'error' in body) return body\n\n  if (typeof body !== 'string' || (await hashBody(body)) !== payload.next_hash) {\n    return { error: 'hash mismatch', status: 409 }\n  }\n\n  const stateWrite = writeState(env, payload.affinity, { body, hash: payload.next_hash, revision: payload.revision }).catch(() => {})\n  console.log(JSON.stringify({\n    relay: 'opencode-anthropic-auth',\n    transport: 'relay',\n    mode: payload.mode,\n    revision: payload.revision,\n    affinity: String(payload.affinity).slice(0, 12),\n    bodyBytes: body.length,\n  }))\n\n  return { body, stateWrite }\n}\n\nfunction resolveBodyFromState(state, payload) {\n  if (payload.mode === 'full_sync') return payload.body\n  if (payload.mode === 'patch') {\n    if (!state || state.hash !== payload.base_hash) {\n      return { error: 'state mismatch', status: 409 }\n    }\n    return applyPatchSet(state.body, payload.patch)\n  }\n  return { error: 'unknown mode', status: 400 }\n}\n\nfunction deferWorkerTask(task) {\n  return new Promise((resolve) => setTimeout(resolve, 0)).then(task)\n}\n\nconst WEBSOCKET_STREAM_FLUSH_BYTES = 1024\nconst WEBSOCKET_STREAM_FLUSH_MS = 20\n\nfunction createWebSocketStreamCoalescer(socket, options = {}) {\n  const flushBytes = options.flushBytes || WEBSOCKET_STREAM_FLUSH_BYTES\n  const flushMs = options.flushMs ?? WEBSOCKET_STREAM_FLUSH_MS\n  let chunks = []\n  let byteLength = 0\n  let flushTimer = null\n  const stats = {\n    upstreamChunks: 0,\n    upstreamBytes: 0,\n    frames: 0,\n    frameBytes: 0,\n  }\n\n  const clearFlushTimer = () => {\n    if (flushTimer === null) return\n    clearTimeout(flushTimer)\n    flushTimer = null\n  }\n\n  const mergeChunks = () => {\n    if (chunks.length === 1) return chunks[0]\n    const frame = new Uint8Array(byteLength)\n    let offset = 0\n    for (const chunk of chunks) {\n      frame.set(chunk, offset)\n      offset += chunk.byteLength\n    }\n    return frame\n  }\n\n  const flush = () => {\n    clearFlushTimer()\n    if (byteLength === 0) return\n    const frame = mergeChunks()\n    chunks = []\n    byteLength = 0\n    socket.send(frame)\n    stats.frames += 1\n    stats.frameBytes += frame.byteLength\n  }\n\n  const scheduleFlush = () => {\n    if (flushTimer !== null) return\n    flushTimer = setTimeout(flush, flushMs)\n  }\n\n  return {\n    push(value) {\n      const chunk = value instanceof Uint8Array ? value : new Uint8Array(value)\n      if (chunk.byteLength === 0) return\n      stats.upstreamChunks += 1\n      stats.upstreamBytes += chunk.byteLength\n      chunks.push(chunk)\n      byteLength += chunk.byteLength\n      if (byteLength >= flushBytes) flush()\n      else scheduleFlush()\n    },\n    flush,\n    stats() {\n      return { ...stats, pendingBytes: byteLength }\n    },\n  }\n}\n\nfunction checkpointWebSocketState(env, payload, body, nextState) {\n  return deferWorkerTask(async () => {\n    try {\n      if ((await hashBody(body)) !== payload.next_hash) {\n        throw new Error('hash mismatch')\n      }\n      await writeState(env, payload.affinity, nextState)\n    } catch (error) {\n      console.log(JSON.stringify({\n        relay: 'opencode-anthropic-auth',\n        transport: 'websocket',\n        event: 'checkpoint_write_failed',\n        affinity: String(payload.affinity).slice(0, 12),\n        message: error instanceof Error ? error.message : String(error),\n      }))\n    }\n  })\n}\n\nasync function prepareWebSocketUpstream(env, state, payload) {\n  if (payload.protocol !== 2 || payload.type !== 'request' || !payload.id || !payload.affinity || !payload.upstream?.url || !payload.next_hash) {\n    return { error: 'invalid payload', status: 400 }\n  }\n\n  const body = resolveBodyFromState(state, payload)\n  if (body && typeof body === 'object' && 'error' in body) return body\n  if (typeof body !== 'string') return { error: 'invalid body', status: 400 }\n  if ((await hashBody(body)) !== payload.next_hash) {\n    return { error: 'hash mismatch', status: 409 }\n  }\n\n  const nextState = { body, hash: payload.next_hash, revision: payload.revision }\n  const checkpoint = checkpointWebSocketState(env, payload, body, nextState)\n  const logAccepted = () => console.log(JSON.stringify({\n    relay: 'opencode-anthropic-auth',\n    transport: 'websocket',\n    mode: payload.mode,\n    revision: payload.revision,\n    affinity: String(payload.affinity).slice(0, 12),\n    bodyBytes: body.length,\n  }))\n\n  return { body, state: nextState, checkpoint, logAccepted }\n}\n\nfunction headersToObject(headers) {\n  const result = {}\n  for (const [key, value] of headers.entries()) result[key] = value\n  return result\n}\n\nasync function handleRelayPayload(env, payload) {\n  const prepared = await prepareUpstream(env, payload)\n  if (prepared.error) return prepared\n  const upstream = await fetch(payload.upstream.url, {\n    method: payload.upstream.method || 'POST',\n    headers: payload.upstream.headers,\n    body: prepared.body,\n  })\n  return { upstream, stateWrite: prepared.stateWrite }\n}\n\nasync function handleWebSocket(socket, env, ctx, payload, getState, setState) {\n  const heartbeat = setInterval(() => {\n    try {\n      socket.send(JSON.stringify({ protocol: 2, type: 'keepalive' }))\n    } catch {\n      clearInterval(heartbeat)\n    }\n  }, 15000)\n  let streamCoalescer = null\n  try {\n    const result = await prepareWebSocketUpstream(env, getState(), payload)\n    if (result.error) {\n      socket.send(JSON.stringify({ protocol: 2, type: 'error', id: payload.id, status: result.status, message: result.error }))\n      return\n    }\n\n    setState(result.state)\n    socket.send(JSON.stringify({ protocol: 2, type: 'accepted', id: payload.id, hash: result.state.hash, revision: result.state.revision }))\n    ctx?.waitUntil?.(deferWorkerTask(result.logAccepted))\n\n    const upstreamPromise = fetch(payload.upstream.url, {\n      method: payload.upstream.method || 'POST',\n      headers: payload.upstream.headers,\n      body: result.body,\n    })\n    ctx?.waitUntil?.(result.checkpoint)\n    const upstream = await upstreamPromise\n    socket.send(JSON.stringify({\n      protocol: 2,\n      type: 'response_start',\n      id: payload.id,\n      status: upstream.status,\n      statusText: upstream.statusText,\n      headers: headersToObject(upstream.headers),\n    }))\n\n    const reader = upstream.body?.getReader()\n    if (reader) {\n      streamCoalescer = createWebSocketStreamCoalescer(socket)\n      while (true) {\n        const { done, value } = await reader.read()\n        if (done) break\n        streamCoalescer.push(value)\n      }\n      streamCoalescer.flush()\n    }\n    const stats = streamCoalescer?.stats?.() || {}\n    socket.send(JSON.stringify({ protocol: 2, type: 'done', id: payload.id, ...stats }))\n  } catch (error) {\n    try {\n      streamCoalescer?.flush?.()\n    } catch {}\n    socket.send(JSON.stringify({ protocol: 2, type: 'error', id: payload.id, status: 500, message: error instanceof Error ? error.message : String(error) }))\n  } finally {\n    clearInterval(heartbeat)\n  }\n}\n\nexport default {\n  async fetch(request, env, ctx) {\n    if (request.headers.get('Upgrade') === 'websocket') {\n      const url = new URL(request.url)\n      const token = url.searchParams.get('token')\n      const affinity = url.searchParams.get('affinity')\n      if (token !== env.RELAY_TOKEN) return new Response('unauthorized', { status: 401 })\n      if (!affinity) return new Response('missing affinity', { status: 400 })\n      const pair = new WebSocketPair()\n      const client = pair[0]\n      const server = pair[1]\n      server.binaryType = 'arraybuffer'\n      let state = null\n      let ready = false\n      server.accept()\n      const loadState = readState(env, affinity).then((loadedState) => {\n        state = loadedState\n        ready = true\n        server.send(JSON.stringify({\n          protocol: 2,\n          type: 'ready',\n          state: state ? { hash: state.hash, revision: state.revision } : null,\n        }))\n      }).catch((error) => {\n        server.send(JSON.stringify({ protocol: 2, type: 'error', status: 500, message: error instanceof Error ? error.message : String(error) }))\n        server.close(1011, 'state load failed')\n      })\n      ctx?.waitUntil?.(loadState)\n      if (!ctx?.waitUntil) void loadState\n      let busy = false\n      server.addEventListener('message', (event) => {\n        if (!ready) {\n          server.send(JSON.stringify({ protocol: 2, type: 'error', status: 425, message: 'relay state is not ready' }))\n          return\n        }\n        if (busy) {\n          server.send(JSON.stringify({ protocol: 2, type: 'error', status: 429, message: 'request already in flight' }))\n          return\n        }\n        let payload\n        try {\n          payload = JSON.parse(event.data)\n        } catch {\n          server.send(JSON.stringify({ protocol: 2, type: 'error', status: 400, message: 'invalid JSON payload' }))\n          return\n        }\n        payload.affinity = affinity\n        busy = true\n        const run = handleWebSocket(server, env, ctx, payload, () => state, (nextState) => { state = nextState }).finally(() => { busy = false })\n        ctx?.waitUntil?.(run)\n        if (!ctx?.waitUntil) void run\n      })\n      return new Response(null, { status: 101, webSocket: client })\n    }\n\n    if (request.method === 'GET') {\n      return Response.json({ status: 'ok', transports: ['http', 'websocket'] })\n    }\n    if (request.method !== 'POST') return new Response('method not allowed', { status: 405 })\n    if (request.headers.get('x-relay-token') !== env.RELAY_TOKEN) {\n      return new Response('unauthorized', { status: 401 })\n    }\n\n    try {\n      const payload = await request.json()\n      const result = await handleRelayPayload(env, payload)\n      if (result.error) return Response.json({ error: result.error }, { status: result.status })\n\n      if (result.stateWrite) ctx.waitUntil(result.stateWrite)\n\n      const upstream = result.upstream\n      return new Response(upstream.body, {\n        status: upstream.status,\n        statusText: upstream.statusText,\n        headers: upstream.headers,\n      })\n    } catch (error) {\n      return Response.json(\n        { error: error instanceof Error ? error.message : 'internal relay error' },\n        { status: 502 },\n      )\n    }\n  },\n}\n";

package/dist/relay.js

@@ -1,7 +1,7 @@
 import { Buffer } from 'node:buffer';
 import { createHash, randomBytes } from 'node:crypto';
-import { dumpRelayRequest } from "./dump.js";
-import { relayLog } from "./logger.js";
+import { dumpRelayRequest } from './dump.js';
+import { relayLog } from './logger.js';
 class RelayStateMismatchError extends Error {
 }
 class RelayWebSocketConnectionResetError extends Error {
@@ -299,15 +299,17 @@ function relayControlErrorMessage(message) {
 class PersistentRelaySession {
     config;
     affinity;
+    timers;
     socket;
     connecting;
     queue = Promise.resolve();
     pending;
     serverState;
     lastUsedAt = Date.now();
-    constructor(config, affinity) {
+    constructor(config, affinity, timers) {
         this.config = config;
         this.affinity = affinity;
+        this.timers = timers;
     }
     touch(now = Date.now()) {
         this.lastUsedAt = now;
@@ -397,7 +399,7 @@ class PersistentRelaySession {
             const socket = new WebSocket(parsed.toString());
             this.socket = socket;
             this.serverState = undefined;
-            const timeout = setTimeout(() => {
+            const timeout = this.timers.setTimeout(() => {
                 socket.close();
                 reject(new Error('relay websocket ready timed out'));
             }, 15_000);
@@ -409,7 +411,7 @@ class PersistentRelaySession {
                     }
                     const message = parseRelayControlMessage(event.data);
                     if (message.type === 'ready') {
-                        clearTimeout(timeout);
+                        this.timers.clearTimeout(timeout);
                         this.serverState = message.state;
                         resolve();
                         return;
@@ -417,20 +419,20 @@ class PersistentRelaySession {
                     this.handleMessage(message);
                 }
                 catch (error) {
-                    clearTimeout(timeout);
+                    this.timers.clearTimeout(timeout);
                     reject(error);
                     this.failPending(error);
                     socket.close();
                 }
             });
             socket.addEventListener('error', () => {
-                clearTimeout(timeout);
+                this.timers.clearTimeout(timeout);
                 const error = new RelayWebSocketConnectionResetError('relay websocket error');
                 reject(error);
                 this.failPending(error);
             });
             socket.addEventListener('close', (event) => {
-                clearTimeout(timeout);
+                this.timers.clearTimeout(timeout);
                 if (this.socket === socket) {
                     this.socket = undefined;
                     this.serverState = undefined;
@@ -503,8 +505,8 @@ class PersistentRelaySession {
         return { response, done };
     }
     resetPendingTimeout(pending) {
-        clearTimeout(pending.timeout);
-        pending.timeout = setTimeout(() => {
+        this.timers.clearTimeout(pending.timeout);
+        pending.timeout = this.timers.setTimeout(() => {
             if (this.pending !== pending)
                 return;
             if (this.retryPendingBeforeResponse(pending, 'response timed out'))
@@ -522,7 +524,7 @@ class PersistentRelaySession {
             return false;
         pending.retryAttempts += 1;
         pending.retryingBeforeResponse = true;
-        clearTimeout(pending.timeout);
+        this.timers.clearTimeout(pending.timeout);
         const attempt = pending.retryAttempts;
         const originalId = pending.payload.id;
         relayLog(`websocket ${reason}; reconnecting and retrying full_sync session=${shortAffinity(this.affinity)} request=${originalId} retry=${attempt} chunks=${pending.streamChunkCount} bytes=${pending.streamByteCount}${closeEvent ? ` ${formatCloseEvent(closeEvent)}` : ''}`);
@@ -681,7 +683,7 @@ class PersistentRelaySession {
             ? ` upstreamChunks=${done.upstreamChunks ?? 'unknown'} upstreamBytes=${done.upstreamBytes ?? 'unknown'} frames=${done.frames} frameBytes=${done.frameBytes ?? 'unknown'}`
             : '';
         relayLog(`perf websocket done session=${shortAffinity(this.affinity)} request=${pending.payload.id} sentMs=${formatMs(finishedAt - pending.sentAt)} streamMs=${pending.responseStartedAt == null ? 'unknown' : formatMs(finishedAt - pending.responseStartedAt)} chunks=${pending.streamChunkCount} bytes=${pending.streamByteCount}${workerStats}`);
-        clearTimeout(pending.timeout);
+        this.timers.clearTimeout(pending.timeout);
         if (!pending.streamDone) {
             this.deliverResponseHeaders(pending);
             pending.streamDone = true;
@@ -694,7 +696,7 @@ class PersistentRelaySession {
         const pending = this.pending;
         if (!pending)
             return;
-        clearTimeout(pending.timeout);
+        this.timers.clearTimeout(pending.timeout);
         this.pending = undefined;
         if (pending.responseStarted) {
             pending.streamController?.error(error);
@@ -737,20 +739,20 @@ function cleanupRelaySessionCaches(now = Date.now()) {
             break;
     }
 }
-function getPersistentRelaySession(config, affinity) {
+function getPersistentRelaySession(config, affinity, timers) {
     cleanupRelaySessionCaches();
     const existing = websocketSessions.get(affinity);
     if (existing) {
         existing.touch();
         return existing;
     }
-    const session = new PersistentRelaySession(config, affinity);
+    const session = new PersistentRelaySession(config, affinity, timers);
     websocketSessions.set(affinity, session);
     cleanupRelaySessionCaches();
     return session;
 }
 export async function sendViaRelay(options) {
-    const { config, input, init, headers, body, fallback, affinity: explicitAffinity, optimisticResponse, onResponseHeaders, } = options;
+    const { config, input, init, headers, body, fallback, affinity: explicitAffinity, optimisticResponse, onResponseHeaders, dumpTag, onDumpCreated, setTimeoutImpl = globalThis.setTimeout, clearTimeoutImpl = globalThis.clearTimeout, } = options;
     if (!config || !isRelayableAnthropicRequest(input, body))
         return fallback();
     const affinity = explicitAffinity ||
@@ -791,7 +793,10 @@ export async function sendViaRelay(options) {
         const sendStart = perfNowMs();
         if (config.transport === 'websocket') {
             try {
-                const session = getPersistentRelaySession(config, affinity);
+                const session = getPersistentRelaySession(config, affinity, {
+                    setTimeout: setTimeoutImpl,
+                    clearTimeout: clearTimeoutImpl,
+                });
                 result = await session.send(payload, bodyText, optimisticResponse === true, onResponseHeaders);
             }
             catch (error) {
@@ -843,7 +848,7 @@ export async function sendViaRelay(options) {
         });
         relayLog(`used relay transport=${result.transport} protocol=${result.protocol} mode=${result.payload.mode} status=${result.response.status} session=${shortAffinity(affinity)} bodyBytes=${bodyText.length} relayBytes=${actualPayloadBytes}`);
         const dumpStart = perfNowMs();
-        await dumpRelayRequest({
+        const dumpHandle = await dumpRelayRequest({
             affinity,
             transport: result.transport,
             protocol: result.protocol,
@@ -853,7 +858,13 @@ export async function sendViaRelay(options) {
             previousBodyText: previous?.body,
             payload: result.payload,
             relayBytes: actualPayloadBytes,
+            tag: dumpTag,
         });
+        try {
+            if (dumpHandle)
+                onDumpCreated?.(dumpHandle);
+        }
+        catch { }
         relayPerfLog('dump', {
             session: shortAffinity(affinity),
             ms: formatMs(perfNowMs() - dumpStart),

package/dist/routing.d.ts

@@ -1,6 +1,6 @@
 import { type AccountStorage, type RoutingMode } from './accounts.ts';
 export declare const CLAUDE_ROUTING_COMMAND_NAME = "claude-routing";
-export declare const ROUTING_MODES: readonly ["main-first", "fallback-first", "sticky-balanced"];
+export declare const ROUTING_MODES: readonly ['main-first', 'fallback-first', 'sticky-balanced'];
 export declare const DEFAULT_ROUTING_MODE: RoutingMode;
 type RoutingCommandAction = {
     type: 'status';

package/dist/routing.js

@@ -1,4 +1,4 @@
-import { createEmptyStorage, getAccountStoragePath, loadAccounts, saveAccounts, } from "./accounts.js";
+import { createEmptyStorage, getAccountStoragePath, loadAccounts, saveAccounts, } from './accounts.js';
 export const CLAUDE_ROUTING_COMMAND_NAME = 'claude-routing';
 export const ROUTING_MODES = [
     'main-first',

package/dist/start.d.ts

@@ -0,0 +1,13 @@
+export declare const CLAUDE_START_COMMAND_NAME = "claude-start";
+export type LaneStartCommandAction = {
+    type: 'fire';
+} | {
+    type: 'usage';
+};
+export declare function parseLaneStartCommandAction(input: string): LaneStartCommandAction;
+export declare function executeLaneStartCommand(input: {
+    argumentsText: string;
+}): {
+    action: LaneStartCommandAction;
+    text: string;
+};

package/dist/start.js

@@ -0,0 +1,29 @@
+export const CLAUDE_START_COMMAND_NAME = 'claude-start';
+const START_STATUS_TITLE = '## Claude Lane Start Status';
+const START_QUEUED_TITLE = '## Claude Lane Start Queued';
+const START_USAGE_TITLE = '## Claude Lane Start Usage';
+const START_USAGE = 'Usage: `/claude-start`.';
+export function parseLaneStartCommandAction(input) {
+    const normalized = input.trim().split(/\s+/).filter(Boolean);
+    if (normalized.length === 0)
+        return { type: 'fire' };
+    return { type: 'usage' };
+}
+export function executeLaneStartCommand(input) {
+    const action = parseLaneStartCommandAction(input.argumentsText);
+    if (action.type === 'fire') {
+        return {
+            action,
+            text: [
+                START_QUEUED_TITLE,
+                '',
+                '- Queued an explicit lane-start request.',
+                '- This is a billed request: the one-token limit does not remove prompt-cache read or write charges.',
+            ].join('\n'),
+        };
+    }
+    return {
+        action,
+        text: [START_USAGE_TITLE, '', START_USAGE, '', START_STATUS_TITLE].join('\n'),
+    };
+}

package/dist/sticky-routing.d.ts

@@ -1,4 +1,4 @@
-import { type AccountStorage, type OAuthQuotaSnapshot } from './accounts.ts';
+import { type AccountOperationError, type AccountStorage, type OAuthQuotaSnapshot } from './accounts.ts';
 export declare const STICKY_ROUTING_MAIN_ACCOUNT_ID = "main";
 export declare const STICKY_ROUTING_SHORT_RESET_GRACE_MS: number;
 export declare const STICKY_ROUTING_ASSIGNMENT_TTL_MS: number;
@@ -33,6 +33,18 @@ export type StickyQuotaFailureDecision = {
     action: 'migrate';
     reason: 'five-hour' | 'seven-day' | 'model-scoped';
 };
+/**
+ * Build the terminal response for a complete sticky quota pool that has no
+ * eligible route. This prevents callers from silently falling through to the
+ * main account after the router deliberately excluded it.
+ */
+export declare function createStickyNoRouteResponse(input: {
+    mainRefreshError?: AccountOperationError;
+    fallbackReauthLabels?: readonly string[];
+    routeQuotas: readonly OAuthQuotaSnapshot[];
+    modelId?: string;
+    now?: number;
+}): Response;
 export declare function stickyQuotaSnapshotIsFresh(quota: OAuthQuotaSnapshot | undefined, storage: AccountStorage | null, now?: number, modelId?: string): boolean;
 export declare function stickyRouteFamilyForModel(model: unknown): StickyRouteFamily;
 export declare function stickyRouteCandidateWeight(input: {

package/dist/sticky-routing.js

@@ -1,8 +1,8 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
 import { basename, dirname, join } from 'node:path';
-import { acquireRefreshFileLock, getKillswitchThresholdsForAccount, getQuotaCheckIntervalMs, getQuotaMinimumRemainingThresholds, getScopedQuotaWindowForModel, isKillswitchEnabled, } from "./accounts.js";
-import { isClaudeFableOrMythos5Model } from "./models.js";
+import { acquireRefreshFileLock, getKillswitchThresholdsForAccount, getQuotaCheckIntervalMs, getQuotaMinimumRemainingThresholds, getScopedQuotaWindowForModel, isKillswitchEnabled, isPermanentRefreshError, killswitchRetryAfterSeconds, quotaSnapshotPassesModelScope, } from './accounts.js';
+import { isClaudeFableOrMythos5Model } from './models.js';
 export const STICKY_ROUTING_MAIN_ACCOUNT_ID = 'main';
 export const STICKY_ROUTING_SHORT_RESET_GRACE_MS = 15 * 60_000;
 export const STICKY_ROUTING_ASSIGNMENT_TTL_MS = 7 * 24 * 60 * 60_000;
@@ -12,6 +12,62 @@ const STICKY_ROUTING_LOCK_WAIT_MS = 5_000;
 const STICKY_ROUTING_LOCK_POLL_MS = 10;
 const STICKY_ROUTING_MAX_ASSIGNMENTS = 4_096;
 const MIN_WEIGHT = 0.000_001;
+/**
+ * Build the terminal response for a complete sticky quota pool that has no
+ * eligible route. This prevents callers from silently falling through to the
+ * main account after the router deliberately excluded it.
+ */
+export function createStickyNoRouteResponse(input) {
+    const modelId = input.modelId;
+    const modelName = modelId
+        ? input.routeQuotas
+            .map((quota) => getScopedQuotaWindowForModel(quota, modelId))
+            .find(Boolean)?.modelName
+        : undefined;
+    let authenticationMessage;
+    if (isPermanentRefreshError(input.mainRefreshError)) {
+        authenticationMessage = modelName
+            ? `Main Claude OAuth account requires re-login, and no fallback OAuth account is currently routable for ${modelName}.`
+            : 'Main Claude OAuth account requires re-login, and no fallback OAuth account is currently routable.';
+    }
+    else if (input.fallbackReauthLabels?.length) {
+        const scope = modelName ? ` for ${modelName}` : '';
+        authenticationMessage = `No OAuth account is currently routable${scope}. Fallback Claude OAuth accounts require re-login: ${input.fallbackReauthLabels.join(', ')}.`;
+    }
+    if (authenticationMessage) {
+        return new Response(JSON.stringify({
+            type: 'error',
+            error: {
+                type: 'authentication_error',
+                message: authenticationMessage,
+            },
+        }), {
+            status: 401,
+            headers: { 'content-type': 'application/json' },
+        });
+    }
+    const scopedBlocked = Boolean(modelId &&
+        input.routeQuotas.length > 0 &&
+        input.routeQuotas.every((quota) => !quotaSnapshotPassesModelScope(quota, modelId)));
+    const [firstQuota, ...remainingQuotas] = input.routeQuotas;
+    const retryAfter = killswitchRetryAfterSeconds(firstQuota, remainingQuotas.map((quota) => ({ quota })), input.now ?? Date.now(), scopedBlocked ? modelId : undefined);
+    const minutes = Math.floor(retryAfter / 60);
+    const seconds = retryAfter % 60;
+    const reason = scopedBlocked && modelName
+        ? `${modelName} weekly limit reached, no routable OAuth accounts.`
+        : 'No OAuth account currently satisfies sticky-balanced quota policy.';
+    const message = `${reason} Retry in ${minutes}m ${seconds}s.`;
+    return new Response(JSON.stringify({
+        type: 'error',
+        error: { type: 'rate_limit_error', message },
+    }), {
+        status: 429,
+        headers: {
+            'content-type': 'application/json',
+            'retry-after': String(retryAfter),
+        },
+    });
+}
 function isRecord(value) {
     return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cortexkit/anthropic-auth-core",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "type": "module",
   "repository": {
     "type": "git",