@centerforagenticai/pi-multi-account 0.1.1

package/src/openai-adapter.ts

@@ -0,0 +1,117 @@
+/**
+ * OpenAI platform-API alias registration (REQ-NATIVE-API-ALIAS-AUTH).
+ *
+ * The distinct `openai` platform family is reached by the vendor's own
+ * pay-per-token API using a stored `api_key` credential, not an OAuth
+ * subscription. Unlike the Codex alias, this needs no stream reattribution and
+ * no OAuth capture: the OpenAI platform provider is a plain API-key provider on
+ * Pi's built-in `openai-responses` handler, so an alias only has to declare
+ * real API-key auth and the `OPENAI_MODELS` catalog re-pointed at its own
+ * provider id. Pi resolves the alias slot's stored `api_key` at dispatch; this
+ * module never reads the key value.
+ *
+ * Catalog source is capture-or-compose: the live model registry's base `openai`
+ * provider catalog when the host has registered it (the pinned Pi 0.84.4 ships
+ * it), else the pinned `@earendil-works/pi-ai` `openaiProvider()` factory. Base
+ * providers are only read, never mutated or re-registered.
+ */
+
+import type {
+	ProviderConfig,
+	ProviderModelConfig,
+} from "@earendil-works/pi-coding-agent";
+import { openaiProvider } from "@earendil-works/pi-ai/providers/openai";
+import { cloneProviderModelCatalog } from "./catalog-rebinding.js";
+
+/** pi-ai model API id for the OpenAI platform Responses API. */
+export const OPENAI_ALIAS_API = "openai-responses" as const;
+/** The base OpenAI platform provider id shipped by pi-ai. */
+export const OPENAI_BASE_PROVIDER = "openai" as const;
+/** Env var the OpenAI platform provider resolves its API key from. */
+const OPENAI_API_KEY_ENV = "OPENAI_API_KEY" as const;
+/** Base URL the pinned pi-ai `openaiProvider()` declares. */
+const OPENAI_BASE_URL = "https://api.openai.com/v1" as const;
+
+export class OpenAiAdapterContractError extends Error {
+	constructor(message: string) {
+		super(
+			`[openai platform contract] ${message} ` +
+				"Run npm run upstream:check and review UPSTREAM.md before release.",
+		);
+		this.name = "OpenAiAdapterContractError";
+	}
+}
+
+/**
+ * Model configs for the OpenAI platform catalog, deeply isolated from any
+ * registry-owned object. Prefers the live registry's base `openai` catalog;
+ * falls back to the pinned pi-ai `openaiProvider()` factory when the host has
+ * not registered a base `openai` provider. The registry-owned `provider`
+ * identity is stripped so the caller can re-point each model at the alias id.
+ */
+export function openaiPlatformModels(
+	registry: unknown,
+): readonly ProviderModelConfig[] {
+	const captured = tryCaptureRegistryModels(registry);
+	if (captured.length > 0) return captured;
+	return composeModelsFromFactory();
+}
+
+function tryCaptureRegistryModels(
+	registry: unknown,
+): readonly ProviderModelConfig[] {
+	try {
+		return cloneProviderModelCatalog(registry, OPENAI_BASE_PROVIDER);
+	} catch {
+		// The base openai provider is not registered in this session's registry;
+		// fall back to the pinned factory catalog rather than failing.
+		return [];
+	}
+}
+
+function composeModelsFromFactory(): readonly ProviderModelConfig[] {
+	const provider = openaiProvider();
+	const models = provider.getModels();
+	if (models.length === 0) {
+		throw new OpenAiAdapterContractError(
+			"The pinned pi-ai openai provider factory yielded no models.",
+		);
+	}
+	return models.map((model: unknown) => {
+		// Strip the registry-owned provider identity; keep every other field so
+		// the alias catalog stays a lossless superset of the base catalog.
+		const clone = structuredClone(model) as ProviderModelConfig & {
+			provider?: unknown;
+		};
+		delete clone.provider;
+		return clone as ProviderModelConfig;
+	});
+}
+
+/**
+ * Builds an OpenAI platform-API alias `ProviderConfig` for one numbered slot:
+ * real API-key auth (`$OPENAI_API_KEY`), the `openai-responses` API, and the
+ * platform catalog re-pointed at the alias. No OAuth, no custom stream — Pi's
+ * built-in `openai-responses` handler serves it once it resolves the slot's
+ * stored `api_key`.
+ */
+export function createOpenAiAliasProviderConfig(
+	sourceModels: readonly ProviderModelConfig[],
+	aliasDisplayLabel: string,
+): ProviderConfig {
+	if (sourceModels.length === 0) {
+		throw new OpenAiAdapterContractError(
+			"Cannot register an OpenAI platform alias with an empty model catalog.",
+		);
+	}
+	return {
+		api: OPENAI_ALIAS_API,
+		baseUrl: OPENAI_BASE_URL,
+		apiKey: `$${OPENAI_API_KEY_ENV}`,
+		models: sourceModels.map((model) => ({
+			...structuredClone(model),
+			api: OPENAI_ALIAS_API,
+			name: `${model.name} (${aliasDisplayLabel})`,
+		})),
+	};
+}

