@cortexkit/anthropic-auth-core 1.5.0 → 1.6.0

package/dist/accounts.d.ts

@@ -31,6 +31,14 @@ export type AccountQuotaWindow = {
     checkedAt: number;
 };
 export type RoutingMode = 'main-first' | 'fallback-first';
+export type KillswitchThresholds = Partial<Record<QuotaWindowName | '5h' | '1w', number>>;
+export type KillswitchConfig = {
+    enabled?: boolean;
+    /** Thresholds for the main OAuth account (remaining % below which the account is killed). */
+    main?: KillswitchThresholds;
+    /** Per-account overrides keyed by account ID. Accounts without an entry use the `main` thresholds. */
+    accounts?: Record<string, KillswitchThresholds>;
+};
 export type AccountStorage = {
     version: 1;
     main?: {
@@ -56,6 +64,8 @@ export type AccountStorage = {
         refreshEveryNRequests?: number;
         minimumRemaining?: Partial<Record<QuotaWindowName | '5h' | '1w', number>>;
         failClosedOnUnknownQuota?: boolean;
+        /** Opt-in OpenCode TUI toast after quota refresh. Default: false. */
+        showToasts?: boolean;
         mainQuota?: OAuthQuotaSnapshot;
         mainQuotaCheckedAt?: number;
         mainQuotaToken?: string;
@@ -83,6 +93,7 @@ export type AccountStorage = {
         fallbackToDirect?: boolean;
         transport?: 'http' | 'websocket';
     };
+    killswitch?: KillswitchConfig;
     accounts: OAuthAccount[];
 };
 export type OAuthQuotaSnapshot = Partial<Record<QuotaWindowName, AccountQuotaWindow>>;
@@ -91,6 +102,7 @@ export type AccountManagerOptions = {
     fetchImpl?: typeof fetch;
     configPath?: string;
     quotaManager?: import('./quota-manager.ts').QuotaManager;
+    onFallbackStorageChanged?: () => void;
 };
 export type AccountRefreshError = {
     accountId: string;
@@ -149,6 +161,22 @@ export declare function getPersistedMainQuota(storage: AccountStorage | null): {
  */
 export declare function getQuotaRefreshEveryNRequests(storage: AccountStorage | null): number;
 export declare function quotaSnapshotPassesPolicy(quota: OAuthQuotaSnapshot | undefined, storage: AccountStorage | null): boolean;
+export declare const DEFAULT_KILLSWITCH_THRESHOLDS: Record<QuotaWindowName, number>;
+export declare function isKillswitchEnabled(storage: AccountStorage | null): boolean;
+/**
+ * Returns true if the account's quota is above its killswitch threshold.
+ * When killswitch is disabled, always returns true.
+ */
+export declare function killswitchPassesPolicy(quota: OAuthQuotaSnapshot | undefined, storage: AccountStorage | null, accountId?: string): boolean;
+/**
+ * Find the earliest reset time across all accounts' quota windows.
+ * Returns seconds from `now` until that reset, or 300 as a fallback.
+ */
+export declare function killswitchRetryAfterSeconds(mainQuota: OAuthQuotaSnapshot | undefined, fallbackAccounts: Array<{
+    quota?: OAuthQuotaSnapshot;
+}>, now: number): number;
+export declare function getKillswitchConfig(storage: AccountStorage | null): KillswitchConfig;
+export declare function setKillswitchPersistent(config: KillswitchConfig, path?: string): Promise<AccountStorage>;
 export declare function getQuotaNextRefreshAt(quota: OAuthQuotaSnapshot | undefined, storage: AccountStorage | null, now: number): number;
 export declare function fetchOAuthQuotaSnapshot(input: {
     accessToken: string;
@@ -166,6 +194,7 @@ export declare class FallbackAccountManager {
     private refreshTimer;
     private quotaTimer;
     readonly quotaManager: import('./quota-manager.ts').QuotaManager | null;
+    private readonly onFallbackStorageChanged;
     constructor(options?: AccountManagerOptions);
     /**
      * Seed QuotaManager from persisted account.quota if no cache entry exists

package/dist/accounts.js

@@ -130,6 +130,7 @@ function normalizeStorage(value) {
         claudeFast: isRecord(value.claudeFast) ? value.claudeFast : undefined,
         cacheKeep: isRecord(value.cacheKeep) ? value.cacheKeep : undefined,
         relay: isRecord(value.relay) ? value.relay : undefined,
+        killswitch: isRecord(value.killswitch) ? value.killswitch : undefined,
         accounts: value.accounts
             .map(normalizeAccount)
             .filter((account) => account != null),
@@ -517,6 +518,95 @@ export function quotaSnapshotPassesPolicy(quota, storage) {
     }
     return true;
 }
+// ---------------------------------------------------------------------------
+// Killswitch — hard-block requests when remaining quota drops below per-account
+// thresholds, even if the API would still accept them.
+// ---------------------------------------------------------------------------
+export const DEFAULT_KILLSWITCH_THRESHOLDS = {
+    five_hour: 5,
+    seven_day: 10,
+};
+function normalizeKillswitchThresholds(thresholds) {
+    return {
+        five_hour: thresholds?.five_hour ??
+            thresholds?.['5h'] ??
+            DEFAULT_KILLSWITCH_THRESHOLDS.five_hour,
+        seven_day: thresholds?.seven_day ??
+            thresholds?.['1w'] ??
+            DEFAULT_KILLSWITCH_THRESHOLDS.seven_day,
+    };
+}
+export function isKillswitchEnabled(storage) {
+    return storage?.killswitch?.enabled === true;
+}
+function getKillswitchThresholdsForAccount(storage, accountId) {
+    if (!storage?.killswitch)
+        return DEFAULT_KILLSWITCH_THRESHOLDS;
+    if (accountId && storage.killswitch.accounts?.[accountId]) {
+        return normalizeKillswitchThresholds(storage.killswitch.accounts[accountId]);
+    }
+    return normalizeKillswitchThresholds(storage.killswitch.main);
+}
+/**
+ * Returns true if the account's quota is above its killswitch threshold.
+ * When killswitch is disabled, always returns true.
+ */
+export function killswitchPassesPolicy(quota, storage, accountId) {
+    if (!isKillswitchEnabled(storage))
+        return true;
+    const thresholds = getKillswitchThresholdsForAccount(storage, accountId);
+    let sawUnknownWindow = false;
+    for (const key of ['five_hour', 'seven_day']) {
+        const window = quota?.[key];
+        // Defer the unknown-window decision: a quota snapshot can legally carry
+        // only one window, and a present window below its threshold must still
+        // block even if the other window is missing.
+        if (!window) {
+            sawUnknownWindow = true;
+            continue;
+        }
+        if (window.remainingPercent < thresholds[key])
+            return false;
+    }
+    if (sawUnknownWindow)
+        return !failClosedOnUnknownQuota(storage);
+    return true;
+}
+/**
+ * Find the earliest reset time across all accounts' quota windows.
+ * Returns seconds from `now` until that reset, or 300 as a fallback.
+ */
+export function killswitchRetryAfterSeconds(mainQuota, fallbackAccounts, now) {
+    const resetTimes = [];
+    const allQuotas = [mainQuota, ...fallbackAccounts.map((a) => a.quota)];
+    for (const quota of allQuotas) {
+        for (const key of ['five_hour', 'seven_day']) {
+            const resetStr = quota?.[key]?.resetsAt;
+            if (!resetStr)
+                continue;
+            const resetTime = Date.parse(resetStr);
+            if (Number.isFinite(resetTime) && resetTime > now) {
+                resetTimes.push(resetTime);
+            }
+        }
+    }
+    if (!resetTimes.length)
+        return 300;
+    return Math.max(1, Math.ceil((Math.min(...resetTimes) - now) / 1000)) + 60;
+}
+export function getKillswitchConfig(storage) {
+    return storage?.killswitch ?? { enabled: false };
+}
+export async function setKillswitchPersistent(config, path = getAccountStoragePath()) {
+    const storage = (await loadAccounts(path)) ?? {
+        version: 1,
+        main: { type: 'opencode', provider: 'anthropic' },
+        accounts: [],
+    };
+    storage.killswitch = config;
+    await saveAccounts(storage, path);
+    return storage;
+}
 export function getQuotaNextRefreshAt(quota, storage, now) {
     if (!quotaEnabled(storage))
         return now + getQuotaCheckIntervalMs(storage);
@@ -664,11 +754,13 @@ export class FallbackAccountManager {
     refreshTimer = null;
     quotaTimer = null;
     quotaManager;
+    onFallbackStorageChanged;
     constructor(options = {}) {
         this.now = options.now ?? Date.now;
         this.fetchImpl = options.fetchImpl ?? fetch;
         this.configPath = options.configPath ?? getAccountStoragePath();
         this.quotaManager = options.quotaManager ?? null;
+        this.onFallbackStorageChanged = options.onFallbackStorageChanged;
     }
     /**
      * Seed QuotaManager from persisted account.quota if no cache entry exists
@@ -880,8 +972,10 @@ export class FallbackAccountManager {
                 // Quota probes are advisory; failed probes fail closed at selection time.
             }
         }
-        if (changed)
+        if (changed) {
             await this.save(storage);
+            this.onFallbackStorageChanged?.();
+        }
     }
     async refreshQuotaForAllAccounts(options = {}) {
         const storage = await this.load();

package/dist/index.d.ts

@@ -7,6 +7,7 @@ export * from './claude-code.ts';
 export * from './constants.ts';
 export * from './dump.ts';
 export * from './fast.ts';
+export * from './killswitch.ts';
 export * from './logger.ts';
 export * from './pkce.ts';
 export * from './quota-manager.ts';

package/dist/index.js

@@ -7,6 +7,7 @@ export * from "./claude-code.js";
 export * from "./constants.js";
 export * from "./dump.js";
 export * from "./fast.js";
+export * from "./killswitch.js";
 export * from "./logger.js";
 export * from "./pkce.js";
 export * from "./quota-manager.js";

package/dist/killswitch.d.ts

@@ -0,0 +1,27 @@
+import type { KillswitchConfig } from './accounts.ts';
+export declare const KILLSWITCH_COMMAND_NAME = "claude-killswitch";
+export type KillswitchCommandAction = {
+    type: 'status';
+} | {
+    type: 'on';
+} | {
+    type: 'off';
+} | {
+    type: 'set';
+    entries: Array<{
+        account: string;
+        fh: number;
+        sd: number;
+    }>;
+} | {
+    type: 'usage';
+};
+export declare function parseKillswitchCommandAction(argumentsText: string): KillswitchCommandAction;
+export declare function executeKillswitchCommand(input: {
+    argumentsText: string;
+    config: KillswitchConfig;
+    accountIds: string[];
+}): {
+    text: string;
+    updatedConfig?: KillswitchConfig;
+};

package/dist/killswitch.js

@@ -0,0 +1,127 @@
+import { DEFAULT_KILLSWITCH_THRESHOLDS as DEFAULT_THRESHOLDS } from "./accounts.js";
+export const KILLSWITCH_COMMAND_NAME = 'claude-killswitch';
+export function parseKillswitchCommandAction(argumentsText) {
+    const parts = argumentsText.trim().split(/\s+/).filter(Boolean);
+    if (parts.length === 0)
+        return { type: 'status' };
+    if (parts.length === 1 && parts[0] === 'on')
+        return { type: 'on' };
+    if (parts.length === 1 && parts[0] === 'off')
+        return { type: 'off' };
+    if (parts[0] === 'set') {
+        const entries = [];
+        for (let i = 1; i < parts.length; i++) {
+            const match = parts[i]?.match(/^([^:]+):(\d+),(\d+)$/);
+            if (!match)
+                return { type: 'usage' };
+            const [, account, fhStr, sdStr] = match;
+            entries.push({
+                account,
+                fh: Number.parseInt(fhStr, 10),
+                sd: Number.parseInt(sdStr, 10),
+            });
+        }
+        if (entries.length === 0)
+            return { type: 'usage' };
+        return { type: 'set', entries };
+    }
+    return { type: 'usage' };
+}
+function buildStatusTable(config, accountIds) {
+    const enabled = config.enabled === true;
+    const lines = [
+        '## Killswitch',
+        '',
+        `Status: **${enabled ? 'ON' : 'OFF'}**`,
+    ];
+    if (enabled) {
+        lines.push('');
+        lines.push('| Account | 5h threshold | 1w threshold |');
+        lines.push('| ------- | ------------ | ------------ |');
+        const mainT = config.main ?? {};
+        const fh = mainT.five_hour ?? mainT['5h'] ?? DEFAULT_THRESHOLDS.five_hour;
+        const sd = mainT.seven_day ?? mainT['1w'] ?? DEFAULT_THRESHOLDS.seven_day;
+        lines.push(`| main | \u2265 ${fh}% | \u2265 ${sd}% |`);
+        for (const id of accountIds) {
+            const t = config.accounts?.[id] ?? config.main ?? {};
+            const afh = t.five_hour ?? t['5h'] ?? DEFAULT_THRESHOLDS.five_hour;
+            const asd = t.seven_day ?? t['1w'] ?? DEFAULT_THRESHOLDS.seven_day;
+            lines.push(`| ${id} | \u2265 ${afh}% | \u2265 ${asd}% |`);
+        }
+    }
+    return lines.join('\n');
+}
+const USAGE_TEXT = [
+    '## Killswitch Commands',
+    '',
+    '```',
+    `/${KILLSWITCH_COMMAND_NAME}              — show status`,
+    `/${KILLSWITCH_COMMAND_NAME} on           — enable with current or default thresholds`,
+    `/${KILLSWITCH_COMMAND_NAME} off          — disable`,
+    `/${KILLSWITCH_COMMAND_NAME} set all:5,10 — set all accounts to 5h≥5%, 1w≥10%`,
+    `/${KILLSWITCH_COMMAND_NAME} set main:3,8 work-alt:5,10 — per-account`,
+    '```',
+].join('\n');
+export function executeKillswitchCommand(input) {
+    const action = parseKillswitchCommandAction(input.argumentsText);
+    if (action.type === 'status') {
+        const status = buildStatusTable(input.config, input.accountIds);
+        return { text: `${status}\n\n${USAGE_TEXT}` };
+    }
+    if (action.type === 'on') {
+        const updated = {
+            ...input.config,
+            enabled: true,
+            main: input.config.main ?? {
+                five_hour: DEFAULT_THRESHOLDS.five_hour,
+                seven_day: DEFAULT_THRESHOLDS.seven_day,
+            },
+        };
+        const status = buildStatusTable(updated, input.accountIds);
+        return {
+            text: `## Killswitch Enabled\n\n${status}`,
+            updatedConfig: updated,
+        };
+    }
+    if (action.type === 'off') {
+        const updated = { ...input.config, enabled: false };
+        return {
+            text: '## Killswitch Disabled',
+            updatedConfig: updated,
+        };
+    }
+    if (action.type === 'set') {
+        const accounts = { ...(input.config.accounts ?? {}) };
+        const updated = {
+            ...input.config,
+            enabled: true,
+            accounts,
+        };
+        for (const entry of action.entries) {
+            const thresholds = {
+                five_hour: entry.fh,
+                seven_day: entry.sd,
+            };
+            if (entry.account === 'main') {
+                updated.main = thresholds;
+            }
+            else if (entry.account === 'all') {
+                updated.main = thresholds;
+                for (const id of input.accountIds) {
+                    accounts[id] = thresholds;
+                }
+            }
+            else {
+                accounts[entry.account] = thresholds;
+            }
+        }
+        const status = buildStatusTable(updated, input.accountIds);
+        return {
+            text: `## Killswitch Updated\n\n${status}`,
+            updatedConfig: updated,
+        };
+    }
+    // usage
+    const status = buildStatusTable(input.config, input.accountIds);
+    return { text: `${status}\n\n${USAGE_TEXT}` };
+}

package/dist/relay.js

@@ -241,6 +241,16 @@ function toBinaryChunk(data) {
 function parseRelayControlMessage(data) {
     return JSON.parse(data);
 }
+function formatCloseEvent(event) {
+    const close = event;
+    const parts = [
+        `code=${close.code ?? 'unknown'}`,
+        `wasClean=${close.wasClean ?? 'unknown'}`,
+    ];
+    if (close.reason)
+        parts.push(`reason=${JSON.stringify(close.reason)}`);
+    return parts.join(' ');
+}
 function relayControlErrorMessage(message) {
     const detail = message.message || 'relay websocket error';
     return message.status
@@ -364,7 +374,7 @@ class PersistentRelaySession {
                 reject(error);
                 this.failPending(error);
             });
-            socket.addEventListener('close', () => {
+            socket.addEventListener('close', (event) => {
                 clearTimeout(timeout);
                 if (this.socket === socket) {
                     this.socket = undefined;
@@ -374,9 +384,16 @@ class PersistentRelaySession {
                 if (this.pending) {
                     if (this.pending.retryingBeforeResponse)
                         return;
-                    if (this.retryPendingBeforeResponse(this.pending, 'closed before response'))
+                    const closedAfterResponseStart = this.pending.responseStartedAt != null;
+                    const reason = closedAfterResponseStart
+                        ? 'closed after response_start before stream bytes'
+                        : 'closed before response';
+                    if (this.retryPendingBeforeResponse(this.pending, reason, event))
                         return;
-                    const error = new Error('relay websocket closed before response');
+                    const error = new Error(closedAfterResponseStart
+                        ? 'relay websocket closed during response stream'
+                        : 'relay websocket closed before response');
+                    relayLog(`websocket ${closedAfterResponseStart ? 'closed during response stream' : 'closed before response without retry'} session=${shortAffinity(this.affinity)} request=${this.pending.payload.id} chunks=${this.pending.streamChunkCount} bytes=${this.pending.streamByteCount} ${formatCloseEvent(event)}`);
                     this.failPending(error);
                 }
             });
@@ -410,6 +427,8 @@ class PersistentRelaySession {
                 rejectDone,
                 sentAt,
                 optimisticResponse,
+                streamChunkCount: 0,
+                streamByteCount: 0,
                 retryAttempts: 0,
                 retryingBeforeResponse: false,
             };
@@ -436,8 +455,8 @@ class PersistentRelaySession {
             this.socket?.close();
         }, 45_000);
     }
-    retryPendingBeforeResponse(pending, reason) {
-        if (pending.responseStartedAt != null)
+    retryPendingBeforeResponse(pending, reason, closeEvent) {
+        if (pending.responseStartedAt != null && pending.streamByteCount > 0)
             return false;
         if (pending.streamDone)
             return false;
@@ -448,7 +467,7 @@ class PersistentRelaySession {
         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}`);
+        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)}` : ''}`);
         this.socket?.close();
         this.socket = undefined;
         this.serverState = undefined;
@@ -484,11 +503,16 @@ class PersistentRelaySession {
         })();
         return true;
     }
+    enqueueStreamChunk(pending, chunk) {
+        pending.streamChunkCount += 1;
+        pending.streamByteCount += chunk.byteLength;
+        pending.streamController?.enqueue(chunk);
+    }
     handleBinaryChunk(data) {
         const pending = this.pending;
         if (!pending?.responseStarted)
             return;
-        pending.streamController?.enqueue(toBinaryChunk(data));
+        this.enqueueStreamChunk(pending, toBinaryChunk(data));
     }
     resolvePendingResponse(pending, status, statusText, headers) {
         if (pending.responseStarted)
@@ -542,7 +566,7 @@ class PersistentRelaySession {
             return;
         }
         if (message.type === 'chunk') {
-            pending.streamController?.enqueue(decodeRelayChunk(message.base64));
+            this.enqueueStreamChunk(pending, decodeRelayChunk(message.base64));
             return;
         }
         if (message.type === 'done') {
@@ -555,7 +579,7 @@ class PersistentRelaySession {
             // would reject a settled promise and leave the stream hanging. Instead,
             // inject an SSE error event and close cleanly.
             if (pending.optimisticResponse && pending.responseStartedAt != null) {
-                relayLog(`websocket relay error during optimistic response session=${shortAffinity(this.affinity)} request=${pending.payload.id} status=${message.status} message=${message.message || 'unknown'}`);
+                relayLog(`websocket relay error during optimistic response session=${shortAffinity(this.affinity)} request=${pending.payload.id} status=${message.status} message=${message.message || 'unknown'} chunks=${pending.streamChunkCount} bytes=${pending.streamByteCount}`);
                 pending.streamController?.enqueue(new TextEncoder().encode(`event: error\ndata: ${JSON.stringify({ type: 'error', error: { type: 'relay_error', message: message.message || 'relay error' } })}\n\n`));
                 this.finishPending();
                 this.socket?.close();
@@ -576,7 +600,7 @@ class PersistentRelaySession {
         if (!pending)
             return;
         const finishedAt = perfNowMs();
-        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)}`);
+        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}`);
         clearTimeout(pending.timeout);
         if (!pending.streamDone) {
             pending.streamDone = true;

package/package.json

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