@centerforagenticai/pi-multi-account 0.1.1

package/src/vendor.ts

@@ -0,0 +1,87 @@
+/**
+ * The two derived axes over a managed provider-family token: the vendor that
+ * authors the model, and the provider type that reaches it. Both are pure
+ * functions of the existing family token plus the per-slot credential type; no
+ * new token is introduced and nothing here performs I/O.
+ *
+ * This module is the single home for the vendor mapping that `src/api-pricing.ts`
+ * previously duplicated for pricing attribution.
+ */
+
+import type { ManagedFamily } from "./config.js";
+import type { CredentialType } from "./discovery.js";
+
+/** Exhaustive managed-family ownership map and the sole source of vendor identity. */
+const VENDOR_BY_FAMILY = {
+	anthropic: "anthropic",
+	"openai-codex": "openai",
+	"google-antigravity": "google",
+	openai: "openai",
+} as const satisfies Readonly<Record<ManagedFamily, string>>;
+
+/** Who authors the model, independent of how an account reaches it. */
+export type Vendor = (typeof VENDOR_BY_FAMILY)[ManagedFamily];
+
+/**
+ * How a managed account reaches a model:
+ * - `subscription`: an OAuth subscription (Claude Pro/Max, ChatGPT/Codex).
+ * - `owning-vendor-api`: the vendor's own pay-per-token platform API key.
+ * - `openrouter`: the metered OpenRouter last resort.
+ */
+export type ProviderType = "subscription" | "owning-vendor-api" | "openrouter";
+
+/** The vendor that authors the models a managed family serves. */
+export function vendorForFamily<Family extends ManagedFamily>(
+	family: Family,
+): (typeof VENDOR_BY_FAMILY)[Family] {
+	return VENDOR_BY_FAMILY[family];
+}
+
+/**
+ * The provider type for a managed family and its discovered credential type.
+ *
+ * Anthropic's OAuth subscription and API key both reach the one `anthropic`
+ * messages provider, so the family alone cannot decide: only a proven `api_key`
+ * credential is the owning-vendor-API tier, and every other credential state
+ * (including `unknown`) defaults to the established subscription. `openai-codex`
+ * and `google-antigravity` are always subscriptions; the distinct `openai`
+ * platform family is always owning-vendor-api regardless of credential.
+ */
+export function providerTypeFor(
+	family: ManagedFamily,
+	credentialType: CredentialType,
+): Exclude<ProviderType, "openrouter"> {
+	switch (family) {
+		case "anthropic":
+			return credentialType === "api_key"
+				? "owning-vendor-api"
+				: "subscription";
+		case "openai":
+			return "owning-vendor-api";
+		case "openai-codex":
+		case "google-antigravity":
+			return "subscription";
+	}
+}
+
+/**
+ * The paid-progression order a turn descends: subscription first, then the
+ * owning-vendor-API tier, then OpenRouter. Lower rank is preferred. This orders
+ * the tiers only; Child 1 uses it for presentation, and the physical descent
+ * that consumes it lands in Child 2.
+ */
+export function tierRank(providerType: ProviderType): number {
+	switch (providerType) {
+		case "subscription":
+			return 0;
+		case "owning-vendor-api":
+			return 1;
+		case "openrouter":
+			return 2;
+	}
+}
+
+/** Whether two managed families are authored by the same vendor. */
+export function sameVendor(a: ManagedFamily, b: ManagedFamily): boolean {
+	return vendorForFamily(a) === vendorForFamily(b);
+}

package/src/warmer.ts

