@centerforagenticai/pi-multi-account 0.1.1

package/src/period-boundaries.ts

@@ -0,0 +1,376 @@
+export const PERIOD_TYPES = [
+	"day",
+	"week",
+	"month",
+	"quarter",
+	"half-year",
+	"year",
+] as const;
+
+export type PeriodType = (typeof PERIOD_TYPES)[number];
+
+export interface PeriodBounds {
+	readonly startMs: number;
+	readonly endMs: number;
+}
+
+/** More than 27 years of daily rows; a corrupt timestamp cannot walk forever. */
+export const DEFAULT_PERIOD_ITERATION_CAP = 10_000;
+
+export class PeriodEnumerationLimitError extends RangeError {
+	constructor(periodType: PeriodType, maxIterations: number) {
+		super(
+			`Calendar ${periodType} enumeration exceeded ${maxIterations} iterations.`,
+		);
+		this.name = "PeriodEnumerationLimitError";
+	}
+}
+
+function assertFiniteTimestamp(value: number, name: string): void {
+	if (!Number.isFinite(value)) {
+		throw new RangeError(`${name} must be a finite timestamp.`);
+	}
+	const date = new Date(value);
+	if (Number.isNaN(date.getTime())) {
+		throw new RangeError(`${name} is outside the supported date range.`);
+	}
+}
+
+function utcMonthBounds(
+	year: number,
+	startMonth: number,
+	months: number,
+): PeriodBounds {
+	return {
+		startMs: Date.UTC(year, startMonth, 1),
+		endMs: Date.UTC(year, startMonth + months, 1),
+	};
+}
+
+/** The pre-existing UTC-only implementation, kept byte-identical so every caller that omits a timezone sees no change. */
+function getUtcPeriodBounds(instantMs: number, periodType: PeriodType): PeriodBounds {
+	const date = new Date(instantMs);
+	const year = date.getUTCFullYear();
+	const month = date.getUTCMonth();
+	const day = date.getUTCDate();
+
+	switch (periodType) {
+		case "day":
+			return {
+				startMs: Date.UTC(year, month, day),
+				endMs: Date.UTC(year, month, day + 1),
+			};
+		case "week": {
+			const mondayOffset = (date.getUTCDay() + 6) % 7;
+			return {
+				startMs: Date.UTC(year, month, day - mondayOffset),
+				endMs: Date.UTC(year, month, day - mondayOffset + 7),
+			};
+		}
+		case "month":
+			return utcMonthBounds(year, month, 1);
+		case "quarter":
+			return utcMonthBounds(year, Math.floor(month / 3) * 3, 3);
+		case "half-year":
+			return utcMonthBounds(year, Math.floor(month / 6) * 6, 6);
+		case "year":
+			return utcMonthBounds(year, 0, 12);
+		default: {
+			const exhaustive: never = periodType;
+			throw new TypeError(`Unsupported period type: ${String(exhaustive)}`);
+		}
+	}
+}
+
+interface ZonedCalendarParts {
+	readonly year: number;
+	/** Zero-based, matching `Date.UTC`'s month argument. */
+	readonly month: number;
+	readonly day: number;
+	readonly hour: number;
+	readonly minute: number;
+	readonly second: number;
+	/** ISO weekday index: 0 = Monday .. 6 = Sunday. */
+	readonly isoWeekdayIndex: number;
+}
+
+const ISO_WEEKDAY_INDEX: Readonly<Record<string, number>> = {
+	Mon: 0,
+	Tue: 1,
+	Wed: 2,
+	Thu: 3,
+	Fri: 4,
+	Sat: 5,
+	Sun: 6,
+};
+
+const ZONED_FORMATTER_CACHE = new Map<string, Intl.DateTimeFormat>();
+
+function zonedFormatter(timeZone: string): Intl.DateTimeFormat {
+	const cached = ZONED_FORMATTER_CACHE.get(timeZone);
+	if (cached !== undefined) return cached;
+	let formatter: Intl.DateTimeFormat;
+	try {
+		formatter = new Intl.DateTimeFormat("en-US", {
+			timeZone,
+			hourCycle: "h23",
+			year: "numeric",
+			month: "2-digit",
+			day: "2-digit",
+			hour: "2-digit",
+			minute: "2-digit",
+			second: "2-digit",
+			weekday: "short",
+		});
+	} catch {
+		throw new RangeError(`"${timeZone}" is not a supported IANA timezone.`);
+	}
+	ZONED_FORMATTER_CACHE.set(timeZone, formatter);
+	return formatter;
+}
+
+function zonedCalendarParts(instantMs: number, timeZone: string): ZonedCalendarParts {
+	const parts = zonedFormatter(timeZone).formatToParts(new Date(instantMs));
+	const byType: Record<string, string> = {};
+	for (const part of parts) byType[part.type] = part.value;
+	const isoWeekdayIndex = ISO_WEEKDAY_INDEX[byType.weekday ?? ""];
+	if (
+		byType.year === undefined ||
+		byType.month === undefined ||
+		byType.day === undefined ||
+		byType.hour === undefined ||
+		byType.minute === undefined ||
+		byType.second === undefined ||
+		isoWeekdayIndex === undefined
+	) {
+		throw new RangeError(
+			`Unable to resolve calendar parts for timezone "${timeZone}".`,
+		);
+	}
+	return {
+		year: Number(byType.year),
+		month: Number(byType.month) - 1,
+		day: Number(byType.day),
+		// A rare ICU quirk renders local midnight as hour "24" under h23; normalize it.
+		hour: byType.hour === "24" ? 0 : Number(byType.hour),
+		minute: Number(byType.minute),
+		second: Number(byType.second),
+		isoWeekdayIndex,
+	};
+}
+
+export interface ZonedCalendarInstant {
+	readonly year: number;
+	/** Zero-based, matching `Date.UTC`'s month argument; may overflow (e.g. -1 or 12) to roll into an adjacent year. */
+	readonly month: number;
+	readonly day: number;
+	readonly hour?: number;
+	readonly minute?: number;
+	readonly second?: number;
+	readonly millisecond?: number;
+}
+
+/**
+ * Resolves wall-clock calendar components in `timeZone` to the UTC instant
+ * (epoch ms) that displays as those components in that zone. Uses the
+ * standard fixed-point iteration: guess the instant assuming UTC, measure how
+ * far its zoned rendering drifts from the target, and correct. Two iterations
+ * converge for every ordinary offset change; the loop is capped so a
+ * pathological zone cannot spin forever.
+ */
+export function resolveZonedInstant(
+	instant: ZonedCalendarInstant,
+	timeZone: string,
+): number {
+	const ms = instant.millisecond ?? 0;
+	const target = Date.UTC(
+		instant.year,
+		instant.month,
+		instant.day,
+		instant.hour ?? 0,
+		instant.minute ?? 0,
+		instant.second ?? 0,
+		ms,
+	);
+	if (timeZone === "UTC") return target;
+	let guess = target;
+	for (let iteration = 0; iteration < 4; iteration += 1) {
+		const zoned = zonedCalendarParts(guess, timeZone);
+		const zonedAsUtc = Date.UTC(
+			zoned.year,
+			zoned.month,
+			zoned.day,
+			zoned.hour,
+			zoned.minute,
+			zoned.second,
+			ms,
+		);
+		const offsetMs = zonedAsUtc - guess;
+		const next = target - offsetMs;
+		if (next === guess) return next;
+		guess = next;
+	}
+	return guess;
+}
+
+function zonedMonthBounds(
+	year: number,
+	startMonth: number,
+	months: number,
+	timeZone: string,
+): PeriodBounds {
+	return {
+		startMs: resolveZonedInstant({ year, month: startMonth, day: 1 }, timeZone),
+		endMs: resolveZonedInstant(
+			{ year, month: startMonth + months, day: 1 },
+			timeZone,
+		),
+	};
+}
+
+function getZonedPeriodBounds(
+	instantMs: number,
+	periodType: PeriodType,
+	timeZone: string,
+): PeriodBounds {
+	const local = zonedCalendarParts(instantMs, timeZone);
+	switch (periodType) {
+		case "day":
+			return {
+				startMs: resolveZonedInstant(
+					{ year: local.year, month: local.month, day: local.day },
+					timeZone,
+				),
+				endMs: resolveZonedInstant(
+					{ year: local.year, month: local.month, day: local.day + 1 },
+					timeZone,
+				),
+			};
+		case "week":
+			return {
+				startMs: resolveZonedInstant(
+					{
+						year: local.year,
+						month: local.month,
+						day: local.day - local.isoWeekdayIndex,
+					},
+					timeZone,
+				),
+				endMs: resolveZonedInstant(
+					{
+						year: local.year,
+						month: local.month,
+						day: local.day - local.isoWeekdayIndex + 7,
+					},
+					timeZone,
+				),
+			};
+		case "month":
+			return zonedMonthBounds(local.year, local.month, 1, timeZone);
+		case "quarter":
+			return zonedMonthBounds(
+				local.year,
+				Math.floor(local.month / 3) * 3,
+				3,
+				timeZone,
+			);
+		case "half-year":
+			return zonedMonthBounds(
+				local.year,
+				Math.floor(local.month / 6) * 6,
+				6,
+				timeZone,
+			);
+		case "year":
+			return zonedMonthBounds(local.year, 0, 12, timeZone);
+		default: {
+			const exhaustive: never = periodType;
+			throw new TypeError(`Unsupported period type: ${String(exhaustive)}`);
+		}
+	}
+}
+
+/**
+ * Assign an observation instant to a start-inclusive/end-exclusive calendar
+ * period. `timeZone` is an IANA zone identifier and defaults to `"UTC"`; the
+ * UTC path is untouched from the original implementation, so every caller
+ * that omits it keeps its exact prior behavior. Account-cost allocation must
+ * still split at UTC month boundaries regardless of this timezone -- see
+ * {@link splitAtUtcMonthBoundaries}.
+ */
+export function getPeriodBounds(
+	instantMs: number,
+	periodType: PeriodType,
+	timeZone: string = "UTC",
+): PeriodBounds {
+	assertFiniteTimestamp(instantMs, "instantMs");
+	return timeZone === "UTC"
+		? getUtcPeriodBounds(instantMs, periodType)
+		: getZonedPeriodBounds(instantMs, periodType, timeZone);
+}
+
+/**
+ * Splits `[startMs, endMs)` into contiguous, non-overlapping segments so that
+ * no segment crosses a UTC calendar-month boundary. Always uses UTC months,
+ * independent of any report display timezone: account-cost allocation must
+ * never let the display timezone change its denominator.
+ */
+export function splitAtUtcMonthBoundaries(
+	startMs: number,
+	endMs: number,
+): readonly PeriodBounds[] {
+	assertFiniteTimestamp(startMs, "startMs");
+	assertFiniteTimestamp(endMs, "endMs");
+	if (endMs <= startMs) return [];
+	const segments: PeriodBounds[] = [];
+	let cursor = startMs;
+	let iterations = 0;
+	while (cursor < endMs) {
+		iterations += 1;
+		if (iterations > DEFAULT_PERIOD_ITERATION_CAP) {
+			throw new PeriodEnumerationLimitError("month", DEFAULT_PERIOD_ITERATION_CAP);
+		}
+		const month = getUtcPeriodBounds(cursor, "month");
+		const segmentEnd = Math.min(endMs, month.endMs);
+		segments.push({ startMs: cursor, endMs: segmentEnd });
+		cursor = segmentEnd;
+	}
+	return segments;
+}
+
+/**
+ * Enumerate completed periods from the period containing the first observation.
+ * The current partial period is excluded. Every stored-record-driven walk is
+ * capped so malformed or far-future timestamps become a reportable error.
+ */
+export function enumerateCompletedPeriods(
+	periodType: PeriodType,
+	firstObservedAtMs: number,
+	nowMs: number,
+	options: { readonly maxIterations?: number; readonly timeZone?: string } = {},
+): readonly PeriodBounds[] {
+	assertFiniteTimestamp(firstObservedAtMs, "firstObservedAtMs");
+	assertFiniteTimestamp(nowMs, "nowMs");
+	const maxIterations =
+		options.maxIterations ?? DEFAULT_PERIOD_ITERATION_CAP;
+	if (!Number.isSafeInteger(maxIterations) || maxIterations < 1) {
+		throw new RangeError("maxIterations must be a positive safe integer.");
+	}
+	const timeZone = options.timeZone ?? "UTC";
+	if (nowMs <= firstObservedAtMs) return [];
+
+	const completed: PeriodBounds[] = [];
+	let bounds = getPeriodBounds(firstObservedAtMs, periodType, timeZone);
+	while (bounds.endMs <= nowMs) {
+		if (completed.length >= maxIterations) {
+			throw new PeriodEnumerationLimitError(periodType, maxIterations);
+		}
+		completed.push(bounds);
+		const next = getPeriodBounds(bounds.endMs, periodType, timeZone);
+		if (next.startMs !== bounds.endMs || next.endMs <= next.startMs) {
+			throw new RangeError(`Calendar ${periodType} enumeration did not advance.`);
+		}
+		bounds = next;
+	}
+	return completed;
+}

