@modelprofile.com/authswitch 9.2.0 → 10.0.0

package/ts/preuse.ts

@@ -1,8 +1,11 @@
-import { orderedUsageWindows } from './accounts.js';
+import { localDateTime, orderedUsageWindows, until } from './accounts.js';
 import type { IAuthHarness, IHarnessAccount, IHarnessPreuseOptions, IHarnessPreuseResult, IHarnessUsageWindow } from './interfaces.harness.js';
 
 export const defaultPreusePrompt = 'Write 2000 words about strawberries.';
 
+/** The close of every message about a prompt that may have reached the provider. */
+export const preuseMayHaveConsumed = 'Tokens may already have been consumed; no automatic retry was made. Check the account status before trying again.';
+
 /**
  * Only fixed local messages may cross the inference error boundary.
  *
@@ -15,6 +18,84 @@ export class PreuseError extends Error {
   constructor(messageArg: string, public readonly requestStarted = false) { super(messageArg); }
 }
 
+/**
+ * A limit that kept a preuse prompt from being answered.
+ *
+ * `usage_limit` is the account's quota, spent until it resets; `rate_limit` a short throttle. `window` names the
+ * window by its length (`weekly`, `five-hour`) and `resetsAt` is an ISO time; either is null when the account's
+ * usage reading or the provider's refusal did not state it.
+ */
+export interface IPreuseLimit {
+  kind: 'usage_limit' | 'rate_limit';
+  window: string | null;
+  resetsAt: string | null;
+}
+
+/**
+ * `Weekly usage limit reached, resets in 16h 46min (2026-09-27 05:12)`: human text, so the reset reads in local time.
+ * The limit itself keeps its ISO `resetsAt` for receipts and JSON output.
+ */
+export const describePreuseLimit = (limitArg: IPreuseLimit, nowArg: number): string => {
+  const name = `${limitArg.window === null ? '' : `${limitArg.window} `}${limitArg.kind === 'usage_limit' ? 'usage' : 'rate'} limit reached`;
+  const countdown = limitArg.resetsAt === null ? null : until(limitArg.resetsAt, nowArg);
+  const at = localDateTime(limitArg.resetsAt);
+  const reset = limitArg.resetsAt === null ? ''
+    : countdown === 'due' ? `, due to reset now (${at})` : `, resets in ${countdown} (${at})`;
+  return `${name.charAt(0).toUpperCase()}${name.slice(1)}${reset}`;
+};
+
+/**
+ * A preuse a limit stopped. `usage` is the account's own usage reading before anything was sent; `provider`
+ * is the provider's refusal of the prompt, which `generationStarted` says came before or after it began to
+ * answer: a refusal before its answer consumed nothing.
+ */
+export class PreuseLimitError extends PreuseError {
+  constructor(public readonly limit: IPreuseLimit, public readonly source: 'usage' | 'provider',
+    public readonly generationStarted: boolean, nowArg: number) {
+    const described = describePreuseLimit(limit, nowArg);
+    super(source === 'usage' ? `${described}. No preuse prompt was sent.`
+      : generationStarted
+        ? `The provider stopped the answer: ${described}. Tokens may already have been consumed; no automatic retry was made.`
+        : `The provider refused the prompt before answering it: ${described}. No tokens were consumed; no automatic retry was made.`,
+    source === 'provider');
+  }
+}
+
+/**
+ * Why a sent preuse prompt failed without a limit, and never with the provider's text.
+ *
+ * `http` is an answer with an HTTP error status; `stream` an error the answer stream reported after it began,
+ * with the machine-readable code the provider stated and no status, since its answer was a success; `response` an answer that could not be read;
+ * `network` a connection that failed before any answer; `aborted` an abort that was neither the caller's nor the
+ * deadline; `unknown` anything else. `status` and `providerCode` are null when the failure did not state them.
+ */
+export interface IPreuseFailure {
+  kind: 'http' | 'stream' | 'response' | 'network' | 'aborted' | 'unknown';
+  status: number | null;
+  providerCode: string | null;
+}
+
+/** `the provider answered HTTP 503`: the cause of a failed preuse, as the tail of a sentence. */
+export const describePreuseFailure = (failureArg: IPreuseFailure): string => {
+  const status = failureArg.status === null ? null : `HTTP ${failureArg.status}`;
+  switch (failureArg.kind) {
+    case 'http': return `the provider answered ${status ?? 'with an HTTP error'}`;
+    case 'stream':
+      return `the answer stream reported an error${failureArg.providerCode === null ? '' : ` (code ${failureArg.providerCode})`}`;
+    case 'response': return `the provider's answer${status ? ` (${status})` : ''} could not be read`;
+    case 'network': return 'no answer arrived: the connection failed';
+    case 'aborted': return 'the request was aborted';
+    case 'unknown': return 'the request ended in an error that names no cause';
+  }
+};
+
+/** A sent preuse prompt that failed for the stated cause; its tokens may have been consumed. */
+export class PreuseFailureError extends PreuseError {
+  constructor(public readonly failure: IPreuseFailure) {
+    super(`Preuse did not complete: ${describePreuseFailure(failure)}. ${preuseMayHaveConsumed}`, true);
+  }
+}
+
 export const validatePreuseOptions = (optionsArg: IHarnessPreuseOptions): void => {
   if (typeof optionsArg.prompt !== 'string' || !optionsArg.prompt.trim() || Buffer.byteLength(optionsArg.prompt, 'utf8') > 16_384) {
     throw new PreuseError('The preuse prompt must contain between 1 and 16384 UTF-8 bytes.');
@@ -92,10 +173,14 @@ export const preuseCountsText = (summaryArg: IPreuseRunSummary): string => [
   ...(summaryArg.notRun.length ? [`${summaryArg.notRun.length} not run`] : []),
 ].join(', ');
 
-/** An adapter's own fixed message, or the fixed local text for an error that crossed the boundary unnamed. */
+/**
+ * An adapter's own fixed message, or, for an error that crossed the boundary unnamed, the fixed local text with
+ * the error's class name -- never its message, which may carry a provider body or a token.
+ */
 const preuseReason = (errorArg: unknown): string => errorArg instanceof PreuseError
   ? errorArg.message
-  : 'Preuse failed. Tokens may already have been consumed; check account status before trying again.';
+  : `Preuse failed with an error the adapter did not name (${errorArg instanceof Error && /^[A-Za-z]{1,64}$/.test(errorArg.name) ? errorArg.name : 'unknown'}). `
+    + 'Tokens may already have been consumed; check account status before trying again.';
 
 /**
  * The account's reset schedule, read after its prompt completed, exactly as the single-account command reads it.

package/ts/ts_migration/legacysources/shared.ts

@@ -1,5 +1,6 @@
 import * as plugins from '../../plugins.js';
 import { readCredentialRaw } from '../../classes.credentialstore.js';
+import { parseOpenAiTokenClaims, type IOpenAiTokenClaims } from '../../openaiauth.js';
 import { resolveClaudeNativeHome, type TClaudeNativeHomeResolution } from '../../classes.claudenative.js';
 import type { TAuthSwitchImportProof, TAuthSwitchImportSourceKind,
   TAuthSwitchImportTreatment } from '../../authority-import-contract.js';
@@ -128,8 +129,8 @@ export interface IOpenAiSourceIdentity {
  * claims the token already carries, which is what lets the inventory run offline.
  */
 export const openAiSourceIdentity = (idToken: string): IOpenAiSourceIdentity | null => {
-  let info: ReturnType<typeof plugins.flexAuth.parseOpenAiChatGptTokenInfo>;
-  try { info = plugins.flexAuth.parseOpenAiChatGptTokenInfo(idToken); }
+  let info: IOpenAiTokenClaims;
+  try { info = parseOpenAiTokenClaims(idToken); }
   catch { return null; }
   if (!info.chatgptUserId || !info.chatgptAccountId) return null;
   return {
@@ -202,7 +203,7 @@ export const openCodeOpenAiIdentity = (entry: Record<string, unknown>):
 /** The expiry claim of an access token, as the broker reads it. Absent or unparsable means unknown. */
 export const accessTokenExpiry = (accessToken: string | null): string | null => {
   if (!accessToken) return null;
-  try { return plugins.flexAuth.parseOpenAiChatGptTokenInfo(accessToken).expiresAt ?? null; }
+  try { return parseOpenAiTokenClaims(accessToken).expiresAt ?? null; }
   catch { return null; }
 };