@modelprofile.com/authswitch 6.2.0 → 6.4.0

package/ts/preuse.ts

@@ -1,9 +1,19 @@
-import type { IHarnessPreuseOptions } from './interfaces.harness.js';
+import { orderedUsageWindows } from './accounts.js';
+import type { IAuthHarness, IHarnessAccount, IHarnessPreuseOptions, IHarnessPreuseResult, IHarnessUsageWindow } from './interfaces.harness.js';
 
 export const defaultPreusePrompt = 'Write 2000 words about strawberries.';
 
-/** Only fixed local messages may cross the inference error boundary. */
-export class PreuseError extends Error {}
+/**
+ * Only fixed local messages may cross the inference error boundary.
+ *
+ * `requestStarted` says whether the prompt may already have reached the provider. False is a refusal that
+ * sent nothing -- an unsupported login, a missing credential, a model catalog that could not be read before
+ * the prompt -- so the account's quota is untouched. True, and any error that is not a `PreuseError` at all,
+ * means tokens may have been consumed, and such a request is never repeated automatically.
+ */
+export class PreuseError extends Error {
+  constructor(messageArg: string, public readonly requestStarted = false) { super(messageArg); }
+}
 
 export const validatePreuseOptions = (optionsArg: IHarnessPreuseOptions): void => {
   if (typeof optionsArg.prompt !== 'string' || !optionsArg.prompt.trim() || Buffer.byteLength(optionsArg.prompt, 'utf8') > 16_384) {
@@ -13,3 +23,131 @@ export const validatePreuseOptions = (optionsArg: IHarnessPreuseOptions): void =
     throw new PreuseError('The preuse model must be a valid model identifier of at most 128 characters.');
   }
 };