package/src/pi-anthropic-oauth.d.ts

@@ -0,0 +1,6 @@
+declare module "pi-anthropic-oauth/src/index.ts" {
+  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+  const piAnthropicOAuth: (pi: ExtensionAPI) => void;
+  export default piAnthropicOAuth;
+}

package/src/preflight.ts

@@ -0,0 +1,253 @@
+/**
+ * Pre-flight account selection.
+ *
+ * Reactive routing only learns an account is unusable by spending a turn on it:
+ * dispatch, wait for the provider to refuse, classify, re-route, continue. Two
+ * common cases are knowable *before* dispatch — a credential that cannot be
+ * resolved at all, and one about to expire mid-turn — and this module turns
+ * both into a selection decision instead of a failure to recover from.
+ *
+ * Every path degrades to today's reactive behaviour. A probe that throws, an
+ * absent expiry, or no better alternative all yield "proceed as before"; none
+ * is allowed to block a turn. Being unable to improve the route is not an
+ * error, so a failed pre-flight is never fatal.
+ *
+ * No credential value is read here. The liveness probe returns only whether
+ * resolution succeeded, and expiry arrives as bounded metadata.
+ */
+
+import type { AllowedFamily, MultiAccountConfig } from "./config.js";
+import { isCredentialUsable } from "./credential-lifecycle.js";
+import type { DiagnosticLog } from "./diagnostics.js";
+
+/** A managed account considered for dispatch, with bounded liveness metadata. */
+export interface PreflightCandidate {
+	readonly providerId: string;
+	readonly family: AllowedFamily;
+	/** Epoch ms of credential expiry, when the credential store reports one. */
+	readonly expiresAtMs?: number | undefined;
+	/** Whether a refresh token exists, i.e. whether expiry is recoverable. */
+	readonly hasRefreshToken: boolean;
+	/** False when runtime state has this account cooling down or invalidated. */
+	readonly available: boolean;
+}
+
+export type PreflightReason =
+	/** The active account resolved and is not near expiry. */
+	| "active-account-healthy"
+	/** Credential resolution failed; the account cannot serve this turn. */
+	| "active-account-unresolvable"
+	/** The active credential expires within the pre-emption window. */
+	| "active-account-near-expiry"
+	/** The active credential is expired and cannot be refreshed. */
+	| "active-account-unusable";
+
+export interface PreflightDecision {
+	/** Provider to dispatch to. Equals the active account when nothing changed. */
+	readonly providerId: string;
+	/** Whether selection moved away from the active account. */
+	readonly switched: boolean;
+	readonly reason: PreflightReason;
+	/**
+	 * True when the active account should be marked terminally unavailable —
+	 * only for a proven resolution failure, never for a predicted expiry.
+	 */
+	readonly invalidateActive: boolean;
+}
+
+/** Resolves an account's credential, reporting success without exposing it. */
+export type LivenessProbe = (providerId: string) => boolean | Promise<boolean>;
+
+/**
+ * Orders candidates by descending credential expiry, furthest-out first.
+ *
+ * With dozens of agents choosing independently from the same pool, any shared
+ * deterministic preference concentrates them on one account. Preferring the
+ * furthest-out expiry spreads load toward accounts with the most life left and
+ * keeps agents from converging on a credential that is about to lapse. Accounts
+ * with unknown expiry sort last: absent evidence of freshness, prefer an
+ * account whose freshness is known.
+ */
+function byFurthestExpiry(
+	a: PreflightCandidate,
+	b: PreflightCandidate,
+): number {
+	// Deterministic ordering is retained intentionally; adding jitter here would
+	// make routing less predictable and is deferred with the spread-selection
+	// design issue rather than invented as part of preflight.
+	const aExpiry = a.expiresAtMs;
+	const bExpiry = b.expiresAtMs;
+	if (aExpiry === undefined && bExpiry === undefined) return 0;
+	if (aExpiry === undefined) return 1;
+	if (bExpiry === undefined) return -1;
+	return bExpiry - aExpiry;
+}
+
+/** Whether a candidate can serve a turn that starts now. */
+function isEligible(
+	candidate: PreflightCandidate,
+	nowMs: number,
+	windowMs: number,
+): boolean {
+	if (!candidate.available) return false;
+	if (
+		!isCredentialUsable(
+			{
+				expiresAtMs: candidate.expiresAtMs,
+				hasRefreshToken: candidate.hasRefreshToken,
+			},
+			nowMs,
+		)
+	) {
+		return false;
+	}
+	// A refreshable credential is never "too close to expiry": refresh renews it
+	// transparently, so only an unrefreshable one can lapse mid-turn.
+	if (candidate.hasRefreshToken) return true;
+	if (candidate.expiresAtMs === undefined) return true;
+	return candidate.expiresAtMs - nowMs > windowMs;
+}
+
+/**
+ * Chooses which account should serve the next turn.
+ *
+ * The active account is kept unless it is provably unable to serve — the
+ * conservative default, since switching costs continuity and every alternative
+ * is only knowable through the same imperfect metadata. A switch happens only
+ * when the active account fails its liveness probe, is already dead, or would
+ * expire mid-turn AND a healthy same-family alternative exists.
+ *
+ * Cross-family substitution is never made here: families differ in models and
+ * capabilities, so quietly moving a turn across them changes its meaning.
+ * Reactive routing already handles that under explicit operator configuration.
+ */
+export async function selectPreflightAccount(options: {
+	readonly activeProviderId: string;
+	readonly candidates: readonly PreflightCandidate[];
+	readonly config: MultiAccountConfig;
+	readonly nowMs: number;
+	readonly probe?: LivenessProbe | undefined;
+	readonly diagnostics?: DiagnosticLog | undefined;
+}): Promise<PreflightDecision> {
+	const { activeProviderId, config, nowMs, probe, diagnostics } = options;
+	const normalizedCandidates = options.candidates.map((candidate) => {
+		if (
+			candidate.expiresAtMs !== undefined &&
+			!Number.isFinite(candidate.expiresAtMs)
+		) {
+			diagnostics?.record(
+				"warning",
+				"preflight.metadata",
+				"Credential expiry metadata was malformed; treating freshness as unknown.",
+				{ providerId: candidate.providerId, field: "expiresAtMs" },
+			);
+			return { ...candidate, expiresAtMs: undefined };
+		}
+		return candidate;
+	});
+	const active = normalizedCandidates.find(
+		(candidate) => candidate.providerId === activeProviderId,
+	);
+	const unchanged = (reason: PreflightReason): PreflightDecision => ({
+		providerId: activeProviderId,
+		switched: false,
+		reason,
+		invalidateActive: false,
+	});
+
+	// An unknown active account is not ours to reason about; leave it alone.
+	if (active === undefined) return unchanged("active-account-healthy");
+
+	const resolved = await runProbe(probe, activeProviderId, diagnostics);
+	const usable = isCredentialUsable(
+		{
+			expiresAtMs: active.expiresAtMs,
+			hasRefreshToken: active.hasRefreshToken,
+		},
+		nowMs,
+	);
+	const nearExpiry =
+		config.preemptiveExpiryWindowMs > 0 &&
+		!isEligible(active, nowMs, config.preemptiveExpiryWindowMs);
+
+	let reason: PreflightReason = "active-account-healthy";
+	if (resolved === false) reason = "active-account-unresolvable";
+	else if (!usable) reason = "active-account-unusable";
+	else if (nearExpiry) reason = "active-account-near-expiry";
+	if (reason === "active-account-healthy") return unchanged(reason);
+
+	const alternative = normalizedCandidates
+		.filter(
+			(candidate) =>
+				candidate.providerId !== activeProviderId &&
+				candidate.family === active.family &&
+				isEligible(candidate, nowMs, config.preemptiveExpiryWindowMs),
+		)
+		.sort(byFurthestExpiry)[0];
+
+	// Only a proven resolution failure invalidates: a predicted expiry has not
+	// actually failed yet, and the credential may still refresh.
+	const invalidateActive = reason === "active-account-unresolvable";
+
+	// No alternative means proceeding with the active account and letting
+	// reactive routing handle any real failure — better than refusing the turn.
+	if (alternative === undefined) {
+		return {
+			providerId: activeProviderId,
+			switched: false,
+			reason,
+			invalidateActive,
+		};
+	}
+
+	return {
+		providerId: alternative.providerId,
+		switched: true,
+		reason,
+		invalidateActive,
+	};
+}
+
+/**
+ * Runs the liveness probe, treating a throw as "no information".
+ *
+ * A probe that fails tells us nothing about the credential, only about the
+ * probe. Reporting undefined keeps that distinct from a definite `false`, so a
+ * broken probe cannot invalidate a healthy account (REQ-EXPIRY-FAILSAFE-1).
+ */
+async function runProbe(
+	probe: LivenessProbe | undefined,
+	providerId: string,
+	diagnostics?: DiagnosticLog,
+): Promise<boolean | undefined> {
+	if (probe === undefined) {
+		diagnostics?.record(
+			"warning",
+			"preflight.probe",
+			"Credential liveness probe is unavailable; continuing reactively.",
+			{ providerId },
+		);
+		return undefined;
+	}
+	try {
+		const result = await probe(providerId);
+		if (typeof result !== "boolean") {
+			diagnostics?.record(
+				"warning",
+				"preflight.probe",
+				"Credential liveness probe returned malformed metadata; continuing reactively.",
+				{ providerId, field: "liveness" },
+			);
+			return undefined;
+		}
+		return result;
+	} catch {
+		diagnostics?.record(
+			"warning",
+			"preflight.probe",
+			"Credential liveness probe failed; continuing reactively.",
+			{ providerId },
+		);
+		return undefined;
+	}
+}