@centerforagenticai/pi-multi-account 0.1.1

package/src/recovery-plan.ts

@@ -0,0 +1,239 @@
+import type { AllowedFamily, ManagedFamily, MultiAccountConfig } from "./config.js";
+import { isAllowedFamily } from "./config.js";
+import { resolveTierModel } from "./tier-model-resolver.js";
+import type { ProviderType } from "./vendor.js";
+import { sameVendor, vendorForFamily } from "./vendor.js";
+import { isCanonicalManagedProviderId } from "./runtime-state.js";
+
+/** Host-observable input modalities used to reject incompatible destinations. */
+export type RecoveryInputModality = "text" | "image";
+
+/** Capability facts projected from one physical catalog row. */
+export interface RecoveryModelCapability {
+	readonly modelId: string;
+	readonly input: readonly RecoveryInputModality[];
+	readonly supportsTools: boolean;
+	readonly contextWindow: number;
+}
+
+/** One validated physical account visible when a request-local plan is built. */
+export interface RecoveryPlanAccount {
+	readonly providerId: string;
+	readonly family: ManagedFamily;
+	readonly providerType: Exclude<ProviderType, "openrouter">;
+	readonly eligible: boolean;
+	readonly models: readonly RecoveryModelCapability[];
+}
+
+export type RecoveryCandidateTier =
+	| "same-family-subscription"
+	| "owning-vendor-api"
+	| "cross-family-subscription";
+
+/** One finite provider/model pair. Logical and physical model identity stay distinct. */
+export interface RecoveryCandidate {
+	readonly providerId: string;
+	readonly family: ManagedFamily;
+	readonly providerType: Exclude<ProviderType, "openrouter">;
+	readonly modelId: string;
+	readonly selectedModelId: string;
+	readonly tier: RecoveryCandidateTier;
+	readonly substitution: "exact" | "configured";
+	readonly capability: RecoveryModelCapability;
+}
+
+export type RecoveryPlanConfig = Pick<
+	MultiAccountConfig,
+	| "sameFamilyFailover"
+	| "crossFamilyChainEnabled"
+	| "crossFamilyChains"
+	| "preferredModels"
+	| "tierModelMap"
+>;
+
+export interface RecoveryCandidatePlanRequest {
+	readonly selectedModelId: string;
+	readonly originFamily: AllowedFamily;
+	readonly accounts: readonly RecoveryPlanAccount[];
+	readonly config: RecoveryPlanConfig;
+	readonly requiredInput: readonly RecoveryInputModality[];
+	readonly requiresTools: boolean;
+	readonly failedPair?: Readonly<{ providerId: string; modelId: string }>;
+}
+
+function providerTypeMatchesFamily(account: RecoveryPlanAccount): boolean {
+	if (account.family === "openai-codex") return account.providerType === "subscription";
+	if (account.family === "openai") return account.providerType === "owning-vendor-api";
+	return account.providerType === "subscription" || account.providerType === "owning-vendor-api";
+}
+
+function usableCapability(
+	model: RecoveryModelCapability,
+	requiredInput: readonly RecoveryInputModality[],
+	requiresTools: boolean,
+): boolean {
+	return (
+		typeof model.modelId === "string" &&
+		model.modelId.length > 0 &&
+		Number.isFinite(model.contextWindow) &&
+		model.contextWindow > 0 &&
+		requiredInput.every((input) => model.input.includes(input)) &&
+		(!requiresTools || model.supportsTools)
+	);
+}
+
+function immutableCapability(model: RecoveryModelCapability): RecoveryModelCapability {
+	return Object.freeze({
+		modelId: model.modelId,
+		input: Object.freeze([...model.input]),
+		supportsTools: model.supportsTools,
+		contextWindow: model.contextWindow,
+	});
+}
+
+/** Build the immutable, deterministic candidate sweep for one logical call. */
+export function buildRecoveryCandidatePlan(
+	request: RecoveryCandidatePlanRequest,
+): readonly RecoveryCandidate[] {
+	if (typeof request.selectedModelId !== "string" || request.selectedModelId.length === 0) {
+		return Object.freeze([]);
+	}
+
+	const accounts: RecoveryPlanAccount[] = [];
+	const seenAccounts = new Set<string>();
+	for (const account of request.accounts) {
+		if (
+			!account.eligible ||
+			!isCanonicalManagedProviderId(account.providerId, account.family) ||
+			!providerTypeMatchesFamily(account) ||
+			seenAccounts.has(account.providerId)
+		) {
+			continue;
+		}
+		seenAccounts.add(account.providerId);
+		accounts.push(account);
+	}
+
+	const candidates: RecoveryCandidate[] = [];
+	const seenPairs = new Set<string>();
+	const add = (
+		account: RecoveryPlanAccount,
+		model: RecoveryModelCapability | undefined,
+		tier: RecoveryCandidateTier,
+		substitution: RecoveryCandidate["substitution"],
+	): void => {
+		if (
+			model === undefined ||
+			!usableCapability(model, request.requiredInput, request.requiresTools)
+		) {
+			return;
+		}
+		if (
+			request.failedPair?.providerId === account.providerId &&
+			request.failedPair.modelId === model.modelId
+		) {
+			return;
+		}
+		const key = `${account.providerId}\u0000${model.modelId}`;
+		if (seenPairs.has(key)) return;
+		seenPairs.add(key);
+		candidates.push(
+			Object.freeze({
+				providerId: account.providerId,
+				family: account.family,
+				providerType: account.providerType,
+				modelId: model.modelId,
+				selectedModelId: request.selectedModelId,
+				tier,
+				substitution,
+				capability: immutableCapability(model),
+			}),
+		);
+	};
+
+	if (request.config.sameFamilyFailover) {
+		const sameFamilySubscriptions = accounts.filter(
+			(account) =>
+				account.providerType === "subscription" &&
+				account.family === request.originFamily,
+		);
+		for (const account of sameFamilySubscriptions) {
+			add(
+				account,
+				account.models.find(({ modelId }) => modelId === request.selectedModelId),
+				"same-family-subscription",
+				"exact",
+			);
+		}
+	}
+
+	// Google has no supported owning-vendor-API destination. Exclude it before
+	// this tier is built at all, so a malformed or hostile account shape can
+	// neither expand via an exact model match nor reach resolveTierModel below.
+	const owningVendorApiAccounts = accounts.filter(
+		(account) =>
+			account.providerType === "owning-vendor-api" &&
+			account.family !== "google-antigravity" &&
+			sameVendor(account.family, request.originFamily),
+	);
+	for (const account of owningVendorApiAccounts) {
+		add(
+			account,
+			account.models.find(({ modelId }) => modelId === request.selectedModelId),
+			"owning-vendor-api",
+			"exact",
+		);
+	}
+	for (const account of owningVendorApiAccounts) {
+		// Google has no supported metered destination; the filter above already
+		// excludes it, and this narrows the type for resolveTierModel below.
+		if (account.family === "google-antigravity") continue;
+		const resolvedModelId = resolveTierModel(
+			request.selectedModelId,
+			vendorForFamily(account.family),
+			account.models.map(({ modelId }) => modelId),
+			request.config.tierModelMap,
+		);
+		if (resolvedModelId === request.selectedModelId) continue;
+		add(
+			account,
+			account.models.find(({ modelId }) => modelId === resolvedModelId),
+			"owning-vendor-api",
+			"configured",
+		);
+	}
+
+	if (request.config.crossFamilyChainEnabled) {
+		const destinationFamilies = request.config.crossFamilyChains
+			.filter(({ from, to }) => from === request.originFamily && to !== from)
+			.map(({ to }) => to);
+		for (const destinationFamily of destinationFamilies) {
+			if (!isAllowedFamily(destinationFamily)) continue;
+			const destinations = accounts.filter(
+				(account) =>
+					account.providerType === "subscription" &&
+					account.family === destinationFamily,
+			);
+			for (const account of destinations) {
+				add(
+					account,
+					account.models.find(({ modelId }) => modelId === request.selectedModelId),
+					"cross-family-subscription",
+					"exact",
+				);
+			}
+			for (const modelId of request.config.preferredModels[destinationFamily] ?? []) {
+				for (const account of destinations) {
+					add(
+						account,
+						account.models.find((model) => model.modelId === modelId),
+						"cross-family-subscription",
+						"configured",
+					);
+				}
+			}
+		}
+	}
+
+	return Object.freeze(candidates);
+}

