@modelprofile.com/authswitch 3.2.0 → 4.0.0

package/ts/interfaces.harness.ts

@@ -53,8 +53,9 @@ export interface IHarnessProcessControl {
  * A live credential that no longer holds the account the last switch activated.
  *
  * Authswitch records the hash of what it wrote, in its own store. A different hash with the same
- * account is that account's own token refresh; a different account is what a running instance
- * writing its in-memory login back looks like.
+ * account is that account's own token refresh; a different account means the login changed outside
+ * authswitch -- a new native login, or, for a harness that does not pick up swaps live, a running
+ * instance writing its in-memory login back.
  */
 export interface IHarnessCredentialDrift {
   slotId?: string;
@@ -97,6 +98,12 @@ export interface IHarnessAccountStatus {
   problems: string[];
   /** Optional structured data for shared presentation; never parse the display facts. */
   summary?: IHarnessStatusSummary;
+  /**
+   * Set when the provider refused a lookup for too many requests (HTTP 429). It says nothing about the account's
+   * usage: callers back off, never read it as an exhausted or expired login. `retryAt` is when the provider asked to
+   * be tried again (ISO 8601 UTC), or null when it did not say.
+   */
+  rateLimit?: { retryAt: string | null };
 }
 
 export interface IHarnessStatusFact {
@@ -127,11 +134,30 @@ export interface IHarnessUsageWindow {
   headline?: true;
 }
 
+/**
+ * The provider's own name for an account's plan, and where that name comes from.
+ *
+ * `live` was read from the provider in this lookup; `stored` is the last name the saved login
+ * carries, which is the only answer available while a provider cannot be reached.
+ */
+export interface IAccountType {
+  plan: string;
+  source: 'live' | 'stored';
+}
+
+/** Live billing information only. Never infer these fields from a plan or entitlement expiry. Dates are ISO 8601 UTC. */
+export interface IHarnessBilling {
+  hasActiveSubscription?: boolean;
+  autoRenew?: boolean;
+  renewsAt?: string;
+  cancelsAt?: string;
+  expiresAt?: string;
+}
+
 export interface IHarnessStatusSummary {
   /** A plan name does not imply an active billing status. */
-  subscription?: { plan: string; source: 'live' | 'stored' };
-  /** Live billing information only. Never infer these fields from a plan or entitlement expiry. */
-  billing?: { hasActiveSubscription?: boolean; autoRenew?: boolean; renewsAt?: string; cancelsAt?: string; expiresAt?: string };
+  subscription?: IAccountType;
+  billing?: IHarnessBilling;
   /** Missing windows are unknown, not unused. Times are ISO 8601 UTC. */
   usageWindows?: IHarnessUsageWindow[];
   resets?: {
@@ -146,6 +172,27 @@ export interface IHarnessOutcome {
   problems: string[];
 }
 
+/**
+ * A caller's status-reading session, such as one `authswitch watch`. Within it an adapter may reuse a lookup whose
+ * answer rarely changes (a Claude profile) instead of repeating it on every read; outside a session every lookup is live.
+ */
+export interface IHarnessStatusSession {
+  /**
+   * The value `lookupArg` resolved to under `keyArg` less than `maxAgeMsArg` ago, otherwise the lookup's fresh result,
+   * which is then remembered. A rejected lookup is never remembered. Keys belong to the adapter that uses them, which
+   * prefixes them with its own id, so a key always names values of one type.
+   */
+  reuse<T>(keyArg: string, maxAgeMsArg: number, lookupArg: () => Promise<T>): Promise<T>;
+}
+
+/** One status lookup; see `IAuthHarness.readAccountStatus` for what it may and may not change. */
+export interface IHarnessStatusOptions {
+  /** Cancels the lookup's requests; an adapter still bounds each request with its own timeout. */
+  signal?: AbortSignal;
+  /** The session the read belongs to, when the caller reads the same accounts repeatedly. */
+  session?: IHarnessStatusSession;
+}
+
 /** A single text-only inference request. Credentials remain inside the adapter. */
 export interface IHarnessPreuseOptions {
   prompt: string;
@@ -171,7 +218,32 @@ export interface IAuthHarness {
   readState(): THarnessResult<IHarnessState>;
   /** Running instances of this harness, when the adapter owns their lifecycle. */
   readonly processes?: IHarnessProcessControl;
-  readAccountStatus(accountIdArg: string): Promise<IHarnessAccountStatus>;
+  /**
+   * Whether running instances pick up a credential swap by themselves, on their next request.
+   *
+   * Such a harness is never offered a stop before a switch, and its outcomes carry no restart advice;
+   * an explicit stop request is still honoured through `processes`. Absent means running instances keep
+   * the login they loaded until they are restarted.
+   */
+  readonly liveSwap?: boolean;
+  /**
+   * Set when this harness's provider never reports renewal or cancellation dates, as a lower-case clause
+   * that completes "<label>: ...". Views then explain the missing dates once instead of per account.
+   */
+  readonly renewalUnavailableReason?: string;
+  /**
+   * Whether `authswitch watch` may switch this harness's login by itself when the active account runs out: every
+   * saved account's usage can be read, and a switch needs no session of the user's stopped. A helper process the
+   * adapter manages itself may still be restarted by its own switch -- Codex' app-server is, because its
+   * credential file cannot be rewritten underneath it. Absent means the watch never switches this harness.
+   */
+  readonly autoSwitch?: boolean;
+  /**
+   * The account's live status. It must never activate, switch or clear a login. It may renew the tokens of the
+   * saved copy it reads when the provider leaves it no other way to answer -- the Claude Code adapter does, for
+   * saved and inactive logins only, under its store's lock -- and must leave the active login's credential alone.
+   */
+  readAccountStatus(accountIdArg: string, optionsArg?: IHarnessStatusOptions): Promise<IHarnessAccountStatus>;
   readonly loginProviders?: IHarnessLoginProvider[];
   beginLogin?(options: IHarnessLoginOptions): Promise<IHarnessLoginHandle>;
   /** Optional quota-consuming capability; never changes the active login. */

package/ts/interfaces.list.ts

@@ -1,4 +1,4 @@
-import type { IHarnessAccount, IHarnessAccountStatus, IHarnessCredentialDrift, TUsageSeverity } from './interfaces.harness.js';
+import type { IAccountType, IHarnessAccount, IHarnessAccountStatus, IHarnessBilling, IHarnessCredentialDrift, TUsageSeverity } from './interfaces.harness.js';
 
 /** Credential-free, versioned output of list --json. Missing status fields stay omitted. */
 export interface IAccountList {
@@ -39,6 +39,10 @@ export interface IAccountLimitRow {
   accountId: string | null;
   slotId?: string;
   isActive: boolean;
+  /** The adapter's plan name (`max`, `pro`), sanitised but not display-formatted; null when none is known or the row names no account. */
+  accountType: IAccountType | null;
+  /** The account's live billing fields as its provider reported them (ISO UTC dates); null when none were reported or the row names no account. */
+  billing: IHarnessBilling | null;
   /** The provider's own window name, or null when no limit data is available. */
   limitType: string | null;
   scope: 'account' | 'feature' | null;
@@ -70,6 +74,8 @@ export interface IActiveAccountRow {
   account: string | null;
   accountId: string | null;
   slotId?: string;
+  /** The adapter's plan name (`max`, `pro`), sanitised but not display-formatted; null when none is known or the row names no account. */
+  accountType: IAccountType | null;
   /** When authswitch last saved this login; null when it was never stashed. */
   savedAt: string | null;
   /** Human elapsed time for the same `savedAt`, relative to `generatedAt`. */

package/ts/plugins.ts

@@ -13,6 +13,15 @@ const nativeRequire = createRequire(import.meta.url);
 /** SQLite is needed only when accessing a Codex state database, not when hosting account APIs. */
 export const loadSqlite = (): typeof import('node:sqlite') => nativeRequire('node:sqlite');
 
+// third party modules
+import type * as properLockfile from 'proper-lockfile';
+export type TProperLockfile = typeof properLockfile;
+/**
+ * Claude Code's own lock library, loaded on first use: it installs process exit hooks when it loads, which a
+ * process that never changes a Claude Code login (such as a host embedding the account service) does not need.
+ */
+export const loadProperLockfile = (): Promise<TProperLockfile> => import('proper-lockfile');
+
 // @push.rocks modules
 import * as smartconsole from '@push.rocks/smartconsole';
 export { smartconsole };

package/ts/ratelimit.ts

@@ -0,0 +1,14 @@
+/**
+ * When a provider that answered HTTP 429 asked to be tried again, read from its `Retry-After` header (RFC 9110: a
+ * number of seconds, or an HTTP date) and returned as ISO 8601 UTC. An absent or unreadable header is null: the
+ * provider did not say, and the caller picks its own backoff.
+ */
+export const retryAtFrom = (headerArg: string | null, nowArg: number): string | null => {
+  const value = headerArg?.trim() ?? '';
+  const time = /^\d{1,9}$/.test(value) ? nowArg + Number(value) * 1000 : /^[A-Za-z]{3}, .+ GMT$/.test(value) ? Date.parse(value) : Number.NaN;
+  return Number.isFinite(time) ? new Date(time).toISOString() : null;
+};
+
+/** The latest retry time several refused requests asked for; null when none of them said. */
+export const latestRetryAt = (retryAtsArg: readonly (string | null)[]): string | null =>
+  retryAtsArg.filter((value): value is string => value !== null).sort().at(-1) ?? null;

package/ts/watchpolicy.ts

@@ -0,0 +1,121 @@
+import { compactUntil, usagePercentText } from './accounts.js';
+import { plainText } from './formatting.js';
+import type { IHarnessUsageWindow } from './interfaces.harness.js';
+
+/** What a watch knows about one account of a harness when it decides. */
+export interface IWatchReading {
+  id: string;
+  label: string;
+  /** Only a saved account can be switched to. */
+  isSaved: boolean;
+  /** The provider's usage windows from a reading recent enough to act on; null while the usage is unknown. */
+  windows: readonly IHarnessUsageWindow[] | null;
+  /** Why the usage is unknown, for a decision that depends on it. */
+  unknownReason?: string;
+}
+
+export interface IWatchPolicyInput {
+  activeId: string | null;
+  readings: readonly IWatchReading[];
+  /** The used percentage at which a window counts as used up. */
+  threshold: number;
+  /** A used-up account is traded for another used-up one only when that one is usable again more than this much sooner. */
+  intervalMs: number;
+  now: number;
+}
+
+/** `ok` says whether the active account is fine; a stay that is not ok still has nothing better to switch to. */
+export type TWatchDecision =
+  | { action: 'stay'; ok: boolean; reason: string }
+  | { action: 'switch'; target: string; reason: string };
+
+/**
+ * How far below the threshold a switch target must be on every limit, so that a switch never lands on an account that
+ * is about to reach it and the watch never flips back and forth.
+ */
+const WATCH_HYSTERESIS = 10;
+
+const accountWindows = (readingArg: IWatchReading): IHarnessUsageWindow[] => (readingArg.windows ?? []).filter(window => window.scope !== 'feature');
+const featureWindows = (readingArg: IWatchReading): IHarnessUsageWindow[] => (readingArg.windows ?? []).filter(window => window.scope === 'feature');
+
+/** The fullest of the windows at or above the threshold (the longer one on a tie), which names why an account is limited. */
+const fullest = (windowsArg: readonly IHarnessUsageWindow[], thresholdArg: number): IHarnessUsageWindow | undefined =>
+  windowsArg.filter(window => window.usedPercent >= thresholdArg)
+    .sort((left, right) => right.usedPercent - left.usedPercent || right.durationSeconds - left.durationSeconds)[0];
+
+const limitText = (windowArg: IHarnessUsageWindow, thresholdArg: number): string =>
+  `${plainText(windowArg.label)} ${usagePercentText(windowArg.usedPercent)} ≥ ${thresholdArg}%`;
+
+/** When a window resets; one without a known reset never does. */
+const resetTime = (windowArg: IHarnessUsageWindow): number => {
+  const time = windowArg.resetAt === null ? Number.NaN : Date.parse(windowArg.resetAt);
+  return Number.isFinite(time) ? time : Number.POSITIVE_INFINITY;
+};
+
+/** When every one of the account's used-up windows has reset. */
+const usableAt = (readingArg: IWatchReading, thresholdArg: number): number =>
+  Math.max(...accountWindows(readingArg).filter(window => window.usedPercent >= thresholdArg).map(resetTime));
+
+/** The reset of the account's longest window: capacity that expires first is used first. */
+const longestWindowReset = (readingArg: IWatchReading): number => {
+  const windows = accountWindows(readingArg);
+  const longest = Math.max(...windows.map(window => window.durationSeconds));
+  return Math.min(...windows.filter(window => window.durationSeconds === longest).map(resetTime));
+};
+
+const peakUsage = (readingArg: IWatchReading): number => Math.max(...accountWindows(readingArg).map(window => window.usedPercent));
+
+/** Numbers that are both unbounded compare as equal, so the next key decides. */
+const ascending = (leftArg: number, rightArg: number): number => leftArg === rightArg ? 0 : leftArg < rightArg ? -1 : 1;
+const byLabel = (leftArg: IWatchReading, rightArg: IWatchReading): number =>
+  leftArg.label.localeCompare(rightArg.label) || leftArg.id.localeCompare(rightArg.id);
+const byPreference = (leftArg: IWatchReading, rightArg: IWatchReading): number =>
+  ascending(longestWindowReset(leftArg), longestWindowReset(rightArg)) || ascending(peakUsage(leftArg), peakUsage(rightArg)) || byLabel(leftArg, rightArg);
+
+/**
+ * Which account a harness should use, from one set of readings. Pure: the same input always decides the same.
+ *
+ * - The active account is used up when any of its account windows is at or above the threshold. The watch then
+ *   switches to the saved account whose account windows are all at least `WATCH_HYSTERESIS` points below it,
+ *   preferring the one whose longest window resets soonest, then the least used, then by label.
+ * - When no account qualifies and every other saved account with a known reading is used up too, it switches to the
+ *   one that is usable again first, and only when that is more than one interval sooner than the active account.
+ * - An active account limited only on a feature window (one model) switches to an account that is below the margin on
+ *   every window; without one it stays, because the active account still serves everything else.
+ * - A reading that is unknown, whatever the cause, never counts as used up and never makes an account a target.
+ */
+export const decideWatchAction = (inputArg: IWatchPolicyInput): TWatchDecision => {
+  const { threshold } = inputArg;
+  const stay = (okArg: boolean, reasonArg: string): TWatchDecision => ({ action: 'stay', ok: okArg, reason: reasonArg });
+  const active = inputArg.readings.find(reading => reading.id === inputArg.activeId);
+  if (!active) return stay(false, 'no active login');
+  if (active.windows === null) return stay(false, `usage unknown${active.unknownReason ? ` (${active.unknownReason})` : ''}`);
+  const margin = threshold - WATCH_HYSTERESIS;
+  const known = inputArg.readings.filter(reading => reading.id !== active.id && reading.isSaved && reading.windows !== null);
+  const below = (windowsArg: readonly IHarnessUsageWindow[]): boolean => windowsArg.every(window => window.usedPercent < margin);
+  const best = (candidatesArg: IWatchReading[]): IWatchReading | undefined => candidatesArg.sort(byPreference)[0];
+
+  const usedUp = fullest(accountWindows(active), threshold);
+  if (usedUp) {
+    const limit = limitText(usedUp, threshold);
+    const target = best(known.filter(reading => accountWindows(reading).length > 0 && below(accountWindows(reading))));
+    if (target) return { action: 'switch', target: target.id, reason: limit };
+    const exhausted = known.filter(reading => fullest(accountWindows(reading), threshold) !== undefined);
+    if (!exhausted.length || exhausted.length < known.length) return stay(false, `${limit}; no other saved account is known to be below ${margin}%`);
+    const soonest = exhausted.map(reading => ({ reading, at: usableAt(reading, threshold) }))
+      .sort((left, right) => ascending(left.at, right.at) || byLabel(left.reading, right.reading))[0];
+    if (soonest.at < usableAt(active, threshold) - inputArg.intervalMs) {
+      return { action: 'switch', target: soonest.reading.id, reason: `${limit}; every saved account is used up, and ${plainText(soonest.reading.label)} is usable again first (in ${compactUntil(new Date(soonest.at).toISOString(), inputArg.now)})` };
+    }
+    return stay(false, `${limit}; every saved account is used up, and none is usable again sooner`);
+  }
+
+  const featureLimit = fullest(featureWindows(active), threshold);
+  if (featureLimit) {
+    const limit = limitText(featureLimit, threshold);
+    const target = best(known.filter(reading => accountWindows(reading).length > 0 && below(reading.windows!)));
+    if (target) return { action: 'switch', target: target.id, reason: limit };
+    return stay(false, `${limit}; no other saved account is known to be below ${margin}% on every limit`);
+  }
+  return stay(true, `every limit below ${threshold}%`);
+};