+
+/**
+ * What one account's turn in a run did.
+ *
+ * `skipped` is a refusal that sent nothing and consumed nothing, with the reason the adapter stated.
+ * `failed` and `interrupted` may both have consumed tokens, so neither is ever retried by the runner.
+ */
+export type TPreuseOutcome = 'completed' | 'skipped' | 'failed' | 'interrupted';
+
+/**
+ * The reset schedule read after a prompt completed.
+ *
+ * `reported` carries what the provider answered, which may be no window at all; `unavailable` is a lookup
+ * that failed, and `notRead` is a run the user interrupted before it asked. None of them says anything
+ * about the completed prompt, which is never repeated because its schedule could not be confirmed.
+ */
+export type TPreuseSchedule =
+  | { kind: 'reported'; windows: readonly IHarnessUsageWindow[] }
+  | { kind: 'unavailable' }
+  | { kind: 'notRead' };
+
+export type TPreuseAccountResult =
+  | { account: IHarnessAccount; outcome: 'completed'; result: IHarnessPreuseResult; schedule: TPreuseSchedule }
+  | { account: IHarnessAccount; outcome: Exclude<TPreuseOutcome, 'completed'>; reason: string };
+
+/** One account starting, and that account's result. A run reports nothing else, and never the generated prose. */
+export type TPreuseRunEvent =
+  | { kind: 'started'; index: number; total: number; account: IHarnessAccount }
+  | { kind: 'finished'; index: number; total: number; result: TPreuseAccountResult };
+
+export interface IPreuseRunSummary {
+  results: readonly TPreuseAccountResult[];
+  counts: Readonly<Record<TPreuseOutcome, number>>;
+  /** Accounts an abort kept the run from reaching. Nothing was sent for them. */
+  notRun: readonly IHarnessAccount[];
+}
+
+/**
+ * Every account a run may preuse, in the order the harness lists them, each at most once.
+ *
+ * A harness reports an active login and that login's saved record as one account -- Codex keys both by
+ * email, the file harness merges the active login into its saved record by account id -- so the walk is
+ * the account list itself. The seen set keeps a repeated id from being charged twice regardless.
+ */
+export const preuseTargets = (accountsArg: readonly IHarnessAccount[]): IHarnessAccount[] => {
+  const seen = new Set<string>();
+  const targets: IHarnessAccount[] = [];
+  for (const account of accountsArg) {
+    if (seen.has(account.id)) continue;
+    seen.add(account.id);
+    targets.push(account);
+  }
+  return targets;
+};
+
+/**
+ * A run's counts in one line, for a command's closing line and for the dashboard footer.
+ *
+ * Completed accounts are always named, including none of them; every other count appears only when it
+ * happened, so a clean run reads as one fact rather than as four.
+ */
+export const preuseCountsText = (summaryArg: IPreuseRunSummary): string => [
+  `${summaryArg.counts.completed} completed`,
+  ...(summaryArg.counts.skipped ? [`${summaryArg.counts.skipped} skipped`] : []),
+  ...(summaryArg.counts.failed ? [`${summaryArg.counts.failed} failed`] : []),
+  ...(summaryArg.counts.interrupted ? [`${summaryArg.counts.interrupted} interrupted`] : []),
+  ...(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. */
+const preuseReason = (errorArg: unknown): string => errorArg instanceof PreuseError
+  ? errorArg.message
+  : 'Preuse failed. 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.
+ *
+ * The read never activates or writes a login, and its failure never turns a completed prompt into a failed
+ * one: there is nothing to undo and nothing worth repeating. An interrupted run does not ask at all.
+ */
+const readPreuseSchedule = async (harnessArg: IAuthHarness, accountArg: IHarnessAccount, signalArg: AbortSignal): Promise<TPreuseSchedule> => {
+  if (signalArg.aborted) return { kind: 'notRead' };
+  try {
+    const status = await harnessArg.readAccountStatus(accountArg.id, { signal: signalArg });
+    return { kind: 'reported', windows: orderedUsageWindows(status.summary?.usageWindows) };
+  } catch { return { kind: 'unavailable' }; }
+};
+
+/**
+ * Send one preuse prompt through each account in turn, and report what each one did.
+ *
+ * Accounts run strictly one after another, each with exactly one inference request and no retry, because
+ * every request costs the account's own quota. An aborted signal stops the run before the next account
+ * starts, and an account already in flight is reported as interrupted: its tokens may be gone either way,
+ * which is why nothing is repeated. Nothing is switched, refreshed, stopped or written anywhere.
+ */
+export const preuseAccounts = async (
+  harnessArg: IAuthHarness,
+  accountsArg: readonly IHarnessAccount[],
+  optionsArg: { prompt: string; model?: string; signal: AbortSignal },
+  reportArg: (eventArg: TPreuseRunEvent) => void,
+): Promise<IPreuseRunSummary> => {
+  const preuseAccount = harnessArg.preuseAccount?.bind(harnessArg);
+  if (!preuseAccount) throw new PreuseError('This harness does not support preuse.');
+  validatePreuseOptions(optionsArg);
+  const results: TPreuseAccountResult[] = [];
+  const counts: Record<TPreuseOutcome, number> = { completed: 0, skipped: 0, failed: 0, interrupted: 0 };
+  const notRun: IHarnessAccount[] = [];
+  const total = accountsArg.length;
+  for (const [index, account] of accountsArg.entries()) {
+    if (optionsArg.signal.aborted) { notRun.push(account); continue; }
+    reportArg({ kind: 'started', index, total, account });
+    let result: TPreuseAccountResult;
+    try {
+      const completed = await preuseAccount(account.id, { prompt: optionsArg.prompt, model: optionsArg.model, signal: optionsArg.signal });
+      result = { account, outcome: 'completed', result: completed, schedule: await readPreuseSchedule(harnessArg, account, optionsArg.signal) };
+    } catch (error) {
+      // A cancelled account is interrupted whether or not its prompt went out; its reason says which.
+      const outcome = optionsArg.signal.aborted ? 'interrupted'
+        : error instanceof PreuseError && !error.requestStarted ? 'skipped' : 'failed';
+      result = { account, outcome, reason: preuseReason(error) };
+    }
+    results.push(result);
+    counts[result.outcome]++;
+    reportArg({ kind: 'finished', index, total, result });
+  }
+  return { results, counts, notRun };
+};