package/src/openrouter-budget.ts

@@ -0,0 +1,304 @@
+import { randomUUID } from "node:crypto";
+import {
+	chmodSync,
+	closeSync,
+	fsyncSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	renameSync,
+	statSync,
+	unlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { acquireMachineLease } from "./machine-lease.js";
+import { getPeriodBounds } from "./period-boundaries.js";
+import { isProjectKey } from "./project-identity.js";
+
+const SCHEMA_VERSION = 1;
+const MAX_STATE_BYTES = 64 * 1024;
+const MAX_PROJECTS = 512;
+const MAX_AMOUNT_USD = 1_000_000;
+const RETENTION_DAYS = 7;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const LEASE_TTL_MS = 5_000;
+const ROUNDING_SCALE = 1_000_000;
+
+interface BudgetEntry {
+	readonly dayStartMs: number;
+	readonly reservedUsd: number;
+}
+
+interface BudgetState {
+	readonly schemaVersion: 1;
+	readonly entries: Readonly<Record<string, BudgetEntry>>;
+}
+
+export type OpenRouterBudgetReservation =
+	| {
+			readonly status: "reserved";
+			readonly dayStartMs: number;
+			readonly reservedTodayUsd: number;
+			readonly remainingTodayUsd: number;
+	  }
+	| {
+			readonly status: "exhausted";
+			readonly dayStartMs: number;
+			readonly reservedTodayUsd: number;
+			readonly remainingTodayUsd: number;
+	  }
+	| { readonly status: "unavailable" };
+
+function defaultPaths(): { readonly path: string; readonly lockPath: string } {
+	const agentDir =
+		process.env.PI_CODING_AGENT_DIR ??
+		join(process.env.HOME ?? ".", ".pi", "agent");
+	// Package storage identity stays decoupled from the logical provider ID.
+	const directory = join(agentDir, "pi-multi-account");
+	return {
+		path: join(directory, "openrouter-budget.json"),
+		lockPath: join(directory, "openrouter-budget.lock"),
+	};
+}
+
+function boundedAmount(value: unknown): value is number {
+	return (
+		typeof value === "number" &&
+		Number.isFinite(value) &&
+		value >= 0 &&
+		value <= MAX_AMOUNT_USD
+	);
+}
+
+function parseState(value: unknown): BudgetState | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) {
+		return undefined;
+	}
+	const candidate = value as Record<string, unknown>;
+	if (
+		candidate.schemaVersion !== SCHEMA_VERSION ||
+		typeof candidate.entries !== "object" ||
+		candidate.entries === null ||
+		Array.isArray(candidate.entries) ||
+		Object.keys(candidate).some(
+			(key) => key !== "schemaVersion" && key !== "entries",
+		)
+	) {
+		return undefined;
+	}
+	const rawEntries = candidate.entries as Record<string, unknown>;
+	if (Object.keys(rawEntries).length > MAX_PROJECTS) return undefined;
+	const entries: Record<string, BudgetEntry> = {};
+	for (const [projectKey, rawEntry] of Object.entries(rawEntries)) {
+		if (
+			!isProjectKey(projectKey) ||
+			typeof rawEntry !== "object" ||
+			rawEntry === null ||
+			Array.isArray(rawEntry)
+		) {
+			return undefined;
+		}
+		const entry = rawEntry as Record<string, unknown>;
+		if (
+			!Number.isSafeInteger(entry.dayStartMs) ||
+			(entry.dayStartMs as number) < 0 ||
+			!boundedAmount(entry.reservedUsd) ||
+			Object.keys(entry).some(
+				(key) => key !== "dayStartMs" && key !== "reservedUsd",
+			)
+		) {
+			return undefined;
+		}
+		entries[projectKey] = {
+			dayStartMs: entry.dayStartMs as number,
+			reservedUsd: entry.reservedUsd,
+		};
+	}
+	return { schemaVersion: SCHEMA_VERSION, entries };
+}
+
+function roundUpUsd(value: number): number {
+	return Math.ceil(value * ROUNDING_SCALE) / ROUNDING_SCALE;
+}
+
+/** Persistent per-project worst-case reservations for metered fallback turns. */
+export class OpenRouterBudgetStore {
+	readonly #path: string;
+	readonly #lockPath: string;
+	readonly #now: () => number;
+	readonly #beforeWrite: (() => void) | undefined;
+
+	constructor(options: {
+		readonly path?: string;
+		readonly lockPath?: string;
+		readonly now?: () => number;
+		/** Test seam for a peer attempting a reservation while this lease is held. */
+		readonly beforeWrite?: () => void;
+	} = {}) {
+		const defaults = defaultPaths();
+		this.#path = options.path ?? defaults.path;
+		this.#lockPath = options.lockPath ?? defaults.lockPath;
+		this.#now = options.now ?? Date.now;
+		this.#beforeWrite = options.beforeWrite;
+	}
+
+	path(): string {
+		return this.#path;
+	}
+
+	reservedToday(projectKey: string, nowMs = this.#now()): number | undefined {
+		if (!isProjectKey(projectKey)) return undefined;
+		try {
+			const state = this.#readState(true);
+			if (state === undefined) return undefined;
+			const entry = state.entries[projectKey];
+			return entry?.dayStartMs === getPeriodBounds(nowMs, "day").startMs
+				? entry.reservedUsd
+				: 0;
+		} catch {
+			return undefined;
+		}
+	}
+
+	reserve(options: {
+		readonly projectKey: string;
+		readonly reservationUsd: number;
+		readonly dailyLimitUsd: number;
+		readonly nowMs?: number;
+	}): OpenRouterBudgetReservation {
+		if (
+			!isProjectKey(options.projectKey) ||
+			!boundedAmount(options.reservationUsd) ||
+			options.reservationUsd <= 0 ||
+			!boundedAmount(options.dailyLimitUsd) ||
+			options.dailyLimitUsd <= 0
+		) {
+			return { status: "unavailable" };
+		}
+		const reservationUsd = roundUpUsd(options.reservationUsd);
+		const dailyLimitUsd = roundUpUsd(options.dailyLimitUsd);
+		const nowMs = options.nowMs ?? this.#now();
+		let dayStartMs: number;
+		try {
+			dayStartMs = getPeriodBounds(nowMs, "day").startMs;
+		} catch {
+			return { status: "unavailable" };
+		}
+
+		let lease: ReturnType<typeof acquireMachineLease>;
+		try {
+			lease = acquireMachineLease({
+				lockPath: this.#lockPath,
+				ttlMs: LEASE_TTL_MS,
+				now: this.#now,
+				// A wedged lock would otherwise fail every reservation closed and
+				// disable OpenRouter permanently.
+				reclaimMalformed: true,
+			});
+		} catch {
+			return { status: "unavailable" };
+		}
+		if (lease === undefined) return { status: "unavailable" };
+		try {
+			if (!lease.renew()) return { status: "unavailable" };
+			const existing = this.#readState(true);
+			if (existing === undefined) return { status: "unavailable" };
+			const current = existing.entries[options.projectKey];
+			const reservedTodayUsd =
+				current?.dayStartMs === dayStartMs ? current.reservedUsd : 0;
+			const remainingTodayUsd = Math.max(
+				0,
+				dailyLimitUsd - reservedTodayUsd,
+			);
+			if (reservedTodayUsd + reservationUsd > dailyLimitUsd) {
+				return {
+					status: "exhausted",
+					dayStartMs,
+					reservedTodayUsd,
+					remainingTodayUsd,
+				};
+			}
+
+			const retainedEntries = Object.fromEntries(
+				Object.entries(existing.entries).filter(
+					([, entry]) => entry.dayStartMs >= dayStartMs - RETENTION_DAYS * DAY_MS,
+				),
+			);
+			retainedEntries[options.projectKey] = {
+				dayStartMs,
+				reservedUsd: roundUpUsd(reservedTodayUsd + reservationUsd),
+			};
+			if (Object.keys(retainedEntries).length > MAX_PROJECTS) {
+				return { status: "unavailable" };
+			}
+			this.#beforeWrite?.();
+			if (!lease.renew()) return { status: "unavailable" };
+			if (!this.#writeState({ schemaVersion: SCHEMA_VERSION, entries: retainedEntries })) {
+				return { status: "unavailable" };
+			}
+			const nextReserved = retainedEntries[options.projectKey]?.reservedUsd;
+			if (nextReserved === undefined) return { status: "unavailable" };
+			return {
+				status: "reserved",
+				dayStartMs,
+				reservedTodayUsd: nextReserved,
+				remainingTodayUsd: Math.max(0, dailyLimitUsd - nextReserved),
+			};
+		} catch {
+			return { status: "unavailable" };
+		} finally {
+			lease.release();
+		}
+	}
+
+	#readState(missingIsEmpty: boolean): BudgetState | undefined {
+		try {
+			const stats = statSync(this.#path);
+			if (!stats.isFile() || stats.size > MAX_STATE_BYTES) return undefined;
+			return parseState(JSON.parse(readFileSync(this.#path, "utf8")));
+		} catch (error) {
+			if (
+				missingIsEmpty &&
+				(error as NodeJS.ErrnoException).code === "ENOENT"
+			) {
+				return { schemaVersion: SCHEMA_VERSION, entries: {} };
+			}
+			return undefined;
+		}
+	}
+
+	#writeState(state: BudgetState): boolean {
+		const encoded = `${JSON.stringify(state)}\n`;
+		if (Buffer.byteLength(encoded, "utf8") > MAX_STATE_BYTES) return false;
+		const directory = dirname(this.#path);
+		mkdirSync(directory, { recursive: true, mode: 0o700 });
+		chmodSync(directory, 0o700);
+		const temporaryPath = `${this.#path}.${process.pid}.${randomUUID()}.tmp`;
+		let descriptor: number | undefined;
+		try {
+			descriptor = openSync(temporaryPath, "wx", 0o600);
+			writeFileSync(descriptor, encoded, { encoding: "utf8" });
+			fsyncSync(descriptor);
+			closeSync(descriptor);
+			descriptor = undefined;
+			renameSync(temporaryPath, this.#path);
+			chmodSync(this.#path, 0o600);
+			return true;
+		} catch {
+			if (descriptor !== undefined) {
+				try {
+					closeSync(descriptor);
+				} catch {
+					// Continue with temporary-file cleanup.
+				}
+			}
+			try {
+				unlinkSync(temporaryPath);
+			} catch {
+				// A failed reservation must not escape into routing.
+			}
+			return false;
+		}
+	}
+}

package/src/openrouter-fallback.ts

@@ -0,0 +1,146 @@
+import type { Api, Model, ModelCostRates } from "@earendil-works/pi-ai";
+
+export const OPENROUTER_PROVIDER_ID = "openrouter";
+export const OPENROUTER_ENABLE_ENV = "PI_MULTI_ACCOUNT_OPENROUTER_ENABLED";
+export const OPENROUTER_ENABLE_VALUE = "conversation-egress";
+export const OPENROUTER_MODEL_ENV = "PI_MULTI_ACCOUNT_OPENROUTER_MODEL";
+export const OPENROUTER_DAILY_LIMIT_ENV =
+	"PI_MULTI_ACCOUNT_OPENROUTER_DAILY_USD_LIMIT";
+
+const MAX_MODEL_ID_LENGTH = 200;
+const MAX_DAILY_LIMIT_USD = 1_000;
+const MODEL_ID_PATTERN = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._:/-]+$/;
+const USD_PATTERN = /^(?:0|[1-9]\d*)(?:\.\d{1,4})?$/;
+
+export type OpenRouterPolicyReason =
+	| "enabled"
+	| "not-enabled"
+	| "delegate-session"
+	| "model-unconfigured"
+	| "budget-unconfigured"
+	| "session-disabled";
+
+export type OpenRouterEnvironmentPolicy =
+	| {
+			readonly enabled: true;
+			readonly reason: "enabled";
+			readonly modelId: string;
+			readonly dailyLimitUsd: number;
+			readonly conversationEgressConsented: true;
+			readonly delegatesAllowed: false;
+	  }
+	| {
+			readonly enabled: false;
+			readonly reason: Exclude<OpenRouterPolicyReason, "enabled">;
+			readonly conversationEgressConsented: boolean;
+			readonly delegatesAllowed: false;
+	  };
+
+export function isDelegateEnvironment(
+	environment: Readonly<Record<string, string | undefined>>,
+): boolean {
+	return Object.keys(environment).some((key) => {
+		if (!key.startsWith("PI_DELEGATE_LINEAGE_")) return false;
+		const value = environment[key];
+		return typeof value === "string" && value.length > 0;
+	});
+}
+
+/**
+ * Resolve the explicit per-project OpenRouter policy without reading the API key.
+ * Partial, malformed, absent, and delegate-process configurations all disable the
+ * metered rung without turning an optional capability into a startup failure.
+ */
+export function resolveOpenRouterEnvironmentPolicy(options: {
+	readonly environment?: Readonly<Record<string, string | undefined>>;
+	readonly sessionDisabled?: boolean;
+} = {}): OpenRouterEnvironmentPolicy {
+	const environment = options.environment ?? process.env;
+	const consented =
+		environment[OPENROUTER_ENABLE_ENV] === OPENROUTER_ENABLE_VALUE;
+	const disabled = (
+		reason: Exclude<OpenRouterPolicyReason, "enabled">,
+	): OpenRouterEnvironmentPolicy => ({
+		enabled: false,
+		reason,
+		conversationEgressConsented: consented,
+		delegatesAllowed: false,
+	});
+	if (options.sessionDisabled) return disabled("session-disabled");
+	if (isDelegateEnvironment(environment)) return disabled("delegate-session");
+	if (!consented) return disabled("not-enabled");
+
+	const modelId = environment[OPENROUTER_MODEL_ENV]?.trim();
+	if (
+		modelId === undefined ||
+		modelId.length === 0 ||
+		modelId.length > MAX_MODEL_ID_LENGTH ||
+		!MODEL_ID_PATTERN.test(modelId)
+	) {
+		return disabled("model-unconfigured");
+	}
+	const rawLimit = environment[OPENROUTER_DAILY_LIMIT_ENV]?.trim();
+	if (rawLimit === undefined || !USD_PATTERN.test(rawLimit)) {
+		return disabled("budget-unconfigured");
+	}
+	const dailyLimitUsd = Number(rawLimit);
+	if (
+		!Number.isFinite(dailyLimitUsd) ||
+		dailyLimitUsd <= 0 ||
+		dailyLimitUsd > MAX_DAILY_LIMIT_USD
+	) {
+		return disabled("budget-unconfigured");
+	}
+	return {
+		enabled: true,
+		reason: "enabled",
+		modelId,
+		dailyLimitUsd,
+		conversationEgressConsented: true,
+		delegatesAllowed: false,
+	};
+}
+
+function validRates(value: ModelCostRates): boolean {
+	return [value.input, value.output, value.cacheRead, value.cacheWrite].every(
+		(rate) => Number.isFinite(rate) && rate >= 0,
+	);
+}
+
+/**
+ * Conservative maximum charge for one request using Pi's live model catalogue.
+ * Context and output maxima are both charged, intentionally double-counting the
+ * output share of a context window. The largest base/tier/cache rate wins.
+ */
+export function worstCaseOpenRouterTurnUsd(
+	model: Model<Api>,
+): number | undefined {
+	if (
+		model.provider !== OPENROUTER_PROVIDER_ID ||
+		!Number.isSafeInteger(model.contextWindow) ||
+		model.contextWindow <= 0 ||
+		!Number.isSafeInteger(model.maxTokens) ||
+		model.maxTokens <= 0 ||
+		!validRates(model.cost)
+	) {
+		return undefined;
+	}
+	const rates: readonly ModelCostRates[] = [
+		model.cost,
+		...(model.cost.tiers ?? []),
+	];
+	if (!rates.every(validRates)) return undefined;
+	const inputRate = Math.max(
+		...rates.flatMap((rate) => [
+			rate.input,
+			rate.input * 2,
+			rate.cacheRead,
+			rate.cacheWrite,
+		]),
+	);
+	const outputRate = Math.max(...rates.map((rate) => rate.output));
+	const total =
+		(model.contextWindow * inputRate + model.maxTokens * outputRate) /
+		1_000_000;
+	return Number.isFinite(total) && total > 0 ? total : undefined;
+}