@@ -0,0 +1,231 @@
+import {
+	acquireMachineLease,
+	type MachineLeaseHandle,
+} from "./machine-lease.js";
+import {
+	credentialWarmingThresholdMs,
+	type AllowedFamily,
+	type MultiAccountConfig,
+} from "./config.js";
+import type { DiagnosticLog } from "./diagnostics.js";
+import type { CredentialType } from "./discovery.js";
+
+export interface WarmCandidate {
+	readonly providerId: string;
+	readonly family: AllowedFamily;
+	/**
+	 * Discovered credential type, carried so the usage fetcher can branch an
+	 * `api_key` account to its unmeasured outcome before any OAuth call. Optional
+	 * so existing construction sites and fixtures stay valid.
+	 */
+	readonly credentialType?: CredentialType;
+	readonly expiresAtMs?: number;
+}
+
+export type CredentialWarmResolver = (providerId: string) => Promise<boolean>;
+
+export interface WarmCycleResult {
+	readonly holder: boolean;
+	readonly attempted: readonly string[];
+	readonly warmed: readonly string[];
+	readonly unavailable: readonly string[];
+}
+
+export interface CredentialWarmerOptions {
+	readonly lockPath: string;
+	readonly leaseTtlMs?: number;
+	readonly now?: () => number;
+	readonly random?: () => number;
+	readonly baseIntervalMs?: number;
+	readonly jitterFraction?: number;
+	/** Test harnesses can disable recursive timers while still exercising a cycle. */
+	readonly scheduleBackground?: boolean;
+	readonly resolveCredential: CredentialWarmResolver;
+	readonly onUnavailable?: (candidate: WarmCandidate) => void;
+	readonly onWarmed?: (candidate: WarmCandidate) => void;
+	/** Runs while this cycle owns the machine lease; it must remain bounded. */
+	readonly compactUnderLease?: (lease: MachineLeaseHandle) => void;
+	readonly diagnostics?: DiagnosticLog;
+}
+
+const DEFAULT_INTERVAL_MS = 60_000;
+const DEFAULT_JITTER_FRACTION = 0.2;
+
+function boundedRandom(random: () => number): number {
+	try {
+		const value = random();
+		return Number.isFinite(value) && value >= 0 && value <= 1 ? value : 0.5;
+	} catch {
+		return 0.5;
+	}
+}
+
+/**
+ * Runs Pi's public credential resolver under the machine-global lease. The
+ * resolver returns only a boolean, so an access token cannot be retained,
+ * logged, or returned by this module.
+ */
+export class CredentialWarmer {
+	readonly #options: CredentialWarmerOptions;
+	readonly #now: () => number;
+	readonly #random: () => number;
+	readonly #baseIntervalMs: number;
+	readonly #jitterFraction: number;
+	readonly #scheduleBackground: boolean;
+	readonly #unavailable = new Set<string>();
+	#timer: ReturnType<typeof setTimeout> | undefined;
+	#stopped = false;
+
+	constructor(options: CredentialWarmerOptions) {
+		this.#options = options;
+		this.#now = options.now ?? Date.now;
+		this.#random = options.random ?? Math.random;
+		this.#baseIntervalMs = options.baseIntervalMs ?? DEFAULT_INTERVAL_MS;
+		this.#jitterFraction = options.jitterFraction ?? DEFAULT_JITTER_FRACTION;
+		this.#scheduleBackground = options.scheduleBackground ?? true;
+		if (
+			!Number.isFinite(this.#baseIntervalMs) ||
+			this.#baseIntervalMs < 1_000
+		) {
+			throw new RangeError("warmer baseIntervalMs must be at least 1000 ms.");
+		}
+		if (
+			!Number.isFinite(this.#jitterFraction) ||
+			this.#jitterFraction < 0 ||
+			this.#jitterFraction > 1
+		) {
+			throw new RangeError("warmer jitterFraction must be between 0 and 1.");
+		}
+	}
+
+	async runCycle(
+		candidates: readonly WarmCandidate[],
+		config: MultiAccountConfig,
+	): Promise<WarmCycleResult> {
+		const empty: WarmCycleResult = {
+			holder: false,
+			attempted: [],
+			warmed: [],
+			unavailable: [],
+		};
+		let lease: MachineLeaseHandle | undefined;
+		try {
+			lease = acquireMachineLease({
+				lockPath: this.#options.lockPath,
+				...(this.#options.leaseTtlMs === undefined
+					? {}
+					: { ttlMs: this.#options.leaseTtlMs }),
+				now: this.#now,
+				// A contentless warming.lock left by a crash would otherwise disable
+				// credential warming permanently and silently.
+				reclaimMalformed: true,
+			});
+		} catch (error) {
+			this.#options.diagnostics?.recordError("credential.warmer.lease", error);
+			return empty;
+		}
+		if (!lease) return empty;
+
+		try {
+			this.#options.compactUnderLease?.(lease);
+		} catch (error) {
+			this.#options.diagnostics?.recordError(
+				"credential.warmer.compact",
+				error,
+			);
+		}
+		const attempted: string[] = [];
+		const warmed: string[] = [];
+		const unavailable: string[] = [];
+		try {
+			const nowMs = this.#now();
+			const thresholdMs = credentialWarmingThresholdMs(config);
+			for (const candidate of candidates) {
+				if (
+					this.#unavailable.has(candidate.providerId) ||
+					candidate.expiresAtMs === undefined ||
+					!Number.isFinite(candidate.expiresAtMs) ||
+					candidate.expiresAtMs - nowMs > thresholdMs
+				)
+					continue;
+				if (!lease.renew()) break;
+				attempted.push(candidate.providerId);
+				let resolved = false;
+				try {
+					resolved =
+						(await this.#options.resolveCredential(candidate.providerId)) ===
+						true;
+				} catch (error) {
+					this.#options.diagnostics?.recordError(
+						"credential.warmer.resolve",
+						error,
+					);
+				}
+				if (resolved) {
+					warmed.push(candidate.providerId);
+					this.#unavailable.delete(candidate.providerId);
+					this.#options.onWarmed?.(candidate);
+				} else {
+					unavailable.push(candidate.providerId);
+					this.#unavailable.add(candidate.providerId);
+					this.#options.onUnavailable?.(candidate);
+				}
+			}
+		} catch (error) {
+			this.#options.diagnostics?.recordError("credential.warmer.cycle", error);
+		} finally {
+			lease.release();
+		}
+		return { holder: true, attempted, warmed, unavailable };
+	}
+
+	/** Forget terminal failures after rediscovery observes a new account state. */
+	resetUnavailable(providerId?: string): void {
+		if (providerId === undefined) this.#unavailable.clear();
+		else this.#unavailable.delete(providerId);
+	}
+
+	/** Starts one leased cycle at a time; only the holder touches credentials. */
+	async start(
+		getCandidates: () => readonly WarmCandidate[],
+		config: MultiAccountConfig,
+	): Promise<WarmCycleResult> {
+		this.#stopped = false;
+		const result = await this.runCycle(getCandidates(), config);
+		if (this.#scheduleBackground) this.#schedule(getCandidates, config);
+		return result;
+	}
+
+	stop(): void {
+		this.#stopped = true;
+		if (this.#timer !== undefined) clearTimeout(this.#timer);
+		this.#timer = undefined;
+	}
+
+	#schedule(
+		getCandidates: () => readonly WarmCandidate[],
+		config: MultiAccountConfig,
+	): void {
+		if (this.#stopped || this.#timer !== undefined) return;
+		const jitter = (boundedRandom(this.#random) * 2 - 1) * this.#jitterFraction;
+		const delay = Math.max(
+			1_000,
+			Math.round(this.#baseIntervalMs * (1 + jitter)),
+		);
+		this.#timer = setTimeout(async () => {
+			this.#timer = undefined;
+			try {
+				await this.runCycle(getCandidates(), config);
+			} catch (error) {
+				this.#options.diagnostics?.recordError(
+					"credential.warmer.schedule",
+					error,
+				);
+			}
+			this.#schedule(getCandidates, config);
+		}, delay);
+		this.#timer.unref?.();
+	}
+}
+
+export { credentialWarmingThresholdMs as warmerThresholdMs } from "./config.js";

package/src/watchdog.ts

@@ -0,0 +1,219 @@
+import { DiagnosticLog } from "./diagnostics.js";
+import type { RuntimeReference } from "./runtime-state.js";
+import { RuntimeState } from "./runtime-state.js";
+
+export const WATCHDOG_ADVISORY =
+  "The continuation after the routing switch made no progress. Check account limits or switch manually.";
+
+/** Suppresses identical operator notices for 15 minutes across continuation refs. */
+export const WATCHDOG_NOTIFICATION_COOLDOWN_MS = 15 * 60 * 1_000;
+
+export interface WatchdogScheduler {
+  set(delayMs: number, callback: () => void): unknown;
+  clear(handle: unknown): void;
+}
+
+export interface WatchdogRegistration {
+  readonly continuationTurnRef: RuntimeReference;
+  readonly intervalMs: number;
+  readonly cancelContinuation: () => void | Promise<void>;
+}
+
+interface ActiveWatchdog {
+  readonly continuationTurnRef: RuntimeReference;
+  readonly intervalMs: number;
+  readonly cancelContinuation: () => void | Promise<void>;
+  readonly dispatchedAtMs: number;
+  lastProgressAtMs: number;
+  toolRunning: boolean;
+  timer?: unknown;
+  fired: boolean;
+}
+
+const defaultScheduler: WatchdogScheduler = {
+  set(delayMs, callback) {
+    return setTimeout(callback, delayMs);
+  },
+  clear(handle) {
+    clearTimeout(handle as ReturnType<typeof setTimeout>);
+  },
+};
+
+export class ContinuationWatchdog {
+  readonly #state: RuntimeState;
+  readonly #diagnostics: DiagnosticLog;
+  readonly #scheduler: WatchdogScheduler;
+  readonly #now: () => number;
+  readonly #notify: (message: string) => void | Promise<void>;
+  readonly #notificationCooldownMs: number;
+  readonly #active = new Map<RuntimeReference, ActiveWatchdog>();
+  #lastNotificationAtMs: number | undefined;
+
+  constructor(options: {
+    state: RuntimeState;
+    diagnostics: DiagnosticLog;
+    notify: (message: string) => void | Promise<void>;
+    scheduler?: WatchdogScheduler;
+    now?: () => number;
+    notificationCooldownMs?: number;
+  }) {
+    const notificationCooldownMs =
+      options.notificationCooldownMs ?? WATCHDOG_NOTIFICATION_COOLDOWN_MS;
+    if (
+      !Number.isSafeInteger(notificationCooldownMs) ||
+      notificationCooldownMs < 1
+    ) {
+      throw new RangeError(
+        "watchdog notification cooldown must be a positive safe integer.",
+      );
+    }
+    this.#state = options.state;
+    this.#diagnostics = options.diagnostics;
+    this.#notify = options.notify;
+    this.#scheduler = options.scheduler ?? defaultScheduler;
+    this.#now = options.now ?? Date.now;
+    this.#notificationCooldownMs = notificationCooldownMs;
+  }
+
+  start(registration: WatchdogRegistration): void {
+    if (!Number.isSafeInteger(registration.intervalMs) || registration.intervalMs < 1) {
+      throw new RangeError("watchdog interval must be a positive safe integer.");
+    }
+    this.cancel(registration.continuationTurnRef);
+    const now = this.#now();
+    const active: ActiveWatchdog = {
+      ...registration,
+      dispatchedAtMs: now,
+      lastProgressAtMs: now,
+      toolRunning: false,
+      fired: false,
+    };
+    this.#syncState(active);
+    this.#active.set(registration.continuationTurnRef, active);
+    try {
+      this.#arm(active);
+    } catch (error) {
+      this.#active.delete(registration.continuationTurnRef);
+      try {
+        this.#state.clearWatchdog(registration.continuationTurnRef);
+      } catch (cleanupError) {
+        this.#diagnostics.recordError("watchdog.start-cleanup", cleanupError);
+      }
+      throw error;
+    }
+  }
+
+  progress(continuationTurnRef: RuntimeReference): void {
+    const active = this.#active.get(continuationTurnRef);
+    if (!active || active.fired) return;
+    active.lastProgressAtMs = this.#now();
+    this.#syncState(active);
+    if (!active.toolRunning) this.#arm(active);
+  }
+
+  setToolRunning(continuationTurnRef: RuntimeReference, running: boolean): void {
+    const active = this.#active.get(continuationTurnRef);
+    if (!active || active.fired) return;
+    active.toolRunning = running;
+    active.lastProgressAtMs = this.#now();
+    if (active.timer !== undefined) {
+      this.#scheduler.clear(active.timer);
+      active.timer = undefined;
+    }
+    this.#syncState(active);
+    // A running tool has no polling loop. Tool completion starts one fresh interval.
+    if (!running) this.#arm(active);
+  }
+
+  progressAll(): void {
+    for (const reference of this.#active.keys()) this.progress(reference);
+  }
+
+  setAllToolsRunning(running: boolean): void {
+    for (const reference of this.#active.keys()) this.setToolRunning(reference, running);
+  }
+
+  #syncState(active: ActiveWatchdog): void {
+    this.#state.setWatchdog({
+      continuationTurnRef: active.continuationTurnRef,
+      dispatchedAtMs: active.dispatchedAtMs,
+      lastProgressAtMs: active.lastProgressAtMs,
+      toolRunning: active.toolRunning,
+    });
+  }
+
+  #arm(active: ActiveWatchdog): void {
+    if (active.timer !== undefined) this.#scheduler.clear(active.timer);
+    active.timer = this.#scheduler.set(active.intervalMs, () => {
+      active.timer = undefined;
+      if (!active.fired && !active.toolRunning) void this.#timeout(active);
+    });
+  }
+
+  async #timeout(active: ActiveWatchdog): Promise<void> {
+    if (active.fired || !this.#active.has(active.continuationTurnRef)) return;
+    active.fired = true;
+    this.#active.delete(active.continuationTurnRef);
+    try {
+      this.#state.clearWatchdog(active.continuationTurnRef);
+    } catch (error) {
+      this.#diagnostics.recordError("watchdog.state", error);
+    }
+    this.#diagnostics.record("warning", "watchdog.timeout", WATCHDOG_ADVISORY);
+    try {
+      await active.cancelContinuation();
+    } catch (error) {
+      this.#diagnostics.recordError("watchdog.cancel", error);
+    }
+    const now = this.#now();
+    if (
+      this.#lastNotificationAtMs !== undefined &&
+      now - this.#lastNotificationAtMs < this.#notificationCooldownMs
+    ) {
+      return;
+    }
+    // Reserve the window before awaiting the sink so concurrent timeouts cannot
+    // race identical notices through. A failed notice attempt is still bounded.
+    this.#lastNotificationAtMs = now;
+    try {
+      await this.#notify(this.#diagnostics.sanitizeOutput(WATCHDOG_ADVISORY));
+    } catch (error) {
+      this.#diagnostics.recordError("watchdog.notify", error);
+    }
+  }
+
+  cancel(continuationTurnRef: RuntimeReference): boolean {
+    const active = this.#active.get(continuationTurnRef);
+    if (!active) return false;
+    if (active.timer !== undefined) this.#scheduler.clear(active.timer);
+    this.#active.delete(continuationTurnRef);
+    try {
+      this.#state.clearWatchdog(continuationTurnRef);
+    } catch (error) {
+      this.#diagnostics.recordError("watchdog.cancel", error);
+    }
+    return true;
+  }
+
+  cancelAll(): void {
+    for (const active of this.#active.values()) {
+      if (active.timer !== undefined) {
+        try {
+          this.#scheduler.clear(active.timer);
+        } catch (error) {
+          this.#diagnostics.recordError("watchdog.cancel-timer", error);
+        }
+      }
+      try {
+        this.#state.clearWatchdog(active.continuationTurnRef);
+      } catch (error) {
+        this.#diagnostics.recordError("watchdog.cancel-state", error);
+      }
+    }
+    this.#active.clear();
+  }
+
+  activeCount(): number {
+    return this.#active.size;
+  }
+}