package/src/report-range.ts

@@ -0,0 +1,203 @@
+/**
+ * Pure custom-range parsing and granularity-satisfiability checks for the
+ * subscription-value report projection.
+ *
+ * Every export here is read-only and side-effect free: no file I/O, no clock
+ * reads (`nowMs` and retained-granularity facts are always caller-supplied),
+ * and no `process.exit`. The eventual standalone CLI maps
+ * {@link ReportRangeResult.exitCode} onto its own process exit; this module
+ * only ever returns that code as data.
+ *
+ * A custom bound is either an ISO date `YYYY-MM-DD` (resolved to local
+ * midnight in the supplied report timezone) or a full RFC 3339 timestamp with
+ * an explicit `Z` or numeric offset. An offsetless date-time, a bare
+ * year-month, or any other shape is rejected as invalid syntax. The
+ * resolved range is start-inclusive and end-exclusive.
+ */
+
+import { getPeriodBounds, resolveZonedInstant, type PeriodType } from "./period-boundaries.js";
+
+const DATE_ONLY_PATTERN = /^\d{4}-\d{2}-\d{2}$/u;
+const OFFSET_DATETIME_PATTERN =
+	/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/u;
+const OFFSETLESS_DATETIME_PATTERN =
+	/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?$/u;
+
+type BoundParseResult =
+	| { readonly ok: true; readonly ms: number }
+	| { readonly ok: false; readonly reason: string };
+
+function parseBound(raw: string, timeZone: string): BoundParseResult {
+	if (raw.length === 0) {
+		return { ok: false, reason: "a custom range bound must not be empty." };
+	}
+	if (DATE_ONLY_PATTERN.test(raw)) {
+		const [yearRaw, monthRaw, dayRaw] = raw.split("-");
+		const year = Number(yearRaw);
+		const month = Number(monthRaw);
+		const day = Number(dayRaw);
+		if (month < 1 || month > 12 || day < 1 || day > 31) {
+			return { ok: false, reason: `"${raw}" is not a valid ISO date.` };
+		}
+		try {
+			return {
+				ok: true,
+				ms: resolveZonedInstant({ year, month: month - 1, day }, timeZone),
+			};
+		} catch (error) {
+			return { ok: false, reason: (error as Error).message };
+		}
+	}
+	if (OFFSET_DATETIME_PATTERN.test(raw)) {
+		const ms = Date.parse(raw);
+		if (!Number.isFinite(ms)) {
+			return { ok: false, reason: `"${raw}" is not a valid RFC 3339 timestamp.` };
+		}
+		return { ok: true, ms };
+	}
+	if (OFFSETLESS_DATETIME_PATTERN.test(raw)) {
+		return {
+			ok: false,
+			reason: `"${raw}" is an offsetless date-time; supply "Z" or a numeric UTC offset.`,
+		};
+	}
+	return {
+		ok: false,
+		reason: `"${raw}" is not a supported ISO date (YYYY-MM-DD) or RFC 3339 timestamp.`,
+	};
+}
+
+/**
+ * The finest granularity actually retained over one sub-interval of history.
+ * `"raw"` means per-observation precision (any instant is a valid boundary);
+ * every other value is a {@link PeriodType} whose own period boundaries are
+ * the finest safely-sliceable instants in that sub-interval.
+ */
+export type RetainedGranularity = "raw" | PeriodType;
+
+export interface GranularitySegment {
+	readonly startMs: number;
+	readonly endMs: number;
+	readonly granularity: RetainedGranularity;
+}
+
+export type RangeSatisfiability =
+	| { readonly status: "satisfiable" }
+	| { readonly status: "unsatisfiable"; readonly reason: string };
+
+function alignsToGranularity(instantMs: number, granularity: RetainedGranularity): boolean {
+	if (granularity === "raw") return true;
+	return getPeriodBounds(instantMs, granularity).startMs === instantMs;
+}
+
+/**
+ * Checks whether `range` can be reported without slicing a coarser retained
+ * rollup to fabricate detail it never recorded. `segments` describes the
+ * caller's own retained-state facts: which sub-intervals of history are only
+ * available at which granularity. A range whose start or end instant falls
+ * inside a segment but does not land on that segment's own granularity
+ * boundary, or that reaches outside every supplied segment, is unsatisfiable.
+ * An empty range (`endMs <= startMs`) is trivially satisfiable.
+ */
+export function assertRangeSatisfiable(
+	range: { readonly startMs: number; readonly endMs: number },
+	segments: readonly GranularitySegment[],
+): RangeSatisfiability {
+	if (range.endMs <= range.startMs) return { status: "satisfiable" };
+	const startSegment = segments.find(
+		(segment) => range.startMs >= segment.startMs && range.startMs < segment.endMs,
+	);
+	if (startSegment === undefined) {
+		return {
+			status: "unsatisfiable",
+			reason: "the range start falls outside every retained interval.",
+		};
+	}
+	if (!alignsToGranularity(range.startMs, startSegment.granularity)) {
+		return {
+			status: "unsatisfiable",
+			reason: `the range start is not aligned to the retained "${startSegment.granularity}" granularity.`,
+		};
+	}
+	const endSegment = segments.find(
+		(segment) => range.endMs > segment.startMs && range.endMs <= segment.endMs,
+	);
+	if (endSegment === undefined) {
+		return {
+			status: "unsatisfiable",
+			reason: "the range end falls outside every retained interval.",
+		};
+	}
+	if (!alignsToGranularity(range.endMs, endSegment.granularity)) {
+		return {
+			status: "unsatisfiable",
+			reason: `the range end is not aligned to the retained "${endSegment.granularity}" granularity.`,
+		};
+	}
+	return { status: "satisfiable" };
+}
+
+export interface ReportRangeInvalid {
+	readonly status: "invalid";
+	readonly exitCode: 2;
+	readonly reason: string;
+}
+
+export interface ReportRangeUnsatisfiable {
+	readonly status: "unsatisfiable";
+	readonly exitCode: 3;
+	readonly reason: string;
+}
+
+export interface ReportRangeResolved {
+	readonly status: "resolved";
+	readonly exitCode: 0;
+	readonly startMs: number;
+	readonly endMs: number;
+}
+
+/**
+ * A discriminated projection result, never a process exit. The standalone
+ * CLI node maps {@link ReportRangeResult.exitCode} onto its own process exit
+ * (2 for invalid syntax, 3 for unsatisfiable precision, 0 for a resolved,
+ * reportable range -- which may still describe a truthful empty window).
+ */
+export type ReportRangeResult =
+	| ReportRangeInvalid
+	| ReportRangeUnsatisfiable
+	| ReportRangeResolved;
+
+/**
+ * Resolves one custom `--from`/`--to` request. `retainedGranularity`, when
+ * supplied, is checked with {@link assertRangeSatisfiable}; omitting it skips
+ * the satisfiability check (useful when a caller only wants syntax
+ * validation). The range is start-inclusive and end-exclusive; `from` equal
+ * to `to` resolves to a valid, explicitly empty range rather than an error.
+ */
+export function resolveCustomRange(input: {
+	readonly fromRaw: string;
+	readonly toRaw: string;
+	readonly timeZone?: string;
+	readonly retainedGranularity?: readonly GranularitySegment[];
+}): ReportRangeResult {
+	const timeZone = input.timeZone ?? "UTC";
+	const from = parseBound(input.fromRaw, timeZone);
+	if (!from.ok) return { status: "invalid", exitCode: 2, reason: from.reason };
+	const to = parseBound(input.toRaw, timeZone);
+	if (!to.ok) return { status: "invalid", exitCode: 2, reason: to.reason };
+	if (to.ms < from.ms) {
+		return {
+			status: "invalid",
+			exitCode: 2,
+			reason: "the range end must not precede its start.",
+		};
+	}
+	const range = { startMs: from.ms, endMs: to.ms };
+	if (input.retainedGranularity !== undefined) {
+		const satisfiability = assertRangeSatisfiable(range, input.retainedGranularity);
+		if (satisfiability.status === "unsatisfiable") {
+			return { status: "unsatisfiable", exitCode: 3, reason: satisfiability.reason };
+		}
+	}
+	return { status: "resolved", exitCode: 0, startMs: range.startMs, endMs: range.endMs };
+}